Files
msd-core/.planning/phases/16-plan-verification-loop/16-02-PLAN.md
Lex Christopherson 96cd23c750 docs(16): create phase plan
Phase 16: Plan Verification Loop
- 3 plan(s) in 2 wave(s)
- Wave 1: 16-01 (create gsd-plan-checker agent)
- Wave 2: 16-02, 16-03 (parallel - orchestrator + planner revision)
- Ready for execution

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-16 08:52:31 -06:00

8.3 KiB

phase, plan, type, wave, depends_on, files_modified, autonomous, must_haves
phase plan type wave depends_on files_modified autonomous must_haves
16-plan-verification-loop 02 execute 2
16-01
commands/gsd/plan-phase.md
true
truths artifacts key_links
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
path provides min_lines
commands/gsd/plan-phase.md Orchestrator for planner → checker → revise loop 200
from to via
plan-phase.md gsd-planner Task() spawn with planning_context
from to via
plan-phase.md gsd-plan-checker Task() spawn with verification_context
from to via
checker output planner revision spawn 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

<execution_context> @/.claude/get-shit-done/workflows/execute-plan.md @/.claude/get-shit-done/templates/summary.md </execution_context>

@.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):
---
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:

<process>

## 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
<verification_context>

**Phase:** {phase_number}
**Phase Goal:** {goal from ROADMAP}

**Plans to verify:**
@.planning/phases/{phase_dir}/*-PLAN.md

**Requirements (if exists):**
@.planning/REQUIREMENTS.md

</verification_context>

<expected_output>
Return one of:
- ## VERIFICATION PASSED — all checks pass
- ## ISSUES FOUND — structured issue list
</expected_output>

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:
<revision_context>

**Phase:** {phase_number}
**Mode:** revision

**Existing plans:**
@.planning/phases/{phase_dir}/*-PLAN.md

**Checker issues:**
{structured_issues_from_checker}

</revision_context>

<instructions>
Read existing PLAN.md files. Make targeted updates to address checker issues.
Do NOT replan from scratch unless issues are fundamental.
Return what changed.
</instructions>
  • 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

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}`

<sub>`/clear` first - fresh context window</sub>

---
```

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:
<success_criteria>
- [ ] .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)
</success_criteria>
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

<success_criteria>

  • 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) </success_criteria>
After completion, create `.planning/phases/16-plan-verification-loop/16-02-SUMMARY.md`