mirror of
https://github.com/glittercowboy/get-shit-done
synced 2026-04-25 17:25:23 +02:00
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
@@ -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>
|
||||
```
|
||||
|
||||
|
||||
@@ -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)
|
||||
Vertical slices maximize parallelism: [01, 02, 03] run simultaneously.
|
||||
Horizontal layers force sequential execution: 01 → 02 → 03.
|
||||
|
||||
**By dependency:** Only when genuine dependencies exist.
|
||||
```
|
||||
Plan 01: Auth foundation (middleware, JWT utils)
|
||||
Plan 02: Protected features (uses auth from 01)
|
||||
```
|
||||
|
||||
**By complexity:** When one slice is much heavier.
|
||||
```
|
||||
Plan 01: Dashboard layout shell
|
||||
Plan 02: Data fetching and state
|
||||
Plan 03: Visualization components
|
||||
```
|
||||
</splitting_strategies>
|
||||
|
||||
<parallel_aware_splitting>
|
||||
**When parallelization is enabled, optimize for plan independence.**
|
||||
<dependency_awareness>
|
||||
**Plans declare dependencies explicitly via frontmatter.**
|
||||
|
||||
<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>
|
||||
```yaml
|
||||
# Independent plan (Wave 1 candidate)
|
||||
depends_on: []
|
||||
files_modified: [src/features/user/model.ts, src/features/user/api.ts]
|
||||
autonomous: true
|
||||
|
||||
<vertical_slice_example>
|
||||
**Sequential (creates chain):**
|
||||
# Dependent plan (later wave)
|
||||
depends_on: ["03-01"]
|
||||
files_modified: [src/integration/stripe.ts]
|
||||
autonomous: true
|
||||
```
|
||||
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 (needs models), 03 depends on 02 (needs APIs)
|
||||
Waves: [01] → [02] → [03] (fully sequential)
|
||||
|
||||
**Parallel-aware (creates independence):**
|
||||
```
|
||||
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)
|
||||
</vertical_slice_example>
|
||||
**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)
|
||||
|
||||
<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>
|
||||
**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.
|
||||
**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.
|
||||
|
||||
**Depth rule:** Depth increases plan COUNT, never plan SIZE.
|
||||
|
||||
**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>
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Phase Prompt Template
|
||||
|
||||
Template for `.planning/phases/XX-name/{phase}-{plan}-PLAN.md` - executable phase plans.
|
||||
Template for `.planning/phases/XX-name/{phase}-{plan}-PLAN.md` - executable phase plans optimized for parallel execution.
|
||||
|
||||
**Naming:** Use `{phase}-{plan}-PLAN.md` format (e.g., `01-02-PLAN.md` for Phase 1, Plan 2)
|
||||
|
||||
@@ -13,30 +13,36 @@ Template for `.planning/phases/XX-name/{phase}-{plan}-PLAN.md` - executable phas
|
||||
phase: XX-name
|
||||
plan: NN
|
||||
type: execute
|
||||
depends_on: [] # Plan IDs this plan requires (e.g., ["01-01"]). Empty = independent.
|
||||
files_modified: [] # Files this plan modifies (from <files> elements)
|
||||
depends_on: [] # Plan IDs this plan requires (e.g., ["01-01"]). Empty = parallel candidate.
|
||||
files_modified: [] # Files this plan modifies. Used for conflict detection.
|
||||
autonomous: true # false if plan has checkpoints requiring user interaction
|
||||
domain: [optional - if domain skill loaded]
|
||||
---
|
||||
|
||||
<objective>
|
||||
[What this phase accomplishes - from roadmap phase goal]
|
||||
[What this plan accomplishes]
|
||||
|
||||
Purpose: [Why this matters for the project]
|
||||
Output: [What artifacts will be created]
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
~/.claude/get-shit-done/workflows/execute-plan.md
|
||||
./summary.md
|
||||
@~/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@~/.claude/get-shit-done/templates/summary.md
|
||||
[If plan contains checkpoint tasks (type="checkpoint:*"), add:]
|
||||
~/.claude/get-shit-done/references/checkpoints.md
|
||||
@~/.claude/get-shit-done/references/checkpoints.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
[If discovery exists:]
|
||||
@.planning/phases/XX-name/DISCOVERY.md
|
||||
@.planning/STATE.md
|
||||
|
||||
# Only reference prior plan SUMMARYs if genuinely needed:
|
||||
# - This plan uses types/exports from prior plan
|
||||
# - Prior plan made decision that affects this plan
|
||||
# Do NOT reflexively chain: Plan 02 refs 01, Plan 03 refs 02...
|
||||
|
||||
[Relevant source files:]
|
||||
@src/path/to/relevant.ts
|
||||
</context>
|
||||
@@ -77,14 +83,6 @@ Output: [What artifacts will be created]
|
||||
<resume-signal>[How to indicate choice - "Select: option-a or option-b"]</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: [Action-oriented name]</name>
|
||||
<files>path/to/file.ext</files>
|
||||
<action>[Specific implementation]</action>
|
||||
<verify>[Command or check]</verify>
|
||||
<done>[Acceptance criteria]</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking">
|
||||
<what-built>[What Claude just built that needs verification]</what-built>
|
||||
<how-to-verify>
|
||||
@@ -96,12 +94,10 @@ Output: [What artifacts will be created]
|
||||
<resume-signal>Type "approved" to continue, or describe issues to fix</resume-signal>
|
||||
</task>
|
||||
|
||||
[Continue for all tasks - mix of auto and checkpoints as needed...]
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
Before declaring phase complete:
|
||||
Before declaring plan complete:
|
||||
- [ ] [Specific test command]
|
||||
- [ ] [Build/type check passes]
|
||||
- [ ] [Behavior verification]
|
||||
@@ -112,188 +108,190 @@ Before declaring phase complete:
|
||||
- All tasks completed
|
||||
- All verification checks pass
|
||||
- No errors or warnings introduced
|
||||
- [Phase-specific criteria]
|
||||
- [Plan-specific criteria]
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`:
|
||||
|
||||
# Phase [X] Plan [Y]: [Name] Summary
|
||||
|
||||
**[Substantive one-liner - what shipped, not "phase complete"]**
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- [Key outcome 1]
|
||||
- [Key outcome 2]
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `path/to/file.ts` - Description
|
||||
- `path/to/another.ts` - Description
|
||||
|
||||
## Decisions Made
|
||||
|
||||
[Key decisions and rationale, or "None"]
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
[Problems and resolutions, or "None"]
|
||||
|
||||
## Next Step
|
||||
|
||||
[If more plans in this phase: "Ready for {phase}-{next-plan}-PLAN.md"]
|
||||
[If phase complete: "Phase complete, ready for next phase"]
|
||||
After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
|
||||
</output>
|
||||
```
|
||||
|
||||
<key_elements>
|
||||
From create-meta-prompts patterns:
|
||||
---
|
||||
|
||||
- XML structure for Claude parsing
|
||||
- @context references for file loading
|
||||
- Task types: auto, checkpoint:human-action, checkpoint:human-verify, checkpoint:decision
|
||||
- Action includes "what to avoid and WHY" (from intelligence-rules)
|
||||
- Verification is specific and executable
|
||||
- Success criteria is measurable
|
||||
- Output specification includes SUMMARY.md structure
|
||||
</key_elements>
|
||||
## Frontmatter Fields
|
||||
|
||||
| Field | Required | Purpose |
|
||||
|-------|----------|---------|
|
||||
| `phase` | Yes | Phase identifier (e.g., `01-foundation`) |
|
||||
| `plan` | Yes | Plan number within phase (e.g., `01`, `02`) |
|
||||
| `type` | Yes | Always `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` to build execution waves. Plans with `depends_on: []` and no file conflicts with sibling plans run in Wave 1 (parallel).
|
||||
|
||||
---
|
||||
|
||||
## Parallel vs Sequential
|
||||
|
||||
<parallel_examples>
|
||||
|
||||
**Wave 1 candidates (parallel):**
|
||||
|
||||
```yaml
|
||||
# Plan 01 - User feature
|
||||
depends_on: []
|
||||
files_modified: [src/models/user.ts, src/api/users.ts]
|
||||
autonomous: true
|
||||
|
||||
# Plan 02 - Product feature (no overlap with Plan 01)
|
||||
depends_on: []
|
||||
files_modified: [src/models/product.ts, src/api/products.ts]
|
||||
autonomous: true
|
||||
|
||||
# Plan 03 - Order feature (no overlap)
|
||||
depends_on: []
|
||||
files_modified: [src/models/order.ts, src/api/orders.ts]
|
||||
autonomous: true
|
||||
```
|
||||
|
||||
All three run in parallel (Wave 1) - no dependencies, no file conflicts.
|
||||
|
||||
**Sequential (genuine dependency):**
|
||||
|
||||
```yaml
|
||||
# Plan 01 - Auth foundation
|
||||
depends_on: []
|
||||
files_modified: [src/lib/auth.ts, src/middleware/auth.ts]
|
||||
autonomous: true
|
||||
|
||||
# Plan 02 - Protected features (needs auth)
|
||||
depends_on: ["01"]
|
||||
files_modified: [src/features/dashboard.ts]
|
||||
autonomous: true
|
||||
```
|
||||
|
||||
Plan 02 waits for Plan 01 - genuine dependency on auth types/middleware.
|
||||
|
||||
**Checkpoint plan:**
|
||||
|
||||
```yaml
|
||||
# Plan 03 - UI with verification
|
||||
depends_on: ["01", "02"]
|
||||
files_modified: [src/components/Dashboard.tsx]
|
||||
autonomous: false # Has checkpoint:human-verify
|
||||
```
|
||||
|
||||
Runs after Wave 1, pauses at checkpoint, orchestrator presents to user, resumes on approval.
|
||||
|
||||
</parallel_examples>
|
||||
|
||||
---
|
||||
|
||||
## Context Section
|
||||
|
||||
**Parallel-aware context:**
|
||||
|
||||
```markdown
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
|
||||
# Only include SUMMARY refs if genuinely needed:
|
||||
# - This plan imports types from prior plan
|
||||
# - Prior plan made decision affecting this plan
|
||||
# - Prior plan's output is input to this plan
|
||||
#
|
||||
# Independent plans need NO prior SUMMARY references.
|
||||
# Do NOT reflexively chain: 02 refs 01, 03 refs 02...
|
||||
|
||||
@src/relevant/source.ts
|
||||
</context>
|
||||
```
|
||||
|
||||
**Bad pattern (creates false dependencies):**
|
||||
```markdown
|
||||
<context>
|
||||
@.planning/phases/03-features/03-01-SUMMARY.md # Just because it's earlier
|
||||
@.planning/phases/03-features/03-02-SUMMARY.md # Reflexive chaining
|
||||
</context>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scope Guidance
|
||||
|
||||
<scope_guidance>
|
||||
**Plan sizing:**
|
||||
|
||||
- Aim for 2-3 tasks per plan
|
||||
- If planning >3 tasks, split into multiple plans (01-01, 01-02, etc.)
|
||||
- Target ~50% context usage maximum
|
||||
- Complex phases: Create 01-01, 01-02, 01-03 plans instead of one large plan
|
||||
- 2-3 tasks per plan
|
||||
- ~50% context usage maximum
|
||||
- Complex phases: Multiple focused plans, not one large plan
|
||||
|
||||
**When to split:**
|
||||
|
||||
- Different subsystems (auth vs API vs UI)
|
||||
- Clear dependency boundaries (setup → implement → test)
|
||||
- Risk of context overflow (>50% estimated usage)
|
||||
- **TDD candidates** - Features that warrant TDD become their own TDD plans
|
||||
</scope_guidance>
|
||||
- >3 tasks
|
||||
- Risk of context overflow
|
||||
- TDD candidates - separate plans
|
||||
|
||||
<tdd_plan_note>
|
||||
**TDD features get dedicated plans.**
|
||||
**Vertical slices preferred:**
|
||||
|
||||
TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR) that consume 40-50% context for a single feature. Features warranting TDD (business logic, validation, algorithms, API contracts) each get their own TDD plan.
|
||||
```
|
||||
PREFER: Plan 01 = User (model + API + UI)
|
||||
Plan 02 = Product (model + API + UI)
|
||||
|
||||
AVOID: Plan 01 = All models
|
||||
Plan 02 = All APIs
|
||||
Plan 03 = All UIs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## TDD Plans
|
||||
|
||||
TDD features get dedicated plans with `type: tdd`.
|
||||
|
||||
**Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
|
||||
→ Yes: Create a TDD plan (one feature per plan)
|
||||
→ Yes: Create a TDD plan
|
||||
→ No: Standard task in standard plan
|
||||
|
||||
See `~/.claude/get-shit-done/references/tdd.md` for TDD plan structure.
|
||||
</tdd_plan_note>
|
||||
|
||||
<good_examples>
|
||||
|
||||
**Sequential plan (has dependencies):**
|
||||
|
||||
```markdown
|
||||
---
|
||||
phase: 01-foundation
|
||||
plan: 02
|
||||
type: execute
|
||||
depends_on: ["01-01"]
|
||||
files_modified: [src/app/api/auth/login/route.ts]
|
||||
domain: next-js
|
||||
---
|
||||
```
|
||||
|
||||
**Independent plan (can run parallel):**
|
||||
## Task Types
|
||||
|
||||
| Type | Use For | Autonomy |
|
||||
|------|---------|----------|
|
||||
| `auto` | Everything Claude can do independently | Fully autonomous |
|
||||
| `checkpoint:human-verify` | Visual/functional verification | Pauses, returns to orchestrator |
|
||||
| `checkpoint:decision` | Implementation choices | Pauses, returns to orchestrator |
|
||||
| `checkpoint:human-action` | Truly unavoidable manual steps (rare) | Pauses, returns to orchestrator |
|
||||
|
||||
**Checkpoint behavior in parallel execution:**
|
||||
- Plan runs until checkpoint
|
||||
- Agent returns with checkpoint details + agent_id
|
||||
- Orchestrator presents to user
|
||||
- User responds
|
||||
- Orchestrator resumes agent with `resume: agent_id`
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
**Autonomous parallel plan:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
phase: 03-features
|
||||
plan: 02
|
||||
type: execute
|
||||
depends_on: []
|
||||
files_modified: [src/components/Dashboard.tsx, src/hooks/useDashboard.ts]
|
||||
---
|
||||
```
|
||||
|
||||
**Full example:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
phase: 01-foundation
|
||||
plan: 01
|
||||
type: execute
|
||||
depends_on: []
|
||||
files_modified: [prisma/schema.prisma, src/lib/db.ts]
|
||||
domain: next-js
|
||||
---
|
||||
|
||||
<objective>
|
||||
Set up Next.js project with authentication foundation.
|
||||
|
||||
Purpose: Establish the core structure and auth patterns all features depend on.
|
||||
Output: Working Next.js app with JWT auth, protected routes, and user model.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
~/.claude/get-shit-done/workflows/execute-plan.md
|
||||
./summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@src/lib/db.ts
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Add User model to database schema</name>
|
||||
<files>prisma/schema.prisma</files>
|
||||
<action>Add User model with fields: id (cuid), email (unique), passwordHash, createdAt, updatedAt. Add Session relation. Use @db.VarChar(255) for email to prevent index issues.</action>
|
||||
<verify>npx prisma validate passes, npx prisma generate succeeds</verify>
|
||||
<done>Schema valid, types generated, no errors</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Create login API endpoint</name>
|
||||
<files>src/app/api/auth/login/route.ts</files>
|
||||
<action>POST endpoint that accepts {email, password}, validates against User table using bcrypt, returns JWT in httpOnly cookie with 15-min expiry. Use jose library for JWT (not jsonwebtoken - it has CommonJS issues with Next.js).</action>
|
||||
<verify>curl -X POST /api/auth/login -d '{"email":"test@test.com","password":"test"}' -H "Content-Type: application/json" returns 200 with Set-Cookie header</verify>
|
||||
<done>Valid credentials return 200 + cookie, invalid return 401, missing fields return 400</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
Before declaring phase complete:
|
||||
- [ ] `npm run build` succeeds without errors
|
||||
- [ ] `npx prisma validate` passes
|
||||
- [ ] Login endpoint responds correctly to valid/invalid credentials
|
||||
- [ ] Protected route redirects unauthenticated users
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
- All tasks completed
|
||||
- All verification checks pass
|
||||
- No TypeScript errors
|
||||
- JWT auth flow works end-to-end
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/01-foundation/01-01-SUMMARY.md`
|
||||
</output>
|
||||
```
|
||||
|
||||
**Independent plan example:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
phase: 05-features
|
||||
plan: 01
|
||||
type: execute
|
||||
depends_on: []
|
||||
files_modified: [src/features/user/model.ts, src/features/user/api.ts, src/features/user/UserList.tsx]
|
||||
autonomous: true
|
||||
---
|
||||
|
||||
<objective>
|
||||
@@ -306,87 +304,150 @@ Output: User model, API endpoints, and UI components.
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
</context>
|
||||
...
|
||||
|
||||
<tasks>
|
||||
<task type="auto">
|
||||
<name>Task 1: Create User model</name>
|
||||
<files>src/features/user/model.ts</files>
|
||||
<action>Define User type with id, email, name, createdAt. Export TypeScript interface.</action>
|
||||
<verify>tsc --noEmit passes</verify>
|
||||
<done>User type exported and usable</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Create User API endpoints</name>
|
||||
<files>src/features/user/api.ts</files>
|
||||
<action>GET /users (list), GET /users/:id (single), POST /users (create). Use User type from model.</action>
|
||||
<verify>curl tests pass for all endpoints</verify>
|
||||
<done>All CRUD operations work</done>
|
||||
</task>
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
- [ ] npm run build succeeds
|
||||
- [ ] API endpoints respond correctly
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- All tasks completed
|
||||
- User feature works end-to-end
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/03-features/03-01-SUMMARY.md`
|
||||
</output>
|
||||
```
|
||||
|
||||
**Dependent plan example:**
|
||||
**Plan with checkpoint (non-autonomous):**
|
||||
|
||||
```markdown
|
||||
---
|
||||
phase: 06-integration
|
||||
plan: 02
|
||||
phase: 03-features
|
||||
plan: 03
|
||||
type: execute
|
||||
depends_on: ["06-01"]
|
||||
files_modified: [src/integration/stripe.ts]
|
||||
depends_on: ["03-01", "03-02"]
|
||||
files_modified: [src/components/Dashboard.tsx]
|
||||
autonomous: false
|
||||
---
|
||||
|
||||
<objective>
|
||||
Integrate Stripe payments using auth from Plan 01.
|
||||
Build dashboard with visual verification.
|
||||
|
||||
Purpose: Add payment processing that requires authenticated users.
|
||||
Output: Stripe integration with user-linked payments.
|
||||
Purpose: Integrate user and product features into unified view.
|
||||
Output: Working dashboard component.
|
||||
</objective>
|
||||
|
||||
<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>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/phases/06-integration/06-01-SUMMARY.md
|
||||
@.planning/phases/03-features/03-01-SUMMARY.md
|
||||
@.planning/phases/03-features/03-02-SUMMARY.md
|
||||
</context>
|
||||
...
|
||||
|
||||
<tasks>
|
||||
<task type="auto">
|
||||
<name>Task 1: Build Dashboard layout</name>
|
||||
<files>src/components/Dashboard.tsx</files>
|
||||
<action>Create responsive grid with UserList and ProductList components. Use Tailwind for styling.</action>
|
||||
<verify>npm run build succeeds</verify>
|
||||
<done>Dashboard renders without errors</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking">
|
||||
<what-built>Responsive dashboard with user and product sections</what-built>
|
||||
<how-to-verify>
|
||||
1. Run: npm run dev
|
||||
2. Visit: http://localhost:3000/dashboard
|
||||
3. Desktop: Verify two-column grid
|
||||
4. Mobile: Verify stacked layout
|
||||
5. Check: No layout shift, no scroll issues
|
||||
</how-to-verify>
|
||||
<resume-signal>Type "approved" or describe issues</resume-signal>
|
||||
</task>
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
- [ ] npm run build succeeds
|
||||
- [ ] Visual verification passed
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- All tasks completed
|
||||
- User approved visual layout
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/03-features/03-03-SUMMARY.md`
|
||||
</output>
|
||||
```
|
||||
|
||||
**Parallelization rules:**
|
||||
- Empty `depends_on` + no file conflicts with sibling plans = can run parallel
|
||||
- Non-empty `depends_on` OR shared files = must run sequentially
|
||||
- `/gsd:execute-phase` analyzes this automatically
|
||||
---
|
||||
|
||||
</good_examples>
|
||||
## Anti-Patterns
|
||||
|
||||
<bad_examples>
|
||||
|
||||
```markdown
|
||||
# Phase 1: Foundation
|
||||
|
||||
## Tasks
|
||||
|
||||
### Task 1: Set up authentication
|
||||
|
||||
**Action**: Add auth to the app
|
||||
**Done when**: Users can log in
|
||||
**Bad: Reflexive dependency chaining**
|
||||
```yaml
|
||||
depends_on: ["03-01"] # Just because 01 comes before 02
|
||||
```
|
||||
|
||||
This is useless. No XML structure, no @context, no verification, no specificity.
|
||||
</bad_examples>
|
||||
**Bad: Horizontal layer grouping**
|
||||
```
|
||||
Plan 01: All models
|
||||
Plan 02: All APIs (depends on 01)
|
||||
Plan 03: All UIs (depends on 02)
|
||||
```
|
||||
|
||||
**Bad: Missing autonomy flag**
|
||||
```yaml
|
||||
# Has checkpoint but no autonomous: false
|
||||
depends_on: []
|
||||
files_modified: [...]
|
||||
# autonomous: ??? <- Missing!
|
||||
```
|
||||
|
||||
**Bad: Vague tasks**
|
||||
```xml
|
||||
<task type="auto">
|
||||
<name>Set up authentication</name>
|
||||
<action>Add auth to the app</action>
|
||||
</task>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Guidelines
|
||||
|
||||
<guidelines>
|
||||
**When to use:**
|
||||
- Creating execution plans for each phase
|
||||
- One plan per 2-3 tasks, multiple plans per phase if needed
|
||||
- Always use XML structure for Claude parsing
|
||||
|
||||
**Task types:**
|
||||
|
||||
- `type="auto"`: Execute without stopping
|
||||
- `type="checkpoint:human-action"`: User must do something (manual step)
|
||||
- `type="checkpoint:human-verify"`: User must verify output (testing, visual check)
|
||||
- `type="checkpoint:decision"`: User must choose between options
|
||||
|
||||
**Gate values:**
|
||||
|
||||
- `gate="blocking"`: Must resolve before continuing
|
||||
- `gate="optional"`: Can skip or defer
|
||||
|
||||
**Context references:**
|
||||
|
||||
- Use @path/to/file.md to load files
|
||||
- Always include @.planning/PROJECT.md and @.planning/ROADMAP.md
|
||||
- Include relevant source files for context
|
||||
- Include workflow/template references
|
||||
|
||||
**After completion:**
|
||||
|
||||
- Create SUMMARY.md in same directory
|
||||
- Follow summary.md template structure
|
||||
- Document deviations, decisions, issues
|
||||
</guidelines>
|
||||
- Include `depends_on`, `files_modified`, `autonomous` in every plan
|
||||
- Prefer vertical slices over horizontal layers
|
||||
- Only reference prior SUMMARYs when genuinely needed
|
||||
- Group checkpoints with related auto tasks in same plan
|
||||
- 2-3 tasks per plan, ~50% context max
|
||||
|
||||
@@ -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