diff --git a/commands/gsd/plan-phase.md b/commands/gsd/plan-phase.md index b5becc977..80ad19976 100644 --- a/commands/gsd/plan-phase.md +++ b/commands/gsd/plan-phase.md @@ -15,16 +15,17 @@ allowed-tools: --- -Create executable phase prompts (PLAN.md files) for a roadmap phase. +Create executable phase prompts (PLAN.md files) for a roadmap phase with optional verification loop. -**Orchestrator role:** Parse arguments, validate phase, gather context paths, spawn gsd-planner agent, present results. +**Orchestrator role:** Parse arguments, validate phase, gather context paths, spawn gsd-planner agent, verify plans with gsd-plan-checker, iterate until plans pass or max iterations reached, present results. -**Why subagent:** Planning burns context fast (reading codebase, building dependency graphs, breaking down tasks). Fresh 200k context for planning. Main context stays lean for user interaction. +**Why subagent:** Planning burns context fast. Verification uses fresh context. User sees the ping-pong between planner and checker in main context. Phase number: $ARGUMENTS (optional - auto-detects next unplanned phase if not provided) Gap closure mode: `--gaps` flag triggers gap closure workflow +Skip verification: `--skip-verify` flag bypasses planner → checker loop Check for existing plans: @@ -50,6 +51,7 @@ Extract from $ARGUMENTS: - Phase number (integer or decimal like `2.1`) - `--gaps` flag for gap closure mode +- `--skip-verify` flag to bypass verification loop **If no phase number:** Detect next unplanned phase from roadmap. @@ -89,6 +91,8 @@ UAT="${PHASE_DIR}/${PHASE}-UAT.md" ## 6. Spawn gsd-planner Agent +Display: `Phase {X}: {Name} — launching planner...` + Fill prompt and spawn: ```markdown @@ -126,7 +130,7 @@ Plans must be executable prompts with: - Tasks in XML format - Verification criteria - must_haves for goal-backward verification - + Before returning PLANNING COMPLETE: @@ -137,7 +141,7 @@ Before returning PLANNING COMPLETE: - [ ] Dependencies correctly identified - [ ] Waves assigned for parallel execution - [ ] must_haves derived from phase goal - + ``` ``` @@ -148,40 +152,149 @@ Task( ) ``` -## 7. Handle Agent Return +## 7. Handle Planner Return -**`## PLANNING COMPLETE`:** Display summary, offer: Execute phase, Review plans, Adjust, Done. +Parse planner output: -**`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation. +**`## PLANNING COMPLETE`:** +- Display: `Planner created {N} plan(s). Files on disk.` +- If `--skip-verify`: Skip to step 11 +- Otherwise: Proceed to step 8 -**`## PLANNING INCONCLUSIVE`:** Show what was attempted, offer: Add context, Retry, Manual. +**`## CHECKPOINT REACHED`:** +- Present to user, get response, spawn continuation (see step 10) -## 8. Spawn Continuation Agent +**`## PLANNING INCONCLUSIVE`:** +- Show what was attempted +- Offer: Add context, Retry, Manual +- Wait for user response + +## 8. Spawn gsd-plan-checker Agent + +Display: `Launching plan checker...` + +Fill checker prompt and spawn: ```markdown - -Continue planning for Phase {phase_number}: {phase_name} - + - -Phase directory: @.planning/phases/{phase_dir}/ -Existing plans: @.planning/phases/{phase_dir}/\*-PLAN.md - +**Phase:** {phase_number} +**Phase Goal:** {goal from ROADMAP} - -**Type:** {checkpoint_type} -**Response:** {user_response} - +**Plans to verify:** +@.planning/phases/{phase_dir}/*-PLAN.md + +**Requirements (if exists):** +@.planning/REQUIREMENTS.md + + + + +Return one of: +- ## VERIFICATION PASSED — all checks pass +- ## ISSUES FOUND — structured issue list + ``` ``` Task( - prompt=continuation_prompt, - subagent_type="gsd-planner", - description="Continue planning Phase {phase}" + prompt=checker_prompt, + subagent_type="gsd-plan-checker", + description="Verify Phase {phase} plans" ) ``` +## 9. Handle Checker Return + +**If `## VERIFICATION PASSED`:** +- Display: `Plans verified. Ready for execution.` +- Proceed to step 11 + +**If `## ISSUES FOUND`:** +- Display: `Checker found issues:` +- List issues from checker output +- Check iteration count +- Proceed to step 10 + +## 10. Revision Loop (Max 3 Iterations) + +Track: `iteration_count` (starts at 1 after initial plan + check) + +**If iteration_count < 3:** + +Display: `Sending back to planner for revision... (iteration {N}/3)` + +Spawn gsd-planner with revision prompt: + +```markdown + + +**Phase:** {phase_number} +**Mode:** revision + +**Existing plans:** +@.planning/phases/{phase_dir}/*-PLAN.md + +**Checker issues:** +{structured_issues_from_checker} + + + + +Read existing PLAN.md files. Make targeted updates to address checker issues. +Do NOT replan from scratch unless issues are fundamental. +Return what changed. + +``` + +``` +Task( + prompt=revision_prompt, + subagent_type="gsd-planner", + description="Revise Phase {phase} plans" +) +``` + +- After planner returns → spawn checker again (step 8) +- Increment iteration_count + +**If iteration_count >= 3:** + +Display: `Max iterations reached. {N} issues remain:` +- List remaining issues + +Offer options: +1. Force proceed (execute despite issues) +2. Provide guidance (user gives direction, retry) +3. Abandon (exit planning) + +Wait for user response. + +## 11. Present Final Status + +```markdown +Phase {X} planned: {N} plan(s) in {M} wave(s) + +## Wave Structure +Wave 1 (parallel): {plan-01}, {plan-02} +Wave 2: {plan-03} + +## Verification +{Passed | Passed with user override | Skipped (--skip-verify)} + +--- + +## Next Up + +**Phase {X}: [Phase Name]** - {N} plan(s) + +`/gsd:execute-phase {X}` + +`/clear` first - fresh context window + +--- +``` +