get-shit-done-cc 1.4.3 → 1.4.5

package/commands/gsd/_archive/execute-phase.md

@@ -0,0 +1,120 @@
+---
+name: gsd:execute-phase
+description: Execute all plans in a phase with intelligent parallelization
+argument-hint: "<phase-number>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - TaskOutput
+  - AskUserQuestion
+  - SlashCommand
+---
+
+<objective>
+Execute all unexecuted plans in a phase with parallel agent spawning.
+
+Analyzes plan dependencies to identify independent plans that can run concurrently.
+Spawns background agents for parallel execution, each agent commits its own tasks atomically.
+
+**Critical constraint:** One subagent per plan, always. This is for context isolation, not parallelization. Even strictly sequential plans spawn separate subagents so each starts with fresh 200k context at 0%.
+
+Use this command when:
+- Phase has 2+ unexecuted plans
+- Want "walk away, come back to completed work" execution
+- Plans have clear dependency boundaries
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/execute-plan.md
+@~/.claude/get-shit-done/workflows/execute-phase.md
+@~/.claude/get-shit-done/templates/summary.md
+@~/.claude/get-shit-done/references/checkpoints.md
+@~/.claude/get-shit-done/references/tdd.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+@.planning/STATE.md
+@.planning/config.json
+</context>
+
+<process>
+1. Validate phase exists in roadmap
+2. Find all PLAN.md files without matching SUMMARY.md
+3. If 0 or 1 plans: suggest /gsd:execute-plan instead
+4. If 2+ plans: follow execute-phase.md workflow
+5. Monitor parallel agents until completion
+6. Present results and next steps
+</process>
+
+<execution_strategies>
+**Strategy A: Fully Autonomous** (no checkpoints)
+
+- Spawn subagent to execute entire plan
+- Subagent creates SUMMARY.md and commits
+- Main context: orchestration only (~5% usage)
+
+**Strategy B: Segmented** (has verify-only checkpoints)
+
+- Execute in segments between checkpoints
+- Subagent for autonomous segments
+- Main context for checkpoints
+- Aggregate results → SUMMARY → commit
+
+**Strategy C: Decision-Dependent** (has decision checkpoints)
+
+- Execute in main context
+- Decision outcomes affect subsequent tasks
+- Quality maintained through small scope (2-3 tasks per plan)
+</execution_strategies>
+
+<deviation_rules>
+During execution, handle discoveries automatically:
+
+1. **Auto-fix bugs** - Fix immediately, document in Summary
+2. **Auto-add critical** - Security/correctness gaps, add and document
+3. **Auto-fix blockers** - Can't proceed without fix, do it and document
+4. **Ask about architectural** - Major structural changes, stop and ask user
+5. **Log enhancements** - Nice-to-haves, log to ISSUES.md, continue
+
+Only rule 4 requires user intervention.
+</deviation_rules>
+
+<commit_rules>
+**Per-Task Commits:**
+
+After each task completes:
+1. Stage only files modified by that task
+2. Commit with format: `{type}({phase}-{plan}): {task-name}`
+3. Types: feat, fix, test, refactor, perf, chore
+4. Record commit hash for SUMMARY.md
+
+**Plan Metadata Commit:**
+
+After all tasks complete:
+1. Stage planning artifacts only: PLAN.md, SUMMARY.md, STATE.md, ROADMAP.md
+2. Commit with format: `docs({phase}-{plan}): complete [plan-name] plan`
+3. NO code files (already committed per-task)
+
+**NEVER use:**
+- `git add .`
+- `git add -A`
+- `git add src/` or any broad directory
+
+**Always stage files individually.**
+</commit_rules>
+
+<success_criteria>
+- [ ] All independent plans executed in parallel
+- [ ] Dependent plans executed after dependencies complete
+- [ ] Each task committed individually (feat/fix/test/refactor)
+- [ ] All SUMMARY.md files created
+- [ ] Metadata committed by orchestrator
+- [ ] Phase progress updated
+</success_criteria>

package/commands/gsd/execute-phase.md

@@ -1,120 +1,113 @@
 ---
 name: gsd:execute-phase
-description: Execute all plans in a phase with intelligent parallelization
+description: Execute all plans in a phase with wave-based parallelization
 argument-hint: "<phase-number>"
 allowed-tools:
   - Read
-  - Write
-  - Edit
-  - Bash
   - Glob
   - Grep
+  - Bash
   - Task
-  - TaskOutput
+  - TodoWrite
   - AskUserQuestion
-  - SlashCommand
 ---
 
 <objective>
-Execute all unexecuted plans in a phase with parallel agent spawning.
-
-Analyzes plan dependencies to identify independent plans that can run concurrently.
-Spawns background agents for parallel execution, each agent commits its own tasks atomically.
+Execute all plans in a phase using wave-based parallel execution.
 
-**Critical constraint:** One subagent per plan, always. This is for context isolation, not parallelization. Even strictly sequential plans spawn separate subagents so each starts with fresh 200k context at 0%.
+Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent loads the full execute-plan context and handles its own plan.
 
-Use this command when:
-- Phase has 2+ unexecuted plans
-- Want "walk away, come back to completed work" execution
-- Plans have clear dependency boundaries
+Context budget: ~15% orchestrator, 100% fresh per subagent.
 </objective>
 
 <execution_context>
-@~/.claude/get-shit-done/workflows/execute-plan.md
 @~/.claude/get-shit-done/workflows/execute-phase.md
-@~/.claude/get-shit-done/templates/summary.md
-@~/.claude/get-shit-done/references/checkpoints.md
-@~/.claude/get-shit-done/references/tdd.md
+@~/.claude/get-shit-done/templates/subagent-task-prompt.md
 </execution_context>
 
 <context>
-Phase number: $ARGUMENTS (required)
+Phase: $ARGUMENTS
 
+@.planning/ROADMAP.md
 @.planning/STATE.md
-@.planning/config.json
 </context>
 
 <process>
-1. Validate phase exists in roadmap
-2. Find all PLAN.md files without matching SUMMARY.md
-3. If 0 or 1 plans: suggest /gsd:execute-plan instead
-4. If 2+ plans: follow execute-phase.md workflow
-5. Monitor parallel agents until completion
-6. Present results and next steps
+1. **Validate phase exists**
+   - Find phase directory matching argument
+   - Count PLAN.md files
+   - Error if no plans found
+
+2. **Discover plans**
+   - List all *-PLAN.md files in phase directory
+   - Check which have *-SUMMARY.md (already complete)
+   - Build list of incomplete plans
+
+3. **Analyze dependencies**
+   - Read each plan's `<context>` section
+   - Detect cross-references to other plans' outputs
+   - Build dependency graph
+
+4. **Group into waves**
+   - Wave 1: Plans with no dependencies
+   - Wave N: Plans depending only on earlier waves
+   - Report wave structure to user
+
+5. **Execute waves**
+   For each wave:
+   - Fill subagent-task-prompt template for each plan
+   - Spawn all agents in wave simultaneously (parallel Task calls)
+   - Wait for completion (Task blocks)
+   - Verify SUMMARYs created
+   - Proceed to next wave
+
+6. **Aggregate results**
+   - Collect summaries from all plans
+   - Report phase completion status
+   - Update ROADMAP.md
+
+7. **Offer next steps**
+   - More phases → `/gsd:plan-phase {next}`
+   - Milestone complete → `/gsd:complete-milestone`
 </process>
 
-<execution_strategies>
-**Strategy A: Fully Autonomous** (no checkpoints)
-
-- Spawn subagent to execute entire plan
-- Subagent creates SUMMARY.md and commits
-- Main context: orchestration only (~5% usage)
-
-**Strategy B: Segmented** (has verify-only checkpoints)
-
-- Execute in segments between checkpoints
-- Subagent for autonomous segments
-- Main context for checkpoints
-- Aggregate results → SUMMARY → commit
-
-**Strategy C: Decision-Dependent** (has decision checkpoints)
-
-- Execute in main context
-- Decision outcomes affect subsequent tasks
-- Quality maintained through small scope (2-3 tasks per plan)
-</execution_strategies>
-
-<deviation_rules>
-During execution, handle discoveries automatically:
+<wave_execution>
+**Parallel spawning:**
 
-1. **Auto-fix bugs** - Fix immediately, document in Summary
-2. **Auto-add critical** - Security/correctness gaps, add and document
-3. **Auto-fix blockers** - Can't proceed without fix, do it and document
-4. **Ask about architectural** - Major structural changes, stop and ask user
-5. **Log enhancements** - Nice-to-haves, log to ISSUES.md, continue
+Spawn all plans in a wave with a single message containing multiple Task calls:
 
-Only rule 4 requires user intervention.
-</deviation_rules>
+```
+Task(prompt=filled_template_for_plan_01, subagent_type="general-purpose")
+Task(prompt=filled_template_for_plan_02, subagent_type="general-purpose")
+Task(prompt=filled_template_for_plan_03, subagent_type="general-purpose")
+```
 
-<commit_rules>
-**Per-Task Commits:**
+All three run in parallel. Task tool blocks until all complete.
 
-After each task completes:
-1. Stage only files modified by that task
-2. Commit with format: `{type}({phase}-{plan}): {task-name}`
-3. Types: feat, fix, test, refactor, perf, chore
-4. Record commit hash for SUMMARY.md
+**No polling.** No background agents. No TaskOutput loops.
+</wave_execution>
 
-**Plan Metadata Commit:**
+<checkpoint_detection>
+Before adding a plan to a parallel wave, scan for checkpoints:
 
-After all tasks complete:
-1. Stage planning artifacts only: PLAN.md, SUMMARY.md, STATE.md, ROADMAP.md
-2. Commit with format: `docs({phase}-{plan}): complete [plan-name] plan`
-3. NO code files (already committed per-task)
+```bash
+grep -c 'type="checkpoint' {plan_path}
+```
 
-**NEVER use:**
-- `git add .`
-- `git add -A`
-- `git add src/` or any broad directory
+**If checkpoints > 0:**
+- Plan requires user interaction
+- Execute in main context OR as solo subagent (not parallel)
+- User interaction flows through normally
 
-**Always stage files individually.**
-</commit_rules>
+**If checkpoints = 0:**
+- Fully autonomous
+- Safe for parallel wave execution
+</checkpoint_detection>
 
 <success_criteria>
-- [ ] All independent plans executed in parallel
-- [ ] Dependent plans executed after dependencies complete
-- [ ] Each task committed individually (feat/fix/test/refactor)
-- [ ] All SUMMARY.md files created
-- [ ] Metadata committed by orchestrator
-- [ ] Phase progress updated
+- [ ] All incomplete plans in phase executed
+- [ ] Each plan has SUMMARY.md
+- [ ] STATE.md reflects phase completion
+- [ ] ROADMAP.md updated
+- [ ] User informed of next steps
 </success_criteria>

package/get-shit-done/references/plan-format.md

@@ -10,14 +10,50 @@ A plan is Claude-executable when Claude can read the PLAN.md and immediately sta
 If Claude has to guess, interpret, or make assumptions - the task is too vague.
 </core_principle>
 
+<frontmatter>
+Every PLAN.md starts with YAML frontmatter:
+
+```yaml
+---
+phase: XX-name
+plan: NN
+type: execute
+depends_on: []              # Plan IDs this plan requires (e.g., ["01-01"])
+files_modified: []          # Files this plan modifies
+autonomous: true            # false if plan has checkpoints
+domain: [optional]          # Domain skill if loaded
+---
+```
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `phase` | Yes | Phase identifier (e.g., `01-foundation`) |
+| `plan` | Yes | Plan number within phase (e.g., `01`, `02`) |
+| `type` | Yes | `execute` for standard plans, `tdd` for TDD plans |
+| `depends_on` | Yes | Array of plan IDs this plan requires. **Empty = Wave 1 candidate** |
+| `files_modified` | Yes | Files this plan touches. Used for conflict detection |
+| `autonomous` | Yes | `true` if no checkpoints, `false` if has checkpoints |
+| `domain` | No | Domain skill if loaded (e.g., `next-js`) |
+
+**Wave assignment:** `/gsd:execute-phase` reads `depends_on` and `files_modified` to build execution waves:
+- `depends_on: []` + no file conflicts → Wave 1 (parallel)
+- `depends_on: ["XX-YY"]` → runs after plan XX-YY completes
+- Shared `files_modified` → sequential by plan number
+
+**Checkpoint detection:** Plans with `autonomous: false` require user interaction. Execute after parallel wave or in main context.
+</frontmatter>
+
 <prompt_structure>
 Every PLAN.md follows this XML structure:
 
 ```markdown
 ---
 phase: XX-name
+plan: NN
 type: execute
-domain: [optional]
+depends_on: []
+files_modified: [path/to/file.ts]
+autonomous: true
 ---
 
 <objective>
@@ -26,9 +62,19 @@ Purpose: [...]
 Output: [...]
 </objective>
 
+<execution_context>
+@~/.claude/get-shit-done/workflows/execute-plan.md
+@~/.claude/get-shit-done/templates/summary.md
+[If checkpoints exist:]
+@~/.claude/get-shit-done/references/checkpoints.md
+</execution_context>
+
 <context>
 @.planning/PROJECT.md
 @.planning/ROADMAP.md
+@.planning/STATE.md
+[Only if genuinely needed:]
+@.planning/phases/XX-name/XX-YY-SUMMARY.md
 @relevant/source/files.ts
 </context>
 
@@ -240,6 +286,14 @@ Use for: Technology selection, architecture decisions, design choices, feature p
 
 **Golden rule:** If Claude CAN automate it, Claude MUST automate it.
 
+**Checkpoint impact on parallelization:**
+- Plans with checkpoints set `autonomous: false` in frontmatter
+- Non-autonomous plans execute after parallel wave or in main context
+- Subagent pauses at checkpoint, returns to orchestrator
+- Orchestrator presents checkpoint to user
+- User responds
+- Orchestrator resumes agent with `resume: agent_id`
+
 See `./checkpoints.md` for comprehensive checkpoint guidance.
 </task_types>
 
@@ -274,14 +328,22 @@ Use @file references to load context for the prompt:
 ```markdown
 <context>
 @.planning/PROJECT.md           # Project vision
-@.planning/ROADMAP.md         # Phase structure
-@.planning/phases/02-auth/DISCOVERY.md  # Discovery results
-@src/lib/db.ts                # Existing database setup
-@src/types/user.ts            # Existing type definitions
+@.planning/ROADMAP.md           # Phase structure
+@.planning/STATE.md             # Current position
+
+# Only include prior SUMMARY if genuinely needed:
+# - This plan imports types from prior plan
+# - Prior plan made decision affecting this plan
+# Independent plans need NO prior SUMMARY references.
+
+@src/lib/db.ts                  # Existing database setup
+@src/types/user.ts              # Existing type definitions
 </context>
 ```
 
 Reference files that Claude needs to understand before implementing.
+
+**Anti-pattern:** Reflexive chaining (02 refs 01, 03 refs 02). Only reference what you actually need.
 </context_references>
 
 <verification_section>
@@ -320,22 +382,7 @@ Specify the SUMMARY.md structure:
 
 ```markdown
 <output>
-After completion, create `.planning/phases/XX-name/SUMMARY.md`:
-
-# Phase X: Name Summary
-
-**[Substantive one-liner]**
-
-## Accomplishments
-
-## Files Created/Modified
-
-## Decisions Made
-
-## Issues Encountered
-
-## Next Phase Readiness
-
+After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 </output>
 ```
 

package/get-shit-done/references/scope-estimation.md

@@ -78,103 +78,78 @@ See `~/.claude/get-shit-done/references/tdd.md` for TDD plan structure.
 </split_signals>
 
 <splitting_strategies>
-**By subsystem:** Auth → 01: DB models, 02: API routes, 03: Protected routes, 04: UI components
+**Vertical slices (default):** Group by feature, not by layer.
 
-**By dependency:** Payments → 01: Stripe setup, 02: Subscription logic, 03: Frontend integration
+```
+PREFER: Plan 01 = User (model + API + UI)
+        Plan 02 = Product (model + API + UI)
+        Plan 03 = Order (model + API + UI)
 
-**By complexity:** Dashboard → 01: Layout shell, 02: Data fetching, 03: Visualization
+AVOID:  Plan 01 = All models
+        Plan 02 = All APIs (depends on 01)
+        Plan 03 = All UIs (depends on 02)
+```
 
-**By verification:** Deploy → 01: Vercel setup (checkpoint), 02: Env config (auto), 03: CI/CD (checkpoint)
-</splitting_strategies>
+Vertical slices maximize parallelism: [01, 02, 03] run simultaneously.
+Horizontal layers force sequential execution: 01 → 02 → 03.
 
-<parallel_aware_splitting>
-**When parallelization is enabled, optimize for plan independence.**
-
-<philosophy_shift>
-| Aspect | Sequential Planning | Parallel-Aware Planning |
-|--------|---------------------|------------------------|
-| Grouping | By workflow stage | By vertical slice |
-| Dependencies | Implicit (later plans reference earlier) | Explicit (only when genuinely needed) |
-| File ownership | Overlap acceptable | Exclusive where possible |
-| SUMMARY refs | Chain pattern (02 refs 01, 03 refs 02) | Minimal (only for real data deps) |
-| Wave result | Most plans in Wave 2+ | More plans in Wave 1 |
-</philosophy_shift>
-
-<vertical_slice_example>
-**Sequential (creates chain):**
+**By dependency:** Only when genuine dependencies exist.
 ```
-Plan 01: Create User model, Product model, Order model
-Plan 02: Create /api/users, /api/products, /api/orders
-Plan 03: Create UserList UI, ProductList UI, OrderList UI
+Plan 01: Auth foundation (middleware, JWT utils)
+Plan 02: Protected features (uses auth from 01)
 ```
-Result: 02 depends on 01 (needs models), 03 depends on 02 (needs APIs)
-Waves: [01] → [02] → [03] (fully sequential)
 
-**Parallel-aware (creates independence):**
+**By complexity:** When one slice is much heavier.
 ```
-Plan 01: User feature (model + API + UI)
-Plan 02: Product feature (model + API + UI)
-Plan 03: Order feature (model + API + UI)
+Plan 01: Dashboard layout shell
+Plan 02: Data fetching and state
+Plan 03: Visualization components
 ```
-Result: Each plan self-contained, no file overlap
-Waves: [01, 02, 03] (all parallel)
-</vertical_slice_example>
-
-<when_to_restructure>
-**Restructure for vertical slices when:**
-- Phase has 3+ features that are independent
-- No shared infrastructure requirements
-- Each feature touches different files
-- Features can be tested independently
-
-**Keep sequential when:**
-- Genuine data dependencies (Order needs User type)
-- Shared foundation required (auth setup before protected features)
-- Single feature being built incrementally
-- Phase is already a vertical slice
-</when_to_restructure>
+</splitting_strategies>
+
+<dependency_awareness>
+**Plans declare dependencies explicitly via frontmatter.**
+
+```yaml
+# Independent plan (Wave 1 candidate)
+depends_on: []
+files_modified: [src/features/user/model.ts, src/features/user/api.ts]
+autonomous: true
+
+# Dependent plan (later wave)
+depends_on: ["03-01"]
+files_modified: [src/integration/stripe.ts]
+autonomous: true
+```
+
+**Wave assignment rules:**
+- `depends_on: []` + no file conflicts → Wave 1 (parallel)
+- `depends_on: ["XX"]` → runs after plan XX completes
+- Shared `files_modified` with sibling → sequential (by plan number)
+
+**SUMMARY references:**
+- Only reference prior SUMMARY if genuinely needed (imported types, decisions affecting this plan)
+- Independent plans need NO prior SUMMARY references
+- Reflexive chaining (02 refs 01, 03 refs 02) is an anti-pattern
+</dependency_awareness>
 
 <file_ownership>
-**Explicit file ownership prevents conflicts:**
+**Exclusive file ownership prevents conflicts:**
 
 ```yaml
 # Plan 01 frontmatter
-files_exclusive: [src/models/user.ts, src/api/users.ts, src/components/UserList.tsx]
+files_modified: [src/models/user.ts, src/api/users.ts, src/components/UserList.tsx]
 
 # Plan 02 frontmatter
-files_exclusive: [src/models/product.ts, src/api/products.ts, src/components/ProductList.tsx]
+files_modified: [src/models/product.ts, src/api/products.ts, src/components/ProductList.tsx]
 ```
 
+No overlap → can run parallel.
+
 **If file appears in multiple plans:** Later plan depends on earlier (by plan number).
 **If file cannot be split:** Plans must be sequential for that file.
 </file_ownership>
 
-<summary_references>
-**Minimize SUMMARY references when parallel-aware:**
-
-**Before (sequential habit):**
-```markdown
-<context>
-@.planning/phases/05-features/05-01-SUMMARY.md  # Always reference prior
-@.planning/phases/05-features/05-02-SUMMARY.md  # Chain continues
-</context>
-```
-
-**After (parallel-aware):**
-```markdown
-<context>
-# Only reference if this plan ACTUALLY needs decisions from prior plan
-# Most parallel plans don't need any SUMMARY references
-</context>
-```
-
-**Include SUMMARY only when:**
-- Prior plan made a decision that affects this plan's approach
-- Prior plan created types/interfaces this plan imports
-- Prior plan's output is input to this plan
-</summary_references>
-</parallel_aware_splitting>
-
 <anti_patterns>
 **Bad - Comprehensive plan:**
 ```
@@ -189,8 +164,26 @@ Plan 1: "Auth Database Models" (2 tasks)
 Plan 2: "Auth API Core" (3 tasks)
 Plan 3: "Auth API Protection" (2 tasks)
 Plan 4: "Auth UI Components" (2 tasks)
-Each: 30-40% context, peak quality, atomic commits (2-3 task commits + 1 metadata commit)
+Each: 30-40% context, peak quality, atomic commits
+```
+
+**Bad - Horizontal layers (sequential):**
+```
+Plan 01: Create User model, Product model, Order model
+Plan 02: Create /api/users, /api/products, /api/orders
+Plan 03: Create UserList UI, ProductList UI, OrderList UI
 ```
+Result: 02 depends on 01, 03 depends on 02
+Waves: [01] → [02] → [03] (fully sequential)
+
+**Good - Vertical slices (parallel):**
+```
+Plan 01: User feature (model + API + UI)
+Plan 02: Product feature (model + API + UI)
+Plan 03: Order feature (model + API + UI)
+```
+Result: Each plan self-contained, no file overlap
+Waves: [01, 02, 03] (all parallel)
 </anti_patterns>
 
 <estimating_context>
@@ -246,15 +239,18 @@ Each plan: fresh context, peak quality. More plans = more thoroughness, same qua
 <summary>
 **2-3 tasks, 50% context target:**
 - All tasks: Peak quality
-- Git: Atomic per-task commits (each task = 1 commit, plan = 1 metadata commit)
-- Autonomous plans: Subagent execution (fresh context)
+- Git: Atomic per-task commits
+- Parallel by default: Fresh context per subagent
 
 **The principle:** Aggressive atomicity. More plans, smaller scope, consistent quality.
 
-**The rule:** If in doubt, split. Quality over consolidation. Always.
-
-**Depth rule:** Depth increases plan COUNT, never plan SIZE.
+**The rules:**
+- If in doubt, split. Quality over consolidation.
+- Depth increases plan COUNT, never plan SIZE.
+- Vertical slices over horizontal layers.
+- Explicit dependencies via `depends_on` frontmatter.
+- Autonomous plans get parallel execution.
 
-**Commit rule:** Each plan produces 3-4 commits total (2-3 task commits + 1 docs commit). More granular history = better observability for Claude.
+**Commit rule:** Each plan produces 3-4 commits total (2-3 task commits + 1 docs commit).
 </summary>
 </scope_estimation>