diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 8f1d8efdd..2eb13a945 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -19,9 +19,11 @@ None - this is internal GSD development following existing command/workflow/temp - [ ] **Phase 3: Integration** - Wire brownfield support into existing GSD workflows - [x] **Phase 10: Parallel Phase Execution** - Separate single-plan vs multi-plan execution with intelligent parallelization - [x] **Phase 11: Parallel-Aware Planning** - Update plan-phase.md to create parallelizable plans when config enables it -- [ ] **Phase 12: Changelog & Update Awareness** - Add changelog generation and /gsd:whats-new for version discovery +- [x] **Phase 12: Changelog & Update Awareness** - Add changelog generation and /gsd:whats-new for version discovery - [x] **Phase 13: Dedicated Debug Agent** - Create gsd-debugger agent, refactor /gsd:debug to thin orchestrator - [x] **Phase 14: Dedicated Researcher Agent** - Create gsd-researcher agent for structured research with baked-in methodology +- [x] **Phase 15: Dedicated Planner Agent** - Create gsd-planner agent, refactor /gsd:plan-phase to thin orchestrator +- [ ] **Phase 16: Plan Verification Loop** - Add planner → checker → revise loop before execution - [x] **Phase 99: Test Parallel (THROWAWAY)** - Create 3 silly independent files to test parallel execution ## Phase Details @@ -203,7 +205,7 @@ This enables execute-phase to produce more Wave 1 plans (true independence) inst Plans: - [x] 12-01: CHANGELOG.md foundation - Create changelog file, update installer to copy it -- [ ] 12-02: Publish command update - Add changelog generation to gsd-publish-version.md +- [x] 12-02: Publish command update - Add changelog generation to gsd-publish-version.md - [x] 12-03: whats-new command - Create /gsd:whats-new with remote fetch and version comparison **Wave structure:** @@ -264,6 +266,49 @@ Currently `/gsd:research-phase` does ad-hoc web searches without structure. The Pattern: Same as gsd-executor/gsd-verifier/gsd-debugger. Agent has expertise, command provides research context and mode. +### Phase 15: Dedicated Planner Agent + +**Goal:** Create `gsd-planner` agent with planning expertise baked in, refactor `/gsd:plan-phase` to thin orchestrator +**Depends on:** Phase 14 +**Research:** Unlikely (applying same agent pattern to planning workflow) +**Plans:** 3 plans + +Plans: +- [x] 15-01: Create gsd-planner agent - Consolidate planning expertise (1,147 lines) +- [x] 15-02: Refactor /gsd:plan-phase - Thin orchestrator (189 lines), deprecate workflow +- [x] 15-03: Deprecate reference files - Replace with agent pointers + +**Wave structure:** +- Wave 1: 15-01 (foundation) +- Wave 2: 15-02, 15-03 (parallel - both depend only on 15-01) + +**Details:** +Created gsd-planner agent with complete planning methodology: discovery levels, task breakdown, dependency graphs, scope estimation, goal-backward analysis, checkpoints, TDD integration, and gap closure mode. Command reduced from ~3,580 loaded lines to 189-line thin orchestrator. + +### Phase 16: Plan Verification Loop + +**Goal:** Add plan verification between planning and execution — planner → checker → revise loop +**Depends on:** Phase 15 +**Research:** Unlikely (extending existing agent patterns) +**Plans:** 3 plans + +Plans: +- [ ] 16-01: Create gsd-plan-checker agent - Goal-backward plan verification (~400-600 lines) +- [ ] 16-02: Update plan-phase.md orchestrator - Planner → checker → revise loop +- [ ] 16-03: Update gsd-planner.md - Add revision mode for handling checker feedback + +**Wave structure:** +- Wave 1: 16-01 (foundation) +- Wave 2: 16-02, 16-03 (parallel - both depend only on 16-01) + +**Details:** +Plans are created and executed without validation. Add `gsd-plan-checker` agent that verifies plans will achieve phase goal before execution begins. Orchestrator spawns planner → checker → planner loop with user visibility. Files on disk as handoff mechanism. + +Components: +- Create `agents/gsd-plan-checker.md` (goal-backward plan verification) +- Update `commands/gsd/plan-phase.md` (orchestrate planner → checker loop) +- Update `agents/gsd-planner.md` (add revision mode) + ### Phase 99: Test Parallel (THROWAWAY) **Goal:** Create 3 independent silly files to test parallel execution - DELETE AFTER TESTING @@ -298,6 +343,9 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 | 9. Integrate Verify-Work | 1/1 | Complete | 2026-01-08 | | 10. Parallel Phase Execution | 4/4 | Complete | 2026-01-12 | | 11. Parallel-Aware Planning | 4/4 | Complete | 2026-01-12 | +| 12. Changelog & Update Awareness | 3/3 | Complete | 2026-01-16 | | 99. Test Parallel (THROWAWAY) | 3/3 | Complete | 2026-01-12 | | 13. Dedicated Debug Agent | 3/3 | Complete | 2026-01-15 | | 14. Dedicated Researcher Agent | 3/3 | Complete | 2026-01-15 | +| 15. Dedicated Planner Agent | 3/3 | Complete | 2026-01-16 | +| 16. Plan Verification Loop | 0/3 | Planned | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 4d370e566..3a11f40a1 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -19,19 +19,19 @@ ## Current Position -Phase: 15 of 15 (Dedicated Planner Agent) -Plan: 1 of 2 in current phase -Status: In progress -Last activity: 2026-01-16 - Completed 15-01-PLAN.md +Phase: 16 of 16 (Plan Verification Loop) +Plan: 0 of 3 in current phase +Status: Planned +Last activity: 2026-01-16 - Phase 16 planned (3 plans in 2 waves) -Progress: ██████████████████████████████ 34/35 plans (97%) +Progress: ██████████████████████████████ 36/36 plans (100%) ## Performance Metrics **Velocity:** -- Total plans completed: 34 -- Average duration: 3.5 min -- Total execution time: ~120 min +- Total plans completed: 36 +- Average duration: 3.4 min +- Total execution time: ~122 min **By Phase:** @@ -51,10 +51,10 @@ Progress: ███████████████████████ | 99 | 3 | 1 min | <1 min (parallel) | | 13 | 3 | 10 min | 3.3 min | | 14 | 3 | 11 min | 3.7 min | -| 15 | 1 | 5 min | 5 min | +| 15 | 3 | 7 min | 2.3 min | **Recent Trend:** -- Last 5 plans: 14-01 (4m), 14-02 (4m), 14-03 (3m), 15-01 (5m) +- Last 5 plans: 14-03 (3m), 15-01 (5m), 15-02 (3m), 15-03 (1m) - Trend: Consistent execution times *Updated after each plan completion* @@ -89,6 +89,9 @@ Progress: ███████████████████████ | 14 | Parallel agent spawning for /gsd:research-project | 4 agents (stack, features, architecture, pitfalls) maximize throughput | | 15 | 1,147 lines from ~3,580 source (68% reduction) | Complete planning methodology consolidated into single agent | | 15 | 14 sections covering full planning workflow | Includes discovery, task breakdown, dependency graph, goal-backward, checkpoints, TDD, gap closure | +| 15 | Deprecation notices point to specific agent sections | Planning references deprecated, content in gsd-planner | +| 15 | 189 lines thin orchestrator for /gsd:plan-phase | Under 200 target, uses agent: gsd-planner frontmatter | +| 15 | Context-only planner-subagent-prompt.md template | Follows debug/research template pattern | ### Deferred Issues @@ -112,16 +115,17 @@ None yet. - Phase 13 added: Dedicated debug agent (gsd-debugger with baked-in expertise, thin orchestrator pattern) - Phase 14 added: Dedicated researcher agent (gsd-researcher with research methodology, tool strategy, output formats) - Phase 15 added: Dedicated planner agent (gsd-planner with planning expertise, refactor plan-phase to thin orchestrator) +- Phase 16 added: Plan verification loop (gsd-plan-checker, planner → checker → revise orchestration) ## Project Alignment Last checked: 2026-01-16 -Status: IN PROGRESS -Assessment: Phase 15 Plan 01 complete, Plan 02 (thin orchestrator refactor) remaining. +Status: ON TRACK +Assessment: Phase 16 added. Plan verification loop — planner → checker → revise orchestration before execution. Drift notes: None ## Session Continuity Last session: 2026-01-16 -Stopped at: Completed 15-01-PLAN.md +Stopped at: Completed 15-03-PLAN.md Resume file: None diff --git a/.planning/phases/16-plan-verification-loop/16-01-PLAN.md b/.planning/phases/16-plan-verification-loop/16-01-PLAN.md new file mode 100644 index 000000000..37339d4e1 --- /dev/null +++ b/.planning/phases/16-plan-verification-loop/16-01-PLAN.md @@ -0,0 +1,216 @@ +--- +phase: 16-plan-verification-loop +plan: 01 +type: execute +wave: 1 +depends_on: [] +files_modified: [agents/gsd-plan-checker.md] +autonomous: true + +must_haves: + truths: + - "Plan checker can load PLAN.md files and parse frontmatter" + - "Plan checker can verify plans against phase goal from ROADMAP.md" + - "Plan checker returns structured issues or passed status" + - "Checker output is consumable by orchestrator and planner" + artifacts: + - path: "agents/gsd-plan-checker.md" + provides: "Plan verification expertise and structured issue reporting" + min_lines: 400 + key_links: + - from: "gsd-plan-checker" + to: "PLAN.md frontmatter" + via: "must_haves, depends_on, files_modified parsing" + - from: "gsd-plan-checker" + to: "ROADMAP.md" + via: "phase goal extraction" +--- + + +Create gsd-plan-checker agent with goal-backward plan verification expertise. + +Purpose: Enable plan validation before execution. The checker reads PLAN.md files, verifies they will achieve the phase goal, and returns structured issues or passed status. + +Output: agents/gsd-plan-checker.md (~400-600 lines) + + + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md + +Existing agents to follow pattern: +@agents/gsd-verifier.md +@agents/gsd-planner.md + +Phase brief with design decisions: +@.planning/phases/16-plan-verification-loop/16-BRIEF.md + + + + + + Task 1: Create gsd-plan-checker agent file + agents/gsd-plan-checker.md + +Create agents/gsd-plan-checker.md following gsd-verifier pattern (checker role, not doer). + +**Frontmatter:** +```yaml +--- +name: gsd-plan-checker +description: Verifies plans will achieve phase goal before execution. Goal-backward analysis of plan quality. Spawned by /gsd:plan-phase orchestrator. +tools: Read, Bash, Glob, Grep +color: green +--- +``` + +**Structure (~400-600 lines total):** + +1. `` (~30 lines) + - Plan quality verifier role + - Spawned by /gsd:plan-phase orchestrator + - Returns structured issues or passed status + - Critical mindset: Plans describe intent, verify they deliver + +2. `` (~40 lines) + - "Plan completeness ≠ Goal achievement" + - Goal-backward verification of PLANS not code + - Start from phase goal, verify plans address it + +3. `` (~150 lines) + Six dimensions from BRIEF: + - **Requirement coverage** — Every phase requirement has task(s) addressing it + - **Task completeness** — Every task has Files + Action + Verify + Done + - **Dependency correctness** — Nothing references future work, depends_on valid + - **Key links planned** — Not just artifacts, but wiring between them + - **Scope sanity** — Plans within context budget (~50%), 2-3 tasks each + - **Verification derivation** — must_haves trace back to phase goal + +4. `` (~150 lines) + Step-by-step process: + - Step 1: Load context (phase goal, requirements from ROADMAP) + - Step 2: Load all PLAN.md files in phase directory + - Step 3: Parse must_haves from plan frontmatter + - Step 4: Check requirement coverage + - Step 5: Validate task structure + - Step 6: Verify dependency graph + - Step 7: Check key links planned + - Step 8: Assess scope + - Step 9: Verify must_haves derivation + - Step 10: Determine overall status + +5. `` (~60 lines) + Output format for issues: + ```yaml + issues: + - plan: "16-01" + dimension: "task_completeness" + severity: "blocker" + description: "Task 2 missing element" + fix_hint: "Add verification command for build output" + ``` + +6. `` (~50 lines) + Return formats: + - `## VERIFICATION PASSED` — All checks pass + - `## ISSUES FOUND` — Structured list for planner + Include plan_ids, issue_count, dimensions_failed + +7. `` (~30 lines) + Checklist for checker completion + +**Anti-patterns to document:** +- Checking code existence (that's gsd-verifier's job) +- Running the application (this is static plan analysis) +- Accepting vague tasks ("implement auth") +- Missing dependency analysis + +**Key insight:** Checker verifies plans WILL achieve goal, verifier verifies code DID achieve goal. Different timing, similar methodology. + + + - File exists: `ls agents/gsd-plan-checker.md` + - Line count: `wc -l agents/gsd-plan-checker.md` (400-600 lines) + - Has all sections: `grep -E "^<(role|core_principle|verification_dimensions|verification_process|issue_structure|structured_returns|success_criteria)>" agents/gsd-plan-checker.md | wc -l` (7 sections) + + gsd-plan-checker.md created with complete plan verification expertise, follows gsd-verifier pattern, has all 7 required sections + + + + Task 2: Add example verification scenarios + agents/gsd-plan-checker.md + +Add `` section (~80 lines) after verification_process showing: + +**Example 1: Missing requirement coverage** +``` +Phase goal: "Users can authenticate" +Requirements: AUTH-01 (login), AUTH-02 (logout), AUTH-03 (session) + +Plans found: +- 01-01: Login form and API +- 01-02: Session management + +Issue: AUTH-02 (logout) has no covering task +``` + +**Example 2: Broken dependency chain** +``` +Plan 02 frontmatter: depends_on: ["01", "03"] +Plan 03 frontmatter: depends_on: ["02"] + +Issue: Circular dependency between 02 and 03 +``` + +**Example 3: Task missing verification** +```xml + + Create login endpoint + src/app/api/auth/login/route.ts + POST endpoint with bcrypt validation + + Login works + + +Issue: Task missing element - cannot confirm completion +``` + +**Example 4: Scope exceeded** +``` +Plan 01 has 5 tasks with 12 files modified +Estimated context: ~80% + +Issue: Plan exceeds 50% context target, split into 2-3 plans +``` + + grep -c "" agents/gsd-plan-checker.md (should be 1) + Examples section added with 4 verification scenarios covering common issues + + + + + +- [ ] agents/gsd-plan-checker.md exists +- [ ] File is 400-600 lines +- [ ] All 7 main sections present +- [ ] Examples section present with 4 scenarios +- [ ] Follows gsd-verifier frontmatter pattern +- [ ] Structured returns match BRIEF spec + + + +- gsd-plan-checker agent created +- Agent has complete plan verification methodology +- Six verification dimensions documented +- Examples cover common failure modes +- Output format consumable by orchestrator + + + +After completion, create `.planning/phases/16-plan-verification-loop/16-01-SUMMARY.md` + diff --git a/.planning/phases/16-plan-verification-loop/16-02-PLAN.md b/.planning/phases/16-plan-verification-loop/16-02-PLAN.md new file mode 100644 index 000000000..8ba833318 --- /dev/null +++ b/.planning/phases/16-plan-verification-loop/16-02-PLAN.md @@ -0,0 +1,325 @@ +--- +phase: 16-plan-verification-loop +plan: 02 +type: execute +wave: 2 +depends_on: ["16-01"] +files_modified: [commands/gsd/plan-phase.md] +autonomous: true + +must_haves: + truths: + - "Orchestrator spawns gsd-planner then gsd-plan-checker" + - "User sees status between agent spawns" + - "If issues found, planner is re-spawned with feedback" + - "Loop terminates after max 3 iterations or passed" + artifacts: + - path: "commands/gsd/plan-phase.md" + provides: "Orchestrator for planner → checker → revise loop" + min_lines: 200 + key_links: + - from: "plan-phase.md" + to: "gsd-planner" + via: "Task() spawn with planning_context" + - from: "plan-phase.md" + to: "gsd-plan-checker" + via: "Task() spawn with verification_context" + - from: "checker output" + to: "planner revision spawn" + via: "issues passed in prompt" +--- + + +Update /gsd:plan-phase orchestrator to spawn planner → checker → revise loop. + +Purpose: Plans are validated before execution, catching issues early. User sees the ping-pong between agents. + +Output: Updated commands/gsd/plan-phase.md with verification loop + + + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md + +Current orchestrator (to be updated): +@commands/gsd/plan-phase.md + +New agent (from 16-01): +@agents/gsd-plan-checker.md + +Phase brief with loop design: +@.planning/phases/16-plan-verification-loop/16-BRIEF.md + +Prior summary showing current orchestrator structure: +@.planning/phases/15-dedicated-planner-agent/15-02-SUMMARY.md + + + + + + Task 1: Update plan-phase.md frontmatter + commands/gsd/plan-phase.md + +Update frontmatter to remove `context: fork` (orchestrator stays in main context per BRIEF): + +```yaml +--- +name: gsd:plan-phase +description: Create detailed execution plan for a phase (PLAN.md) with verification loop +argument-hint: "[phase] [--gaps] [--skip-verify]" +agent: gsd-planner +allowed-tools: + - Read + - Write + - Bash + - Glob + - Grep + - Task + - WebFetch + - mcp__context7__* +--- +``` + +Changes: +- Remove `context: fork` — orchestrator stays in main context +- Add `--skip-verify` flag description to argument-hint +- Add `Task` to allowed-tools (needed for spawning checker) + + grep -E "^context:" commands/gsd/plan-phase.md (should return nothing) + Frontmatter updated, context: fork removed, Task tool added + + + + Task 2: Add verification loop to process + commands/gsd/plan-phase.md + +Rewrite `` section to include verification loop. Target ~250-300 lines total for orchestrator. + +**New process flow:** + +```markdown + + +## 1. Validate Environment +(existing — check .planning/ exists) + +## 2. Parse Arguments +Extract: +- Phase number (integer or decimal) +- `--gaps` flag for gap closure mode +- `--skip-verify` flag to bypass verification loop + +## 3. Validate Phase +(existing — check phase in ROADMAP) + +## 4. Check Existing Plans +(existing — offer replan/view options) + +## 5. Gather Context Paths +(existing — STATE, ROADMAP, REQUIREMENTS, phase context files) + +## 6. Spawn gsd-planner Agent + +Display: "Phase {X}: {Name} — launching planner..." + +``` +Task( + prompt=planner_prompt, + subagent_type="gsd-planner", + description="Plan Phase {phase}" +) +``` + +## 7. Handle Planner Return + +Parse planner output: +- `## PLANNING COMPLETE` — Plans created, proceed to verification +- `## CHECKPOINT REACHED` — Present to user, handle response +- `## PLANNING INCONCLUSIVE` — Show issues, offer options + +If PLANNING COMPLETE: + - Display: "Planner created {N} plan(s). Files on disk." + - If `--skip-verify`: Skip to step 11 + - Otherwise: Proceed to step 8 + +## 8. Spawn gsd-plan-checker Agent + +Display: "Launching plan checker..." + +``` +Task( + prompt=checker_prompt, + subagent_type="gsd-plan-checker", + description="Verify Phase {phase} plans" +) +``` + +Checker prompt template: +```markdown + + +**Phase:** {phase_number} +**Phase Goal:** {goal from ROADMAP} + +**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 + +``` + +## 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 + +## 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. + +``` + + - 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} + +--- + +## Next Up + +**Phase {X}: [Phase Name]** - {N} plan(s) + +`/gsd:execute-phase {X}` + +`/clear` first - fresh context window + +--- +``` + + +``` + +**Key design decisions from BRIEF:** +- Orchestrator stays in main context (user sees ping-pong) +- Files on disk as handoff mechanism +- Max 3 iterations before escalating to user +- --skip-verify flag for experienced users + + + - Process has 11 steps: `grep -c "^## [0-9]" commands/gsd/plan-phase.md` + - Checker spawn exists: `grep -c "gsd-plan-checker" commands/gsd/plan-phase.md` (at least 2) + - Revision loop exists: `grep -c "iteration" commands/gsd/plan-phase.md` (at least 3) + + Process section rewritten with planner → checker → revise loop, max 3 iterations, user visibility + + + + Task 3: Update success criteria + commands/gsd/plan-phase.md + +Update `` to include verification loop: + +```markdown + +- [ ] .planning/ directory validated +- [ ] Phase validated against roadmap +- [ ] Existing plans checked +- [ ] gsd-planner spawned with context +- [ ] Plans created (PLANNING COMPLETE or CHECKPOINT handled) +- [ ] gsd-plan-checker spawned (unless --skip-verify) +- [ ] Verification passed OR user override OR max iterations with user decision +- [ ] User sees status between agent spawns +- [ ] User knows next steps (execute or review) + +``` + + grep -c "gsd-plan-checker" commands/gsd/plan-phase.md (at least 3 — in process and success_criteria) + Success criteria updated to include verification loop steps + + + + + +- [ ] context: fork removed from frontmatter +- [ ] Task tool added to allowed-tools +- [ ] Process has 11 numbered steps +- [ ] Checker spawn in step 8 +- [ ] Revision loop in step 10 with max 3 iterations +- [ ] --skip-verify flag documented +- [ ] Success criteria includes verification steps + + + +- plan-phase.md orchestrates planner → checker loop +- User sees status between agent spawns +- Max 3 iterations before user escalation +- --skip-verify flag available for power users +- Orchestrator stays in main context (no fork) + + + +After completion, create `.planning/phases/16-plan-verification-loop/16-02-SUMMARY.md` + diff --git a/.planning/phases/16-plan-verification-loop/16-03-PLAN.md b/.planning/phases/16-plan-verification-loop/16-03-PLAN.md new file mode 100644 index 000000000..0f0e17020 --- /dev/null +++ b/.planning/phases/16-plan-verification-loop/16-03-PLAN.md @@ -0,0 +1,273 @@ +--- +phase: 16-plan-verification-loop +plan: 03 +type: execute +wave: 2 +depends_on: ["16-01"] +files_modified: [agents/gsd-planner.md] +autonomous: true + +must_haves: + truths: + - "Planner can accept checker feedback in revision mode" + - "Planner reads existing PLAN.md files when revising" + - "Planner makes targeted updates, not full replan" + - "Planner returns what changed for user visibility" + artifacts: + - path: "agents/gsd-planner.md" + provides: "Standard and revision planning modes" + min_lines: 1100 + key_links: + - from: "gsd-planner revision_mode" + to: "existing PLAN.md files" + via: "Read tool in revision flow" + - from: "gsd-planner" + to: "checker issues" + via: "revision_context in prompt" +--- + + +Add revision mode to gsd-planner agent for handling checker feedback. + +Purpose: Planner can make targeted updates to existing plans based on checker issues, completing the verification loop. + +Output: Updated agents/gsd-planner.md with revision mode + + + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md + +Current planner agent (to be updated): +@agents/gsd-planner.md + +Checker agent (from 16-01, for understanding issue format): +@agents/gsd-plan-checker.md + +Phase brief: +@.planning/phases/16-plan-verification-loop/16-BRIEF.md + + + + + + Task 1: Add revision_mode section to gsd-planner + agents/gsd-planner.md + +Add new `` section (~100 lines) after `` section. + +```markdown + + +## Planning from Checker Feedback + +Triggered when orchestrator provides `` with checker issues. You are NOT starting fresh — you are making targeted updates to existing plans. + +**Mindset:** Surgeon, not architect. Minimal changes to address specific issues. + +### Step 1: Load Existing Plans + +Read all PLAN.md files in the phase directory: + +```bash +cat .planning/phases/${PHASE}-*/*-PLAN.md +``` + +Build mental model of: +- Current plan structure (wave assignments, dependencies) +- Existing tasks (what's already planned) +- must_haves (goal-backward criteria) + +### Step 2: Parse Checker Issues + +Issues come in structured format: + +```yaml +issues: + - plan: "16-01" + dimension: "task_completeness" + severity: "blocker" + description: "Task 2 missing element" + fix_hint: "Add verification command for build output" +``` + +Group issues by: +- Plan (which PLAN.md needs updating) +- Dimension (what type of issue) +- Severity (blocker vs warning) + +### Step 3: Determine Revision Strategy + +**For each issue type:** + +| Dimension | Revision Strategy | +|-----------|-------------------| +| requirement_coverage | Add task(s) to cover missing requirement | +| task_completeness | Add missing elements to existing task | +| dependency_correctness | Fix depends_on array, recompute waves | +| key_links_planned | Add wiring task or update action to include wiring | +| scope_sanity | Split plan into multiple smaller plans | +| must_haves_derivation | Derive and add must_haves to frontmatter | + +### Step 4: Make Targeted Updates + +**DO:** +- Edit specific sections that checker flagged +- Preserve working parts of plans +- Update wave numbers if dependencies change +- Keep changes minimal and focused + +**DO NOT:** +- Rewrite entire plans for minor issues +- Change task structure if only missing elements +- Add unnecessary tasks beyond what checker requested +- Break existing working plans + +### Step 5: Validate Changes + +After making edits, self-check: +- [ ] All flagged issues addressed +- [ ] No new issues introduced +- [ ] Wave numbers still valid +- [ ] Dependencies still correct +- [ ] Files on disk updated (use Write tool) + +### Step 6: Return Revision Summary + +```markdown +## REVISION COMPLETE + +**Issues addressed:** {N}/{M} + +### Changes Made + +| Plan | Change | Issue Addressed | +|------|--------|-----------------| +| 16-01 | Added to Task 2 | task_completeness | +| 16-02 | Added logout task | requirement_coverage (AUTH-02) | + +### Files Updated + +- .planning/phases/16-xxx/16-01-PLAN.md +- .planning/phases/16-xxx/16-02-PLAN.md + +{If any issues NOT addressed:} + +### Unaddressed Issues + +| Issue | Reason | +|-------|--------| +| {issue} | {why not addressed - needs user input} | +``` + + +``` + +Place this section after `` and before ``. + + grep -c "" agents/gsd-planner.md (should be 1) + revision_mode section added with 6-step revision process + + + + Task 2: Update role section to mention revision mode + agents/gsd-planner.md + +Update the `` section to mention revision mode. Find the line that says: + +```markdown +You are spawned by: + +- `/gsd:plan-phase` orchestrator (standard phase planning) +- `/gsd:plan-phase --gaps` orchestrator (gap closure planning from verification failures) +``` + +And update to: + +```markdown +You are spawned by: + +- `/gsd:plan-phase` orchestrator (standard phase planning) +- `/gsd:plan-phase --gaps` orchestrator (gap closure planning from verification failures) +- `/gsd:plan-phase` orchestrator in revision mode (updating plans based on checker feedback) +``` + +Also update the **Core responsibilities** list to add: + +```markdown +- Revise existing plans based on checker feedback (revision mode) +``` + + grep -c "revision mode" agents/gsd-planner.md (at least 2) + Role section updated to document revision mode spawning + + + + Task 3: Add revision return format to structured_returns + agents/gsd-planner.md + +Add REVISION COMPLETE format to `` section. Find the section and add after "Gap Closure Plans Created": + +```markdown +## Revision Complete + +```markdown +## REVISION COMPLETE + +**Issues addressed:** {N}/{M} + +### Changes Made + +| Plan | Change | Issue Addressed | +|------|--------|-----------------| +| {plan-id} | {what changed} | {dimension: description} | + +### Files Updated + +- .planning/phases/{phase_dir}/{plan}-PLAN.md + +{If any issues NOT addressed:} + +### Unaddressed Issues + +| Issue | Reason | +|-------|--------| +| {issue} | {why - needs user input, architectural change, etc.} | + +### Ready for Re-verification + +Checker can now re-verify updated plans. +``` +``` + + grep -c "REVISION COMPLETE" agents/gsd-planner.md (should be 2 — in revision_mode and structured_returns) + REVISION COMPLETE return format added to structured_returns section + + + + + +- [ ] revision_mode section exists (~100 lines) +- [ ] 6 steps documented in revision_mode +- [ ] Role section mentions revision mode +- [ ] Core responsibilities include revision +- [ ] structured_returns has REVISION COMPLETE format +- [ ] File still parses correctly (no broken XML) + + + +- gsd-planner has complete revision mode documentation +- Revision strategy table covers all issue dimensions +- Return format matches what orchestrator expects +- Planner can be spawned in standard, gap_closure, or revision mode + + + +After completion, create `.planning/phases/16-plan-verification-loop/16-03-SUMMARY.md` + diff --git a/.planning/phases/16-plan-verification-loop/16-BRIEF.md b/.planning/phases/16-plan-verification-loop/16-BRIEF.md new file mode 100644 index 000000000..d2fb92c2a --- /dev/null +++ b/.planning/phases/16-plan-verification-loop/16-BRIEF.md @@ -0,0 +1,139 @@ +# Phase 16: Plan Verification Loop + +## Problem + +Plans are created and executed without validation. The executor verifies task completion, but nothing verifies the plan will achieve the phase goal before execution begins. + +Current flow: +``` +plan-phase → creates PLAN.md → execute-plan → verifier checks if tasks completed +``` + +Gap: A plan can have all tasks complete but still fail the phase goal if the tasks were wrong. + +## Solution + +Add plan verification between planning and execution: + +``` +plan-phase (orchestrator) + │ + ├── "Phase 3: Auth — launching planner..." + │ + ├── Task(gsd-planner) + │ └── WRITES PLAN.md files to disk + │ └── Returns summary + │ + ├── "Planner created 3 plans. Launching checker..." + │ + ├── Task(gsd-plan-checker) + │ └── READS PLAN.md files from disk + │ └── Verifies plans will achieve phase goal + │ └── Returns passed | issues + │ + ├── IF issues: + │ "Checker found issues: + │ - 03-01 missing password hashing task + │ - 03-03 has no verification for middleware + │ + │ Sending back to planner..." + │ + │ Task(gsd-planner, with checker feedback) + │ └── READS existing PLAN.md files + │ └── UPDATES based on feedback + │ └── Returns what changed + │ + │ Task(gsd-plan-checker) → re-verify + │ + └── "Plans verified. Ready for execution." +``` + +## Key Design Decisions + +### Files on disk as handoff mechanism + +Each agent reads from and writes to disk. No context passing between agents. + +- Checker sees exactly what executor will see +- Planner can make surgical updates +- Nothing lost between spawns +- Fresh perspective each time + +### User sees the ping-pong + +Orchestrator stays in main context. User sees: +- What phase is being planned +- What planner created +- What checker found +- What planner revised +- Final verification status + +Not a black box. + +### gsd-plan-checker responsibilities + +Goal-backward verification of plan quality: + +1. **Requirement coverage** — Every phase requirement has task(s) addressing it +2. **Task completeness** — Every task has Files + Action + Verify + Done +3. **Dependency correctness** — Nothing references future work +4. **Key links planned** — Not just artifacts, but wiring between them +5. **Scope sanity** — Plans within context budget (~50%) +6. **Verification derivation** — must_haves trace back to phase goal + +### Loop termination + +- Max 3 iterations (plan → check → revise → check → revise → check) +- If still failing after 3, present issues to user for decision +- User can: force proceed, provide guidance, abandon + +## Deliverables + +### 1. Create `agents/gsd-plan-checker.md` + +New agent with plan verification expertise: +- Reads PLAN.md files from disk +- Checks against phase goal and requirements +- Returns structured issues or passed +- ~400-600 lines (similar scope to gsd-verifier) + +### 2. Update `commands/gsd/plan-phase.md` + +Remove `context: fork` — orchestrator stays in main context. + +Add orchestration logic: +- Spawn gsd-planner (existing) +- Present results to user +- Spawn gsd-plan-checker +- If issues, present and spawn planner with feedback +- Loop until passed or max iterations +- Present final status + +### 3. Update `agents/gsd-planner.md` + +Add revision mode: +- Accept checker feedback in prompt +- Read existing PLAN.md files +- Make targeted updates (not full replan) +- Return what changed + +## Architecture Alignment + +Follows established patterns: +- `gsd-executor` creates code, `gsd-verifier` checks it +- `gsd-planner` creates plans, `gsd-plan-checker` checks them + +Mirrors the verification philosophy: +- Goal-backward thinking +- must_haves as checkable criteria +- Structured gap reporting + +## Success Criteria + +- [ ] `gsd-plan-checker` agent created +- [ ] `plan-phase.md` orchestrates planner → checker loop +- [ ] User sees status between agent spawns +- [ ] Checker verifies plans against phase goal +- [ ] Planner can revise based on feedback +- [ ] Loop terminates (max 3 iterations or passed) +- [ ] Plans verified before execution available