diff --git a/agents/gsd-codebase-mapper.md b/agents/gsd-codebase-mapper.md index 06f20eda2..b351be592 100644 --- a/agents/gsd-codebase-mapper.md +++ b/agents/gsd-codebase-mapper.md @@ -31,7 +31,7 @@ Your job: Explore thoroughly, then write document(s) directly. Return confirmati | refactor, cleanup | CONCERNS.md, ARCHITECTURE.md | | setup, config | STACK.md, STRUCTURE.md | -**`/gsd:execute-plan`** references codebase docs to: +**`/gsd:execute-phase`** references codebase docs to: - Follow existing conventions when writing code - Know where to place new files (STRUCTURE.md) - Match testing patterns (TESTING.md) diff --git a/agents/gsd-executor.md b/agents/gsd-executor.md index 774830d1a..bc9ed3fe9 100644 --- a/agents/gsd-executor.md +++ b/agents/gsd-executor.md @@ -8,10 +8,7 @@ color: yellow You are a GSD plan executor. You execute PLAN.md files atomically, creating per-task commits, handling deviations automatically, pausing at checkpoints, and producing SUMMARY.md files. -You are spawned by either: - -- `/gsd:execute-plan` command (single plan execution) -- `/gsd:execute-phase` orchestrator (parallel plan execution) +You are spawned by `/gsd:execute-phase` orchestrator. Your job: Execute the plan completely, commit each task, create SUMMARY.md, update STATE.md. diff --git a/commands/gsd/execute-plan.md b/commands/gsd/execute-plan.md deleted file mode 100644 index a92fbf43f..000000000 --- a/commands/gsd/execute-plan.md +++ /dev/null @@ -1,400 +0,0 @@ ---- -name: gsd:execute-plan -description: Execute a PLAN.md file -argument-hint: "[path-to-PLAN.md]" -allowed-tools: - - Read - - Glob - - Grep - - Bash - - Task - - TodoWrite - - AskUserQuestion ---- - - -@~/.claude/get-shit-done/references/ui-brand.md - - - -Execute a single PLAN.md file by spawning the `gsd-executor` subagent. - -Orchestrator stays lean: validate plan, spawn subagent, handle checkpoints, report completion. The `gsd-executor` has all execution logic baked in. - -Context budget: ~15% orchestrator, 100% fresh for subagent. - - - - - - - -Plan path: $ARGUMENTS - -@.planning/STATE.md -@.planning/config.json (if exists) - - - -1. **Validate plan exists** - - Confirm file at $ARGUMENTS exists - - Error if not found: "Plan not found: {path}" - -2. **Check if already executed** - - Derive SUMMARY path from plan path (replace PLAN.md with SUMMARY.md) - - If SUMMARY exists: "Plan already executed. SUMMARY: {path}" - - Offer: re-execute or exit - -3. **Parse plan identifiers** - Extract from path like `.planning/phases/03-auth/03-02-PLAN.md`: - - phase_number: `03` - - phase_name: `auth` - - plan_number: `02` - - plan_path: full path - -4. **Pre-execution summary (interactive mode only)** - Check config.json for mode. Skip this step if mode=yolo. - - Parse PLAN.md to extract: - - objective: First sentence or line from `` element - - task_count: Count of `` elements within tasks - - Display friendly summary before spawning: - ``` - ════════════════════════════════════════ - EXECUTING: {phase_number}-{plan_number} {phase_name} - ════════════════════════════════════════ - - Building: {objective one-liner} - Tasks: {task_count} - Files: {comma-separated file list} - - Full plan: {plan_path} - ════════════════════════════════════════ - ``` - - No confirmation needed. Proceed to spawn after displaying. - - In yolo mode, display abbreviated version: - ``` - ⚡ Executing {phase_number}-{plan_number}: {objective one-liner} - ``` - -5. **Spawn gsd-executor subagent** - - ``` - Task( - prompt="Execute plan at {plan_path} - -Plan: @{plan_path} -Project state: @.planning/STATE.md -Config: @.planning/config.json (if exists)", - subagent_type="gsd-executor", - description="Execute {phase}-{plan}" - ) - ``` - - The `gsd-executor` subagent has all execution logic baked in: - - Deviation rules (auto-fix bugs, critical gaps, blockers; ask for architectural) - - Checkpoint protocols (human-verify, decision, human-action) - - Commit formatting (per-task atomic commits) - - Summary creation - - State updates - -6. **Handle subagent return** - - If contains "## CHECKPOINT REACHED": Execute checkpoint_handling - - If contains "## PLAN COMPLETE": Verify SUMMARY exists, report success - -7. **Report completion and offer next steps** - - Show SUMMARY path - - Show commits from subagent return - - Route to next action (see ``) - - - -**MANDATORY: Present copy/paste-ready next command.** - -After plan completes, determine what's next: - -**Step 1: Count plans vs summaries in current phase** -```bash -ls -1 .planning/phases/[phase-dir]/*-PLAN.md 2>/dev/null | wc -l -ls -1 .planning/phases/[phase-dir]/*-SUMMARY.md 2>/dev/null | wc -l -``` - -**Step 2: Route based on counts** - -| Condition | Action | -|-----------|--------| -| summaries < plans | More plans remain → Route A | -| summaries = plans | Phase complete → Step 2.5 (verify phase goal) | - -**Step 2.5: Verify phase goal (only when phase complete)** - -When summaries = plans, verify the phase achieved its GOAL before proceeding: - -``` -Task( - prompt="Verify phase {phase_number} goal achievement - -Phase: {phase_number} - {phase_name} -Phase goal: {phase_goal_from_roadmap} -Phase directory: @.planning/phases/{phase_dir}/ - -Project context: -@.planning/ROADMAP.md -@.planning/REQUIREMENTS.md (if exists)", - subagent_type="gsd-verifier", - description="Verify phase {phase_number}" -) -``` - -Handle verification result: -- **If passed:** Continue to Step 2.6 (update requirements) -- **If gaps_found:** Create fix plans, execute them, re-verify (max 3 cycles) -- **If human_needed:** Present items to user, collect response - -**Step 2.6: Update requirements (only when verification passes)** - -When summaries = plans, update REQUIREMENTS.md before presenting completion: - -1. Get phase number from completed plan path -2. Read ROADMAP.md, find the phase's `Requirements:` line (e.g., "AUTH-01, AUTH-02") -3. Read REQUIREMENTS.md traceability table -4. For each REQ-ID in this phase: change Status from "Pending" to "Complete" -5. Write updated REQUIREMENTS.md -6. Stage for commit: `git add .planning/REQUIREMENTS.md` - -**Skip if:** REQUIREMENTS.md doesn't exist, or phase has no Requirements line in ROADMAP.md. - ---- - -**Route A: More plans remain in phase** - -Find next PLAN.md without matching SUMMARY.md. Present: - -``` -Plan {phase}-{plan} complete. -Summary: .planning/phases/{phase-dir}/{phase}-{plan}-SUMMARY.md - -{Y} of {X} plans complete for Phase {Z}. - ---- - -## ▶ Next Up - -**{phase}-{next-plan}: [Plan Name]** — [objective from PLAN.md] - -`/gsd:execute-plan .planning/phases/{phase-dir}/{phase}-{next-plan}-PLAN.md` - -`/clear` first → fresh context window - ---- -``` - ---- - -**Step 3: Check milestone status (only when phase complete)** - -Read ROADMAP.md. Find current phase number and highest phase in milestone. - -| Condition | Action | -|-----------|--------| -| current < highest | More phases → Route B | -| current = highest | Milestone complete → Route C | - ---- - -**Route B: Phase complete, more phases remain** - -``` -## ✓ Phase {Z}: {Name} Complete - -All {Y} plans finished. - ---- - -## ▶ Next Up - -**Phase {Z+1}: {Name}** — {Goal from ROADMAP.md} - -`/gsd:plan-phase {Z+1}` - -`/clear` first → fresh context window - ---- -``` - ---- - -**Route C: Milestone complete** - -``` -🎉 MILESTONE COMPLETE! - -## ✓ Phase {Z}: {Name} Complete - -All {N} phases finished. - ---- - -## ▶ Next Up - -`/gsd:complete-milestone` - -`/clear` first → fresh context window - ---- -``` - - - -When `gsd-executor` returns with checkpoint: - -**1. Parse return:** - -The subagent returns a structured checkpoint: -``` -## CHECKPOINT REACHED - -**Type:** [human-verify | decision | human-action] -**Plan:** {phase}-{plan} -**Progress:** {completed}/{total} tasks complete - -### Completed Tasks -| Task | Name | Commit | Files | -|------|------|--------|-------| -| 1 | [task name] | [hash] | [files] | - -### Current Task -**Task {N}:** [name] -**Status:** [blocked | awaiting verification | awaiting decision] -**Blocked by:** [specific blocker] - -### Checkpoint Details -[Type-specific content for user] - -### Awaiting -[What user needs to provide] -``` - -**2. Present checkpoint to user:** - -Display rich formatted checkpoint based on type: - -**For human-verify:** -``` -╔═══════════════════════════════════════════════════════╗ -║ CHECKPOINT: Verification Required ║ -╚═══════════════════════════════════════════════════════╝ - -Progress: {X}/{Y} tasks complete -Task: {task name} - -Built: {what-built from checkpoint details} - -How to verify: - {numbered verification steps} - -──────────────────────────────────────────────────────── -→ YOUR ACTION: Type "approved" or describe issues -──────────────────────────────────────────────────────── -``` - -**For human-action (auth gate):** -``` -╔═══════════════════════════════════════════════════════╗ -║ CHECKPOINT: Action Required ║ -╚═══════════════════════════════════════════════════════╝ - -Progress: {X}/{Y} tasks complete -Task: {task name} - -Attempted: {automation attempted} -Error: {error encountered} - -What you need to do: - {numbered instructions} - -I'll verify: {verification} - -──────────────────────────────────────────────────────── -→ YOUR ACTION: Type "done" when complete -──────────────────────────────────────────────────────── -``` - -**For decision:** -``` -╔═══════════════════════════════════════════════════════╗ -║ CHECKPOINT: Decision Required ║ -╚═══════════════════════════════════════════════════════╝ - -Progress: {X}/{Y} tasks complete -Task: {task name} - -Decision: {what's being decided} - -Context: {why this matters} - -Options: - 1. {option-a} - {name} - Pros: {benefits} - Cons: {tradeoffs} - - 2. {option-b} - {name} - Pros: {benefits} - Cons: {tradeoffs} - -──────────────────────────────────────────────────────── -→ YOUR ACTION: Select option-a or option-b -──────────────────────────────────────────────────────── -``` - -**3. Collect response:** -Wait for user input: -- human-verify: "approved" or description of issues -- decision: option selection -- human-action: "done" when complete - -**4. Spawn fresh continuation agent:** - -Spawn fresh `gsd-executor` with continuation context: - -``` -Task( - prompt="Continue executing plan at {plan_path} - - -{completed_tasks_table from checkpoint return} - - - -Resume from: Task {N} - {task_name} -User response: {user_response} -{resume_instructions based on checkpoint type} - - -Plan: @{plan_path} -Project state: @.planning/STATE.md", - subagent_type="gsd-executor", - description="Continue {phase}-{plan}" -) -``` - -The `gsd-executor` has continuation handling baked in — it will verify previous commits and resume correctly. - -**Why fresh agent, not resume:** -Task tool resume fails after multiple tool calls (presenting to user, waiting for response). Fresh agent with state handoff is the correct pattern. - -**5. Repeat:** -Continue handling returns until "## PLAN COMPLETE" or user stops. - - - -- [ ] Plan executed (SUMMARY.md created) -- [ ] All checkpoints handled -- [ ] If phase complete: Phase goal verified (gsd-verifier spawned, VERIFICATION.md created) -- [ ] If phase complete: REQUIREMENTS.md updated (phase requirements marked Complete) -- [ ] User informed of completion and next steps - diff --git a/commands/gsd/help.md b/commands/gsd/help.md index 66ecdade4..987fd7654 100644 --- a/commands/gsd/help.md +++ b/commands/gsd/help.md @@ -127,22 +127,13 @@ Result: Creates `.planning/phases/01-foundation/01-01-PLAN.md` ### Execution -**`/gsd:execute-plan `** -Execute a single PLAN.md file. - -- Runs plan tasks sequentially -- Creates SUMMARY.md after completion -- Updates STATE.md with accumulated context -- Use for interactive execution with checkpoints - -Usage: `/gsd:execute-plan .planning/phases/01-foundation/01-01-PLAN.md` - **`/gsd:execute-phase `** -Execute all plans in a phase with wave-based parallelization. +Execute all plans in a phase. - Groups plans by wave (from frontmatter), executes waves sequentially - Plans within each wave run in parallel via Task tool - Verifies phase goal after all plans complete +- Updates REQUIREMENTS.md, ROADMAP.md, STATE.md Usage: `/gsd:execute-phase 5` @@ -368,7 +359,7 @@ Change anytime by editing `.planning/config.json` ``` /gsd:insert-phase 5 "Critical security fix" /gsd:plan-phase 5.1 -/gsd:execute-plan .planning/phases/05.1-critical-security-fix/05.1-01-PLAN.md +/gsd:execute-phase 5.1 ``` **Completing a milestone:** diff --git a/commands/gsd/plan-phase.md b/commands/gsd/plan-phase.md index 96368d234..13f645e26 100644 --- a/commands/gsd/plan-phase.md +++ b/commands/gsd/plan-phase.md @@ -251,7 +251,7 @@ Fill prompt and spawn: -Output consumed by /gsd:execute-phase or /gsd:execute-plan +Output consumed by /gsd:execute-phase Plans must be executable prompts with: - Frontmatter (wave, depends_on, files_modified, autonomous) diff --git a/commands/gsd/progress.md b/commands/gsd/progress.md index d2fd3651f..09a81c3cd 100644 --- a/commands/gsd/progress.md +++ b/commands/gsd/progress.md @@ -154,7 +154,7 @@ Read its `` section. **{phase}-{plan}: [Plan Name]** — [objective summary from PLAN.md] -`/gsd:execute-plan [full-path-to-PLAN.md]` +`/gsd:execute-phase {phase}` `/clear` first → fresh context window @@ -226,7 +226,7 @@ UAT.md exists with gaps (diagnosed issues). User needs to plan fixes. --- **Also available:** -- `/gsd:execute-plan [path]` — continue with other work first +- `/gsd:execute-phase {phase}` — execute phase plans - `/gsd:verify-work {phase}` — run more UAT testing --- @@ -359,7 +359,7 @@ Ready to plan the next milestone. - [ ] Rich context provided (recent work, decisions, issues) - [ ] Current position clear with visual progress - [ ] What's next clearly explained -- [ ] Smart routing: /gsd:execute-plan if plan exists, /gsd:plan-phase if not +- [ ] Smart routing: /gsd:execute-phase if plans exist, /gsd:plan-phase if not - [ ] User confirms before any action - [ ] Seamless handoff to appropriate gsd command diff --git a/get-shit-done/references/continuation-format.md b/get-shit-done/references/continuation-format.md index 090ab997b..92e609c67 100644 --- a/get-shit-done/references/continuation-format.md +++ b/get-shit-done/references/continuation-format.md @@ -44,7 +44,7 @@ Standard format for presenting next steps after completing a command or workflow **02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry -`/gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md` +`/gsd:execute-phase 2` `/clear` first → fresh context window @@ -69,7 +69,7 @@ Add note that this is the last plan and what comes after: **02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry Final plan in Phase 2 -`/gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md` +`/gsd:execute-phase 2` `/clear` first → fresh context window @@ -220,7 +220,7 @@ Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with slidi ## To Continue Run `/clear`, then paste: -/gsd:execute-plan .planning/phases/02-auth/02-03-PLAN.md +/gsd:execute-phase 2 ``` User has no idea what 02-03 is about. diff --git a/get-shit-done/templates/planner-subagent-prompt.md b/get-shit-done/templates/planner-subagent-prompt.md index 9dc6f8e06..c1fc0d208 100644 --- a/get-shit-done/templates/planner-subagent-prompt.md +++ b/get-shit-done/templates/planner-subagent-prompt.md @@ -34,7 +34,7 @@ Template for spawning gsd-planner agent. The agent contains all planning experti -Output consumed by /gsd:execute-phase or /gsd:execute-plan +Output consumed by /gsd:execute-phase Plans must be executable prompts with: - Frontmatter (wave, depends_on, files_modified, autonomous) - Tasks in XML format diff --git a/get-shit-done/workflows/execute-plan.md b/get-shit-done/workflows/execute-plan.md index 574b10dc8..407762f3a 100644 --- a/get-shit-done/workflows/execute-plan.md +++ b/get-shit-done/workflows/execute-plan.md @@ -1196,7 +1196,7 @@ You will NOT be resumed. A new agent continues from where you stopped, using you **How to know if you were spawned:** -If you're reading this workflow because an orchestrator spawned you (vs running directly from /gsd:execute-plan), the orchestrator's prompt will include checkpoint return instructions. Follow those instructions when you hit a checkpoint. +If you're reading this workflow because an orchestrator spawned you (vs running directly), the orchestrator's prompt will include checkpoint return instructions. Follow those instructions when you hit a checkpoint. **If running in main context (not spawned):** @@ -1701,7 +1701,7 @@ Summary: .planning/phases/{phase-dir}/{phase}-{plan}-SUMMARY.md **{phase}-{next-plan}: [Plan Name]** — [objective from next PLAN.md] -`/gsd:execute-plan .planning/phases/{phase-dir}/{phase}-{next-plan}-PLAN.md` +`/gsd:execute-phase {phase}` `/clear` first → fresh context window diff --git a/get-shit-done/workflows/resume-project.md b/get-shit-done/workflows/resume-project.md index 15b7ba470..57acd090e 100644 --- a/get-shit-done/workflows/resume-project.md +++ b/get-shit-done/workflows/resume-project.md @@ -180,9 +180,7 @@ What would you like to do? [Primary action based on state - e.g.:] 1. Resume interrupted agent (/gsd:resume-task) [if interrupted agent found] OR -1. Resume from checkpoint (/gsd:execute-plan .planning/phases/XX-name/.continue-here-02-01.md) - OR -1. Execute next plan (/gsd:execute-plan .planning/phases/XX-name/02-02-PLAN.md) +1. Execute phase (/gsd:execute-phase {phase}) OR 1. Discuss Phase 3 context (/gsd:discuss-phase 3) [if CONTEXT.md missing] OR @@ -217,7 +215,7 @@ Based on user selection, route to appropriate workflow: **{phase}-{plan}: [Plan Name]** — [objective from PLAN.md] - `/gsd:execute-plan [path]` + `/gsd:execute-phase {phase}` `/clear` first → fresh context window