feat: parallel-first planning with dependency graphs and checkpoint-resume
- plan-phase.md: dependency-first planning, vertical slices default - phase-prompt.md: autonomous field, wave structure, frontmatter table - scope-estimation.md: parallel default, removed "parallel-aware" framing - plan-format.md: frontmatter docs with depends_on, files_modified, autonomous - execute-phase.md: checkpoint-resume flow using Task resume parameter Plans now declare explicit dependencies via frontmatter. Wave assignment is automatic based on depends_on + files_modified. Checkpoints pause subagent, return to orchestrator, user responds, orchestrator resumes. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
@@ -3,7 +3,7 @@ Execute all plans in a phase using wave-based parallel execution. Orchestrator s
|
||||
</purpose>
|
||||
|
||||
<core_principle>
|
||||
The orchestrator's job is coordination, not execution. Each subagent loads the full execute-plan context itself. Orchestrator discovers plans, analyzes dependencies, groups into waves, spawns agents, collects results.
|
||||
The orchestrator's job is coordination, not execution. Each subagent loads the full execute-plan context itself. Orchestrator discovers plans, analyzes dependencies, groups into waves, spawns agents, handles checkpoints, collects results.
|
||||
</core_principle>
|
||||
|
||||
<process>
|
||||
@@ -29,7 +29,7 @@ Report: "Found {N} plans in {phase_dir}"
|
||||
</step>
|
||||
|
||||
<step name="discover_plans">
|
||||
List all plans and their completion status:
|
||||
List all plans and extract metadata:
|
||||
|
||||
```bash
|
||||
# Get all plans
|
||||
@@ -39,33 +39,38 @@ ls -1 "$PHASE_DIR"/*-PLAN.md 2>/dev/null | sort
|
||||
ls -1 "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null | sort
|
||||
```
|
||||
|
||||
For each plan, read frontmatter to extract:
|
||||
- `depends_on: []` - Plan IDs this plan requires
|
||||
- `files_modified: []` - Files this plan touches
|
||||
- `autonomous: true/false` - Whether plan has checkpoints
|
||||
|
||||
Build plan inventory:
|
||||
- Plan path
|
||||
- Plan number (extracted from filename)
|
||||
- Plan ID (e.g., "03-01")
|
||||
- Dependencies
|
||||
- Files modified
|
||||
- Autonomous flag
|
||||
- Completion status (SUMMARY exists = complete)
|
||||
|
||||
Skip completed plans. If all complete, report "Phase already executed" and exit.
|
||||
</step>
|
||||
|
||||
<step name="analyze_dependencies">
|
||||
For each incomplete plan, check if it depends on outputs from other plans.
|
||||
Build dependency graph from frontmatter:
|
||||
|
||||
**Read each plan's `<context>` section:**
|
||||
- Look for @-references to files that other plans create
|
||||
- Look for explicit `requires:` in frontmatter
|
||||
**Direct dependencies:**
|
||||
- `depends_on: ["03-01"]` → this plan depends on 03-01
|
||||
|
||||
**Dependency patterns:**
|
||||
- Plan references `@.planning/phases/.../XX-YY-SUMMARY.md` → depends on plan XX-YY
|
||||
- Plan references files created by earlier plan → depends on that plan
|
||||
- No cross-references → independent, can run in parallel
|
||||
**File conflict dependencies:**
|
||||
- If two plans modify same file, later plan (by number) depends on earlier
|
||||
|
||||
**Build dependency graph:**
|
||||
**Build graph:**
|
||||
```
|
||||
plan-01: [] # no dependencies
|
||||
plan-02: [] # no dependencies
|
||||
plan-03: [plan-01] # depends on plan-01 outputs
|
||||
plan-04: [plan-02] # depends on plan-02 outputs
|
||||
plan-05: [plan-03, plan-04] # depends on both
|
||||
plan-01: {deps: [], files: [src/user.ts], autonomous: true}
|
||||
plan-02: {deps: [], files: [src/product.ts], autonomous: true}
|
||||
plan-03: {deps: ["plan-01"], files: [src/dashboard.tsx], autonomous: false}
|
||||
plan-04: {deps: ["plan-02"], files: [src/cart.ts], autonomous: true}
|
||||
plan-05: {deps: ["plan-03", "plan-04"], files: [src/checkout.ts], autonomous: true}
|
||||
```
|
||||
</step>
|
||||
|
||||
@@ -73,34 +78,39 @@ plan-05: [plan-03, plan-04] # depends on both
|
||||
Group plans into execution waves based on dependencies:
|
||||
|
||||
**Wave assignment algorithm:**
|
||||
1. Wave 1: All plans with no dependencies
|
||||
2. Wave 2: Plans whose dependencies are all in Wave 1
|
||||
1. Wave 1: All plans with no dependencies AND autonomous=true
|
||||
2. Non-autonomous plans with no dependencies: execute after Wave 1, before Wave 2
|
||||
3. Wave N: Plans whose dependencies are all in earlier waves
|
||||
|
||||
**Separate checkpoint plans:**
|
||||
Plans with `autonomous: false` execute in main context (not parallel subagent) to handle user interaction.
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Wave 1: [plan-01, plan-02] # parallel - no dependencies
|
||||
Wave 2: [plan-03, plan-04] # parallel - depend only on Wave 1
|
||||
Wave 3: [plan-05] # sequential - depends on Wave 2
|
||||
Wave 1 (parallel): [plan-01, plan-02]
|
||||
Checkpoint: [plan-03] - has human-verify, runs in main context
|
||||
Wave 2 (parallel): [plan-04]
|
||||
Wave 3: [plan-05]
|
||||
```
|
||||
|
||||
Report wave structure to user:
|
||||
```
|
||||
Execution Plan:
|
||||
Wave 1 (parallel): plan-01, plan-02
|
||||
Wave 2 (parallel): plan-03, plan-04
|
||||
Wave 3: plan-05
|
||||
Wave 1 (parallel): 03-01, 03-02
|
||||
Checkpoint: 03-03 (requires user verification)
|
||||
Wave 2 (parallel): 03-04
|
||||
Wave 3: 03-05
|
||||
|
||||
Total: 5 plans in 3 waves
|
||||
Total: 5 plans in 3 waves + 1 checkpoint
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="execute_waves">
|
||||
Execute each wave in sequence. Plans within a wave run in parallel.
|
||||
Execute each wave in sequence. Autonomous plans within a wave run in parallel.
|
||||
|
||||
**For each wave:**
|
||||
|
||||
1. **Spawn all agents in wave simultaneously:**
|
||||
1. **Spawn all autonomous agents in wave simultaneously:**
|
||||
|
||||
Use Task tool with multiple parallel calls. Each agent gets prompt from subagent-task-prompt template:
|
||||
|
||||
@@ -151,8 +161,78 @@ Execute each wave in sequence. Plans within a wave run in parallel.
|
||||
- If continue: proceed to next wave (dependent plans may also fail)
|
||||
- If stop: exit with partial completion report
|
||||
|
||||
5. **Proceed to next wave**
|
||||
5. **Execute checkpoint plans between waves:**
|
||||
|
||||
See `<checkpoint_handling>` for details.
|
||||
|
||||
6. **Proceed to next wave**
|
||||
|
||||
</step>
|
||||
|
||||
<step name="checkpoint_handling">
|
||||
Plans with `autonomous: false` require user interaction.
|
||||
|
||||
**Detection:** Check `autonomous` field in frontmatter.
|
||||
|
||||
**Execution flow for checkpoint plans:**
|
||||
|
||||
1. **Spawn agent for checkpoint plan:**
|
||||
```
|
||||
Task(prompt="{subagent-task-prompt}", subagent_type="general-purpose")
|
||||
```
|
||||
|
||||
2. **Agent runs until checkpoint:**
|
||||
- Executes auto tasks normally
|
||||
- Reaches checkpoint task (e.g., `type="checkpoint:human-verify"`)
|
||||
- Agent returns with checkpoint details in its response
|
||||
|
||||
3. **Agent return includes:**
|
||||
- Checkpoint type (human-verify, decision, human-action)
|
||||
- Checkpoint details (what-built, options, instructions)
|
||||
- Agent ID for resumption
|
||||
- Progress so far (tasks completed)
|
||||
|
||||
4. **Orchestrator presents checkpoint to user:**
|
||||
```
|
||||
## Checkpoint: Visual Verification Required
|
||||
|
||||
**Plan:** 03-03 Dashboard Layout
|
||||
**Progress:** 2/3 tasks complete
|
||||
|
||||
**What was built:**
|
||||
Responsive dashboard with sidebar navigation
|
||||
|
||||
**Please verify:**
|
||||
1. Run: npm run dev
|
||||
2. Visit: http://localhost:3000/dashboard
|
||||
3. Desktop (>1024px): Verify sidebar left, content right
|
||||
4. Mobile (375px): Verify single column layout
|
||||
|
||||
Type "approved" to continue, or describe issues to fix.
|
||||
```
|
||||
|
||||
5. **User responds:**
|
||||
- "approved" → resume agent
|
||||
- Description of issues → resume agent with feedback
|
||||
|
||||
6. **Resume agent:**
|
||||
```
|
||||
Task(resume="{agent_id}", prompt="User response: {user_input}")
|
||||
```
|
||||
|
||||
7. **Agent continues from checkpoint:**
|
||||
- If approved: proceed to next task
|
||||
- If issues: fix and re-present checkpoint, or ask for clarification
|
||||
|
||||
8. **Repeat until plan completes or user stops**
|
||||
|
||||
**Checkpoint in parallel context:**
|
||||
If a plan in a parallel wave has a checkpoint:
|
||||
- Spawn as normal
|
||||
- Agent pauses at checkpoint and returns
|
||||
- Other parallel agents may complete while waiting
|
||||
- Handle checkpoint, resume agent
|
||||
- Wait for all agents to finish before next wave
|
||||
</step>
|
||||
|
||||
<step name="aggregate_results">
|
||||
@@ -169,13 +249,14 @@ After all waves complete, aggregate results:
|
||||
| Wave | Plans | Status |
|
||||
|------|-------|--------|
|
||||
| 1 | plan-01, plan-02 | ✓ Complete |
|
||||
| 2 | plan-03, plan-04 | ✓ Complete |
|
||||
| CP | plan-03 | ✓ Verified |
|
||||
| 2 | plan-04 | ✓ Complete |
|
||||
| 3 | plan-05 | ✓ Complete |
|
||||
|
||||
### Plan Details
|
||||
|
||||
1. **plan-01**: [one-liner from SUMMARY.md]
|
||||
2. **plan-02**: [one-liner from SUMMARY.md]
|
||||
1. **03-01**: [one-liner from SUMMARY.md]
|
||||
2. **03-02**: [one-liner from SUMMARY.md]
|
||||
...
|
||||
|
||||
### Issues Encountered
|
||||
@@ -204,18 +285,18 @@ Present next steps based on milestone status:
|
||||
|
||||
**If more phases remain:**
|
||||
```
|
||||
## ▶ Next Up
|
||||
## Next Up
|
||||
|
||||
**Phase {X+1}: {Name}** — {Goal}
|
||||
|
||||
`/gsd:plan-phase {X+1}`
|
||||
|
||||
<sub>`/clear` first → fresh context window</sub>
|
||||
<sub>`/clear` first for fresh context</sub>
|
||||
```
|
||||
|
||||
**If milestone complete:**
|
||||
```
|
||||
🎉 MILESTONE COMPLETE!
|
||||
MILESTONE COMPLETE!
|
||||
|
||||
All {N} phases executed.
|
||||
|
||||
@@ -229,7 +310,7 @@ All {N} phases executed.
|
||||
**Why this works:**
|
||||
|
||||
Orchestrator context usage: ~10-15%
|
||||
- Read plan files (small)
|
||||
- Read plan frontmatter (small)
|
||||
- Analyze dependencies (logic, no heavy reads)
|
||||
- Fill template strings
|
||||
- Spawn Task calls
|
||||
@@ -262,17 +343,26 @@ Each subagent: Fresh 200k context
|
||||
- Something systemic (git issues, permissions, etc.)
|
||||
- Stop execution
|
||||
- Report for manual investigation
|
||||
|
||||
**Checkpoint fails to resolve:**
|
||||
- User can't approve or provides repeated issues
|
||||
- Ask: "Skip this plan?" or "Abort phase execution?"
|
||||
- Record partial progress in STATE.md
|
||||
</failure_handling>
|
||||
|
||||
<checkpoint_handling>
|
||||
Plans with checkpoints require user interaction. These cannot run fully autonomous.
|
||||
<resumption>
|
||||
**Resuming interrupted execution:**
|
||||
|
||||
**Detection:** Scan plan for `type="checkpoint` before spawning.
|
||||
If phase execution was interrupted (context limit, user exit, error):
|
||||
|
||||
**If checkpoints found:**
|
||||
- Don't include in parallel wave
|
||||
- Execute after wave completes, in main context
|
||||
- Or spawn as single agent and wait (user interaction flows through)
|
||||
1. Run `/gsd:execute-phase {phase}` again
|
||||
2. discover_plans finds completed SUMMARYs
|
||||
3. Skips completed plans
|
||||
4. Resumes from first incomplete plan
|
||||
5. Continues wave-based execution
|
||||
|
||||
**Checkpoint-heavy plans:** Execute sequentially in main context rather than subagent.
|
||||
</checkpoint_handling>
|
||||
**STATE.md tracks:**
|
||||
- Last completed plan
|
||||
- Current wave
|
||||
- Any pending checkpoints
|
||||
</resumption>
|
||||
|
||||
@@ -30,10 +30,18 @@ Decimal phases enable urgent work insertion without renumbering:
|
||||
</required_reading>
|
||||
|
||||
<purpose>
|
||||
Create an executable phase prompt (PLAN.md). PLAN.md IS the prompt that Claude executes - not a document that gets transformed.
|
||||
Create executable phase prompts (PLAN.md files) optimized for parallel execution.
|
||||
|
||||
PLAN.md IS the prompt that Claude executes. Plans are grouped into execution waves based on dependencies - independent plans run in parallel, dependent plans wait for predecessors.
|
||||
</purpose>
|
||||
|
||||
<planning_principles>
|
||||
**Parallel by default:** Think in dependency graphs, not sequential lists. Ask "what does this need?" not "what comes next?"
|
||||
|
||||
**Vertical slices over horizontal layers:** Group by feature (User: model + API + UI) not by type (all models → all APIs → all UIs).
|
||||
|
||||
**Explicit dependencies:** Every plan declares what it needs (`depends_on`) and what it touches (`files_modified`). Empty dependencies = parallel candidate.
|
||||
|
||||
**Secure by design:** Assume hostile input on every boundary. Validate, parameterize, authenticate, fail closed.
|
||||
|
||||
**Performance by design:** Assume production load, not demo conditions. Plan for efficient data access, appropriate caching, minimal round trips.
|
||||
@@ -54,28 +62,6 @@ Read `.planning/STATE.md` and parse:
|
||||
If STATE.md missing but .planning/ exists, offer to reconstruct or continue without.
|
||||
</step>
|
||||
|
||||
<step name="read_parallelization_config" priority="second">
|
||||
Read parallelization settings from config.json:
|
||||
|
||||
```bash
|
||||
cat .planning/config.json 2>/dev/null | jq '.parallelization'
|
||||
```
|
||||
|
||||
**Extract settings:**
|
||||
- `enabled`: Whether parallel execution is available (default: true)
|
||||
- `plan_level`: Whether plan-level parallelization is enabled (default: true)
|
||||
|
||||
**Store for later steps:**
|
||||
- If `parallelization.enabled && parallelization.plan_level`: Planning will optimize for independence
|
||||
- Group tasks by vertical slice (feature A, feature B) not workflow stage (setup → implement → test)
|
||||
- Avoid unnecessary inter-plan dependencies
|
||||
- Track files each plan modifies via `files_modified`
|
||||
- Keep `depends_on` empty when genuinely independent
|
||||
- If disabled: Planning proceeds with sequential assumptions (current behavior)
|
||||
|
||||
**If config.json missing:** Assume parallelization enabled (new projects get it by default).
|
||||
</step>
|
||||
|
||||
<step name="load_codebase_context">
|
||||
Check for codebase map:
|
||||
|
||||
@@ -255,7 +241,12 @@ cat .planning/phases/XX-name/${PHASE}-CONTEXT.md 2>/dev/null
|
||||
</step>
|
||||
|
||||
<step name="break_into_tasks">
|
||||
Decompose phase into tasks and identify TDD candidates.
|
||||
Decompose phase into tasks. **Think dependencies first, not sequence.**
|
||||
|
||||
For each potential task, ask:
|
||||
1. **What does this task NEED?** (files, types, APIs that must exist)
|
||||
2. **What does this task CREATE?** (files, types, APIs others might need)
|
||||
3. **Can this run independently?** (no dependencies = Wave 1 candidate)
|
||||
|
||||
**Standard tasks need:**
|
||||
- **Type**: auto, checkpoint:human-verify, checkpoint:decision (human-action rarely needed)
|
||||
@@ -286,10 +277,6 @@ Standard tasks (remain in standard plans):
|
||||
→ Yes: Create a dedicated TDD plan for this feature (one feature per TDD plan)
|
||||
→ No: Standard task in standard plan
|
||||
|
||||
**Why TDD gets its own plan:** TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. Embedded in a multi-task plan, TDD work consumes 50-60% of context alone, degrading quality for remaining tasks.
|
||||
|
||||
**Test framework:** If project has no test setup and TDD plans are needed, the first TDD plan's RED phase handles framework setup as part of writing the first test.
|
||||
|
||||
See `~/.claude/get-shit-done/references/tdd.md` for TDD plan structure.
|
||||
|
||||
**Checkpoints:** Visual/functional verification → checkpoint:human-verify. Implementation choices → checkpoint:decision. Manual action (email, 2FA) → checkpoint:human-action (rare).
|
||||
@@ -299,54 +286,134 @@ See `~/.claude/get-shit-done/references/tdd.md` for TDD plan structure.
|
||||
See ~/.claude/get-shit-done/references/checkpoints.md for checkpoint structure.
|
||||
</step>
|
||||
|
||||
<step name="parallelization_aware">
|
||||
**Restructure task grouping for parallel execution when enabled.**
|
||||
<step name="build_dependency_graph">
|
||||
**Map task dependencies explicitly before grouping into plans.**
|
||||
|
||||
**Skip if:** Parallelization disabled in config (from read_parallelization_config step).
|
||||
**1. For each task identified, record:**
|
||||
- `needs`: What must exist before this task runs (files, types, prior task outputs)
|
||||
- `creates`: What this task produces (files, types, exports)
|
||||
- `has_checkpoint`: Does this task require user interaction?
|
||||
|
||||
**If enabled, analyze task groupings:**
|
||||
**2. Build the dependency graph:**
|
||||
|
||||
1. **Identify file ownership per task group:**
|
||||
- Extract all files from `<files>` elements
|
||||
- Map each file to which plan(s) would modify it
|
||||
- Flag overlaps as forced dependencies
|
||||
```
|
||||
Example phase with 6 tasks:
|
||||
|
||||
2. **Detect unnecessary dependencies:**
|
||||
- Check if any plan references another plan's SUMMARY in @context
|
||||
- If reference is NOT genuinely needed (no decision/output dependency), remove it
|
||||
- Only keep SUMMARY references when later plan actually needs earlier plan's decisions
|
||||
Task A (User model): needs nothing, creates src/models/user.ts
|
||||
Task B (Product model): needs nothing, creates src/models/product.ts
|
||||
Task C (User API): needs Task A, creates src/api/users.ts
|
||||
Task D (Product API): needs Task B, creates src/api/products.ts
|
||||
Task E (Dashboard): needs Task C + D, creates src/components/Dashboard.tsx
|
||||
Task F (Verify UI): checkpoint:human-verify, needs Task E
|
||||
|
||||
3. **Restructure for vertical slices (if beneficial):**
|
||||
Dependency graph:
|
||||
A ──→ C ──┐
|
||||
├──→ E ──→ F
|
||||
B ──→ D ──┘
|
||||
|
||||
| Sequential (current) | Parallel-aware |
|
||||
|---------------------|----------------|
|
||||
| Plan 01: All models | Plan 01: Feature A (model + API + UI) |
|
||||
| Plan 02: All APIs | Plan 02: Feature B (model + API + UI) |
|
||||
| Plan 03: All UIs | Plan 03: Feature C (model + API + UI) |
|
||||
Wave analysis:
|
||||
Wave 1: A, B (independent roots)
|
||||
Wave 2: C, D (depend only on Wave 1)
|
||||
Wave 3: E (depends on Wave 2)
|
||||
Wave 4: F (checkpoint, depends on Wave 3)
|
||||
```
|
||||
|
||||
**When to restructure:**
|
||||
- Multiple plans with same file types (all touching models, all touching APIs)
|
||||
- No genuine data dependencies between features
|
||||
- Each vertical slice is self-contained
|
||||
**3. Identify parallelization opportunities:**
|
||||
|
||||
**When NOT to restructure:**
|
||||
- Genuine dependencies (Plan 02 uses types from Plan 01)
|
||||
- Shared infrastructure (all features need auth setup first)
|
||||
- Single-concern phases (all plans ARE vertical slices already)
|
||||
| Pattern | Result |
|
||||
|---------|--------|
|
||||
| No dependencies | Wave 1 (parallel) |
|
||||
| Depends only on Wave 1 | Wave 2 (parallel) |
|
||||
| Has checkpoint | Runs in wave, but can pause/resume |
|
||||
| Shared file conflict | Must be sequential |
|
||||
|
||||
4. **Set plan frontmatter for parallelization:**
|
||||
**4. Detect and prefer vertical slices:**
|
||||
|
||||
For each plan, determine:
|
||||
- `depends_on: [plan-ids]` — explicit dependencies (empty if independent)
|
||||
- `files_modified: [paths]` — files this plan will modify
|
||||
**Sequential (horizontal layers) - AVOID:**
|
||||
```
|
||||
Plan 01: Create User model, Product model, Order model
|
||||
Plan 02: Create User API, Product API, Order API
|
||||
Plan 03: Create User UI, Product UI, Order UI
|
||||
```
|
||||
Result: Fully sequential (02 needs 01, 03 needs 02)
|
||||
|
||||
`/gsd:execute-phase` uses these to detect parallelization opportunities automatically.
|
||||
**Parallel (vertical slices) - PREFER:**
|
||||
```
|
||||
Plan 01: User feature (model + API + UI)
|
||||
Plan 02: Product feature (model + API + UI)
|
||||
Plan 03: Order feature (model + API + UI)
|
||||
```
|
||||
Result: All three can run in parallel (Wave 1)
|
||||
|
||||
**Output:** Task groupings optimized for independence, frontmatter values determined.
|
||||
**When vertical slices work:**
|
||||
- Features are independent (no shared types/data)
|
||||
- Each slice is self-contained
|
||||
- No cross-feature dependencies
|
||||
|
||||
**When horizontal layers are necessary:**
|
||||
- Shared foundation required (auth before protected features)
|
||||
- Genuine type dependencies (Order needs User type)
|
||||
- Infrastructure setup (database before all features)
|
||||
|
||||
**5. Output: Dependency map for each plan**
|
||||
|
||||
For each plan, determine:
|
||||
- `depends_on: []` - plan IDs this plan requires (empty = parallel candidate)
|
||||
- `files_modified: []` - files this plan touches (for conflict detection)
|
||||
- `autonomous: true|false` - has checkpoints requiring user interaction?
|
||||
</step>
|
||||
|
||||
<step name="group_into_plans">
|
||||
**Group tasks into plans based on dependency waves and autonomy.**
|
||||
|
||||
**Grouping rules:**
|
||||
|
||||
1. **Same-wave tasks with no file conflicts → can be in parallel plans**
|
||||
2. **Tasks with shared files → must be in same plan or sequential plans**
|
||||
3. **Checkpoint tasks → mark plan as `autonomous: false`**
|
||||
4. **Each plan: 2-3 tasks max, single concern, ~50% context target**
|
||||
|
||||
**Plan assignment algorithm:**
|
||||
|
||||
```
|
||||
1. Start with Wave 1 tasks (no dependencies)
|
||||
2. Group into plans by:
|
||||
- Feature affinity (vertical slice)
|
||||
- File ownership (no conflicts)
|
||||
- Checkpoint presence (group checkpoints with related auto tasks)
|
||||
3. Move to Wave 2 tasks, repeat
|
||||
4. Continue until all tasks assigned
|
||||
```
|
||||
|
||||
**Example grouping:**
|
||||
|
||||
```
|
||||
Tasks identified:
|
||||
- A: User model (Wave 1, auto)
|
||||
- B: Product model (Wave 1, auto)
|
||||
- C: User API (Wave 2, auto)
|
||||
- D: Product API (Wave 2, auto)
|
||||
- E: Dashboard (Wave 3, auto)
|
||||
- F: Verify Dashboard (Wave 3, checkpoint)
|
||||
|
||||
Grouping into plans:
|
||||
Plan 01: [A, C] - User feature (model + API)
|
||||
depends_on: [], autonomous: true
|
||||
|
||||
Plan 02: [B, D] - Product feature (model + API)
|
||||
depends_on: [], autonomous: true
|
||||
|
||||
Plan 03: [E, F] - Dashboard (build + verify)
|
||||
depends_on: ["01", "02"], autonomous: false
|
||||
|
||||
Wave structure:
|
||||
Wave 1 (parallel): Plan 01, Plan 02
|
||||
Wave 2: Plan 03 (has checkpoint, runs after Wave 1)
|
||||
```
|
||||
</step>
|
||||
|
||||
<step name="estimate_scope">
|
||||
After tasks, assess against quality degradation curve.
|
||||
After grouping, verify each plan fits context budget.
|
||||
|
||||
**Check depth setting:**
|
||||
```bash
|
||||
@@ -370,8 +437,6 @@ cat .planning/config.json 2>/dev/null | grep depth
|
||||
For comprehensive depth:
|
||||
- Create MORE plans when the work warrants it, not bigger ones
|
||||
- If a phase has 15 tasks, that's 5-8 plans (not 3 plans with 5 tasks each)
|
||||
- Don't compress to look efficient—thoroughness is the goal
|
||||
- Let small phases stay small—don't pad to hit a number
|
||||
- Each plan stays focused: 2-3 tasks, single concern
|
||||
|
||||
For quick depth:
|
||||
@@ -382,14 +447,8 @@ For quick depth:
|
||||
|
||||
**ALWAYS split if:** >3 tasks, multiple subsystems, >5 files in any task, complex domains (auth, payments).
|
||||
|
||||
**If scope appropriate (2-3 tasks, single subsystem, <5 files/task):** Proceed to confirm_breakdown.
|
||||
|
||||
**If large (>3 tasks):** Split by subsystem, dependency, complexity, or autonomous vs interactive.
|
||||
|
||||
**Each plan must be:** 2-3 tasks max, ~50% context target, independently committable.
|
||||
|
||||
**Autonomous optimization:** No checkpoints → subagent (fresh context). Has checkpoints → main context. Group autonomous work together.
|
||||
|
||||
See ~/.claude/get-shit-done/references/scope-estimation.md for complete guidance.
|
||||
</step>
|
||||
|
||||
@@ -399,22 +458,39 @@ Auto-approve and proceed to write_phase_prompt.
|
||||
</if>
|
||||
|
||||
<if mode="interactive">
|
||||
Present breakdown inline:
|
||||
Present breakdown with wave structure:
|
||||
|
||||
```
|
||||
Phase [X] breakdown:
|
||||
|
||||
### Tasks ({phase}-01-PLAN.md)
|
||||
1. [Task] - [brief] [type]
|
||||
2. [Task] - [brief] [type]
|
||||
## Execution Waves
|
||||
|
||||
Autonomous: [yes/no]
|
||||
**Wave 1 (parallel):**
|
||||
{phase}-01: [Plan Name] [autonomous]
|
||||
- Task: [brief]
|
||||
- Task: [brief]
|
||||
|
||||
{phase}-02: [Plan Name] [autonomous]
|
||||
- Task: [brief]
|
||||
- Task: [brief]
|
||||
|
||||
**Wave 2 (parallel):**
|
||||
{phase}-03: [Plan Name] (depends: 01, 02) [autonomous]
|
||||
- Task: [brief]
|
||||
|
||||
**Wave 3:**
|
||||
{phase}-04: [Plan Name] (depends: 03) [has checkpoint]
|
||||
- Task: [brief]
|
||||
- Checkpoint: [type]
|
||||
|
||||
---
|
||||
Total: [N] plans in [M] waves
|
||||
Parallel plans: [X]
|
||||
Sequential plans: [Y]
|
||||
|
||||
Does this look right? (yes / adjust / start over)
|
||||
```
|
||||
|
||||
For multiple plans, show each plan with its tasks.
|
||||
|
||||
Wait for confirmation. If "adjust": revise. If "start over": return to gather_phase_context.
|
||||
</if>
|
||||
</step>
|
||||
@@ -427,10 +503,10 @@ Use template from `~/.claude/get-shit-done/templates/phase-prompt.md`.
|
||||
**Multiple plans:** Write separate files ({phase}-01-PLAN.md, {phase}-02-PLAN.md, etc.)
|
||||
|
||||
Each plan follows template structure with:
|
||||
- Frontmatter (phase, plan, type, depends_on, files_modified, domain)
|
||||
- Frontmatter (phase, plan, type, depends_on, files_modified, autonomous, domain)
|
||||
- Objective (plan-specific goal, purpose, output)
|
||||
- Execution context (execute-plan.md, summary template, checkpoints.md if needed)
|
||||
- Context (@references to PROJECT, ROADMAP, STATE, codebase docs, RESEARCH/DISCOVERY/CONTEXT if exist, prior summaries, source files, prior decisions, deferred issues, concerns)
|
||||
- Context (@references to PROJECT, ROADMAP, STATE, codebase docs, RESEARCH/DISCOVERY/CONTEXT if exist, prior summaries, source files)
|
||||
- Tasks (XML format with types)
|
||||
- Verification, Success criteria, Output specification
|
||||
|
||||
@@ -441,17 +517,18 @@ Each plan follows template structure with:
|
||||
phase: XX-name
|
||||
plan: NN
|
||||
type: execute
|
||||
depends_on: [plan IDs this plan requires, or empty array]
|
||||
files_modified: [files this plan will modify]
|
||||
depends_on: [] # Plan IDs this plan requires. Empty = Wave 1 candidate.
|
||||
files_modified: [] # Files this plan touches. Used for conflict detection.
|
||||
autonomous: true # false if plan has checkpoints requiring user interaction
|
||||
domain: [optional]
|
||||
---
|
||||
```
|
||||
|
||||
**Parallelization is automatic:** `/gsd:execute-phase` analyzes `depends_on` and `files_modified` to determine which plans can run in parallel. No explicit flag needed.
|
||||
**Wave assignment is automatic:** `/gsd:execute-phase` reads `depends_on` to build waves. Plans with empty `depends_on` and no file conflicts run in Wave 1 (parallel).
|
||||
|
||||
**Context section population from frontmatter analysis:**
|
||||
**Context section - parallel-aware:**
|
||||
|
||||
Inject automatically-assembled context package from read_project_history step:
|
||||
Only include prior plan SUMMARY references if this plan genuinely needs decisions/outputs:
|
||||
|
||||
```markdown
|
||||
<context>
|
||||
@@ -459,37 +536,30 @@ Inject automatically-assembled context package from read_project_history step:
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
|
||||
# Auto-selected based on dependency graph (from frontmatter):
|
||||
@.planning/phases/XX-name/YY-ZZ-SUMMARY.md
|
||||
@.planning/phases/AA-name/BB-CC-SUMMARY.md
|
||||
# Only reference prior plans if genuinely needed:
|
||||
# - This plan uses types/exports from prior plan
|
||||
# - This plan continues work from prior plan
|
||||
# - Prior plan made decision that affects this plan
|
||||
#
|
||||
# Do NOT reflexively chain: Plan 02 refs 01, Plan 03 refs 02...
|
||||
# Independent plans need no prior SUMMARY references.
|
||||
|
||||
# Key files from frontmatter (relevant to this phase):
|
||||
@path/to/important/file.ts
|
||||
@path/to/another/file.ts
|
||||
|
||||
**Tech stack available:** [extracted from frontmatter tech-stack.added]
|
||||
**Established patterns:** [extracted from frontmatter patterns-established]
|
||||
**Constraining decisions:**
|
||||
- [Phase X]: [decision from frontmatter]
|
||||
- [Phase Y]: [decision from frontmatter]
|
||||
|
||||
**Issues being addressed:** [If any from ISSUES.md]
|
||||
@path/to/relevant/source.ts
|
||||
</context>
|
||||
```
|
||||
|
||||
This ensures every PLAN.md gets optimal context automatically assembled via dependency graph, making execution as informed as possible.
|
||||
**For plans with checkpoints:**
|
||||
|
||||
**Context section population (parallel-aware):**
|
||||
Include checkpoint reference in execution_context:
|
||||
```markdown
|
||||
<execution_context>
|
||||
@~/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@~/.claude/get-shit-done/templates/summary.md
|
||||
@~/.claude/get-shit-done/references/checkpoints.md
|
||||
</execution_context>
|
||||
```
|
||||
|
||||
When parallelization enabled:
|
||||
- Only include SUMMARY references if this plan genuinely needs decisions/outputs from prior plan
|
||||
- Avoid reflexive "Plan 02 references Plan 01 SUMMARY" patterns
|
||||
- Each plan should be as self-contained as possible
|
||||
|
||||
When parallelization disabled:
|
||||
- Include SUMMARY references as before (sequential context chain)
|
||||
|
||||
For multi-plan phases: each plan has focused scope, references previous plan summaries only when genuinely needed (via frontmatter selection), last plan's success criteria includes "Phase X complete".
|
||||
Checkpoint plans can still run in parallel waves. When they hit a checkpoint, they pause and return to the orchestrator. User responds, orchestrator resumes the agent.
|
||||
</step>
|
||||
|
||||
<step name="git_commit">
|
||||
@@ -506,8 +576,8 @@ git commit -m "$(cat <<'EOF'
|
||||
docs(${PHASE}): create phase plan
|
||||
|
||||
Phase ${PHASE}: ${PHASE_NAME}
|
||||
- [N] plan(s) created
|
||||
- [X] total tasks defined
|
||||
- [N] plan(s) in [M] wave(s)
|
||||
- [X] parallel, [Y] sequential
|
||||
- Ready for execution
|
||||
EOF
|
||||
)"
|
||||
@@ -518,7 +588,12 @@ Confirm: "Committed: docs(${PHASE}): create phase plan"
|
||||
|
||||
<step name="offer_next">
|
||||
```
|
||||
Phase {X} planned: {N} plan(s) created in .planning/phases/XX-name/
|
||||
Phase {X} planned: {N} plan(s) in {M} wave(s)
|
||||
|
||||
## Wave Structure
|
||||
Wave 1 (parallel): {plan-01}, {plan-02}
|
||||
Wave 2: {plan-03}
|
||||
...
|
||||
|
||||
---
|
||||
|
||||
@@ -530,7 +605,7 @@ Phase {X} planned: {N} plan(s) created in .planning/phases/XX-name/
|
||||
`/gsd:execute-plan .planning/phases/XX-name/{phase}-01-PLAN.md`
|
||||
|
||||
[If 2+ plans created:]
|
||||
**Phase {X}: [Phase Name]** - {N} plans ready
|
||||
**Phase {X}: [Phase Name]** - {N} plans in {M} waves
|
||||
|
||||
`/gsd:execute-phase {X}`
|
||||
|
||||
@@ -539,8 +614,8 @@ Phase {X} planned: {N} plan(s) created in .planning/phases/XX-name/
|
||||
---
|
||||
|
||||
**Also available:**
|
||||
- Review/adjust tasks before executing
|
||||
[If 2+ plans: - `/gsd:execute-plan {phase}-01-PLAN.md` - run plans one at a time interactively]
|
||||
- Review/adjust plans before executing
|
||||
[If 2+ plans: - `/gsd:execute-plan {phase}-01-PLAN.md` - run plans one at a time]
|
||||
[If 2+ plans: - View all plans: `ls .planning/phases/XX-name/*-PLAN.md`]
|
||||
|
||||
---
|
||||
@@ -567,6 +642,7 @@ If you can't specify Files + Action + Verify + Done, the task is too vague.
|
||||
- No team assignments
|
||||
- No acceptance criteria committees
|
||||
- No sub-sub-sub tasks
|
||||
- **No reflexive sequential chaining** (Plan 02 depends on 01 "just because")
|
||||
Tasks are instructions for Claude, not Jira tickets.
|
||||
</anti_patterns>
|
||||
|
||||
@@ -575,13 +651,15 @@ Phase planning complete when:
|
||||
- [ ] STATE.md read, project history absorbed
|
||||
- [ ] Mandatory discovery completed (Level 0-3)
|
||||
- [ ] Prior decisions, issues, concerns synthesized
|
||||
- [ ] Dependency graph built (needs/creates for each task)
|
||||
- [ ] Tasks grouped into plans by wave, not by sequence
|
||||
- [ ] PLAN file(s) exist with XML structure
|
||||
- [ ] Each plan: depends_on, files_modified, autonomous in frontmatter
|
||||
- [ ] Each plan: Objective, context, tasks, verification, success criteria, output
|
||||
- [ ] @context references included (STATE, RESEARCH/DISCOVERY if exist, relevant summaries)
|
||||
- [ ] Each plan: 2-3 tasks (~50% context)
|
||||
- [ ] Each task: Type, Files (if auto), Action, Verify, Done
|
||||
- [ ] Checkpoints properly structured
|
||||
- [ ] If RESEARCH.md exists: "don't hand-roll" items NOT being custom-built
|
||||
- [ ] Wave structure maximizes parallelism
|
||||
- [ ] PLAN file(s) committed to git
|
||||
- [ ] User knows next steps
|
||||
- [ ] User knows next steps and wave structure
|
||||
</success_criteria>
|
||||
|
||||
Reference in New Issue
Block a user