diff --git a/get-shit-done/references/plan-format.md b/get-shit-done/references/plan-format.md index f7ea067e..e3780f07 100644 --- a/get-shit-done/references/plan-format.md +++ b/get-shit-done/references/plan-format.md @@ -10,14 +10,50 @@ A plan is Claude-executable when Claude can read the PLAN.md and immediately sta If Claude has to guess, interpret, or make assumptions - the task is too vague. + +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. + + 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 --- @@ -26,9 +62,19 @@ Purpose: [...] Output: [...] + +@~/.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 + + @.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 @@ -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. @@ -274,14 +328,22 @@ Use @file references to load context for the prompt: ```markdown @.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 ``` 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. @@ -320,22 +382,7 @@ Specify the SUMMARY.md structure: ```markdown -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` ``` diff --git a/get-shit-done/references/scope-estimation.md b/get-shit-done/references/scope-estimation.md index 15e167f5..3db1308e 100644 --- a/get-shit-done/references/scope-estimation.md +++ b/get-shit-done/references/scope-estimation.md @@ -78,103 +78,78 @@ See `~/.claude/get-shit-done/references/tdd.md` for TDD plan structure. -**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 +``` - -**When parallelization is enabled, optimize for plan independence.** + +**Plans declare dependencies explicitly via frontmatter.** - -| 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 | - +```yaml +# Independent plan (Wave 1 candidate) +depends_on: [] +files_modified: [src/features/user/model.ts, src/features/user/api.ts] +autonomous: true - -**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) - +**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) - -**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 - +**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 + -**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. - -**Minimize SUMMARY references when parallel-aware:** - -**Before (sequential habit):** -```markdown - -@.planning/phases/05-features/05-01-SUMMARY.md # Always reference prior -@.planning/phases/05-features/05-02-SUMMARY.md # Chain continues - -``` - -**After (parallel-aware):** -```markdown - -# Only reference if this plan ACTUALLY needs decisions from prior plan -# Most parallel plans don't need any SUMMARY references - -``` - -**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 - - - **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) @@ -246,15 +239,18 @@ Each plan: fresh context, peak quality. More plans = more thoroughness, same qua **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). diff --git a/get-shit-done/templates/phase-prompt.md b/get-shit-done/templates/phase-prompt.md index bf02715d..b01d3896 100644 --- a/get-shit-done/templates/phase-prompt.md +++ b/get-shit-done/templates/phase-prompt.md @@ -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 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] --- -[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] -~/.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 @.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 @@ -77,14 +83,6 @@ Output: [What artifacts will be created] [How to indicate choice - "Select: option-a or option-b"] - - Task 3: [Action-oriented name] - path/to/file.ext - [Specific implementation] - [Command or check] - [Acceptance criteria] - - [What Claude just built that needs verification] @@ -96,12 +94,10 @@ Output: [What artifacts will be created] Type "approved" to continue, or describe issues to fix -[Continue for all tasks - mix of auto and checkpoints as needed...] - -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] -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` ``` - -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 - +## 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 + + + +**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. + + + +--- + +## Context Section + +**Parallel-aware context:** + +```markdown + +@.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 + +``` + +**Bad pattern (creates false dependencies):** +```markdown + +@.planning/phases/03-features/03-01-SUMMARY.md # Just because it's earlier +@.planning/phases/03-features/03-02-SUMMARY.md # Reflexive chaining + +``` + +--- + +## 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 - +- >3 tasks +- Risk of context overflow +- TDD candidates - separate plans - -**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. - - - -**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 ---- - - -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. - - - -~/.claude/get-shit-done/workflows/execute-plan.md -./summary.md - - - -@.planning/PROJECT.md -@.planning/ROADMAP.md -@src/lib/db.ts - - - - - - Task 1: Add User model to database schema - prisma/schema.prisma - 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. - npx prisma validate passes, npx prisma generate succeeds - Schema valid, types generated, no errors - - - - Task 2: Create login API endpoint - src/app/api/auth/login/route.ts - 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). - curl -X POST /api/auth/login -d '{"email":"test@test.com","password":"test"}' -H "Content-Type: application/json" returns 200 with Set-Cookie header - Valid credentials return 200 + cookie, invalid return 401, missing fields return 400 - - - - - -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 - - - - -- All tasks completed -- All verification checks pass -- No TypeScript errors -- JWT auth flow works end-to-end - - - -After completion, create `.planning/phases/01-foundation/01-01-SUMMARY.md` - -``` - -**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 --- @@ -306,87 +304,150 @@ Output: User model, API endpoints, and UI components. @.planning/PROJECT.md @.planning/ROADMAP.md +@.planning/STATE.md -... + + + + Task 1: Create User model + src/features/user/model.ts + Define User type with id, email, name, createdAt. Export TypeScript interface. + tsc --noEmit passes + User type exported and usable + + + + Task 2: Create User API endpoints + src/features/user/api.ts + GET /users (list), GET /users/:id (single), POST /users (create). Use User type from model. + curl tests pass for all endpoints + All CRUD operations work + + + + +- [ ] npm run build succeeds +- [ ] API endpoints respond correctly + + + +- All tasks completed +- User feature works end-to-end + + + +After completion, create `.planning/phases/03-features/03-01-SUMMARY.md` + ``` -**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 --- -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. + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md +@~/.claude/get-shit-done/references/checkpoints.md + + @.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 -... + + + + Task 1: Build Dashboard layout + src/components/Dashboard.tsx + Create responsive grid with UserList and ProductList components. Use Tailwind for styling. + npm run build succeeds + Dashboard renders without errors + + + + Responsive dashboard with user and product sections + + 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 + + Type "approved" or describe issues + + + + +- [ ] npm run build succeeds +- [ ] Visual verification passed + + + +- All tasks completed +- User approved visual layout + + + +After completion, create `.planning/phases/03-features/03-03-SUMMARY.md` + ``` -**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 +--- - +## Anti-Patterns - - -```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: 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 + + Set up authentication + Add auth to the app + +``` + +--- + +## 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 - +- 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 diff --git a/get-shit-done/workflows/execute-phase.md b/get-shit-done/workflows/execute-phase.md index 0c49b072..fcfa8704 100644 --- a/get-shit-done/workflows/execute-phase.md +++ b/get-shit-done/workflows/execute-phase.md @@ -3,7 +3,7 @@ Execute all plans in a phase using wave-based parallel execution. Orchestrator s -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. @@ -29,7 +29,7 @@ Report: "Found {N} plans in {phase_dir}" -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. -For each incomplete plan, check if it depends on outputs from other plans. +Build dependency graph from frontmatter: -**Read each plan's `` 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} ``` @@ -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 ``` -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 `` for details. + +6. **Proceed to next wave** + + + + +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 @@ -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}` -`/clear` first → fresh context window +`/clear` first for fresh context ``` **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 - -Plans with checkpoints require user interaction. These cannot run fully autonomous. + +**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. - +**STATE.md tracks:** +- Last completed plan +- Current wave +- Any pending checkpoints + diff --git a/get-shit-done/workflows/plan-phase.md b/get-shit-done/workflows/plan-phase.md index 776be6e0..bf1f5e3f 100644 --- 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: -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. +**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. - -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). - - Check for codebase map: @@ -255,7 +241,12 @@ cat .planning/phases/XX-name/${PHASE}-CONTEXT.md 2>/dev/null -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. - -**Restructure task grouping for parallel execution when enabled.** + +**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 `` 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? + + + +**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) +``` -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. @@ -399,22 +458,39 @@ Auto-approve and proceed to write_phase_prompt. -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. @@ -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 @@ -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 ``` -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 + +@~/.claude/get-shit-done/workflows/execute-plan.md +@~/.claude/get-shit-done/templates/summary.md +@~/.claude/get-shit-done/references/checkpoints.md + +``` -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. @@ -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" ``` -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. @@ -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