golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: delete old .planning files

Browse Source
This commit is contained in:
Lex Christopherson
2026-01-16 17:18:28 -06:00
parent 8251879aab
commit eb641b7339
37 changed files with 0 additions and 6117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

351
.planning/ROADMAP.md
View File

@@ -1,351 +0,0 @@
# Roadmap: GSD Brownfield Support
## Overview
Add comprehensive brownfield support to GSD. Users adopting GSD for existing codebases will have a systematic way to capture architectural knowledge before planning begins. A new `/gsd:map-codebase` workflow will produce structured `.planning/codebase/` documents that stay current as plans execute.
## Domain Expertise
None - this is internal GSD development following existing command/workflow/template patterns.
## Phases
**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
- [ ] **Phase 1: Templates & Structure** - Create codebase map templates and folder structure
- [ ] **Phase 2: Map Codebase Command** - Build /gsd:map-codebase with parallel Explore agents
- [ ] **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
- [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
- [x] **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
### Phase 1: Templates & Structure
**Goal**: Create templates for all codebase map document types and define the folder structure
**Depends on**: Nothing (first phase)
**Research**: Unlikely (established GSD template patterns)
**Plans**: TBD
Documents to template:
- stack.md (languages, frameworks, dependencies)
- architecture.md (patterns, layers, data flow)
- structure.md (directory layout, key files)
- conventions.md (coding standards, naming)
- testing.md (test setup, patterns)
- integrations.md (external services, APIs)
- concerns.md (tech debt, known issues)
### Phase 2: Map Codebase Command
**Goal**: Build the /gsd:map-codebase slash command with parallel Explore agent workflow
**Depends on**: Phase 1
**Research**: Unlikely (using existing Explore agent patterns, GSD workflow conventions)
**Plans**: TBD
Components:
- Slash command: `commands/gsd/map-codebase.md`
- Workflow: `get-shit-done/workflows/map-codebase.md`
- Parallel Explore agent orchestration
- Output to `.planning/codebase/`
### Phase 3: Integration
**Goal**: Wire brownfield support into existing GSD workflows
**Depends on**: Phase 2
**Research**: Unlikely (modifying existing GSD commands, established patterns)
**Plans**: TBD
Integration points:
- `/gsd:new-project` - detect existing code, offer to map first
- `/gsd:plan-phase` - load relevant codebase context automatically
- Post-execution - update codebase map after plan execution
### Phase 4: Plan-Phase Optimizations
**Goal**: Reduce context usage in /gsd:plan-phase by ~37% through file consolidation and verbosity reduction
**Depends on**: Phase 3
**Research**: Unlikely (internal optimization of existing files)
**Plans**: TBD
Optimization targets:
- Merge `cli-automation.md` into `checkpoints.md` (-15KB)
- Compress `plan-format.md` to reference card (-7KB)
- Trim `scope-estimation.md` verbosity (-6KB)
- Streamline `plan-phase.md` workflow (-9KB)
### Phase 5: TDD Instructions
**Goal**: Add TDD guidance to GSD so Claude uses test-driven development when appropriate and beneficial
**Depends on**: Phase 4
**Research**: Unlikely (established TDD patterns, GSD integration points clear)
**Plans**: 2 plans
Plans:
- [ ] 05-01: TDD Foundation - Create tdd.md reference, add TDD annotation to plan-format.md
- [ ] 05-02: TDD Integration - Update plan-phase.md detection, execute-phase.md execution flow
### Phase 6: Frontmatter System Upgrade
**Goal:** Add YAML frontmatter to SUMMARY.md enabling automatic context assembly via dependency graph
**Depends on:** Phase 5
**Plans:** 2 plans
Plans:
- [ ] 06-01: Frontmatter Schema - Add comprehensive YAML frontmatter to summary.md template with dependency metadata
- [ ] 06-02: Intelligent Selection - Implement frontmatter-based context assembly in plan-phase.md
**Details:**
Transform planning from "Claude guesses which summaries to read" to "System automatically assembles optimal context" by:
- Adding frontmatter with subsystem, requires/provides/affects, tech-stack, key-files, key-decisions
- Scanning all summary frontmatter (fast - first ~25 lines each)
- Building dependency graph to auto-select relevant prior phases
- Extracting context from frontmatter before reading full summaries
- Making context assembly deterministic and optimal
### Phase 7: Backfill Existing Summaries With Frontmatter
**Goal:** Backfill YAML frontmatter with dependency graph metadata to Phase 1-6 historical summaries
**Depends on:** Phase 6
**Plans:** 1 plan
Plans:
- [x] 07-01: Backfill frontmatter to all Phase 1-5 summaries (10 files)
**Details:**
Enable intelligent context assembly for all historical phases by adding consistent frontmatter with subsystem categorization, dependency graph (requires/provides/affects), tech tracking, key decisions, and patterns established.
### Phase 8: Improve Roadmap System
**Goal:** [To be planned]
**Depends on:** Phase 7
**Research:** Unlikely (internal GSD workflow improvements)
**Plans:** TBD
Plans:
- [ ] TBD (run /gsd:plan-phase 8 to break down)
**Details:**
[To be added during planning]
### Phase 9: Integrate Verify-Work
**Goal:** Properly integrate /gsd:verify-work into GSD with workflow delegation, templates, and /gsd:plan-fix command
**Depends on:** Phase 8
**Research:** Unlikely (refactoring contributed command to match GSD patterns)
**Plans:** TBD
Components:
- Refactor `commands/gsd/verify-work.md` to GSD style (workflow delegation)
- Create `workflows/verify-work.md` for UAT logic
- Create `templates/uat-issues.md` for phase-scoped issues format
- Create `commands/gsd/plan-fix.md` for planning fixes from UAT issues
- Update `commands/gsd/progress.md` to offer plan-fix when issues exist
- Update README.md with new commands
**Details:**
Community contribution from OracleGreyBeard. Original command works but doesn't follow GSD patterns (no workflow delegation, inline templates, verbose steps). Refactor to match conventions, then add /gsd:plan-fix to complete the verify → fix loop.
### Phase 10: Parallel Phase Execution
**Goal:** Implement proper parallel phase execution with clean separation between single-plan and multi-plan execution
**Depends on:** Phase 9
**Research:** Unlikely (adapting PR #43 patterns, existing GSD conventions)
**Plans:** 4 plans
Plans:
- [x] 10-01: Rename execute-phase → execute-plan - Rename workflow file, update all 9 references across commands/workflows/templates
- [x] 10-02: Create parallel execution workflow - New `workflows/execute-phase.md` with dependency analysis, parallel spawning, orchestrator commits
- [x] 10-03: Create execute-phase command - New `commands/gsd/execute-phase.md` + parallelization config schema in templates/config.json
- [x] 10-04: Update agent-history schema - Extend to v1.2 with parallel_group, granularity, task_results fields
**Details:**
Structural refactoring to separate concerns:
- `/gsd:execute-plan` executes a single PLAN.md (current behavior, ~1,700 lines)
- `/gsd:execute-phase` executes all plans in a phase with intelligent parallelization (~1,300 lines)
Parallelization features (adapted from PR #43):
- Dependency analysis via `requires`/`provides` frontmatter + `<files>` overlap detection
- Parallel agent spawning for independent plans (respects max_concurrent_agents)
- Orchestrator holds commits until all agents complete
- Merge conflict detection as failsafe
- Configurable via `.planning/config.json` parallelization section
### Phase 11: Parallel-Aware Planning
**Goal:** Update plan-phase.md to create plans optimized for parallel execution when parallelization is enabled
**Depends on:** Phase 10
**Research:** Unlikely (extending existing plan-phase workflow)
**Plans:** 4 plans
Plans:
- [x] 11-01: Update phase-prompt template - Add parallelization frontmatter fields (parallelizable, depends_on, files_exclusive)
- [x] 11-02: Add parallel-aware step to plan-phase workflow - Read config, restructure for vertical slices, document independence
- [x] 11-03: Update execute-phase to use plan frontmatter - Use explicit markers instead of inference, backward compat
- [x] 11-04: Documentation and examples - Update references, add parallel vs sequential planning examples
**Details:**
Current plan-phase.md has sequential execution bias - later plans reference earlier SUMMARY.md, file overlap is acceptable, no independence markers. When parallelization enabled in config.json, planning should:
- Group by vertical slice (feature A, feature B) not workflow stage (setup → implement → test)
- Avoid unnecessary inter-plan dependencies (only reference SUMMARY if genuinely needed)
- Mark explicit file ownership per plan
- Add frontmatter: `parallelizable: true/false`, `depends_on: []`, `files_exclusive: []`
This enables execute-phase to produce more Wave 1 plans (true independence) instead of sequential chains.
### Phase 12: Changelog & Update Awareness
**Goal:** Add changelog generation to publish workflow and `/gsd:whats-new` command for users to discover changes
**Depends on:** Phase 11
**Research:** Unlikely (straightforward command + workflow additions)
**Plans:** 3 plans
Plans:
- [x] 12-01: CHANGELOG.md foundation - Create changelog file, update installer to copy it
- [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:**
- Wave 1: 12-01 (foundation)
- Wave 2: 12-02, 12-03 (parallel - both depend only on 12-01)
**Details:**
Users adopting GSD need visibility into what changed between versions. The publish workflow generates curated changelog entries (Claude-drafted, Lex-approved). `/gsd:whats-new` fetches from GitHub raw, compares to installed version, and prompts to update if behind.
### Phase 13: Dedicated Debug Agent
**Goal:** Create `gsd-debugger` agent with all debugging expertise baked in, refactor `/gsd:debug` to thin orchestrator
**Depends on:** Phase 12
**Research:** Unlikely (consolidating existing debugging content into agent pattern)
**Plans:** 3 plans
Plans:
- [x] 13-01: Create gsd-debugger agent - Consolidate debugging expertise (990 lines)
- [x] 13-02: Refactor /gsd:debug - Thin orchestrator (149 lines), deprecate workflow
- [x] 13-03: Deprecate reference files - Replace with agent pointers
**Details:**
Created gsd-debugger agent with scientific method, hypothesis testing, 7+ investigation techniques, verification patterns, and debug file protocol. Command reduced from ~2,400 loaded lines to 149-line thin orchestrator.
### Phase 14: Dedicated Researcher Agent
**Goal:** Create `gsd-researcher` agent with research methodology baked in, refactor research commands to spawn specialized agents
**Depends on:** Phase 13
**Research:** Unlikely (applying same agent pattern to research workflows)
**Plans:** 3 plans
Plans:
- [x] 14-01: Create gsd-researcher agent - Consolidate research expertise (902 lines)
- [x] 14-02: Refactor /gsd:research-phase - Thin orchestrator (130 lines), deprecate workflow
- [x] 14-03: Refactor /gsd:research-project - Parallel agent spawning (137 lines), deprecate workflow
**Wave structure:**
- Wave 1: 14-01 (foundation)
- Wave 2: 14-02, 14-03 (parallel - both depend only on 14-01)
Components:
- Create `agents/gsd-researcher.md` with research expertise
- Refactor `commands/gsd/research-phase.md` to spawn gsd-researcher
- Refactor `commands/gsd/research-project.md` to use researcher agents
- Define research modes: ecosystem, feasibility, implementation, comparison
**Details:**
Currently `/gsd:research-phase` does ad-hoc web searches without structure. The gsd-researcher agent brings:
- **Research methodology**: Scoping questions, evaluating sources, synthesizing findings
- **Tool strategy**: When to WebSearch vs WebFetch vs Grep vs Context7
- **Output formats**: Structured findings (feasibility, comparison matrices, API investigations)
- **Evidence quality**: Distinguishing authoritative sources from noise
- **Research modes**:
- `ecosystem` — Survey landscape (tools, approaches, prior art)
- `feasibility` — Can we do X? What are blockers?
- `implementation` — How specifically to implement X?
- `comparison` — Compare options A vs B vs C
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:
- [x] 16-01: Create gsd-plan-checker agent - Goal-backward plan verification (744 lines)
- [x] 16-02: Update plan-phase.md orchestrator - Planner → checker → revise loop (310 lines)
- [x] 16-03: Update gsd-planner.md - Add revision mode for handling checker feedback (1,284 lines total)
**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
**Depends on:** Nothing (independent test)
**Research:** No
**Plans:** 3 plans (all parallelizable)
Plans:
- [x] 99-01: Create animal-facts.md - A file with 5 animal facts
- [x] 99-02: Create dad-jokes.md - A file with 5 dad jokes
- [x] 99-03: Create random-numbers.md - A file with 5 random numbers
**Details:**
Each plan touches completely different files, no dependencies, perfect for testing Wave 1 parallel execution.
Files go in: `test-output/` (gitignored throwaway directory)
## Progress
**Execution Order:**
Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Templates & Structure | 3/3 | Complete | 2025-12-17 |
| 2. Map Codebase Command | 2/2 | Complete | 2025-12-17 |
| 3. Integration | 1/1 | Complete | 2025-12-17 |
| 4. Plan-Phase Optimizations | 2/2 | Complete | 2025-12-29 |
| 5. TDD Instructions | 2/2 | Complete | 2025-12-31 |
| 6. Frontmatter System Upgrade | 2/2 | Complete | 2026-01-05 |
| 7. Backfill Existing Summaries | 1/1 | Complete | 2026-01-05 |
| 8. Improve Roadmap System | 1/1 | Complete | 2026-01-05 |
| 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 | 3/3 | Complete | 2026-01-16 |

139
.planning/STATE.md
View File

@@ -1,139 +0,0 @@
# Project State
## Project Summary
**Building:** Brownfield support for GSD - `/gsd:map-codebase` workflow that analyzes existing codebases using parallel Explore agents, producing structured `.planning/codebase/` documents.
**Core requirements:**
- `/gsd:map-codebase` produces useful codebase documents from any codebase
- Documents are focused (<100 lines each) and easy to update incrementally
- `/gsd:new-project` detects existing code and offers mapping
- `/gsd:plan-phase` loads relevant codebase context automatically
- Codebase map updates after plan execution
**Constraints:**
- Explore agents required for initial mapping
- Each codebase map file must stay under ~100 lines
- Only load relevant codebase sections into phase planning
- Follow existing GSD command/workflow/template patterns
## Current Position
Phase: 16 of 16 (Plan Verification Loop)
Plan: 3 of 3 in current phase
Status: Phase complete
Last activity: 2026-01-16 - Completed 16-03-PLAN.md
Progress: ███████████████████████████████████████ 39/39 plans (100%)
## Performance Metrics
**Velocity:**
- Total plans completed: 39
- Average duration: 3.4 min
- Total execution time: ~132 min
**By Phase:**
| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| 1 | 3 | 9 min | 3 min |
| 2 | 2 | 5 min | 2.5 min |
| 3 | 1 | 2 min | 2 min |
| 4 | 2 | 7 min | 3.5 min |
| 5 | 2 | 5 min | 2.5 min |
| 6 | 2 | 4 min | 2 min |
| 7 | 1 | 4 min | 4 min |
| 8 | 1 | 1 min | 1 min |
| 9 | 1 | 3 min | 3 min |
| 10 | 4 | 33 min | 8.3 min |
| 11 | 4 | 12 min | 3 min |
| 99 | 3 | 1 min | <1 min (parallel) |
| 13 | 3 | 10 min | 3.3 min |
| 14 | 3 | 11 min | 3.7 min |
| 15 | 3 | 7 min | 2.3 min |
| 16 | 3 | 10 min | 3.3 min |
**Recent Trend:**
- Last 5 plans: 15-03 (1m), 16-01 (3m), 16-02 (4m), 16-03 (3m)
- Trend: Consistent execution times
*Updated after each plan completion*
## Accumulated Context
### Decisions Made
| Phase | Decision | Rationale |
|-------|----------|-----------|
| 0 | Folder with focused files | Easier to update incrementally than monolithic file |
| 0 | Update after plan execution | Fits existing STATE.md update pattern |
| 0 | Parallel Explore agents | Thoroughness for initial mapping |
| 0 | Selective context loading | Avoid loading irrelevant sections |
| 6 | Frontmatter with dependency graph | Enable automatic context assembly via transitive closure |
| 6 | Intelligent summary selection | Scan frontmatter, build graph, auto-select relevant phases |
| 8 | Active milestone details in ROADMAP.md | Single source of truth during development, archive only on completion |
| 9 | Phase-scoped UAT issues | Keep UAT findings tied to specific plan, not global ISSUES.md |
| 10 | git mv preserves history | Rename workflow while keeping git history intact |
| 10 | execute-plan = single, execute-phase = parallel | Clear naming for single-plan vs multi-plan execution |
| 10 | Agent-history v1.2 schema | Extended for parallel tracking, dependencies, resume support |
| 11 | Frontmatter parallelization markers | parallelizable, depends_on, files_exclusive in plan template |
| 11 | Vertical slices over workflow stages | Maximize independence when parallelization enabled |
| 11 | SUMMARY references only when needed | Avoid reflexive sequential chains |
| 13 | Consolidated debugging expertise to 990 lines | Complete methodology with 59% reduction from source material |
| 13 | Thin orchestrator pattern for /gsd:debug | Orchestrator <200 lines, expertise in agent - reduces main context from ~2,400 to ~150 |
| 13 | Deprecated reference files with redirect notices | No duplicate content between references and agent |
| 14 | 4 explicit research modes | Ecosystem, feasibility, implementation, comparison cover all needs |
| 14 | Context7 > Official > WebSearch hierarchy | Prevents hallucination with authoritative sources first |
| 14 | 902 lines from ~1,200 source (25% reduction) | Preserved all concepts while removing redundancy |
| 14 | Thin orchestrator for /gsd:research-phase | Orchestrator 130 lines, expertise in agent |
| 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 |
| 16 | Six verification dimensions | Coverage, completeness, dependencies, links, scope, derivation |
| 16 | Checker verifies plans WILL achieve goal | Same methodology as verifier but applied to plans pre-execution |
| 16 | Orchestrator stays in main context | User sees ping-pong between planner and checker |
| 16 | Max 3 iterations before user escalation | Prevents infinite loops, gives user control |
| 16 | --skip-verify flag for power users | Experienced users can bypass verification when confident |
| 16 | 6-step revision process in planner | Surgeon mindset: minimal targeted updates for checker issues |
| 16 | Strategy table maps dimensions to actions | Each of 6 issue dimensions has specific revision strategy |
### Deferred Issues
None yet.
### Blockers/Concerns Carried Forward
None yet.
### Roadmap Evolution
- Phase 4 added: Plan-phase optimizations (~37% context reduction target)
- Phase 5 added: TDD instructions for appropriate test-driven development
- Phase 6 added: Frontmatter and related system upgrade
- Phase 7 added: Backfill existing summaries with frontmatter
- Phase 8 added: Improve roadmap system
- Phase 9 added: Integrate verify-work (community contribution from OracleGreyBeard)
- Phase 10 added: Parallel phase execution (rename workflow, create /gsd:execute-phase with parallelization)
- Phase 11 added: Parallel-aware planning (update plan-phase.md to create parallelizable plans when enabled)
- Phase 12 added: Changelog & update awareness (remote changelog fetch, /gsd:whats-new, publish workflow integration)
- 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: COMPLETE
Assessment: Phase 16 complete. Plan verification loop — gsd-plan-checker (744 lines), plan-phase orchestrator loop (310 lines), gsd-planner revision mode (1,284 lines).
Drift notes: None
## Session Continuity
Last session: 2026-01-16
Stopped at: Completed 16-03-PLAN.md (Phase 16 complete)
Resume file: None

134
.planning/phases/09-integrate-verify-work/09-01-PLAN.md
View File

@@ -1,134 +0,0 @@
---
phase: 09-integrate-verify-work
plan: 01
type: execute
---
<objective>
Create GSD-compliant foundation for verify-work: workflow, template, and refactored command.
Purpose: Align community-contributed verify-work command with GSD patterns (workflow delegation, templates, terse steps).
Output: Refactored verify-work.md command, new verify-work.md workflow, new uat-issues.md template.
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/execute-phase.md
@~/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
**Current verify-work.md (to refactor):**
@commands/gsd/verify-work.md
**Pattern references (existing GSD commands to match):**
@commands/gsd/discuss-phase.md
@commands/gsd/consider-issues.md
**Pattern references (existing GSD workflows to match):**
@get-shit-done/workflows/discuss-phase.md
**Pattern references (existing GSD templates to match):**
@get-shit-done/templates/context.md
@get-shit-done/templates/issues.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Create verify-work workflow</name>
<files>get-shit-done/workflows/verify-work.md</files>
<action>
Create workflow following GSD patterns from discuss-phase.md:
- Use `<purpose>` tag for overview
- Use `<process>` with `<step name="X">` tags (terse names: identify, extract, generate, guide, collect, log, summarize, offer)
- Reference template for issues format: `@~/.claude/get-shit-done/templates/uat-issues.md`
- Log issues to phase-scoped file: `.planning/phases/XX-name/{phase}-{plan}-ISSUES.md` (NOT global ISSUES.md)
- Use AskUserQuestion for all user interaction (matching discuss-phase.md pattern)
- Include `<success_criteria>` at end
Key logic to preserve from current verify-work.md:
- Find SUMMARY.md based on args or most recent
- Extract user-observable deliverables
- Generate test checklist
- Guide through pass/fail/partial/skip for each test
- Collect issues with severity
- Present summary with verdict
- Offer next actions based on results
</action>
<verify>File exists at get-shit-done/workflows/verify-work.md with proper XML structure</verify>
<done>Workflow file created with GSD-compliant structure, all logic preserved</done>
</task>
<task type="auto">
<name>Task 2: Create UAT issues template</name>
<files>get-shit-done/templates/uat-issues.md</files>
<action>
Create template for phase-scoped UAT issues following patterns from context.md and issues.md:
- Template header explaining purpose and location
- File template section with markdown structure
- Location: `.planning/phases/XX-name/{phase}-{plan}-ISSUES.md`
- Fields: UAT-NNN prefix, discovered date, phase/plan tested, severity, description, expected, actual
- Include good_examples section
- Include guidelines section
Key difference from global issues.md:
- Scoped to specific plan that was tested
- Used as input for /gsd:plan-fix command
- No "Closed Enhancements" section (issues are fixed via FIX.md plan, then file is historical record)
</action>
<verify>File exists at get-shit-done/templates/uat-issues.md with proper template structure</verify>
<done>Template created with phase-scoped issues format</done>
</task>
<task type="auto">
<name>Task 3: Refactor verify-work command</name>
<files>commands/gsd/verify-work.md</files>
<action>
Refactor to match GSD command patterns from discuss-phase.md:
- Add `name: gsd:verify-work` to frontmatter (already present)
- Update execution_context to reference workflow: `@~/.claude/get-shit-done/workflows/verify-work.md`
- Add template reference: `@~/.claude/get-shit-done/templates/uat-issues.md`
- Simplify process section to delegate to workflow (like discuss-phase.md does)
- Remove inline step details (moved to workflow)
- Keep anti_patterns and success_criteria sections
- Update success_criteria to reference phase-scoped ISSUES.md
Structure should match discuss-phase.md:
```
<process>
1. Validate arguments (phase/plan number)
2. Follow verify-work.md workflow
3. Offer next steps (plan-fix if issues found)
</process>
```
</action>
<verify>Command file matches GSD patterns, references workflow and template</verify>
<done>Command refactored to delegate to workflow, follows GSD conventions</done>
</task>
</tasks>
<verification>
Before declaring plan complete:
- [ ] `get-shit-done/workflows/verify-work.md` exists with proper XML structure
- [ ] `get-shit-done/templates/uat-issues.md` exists with template format
- [ ] `commands/gsd/verify-work.md` delegates to workflow
- [ ] No inline logic remains in command (all in workflow)
- [ ] Issues logged to phase-scoped file, not global ISSUES.md
</verification>
<success_criteria>
- All 3 files created/updated
- Workflow follows GSD patterns (terse steps, XML structure)
- Template follows GSD patterns (examples, guidelines)
- Command delegates to workflow (no inline logic)
- Phase-scoped issues file location used
</success_criteria>
<output>
After completion, create `.planning/phases/09-integrate-verify-work/09-01-SUMMARY.md`
</output>

99
.planning/phases/09-integrate-verify-work/09-01-SUMMARY.md
View File

@@ -1,99 +0,0 @@
---
phase: 09-integrate-verify-work
plan: 01
subsystem: commands
tags: [verify-work, uat, testing, workflow, template]
# Dependency graph
requires:
- phase: 08-improve-roadmap
provides: GSD command/workflow patterns
provides:
- verify-work workflow with GSD structure
- UAT issues template for phase-scoped issues
- Refactored verify-work command with workflow delegation
affects: [plan-fix, progress]
# Tech tracking
tech-stack:
added: []
patterns: [workflow-delegation, phase-scoped-issues, AskUserQuestion-pattern]
key-files:
created:
- get-shit-done/workflows/verify-work.md
- get-shit-done/templates/uat-issues.md
modified:
- commands/gsd/verify-work.md
key-decisions:
- "Phase-scoped issues (not global ISSUES.md) for UAT findings"
- "UAT- prefix distinguishes from ISS- enhancement issues"
- "Workflow delegates via AskUserQuestion for all user interaction"
patterns-established:
- "Phase-scoped issue files: {phase}-{plan}-ISSUES.md alongside SUMMARY.md"
- "UAT workflow: extract → generate → guide → collect → log → summarize → offer"
issues-created: []
# Metrics
duration: 3min
completed: 2026-01-08
---
# Phase 9 Plan 1: GSD-Compliant Verify-Work Foundation Summary
**Workflow, template, and refactored command for UAT testing with phase-scoped issue logging**
## Performance
- **Duration:** 3 min
- **Started:** 2026-01-08T14:55:24Z
- **Completed:** 2026-01-08T14:58:12Z
- **Tasks:** 3
- **Files modified:** 3
## Accomplishments
- Created verify-work workflow with GSD-compliant XML structure (terse step names, AskUserQuestion pattern)
- Created UAT issues template for phase-scoped issue tracking
- Refactored verify-work command to delegate to workflow (no inline logic)
## Task Commits
1. **Task 1: Create verify-work workflow** - `a9a9eff` (feat)
2. **Task 2: Create UAT issues template** - `654b066` (feat)
3. **Task 3: Refactor verify-work command** - `e5624d3` (refactor)
**Plan metadata:** (pending)
## Files Created/Modified
- `get-shit-done/workflows/verify-work.md` - UAT workflow with 8 terse steps
- `get-shit-done/templates/uat-issues.md` - Phase-scoped issue format with severity guide
- `commands/gsd/verify-work.md` - Refactored to delegate to workflow
## Decisions Made
- Phase-scoped issues (`{phase}-{plan}-ISSUES.md`) rather than global `ISSUES.md` — keeps UAT findings tied to specific work
- UAT- prefix for numbering — distinguishes from ISS- enhancement issues
- Per-file numbering (UAT-001, UAT-002) — no global sequence needed
## Deviations from Plan
None - plan executed exactly as written.
## Issues Encountered
None
## Next Phase Readiness
- verify-work workflow ready for use
- Next: Create `/gsd:plan-fix` command to complete verify → fix loop
- README.md update needed to document new commands
---
*Phase: 09-integrate-verify-work*
*Completed: 2026-01-08*

98
.planning/phases/10-parallel-phase-execution/10-01-SUMMARY.md
View File

@@ -1,98 +0,0 @@
---
phase: 10-parallel-phase-execution
plan: 01
subsystem: infra
tags: [refactoring, workflow, execute-plan, git-mv]
# Dependency graph
requires:
- phase: 09-integrate-verify-work
provides: verify-work foundation for future execute-phase
provides:
- execute-plan.md workflow file (renamed from execute-phase.md)
- Clean references across all source files
affects: [10-02, 10-03, execute-phase]
# Tech tracking
tech-stack:
added: []
patterns: [execute-plan for single-plan execution]
key-files:
created: []
modified: [get-shit-done/workflows/execute-plan.md, commands/gsd/execute-plan.md, commands/gsd/plan-fix.md, commands/gsd/resume-task.md, get-shit-done/workflows/plan-phase.md, get-shit-done/templates/phase-prompt.md, get-shit-done/templates/summary.md, get-shit-done/templates/agent-history.md, get-shit-done/templates/codebase/structure.md]
key-decisions:
- "git mv preserves history"
- "Historical .planning/ docs keep old names (expected)"
patterns-established:
- "execute-plan = single PLAN.md execution"
- "execute-phase = multi-plan parallel execution (future)"
issues-created: []
# Metrics
duration: 11min
completed: 2026-01-12
---
# Phase 10 Plan 01: Rename execute-phase to execute-plan Summary
**Renamed execute-phase.md workflow to execute-plan.md across 9 source files, preserving git history**
## Performance
- **Duration:** 11 min
- **Started:** 2026-01-12T18:36:43Z
- **Completed:** 2026-01-12T18:47:18Z
- **Tasks:** 3
- **Files modified:** 9
## Accomplishments
- Renamed workflow file using git mv to preserve history
- Updated all @reference paths in commands and templates
- Updated all documentation mentions across 5 files
- Verified installer still works correctly
## Task Commits
Each task was committed atomically:
1. **Task 1: Rename workflow file** - `1690b53` (refactor)
2. **Task 2: Update @reference paths** - `a6960a7` (refactor)
3. **Task 3: Update documentation mentions** - `4ea054b` (docs)
**Plan metadata:** `81cbd29` (docs: complete plan)
## Files Created/Modified
- `get-shit-done/workflows/execute-plan.md` - Renamed from execute-phase.md
- `commands/gsd/execute-plan.md` - Updated workflow reference and process text
- `commands/gsd/plan-fix.md` - Updated execution_context reference
- `commands/gsd/resume-task.md` - Updated infrastructure mention
- `get-shit-done/workflows/plan-phase.md` - Updated execution context reference
- `get-shit-done/templates/phase-prompt.md` - Updated 2 path occurrences
- `get-shit-done/templates/summary.md` - Updated 3 workflow mentions
- `get-shit-done/templates/agent-history.md` - Updated 2 workflow mentions
- `get-shit-done/templates/codebase/structure.md` - Updated example workflow name
## Decisions Made
- Used git mv for rename to preserve file history
- Historical .planning/ documents intentionally keep old references (they document what happened at that time)
- node_modules and .claude/ references are from old installs; installer refreshes them
## Deviations from Plan
None - plan executed exactly as written.
## Issues Encountered
None
## Next Phase Readiness
- Ready for 10-02-PLAN.md (create parallel execution workflow)
- execute-plan.md now handles single-plan execution
- New execute-phase.md will handle multi-plan parallel execution
---
*Phase: 10-parallel-phase-execution*
*Completed: 2026-01-12*

97
.planning/phases/10-parallel-phase-execution/10-02-SUMMARY.md
View File

@@ -1,97 +0,0 @@
---
phase: 10-parallel-phase-execution
plan: 02
subsystem: infra
tags: [workflow, parallel-execution, subagent, Task-tool, orchestrator]
# Dependency graph
requires:
- phase: 10-parallel-phase-execution
provides: execute-plan.md renamed from execute-phase.md
provides:
- execute-phase.md workflow for parallel phase execution
- Dependency analysis with topological sort wave calculation
- Parallel agent spawning with Task tool
- Orchestrator commit handling with merge conflict detection
affects: [10-03, 10-04, execute-phase]
# Tech tracking
tech-stack:
added: []
patterns: [parallel-agent-orchestration, wave-based-execution, orchestrator-commits]
key-files:
created: [get-shit-done/workflows/execute-phase.md]
modified: []
key-decisions:
- "Agents don't commit - orchestrator batches commits"
- "Wave-based execution with topological sort"
- "Merge conflict detection as failsafe"
patterns-established:
- "Parallel agent spawn prompt with PARALLEL_AGENT_COMPLETE report format"
- "TaskOutput polling loop for monitoring"
- "check_and_spawn_dependents for wave progression"
issues-created: []
# Metrics
duration: 15min
completed: 2026-01-12
---
# Phase 10 Plan 02: Create Parallel Execution Workflow Summary
**Created execute-phase.md workflow with 9 steps for intelligent parallelization: dependency analysis, wave calculation, parallel agent spawning via Task tool, and orchestrator commit handling**
## Performance
- **Duration:** 15 min
- **Started:** 2026-01-12T18:51:58Z
- **Completed:** 2026-01-12T19:07:23Z
- **Tasks:** 3
- **Files modified:** 1 (created)
## Accomplishments
- Created 956-line execute-phase.md workflow with complete parallel execution logic
- Implemented dependency analysis with frontmatter + `<files>` extraction and topological sort
- Built wave-based execution model (Wave 1 parallel, Wave 2+ waits for dependencies)
- Added parallel agent spawning with Task tool run_in_background, XML prompt format
- Implemented monitor_parallel_completion with TaskOutput polling and dependent spawning
- Added orchestrator_commit with merge conflict detection failsafe
## Task Commits
Each task was committed atomically:
1. **Task 1: Create execute-phase.md workflow structure** - `af7720c` (feat)
2. **Task 2: Implement dependency analysis step** - `caf2810` (feat)
3. **Task 3: Implement parallel spawning and monitoring** - `511def7` (feat)
**Plan metadata:** TBD (docs: complete plan)
## Files Created/Modified
- `get-shit-done/workflows/execute-phase.md` - New workflow for parallel phase execution (956 lines)
## Decisions Made
- Agents don't commit - orchestrator collects all changes and commits per-plan in order
- Wave-based topological sort for dependency ordering
- Merge conflict detection as failsafe (dependency analysis should prevent, but edge cases exist)
- PARALLEL_AGENT_COMPLETE report format for structured agent output parsing
## Deviations from Plan
None - plan executed exactly as written.
## Issues Encountered
None
## Next Phase Readiness
- Ready for 10-03-PLAN.md (create execute-phase command + config)
- execute-phase.md workflow complete with all 9 steps
- Parallelization config schema defined in workflow (to be formalized in templates/config.json)
---
*Phase: 10-parallel-phase-execution*
*Completed: 2026-01-12*

98
.planning/phases/10-parallel-phase-execution/10-03-SUMMARY.md
View File

@@ -1,98 +0,0 @@
---
phase: 10-parallel-phase-execution
plan: 03
subsystem: commands
tags: [slash-command, parallelization, config, documentation]
requires:
- phase: 10-01
provides: renamed execute-plan workflow
- phase: 10-02
provides: execute-phase.md parallel workflow
provides:
- /gsd:execute-phase slash command
- parallelization config schema in config.json
- command documentation in README.md and help.md
affects: [users, config, workflow]
tech-stack:
added: []
patterns: [config-schema-extension, command-workflow-separation]
key-files:
created:
- commands/gsd/execute-phase.md
modified:
- get-shit-done/templates/config.json
- README.md
- commands/gsd/help.md
key-decisions:
- "Config schema uses parallelization section with plan_level/task_level for future extensibility"
- "Documentation explains when to use execute-plan vs execute-phase"
patterns-established:
- "Command files delegate to workflow files for execution logic"
issues-created: []
duration: 4min
completed: 2026-01-12
---
# Phase 10 Plan 03: Create Execute-Phase Command Summary
**New /gsd:execute-phase command with parallelization config and documentation for parallel "walk away" phase execution.**
## Performance
- **Duration:** 4 min
- **Started:** 2026-01-12T19:45:00Z
- **Completed:** 2026-01-12T19:49:00Z
- **Tasks:** 3
- **Files modified:** 4
## Accomplishments
- Created /gsd:execute-phase slash command that references execute-phase.md workflow
- Added parallelization configuration section to config.json template
- Updated README.md and help.md with new command documentation
## Task Commits
Each task was committed atomically:
1. **Task 1: Create execute-phase command** - `18a1fd1` (feat)
2. **Task 2: Add parallelization config to config.json template** - `8b8b5d6` (feat)
3. **Task 3: Update documentation** - `b372905` (docs)
## Files Created/Modified
- `commands/gsd/execute-phase.md` - New slash command for parallel phase execution
- `get-shit-done/templates/config.json` - Added parallelization section with 6 config options
- `README.md` - Added execute-phase to command table and explained when to use each
- `commands/gsd/help.md` - Added full usage entry with config options
## Decisions Made
- Config schema uses dedicated `parallelization` section with `plan_level`/`task_level` flags for future extensibility
- Documentation explicitly explains when to use `/gsd:execute-plan` vs `/gsd:execute-phase`
## Deviations from Plan
None - plan executed exactly as written.
## Issues Encountered
None
## Next Phase Readiness
- Execute-phase command available for parallel phase execution
- Ready for 10-04: agent-history schema extension
---
*Phase: 10-parallel-phase-execution*
*Completed: 2026-01-12*

109
.planning/phases/10-parallel-phase-execution/10-04-SUMMARY.md
View File

@@ -1,109 +0,0 @@
---
phase: 10-parallel-phase-execution
plan: 04
subsystem: infra
tags: [agent-tracking, parallel-execution, resume, schema]
# Dependency graph
requires:
- phase: 10-01
provides: execute-plan workflow renamed
- phase: 10-02
provides: execute-phase parallel workflow
- phase: 10-03
provides: execute-phase command and config
provides:
- Agent-history v1.2 schema with parallel tracking fields
- Parallel group format conventions
- Resume documentation for parallel batches
affects: [execute-phase, resume-task]
# Tech tracking
tech-stack:
added: []
patterns: [parallel-group-ids, dependency-tracking]
key-files:
created: []
modified: [get-shit-done/templates/agent-history.md]
key-decisions:
- "Version bump to 1.2 for parallel fields"
- "Parallel group format: phase-{phase}-batch-{timestamp}"
patterns-established:
- "Agent entries track execution_mode for sequential vs parallel"
- "depends_on links agents for dependency resolution"
issues-created: []
# Metrics
duration: 3min
completed: 2026-01-12
---
# Phase 10 Plan 4: Agent History Schema v1.2 Summary
**Extended agent-history.json schema to v1.2 with parallel execution tracking, dependency fields, and resume documentation**
## Performance
- **Duration:** 3 min
- **Started:** 2026-01-12T19:21:58Z
- **Completed:** 2026-01-12T19:24:30Z
- **Tasks:** 3
- **Files modified:** 1
## Accomplishments
- Updated schema version from 1.0 to 1.2
- Added 7 new fields for parallel execution tracking
- Added queued and failed status values
- Created parallel execution examples (plan-level, dependency)
- Documented parallel resume workflow and conflict detection
## Task Commits
1. **Task 1: Update schema version and add new fields** - `eaed882` (feat)
2. **Task 2: Add parallel execution examples** - `cc7e078` (feat)
3. **Task 3: Document resume support for parallel groups** - `3743d1c` (feat)
**Plan metadata:** (pending)
## Files Created/Modified
- `get-shit-done/templates/agent-history.md` - Extended with v1.2 schema, parallel fields, examples, resume docs
## Decisions Made
- Version bumped to 1.2 to indicate parallel execution capability
- Parallel group format standardized as `phase-{phase}-batch-{timestamp}`
- Resume documentation includes conflict detection for parallel scenarios
## Deviations from Plan
None - plan executed exactly as written.
## Issues Encountered
None
## Phase 10 Complete
All 4 plans executed:
- 10-01: Renamed execute-phase → execute-plan workflow
- 10-02: Created parallel execution workflow (execute-phase.md)
- 10-03: Created /gsd:execute-phase command + parallelization config
- 10-04: Extended agent-history schema to v1.2
Parallel phase execution now available via `/gsd:execute-phase`.
## Next Phase Readiness
- Phase 10 complete
- Milestone complete - all 10 phases finished
- Ready for `/gsd:complete-milestone`
---
*Phase: 10-parallel-phase-execution*
*Completed: 2026-01-12*

92
.planning/phases/11-parallel-aware-planning/11-01-SUMMARY.md
View File

@@ -1,92 +0,0 @@
---
phase: 11-parallel-aware-planning
plan: 01
subsystem: workflow
tags: [parallelization, frontmatter, planning, config]
# Dependency graph
requires:
- phase: 10-parallel-phase-execution
provides: parallel execution infrastructure, config schema
provides:
- Parallelization frontmatter fields in phase-prompt template
- Config reading step in plan-phase workflow
affects: [11-02, 11-03]
# Tech tracking
tech-stack:
added: []
patterns: [frontmatter-based dependency markers, config-driven planning behavior]
key-files:
created: []
modified: [get-shit-done/templates/phase-prompt.md, get-shit-done/workflows/plan-phase.md]
key-decisions:
- "Default parallelizable to false for safety"
- "files_exclusive used for conflict detection"
- "Config reading happens early, after load_project_state"
patterns-established:
- "Frontmatter parallelization markers: parallelizable, depends_on, files_exclusive"
- "Config-driven planning: read parallelization settings before structuring plans"
issues-created: []
# Metrics
duration: 4min
completed: 2026-01-12
---
# Phase 11 Plan 1: Parallelization Frontmatter Summary
**Added frontmatter fields (parallelizable, depends_on, files_exclusive) to plan template and config reading step to plan-phase workflow**
## Performance
- **Duration:** 4 min
- **Started:** 2026-01-12T20:30:00Z
- **Completed:** 2026-01-12T20:34:00Z
- **Tasks:** 2
- **Files modified:** 2
## Accomplishments
- Added three parallelization frontmatter fields to phase-prompt.md template
- Added frontmatter_guidance section explaining when to use each field
- Updated good_examples with parallel and sequential plan examples
- Added read_parallelization_config step to plan-phase.md workflow
## Task Commits
Each task was committed atomically:
1. **Task 1: Add parallelization frontmatter to phase-prompt.md** - `560ef34` (feat)
2. **Task 2: Add read_parallelization_config step to plan-phase.md** - `8e67241` (feat)
## Files Created/Modified
- `get-shit-done/templates/phase-prompt.md` - Added parallelizable, depends_on, files_exclusive fields with guidance
- `get-shit-done/workflows/plan-phase.md` - Added read_parallelization_config step after load_project_state
## Decisions Made
- Default parallelizable to false for safety (opt-in to parallel execution)
- files_exclusive field enables conflict detection by execute-phase
- Config reading happens early (priority="second") so planning behavior is informed throughout
## Deviations from Plan
None - plan executed exactly as written.
## Issues Encountered
None
## Next Step
Ready for 11-02-PLAN.md (Add parallel-aware step to plan-phase workflow)
---
*Phase: 11-parallel-aware-planning*
*Completed: 2026-01-12*

95
.planning/phases/11-parallel-aware-planning/11-02-SUMMARY.md
View File

@@ -1,95 +0,0 @@
---
phase: 11-parallel-aware-planning
plan: 02
subsystem: planning
tags: [parallelization, plan-phase, frontmatter, vertical-slices]
# Dependency graph
requires:
- phase: 11-01
provides: parallelization frontmatter fields in phase-prompt template
provides:
- parallelization_aware step in plan-phase.md
- parallelization frontmatter guidance in write_phase_prompt
- parallel-aware context section population rules
affects: [execute-phase, planning]
# Tech tracking
tech-stack:
added: []
patterns: [vertical-slice-planning, file-ownership-analysis]
key-files:
created: []
modified:
- get-shit-done/workflows/plan-phase.md
key-decisions:
- "Vertical slices preferred over workflow stages when parallelization enabled"
- "SUMMARY references only when genuinely needed (not reflexive)"
- "parallelizable: false if disabled in config"
patterns-established:
- "File ownership analysis before task grouping"
- "Dependency detection via SUMMARY references"
issues-created: []
# Metrics
duration: 2min
completed: 2026-01-12
---
# Phase 11 Plan 02: Parallel-Aware Planning Step Summary
**Added parallelization_aware step to plan-phase.md with file ownership analysis and vertical slice restructuring logic**
## Performance
- **Duration:** 2 min
- **Started:** 2026-01-12T20:12:58Z
- **Completed:** 2026-01-12T20:14:41Z
- **Tasks:** 2
- **Files modified:** 1
## Accomplishments
- Added parallelization_aware step with file ownership analysis and vertical slice logic
- Updated write_phase_prompt with parallelization frontmatter guidance
- Added parallel-aware context section population rules
## Task Commits
Each task was committed atomically:
1. **Task 1: Add parallelization_aware step** - `082c689` (feat)
2. **Task 2: Update write_phase_prompt step** - `31a77ae` (feat)
**Plan metadata:** (this commit)
## Files Created/Modified
- `get-shit-done/workflows/plan-phase.md` - Added parallelization_aware step and frontmatter guidance
## Decisions Made
- Vertical slice restructuring is conditional (only when beneficial)
- File ownership analysis flags forced dependencies
- SUMMARY references avoided when not genuinely needed
## Deviations from Plan
None - plan executed exactly as written.
## Issues Encountered
None
## Next Phase Readiness
- plan-phase.md now creates parallelization frontmatter
- Ready for 11-03 to consume frontmatter in execute-phase
---
*Phase: 11-parallel-aware-planning*
*Completed: 2026-01-12*

97
.planning/phases/11-parallel-aware-planning/11-03-SUMMARY.md
View File

@@ -1,97 +0,0 @@
---
phase: 11-parallel-aware-planning
plan: 03
subsystem: workflow
tags: [execute-phase, frontmatter, parallelization, backward-compatibility]
# Dependency graph
requires:
- phase: 11-02
provides: parallelization frontmatter fields in plan template
provides:
- execute-phase.md reads parallelizable, depends_on, files_exclusive from plan frontmatter
- frontmatter-aware categorization and wave calculation
- backward compatibility with old plans (inference fallback)
affects: [11-04, execute-phase users]
# Tech tracking
tech-stack:
added: []
patterns:
- "frontmatter-first with inference fallback"
- "explicit over implicit dependencies"
key-files:
created: []
modified:
- get-shit-done/workflows/execute-phase.md
key-decisions:
- "Use frontmatter when present, fall back to inference for backward compat"
- "parallelizable: false without depends_on forces Wave 2+"
- "Add [frontmatter] annotation in wave output for visibility"
patterns-established:
- "PLAN_HAS_FRONTMATTER tracking for conditional logic"
- "Frontmatter values populate same arrays as inference (unified downstream)"
issues-created: []
# Metrics
duration: 3min
completed: 2026-01-12
---
# Phase 11 Plan 03: Execute-Phase Frontmatter Support Summary
**execute-phase.md reads parallelization frontmatter (parallelizable, depends_on, files_exclusive) with backward compatibility**
## Performance
- **Duration:** 3 min
- **Started:** 2026-01-12T20:15:00Z
- **Completed:** 2026-01-12T20:18:42Z
- **Tasks:** 2
- **Files modified:** 1
## Accomplishments
- analyze_plan_dependencies now reads `parallelizable`, `depends_on`, `files_exclusive` from plan frontmatter
- Categorization and wave calculation use explicit frontmatter when present
- Old plans without new frontmatter fields continue working via inference fallback
## Task Commits
Each task was committed atomically:
1. **Task 1: Update analyze_plan_dependencies to read frontmatter fields** - `9fcc2a4` (feat)
2. **Task 2: Update categorization to use frontmatter parallelizable field** - `5c8e5df` (feat)
**Plan metadata:** (this commit) (docs: complete plan)
## Files Created/Modified
- `get-shit-done/workflows/execute-phase.md` - Added frontmatter reading, updated categorization, updated wave calculation
## Decisions Made
- Use frontmatter directly when present (no inference needed)
- Fall back to inference for backward compatibility with old plans
- `parallelizable: false` without explicit `depends_on` forces Wave 2+ (waits for all Wave 1 plans)
## Deviations from Plan
None - plan executed exactly as written.
## Issues Encountered
None
## Next Phase Readiness
- execute-phase.md now supports both old (inference-based) and new (frontmatter-based) plans
- Ready for 11-04 (documentation and examples)
---
*Phase: 11-parallel-aware-planning*
*Completed: 2026-01-12*

98
.planning/phases/11-parallel-aware-planning/11-04-SUMMARY.md
View File

@@ -1,98 +0,0 @@
---
phase: 11-parallel-aware-planning
plan: 04
subsystem: documentation
tags: [parallel-execution, planning, vertical-slices, file-ownership]
# Dependency graph
requires:
- phase: 11-01
provides: parallelization frontmatter fields in plan template
- phase: 11-02
provides: parallel-aware step in plan-phase workflow
- phase: 11-03
provides: execute-phase reads plan frontmatter
provides:
- Parallel-aware splitting strategy in scope-estimation.md
- Vertical slice vs sequential planning examples
- File ownership and SUMMARY reference guidance
affects: [plan-phase, scope-estimation, phase-prompt]
# Tech tracking
tech-stack:
added: []
patterns: [vertical-slice-planning, explicit-file-ownership, minimal-summary-references]
key-files:
created: []
modified:
- get-shit-done/references/scope-estimation.md
- get-shit-done/templates/phase-prompt.md
key-decisions:
- "Vertical slices maximize Wave 1 plans vs workflow-stage grouping"
- "File ownership explicit in frontmatter prevents merge conflicts"
- "SUMMARY references only when prior plan decisions affect current approach"
patterns-established:
- "Parallel-aware planning groups by vertical slice, not workflow stage"
- "files_exclusive in frontmatter declares file ownership"
- "Minimal SUMMARY references - only for genuine data dependencies"
issues-created: []
# Metrics
duration: 3min
completed: 2026-01-12
---
# Phase 11 Plan 04: Documentation Summary
**Parallel-aware splitting strategy and examples documenting vertical slice planning vs sequential workflow stages**
## Performance
- **Duration:** 3 min
- **Started:** 2026-01-12T19:45:00Z
- **Completed:** 2026-01-12T19:48:00Z
- **Tasks:** 2
- **Files modified:** 2
## Accomplishments
- Added `<parallel_aware_splitting>` section to scope-estimation.md with philosophy shift table, vertical slice examples, file ownership guidance, and SUMMARY reference minimization
- Added parallel and sequential plan examples to phase-prompt.md with frontmatter patterns and key differences
## Task Commits
Each task was committed atomically:
1. **Task 1: Add parallel-aware splitting strategy** - `a1f6e9f` (feat)
2. **Task 2: Add parallel vs sequential examples** - `67afce6` (feat)
## Files Created/Modified
- `get-shit-done/references/scope-estimation.md` - Added parallel_aware_splitting section with philosophy shift, vertical slice examples, when to restructure, file ownership, SUMMARY references
- `get-shit-done/templates/phase-prompt.md` - Added parallel-aware and sequential plan examples with frontmatter patterns
## Decisions Made
None - followed plan as specified
## Deviations from Plan
None - plan executed exactly as written.
## Issues Encountered
None
## Next Phase Readiness
- Phase 11: Parallel-Aware Planning complete
- All 4 plans finished (template, workflow, execute-phase, documentation)
- Milestone complete - ready for `/gsd:complete-milestone`
---
*Phase: 11-parallel-aware-planning*
*Completed: 2026-01-12*

87
.planning/phases/12-changelog-and-update-awareness/12-03-SUMMARY.md
View File

@@ -1,87 +0,0 @@
---
phase: 12-changelog-and-update-awareness
plan: 03
subsystem: infra
tags: [changelog, version, whats-new, update-awareness]
requires:
- phase: 12-01
provides: CHANGELOG.md file and installer changelog copy
provides:
- /gsd:whats-new command for version comparison
- VERSION file written during installation
- Help documentation for whats-new command
affects: []
tech-stack:
added: []
patterns:
- Remote changelog fetch via WebFetch for update awareness
- VERSION file for installed version tracking
key-files:
created:
- commands/gsd/whats-new.md
modified:
- bin/install.js
- commands/gsd/help.md
key-decisions:
- "VERSION file approach (simpler than parsing package.json)"
- "Remote fetch from GitHub raw for discovering unreleased changes"
- "Graceful fallback to local changelog when offline"
duration: 4min
completed: 2026-01-14
---
# Phase 12 Plan 03: whats-new Command Summary
**/gsd:whats-new command created for users to discover changes since their installed version, with VERSION file written during installation and help documentation updated**
## Performance
- **Duration:** 4 min
- **Started:** 2026-01-14T20:10:00Z
- **Completed:** 2026-01-14T20:14:00Z
- **Tasks:** 3
- **Files modified:** 3
## Accomplishments
- Created /gsd:whats-new command with remote changelog fetch
- Added VERSION file creation to installer
- Updated help.md with whats-new command documentation
## Task Commits
Each task was committed atomically:
1. **Task 1: Create whats-new.md command** - `1a55ac8` (feat)
2. **Task 2: Update install.js to write VERSION file** - `b281148` (feat)
3. **Task 3: Update help.md to include whats-new command** - `68f3cd1` (docs)
## Files Created/Modified
- `commands/gsd/whats-new.md` - Command for version comparison and changelog display
- `bin/install.js` - Added VERSION file creation during installation
- `commands/gsd/help.md` - Added whats-new to Utility Commands section
## Decisions Made
- VERSION file approach chosen over parsing package.json (simpler, more reliable)
- Remote fetch from GitHub enables discovering changes in versions not yet installed
- Graceful fallback to local changelog when offline or GitHub unavailable
## Deviations from Plan
None - plan executed exactly as written.
## Issues Encountered
None
## Next Phase Readiness
- /gsd:whats-new command ready for users to discover updates
- Phase 12 complete (all 3 plans finished)
- Ready for phase completion and milestone wrap-up
---
*Phase: 12-changelog-and-update-awareness*
*Completed: 2026-01-14*

249
.planning/phases/13-debug-agent/13-01-PLAN.md
View File

@@ -1,249 +0,0 @@
---
phase: 13-debug-agent
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- agents/gsd-debugger.md
autonomous: true
must_haves:
truths:
- "gsd-debugger agent contains all debugging expertise"
- "Agent can execute investigations autonomously"
- "Agent handles all checkpoint types (human-verify, decision, human-action)"
- "Agent follows scientific method for hypothesis testing"
artifacts:
- path: "agents/gsd-debugger.md"
provides: "Complete debugging expertise agent"
min_lines: 600
contains: "scientific method"
key_links:
- from: "agents/gsd-debugger.md"
to: "templates/DEBUG.md"
via: "references debug file structure"
pattern: "DEBUG\\.md"
---
<objective>
Create the gsd-debugger agent with all debugging expertise consolidated.
Purpose: Move ~2,400 lines of debugging methodology from orchestrator context into a dedicated agent file, following the gsd-executor/gsd-verifier pattern.
Output: `agents/gsd-debugger.md` containing complete debugging expertise.
</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 debugging content to consolidate:
@get-shit-done/workflows/debug.md
@get-shit-done/templates/debug-subagent-prompt.md
@get-shit-done/references/debugging/debugging-mindset.md
@get-shit-done/references/debugging/hypothesis-testing.md
@get-shit-done/references/debugging/investigation-techniques.md
@get-shit-done/references/debugging/verification-patterns.md
@get-shit-done/references/debugging/when-to-research.md
# Agent pattern reference:
@agents/gsd-executor.md
@agents/gsd-verifier.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Create gsd-debugger agent file</name>
<files>agents/gsd-debugger.md</files>
<action>
Create `agents/gsd-debugger.md` following the pattern from gsd-executor/gsd-verifier.
**Structure:**
```yaml
---
name: gsd-debugger
description: Investigates bugs using scientific method, manages debug sessions, handles checkpoints. Spawned by /gsd:debug orchestrator.
tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch
color: orange
---
```
**Sections to include (consolidate from references):**
1. `<role>` - What this agent does, when it's spawned, core responsibilities
2. `<philosophy>` - From debugging-mindset.md:
- User = reporter, Claude = investigator
- Meta-debugging awareness (debugging your own code)
- Foundation principles (observable facts, verify assumptions)
- Cognitive biases to avoid
3. `<hypothesis_testing>` - From hypothesis-testing.md:
- Falsifiability requirement
- How to form specific, testable hypotheses
- Experimental design framework
- Evidence quality (strong vs weak)
- Decision point criteria
- Recovery from wrong hypotheses
4. `<investigation_techniques>` - From investigation-techniques.md:
- Binary search / divide and conquer
- Rubber duck debugging
- Minimal reproduction
- Working backwards
- Differential debugging
- Observability first
- Comment out everything
- Git bisect
5. `<verification_patterns>` - From verification-patterns.md:
- What "verified" means (5 criteria)
- Reproduction verification
- Regression testing
- Environment verification
- Stability testing
- Verification checklist
6. `<research_vs_reasoning>` - From when-to-research.md:
- Research signals (error messages, library behavior, domain gaps)
- Reasoning signals (your code, have all info, logic errors)
- How to research (web search, Context7, GitHub issues)
- Balance between research and reasoning
7. `<debug_file_protocol>` - From debug.md workflow:
- File structure and sections
- Update rules (OVERWRITE vs APPEND)
- Status transitions
- Current Focus maintenance
- Evidence and Eliminated tracking
8. `<execution_flow>` - Adapted from debug.md workflow:
- check_active_session
- create_debug_file (if new session)
- symptom_gathering (if not prefilled)
- investigation_loop
- resume_from_file (if continuing)
- return_diagnosis (if find_root_cause_only)
- fix_and_verify (if find_and_fix)
- archive_session
9. `<checkpoint_behavior>` - From debug-subagent-prompt.md:
- When to return checkpoints
- Checkpoint return format
- Types: human-verify, human-action, decision
- What happens after (fresh continuation agent)
10. `<structured_returns>` - From debug-subagent-prompt.md:
- ROOT CAUSE FOUND format
- DEBUG COMPLETE format
- INVESTIGATION INCONCLUSIVE format
- CHECKPOINT REACHED format
11. `<modes>` - From debug.md workflow:
- symptoms_prefilled: true/false
- goal: find_root_cause_only / find_and_fix
- How each mode affects behavior
12. `<success_criteria>` - Checklist for complete debugging
**Key consolidation principles:**
- Compress verbose explanations into actionable rules
- Remove redundant examples (keep 1-2 best per concept)
- Maintain all key concepts and decision trees
- Target ~700-800 lines (vs ~2,400 original)
</action>
<verify>
File exists at agents/gsd-debugger.md with:
- YAML frontmatter with name, description, tools, color
- All 12 sections present
- At least 600 lines
- No markdown syntax errors
</verify>
<done>
gsd-debugger.md contains complete debugging expertise in consolidated form, following gsd-executor/gsd-verifier pattern
</done>
</task>
<task type="auto">
<name>Task 2: Verify agent completeness against source material</name>
<files>agents/gsd-debugger.md</files>
<action>
Review the created agent against source files to ensure no critical concepts were lost.
**Checklist:**
1. From debugging-mindset.md:
- [ ] Meta-debugging (debugging your own code)
- [ ] Cognitive biases (confirmation, anchoring, availability, sunk cost)
- [ ] Systematic investigation disciplines
- [ ] When to restart
2. From hypothesis-testing.md:
- [ ] Falsifiability principle
- [ ] Experimental design framework (7 steps)
- [ ] Multiple hypothesis comparison
- [ ] Recovery from wrong hypotheses
3. From investigation-techniques.md:
- [ ] All 7+ techniques documented
- [ ] Decision tree for technique selection
4. From verification-patterns.md:
- [ ] 5 criteria for verification
- [ ] All verification patterns
- [ ] Checklist template
5. From when-to-research.md:
- [ ] Research vs reasoning signals
- [ ] Research how-to guide
- [ ] Balance guidance
6. From debug.md workflow:
- [ ] All process steps
- [ ] Debug file update rules
- [ ] Mode handling
7. From debug-subagent-prompt.md:
- [ ] Return formats
- [ ] Checkpoint formats
- [ ] Continuation handling
If any concepts are missing, add them to the appropriate section.
</action>
<verify>
Review checklist shows all critical concepts present in gsd-debugger.md
</verify>
<done>
Agent contains all debugging expertise from source files
</done>
</task>
</tasks>
<verification>
Before declaring plan complete:
- [ ] agents/gsd-debugger.md exists with proper YAML frontmatter
- [ ] All 12 major sections present
- [ ] File is 600-900 lines (compressed but complete)
- [ ] No critical debugging concepts lost from source material
- [ ] Follows gsd-executor/gsd-verifier structural pattern
</verification>
<success_criteria>
- gsd-debugger.md created with complete debugging expertise
- Agent follows established pattern (frontmatter, role, process steps, success_criteria)
- Consolidation reduces ~2,400 lines to ~700-800 lines
- All critical debugging concepts preserved
</success_criteria>
<output>
After completion, create `.planning/phases/13-debug-agent/13-01-SUMMARY.md`
</output>

91
.planning/phases/13-debug-agent/13-01-SUMMARY.md
View File

@@ -1,91 +0,0 @@
---
phase: 13-debug-agent
plan: 01
subsystem: agents
tags: [debugging, scientific-method, hypothesis-testing, verification, subagent]
# Dependency graph
requires:
- phase: none
provides: standalone agent creation (no prior phases required)
provides:
- gsd-debugger agent with complete debugging expertise
- scientific method debugging methodology
- debug file protocol and state management
- checkpoint handling for user interaction
affects: [13-02-orchestrator, future-debugging-enhancements]
# Tech tracking
tech-stack:
added: []
patterns: [scientific-debugging-method, hypothesis-testing-framework, debug-file-persistence]
key-files:
created: [agents/gsd-debugger.md]
modified: []
key-decisions:
- "Consolidated ~2,400 lines to 990 lines (59% reduction)"
- "All 12 sections included: role, philosophy, hypothesis_testing, investigation_techniques, verification_patterns, research_vs_reasoning, debug_file_protocol, execution_flow, checkpoint_behavior, structured_returns, modes, success_criteria"
patterns-established:
- "Debugging agent pattern: complete methodology baked into agent file"
- "Scientific method as debugging foundation"
# Metrics
duration: 5min
completed: 2026-01-15
---
# Phase 13 Plan 01: Create gsd-debugger Agent Summary
**Complete debugging expertise consolidated into dedicated agent - 990 lines with scientific method, hypothesis testing, 7+ investigation techniques, verification patterns, and full checkpoint handling**
## Performance
- **Duration:** 5 min
- **Started:** 2026-01-15T22:12:48Z
- **Completed:** 2026-01-15T22:17:36Z
- **Tasks:** 2
- **Files modified:** 1
## Accomplishments
- Created gsd-debugger.md with all debugging expertise from ~2,400 source lines
- Consolidated into 990 lines (59% reduction) while preserving all critical concepts
- Structured as thin orchestrator pattern - agent has baked-in expertise
## Task Commits
Each task was committed atomically:
1. **Task 1: Create gsd-debugger agent file** - `7cefaf1` (feat)
2. **Task 2: Verify agent completeness** - No commit (verification task, no changes)
## Files Created/Modified
- `agents/gsd-debugger.md` - Complete debugging agent with 12 sections covering methodology, techniques, protocols
## Decisions Made
- 990 lines final (target was 700-800, acceptable given no concept loss)
- All 12 required sections included per plan specification
- Followed gsd-executor/gsd-verifier pattern for structure
## Deviations from Plan
None - plan executed exactly as written.
## Issues Encountered
None.
## User Setup Required
None - no external service configuration required.
## Next Phase Readiness
- gsd-debugger agent ready for integration with orchestrator
- Plan 13-02 will update /gsd:debug command to use thin orchestrator pattern
- Plan 13-03 will handle migration of deprecated files
---
*Phase: 13-debug-agent*
*Completed: 2026-01-15*

366
.planning/phases/13-debug-agent/13-02-PLAN.md
View File

@@ -1,366 +0,0 @@
---
phase: 13-debug-agent
plan: 02
type: execute
wave: 2
depends_on: ["13-01"]
files_modified:
- commands/gsd/debug.md
- get-shit-done/workflows/debug.md
- get-shit-done/templates/debug-subagent-prompt.md
autonomous: true
must_haves:
truths:
- "/gsd:debug spawns gsd-debugger agent"
- "Command is <150 lines (thin orchestrator)"
- "Workflow file removed or redirects to agent"
- "Debug subagent template simplified"
artifacts:
- path: "commands/gsd/debug.md"
provides: "Thin orchestrator for debugging"
min_lines: 80
contains: "gsd-debugger"
key_links:
- from: "commands/gsd/debug.md"
to: "agents/gsd-debugger.md"
via: "Task spawn with subagent_type"
pattern: "gsd-debugger"
---
<objective>
Refactor /gsd:debug command to thin orchestrator that spawns gsd-debugger agent.
Purpose: Reduce orchestrator context from ~2,400 lines to ~100-150 lines. Debugging expertise now lives in the agent.
Output: Streamlined command, deprecated workflow, simplified template.
</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
@.planning/phases/13-debug-agent/13-01-SUMMARY.md
# Current files to refactor:
@commands/gsd/debug.md
@get-shit-done/workflows/debug.md
@get-shit-done/templates/debug-subagent-prompt.md
# Agent created in previous plan:
@agents/gsd-debugger.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Refactor /gsd:debug to thin orchestrator</name>
<files>commands/gsd/debug.md</files>
<action>
Rewrite `commands/gsd/debug.md` as a thin orchestrator (~100-150 lines).
**Orchestrator responsibilities:**
1. Check for active debug sessions
2. Gather symptoms from user (if new issue)
3. Spawn gsd-debugger agent with context
4. Handle checkpoint returns
5. Spawn continuation agents as needed
**Structure:**
```yaml
---
name: gsd:debug
description: Systematic debugging with persistent state across context resets
argument-hint: [issue description]
allowed-tools:
- Read
- Bash
- Task
- AskUserQuestion
---
```
**Sections:**
```markdown
<objective>
Debug issues using scientific method with subagent isolation.
**Orchestrator role:** Gather symptoms, spawn gsd-debugger agent, handle checkpoints, spawn continuations.
**Why subagent:** Investigation burns context fast. Fresh 200k context per investigation. Main context stays lean.
</objective>
<context>
User's issue: $ARGUMENTS
Check for active sessions:
```bash
ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
```
</context>
<process>
## 1. Check Active Sessions
[Simplified from current - just list and route]
## 2. Gather Symptoms (if new issue)
[Keep current AskUserQuestion flow - this stays in main context]
## 3. Spawn gsd-debugger Agent
Fill prompt and spawn:
```markdown
<objective>
Investigate issue: {trigger}
</objective>
<symptoms>
expected: {expected}
actual: {actual}
errors: {errors}
reproduction: {reproduction}
timeline: {timeline}
</symptoms>
<mode>
symptoms_prefilled: true
goal: find_and_fix
</mode>
```
Task(
prompt=filled_prompt,
subagent_type="gsd-debugger",
description="Debug {slug}"
)
## 4. Handle Agent Return
[Keep current routing logic for ROOT CAUSE FOUND, CHECKPOINT REACHED, INCONCLUSIVE]
## 5. Spawn Continuation (After Checkpoint)
[Keep current continuation spawning, but simpler]
</process>
<success_criteria>
- [ ] Active sessions checked
- [ ] Symptoms gathered (if new)
- [ ] gsd-debugger spawned with context
- [ ] Checkpoints handled correctly
- [ ] Root cause confirmed before fixing
</success_criteria>
```
**Key changes:**
- Remove @~/.claude/get-shit-done/workflows/debug.md reference
- Remove @~/.claude/get-shit-done/references/debugging/*.md references
- Use `subagent_type="gsd-debugger"` instead of `subagent_type="general-purpose"`
- All debugging expertise is now IN the agent, not loaded by orchestrator
</action>
<verify>
File is <150 lines.
References gsd-debugger as subagent_type.
Does NOT reference workflows/debug.md or references/debugging/*.md.
</verify>
<done>
/gsd:debug is thin orchestrator that spawns gsd-debugger agent
</done>
</task>
<task type="auto">
<name>Task 2: Deprecate workflows/debug.md</name>
<files>get-shit-done/workflows/debug.md</files>
<action>
Replace `get-shit-done/workflows/debug.md` with a redirect notice.
**New content (~20 lines):**
```markdown
# Debug Workflow (DEPRECATED)
This workflow has been consolidated into the `gsd-debugger` agent.
**Location:** `agents/gsd-debugger.md`
**Reason:** The gsd-debugger agent contains all debugging expertise. Loading a separate workflow into orchestrator context was wasteful.
**Migration:**
- `/gsd:debug` now spawns `gsd-debugger` agent directly
- All debugging methodology lives in the agent file
- Templates remain at `get-shit-done/templates/DEBUG.md`
See `agents/gsd-debugger.md` for debugging expertise.
```
This preserves the file for git history but makes it clear the content moved.
</action>
<verify>
File exists with deprecation notice.
File is <30 lines.
Points to agents/gsd-debugger.md.
</verify>
<done>
workflows/debug.md deprecated with redirect to agent
</done>
</task>
<task type="auto">
<name>Task 3: Simplify debug-subagent-prompt.md template</name>
<files>get-shit-done/templates/debug-subagent-prompt.md</files>
<action>
Simplify `get-shit-done/templates/debug-subagent-prompt.md` since the agent now contains the expertise.
**Current state:** ~355 lines with embedded execution context, checkpoint formats, investigation protocol.
**New state:** ~60-80 lines - just placeholders and context injection.
**New structure:**
```markdown
# Debug Subagent Prompt Template
Template for spawning gsd-debugger agent. The agent contains all debugging expertise - this template provides problem context only.
---
## Template
```markdown
<objective>
Investigate issue: {issue_id}
**Summary:** {issue_summary}
</objective>
<symptoms>
expected: {expected}
actual: {actual}
errors: {errors}
reproduction: {reproduction}
timeline: {timeline}
</symptoms>
<mode>
symptoms_prefilled: {true_or_false}
goal: {find_root_cause_only | find_and_fix}
</mode>
<debug_file>
Create: .planning/debug/{slug}.md
</debug_file>
```
---
## Placeholders
| Placeholder | Source | Example |
|-------------|--------|---------|
| `{issue_id}` | Orchestrator-assigned | `auth-screen-dark` |
| `{issue_summary}` | User description | `Auth screen is too dark` |
| `{expected}` | From symptoms | `See logo clearly` |
| `{actual}` | From symptoms | `Screen is dark` |
| `{errors}` | From symptoms | `None in console` |
| `{reproduction}` | From symptoms | `Open /auth page` |
| `{timeline}` | From symptoms | `After recent deploy` |
| `{goal}` | Orchestrator sets | `find_and_fix` |
| `{slug}` | Generated | `auth-screen-dark` |
---
## Usage
**From /gsd:debug:**
```python
Task(
prompt=filled_template,
subagent_type="gsd-debugger",
description="Debug {slug}"
)
```
**From diagnose-issues (UAT):**
```python
Task(prompt=template, subagent_type="gsd-debugger", description="Debug UAT-001")
```
---
## Continuation
For checkpoints, spawn fresh agent with:
```markdown
<objective>
Continue debugging {slug}. Evidence is in the debug file.
</objective>
<prior_state>
Debug file: @.planning/debug/{slug}.md
</prior_state>
<checkpoint_response>
**Type:** {checkpoint_type}
**Response:** {user_response}
</checkpoint_response>
<mode>
goal: {goal}
</mode>
```
```
**Key changes:**
- Remove embedded execution_context references (agent has this)
- Remove checkpoint_behavior section (agent has this)
- Remove return_formats section (agent has this)
- Remove investigation_protocol section (agent has this)
- Keep only: template, placeholders, usage examples, continuation format
</action>
<verify>
File is <100 lines.
Contains template with placeholders.
Does NOT contain execution_context, checkpoint_behavior, or investigation_protocol sections.
References subagent_type="gsd-debugger".
</verify>
<done>
debug-subagent-prompt.md simplified to context injection only
</done>
</task>
</tasks>
<verification>
Before declaring plan complete:
- [ ] commands/gsd/debug.md is <150 lines
- [ ] commands/gsd/debug.md uses subagent_type="gsd-debugger"
- [ ] commands/gsd/debug.md does NOT load workflow or reference files
- [ ] workflows/debug.md is deprecated redirect (<30 lines)
- [ ] templates/debug-subagent-prompt.md is <100 lines
- [ ] All files reference the agent, not embedded expertise
</verification>
<success_criteria>
- /gsd:debug refactored to thin orchestrator
- Context usage reduced from ~2,400 to ~150 lines in orchestrator
- workflows/debug.md deprecated with pointer to agent
- debug-subagent-prompt.md simplified to context-only
</success_criteria>
<output>
After completion, create `.planning/phases/13-debug-agent/13-02-SUMMARY.md`
</output>

147
.planning/phases/13-debug-agent/13-03-PLAN.md
View File

@@ -1,147 +0,0 @@
---
phase: 13-debug-agent
plan: 03
type: execute
wave: 2
depends_on: ["13-01"]
files_modified:
- get-shit-done/references/debugging/debugging-mindset.md
- get-shit-done/references/debugging/hypothesis-testing.md
- get-shit-done/references/debugging/investigation-techniques.md
- get-shit-done/references/debugging/verification-patterns.md
- get-shit-done/references/debugging/when-to-research.md
autonomous: true
must_haves:
truths:
- "Reference files replaced with pointers to agent"
- "No duplicate content between references and agent"
artifacts:
- path: "get-shit-done/references/debugging/debugging-mindset.md"
provides: "Redirect to gsd-debugger agent"
contains: "gsd-debugger"
key_links:
- from: "get-shit-done/references/debugging/*.md"
to: "agents/gsd-debugger.md"
via: "redirect notice"
pattern: "agents/gsd-debugger"
---
<objective>
Deprecate debugging reference files with pointers to gsd-debugger agent.
Purpose: Eliminate duplicate content. Debugging expertise now lives solely in the agent file.
Output: 5 reference files reduced to redirect notices.
</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
@.planning/phases/13-debug-agent/13-01-SUMMARY.md
# Agent that now contains this content:
@agents/gsd-debugger.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Deprecate all debugging reference files</name>
<files>
get-shit-done/references/debugging/debugging-mindset.md
get-shit-done/references/debugging/hypothesis-testing.md
get-shit-done/references/debugging/investigation-techniques.md
get-shit-done/references/debugging/verification-patterns.md
get-shit-done/references/debugging/when-to-research.md
</files>
<action>
Replace each file with a redirect notice pointing to the agent.
**Template for each file (~15 lines):**
```markdown
# [Original Title] (DEPRECATED)
This reference has been consolidated into the `gsd-debugger` agent.
**Location:** `agents/gsd-debugger.md`
**Section:** `<[relevant_section_name]>`
**Reason:** Debugging expertise is now baked into the agent. Loading separate reference files into orchestrator context was wasteful (~95% context reduction).
See `agents/gsd-debugger.md` for the consolidated debugging methodology.
```
**Specific mappings:**
1. `debugging-mindset.md` → `<philosophy>` section
2. `hypothesis-testing.md` → `<hypothesis_testing>` section
3. `investigation-techniques.md` → `<investigation_techniques>` section
4. `verification-patterns.md` → `<verification_patterns>` section
5. `when-to-research.md` → `<research_vs_reasoning>` section
Each file should be ~15 lines with the redirect notice.
</action>
<verify>
All 5 files exist with redirect notices.
Each file is <20 lines.
Each file points to agents/gsd-debugger.md.
Each file specifies the relevant section in the agent.
</verify>
<done>
All debugging reference files deprecated with agent pointers
</done>
</task>
<task type="auto">
<name>Task 2: Update installer to include agents directory</name>
<files>bin/install.js</files>
<action>
Verify that `bin/install.js` copies the `agents/` directory during installation.
Check if agents/ is already included. If not, add it to the copy list.
**Expected behavior:**
- `agents/*.md` files copied to `~/.claude/agents/` (global) or `.claude/agents/` (local)
- Similar to how `commands/`, `get-shit-done/`, etc. are handled
**If already handled:** No changes needed, note in summary.
**If not handled:** Add agents directory to the copy list.
</action>
<verify>
Run: `node bin/install.js --local --dry-run` (if dry-run exists) or check install.js code
Confirm agents/ directory will be copied on install.
</verify>
<done>
Installer copies agents/ directory
</done>
</task>
</tasks>
<verification>
Before declaring plan complete:
- [ ] All 5 debugging reference files are <20 lines each
- [ ] All 5 files point to agents/gsd-debugger.md
- [ ] Each file specifies the section in the agent
- [ ] Installer handles agents/ directory
</verification>
<success_criteria>
- Debugging reference files deprecated
- No duplicate content between references and agent
- Installer copies agents directory
</success_criteria>
<output>
After completion, create `.planning/phases/13-debug-agent/13-03-SUMMARY.md`
</output>

207
.planning/phases/14-dedicated-researcher-agent/14-01-PLAN.md
View File

@@ -1,207 +0,0 @@
---
phase: 14-dedicated-researcher-agent
plan: 01
type: execute
wave: 1
depends_on: []
files_modified: [agents/gsd-researcher.md]
autonomous: true
must_haves:
truths:
- "gsd-researcher agent file exists with complete research methodology"
- "Agent covers all 4 research modes: ecosystem, feasibility, implementation, comparison"
- "Agent includes tool strategy (when to use Context7 vs WebSearch vs WebFetch)"
- "Agent includes source hierarchy and verification requirements"
artifacts:
- path: "agents/gsd-researcher.md"
provides: "Complete research expertise in single agent file"
min_lines: 600
contains: "research_modes"
key_links:
- from: "agents/gsd-researcher.md"
to: "research commands"
via: "spawned by orchestrator"
pattern: "spawned by.*research"
---
<objective>
Create gsd-researcher agent with all research expertise baked in.
Purpose: Consolidate ~1,200 lines of research methodology (research-phase.md workflow, research-project.md workflow, research-pitfalls.md, research.md template) into a single agent file following the thin orchestrator pattern established in Phase 13.
Output: `agents/gsd-researcher.md` (~800-1000 lines) containing complete research methodology that orchestrators can spawn.
</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
Source material to consolidate:
@get-shit-done/workflows/research-phase.md
@get-shit-done/workflows/research-project.md
@get-shit-done/references/research-pitfalls.md
@get-shit-done/templates/research.md
Pattern reference (Phase 13 agent):
@agents/gsd-debugger.md (first 150 lines for structure pattern)
</context>
<tasks>
<task type="auto">
<name>Task 1: Create gsd-researcher agent file</name>
<files>agents/gsd-researcher.md</files>
<action>
Create agents/gsd-researcher.md following the gsd-debugger pattern with these sections:
**Frontmatter:**
```yaml
---
name: gsd-researcher
description: Conducts comprehensive research using systematic methodology, source verification, and structured output. Spawned by /gsd:research-phase and /gsd:research-project orchestrators.
tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
color: cyan
---
```
**Core sections to include:**
1. `<role>` - Research agent identity, what spawns it, core responsibilities
2. `<philosophy>` - Research principles:
- Source hierarchy (Context7 > Official docs > WebSearch)
- Verification requirements (cross-reference, confidence levels)
- Treating Claude's training as hypothesis not fact
- Honest reporting of gaps and unknowns
3. `<research_modes>` - Four research modes with clear triggers:
- `ecosystem` — Survey landscape (tools, approaches, prior art)
- `feasibility` — Can we do X? What are blockers?
- `implementation` — How specifically to implement X?
- `comparison` — Compare options A vs B vs C
4. `<tool_strategy>` - When to use each research tool:
- Context7: First for any library/framework (authoritative, current)
- Official docs via WebFetch: When Context7 lacks coverage
- WebSearch: Ecosystem discovery, community patterns, pitfalls
- Verification protocol: WebSearch findings must be cross-verified
5. `<source_hierarchy>` - Source prioritization:
- HIGH confidence: Context7, official documentation
- MEDIUM confidence: WebSearch verified with official source
- LOW confidence: WebSearch only (flagged for validation)
6. `<verification_protocol>` - From research-pitfalls.md:
- All known pitfalls (config scope, deprecated features, tool variations, negative claims, etc.)
- Red flags to watch for
- Quick reference checklist
7. `<output_formats>` - Templates for research outputs:
- Phase research (RESEARCH.md structure)
- Project research (SUMMARY.md, STACK.md, etc.)
- Comparison matrices
- Feasibility assessments
8. `<execution_flow>` - How the agent operates:
- Receive research question/scope from orchestrator
- Identify research domains
- Execute research protocol
- Verify findings
- Write output file(s)
- Return structured result
9. `<structured_returns>` - Return format to orchestrator:
- Research complete with findings summary
- Confidence assessment
- Files created
- Open questions/gaps
10. `<success_criteria>` - When research is complete
Target: 800-1000 lines (consolidation from ~1,200 source lines with 20-30% reduction while preserving all critical concepts)
</action>
<verify>
Verify file exists and has required sections:
```bash
wc -l agents/gsd-researcher.md
grep -c "research_modes\|tool_strategy\|source_hierarchy\|verification_protocol\|output_formats" agents/gsd-researcher.md
```
Expected: 600-1000 lines, 5+ section matches
</verify>
<done>agents/gsd-researcher.md exists with all 10 required sections, 600-1000 lines</done>
</task>
<task type="auto">
<name>Task 2: Verify agent completeness</name>
<files>agents/gsd-researcher.md</files>
<action>
Read the created agent file and verify:
1. **All research modes documented:**
- ecosystem mode has clear scope and output
- feasibility mode has clear scope and output
- implementation mode has clear scope and output
- comparison mode has clear scope and output
2. **Tool strategy is actionable:**
- Context7 usage is explicit (resolve-library-id, query-docs)
- WebFetch patterns for official docs
- WebSearch query templates with {current_year}
- Verification requirements are clear
3. **Pitfalls are preserved:**
- All pitfalls from research-pitfalls.md included
- Red flags section present
- Quick reference checklist included
4. **Output formats match templates:**
- RESEARCH.md structure matches research.md template
- Project research structure matches research-project templates
5. **No critical concepts lost:**
- Source hierarchy preserved
- Confidence levels system preserved
- Cross-verification requirements preserved
If any gaps found, edit to add missing content.
</action>
<verify>
All 4 research modes documented:
```bash
grep -E "ecosystem|feasibility|implementation|comparison" agents/gsd-researcher.md | wc -l
```
Expected: 4+ matches (mode definitions plus references)
</verify>
<done>Agent contains all 4 research modes, complete tool strategy, all pitfalls, and output formats</done>
</task>
</tasks>
<verification>
Before declaring plan complete:
- [ ] agents/gsd-researcher.md exists
- [ ] File is 600-1000 lines (consolidated from ~1,200)
- [ ] All 10 required sections present
- [ ] 4 research modes defined with triggers and outputs
- [ ] Tool strategy section is actionable
- [ ] Verification protocol includes all pitfalls
- [ ] Output formats match existing templates
</verification>
<success_criteria>
- All tasks completed
- Agent file follows gsd-debugger pattern
- Research methodology consolidated without concept loss
- Ready for orchestrator integration (Plan 14-02)
</success_criteria>
<output>
After completion, create `.planning/phases/14-dedicated-researcher-agent/14-01-SUMMARY.md`
</output>

98
.planning/phases/14-dedicated-researcher-agent/14-01-SUMMARY.md
View File

@@ -1,98 +0,0 @@
---
phase: 14-dedicated-researcher-agent
plan: 01
subsystem: research-agent
tags: [research, agent, methodology, context7, verification]
dependency_graph:
requires: [13-01, 13-02] # Pattern from gsd-debugger agent
provides: [gsd-researcher-agent]
affects: [14-02, 14-03] # Orchestrator integration
tech_stack:
added: []
patterns: [thin-orchestrator, dedicated-agent, source-hierarchy]
key_files:
created:
- agents/gsd-researcher.md
modified: []
decisions:
- id: research-modes
choice: "4 explicit research modes"
rationale: "Ecosystem, feasibility, implementation, comparison cover all research needs with clear triggers"
- id: source-hierarchy
choice: "Context7 > Official > WebSearch with confidence levels"
rationale: "Prevents hallucination by enforcing current authoritative sources first"
- id: consolidation-ratio
choice: "902 lines from ~1,200 source (25% reduction)"
rationale: "Preserved all critical concepts while reducing redundancy"
metrics:
duration: 4 min
completed: 2026-01-15
---
# Phase 14 Plan 01: Create gsd-researcher Agent Summary
Consolidated ~1,200 lines of research methodology into 902-line gsd-researcher agent with 4 research modes, source hierarchy, and verification protocol.
## What Was Done
### Task 1: Create gsd-researcher agent file
Created `agents/gsd-researcher.md` following the gsd-debugger pattern established in Phase 13.
**Key sections included:**
- `<role>` - Research agent identity, spawned by research orchestrators
- `<philosophy>` - Claude's training as hypothesis, honest reporting, investigation vs confirmation
- `<research_modes>` - 4 modes: ecosystem, feasibility, implementation, comparison
- `<tool_strategy>` - Context7 first, official docs, WebSearch with verification
- `<source_hierarchy>` - HIGH/MEDIUM/LOW confidence levels with attribution requirements
- `<verification_protocol>` - 8 known pitfalls, red flags, quick reference checklist
- `<output_formats>` - Templates for RESEARCH.md, project research files, comparisons, feasibility
- `<execution_flow>` - 6-step research protocol
- `<structured_returns>` - Return format for orchestrator communication
- `<success_criteria>` - Completion and quality indicators
### Task 2: Verify agent completeness
Verified all required content present:
- All 4 research modes with clear scope and output focus
- Tool strategy with explicit Context7 resolve/query, WebFetch patterns, WebSearch templates
- All 8 pitfalls from research-pitfalls.md preserved
- Output formats match existing templates (research.md, research-project templates)
- Source hierarchy and confidence level system intact
## Decisions Made
| Decision | Choice | Rationale |
|----------|--------|-----------|
| Research modes | 4 explicit modes | Ecosystem, feasibility, implementation, comparison cover all needs with clear triggers |
| Source hierarchy | Context7 > Official > WebSearch | Prevents hallucination by enforcing current authoritative sources |
| Consolidation ratio | 902 lines from ~1,200 | 25% reduction while preserving all critical concepts |
## Deviations from Plan
None - plan executed exactly as written.
## Files Changed
| File | Action | Purpose |
|------|--------|---------|
| agents/gsd-researcher.md | Created | Complete research agent with methodology |
## Commit History
| Commit | Message |
|--------|---------|
| 2f8b551 | feat(14-01): create gsd-researcher agent with research methodology |
## Metrics
- **Duration:** 4 minutes
- **Lines consolidated:** ~1,200 source to 902 agent (25% reduction)
- **Sections:** 10 major sections covering all research methodology
## Next Phase Readiness
Ready for Plan 14-02 (thin orchestrator for research-phase command). The agent file provides complete research expertise that orchestrators can spawn.

233
.planning/phases/14-dedicated-researcher-agent/14-02-PLAN.md
View File

@@ -1,233 +0,0 @@
---
phase: 14-dedicated-researcher-agent
plan: 02
type: execute
wave: 2
depends_on: ["14-01"]
files_modified: [commands/gsd/research-phase.md, get-shit-done/workflows/research-phase.md, get-shit-done/templates/research-subagent-prompt.md]
autonomous: true
must_haves:
truths:
- "/gsd:research-phase spawns gsd-researcher agent"
- "Command is <200 lines (thin orchestrator)"
- "Workflow file has deprecation notice pointing to agent"
artifacts:
- path: "commands/gsd/research-phase.md"
provides: "Thin orchestrator that spawns researcher agent"
min_lines: 80
contains: "gsd-researcher"
- path: "get-shit-done/workflows/research-phase.md"
provides: "Deprecation notice"
contains: "DEPRECATED"
key_links:
- from: "commands/gsd/research-phase.md"
to: "agents/gsd-researcher.md"
via: "Task tool spawn"
pattern: "subagent_type.*gsd-researcher"
---
<objective>
Refactor /gsd:research-phase to thin orchestrator that spawns gsd-researcher agent.
Purpose: Apply the thin orchestrator pattern from Phase 13 — command handles argument parsing and context gathering, all research expertise lives in the agent. Reduces main context from ~450+ lines to ~150 lines.
Output: Refactored command (~150 lines), deprecated workflow, simplified subagent prompt template.
</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
Files to refactor:
@commands/gsd/research-phase.md
@get-shit-done/workflows/research-phase.md
Pattern reference (Phase 13 thin orchestrator):
@commands/gsd/debug.md
@.planning/phases/13-debug-agent/13-02-SUMMARY.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Refactor /gsd:research-phase to thin orchestrator</name>
<files>commands/gsd/research-phase.md</files>
<action>
Rewrite commands/gsd/research-phase.md as thin orchestrator following the debug.md pattern:
**Keep in orchestrator (low context cost, user interaction):**
- Argument parsing (phase number)
- Validation (phase exists in roadmap)
- Checking for existing RESEARCH.md
- Gathering phase context (roadmap description, requirements)
- Spawning the researcher agent with context
- Presenting results to user
- Offering next steps
**Delegate to agent (burns context during research):**
- All research methodology
- Tool strategy (Context7, WebSearch, etc.)
- Source verification
- Output generation
**Structure:**
```markdown
---
name: gsd:research-phase
description: Research how to implement a phase before planning
argument-hint: "[phase]"
allowed-tools:
- Read
- Bash
- Task
---
<objective>
Research how to implement a phase. Spawns gsd-researcher agent with phase context.
</objective>
<process>
1. Parse phase argument
2. Validate phase exists in roadmap
3. Check for existing RESEARCH.md
4. Gather phase context (description, requirements, constraints)
5. Spawn gsd-researcher agent with research question
6. Present results and offer next steps
</process>
<spawn_researcher>
Task(
prompt="Research implementation approach for phase {phase}...",
subagent_type="gsd-researcher"
)
</spawn_researcher>
```
Target: ~150 lines (down from ~84 lines command + ~450 lines workflow)
</action>
<verify>
```bash
wc -l commands/gsd/research-phase.md
grep -c "gsd-researcher\|Task\|subagent_type" commands/gsd/research-phase.md
```
Expected: <200 lines, 3+ spawning references
</verify>
<done>commands/gsd/research-phase.md is thin orchestrator <200 lines, spawns gsd-researcher</done>
</task>
<task type="auto">
<name>Task 2: Deprecate workflows/research-phase.md</name>
<files>get-shit-done/workflows/research-phase.md</files>
<action>
Replace workflows/research-phase.md with deprecation notice following Phase 13 pattern:
```markdown
# Research Phase Workflow
## ⚠️ DEPRECATED
**This workflow has been consolidated into the gsd-researcher agent.**
The research methodology, tool strategy, and verification protocols now live in:
- `agents/gsd-researcher.md`
The `/gsd:research-phase` command spawns the gsd-researcher agent directly.
**Migration:** No action needed — the command handles this automatically.
---
*Deprecated: 2026-01-XX*
*Replaced by: agents/gsd-researcher.md*
```
Keep file (don't delete) for git history traceability.
</action>
<verify>
```bash
head -20 get-shit-done/workflows/research-phase.md
```
Should show DEPRECATED notice
</verify>
<done>workflows/research-phase.md has deprecation notice pointing to agent</done>
</task>
<task type="auto">
<name>Task 3: Create research-subagent-prompt.md template</name>
<files>get-shit-done/templates/research-subagent-prompt.md</files>
<action>
Create a simple context-passing template for spawning the researcher agent:
```markdown
# Research Subagent Prompt Template
Template for spawning gsd-researcher agent from orchestrators.
## Template
```
<objective>
Research: {research_question}
Mode: {research_mode} (ecosystem | feasibility | implementation | comparison)
</objective>
<context>
Phase: {phase_number} - {phase_name}
Description: {phase_description}
Requirements:
{phase_requirements}
Constraints:
{constraints_from_state}
</context>
<output>
Write research findings to: {output_path}
Use RESEARCH.md template structure for phase research.
</output>
```
**Note:** Research methodology, tool strategy, and verification protocols are baked into the gsd-researcher agent. This template only passes context.
```
Target: ~60 lines (context-only, agent has expertise)
</action>
<verify>
```bash
wc -l get-shit-done/templates/research-subagent-prompt.md
```
Expected: <100 lines
</verify>
<done>research-subagent-prompt.md template created, context-only (~60 lines)</done>
</task>
</tasks>
<verification>
Before declaring plan complete:
- [ ] commands/gsd/research-phase.md is <200 lines
- [ ] Command spawns gsd-researcher agent via Task tool
- [ ] workflows/research-phase.md has deprecation notice
- [ ] research-subagent-prompt.md template exists
- [ ] Template is context-only (no methodology duplication)
</verification>
<success_criteria>
- All tasks completed
- Thin orchestrator pattern applied
- Main context reduced from ~530 lines to ~150 lines
- Workflow deprecated with clear redirect
</success_criteria>
<output>
After completion, create `.planning/phases/14-dedicated-researcher-agent/14-02-SUMMARY.md`
</output>

233
.planning/phases/14-dedicated-researcher-agent/14-03-PLAN.md
View File

@@ -1,233 +0,0 @@
---
phase: 14-dedicated-researcher-agent
plan: 03
type: execute
wave: 2
depends_on: ["14-01"]
files_modified: [commands/gsd/research-project.md, get-shit-done/workflows/research-project.md]
autonomous: true
must_haves:
truths:
- "/gsd:research-project spawns parallel gsd-researcher agents"
- "Command is <200 lines (thin orchestrator)"
- "Workflow file has deprecation notice pointing to agent"
- "4 parallel agents for stack, features, architecture, pitfalls"
artifacts:
- path: "commands/gsd/research-project.md"
provides: "Thin orchestrator that spawns parallel researcher agents"
min_lines: 100
contains: "gsd-researcher"
- path: "get-shit-done/workflows/research-project.md"
provides: "Deprecation notice"
contains: "DEPRECATED"
key_links:
- from: "commands/gsd/research-project.md"
to: "agents/gsd-researcher.md"
via: "Parallel Task tool spawns"
pattern: "subagent_type.*gsd-researcher"
---
<objective>
Refactor /gsd:research-project to spawn parallel gsd-researcher agents.
Purpose: Apply thin orchestrator pattern — command handles project analysis and spawns 4 parallel researcher agents (stack, features, architecture, pitfalls). Each agent writes its own file, orchestrator synthesizes SUMMARY.md.
Output: Refactored command (~180 lines), deprecated workflow.
</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
Files to refactor:
@commands/gsd/research-project.md
@get-shit-done/workflows/research-project.md
Pattern reference:
@commands/gsd/debug.md (thin orchestrator pattern)
@.planning/phases/13-debug-agent/13-02-SUMMARY.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Refactor /gsd:research-project to thin orchestrator</name>
<files>commands/gsd/research-project.md</files>
<action>
Rewrite commands/gsd/research-project.md as thin orchestrator:
**Keep in orchestrator:**
- PROJECT.md validation
- Domain analysis from PROJECT.md
- Research question generation
- Spawning 4 parallel researcher agents
- Waiting for all agents to complete
- Synthesizing SUMMARY.md from agent outputs
- Offering next steps
**Delegate to agents (each writes its own file):**
- Stack research → .planning/research/STACK.md
- Features research → .planning/research/FEATURES.md
- Architecture research → .planning/research/ARCHITECTURE.md
- Pitfalls research → .planning/research/PITFALLS.md
**Structure:**
```markdown
---
name: gsd:research-project
description: Research domain ecosystem before creating roadmap
allowed-tools:
- Read
- Write
- Bash
- Task
---
<objective>
Research domain ecosystem. Spawns 4 parallel gsd-researcher agents for comprehensive coverage.
</objective>
<process>
1. Validate PROJECT.md exists
2. Analyze project to determine domain
3. Generate research questions (stack, features, architecture, pitfalls)
4. Create .planning/research/ directory
5. Spawn 4 gsd-researcher agents in parallel (each writes its own file)
6. Wait for all to complete
7. Synthesize SUMMARY.md from agent outputs
8. Commit research
9. Offer next steps
</process>
<spawn_agents>
Spawn all 4 in parallel with single message containing multiple Task calls:
Task(prompt="Research stack for {domain}...", subagent_type="gsd-researcher")
Task(prompt="Research features for {domain}...", subagent_type="gsd-researcher")
Task(prompt="Research architecture for {domain}...", subagent_type="gsd-researcher")
Task(prompt="Research pitfalls for {domain}...", subagent_type="gsd-researcher")
</spawn_agents>
```
Target: ~180 lines (down from ~138 lines command + ~430 lines workflow)
</action>
<verify>
```bash
wc -l commands/gsd/research-project.md
grep -c "gsd-researcher\|Task\|parallel" commands/gsd/research-project.md
```
Expected: <200 lines, 4+ spawning references
</verify>
<done>commands/gsd/research-project.md is thin orchestrator <200 lines, spawns 4 parallel agents</done>
</task>
<task type="auto">
<name>Task 2: Deprecate workflows/research-project.md</name>
<files>get-shit-done/workflows/research-project.md</files>
<action>
Replace workflows/research-project.md with deprecation notice:
```markdown
# Research Project Workflow
## ⚠️ DEPRECATED
**This workflow has been consolidated into the gsd-researcher agent.**
The research methodology for project research now lives in:
- `agents/gsd-researcher.md`
The `/gsd:research-project` command spawns 4 parallel gsd-researcher agents:
- Stack agent → .planning/research/STACK.md
- Features agent → .planning/research/FEATURES.md
- Architecture agent → .planning/research/ARCHITECTURE.md
- Pitfalls agent → .planning/research/PITFALLS.md
The orchestrator synthesizes SUMMARY.md after all agents complete.
**Migration:** No action needed — the command handles this automatically.
---
*Deprecated: 2026-01-XX*
*Replaced by: agents/gsd-researcher.md*
```
Keep file for git history.
</action>
<verify>
```bash
head -25 get-shit-done/workflows/research-project.md
```
Should show DEPRECATED notice
</verify>
<done>workflows/research-project.md has deprecation notice pointing to agent</done>
</task>
<task type="auto">
<name>Task 3: Deprecate research-pitfalls.md reference</name>
<files>get-shit-done/references/research-pitfalls.md</files>
<action>
Add deprecation notice to top of research-pitfalls.md (keeping content for reference):
```markdown
# Research Pitfalls Reference
## ⚠️ DEPRECATED
**This reference has been consolidated into the gsd-researcher agent.**
The verification protocols and pitfall patterns now live in:
- `agents/gsd-researcher.md` (section: `<verification_protocol>`)
The content below is preserved for reference but is no longer the primary source.
---
*Deprecated: 2026-01-XX*
*Replaced by: agents/gsd-researcher.md*
---
[existing content follows]
```
Keep full content below the notice for reference.
</action>
<verify>
```bash
head -20 get-shit-done/references/research-pitfalls.md
```
Should show DEPRECATED notice with pointer to agent
</verify>
<done>research-pitfalls.md has deprecation notice pointing to agent</done>
</task>
</tasks>
<verification>
Before declaring plan complete:
- [ ] commands/gsd/research-project.md is <200 lines
- [ ] Command spawns 4 parallel gsd-researcher agents
- [ ] workflows/research-project.md has deprecation notice
- [ ] research-pitfalls.md has deprecation notice
- [ ] All deprecation notices point to agents/gsd-researcher.md
</verification>
<success_criteria>
- All tasks completed
- Parallel agent spawning pattern documented
- Main context reduced significantly
- All deprecated files point to new agent location
</success_criteria>
<output>
After completion, create `.planning/phases/14-dedicated-researcher-agent/14-03-SUMMARY.md`
</output>

100
.planning/phases/14-dedicated-researcher-agent/14-03-SUMMARY.md
View File

@@ -1,100 +0,0 @@
---
phase: 14-dedicated-researcher-agent
plan: 03
subsystem: commands
tags: [research, orchestrator, parallel-agents, thin-orchestrator]
# Dependency graph
requires:
- phase: 14-01
provides: gsd-researcher agent with complete research expertise
provides:
- Parallel-spawning /gsd:research-project command (137 lines)
- Deprecated workflow with redirect to agent
- Deprecated research-pitfalls reference with redirect to agent
affects: [research-users, project-research-workflow]
# Tech tracking
tech-stack:
added: []
patterns: [parallel-agent-spawning, thin-orchestrator-pattern]
key-files:
created: []
modified: [commands/gsd/research-project.md, get-shit-done/workflows/research-project.md, get-shit-done/references/research-pitfalls.md]
key-decisions:
- "Orchestrator spawns 4 parallel agents (stack, features, architecture, pitfalls)"
- "Each agent writes its own file, orchestrator synthesizes SUMMARY.md"
- "Workflow and reference files kept with deprecation notices for git history"
patterns-established:
- "Parallel agent spawning: single orchestrator spawns multiple specialized agents"
- "Agent writes output directly: no orchestrator intermediary for file creation"
# Metrics
duration: 3min
completed: 2026-01-15
---
# Phase 14 Plan 03: Research Project Parallel Orchestrator Summary
**Refactored /gsd:research-project to spawn 4 parallel gsd-researcher agents - context reduction from ~565 lines to 137 lines in main thread**
## Performance
- **Duration:** 3 min
- **Started:** 2026-01-15T23:01:53Z
- **Completed:** 2026-01-15T23:05:04Z
- **Tasks:** 3
- **Files modified:** 3
## Accomplishments
- Rewrote /gsd:research-project to spawn 4 parallel gsd-researcher agents
- Each agent writes its own file (STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md)
- Orchestrator synthesizes SUMMARY.md after all agents complete
- Deprecated workflows/research-project.md with redirect to agent
- Deprecated references/research-pitfalls.md with redirect to agent
## Task Commits
Each task was committed atomically:
1. **Task 1: Refactor /gsd:research-project to thin orchestrator** - `982faf1` (refactor)
2. **Task 2: Deprecate workflows/research-project.md** - `fc67d2c` (docs)
3. **Task 3: Deprecate research-pitfalls.md reference** - `ccac62d` (docs)
## Files Modified
- `commands/gsd/research-project.md` - Thin orchestrator spawning 4 parallel agents (137 lines)
- `get-shit-done/workflows/research-project.md` - Deprecation notice pointing to agent (23 lines)
- `get-shit-done/references/research-pitfalls.md` - Deprecation notice with preserved content
## Decisions Made
- Parallel agent spawning for maximum research throughput
- Each agent writes directly to .planning/research/ (no orchestrator bottleneck)
- Orchestrator handles project analysis, question generation, and final synthesis
- Content preserved in reference file for historical reference
## Deviations from Plan
None - plan executed exactly as written.
## Issues Encountered
None.
## User Setup Required
None - no external service configuration required.
## Next Phase Readiness
- Phase 14 (Researcher Agent) complete
- All three plans executed:
- 14-01: Created gsd-researcher agent (902 lines)
- 14-02: Integrated with /gsd:research-phase
- 14-03: Integrated with /gsd:research-project (parallel spawning)
- Project complete - all 33 plans executed
---
*Phase: 14-dedicated-researcher-agent*
*Completed: 2026-01-15*

97
.planning/phases/14-dedicated-researcher-agent/14-VERIFICATION.md
View File

@@ -1,97 +0,0 @@
---
phase: 14-dedicated-researcher-agent
verified: 2026-01-15T23:30:00Z
status: passed
score: 7/7 must-haves verified
---
# Phase 14: Dedicated Researcher Agent Verification Report
**Phase Goal:** Create gsd-researcher agent with research methodology baked in, refactor research commands to spawn specialized agents
**Verified:** 2026-01-15
**Status:** PASSED
**Re-verification:** No - initial verification
## Goal Achievement
### Observable Truths
| # | Truth | Status | Evidence |
|---|-------|--------|----------|
| 1 | gsd-researcher agent file exists with complete research methodology | VERIFIED | `agents/gsd-researcher.md` exists (902 lines) |
| 2 | Agent covers all 4 research modes | VERIFIED | `<research_modes>` section lines 71-157: ecosystem, feasibility, implementation, comparison |
| 3 | Agent includes tool strategy | VERIFIED | `<tool_strategy>` section lines 159-268: Context7, WebFetch, WebSearch with verification protocol |
| 4 | Agent includes source hierarchy and verification | VERIFIED | `<source_hierarchy>` lines 270-325, `<verification_protocol>` lines 327-432 |
| 5 | /gsd:research-phase spawns gsd-researcher agent | VERIFIED | `commands/gsd/research-phase.md` lines 84, 117: `subagent_type="gsd-researcher"` |
| 6 | /gsd:research-project spawns 4 parallel agents | VERIFIED | `commands/gsd/research-project.md` lines 70-84: 4 Task calls with `subagent_type="gsd-researcher"` |
| 7 | Workflows deprecated with redirect to agent | VERIFIED | Both workflow files contain "DEPRECATED" notice pointing to `agents/gsd-researcher.md` |
**Score:** 7/7 truths verified
### Required Artifacts
| Artifact | Expected | Status | Details |
|----------|----------|--------|---------|
| `agents/gsd-researcher.md` | 600+ lines, contains research_modes | VERIFIED | 902 lines, all 10 sections present |
| `commands/gsd/research-phase.md` | <200 lines, spawns agent | VERIFIED | 130 lines, references gsd-researcher 5 times |
| `commands/gsd/research-project.md` | <200 lines, spawns 4 parallel | VERIFIED | 137 lines, 4 Task spawns with gsd-researcher |
| `get-shit-done/workflows/research-phase.md` | DEPRECATED notice | VERIFIED | 17 lines, deprecation notice with redirect |
| `get-shit-done/workflows/research-project.md` | DEPRECATED notice | VERIFIED | 23 lines, deprecation notice with redirect |
| `get-shit-done/templates/research-subagent-prompt.md` | Context-only template | VERIFIED | 92 lines, context-passing template |
| `get-shit-done/references/research-pitfalls.md` | DEPRECATED notice | VERIFIED | Deprecation header, original content preserved |
### Key Link Verification
| From | To | Via | Status | Details |
|------|-----|-----|--------|---------|
| `research-phase.md` | `gsd-researcher.md` | Task spawn | WIRED | Line 84: `subagent_type="gsd-researcher"` |
| `research-project.md` | `gsd-researcher.md` | 4x Task spawn | WIRED | Lines 72, 76, 80, 84: parallel spawns |
| `research-subagent-prompt.md` | `gsd-researcher.md` | Template reference | WIRED | Template notes agent contains methodology |
### Requirements Coverage
Phase 14 requirements from ROADMAP:
- **Create gsd-researcher agent**: SATISFIED - 902 line agent with complete methodology
- **Refactor /gsd:research-phase**: SATISFIED - 130 line thin orchestrator
- **Refactor /gsd:research-project**: SATISFIED - 137 line parallel orchestrator
### Anti-Patterns Found
| File | Line | Pattern | Severity | Impact |
|------|------|---------|----------|--------|
| None | - | - | - | - |
No TODO, FIXME, placeholder, or stub patterns found in any phase artifacts.
### Human Verification Required
None - all phase artifacts are documentation/prompts that can be verified structurally.
### Verification Summary
Phase 14 goal fully achieved:
1. **gsd-researcher agent** (902 lines) consolidates ~1,200 lines of research methodology from:
- research-phase.md workflow (~450 lines)
- research-project.md workflow (~430 lines)
- research-pitfalls.md reference (~160 lines)
- research.md template (~160 lines)
2. **Thin orchestrator pattern** applied to both research commands:
- `/gsd:research-phase`: 130 lines (down from ~530 combined)
- `/gsd:research-project`: 137 lines with parallel agent spawning
3. **Deprecation notices** added to all superseded files with clear redirect to new agent location
4. **All 4 research modes** fully documented: ecosystem, feasibility, implementation, comparison
5. **Tool strategy** explicit: Context7 > Official docs > WebSearch with verification protocol
6. **Source hierarchy** with confidence levels: HIGH/MEDIUM/LOW
7. **Verification protocol** includes all 8 pitfalls from original reference
---
*Verified: 2026-01-15*
*Verifier: Claude (gsd-verifier)*

197
.planning/phases/14-researcher-agent/14-01-PLAN.md
View File

@@ -1,197 +0,0 @@
---
phase: 14-researcher-agent
plan: 01
type: execute
wave: 1
depends_on: []
files_modified: [agents/gsd-researcher.md]
autonomous: true
must_haves:
truths:
- "Agent has research methodology for Context7, WebSearch, WebFetch"
- "Agent understands source hierarchy (Context7 > official docs > WebSearch)"
- "Agent can operate in multiple research modes (ecosystem, feasibility, implementation, comparison)"
- "Agent produces structured RESEARCH.md output"
artifacts:
- path: "agents/gsd-researcher.md"
provides: "Complete research expertise"
min_lines: 700
contains: "<research_methodology>"
key_links:
- from: "gsd-researcher.md"
to: "RESEARCH.md output"
via: "research_protocol and output_formats sections"
pattern: "RESEARCH\\.md"
---
<objective>
Create gsd-researcher agent with complete research methodology baked in.
Purpose: Consolidate ~1,600 lines of research expertise (workflows, references, templates) into a dedicated agent that can be spawned by research commands.
Output: `agents/gsd-researcher.md` with research methodology, source hierarchy, verification patterns, and multiple research modes.
</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
# Source material to consolidate:
@get-shit-done/workflows/research-phase.md
@get-shit-done/workflows/research-project.md
@get-shit-done/references/research-pitfalls.md
@get-shit-done/templates/research.md
# Pattern to follow:
@agents/gsd-debugger.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Create gsd-researcher agent</name>
<files>agents/gsd-researcher.md</files>
<action>
Create `agents/gsd-researcher.md` following the gsd-debugger pattern. Consolidate research expertise from source files (~1,600 lines) into ~700-900 lines.
**Agent structure (required sections):**
1. **Frontmatter:**
- name: gsd-researcher
- description: Researches domains using Context7, WebSearch, and official docs. Spawned by /gsd:research-phase and /gsd:research-project.
- tools: Read, Write, Bash, Glob, Grep, WebFetch, WebSearch, mcp__context7__*
2. **role:** What the agent does, when spawned, core responsibilities
3. **philosophy:**
- Research vs intuition (Claude's training is 6-18 months stale)
- Source hierarchy (Context7 > official docs > WebSearch)
- Evidence quality (verified vs unverified)
- Confidence levels (HIGH/MEDIUM/LOW)
4. **research_methodology:**
- Context7 protocol (resolve-library-id → query-docs)
- WebFetch protocol (official docs, exact URLs)
- WebSearch protocol (discovery queries with {current_year})
- Cross-verification (mandatory for WebSearch findings)
5. **research_modes:**
- **ecosystem:** Survey landscape (tools, approaches, prior art, standard stack)
- **feasibility:** Can we do X? What are blockers? What's the effort?
- **implementation:** How specifically to implement X? Patterns, libraries, code examples
- **comparison:** Compare options A vs B vs C with tradeoffs
6. **verification_patterns:**
- Pitfalls checklist (from research-pitfalls.md)
- Source quality assessment
- Negative claim verification ("X is not possible" needs official source)
- Enumeration completeness (all known options investigated)
7. **output_formats:**
- RESEARCH.md structure (from templates/research.md - condensed)
- STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md (for research-project)
- Confidence markup and source citations
8. **execution_flow:**
- Mode detection from prompt
- Context loading (phase description, requirements, PROJECT.md)
- Domain identification
- Research execution (by mode)
- Quality check (pitfalls checklist)
- Output creation
- Structured return
9. **structured_returns:**
- RESEARCH COMPLETE (standard success)
- RESEARCH INCONCLUSIVE (gaps documented)
10. **success_criteria:** Checklist for complete research
**Content consolidation targets:**
- research-phase.md (~457 lines) → extract methodology, source protocol, output structure
- research-project.md (~426 lines) → extract parallel research patterns, project domain analysis
- research-pitfalls.md (~215 lines) → extract verification checklist, red flags
- templates/research.md (~529 lines) → extract output structure (condensed)
**Target length:** 700-900 lines (from ~1,600 source lines = ~50% reduction)
The agent should be self-contained - spawning it with mode and context should produce quality research output.
</action>
<verify>
- File exists at agents/gsd-researcher.md
- Contains all 10 required sections
- Line count is 700-900 lines
- References Context7 MCP tools
- Includes research modes (ecosystem, feasibility, implementation, comparison)
- Includes pitfalls checklist
</verify>
<done>gsd-researcher.md created with complete research methodology, all modes, verification patterns</done>
</task>
<task type="auto">
<name>Task 2: Verify agent completeness</name>
<files>agents/gsd-researcher.md</files>
<action>
Read the created agent file and verify:
1. **All sections present:**
- [ ] Frontmatter with tools
- [ ] role section
- [ ] philosophy section
- [ ] research_methodology section
- [ ] research_modes section (all 4 modes)
- [ ] verification_patterns section
- [ ] output_formats section
- [ ] execution_flow section
- [ ] structured_returns section
- [ ] success_criteria section
2. **Key content verified:**
- [ ] Context7 protocol documented (resolve-library-id → query-docs)
- [ ] Source hierarchy documented (Context7 > official > WebSearch)
- [ ] All 4 research modes documented (ecosystem, feasibility, implementation, comparison)
- [ ] Pitfalls checklist included
- [ ] RESEARCH.md output structure defined
- [ ] Confidence levels explained
3. **No orphaned concepts:**
- [ ] Nothing references external workflow files for core methodology
- [ ] Agent is self-contained
If any gaps found, update the agent file.
</action>
<verify>All verification points checked, agent is complete and self-contained</verify>
<done>Agent verified complete with all methodology, modes, and verification patterns</done>
</task>
</tasks>
<verification>
Before declaring plan complete:
- [ ] agents/gsd-researcher.md exists
- [ ] File is 700-900 lines (consolidated from ~1,600)
- [ ] All 10 required sections present
- [ ] All 4 research modes documented
- [ ] Context7 protocol included
- [ ] Pitfalls checklist integrated
- [ ] Agent follows gsd-debugger structural pattern
</verification>
<success_criteria>
- gsd-researcher.md created with complete research methodology
- All source expertise consolidated (research-phase, research-project, research-pitfalls, templates/research)
- Agent is self-contained (no required external methodology files)
- Follows established agent pattern (like gsd-debugger)
- Ready for command integration in 14-02 and 14-03
</success_criteria>
<output>
After completion, create `.planning/phases/14-researcher-agent/14-01-SUMMARY.md`
</output>

205
.planning/phases/14-researcher-agent/14-02-PLAN.md
View File

@@ -1,205 +0,0 @@
---
phase: 14-researcher-agent
plan: 02
type: execute
wave: 2
depends_on: ["14-01"]
files_modified: [commands/gsd/research-phase.md, get-shit-done/templates/research-subagent-prompt.md]
autonomous: true
must_haves:
truths:
- "/gsd:research-phase spawns gsd-researcher agent"
- "Agent receives phase context and produces RESEARCH.md"
- "Command is thin orchestrator (<200 lines)"
artifacts:
- path: "commands/gsd/research-phase.md"
provides: "Thin orchestrator for phase research"
min_lines: 80
contains: "gsd-researcher"
- path: "get-shit-done/templates/research-subagent-prompt.md"
provides: "Subagent prompt template"
min_lines: 30
key_links:
- from: "research-phase.md command"
to: "gsd-researcher agent"
via: "Task tool spawn"
pattern: "subagent_type.*gsd-researcher"
---
<objective>
Refactor /gsd:research-phase to thin orchestrator that spawns gsd-researcher agent.
Purpose: Reduce main context load from ~500+ lines (command + workflow) to ~150 lines. Agent carries the research expertise.
Output: Thin orchestrator command + subagent prompt template.
</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 implementation to refactor:
@commands/gsd/research-phase.md
@get-shit-done/workflows/research-phase.md
# Agent we're delegating to:
@agents/gsd-researcher.md
# Pattern to follow (from Phase 13):
@commands/gsd/debug.md
@get-shit-done/templates/debug-subagent-prompt.md
# Prior summary for context:
@.planning/phases/14-researcher-agent/14-01-SUMMARY.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Create research-subagent-prompt template</name>
<files>get-shit-done/templates/research-subagent-prompt.md</files>
<action>
Create `get-shit-done/templates/research-subagent-prompt.md` following the debug-subagent-prompt.md pattern.
**Template structure:**
```markdown
# Research Agent Prompt
You are a GSD researcher spawned by the orchestrator.
**Your agent expertise:**
@~/.claude/agents/gsd-researcher.md
**Research context:**
{PHASE_CONTEXT}
**Research mode:** {MODE}
**Research scope:**
{SCOPE}
**Output location:** {OUTPUT_PATH}
Execute research following your baked-in methodology. Return structured result when complete.
```
The template should be context-only (~50-80 lines). The agent file has all the methodology.
</action>
<verify>File exists at get-shit-done/templates/research-subagent-prompt.md</verify>
<done>Subagent prompt template created, references gsd-researcher agent</done>
</task>
<task type="auto">
<name>Task 2: Refactor research-phase command to thin orchestrator</name>
<files>commands/gsd/research-phase.md</files>
<action>
Rewrite `commands/gsd/research-phase.md` as a thin orchestrator (~120-150 lines).
**Orchestrator responsibilities (keep in command):**
1. Validate phase argument
2. Check for existing RESEARCH.md (offer to update/skip)
3. Load phase context (ROADMAP, requirements, CONTEXT.md if exists)
4. Spawn gsd-researcher agent with mode and context
5. Handle agent return (RESEARCH COMPLETE or RESEARCH INCONCLUSIVE)
6. Commit RESEARCH.md to git
7. Offer next steps
**Delegate to agent (via gsd-researcher):**
- Research methodology
- Source hierarchy (Context7 > official > WebSearch)
- Domain identification
- Research execution
- Verification checklist
- RESEARCH.md content creation
**Command structure:**
```yaml
---
name: gsd:research-phase
description: Research how to implement a phase before planning
argument-hint: "[phase]"
allowed-tools:
- Read
- Bash
- Glob
- Grep
- Write
- Task
---
```
**Process:**
1. validate_phase - Check phase exists in roadmap
2. check_existing - Offer to update/view/skip if RESEARCH.md exists
3. load_context - Read ROADMAP, requirements, CONTEXT.md
4. spawn_researcher - Use Task tool with subagent_type: "gsd-researcher"
5. handle_result - Process agent return
6. git_commit - Commit RESEARCH.md
7. offer_next - Suggest /gsd:plan-phase
**Key change:** Remove all research methodology from command. Keep only orchestration logic.
</action>
<verify>
- Command file is 120-150 lines
- Spawns gsd-researcher agent
- No research methodology in command (delegated to agent)
- Has validate, check_existing, load_context, spawn_researcher, handle_result, git_commit steps
</verify>
<done>/gsd:research-phase refactored to thin orchestrator that spawns gsd-researcher</done>
</task>
<task type="auto">
<name>Task 3: Deprecate workflows/research-phase.md</name>
<files>get-shit-done/workflows/research-phase.md</files>
<action>
Replace `get-shit-done/workflows/research-phase.md` with deprecation notice (following Phase 13 pattern).
**Content:**
```markdown
# DEPRECATED
This workflow has been replaced by the gsd-researcher agent.
**New location:** `~/.claude/agents/gsd-researcher.md`
The `/gsd:research-phase` command now spawns the gsd-researcher agent directly. All research methodology is baked into the agent.
**Migration:** No action needed. Commands automatically use the new agent.
```
Keep the file (don't delete) for git history traceability.
</action>
<verify>File contains deprecation notice pointing to gsd-researcher agent</verify>
<done>workflows/research-phase.md deprecated with redirect to agent</done>
</task>
</tasks>
<verification>
Before declaring plan complete:
- [ ] get-shit-done/templates/research-subagent-prompt.md exists
- [ ] commands/gsd/research-phase.md refactored (120-150 lines)
- [ ] Command spawns gsd-researcher agent
- [ ] No research methodology in command
- [ ] workflows/research-phase.md deprecated with redirect
</verification>
<success_criteria>
- /gsd:research-phase is now a thin orchestrator
- Command spawns gsd-researcher agent for research
- Main context load reduced from ~500+ to ~150 lines
- Workflow file deprecated (not deleted) with agent pointer
- Pattern established for research-project refactoring
</success_criteria>
<output>
After completion, create `.planning/phases/14-researcher-agent/14-02-SUMMARY.md`
</output>

213
.planning/phases/14-researcher-agent/14-03-PLAN.md
View File

@@ -1,213 +0,0 @@
---
phase: 14-researcher-agent
plan: 03
type: execute
wave: 2
depends_on: ["14-01"]
files_modified: [commands/gsd/research-project.md, get-shit-done/workflows/research-project.md, get-shit-done/references/research-pitfalls.md]
autonomous: true
must_haves:
truths:
- "/gsd:research-project spawns parallel gsd-researcher agents"
- "Each agent handles one research domain (stack, features, architecture, pitfalls)"
- "Command is thin orchestrator (<200 lines)"
- "Deprecated files redirect to agent"
artifacts:
- path: "commands/gsd/research-project.md"
provides: "Thin orchestrator for project research"
min_lines: 100
contains: "gsd-researcher"
- path: "get-shit-done/workflows/research-project.md"
provides: "Deprecation notice"
contains: "DEPRECATED"
- path: "get-shit-done/references/research-pitfalls.md"
provides: "Deprecation notice"
contains: "DEPRECATED"
key_links:
- from: "research-project.md command"
to: "gsd-researcher agents (parallel)"
via: "Multiple Task tool spawns"
pattern: "subagent_type.*gsd-researcher"
---
<objective>
Refactor /gsd:research-project to thin orchestrator that spawns parallel gsd-researcher agents + deprecate remaining files.
Purpose: Reduce main context load, enable parallel research for project domains.
Output: Thin orchestrator command + deprecated workflow and reference files.
</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 implementation to refactor:
@commands/gsd/research-project.md
@get-shit-done/workflows/research-project.md
@get-shit-done/references/research-pitfalls.md
# Agent we're delegating to:
@agents/gsd-researcher.md
# Template from 14-02:
@get-shit-done/templates/research-subagent-prompt.md
# Prior summaries:
@.planning/phases/14-researcher-agent/14-01-SUMMARY.md
@.planning/phases/14-researcher-agent/14-02-SUMMARY.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Refactor research-project command to thin orchestrator</name>
<files>commands/gsd/research-project.md</files>
<action>
Rewrite `commands/gsd/research-project.md` as a thin orchestrator (~150-180 lines).
**Orchestrator responsibilities (keep in command):**
1. Validate PROJECT.md exists
2. Check for existing .planning/research/ (offer to view/replace/cancel)
3. Analyze PROJECT.md to determine domain
4. Generate research questions for each dimension
5. Spawn 4 parallel gsd-researcher agents (stack, features, architecture, pitfalls)
6. Wait for all agents to complete
7. Create SUMMARY.md (synthesize agent outputs)
8. Commit research to git
9. Offer next steps (/gsd:define-requirements)
**Delegate to agents (via gsd-researcher):**
- Research methodology
- Source hierarchy
- Domain-specific research execution
- Verification checklist
- Individual file content (STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md)
**Command structure:**
```yaml
---
name: gsd:research-project
description: Research domain ecosystem before creating roadmap
allowed-tools:
- Read
- Write
- Bash
- Glob
- Grep
- Task
---
```
**Process:**
1. validate - Check PROJECT.md exists
2. check_existing - Handle existing research folder
3. analyze_project - Extract domain, stack hints, core value
4. determine_questions - Generate 4 research questions
5. setup_directory - Create .planning/research/
6. spawn_researchers - Spawn 4 gsd-researcher agents in parallel:
- Stack agent (mode: implementation, question: stack question)
- Features agent (mode: ecosystem, question: features question)
- Architecture agent (mode: implementation, question: architecture question)
- Pitfalls agent (mode: feasibility, question: pitfalls question)
7. write_summary - Synthesize agent outputs into SUMMARY.md
8. git_commit - Commit all research files
9. present_results - Show summary, offer /gsd:define-requirements
**Parallel spawn pattern:**
```
# Spawn all 4 in parallel (single message with multiple Task calls)
Task(subagent_type: "gsd-researcher", prompt: stack context)
Task(subagent_type: "gsd-researcher", prompt: features context)
Task(subagent_type: "gsd-researcher", prompt: architecture context)
Task(subagent_type: "gsd-researcher", prompt: pitfalls context)
```
Each agent writes its own output file (.planning/research/{DOMAIN}.md).
</action>
<verify>
- Command file is 150-180 lines
- Spawns 4 parallel gsd-researcher agents
- No research methodology in command (delegated to agents)
- Has validate, analyze, spawn_researchers, write_summary, git_commit steps
</verify>
<done>/gsd:research-project refactored to parallel orchestrator</done>
</task>
<task type="auto">
<name>Task 2: Deprecate workflows/research-project.md</name>
<files>get-shit-done/workflows/research-project.md</files>
<action>
Replace `get-shit-done/workflows/research-project.md` with deprecation notice.
**Content:**
```markdown
# DEPRECATED
This workflow has been replaced by the gsd-researcher agent.
**New location:** `~/.claude/agents/gsd-researcher.md`
The `/gsd:research-project` command now spawns parallel gsd-researcher agents directly. Each agent handles one research domain (stack, features, architecture, pitfalls).
**Migration:** No action needed. Commands automatically use the new agents.
```
</action>
<verify>File contains deprecation notice pointing to gsd-researcher agent</verify>
<done>workflows/research-project.md deprecated with redirect to agent</done>
</task>
<task type="auto">
<name>Task 3: Deprecate references/research-pitfalls.md</name>
<files>get-shit-done/references/research-pitfalls.md</files>
<action>
Replace `get-shit-done/references/research-pitfalls.md` with deprecation notice.
**Content:**
```markdown
# DEPRECATED
This reference has been consolidated into the gsd-researcher agent.
**New location:** `~/.claude/agents/gsd-researcher.md`
**Section:** `<verification_patterns>`
All pitfall detection, verification checklists, and red flags are now baked into the gsd-researcher agent.
**Migration:** No action needed. Research agents automatically apply verification patterns.
```
</action>
<verify>File contains deprecation notice pointing to gsd-researcher agent verification_patterns section</verify>
<done>references/research-pitfalls.md deprecated with redirect to agent</done>
</task>
</tasks>
<verification>
Before declaring plan complete:
- [ ] commands/gsd/research-project.md refactored (150-180 lines)
- [ ] Command spawns 4 parallel gsd-researcher agents
- [ ] No research methodology in command
- [ ] workflows/research-project.md deprecated with redirect
- [ ] references/research-pitfalls.md deprecated with redirect
</verification>
<success_criteria>
- /gsd:research-project is now a thin parallel orchestrator
- Command spawns 4 gsd-researcher agents in parallel
- Main context load significantly reduced
- Workflow and reference files deprecated with agent pointers
- Phase 14 complete - all research expertise consolidated in gsd-researcher
</success_criteria>
<output>
After completion, create `.planning/phases/14-researcher-agent/14-03-SUMMARY.md`
</output>

260
.planning/phases/15-dedicated-planner-agent/15-01-PLAN.md
View File

@@ -1,260 +0,0 @@
---
phase: 15-dedicated-planner-agent
plan: 01
type: execute
wave: 1
depends_on: []
files_modified: [agents/gsd-planner.md]
autonomous: true
must_haves:
truths:
- "gsd-planner agent file contains complete planning methodology"
- "Agent includes all concepts from source reference files"
- "Agent follows established gsd-debugger/gsd-researcher patterns"
artifacts:
- path: "agents/gsd-planner.md"
provides: "Complete planning agent with baked-in expertise"
min_lines: 800
contains: "name: gsd-planner"
key_links:
- from: "agents/gsd-planner.md"
to: "planning methodology"
via: "consolidated content"
pattern: "<role>|<philosophy>|<execution_flow>"
---
<objective>
Create gsd-planner agent with complete planning methodology baked in.
Purpose: Consolidate ~3,580 lines of planning references into a dedicated agent that spawns for phase planning.
Output: `agents/gsd-planner.md` with all planning expertise (~900-1100 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
# Pattern references from Phase 13-14:
@agents/gsd-debugger.md
@agents/gsd-researcher.md
# Source files to consolidate:
@get-shit-done/references/principles.md
@get-shit-done/workflows/plan-phase.md
@get-shit-done/templates/phase-prompt.md
@get-shit-done/references/plan-format.md
@get-shit-done/references/scope-estimation.md
@get-shit-done/references/checkpoints.md
@get-shit-done/references/tdd.md
@get-shit-done/references/goal-backward.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Create gsd-planner agent file</name>
<files>agents/gsd-planner.md</files>
<action>
Create `agents/gsd-planner.md` consolidating all planning methodology from source files.
**Agent structure (follow gsd-debugger/gsd-researcher pattern):**
**Frontmatter:**
```yaml
---
name: gsd-planner
description: Creates executable phase plans with task breakdown, dependency analysis, and goal-backward verification. Spawned by /gsd:plan-phase orchestrator.
tools: Read, Write, Bash, Glob, Grep, WebFetch, mcp__context7__*
color: green
---
```
**Required sections:**
1. `<role>` - Planning agent identity
- Spawned by /gsd:plan-phase orchestrator
- Produces PLAN.md files with executable tasks
- Handles both standard planning and gap closure mode (--gaps)
2. `<philosophy>` - Core planning principles
- Solo developer + Claude workflow (from principles.md)
- Plans are prompts (not documents that become prompts)
- Scope control and quality degradation curve
- Ship fast, no enterprise patterns
3. `<discovery_levels>` - Mandatory discovery protocol
- Level 0-3 from plan-phase.md
- When to research vs proceed
- Integration with Context7 for library questions
4. `<task_breakdown>` - How to decompose phases
- Task anatomy: files, action, verify, done
- Task types: auto, checkpoint:human-verify, checkpoint:decision, checkpoint:human-action
- TDD detection heuristic (from tdd.md)
- User setup detection for external services
5. `<dependency_graph>` - Building dependency graphs
- needs/creates analysis per task
- Wave assignment algorithm
- Vertical slices vs horizontal layers
- File ownership for parallel execution
6. `<scope_estimation>` - Plan sizing
- Context budget rules (50% target, 2-3 tasks max)
- Split signals (always split, consider splitting)
- Depth calibration (quick/standard/comprehensive)
- Estimating context per task type
7. `<plan_format>` - PLAN.md structure
- Frontmatter fields (phase, plan, type, wave, depends_on, files_modified, autonomous, must_haves)
- XML task structure
- Context section rules (parallel-aware)
- Verification and success criteria
8. `<goal_backward>` - Must-haves derivation
- Truths (observable behaviors)
- Artifacts (files that must exist)
- Key links (critical connections)
- From goal-backward.md
9. `<checkpoints>` - Checkpoint patterns
- Types and when to use each
- Execution protocol
- Authentication gates
- Anti-patterns (from checkpoints.md)
10. `<tdd_integration>` - TDD plan structure
- When TDD improves quality
- TDD plan format vs standard plan
- RED-GREEN-REFACTOR cycle
- From tdd.md
11. `<gap_closure_mode>` - Planning from verification gaps
- Parse VERIFICATION.md / UAT.md
- Create tasks from gap.missing items
- Number plans sequentially after existing
- From gap_closure_mode step in plan-phase.md
12. `<execution_flow>` - Step-by-step planning process
- load_project_state
- load_codebase_context
- identify_phase
- mandatory_discovery
- read_project_history (intelligent frontmatter assembly)
- gather_phase_context
- break_into_tasks
- build_dependency_graph
- assign_waves
- group_into_plans
- estimate_scope
- confirm_breakdown
- write_phase_prompt
- git_commit
- offer_next
13. `<structured_returns>` - Return format for orchestrator
- PLANNING COMPLETE (plans created, wave structure)
- CHECKPOINT REACHED (decision needed)
- Planning outcome summary
14. `<success_criteria>` - Completion checklist
- Standard mode criteria
- Gap closure mode criteria
**Consolidation targets:**
- Preserve ALL critical concepts from source files
- Target ~900-1100 lines (similar to gsd-researcher at 902 lines)
- Eliminate redundancy between source files
- Keep examples concise but instructive
- Do NOT pad to hit line count - derive from actual content
**What to preserve:**
- Quality degradation curve percentages
- Wave assignment algorithm
- Task anatomy structure (files, action, verify, done)
- Checkpoint types and execution protocol
- Discovery levels and triggers
- Goal-backward derivation process
- TDD heuristic (can you write expect before fn?)
- Anti-patterns and bad examples
- Context budget rules
**What to compress/eliminate:**
- Duplicate explanations across files
- Verbose examples (keep one good example per concept)
- Excessive caveats and disclaimers
- Repetitive anti-pattern lists
</action>
<verify>
File exists: `agents/gsd-planner.md`
Contains frontmatter with `name: gsd-planner`
Has all 14 required sections with XML tags
Line count between 800-1200
</verify>
<done>gsd-planner agent file created with all planning methodology consolidated</done>
</task>
<task type="auto">
<name>Task 2: Verify agent completeness</name>
<files>agents/gsd-planner.md</files>
<action>
Read the created agent file and verify all required content is present:
**Verification checklist:**
- [ ] Role section explains what agent does and who spawns it
- [ ] Philosophy includes solo-dev principles and "plans are prompts"
- [ ] Discovery levels include all 4 levels (0-3) with triggers
- [ ] Task breakdown includes all task types and TDD detection
- [ ] Dependency graph includes wave algorithm and vertical slices
- [ ] Scope estimation includes context budget rules and split signals
- [ ] Plan format includes complete frontmatter schema and must_haves
- [ ] Goal backward includes truths, artifacts, key_links derivation
- [ ] Checkpoints includes all types with execution protocol
- [ ] TDD integration includes when-to-use and plan structure
- [ ] Gap closure mode includes parsing and task creation
- [ ] Execution flow includes all steps from plan-phase.md
- [ ] Structured returns includes planning outcome format
- [ ] Success criteria includes both standard and gap closure checklists
**Content verification:**
- Quality degradation curve (0-30% peak, 30-50% good, 50-70% degrading, 70%+ poor)
- Wave assignment algorithm present
- Checkpoint types: human-verify, decision, human-action
- Discovery triggers for each level
- TDD heuristic about expect() before fn
- Anti-patterns section present
If any gaps found, edit file to add missing content.
</action>
<verify>All 14 sections present with appropriate content depth</verify>
<done>Agent verified complete with all planning methodology</done>
</task>
</tasks>
<verification>
Before declaring plan complete:
- [ ] `agents/gsd-planner.md` exists
- [ ] File has valid YAML frontmatter
- [ ] All 14 sections present with XML tags
- [ ] Line count is 800-1200 lines
- [ ] No duplicate content from compression
</verification>
<success_criteria>
- gsd-planner agent file created
- All planning methodology consolidated from source files
- Follows gsd-debugger/gsd-researcher pattern
- Ready for orchestrator integration in Plan 15-02
</success_criteria>
<output>
After completion, create `.planning/phases/15-dedicated-planner-agent/15-01-SUMMARY.md`
</output>

106
.planning/phases/15-dedicated-planner-agent/15-01-SUMMARY.md
View File

@@ -1,106 +0,0 @@
---
phase: 15
plan: 01
subsystem: agents
tags: [planner, agent, planning, methodology]
dependency-graph:
requires: [13, 14]
provides: [gsd-planner-agent, consolidated-planning-methodology]
affects: [future-plan-phase-refactor]
tech-stack:
added: []
patterns: [consolidated-agent, thin-orchestrator-pattern]
key-files:
created: [agents/gsd-planner.md]
modified: []
key-decisions:
- "14 sections covering complete planning workflow"
- "1,147 lines consolidated from ~3,580 lines of source material"
- "Follows gsd-debugger/gsd-researcher pattern"
metrics:
duration: "5 min"
completed: "2026-01-16"
---
# Phase 15 Plan 01: Create gsd-planner Agent Summary
**One-liner:** Consolidated ~3,580 lines of planning references into 1,147-line dedicated agent following gsd-debugger/gsd-researcher pattern.
## Accomplishments
1. **Created gsd-planner agent file** (`agents/gsd-planner.md`)
- Complete planning methodology baked into single agent file
- 1,147 lines (within 800-1200 target)
- 14 sections covering full planning workflow
- Follows established agent patterns from Phase 13-14
2. **Consolidated planning methodology from source files:**
- `references/principles.md` - Solo developer + Claude workflow philosophy
- `workflows/plan-phase.md` - Full execution flow with 16 steps
- `templates/phase-prompt.md` - PLAN.md structure and frontmatter
- `references/plan-format.md` - Task anatomy and types
- `references/scope-estimation.md` - Context budget and split signals
- `references/checkpoints.md` - Checkpoint types and authentication gates
- `references/tdd.md` - TDD detection and plan structure
- `references/goal-backward.md` - Must-haves derivation process
3. **Agent sections implemented:**
- `<role>` - Planning agent identity and responsibilities
- `<philosophy>` - Plans are prompts, quality degradation curve, ship fast
- `<discovery_levels>` - Levels 0-3 with triggers
- `<task_breakdown>` - Task anatomy, types, TDD detection
- `<dependency_graph>` - Wave analysis, vertical slices
- `<scope_estimation>` - Context budget, split signals, depth calibration
- `<plan_format>` - PLAN.md structure, frontmatter schema
- `<goal_backward>` - Truths, artifacts, key_links derivation
- `<checkpoints>` - Types, authentication gates, anti-patterns
- `<tdd_integration>` - When to use, plan structure, RED-GREEN-REFACTOR
- `<gap_closure_mode>` - Planning from verification gaps
- `<execution_flow>` - 16 steps from load_project_state to offer_next
- `<structured_returns>` - PLANNING COMPLETE, CHECKPOINT REACHED formats
- `<success_criteria>` - Standard mode and gap closure mode checklists
## Technical Details
**Source material (~3,580 lines):**
- principles.md: ~73 lines
- plan-phase.md: ~868 lines
- phase-prompt.md: ~575 lines
- plan-format.md: ~474 lines
- scope-estimation.md: ~257 lines
- checkpoints.md: ~789 lines
- tdd.md: ~264 lines
- goal-backward.md: ~287 lines
**Consolidation result:**
- 1,147 lines (68% reduction from source material)
- Preserved all critical concepts
- Eliminated redundancy between source files
- Kept concise examples for each concept
## Deviations from Plan
None - plan executed exactly as written.
## Commits
| Commit | Type | Description |
|--------|------|-------------|
| 1f45bef | feat | Create gsd-planner agent file |
## Next Phase Readiness
**Ready for Plan 15-02:** Refactor plan-phase.md to thin orchestrator
- gsd-planner agent contains all planning expertise
- plan-phase.md can be reduced to ~200 lines orchestrator
- Will spawn gsd-planner subagent for actual planning work
**Dependencies satisfied:**
- Agent file exists and is complete
- All 14 sections verified present
- Follows established pattern from gsd-debugger/gsd-researcher

301
.planning/phases/15-dedicated-planner-agent/15-02-PLAN.md
View File

@@ -1,301 +0,0 @@
---
phase: 15-dedicated-planner-agent
plan: 02
type: execute
wave: 2
depends_on: ["15-01"]
files_modified: [commands/gsd/plan-phase.md, get-shit-done/workflows/plan-phase.md, get-shit-done/templates/planner-subagent-prompt.md]
autonomous: true
must_haves:
truths:
- "/gsd:plan-phase command spawns gsd-planner agent"
- "Orchestrator is thin (<200 lines)"
- "Template provides context, agent has expertise"
artifacts:
- path: "commands/gsd/plan-phase.md"
provides: "Thin orchestrator for phase planning"
min_lines: 80
contains: "agent: gsd-planner"
- path: "get-shit-done/templates/planner-subagent-prompt.md"
provides: "Context-only prompt template for spawning planner"
min_lines: 50
key_links:
- from: "commands/gsd/plan-phase.md"
to: "agents/gsd-planner.md"
via: "agent: gsd-planner frontmatter"
pattern: "agent: gsd-planner"
---
<objective>
Refactor /gsd:plan-phase to thin orchestrator that spawns gsd-planner agent.
Purpose: Reduce context usage in main thread from ~3,580 lines to ~150 lines.
Output: Thin orchestrator command and context-only subagent prompt template.
</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
# Pattern references from Phase 13-14:
@commands/gsd/debug.md
@commands/gsd/research-phase.md
@get-shit-done/templates/debug-subagent-prompt.md
@get-shit-done/templates/research-subagent-prompt.md
# Prior plan summary:
@.planning/phases/15-dedicated-planner-agent/15-01-SUMMARY.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Refactor /gsd:plan-phase to thin orchestrator</name>
<files>commands/gsd/plan-phase.md</files>
<action>
Rewrite `commands/gsd/plan-phase.md` as thin orchestrator following debug.md and research-phase.md patterns.
**New frontmatter:**
```yaml
---
name: gsd:plan-phase
description: Create detailed execution plan for a phase (PLAN.md)
argument-hint: "[phase] [--gaps]"
context: fork
agent: gsd-planner
allowed-tools:
- Read
- Write
- Bash
- Glob
- Grep
- WebFetch
- mcp__context7__*
---
```
**Key change:** Add `agent: gsd-planner` to spawn dedicated agent.
**Orchestrator responsibilities (keep in command):**
1. Check .planning/ directory exists
2. Parse arguments (phase number, --gaps flag)
3. Detect next unplanned phase if no number provided
4. Validate phase exists in roadmap
5. Gather minimal context (STATE.md, ROADMAP.md paths)
6. Spawn gsd-planner agent with context
7. Present results and next steps
**Delegate to agent:**
- All planning methodology
- Discovery levels
- Task breakdown
- Dependency analysis
- Plan creation
- Gap closure logic
**Target:** ~120-150 lines (similar to research-phase.md at 130 lines)
**Structure:**
```markdown
<objective>
[Brief - planning phases into PLAN.md files]
</objective>
<orchestrator_process>
1. Validate .planning/ exists
2. Parse $ARGUMENTS for phase number and --gaps
3. If no phase: detect next unplanned from roadmap
4. Validate phase in roadmap
5. Spawn gsd-planner with context
6. Present results
</orchestrator_process>
<spawn_planner>
Use Task tool to spawn gsd-planner agent with:
- Phase number
- Gap closure mode flag
- Project context paths
</spawn_planner>
<present_results>
[Format for showing plan summary and next steps]
</present_results>
```
**DO NOT include in orchestrator:**
- Plan-phase workflow content
- Reference file content
- Task breakdown logic
- Discovery level definitions
- Scope estimation rules
</action>
<verify>
File exists: `commands/gsd/plan-phase.md`
Has `agent: gsd-planner` in frontmatter
Line count under 200
No workflow or reference file inclusions in execution_context
</verify>
<done>/gsd:plan-phase refactored to thin orchestrator (~120-150 lines)</done>
</task>
<task type="auto">
<name>Task 2: Deprecate workflows/plan-phase.md</name>
<files>get-shit-done/workflows/plan-phase.md</files>
<action>
Replace `get-shit-done/workflows/plan-phase.md` with deprecation notice following the pattern from workflows/debug.md and workflows/research-phase.md.
**New content:**
```markdown
# DEPRECATED: Plan-Phase Workflow
**This workflow has been consolidated into the gsd-planner agent.**
## Migration
Planning expertise is now baked into:
- `agents/gsd-planner.md` - Complete planning methodology
The `/gsd:plan-phase` command spawns the gsd-planner agent directly.
## Why This Changed
The thin orchestrator pattern reduces main context usage:
- Before: ~3,580 lines loaded into main context
- After: ~150 lines in orchestrator, expertise in agent
## Historical Reference
This file previously contained:
- Discovery level definitions
- Project history assembly
- Task breakdown process
- Dependency graph building
- Wave assignment algorithm
- Plan writing steps
All content preserved in `agents/gsd-planner.md`.
---
*Deprecated: 2026-01-16*
*Replaced by: agents/gsd-planner.md*
```
**Keep file for git history** - do not delete.
</action>
<verify>
File exists with deprecation notice
Points to agents/gsd-planner.md
Explains why change was made
</verify>
<done>workflows/plan-phase.md deprecated with redirect to agent</done>
</task>
<task type="auto">
<name>Task 3: Create planner-subagent-prompt.md template</name>
<files>get-shit-done/templates/planner-subagent-prompt.md</files>
<action>
Create `get-shit-done/templates/planner-subagent-prompt.md` following the pattern from debug-subagent-prompt.md and research-subagent-prompt.md.
**Template structure:**
```markdown
# Planner Subagent Prompt
Context-only template for spawning gsd-planner agent. Agent has all methodology baked in.
## Template
\`\`\`markdown
<planning_context>
**Phase:** {phase_number}
**Mode:** {standard | gap_closure}
**Project State:**
@.planning/STATE.md
**Roadmap:**
@.planning/ROADMAP.md
**Requirements (if exists):**
@.planning/REQUIREMENTS.md
**Phase Context (if exists):**
@.planning/phases/{phase_dir}/{phase}-CONTEXT.md
**Research (if exists):**
@.planning/phases/{phase_dir}/{phase}-RESEARCH.md
**Gap Closure (if --gaps mode):**
@.planning/phases/{phase_dir}/{phase}-VERIFICATION.md
@.planning/phases/{phase_dir}/{phase}-UAT.md
</planning_context>
<downstream_consumer>
Output consumed by /gsd:execute-phase or /gsd:execute-plan
Plans must be executable prompts with:
- Frontmatter (wave, depends_on, files_modified, autonomous)
- Tasks in XML format
- Verification criteria
- must_haves for goal-backward verification
</downstream_consumer>
<quality_gate>
Before returning PLANNING COMPLETE:
- [ ] PLAN.md files created in phase directory
- [ ] Each plan has valid frontmatter
- [ ] Tasks are specific and actionable
- [ ] Dependencies correctly identified
- [ ] Waves assigned for parallel execution
- [ ] must_haves derived from phase goal
</quality_gate>
\`\`\`
## Usage
Orchestrator fills in context paths and spawns agent:
1. Replace {phase_number} with actual phase
2. Replace {phase_dir} with phase directory name
3. Set mode based on --gaps flag
4. Agent loads context and produces plans
```
**Key principle:** Template provides CONTEXT. Agent has EXPERTISE.
</action>
<verify>
File exists: `get-shit-done/templates/planner-subagent-prompt.md`
Contains planning_context section
Contains downstream_consumer section
Contains quality_gate section
No methodology content (that's in the agent)
</verify>
<done>planner-subagent-prompt.md template created</done>
</task>
</tasks>
<verification>
Before declaring plan complete:
- [ ] commands/gsd/plan-phase.md is thin orchestrator (<200 lines)
- [ ] workflows/plan-phase.md has deprecation notice
- [ ] templates/planner-subagent-prompt.md created
- [ ] All three files committed
</verification>
<success_criteria>
- /gsd:plan-phase refactored to thin orchestrator
- Workflow deprecated with redirect
- Subagent template created
- Pattern matches Phase 13-14 (debug, research)
</success_criteria>
<output>
After completion, create `.planning/phases/15-dedicated-planner-agent/15-02-SUMMARY.md`
</output>

175
.planning/phases/15-dedicated-planner-agent/15-03-PLAN.md
View File

@@ -1,175 +0,0 @@
---
phase: 15-dedicated-planner-agent
plan: 03
type: execute
wave: 2
depends_on: ["15-01"]
files_modified: [get-shit-done/references/principles.md, get-shit-done/references/plan-format.md, get-shit-done/references/scope-estimation.md, get-shit-done/references/goal-backward.md, get-shit-done/templates/phase-prompt.md]
autonomous: true
must_haves:
truths:
- "Deprecated reference files point to gsd-planner agent"
- "Files retained for git history"
- "Deprecation notices explain migration"
artifacts:
- path: "get-shit-done/references/principles.md"
provides: "Deprecation notice pointing to agent"
contains: "DEPRECATED"
- path: "get-shit-done/references/plan-format.md"
provides: "Deprecation notice pointing to agent"
contains: "DEPRECATED"
- path: "get-shit-done/references/scope-estimation.md"
provides: "Deprecation notice pointing to agent"
contains: "DEPRECATED"
- path: "get-shit-done/references/goal-backward.md"
provides: "Deprecation notice pointing to agent"
contains: "DEPRECATED"
key_links:
- from: "deprecated references"
to: "agents/gsd-planner.md"
via: "deprecation notice redirect"
pattern: "agents/gsd-planner.md"
---
<objective>
Deprecate reference files that are now consolidated into gsd-planner agent.
Purpose: Prevent duplicate content and stale documentation.
Output: Deprecation notices in reference files pointing to agent.
</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
# Pattern reference from Phase 13:
@.planning/phases/13-debug-agent/13-03-SUMMARY.md
# Prior plan summary:
@.planning/phases/15-dedicated-planner-agent/15-01-SUMMARY.md
</context>
<tasks>
<task type="auto">
<name>Task 1: Deprecate planning-specific reference files</name>
<files>get-shit-done/references/principles.md, get-shit-done/references/plan-format.md, get-shit-done/references/scope-estimation.md, get-shit-done/references/goal-backward.md</files>
<action>
Replace content of planning-specific reference files with deprecation notices.
**Files to deprecate (planning-specific, now in agent):**
1. `references/principles.md` - GSD principles (now in agent philosophy)
2. `references/plan-format.md` - PLAN.md structure (now in agent plan_format)
3. `references/scope-estimation.md` - Scope rules (now in agent scope_estimation)
4. `references/goal-backward.md` - Must-haves derivation (now in agent goal_backward)
**Files to KEEP (used by other commands):**
- `references/checkpoints.md` - Used by execute-plan.md and other workflows
- `references/tdd.md` - Used by execute-plan.md for TDD execution
- `references/questioning.md` - Used by discussion commands
- `references/continuation-format.md` - Used by continuation handling
- `references/git-integration.md` - Used by multiple workflows
- `references/verification-patterns.md` - Used by verify-work
- `references/research-pitfalls.md` - Used by gsd-researcher agent
**Deprecation notice template:**
```markdown
# DEPRECATED: [Original Title]
**This reference has been consolidated into the gsd-planner agent.**
## Migration
Planning expertise is now baked into:
- `agents/gsd-planner.md` - Section: `<section_name>`
## Why This Changed
The thin orchestrator pattern consolidates all planning methodology into the agent:
- Before: Reference files loaded separately (~X lines)
- After: Agent has expertise baked in, orchestrator is thin
## Historical Reference
This file previously contained:
- [Key concept 1]
- [Key concept 2]
- [Key concept 3]
All content preserved in `agents/gsd-planner.md`.
---
*Deprecated: 2026-01-16*
*Replaced by: agents/gsd-planner.md*
```
**Customize each notice:**
- principles.md → philosophy section
- plan-format.md → plan_format section
- scope-estimation.md → scope_estimation section
- goal-backward.md → goal_backward section
</action>
<verify>
All 4 files contain "DEPRECATED" header
All point to agents/gsd-planner.md
All explain which section contains the content
</verify>
<done>Planning-specific references deprecated with agent pointers</done>
</task>
<task type="auto">
<name>Task 2: Add deprecation note to phase-prompt template</name>
<files>get-shit-done/templates/phase-prompt.md</files>
<action>
Add deprecation header to `get-shit-done/templates/phase-prompt.md` while preserving content.
**Why preserve content:** This template is used by the gsd-planner agent as reference for PLAN.md structure. The agent needs to know the output format.
**Add header at top:**
```markdown
# Phase Prompt Template
> **Note:** Planning methodology is in `agents/gsd-planner.md`.
> This template defines the PLAN.md output format that the agent produces.
Template for `.planning/phases/XX-name/{phase}-{plan}-PLAN.md` - executable phase plans optimized for parallel execution.
...
```
**Keep all existing content** - this is the output format spec, not methodology.
</action>
<verify>
File has note pointing to agent
All existing content preserved
Template structure intact
</verify>
<done>phase-prompt.md has clarifying note about agent relationship</done>
</task>
</tasks>
<verification>
Before declaring plan complete:
- [ ] 4 reference files deprecated with notices
- [ ] phase-prompt.md has clarifying note
- [ ] checkpoints.md and tdd.md NOT deprecated (used by other workflows)
- [ ] All deprecation notices point to agents/gsd-planner.md
</verification>
<success_criteria>
- Planning-specific references deprecated
- Shared references (checkpoints, tdd) preserved
- phase-prompt.md clarified but preserved
- Pattern matches Phase 13 deprecation approach
</success_criteria>
<output>
After completion, create `.planning/phases/15-dedicated-planner-agent/15-03-SUMMARY.md`
</output>

216
.planning/phases/16-plan-verification-loop/16-01-PLAN.md
View File

@@ -1,216 +0,0 @@
---
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>

102
.planning/phases/16-plan-verification-loop/16-01-SUMMARY.md
View File

@@ -1,102 +0,0 @@
---
phase: 16-plan-verification-loop
plan: 01
subsystem: agents
tags: [verification, planning, goal-backward, plan-checker]
# Dependency graph
requires:
- phase: 15-dedicated-planner-agent
provides: gsd-planner agent to create plans
provides:
- gsd-plan-checker agent for plan verification before execution
- Six verification dimensions (coverage, completeness, dependencies, links, scope, derivation)
- Structured issue format for planner feedback loop
affects: [16-plan-verification-loop, plan-phase, execute-phase]
# Tech tracking
tech-stack:
added: []
patterns:
- "Goal-backward plan verification (plans, not code)"
- "Structured issue reporting with fix hints"
- "Checker role mirrors verifier (verify plans vs verify code)"
key-files:
created:
- agents/gsd-plan-checker.md
modified: []
key-decisions:
- "Six dimensions: coverage, completeness, dependencies, links, scope, derivation"
- "Structured YAML issue format for planner consumption"
- "Checker returns passed or issues_found status"
patterns-established:
- "Plan checker verifies BEFORE execution (vs verifier verifies AFTER)"
- "Same goal-backward methodology as gsd-verifier but applied to plans"
# Metrics
duration: 3min
completed: 2026-01-16
---
# Phase 16 Plan 01: Create gsd-plan-checker Agent Summary
**Goal-backward plan verification agent with six dimensions: coverage, completeness, dependencies, links, scope, and derivation**
## Performance
- **Duration:** 3 min
- **Started:** 2026-01-16T14:54:04Z
- **Completed:** 2026-01-16T14:56:57Z
- **Tasks:** 2
- **Files modified:** 1
## Accomplishments
- Created gsd-plan-checker agent with complete plan verification methodology
- Six verification dimensions covering all aspects of plan quality
- Structured issue format that planner can consume for revisions
- Four example scenarios demonstrating common failure modes
## Task Commits
Each task was committed atomically:
1. **Task 1+2: Create gsd-plan-checker with examples** - `47eab1a` (feat)
- Combined task: created agent with all sections including examples
**Plan metadata:** (pending)
## Files Created/Modified
- `agents/gsd-plan-checker.md` - Plan verification agent (744 lines)
## Decisions Made
- **Six verification dimensions:** Coverage, completeness, dependencies, key links, scope, derivation - comprehensive without overlap
- **Structured YAML issues:** Format allows planner to programmatically parse and address
- **Checker vs Verifier distinction:** Clear - checker verifies plans WILL achieve goal, verifier verifies code DID achieve goal
## Deviations from Plan
None - plan executed as written (Task 2's examples section was included in Task 1 creation for efficiency).
## Issues Encountered
None
## User Setup Required
None - no external service configuration required.
## Next Phase Readiness
- gsd-plan-checker agent ready for integration
- Next: 16-02 updates plan-phase.md orchestrator to spawn checker after planner
- Next: 16-03 adds revision mode to gsd-planner for handling checker feedback
---
*Phase: 16-plan-verification-loop*
*Completed: 2026-01-16*

325
.planning/phases/16-plan-verification-loop/16-02-PLAN.md
View File

@@ -1,325 +0,0 @@
---
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
View File

@@ -1,273 +0,0 @@
---
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>

94
.planning/phases/16-plan-verification-loop/16-03-SUMMARY.md
View File

@@ -1,94 +0,0 @@
---
phase: 16-plan-verification-loop
plan: 03
subsystem: planning
tags: [gsd-planner, revision-mode, checker-feedback, plan-updates]
# Dependency graph
requires:
- phase: 16-01
provides: gsd-plan-checker agent with issue format
provides:
- revision_mode section in gsd-planner
- 6-step revision process for handling checker feedback
- REVISION COMPLETE return format
affects: [plan-phase orchestrator, verification loop]
# Tech tracking
tech-stack:
added: []
patterns: [surgeon mindset for targeted plan updates]
key-files:
created: []
modified: [agents/gsd-planner.md]
key-decisions:
- "6-step revision process matching checker issue format"
- "Strategy table mapping each issue dimension to specific revision action"
- "Surgeon mindset: minimal targeted updates, not full rewrites"
patterns-established:
- "Revision mode parses structured issues and applies targeted fixes"
- "Return format mirrors gap_closure format for orchestrator consistency"
# Metrics
duration: 3min
completed: 2026-01-16
---
# Phase 16 Plan 03: Planner Revision Mode Summary
**Revision mode added to gsd-planner for handling checker feedback with 6-step targeted update process**
## Performance
- **Duration:** 3 min
- **Started:** 2026-01-16
- **Completed:** 2026-01-16
- **Tasks:** 3
- **Files modified:** 1
## Accomplishments
- Added revision_mode section (~105 lines) with 6-step revision process
- Updated role section to document revision mode spawning and responsibility
- Added REVISION COMPLETE return format to structured_returns section
- Planner can now be spawned in standard, gap_closure, or revision mode
## Task Commits
Each task was committed atomically:
1. **Task 1: Add revision_mode section** - `6b31a92` (feat)
2. **Task 2: Update role section** - `8420752` (docs)
3. **Task 3: Add REVISION COMPLETE format** - `ace3b36` (docs)
## Files Created/Modified
- `agents/gsd-planner.md` - Added revision_mode section, updated role, added return format (now 1,284 lines)
## Decisions Made
- 6-step process: Load plans, parse issues, determine strategy, make updates, validate, return summary
- Strategy table maps each of the 6 verification dimensions to specific revision actions
- Surgeon mindset emphasized: minimal changes to address specific issues, preserve working parts
## Deviations from Plan
None - plan executed exactly as written.
## Issues Encountered
None
## User Setup Required
None - no external service configuration required.
## Next Phase Readiness
- gsd-planner has complete revision mode documentation
- Revision strategy table covers all 6 issue dimensions from gsd-plan-checker
- Return format matches what orchestrator expects
- Ready for plan-phase orchestrator integration (16-02)
---
*Phase: 16-plan-verification-loop*
*Completed: 2026-01-16*

139
.planning/phases/16-plan-verification-loop/16-BRIEF.md
View File

@@ -1,139 +0,0 @@
# 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

96
.planning/phases/16-plan-verification-loop/16-VERIFICATION.md
View File

@@ -1,96 +0,0 @@
---
phase: 16-plan-verification-loop
verified: 2026-01-16T15:30:00Z
status: passed
score: 12/12 must-haves verified
---
# Phase 16: Plan Verification Loop Verification Report
**Phase Goal:** Add plan verification between planning and execution — planner -> checker -> revise loop
**Verified:** 2026-01-16
**Status:** passed
**Re-verification:** No — initial verification
## Goal Achievement
### Observable Truths
| # | Truth | Status | Evidence |
|---|-------|--------|----------|
| 1 | Plan checker can load PLAN.md files and parse frontmatter | VERIFIED | `gsd-plan-checker.md` lines 250-302: Step 2-3 document loading PLAN.md files and parsing frontmatter |
| 2 | Plan checker can verify plans against phase goal from ROADMAP.md | VERIFIED | `gsd-plan-checker.md` lines 253-261: Extracts phase goal from ROADMAP.md |
| 3 | Plan checker returns structured issues or passed status | VERIFIED | `gsd-plan-checker.md` lines 630-706: `## VERIFICATION PASSED` and `## ISSUES FOUND` structured returns |
| 4 | Checker output is consumable by orchestrator and planner | VERIFIED | `gsd-plan-checker.md` lines 569-627: YAML issue structure with plan, dimension, severity, fix_hint |
| 5 | Orchestrator spawns gsd-planner then gsd-plan-checker | VERIFIED | `plan-phase.md` steps 6 and 8: Task() spawns for gsd-planner then gsd-plan-checker |
| 6 | User sees status between agent spawns | VERIFIED | `plan-phase.md` lines 94, 174, 225, 263: Display statements between each spawn |
| 7 | If issues found, planner is re-spawned with feedback | VERIFIED | `plan-phase.md` lines 219-259: Step 10 spawns planner with revision_context containing issues |
| 8 | Loop terminates after max 3 iterations or passed | VERIFIED | `plan-phase.md` lines 221, 223, 261-271: iteration_count tracking, max 3 check, user options |
| 9 | Planner can accept checker feedback in revision mode | VERIFIED | `gsd-planner.md` line 842-945: `<revision_mode>` section accepts `<revision_context>` with issues |
| 10 | Planner reads existing PLAN.md files when revising | VERIFIED | `gsd-planner.md` lines 850-861: Step 1 loads existing PLAN.md files |
| 11 | Planner makes targeted updates, not full replan | VERIFIED | `gsd-planner.md` lines 894-906: DO/DO NOT guidance - "Surgeon, not architect" mindset |
| 12 | Planner returns what changed for user visibility | VERIFIED | `gsd-planner.md` lines 917-943: Step 6 returns `## REVISION COMPLETE` with changes table |
**Score:** 12/12 truths verified
### Required Artifacts
| Artifact | Expected | Status | Details |
|----------|----------|--------|---------|
| `agents/gsd-plan-checker.md` | Plan verification agent (400-600 lines) | VERIFIED | 744 lines, 9 sections (exceeds 7 required), complete methodology |
| `commands/gsd/plan-phase.md` | Orchestrator with verification loop (200+ lines) | VERIFIED | 310 lines, 11 process steps, planner -> checker -> revise loop |
| `agents/gsd-planner.md` | Planner with revision mode (1100+ lines) | VERIFIED | 1284 lines, revision_mode section added (~105 lines) |
### Key Link Verification
| From | To | Via | Status | Details |
|------|-----|-----|--------|---------|
| plan-phase.md | gsd-planner | Task() spawn | WIRED | Lines 147-153, 250-256 |
| plan-phase.md | gsd-plan-checker | Task() spawn | WIRED | Lines 199-205 |
| checker output | planner revision | issues in revision_context | WIRED | Lines 229-247 pass issues to planner |
| gsd-plan-checker | PLAN.md files | Read in verification_process | WIRED | Lines 250-302 load PLAN.md |
| gsd-plan-checker | ROADMAP.md | Phase goal extraction | WIRED | Lines 253-254 extract goal |
| gsd-planner revision | existing PLANs | Read tool | WIRED | Lines 850-856 load existing plans |
| gsd-planner revision | checker issues | revision_context | WIRED | Lines 863-879 parse issue format |
### Requirements Coverage
| Requirement | Status | Evidence |
|-------------|--------|----------|
| gsd-plan-checker agent created | SATISFIED | `agents/gsd-plan-checker.md` (744 lines) |
| plan-phase.md orchestrates planner -> checker loop | SATISFIED | Steps 6-10 in process section |
| User sees status between agent spawns | SATISFIED | Display statements at each step |
| Checker verifies plans against phase goal | SATISFIED | 6 verification dimensions |
| Planner can revise based on feedback | SATISFIED | `<revision_mode>` section |
| Loop terminates (max 3 iterations or passed) | SATISFIED | iteration_count tracking |
| Plans verified before execution available | SATISFIED | Complete flow verified |
### Anti-Patterns Found
| File | Line | Pattern | Severity | Impact |
|------|------|---------|----------|--------|
| - | - | - | - | No anti-patterns found |
No TODO, FIXME, placeholder, or stub patterns detected in any of the three artifacts.
### Human Verification Required
None required. All phase deliverables are documentable artifacts (markdown files) that can be fully verified programmatically.
### Gaps Summary
No gaps found. All 12 must-have truths verified. All 3 artifacts exist, are substantive (exceed minimum line counts), and are properly wired together. The verification loop is complete:
1. `plan-phase.md` spawns `gsd-planner`
2. Planner creates PLAN.md files
3. `plan-phase.md` spawns `gsd-plan-checker`
4. Checker verifies plans, returns passed or issues
5. If issues, `plan-phase.md` spawns planner with revision_context
6. Planner makes targeted updates (revision_mode)
7. Loop repeats up to 3 iterations or until passed
8. User sees status throughout
---
_Verified: 2026-01-16_
_Verifier: Claude (gsd-verifier)_