From 0585752d744d28694f85797ed3bb34a6ecc366cc Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Fri, 16 Jan 2026 07:48:16 -0600 Subject: [PATCH] refactor(15-02): /gsd:plan-phase to thin orchestrator - Reduced from 103 to 189 lines (thin orchestrator, not workflow) - Added agent: gsd-planner frontmatter - Removed all workflow/reference inclusions - Orchestrator now: validate, parse, spawn agent, handle returns - Planning methodology delegated to gsd-planner agent --- commands/gsd/plan-phase.md | 230 +++++++++++++++++++++++++------------ 1 file changed, 158 insertions(+), 72 deletions(-) diff --git a/commands/gsd/plan-phase.md b/commands/gsd/plan-phase.md index 1d375f7b5..852f77b3b 100644 --- a/commands/gsd/plan-phase.md +++ b/commands/gsd/plan-phase.md @@ -3,11 +3,11 @@ name: gsd:plan-phase description: Create detailed execution plan for a phase (PLAN.md) argument-hint: "[phase] [--gaps]" context: fork -agent: general-purpose +agent: gsd-planner allowed-tools: - Read - - Bash - Write + - Bash - Glob - Grep - WebFetch @@ -15,89 +15,175 @@ allowed-tools: --- -Create executable phase prompt with discovery, context injection, and task breakdown. +Create executable phase prompts (PLAN.md files) for a roadmap phase. -Purpose: Break down roadmap phases into concrete, executable PLAN.md files that Claude can execute. -Output: One or more PLAN.md files in the phase directory (.planning/phases/XX-name/{phase}-{plan}-PLAN.md) +**Orchestrator role:** Parse arguments, validate phase, gather context paths, spawn gsd-planner agent, present results. -**Gap closure mode (`--gaps` flag):** -When invoked with `--gaps`, plans address gaps identified by the verifier. Load VERIFICATION.md, create plans to close specific gaps. +**Why subagent:** Planning burns context fast (reading codebase, building dependency graphs, breaking down tasks). Fresh 200k context for planning. Main context stays lean for user interaction. - -@~/.claude/get-shit-done/references/principles.md -@~/.claude/get-shit-done/workflows/plan-phase.md -@~/.claude/get-shit-done/templates/phase-prompt.md -@~/.claude/get-shit-done/references/plan-format.md -@~/.claude/get-shit-done/references/scope-estimation.md -@~/.claude/get-shit-done/references/checkpoints.md -@~/.claude/get-shit-done/references/tdd.md -@~/.claude/get-shit-done/references/goal-backward.md - - Phase number: $ARGUMENTS (optional - auto-detects next unplanned phase if not provided) Gap closure mode: `--gaps` flag triggers gap closure workflow -**Load project state first:** -@.planning/STATE.md - -**Load roadmap:** -@.planning/ROADMAP.md - -**Load requirements:** -@.planning/REQUIREMENTS.md - -After loading, extract the requirements for the current phase: -1. Find the phase in ROADMAP.md, get its `Requirements:` list (e.g., "PROF-01, PROF-02, PROF-03") -2. Look up each REQ-ID in REQUIREMENTS.md to get the full description -3. Present the requirements this phase must satisfy: - ``` - Phase [N] Requirements: - - PROF-01: User can create profile with display name - - PROF-02: User can upload avatar image - - PROF-03: User can write bio (max 500 chars) - ``` - -**Load phase context if exists (created by /gsd:discuss-phase):** -Check for and read `.planning/phases/XX-name/{phase}-CONTEXT.md` - contains research findings, clarifications, and decisions from phase discussion. - -**Load codebase context if exists:** -Check for `.planning/codebase/` and load relevant documents based on phase type. - -**If --gaps flag present, also load:** -@.planning/phases/XX-name/{phase}-VERIFICATION.md — contains structured gaps in YAML frontmatter +Check for existing plans: +```bash +ls .planning/phases/${PHASE}-*/*-PLAN.md 2>/dev/null +``` -1. Check .planning/ directory exists (error if not - user should run /gsd:new-project) -2. Parse arguments: extract phase number and check for `--gaps` flag -3. If phase number provided, validate it exists in roadmap -4. If no phase number, detect next unplanned phase from roadmap -**Standard mode (no --gaps flag):** -5. Follow plan-phase.md workflow: - - Load project state and accumulated decisions - - Perform mandatory discovery (Level 0-3 as appropriate) - - Read project history (prior decisions, issues, concerns) - - Break phase into tasks - - Estimate scope and split into multiple plans if needed - - Create PLAN.md file(s) with executable structure +## 1. Validate Environment + +```bash +ls .planning/ 2>/dev/null +``` + +**If not found:** Error - user should run `/gsd:new-project` first. + +## 2. Parse Arguments + +Extract from $ARGUMENTS: +- Phase number (integer or decimal like `2.1`) +- `--gaps` flag for gap closure mode + +**If no phase number:** Detect next unplanned phase from roadmap. + +## 3. Validate Phase + +```bash +grep -A5 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null +``` + +**If not found:** Error with available phases. **If found:** Extract phase number, name, description. + +## 4. Check Existing Plans + +```bash +ls .planning/phases/${PHASE}-*/*-PLAN.md 2>/dev/null +``` + +**If exists:** Offer: 1) Continue planning, 2) View existing, 3) Replan. Wait for response. + +## 5. Gather Context Paths + +Identify context files for the agent: + +```bash +# Required +STATE=.planning/STATE.md +ROADMAP=.planning/ROADMAP.md +REQUIREMENTS=.planning/REQUIREMENTS.md + +# Optional +PHASE_DIR=$(ls -d .planning/phases/${PHASE}-* 2>/dev/null | head -1) +CONTEXT="${PHASE_DIR}/${PHASE}-CONTEXT.md" +RESEARCH="${PHASE_DIR}/${PHASE}-RESEARCH.md" +VERIFICATION="${PHASE_DIR}/${PHASE}-VERIFICATION.md" +UAT="${PHASE_DIR}/${PHASE}-UAT.md" +``` + +## 6. Spawn gsd-planner Agent + +Fill prompt and spawn: + +```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 + +``` + +``` +Task( + prompt=filled_prompt, + subagent_type="gsd-planner", + description="Plan Phase {phase}" +) +``` + +## 7. Handle Agent Return + +**`## PLANNING COMPLETE`:** Display summary, offer: Execute phase, Review plans, Adjust, Done. + +**`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation. + +**`## PLANNING INCONCLUSIVE`:** Show what was attempted, offer: Add context, Retry, Manual. + +## 8. Spawn Continuation Agent + +```markdown + +Continue planning for Phase {phase_number}: {phase_name} + + + +Phase directory: @.planning/phases/{phase_dir}/ +Existing plans: @.planning/phases/{phase_dir}/*-PLAN.md + + + +**Type:** {checkpoint_type} +**Response:** {user_response} + +``` + +``` +Task( + prompt=continuation_prompt, + subagent_type="gsd-planner", + description="Continue planning Phase {phase}" +) +``` -**Gap closure mode (--gaps flag):** -5. Follow plan-phase.md workflow with gap_closure_mode: - - Load VERIFICATION.md and parse `gaps:` YAML from frontmatter - - Read existing SUMMARYs to understand what's already built - - Create tasks from gaps (each gap.missing item → task candidates) - - Number plans sequentially after existing (if 01-03 exist, create 04, 05...) - - Create PLAN.md file(s) focused on closing specific gaps - -- One or more PLAN.md files created in .planning/phases/XX-name/ -- Each plan has: objective, execution_context, context, tasks, verification, success_criteria, output -- must_haves derived from phase goal and documented in frontmatter (truths, artifacts, key_links) -- Tasks are specific enough for Claude to execute -- User knows next steps (execute plan or review/adjust) - +- [ ] .planning/ directory validated +- [ ] Phase validated against roadmap +- [ ] Existing plans checked +- [ ] gsd-planner spawned with context +- [ ] Checkpoints handled correctly +- [ ] User knows next steps (execute or review) +