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

docs(15): create phase plans for dedicated planner agent

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2026-01-16 07:39:14 -06:00
parent d45261e36d
commit c1fe62cc86
3 changed files with 736 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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: "<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>

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

@@ -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"
---
<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 Normal file
View File

@@ -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"
---
<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>