populate-state

name	populate-state
description	Generate `.claude/phase-state.json` from the main execution plan and git history. Use to recover phase state after context loss or when joining an existing project.
allowed-tools	Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion

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" 
      
      
         
         
         
         
         
         
         
              
              
                   
            
                        
        
      
    
  

   
     
       
       
       
       
       ...
    
  

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