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>
This commit is contained in:
Lex Christopherson
@@ -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 | - |
|
||||
|
||||
@@ -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
|
||||
|
||||
216
.planning/phases/16-plan-verification-loop/16-01-PLAN.md
Normal file
216
.planning/phases/16-plan-verification-loop/16-01-PLAN.md
Normal file
@@ -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"
|
||||
---
|
||||
|
||||
<objective>
|
||||
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)
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@~/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.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
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Create gsd-plan-checker agent file</name>
|
||||
<files>agents/gsd-plan-checker.md</files>
|
||||
<action>
|
||||
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. `<role>` (~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. `<core_principle>` (~40 lines)
|
||||
- "Plan completeness ≠ Goal achievement"
|
||||
- Goal-backward verification of PLANS not code
|
||||
- Start from phase goal, verify plans address it
|
||||
|
||||
3. `<verification_dimensions>` (~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. `<verification_process>` (~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. `<issue_structure>` (~60 lines)
|
||||
Output format for issues:
|
||||
```yaml
|
||||
issues:
|
||||
- plan: "16-01"
|
||||
dimension: "task_completeness"
|
||||
severity: "blocker"
|
||||
description: "Task 2 missing <verify> element"
|
||||
fix_hint: "Add verification command for build output"
|
||||
```
|
||||
|
||||
6. `<structured_returns>` (~50 lines)
|
||||
Return formats:
|
||||
- `## VERIFICATION PASSED` — All checks pass
|
||||
- `## ISSUES FOUND` — Structured list for planner
|
||||
Include plan_ids, issue_count, dimensions_failed
|
||||
|
||||
7. `<success_criteria>` (~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.
|
||||
</action>
|
||||
<verify>
|
||||
- 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)
|
||||
</verify>
|
||||
<done>gsd-plan-checker.md created with complete plan verification expertise, follows gsd-verifier pattern, has all 7 required sections</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Add example verification scenarios</name>
|
||||
<files>agents/gsd-plan-checker.md</files>
|
||||
<action>
|
||||
Add `<examples>` 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
|
||||
<task type="auto">
|
||||
<name>Create login endpoint</name>
|
||||
<files>src/app/api/auth/login/route.ts</files>
|
||||
<action>POST endpoint with bcrypt validation</action>
|
||||
<!-- Missing <verify> -->
|
||||
<done>Login works</done>
|
||||
</task>
|
||||
|
||||
Issue: Task missing <verify> 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
|
||||
```
|
||||
</action>
|
||||
<verify>grep -c "<examples>" agents/gsd-plan-checker.md (should be 1)</verify>
|
||||
<done>Examples section added with 4 verification scenarios covering common issues</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
- [ ] 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
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- 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
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/16-plan-verification-loop/16-01-SUMMARY.md`
|
||||
</output>
|
||||
325
.planning/phases/16-plan-verification-loop/16-02-PLAN.md
Normal file
325
.planning/phases/16-plan-verification-loop/16-02-PLAN.md
Normal file
@@ -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"
|
||||
---
|
||||
|
||||
<objective>
|
||||
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
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@~/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<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
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Update plan-phase.md frontmatter</name>
|
||||
<files>commands/gsd/plan-phase.md</files>
|
||||
<action>
|
||||
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)
|
||||
</action>
|
||||
<verify>grep -E "^context:" commands/gsd/plan-phase.md (should return nothing)</verify>
|
||||
<done>Frontmatter updated, context: fork removed, Task tool added</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Add verification loop to process</name>
|
||||
<files>commands/gsd/plan-phase.md</files>
|
||||
<action>
|
||||
Rewrite `<process>` section to include verification loop. Target ~250-300 lines total for orchestrator.
|
||||
|
||||
**New process flow:**
|
||||
|
||||
```markdown
|
||||
<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:
|
||||
|
||||
```markdown
|
||||
<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
|
||||
|
||||
```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}`
|
||||
|
||||
<sub>`/clear` first - fresh context window</sub>
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
</process>
|
||||
```
|
||||
|
||||
**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
|
||||
</action>
|
||||
<verify>
|
||||
- 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)
|
||||
</verify>
|
||||
<done>Process section rewritten with planner → checker → revise loop, max 3 iterations, user visibility</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: Update success criteria</name>
|
||||
<files>commands/gsd/plan-phase.md</files>
|
||||
<action>
|
||||
Update `<success_criteria>` to include verification loop:
|
||||
|
||||
```markdown
|
||||
<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>
|
||||
```
|
||||
</action>
|
||||
<verify>grep -c "gsd-plan-checker" commands/gsd/plan-phase.md (at least 3 — in process and success_criteria)</verify>
|
||||
<done>Success criteria updated to include verification loop steps</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
- [ ] 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
|
||||
</verification>
|
||||
|
||||
<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>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/16-plan-verification-loop/16-02-SUMMARY.md`
|
||||
</output>
|
||||
273
.planning/phases/16-plan-verification-loop/16-03-PLAN.md
Normal file
273
.planning/phases/16-plan-verification-loop/16-03-PLAN.md
Normal file
@@ -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"
|
||||
---
|
||||
|
||||
<objective>
|
||||
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
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@~/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.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
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Add revision_mode section to gsd-planner</name>
|
||||
<files>agents/gsd-planner.md</files>
|
||||
<action>
|
||||
Add new `<revision_mode>` section (~100 lines) after `<gap_closure_mode>` section.
|
||||
|
||||
```markdown
|
||||
<revision_mode>
|
||||
|
||||
## Planning from Checker Feedback
|
||||
|
||||
Triggered when orchestrator provides `<revision_context>` 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 <verify> 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 <verify> 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} |
|
||||
```
|
||||
|
||||
</revision_mode>
|
||||
```
|
||||
|
||||
Place this section after `<gap_closure_mode>` and before `<execution_flow>`.
|
||||
</action>
|
||||
<verify>grep -c "<revision_mode>" agents/gsd-planner.md (should be 1)</verify>
|
||||
<done>revision_mode section added with 6-step revision process</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Update role section to mention revision mode</name>
|
||||
<files>agents/gsd-planner.md</files>
|
||||
<action>
|
||||
Update the `<role>` 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)
|
||||
```
|
||||
</action>
|
||||
<verify>grep -c "revision mode" agents/gsd-planner.md (at least 2)</verify>
|
||||
<done>Role section updated to document revision mode spawning</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: Add revision return format to structured_returns</name>
|
||||
<files>agents/gsd-planner.md</files>
|
||||
<action>
|
||||
Add REVISION COMPLETE format to `<structured_returns>` 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.
|
||||
```
|
||||
```
|
||||
</action>
|
||||
<verify>grep -c "REVISION COMPLETE" agents/gsd-planner.md (should be 2 — in revision_mode and structured_returns)</verify>
|
||||
<done>REVISION COMPLETE return format added to structured_returns section</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
- [ ] 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)
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- 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
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/16-plan-verification-loop/16-03-SUMMARY.md`
|
||||
</output>
|
||||
139
.planning/phases/16-plan-verification-loop/16-BRIEF.md
Normal file
139
.planning/phases/16-plan-verification-loop/16-BRIEF.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user