# Workflow Status System

The universal entry point for BMM workflows - answers "what should I do now?" for any agent.

## Overview

The workflow status system provides:

- **Smart project initialization** - Detects existing work and infers project details
- **Simple status tracking** - Key-value pairs for instant parsing
- **Intelligent routing** - Suggests next actions based on current state
- **Modular workflow paths** - Each project type/level has its own clean definition

## Architecture

### Core Components

```
workflow-status/
├── workflow.yaml              # Main configuration
├── instructions.md            # Status checker (99 lines)
├── workflow-status-template.yaml # Clean YAML status template
├── project-levels.yaml        # Source of truth for scale definitions
└── paths/                     # Modular workflow definitions
    ├── greenfield-level-0.yaml through level-4.yaml
    ├── brownfield-level-0.yaml through level-4.yaml
    └── game-design.yaml
```

### Related Workflow

```
workflow-init/
├── workflow.yaml              # Initialization configuration
└── instructions.md            # Smart setup (182 lines)
```

## How It Works

### For New Projects

1. User runs `workflow-status`
2. System finds no status file
3. Directs to `workflow-init`
4. Init workflow:
   - Scans for existing work (PRDs, code, etc.)
   - Infers project details from what it finds
   - Asks minimal questions (name + description)
   - Confirms understanding in one step
   - Creates status file with workflow path

### For Existing Projects

1. User runs `workflow-status`
2. System reads status file
3. Shows current state and options:
   - Continue in-progress work
   - Next required step
   - Available optional workflows
4. User picks action

## Status File Format

Clean YAML format with all workflows listed up front:

```yaml
# generated: 2025-10-29
# project: MyProject
# project_type: software
# project_level: 2
# field_type: greenfield
# workflow_path: greenfield-level-2.yaml

workflow_status:
  # Phase 1: Analysis
  brainstorm-project: optional
  research: optional
  product-brief: recommended

  # Phase 2: Planning
  prd: docs/prd.md
  validate-prd: optional
  create-design: conditional

  # Phase 3: Solutioning
  create-architecture: required
  validate-architecture: optional
  solutioning-gate-check: required
```

**Status Values:**

- `required` / `optional` / `recommended` / `conditional` - Not yet started
- `{file-path}` - Completed (e.g., `docs/prd.md`)
- `skipped` - Optional workflow that was skipped

Any agent can instantly parse what they need:

- Read YAML to see all workflows and their status
- Check which workflows are completed vs pending
- Auto-detect existing work by scanning for output files

## Project Levels

Source of truth: `/src/modules/bmm/README.md` lines 77-85

- **Level 0**: Single atomic change (1 story)
- **Level 1**: Small feature (1-10 stories)
- **Level 2**: Medium project (5-15 stories)
- **Level 3**: Complex system (12-40 stories)
- **Level 4**: Enterprise scale (40+ stories)

## Workflow Paths

Each combination has its own file:

- `greenfield-level-X.yaml` - New projects at each level
- `brownfield-level-X.yaml` - Existing codebases at each level
- `game-design.yaml` - Game projects (all levels)

Benefits:

- Load only what's needed (60 lines vs 750+)
- Easy to maintain individual paths
- Clear separation of concerns

## Smart Detection

The init workflow intelligently detects:

**Project Type:**

- Finds GDD → game
- Otherwise → software

**Project Level:**

- Reads PRD epic/story counts
- Analyzes scope descriptions
- Makes educated guess

**Field Type:**

- Finds source code → brownfield
- Only planning docs → greenfield
- Checks git history age

**Documentation Status:**

- Finds index.md → was undocumented
- Good README → documented
- Missing docs → needs documentation

## Usage Examples

### Any Agent Checking Status

```
Agent: workflow-status
Result: "Current: Phase 2 - Planning, Next: prd (pm agent)"
```

### New Project Setup

```
Agent: workflow-status
System: "No status found. Run workflow-init"
Agent: workflow-init
System: "Tell me about your project"
User: "Building a dashboard with user management"
System: "Level 2 greenfield software project. Correct?"
User: "Yes"
System: "Status created! Next: pm agent, run prd"
```

### Smart Inference

```
System finds: prd-dashboard.md with 3 epics
System finds: package.json, src/ directory
System infers: Level 2 brownfield software
User confirms or corrects
```

## Philosophy

**Less Structure, More Intelligence**

Instead of complex if/else logic:

- Trust the LLM to analyze and infer
- Use natural language for corrections
- Keep menus simple and contextual
- Let intelligence emerge from the model

**Result:** A workflow system that feels like talking to a smart assistant, not filling out a form.

## Implementation Details

### workflow-init (6 Steps)

1. **Scan for existing work** - Check for docs, code, git history
2. **Confirm findings** - Show what was detected (if anything)
3. **Gather info** - Name, description, confirm type/level/field
4. **Load path file** - Select appropriate workflow definition
5. **Generate workflow** - Build from path file
6. **Create status file** - Save and show next step

### workflow-status (4 Steps)

1. **Check for status file** - Direct to init if missing
2. **Parse status** - Extract key-value pairs
3. **Display options** - Show current, required, optional
4. **Handle selection** - Execute user's choice

## Best Practices

1. **Let the AI guess** - It's usually right, user corrects if needed
2. **One conversation** - Get all info in Step 3 of init
3. **Simple parsing** - Key-value pairs, not complex structures
4. **Modular paths** - Each scenario in its own file
5. **Trust intelligence** - LLM understands context better than rules

## Integration

Other workflows read the status to coordinate:

- Any workflow can check CURRENT_PHASE
- Workflows can verify prerequisites are complete
- All agents can ask "what should I do?"

**Phase 4 (Implementation):**

- workflow-status only tracks sprint-planning completion
- After sprint-planning, all story/epic tracking happens in sprint-status.yaml
- Phase 4 workflows do NOT read/write workflow-status (except sprint-planning for prerequisite verification)

The workflow-status.yaml file is the single source of truth for Phases 1-3, and sprint-status.yaml takes over for Phase 4 implementation tracking.

## Benefits

✅ **Smart Detection** - Infers from existing work instead of asking everything
✅ **Minimal Questions** - Just name and description in most cases
✅ **Clean Status** - Simple key-value pairs for instant parsing
✅ **Modular Paths** - 60-line files instead of 750+ line monolith
✅ **Natural Language** - "Tell me about your project" not "Pick 1-12"
✅ **Intelligent Menus** - Shows only relevant options
✅ **Fast Parsing** - Grep instead of complex logic
✅ **Easy Maintenance** - Change one level without affecting others

## Future Enhancements

- Visual progress indicators
- Time tracking and estimates
- Multi-project support
- Team synchronization

---

**This workflow is the front door to BMad Method. Start here to know what to do next.**