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>
2026-01-13 16:32:03 -06:00
parent e30e387c00
commit e5d4ecc28c
5 changed files with 765 additions and 493 deletions
--- a/get-shit-done/workflows/plan-phase.md
+++ b/get-shit-done/workflows/plan-phase.md
@@ -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>