From c1fe62cc8690ee32aade8cc9c6e263fc8723be24 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Fri, 16 Jan 2026 07:39:14 -0600 Subject: [PATCH] docs(15): create phase plans for dedicated planner agent Phase 15: Dedicated Planner Agent - 3 plans in 2 waves - Wave 1: 15-01 (create gsd-planner agent) - Wave 2: 15-02, 15-03 (parallel - orchestrator refactor, deprecations) - Ready for execution Co-Authored-By: Claude Opus 4.5 --- .../15-dedicated-planner-agent/15-01-PLAN.md | 260 +++++++++++++++ .../15-dedicated-planner-agent/15-02-PLAN.md | 301 ++++++++++++++++++ .../15-dedicated-planner-agent/15-03-PLAN.md | 175 ++++++++++ 3 files changed, 736 insertions(+) create mode 100644 .planning/phases/15-dedicated-planner-agent/15-01-PLAN.md create mode 100644 .planning/phases/15-dedicated-planner-agent/15-02-PLAN.md create mode 100644 .planning/phases/15-dedicated-planner-agent/15-03-PLAN.md diff --git a/.planning/phases/15-dedicated-planner-agent/15-01-PLAN.md b/.planning/phases/15-dedicated-planner-agent/15-01-PLAN.md new file mode 100644 index 000000000..8934a8707 --- /dev/null +++ b/.planning/phases/15-dedicated-planner-agent/15-01-PLAN.md @@ -0,0 +1,260 @@ +--- +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: "||" +--- + + +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). + + + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md + + + +@.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 + + + + + + Task 1: Create gsd-planner agent file + agents/gsd-planner.md + +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. `` - 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. `` - 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. `` - Mandatory discovery protocol + - Level 0-3 from plan-phase.md + - When to research vs proceed + - Integration with Context7 for library questions + +4. `` - 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. `` - Building dependency graphs + - needs/creates analysis per task + - Wave assignment algorithm + - Vertical slices vs horizontal layers + - File ownership for parallel execution + +6. `` - 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.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. `` - Must-haves derivation + - Truths (observable behaviors) + - Artifacts (files that must exist) + - Key links (critical connections) + - From goal-backward.md + +9. `` - Checkpoint patterns + - Types and when to use each + - Execution protocol + - Authentication gates + - Anti-patterns (from checkpoints.md) + +10. `` - TDD plan structure + - When TDD improves quality + - TDD plan format vs standard plan + - RED-GREEN-REFACTOR cycle + - From tdd.md + +11. `` - 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. `` - 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. `` - Return format for orchestrator + - PLANNING COMPLETE (plans created, wave structure) + - CHECKPOINT REACHED (decision needed) + - Planning outcome summary + +14. `` - 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 + + +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 + + gsd-planner agent file created with all planning methodology consolidated + + + + Task 2: Verify agent completeness + agents/gsd-planner.md + +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. + + All 14 sections present with appropriate content depth + Agent verified complete with all planning methodology + + + + + +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 + + + +- 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 + + + +After completion, create `.planning/phases/15-dedicated-planner-agent/15-01-SUMMARY.md` + diff --git a/.planning/phases/15-dedicated-planner-agent/15-02-PLAN.md b/.planning/phases/15-dedicated-planner-agent/15-02-PLAN.md new file mode 100644 index 000000000..4e9bfd417 --- /dev/null +++ b/.planning/phases/15-dedicated-planner-agent/15-02-PLAN.md @@ -0,0 +1,301 @@ +--- +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" +--- + + +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. + + + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md + + + +@.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 + + + + + + Task 1: Refactor /gsd:plan-phase to thin orchestrator + commands/gsd/plan-phase.md + +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 + +[Brief - planning phases into PLAN.md files] + + + +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 + + + +Use Task tool to spawn gsd-planner agent with: +- Phase number +- Gap closure mode flag +- Project context paths + + + +[Format for showing plan summary and next steps] + +``` + +**DO NOT include in orchestrator:** +- Plan-phase workflow content +- Reference file content +- Task breakdown logic +- Discovery level definitions +- Scope estimation rules + + +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 + + /gsd:plan-phase refactored to thin orchestrator (~120-150 lines) + + + + Task 2: Deprecate workflows/plan-phase.md + get-shit-done/workflows/plan-phase.md + +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. + + +File exists with deprecation notice +Points to agents/gsd-planner.md +Explains why change was made + + workflows/plan-phase.md deprecated with redirect to agent + + + + Task 3: Create planner-subagent-prompt.md template + get-shit-done/templates/planner-subagent-prompt.md + +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 + + +**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 + + + + +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 + + + +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 + +\`\`\` + +## 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. + + +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) + + planner-subagent-prompt.md template created + + + + + +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 + + + +- /gsd:plan-phase refactored to thin orchestrator +- Workflow deprecated with redirect +- Subagent template created +- Pattern matches Phase 13-14 (debug, research) + + + +After completion, create `.planning/phases/15-dedicated-planner-agent/15-02-SUMMARY.md` + diff --git a/.planning/phases/15-dedicated-planner-agent/15-03-PLAN.md b/.planning/phases/15-dedicated-planner-agent/15-03-PLAN.md new file mode 100644 index 000000000..53e4771a5 --- /dev/null +++ b/.planning/phases/15-dedicated-planner-agent/15-03-PLAN.md @@ -0,0 +1,175 @@ +--- +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" +--- + + +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. + + + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md + + + +@.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 + + + + + + Task 1: Deprecate planning-specific reference 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 + +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: `` + +## 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 + + +All 4 files contain "DEPRECATED" header +All point to agents/gsd-planner.md +All explain which section contains the content + + Planning-specific references deprecated with agent pointers + + + + Task 2: Add deprecation note to phase-prompt template + get-shit-done/templates/phase-prompt.md + +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. + + +File has note pointing to agent +All existing content preserved +Template structure intact + + phase-prompt.md has clarifying note about agent relationship + + + + + +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 + + + +- Planning-specific references deprecated +- Shared references (checkpoints, tdd) preserved +- phase-prompt.md clarified but preserved +- Pattern matches Phase 13 deprecation approach + + + +After completion, create `.planning/phases/15-dedicated-planner-agent/15-03-SUMMARY.md` +