benjaminshoemaker/populate-state

Populate Phase State

Generate .claude/phase-state.json from the active greenfield execution plan and git history.

Use this command when:

• Starting to use the orchestrator on an existing project
• phase-state.json is missing or corrupted
• State has drifted from actual progress

Workflow

Copy this checklist and track progress:

Populate State Progress:
- [ ] Directory guard (verify main execution plan exists)
- [ ] Ensure .claude directory exists
- [ ] Parse the main execution plan (phases, tasks, criteria)
- [ ] Parse git history (commits, branches, timestamps)
- [ ] Detect features (features/*/EXECUTION_PLAN.md)
- [ ] Identify blockers (BLOCKED markers, stale tasks)
- [ ] Generate .claude/phase-state.json
- [ ] Determine task and phase statuses
- [ ] Output summary report

Directory Guard (Wrong Directory Check)

Before starting:

• If the current directory appears to be the toolkit repo (e.g., .toolkit-marker exists), STOP and tell the user to run /populate-state from their project directory instead.
• Resolve the main execution plan in this order:
  1. EXECUTION_PLAN.md in the current working directory
  2. plans/greenfield/EXECUTION_PLAN.md in the current working directory
• If neither exists, STOP and tell the user to cd into the directory containing the active EXECUTION_PLAN.md and re-run /populate-state.

Instructions

1. Ensure directory exists

   mkdir -p .claude
   

2. Parse the main execution plan to extract:

   • Total phases (count ## Phase N headers)
   • Tasks per phase (count #### Task X.Y.Z headers)
   • Completion status per task (count - [x] vs - [ ] in acceptance criteria)
   • A task is COMPLETE if ALL its acceptance criteria are [x]

3. Parse git history to extract:

   • Task completion timestamps (from commits matching task(X.Y.Z):)
   • Phase branches (from branches matching phase-N)
   • Last activity date per phase

4. Detect features by scanning for:

   • features/*/EXECUTION_PLAN.md files
   • Parse each feature's execution plan the same way

5. Identify blockers by scanning the main execution plan for:

   • Tasks with **Status:** BLOCKED marker
   • Tasks with incomplete criteria that have no recent git activity (7+ days)
   • Mark these as potentially blocked

6. Generate .claude/phase-state.json with this structure:

{
  "schema_version": "1.0",
  "project_name": "{from directory name}",
  "last_updated": "{ISO timestamp}",
  "generated_by": "populate-state",

  "main": {
    "current_phase": 2,
    "total_phases": 6,
    "status": "IN_PROGRESS",
    "phases": [
      {
        "number": 1,
        "name": "Foundation",
        "status": "COMPLETE",
        "tasks_total": 8,
        "tasks_complete": 8,
        "completed_at": "2026-01-10T14:22:00Z"
      },
      {
        "number": 2,
        "name": "Core Features",
        "status": "IN_PROGRESS",
        "tasks_total": 12,
        "tasks_complete": 5,
        "started_at": "2026-01-11T09:00:00Z",
        "tasks": {
          "2.1.A": {"status": "COMPLETE", "completed_at": "..."},
          "2.1.B": {"status": "COMPLETE", "completed_at": "..."},
          "2.2.A": {"status": "IN_PROGRESS", "failures": {"consecutive": 0, "verification_attempts": {}, "last_errors": []}},
          "2.2.B": {"status": "NOT_STARTED"},
          "2.3.A": {"status": "BLOCKED", "blocker": "Needs API key", "since": "...", "failures": {"consecutive": 1, "verification_attempts": {"V-003": 3}, "last_errors": ["timeout connecting to API"]}}
        }
      }
    ]
  },

  "features": {
    "improved_metrics": {
      "path": "features/improved_metrics",
      "current_phase": 2,
      "total_phases": 4,
      "status": "IN_PROGRESS",
      "phases": [...]
    }
  }
}

1. Determine task status using this logic:

   • COMPLETE: All acceptance criteria are [x] AND git commit exists for task
   • IN_PROGRESS: Some criteria are [x] OR git commit exists but not all criteria done
   • BLOCKED: Has **Status:** BLOCKED marker OR stale (7+ days, incomplete)
   • NOT_STARTED: No criteria are [x] AND no git commit for task

2. Determine phase status using this logic:

   • COMPLETE: All tasks are COMPLETE
   • IN_PROGRESS: At least one task is IN_PROGRESS or COMPLETE, but not all COMPLETE
   • BLOCKED: Current task is BLOCKED
   • NOT_STARTED: No tasks have any progress

3. Output summary after generation:

Phase State Generated: .claude/phase-state.json

Main Project: Phase 2 of 6 (IN_PROGRESS)
  - Phase 1: COMPLETE (8/8 tasks)
  - Phase 2: IN_PROGRESS (5/12 tasks, 1 blocked)

Features:
  - improved_metrics: Phase 2 of 4 (IN_PROGRESS)
  - github_oauth: Phase 3 of 4 (IN_PROGRESS)

Blockers Found: 2
  - Task 2.3.A: Needs API key (blocked 3 days)
  - Feature improved_metrics Task 2.1.C: Test failures (blocked 1 day)

Error Handling

| Situation | Action | |-----------|--------| | No main execution plan found in working directory | STOP and tell user to cd into the directory containing the active EXECUTION_PLAN.md | | Main execution plan has non-standard phase/task headers that cannot be parsed | Report which headers were unrecognized, generate state for parseable phases, and warn about skipped sections | | Git history is unavailable (not a git repo or shallow clone) | Skip git-based timestamp and commit detection; derive status solely from checkbox state in the main execution plan | | .claude/ directory cannot be created (permissions issue) | Report the permission error and suggest running with appropriate permissions or creating the directory manually | | Existing phase-state.json is malformed or from an incompatible schema version | Overwrite it with freshly generated state and warn user that the previous file was replaced |

Notes

• This command is read-only for the main execution plan - it only generates state
• If phase-state.json exists, it will be overwritten
• Run this after manually updating execution-plan checkboxes
• The orchestrator can trigger this command on projects missing phase-state.json