msd-core/get-shit-done/workflows/plan-phase.md

<decimal_phase_numbering> Decimal phases enable urgent work insertion without renumbering:

• Integer phases (1, 2, 3) = planned milestone work
• Decimal phases (2.1, 2.2) = urgent insertions between integers

Rules:

• Decimals between consecutive integers (2.1 between 2 and 3)
• Filesystem sorting works automatically (2 < 2.1 < 2.2 < 3)
• Directory format: 02.1-description/, Plan format: 02.1-01-PLAN.md

Validation: Integer X must exist and be complete, X+1 must exist, decimal X.Y must not exist, Y >= 1 </decimal_phase_numbering>

<required_reading> Read these files NOW:

1. ~/.claude/get-shit-done/templates/phase-prompt.md
2. ~/.claude/get-shit-done/references/plan-format.md
3. ~/.claude/get-shit-done/references/scope-estimation.md
4. ~/.claude/get-shit-done/references/checkpoints.md
5. ~/.claude/get-shit-done/references/tdd.md
6. .planning/ROADMAP.md
7. .planning/PROJECT.md

Load domain expertise from ROADMAP:

• Parse ROADMAP.md's ## Domain Expertise section for paths
• Read each domain SKILL.md (these serve as indexes)
• Determine phase type and load ONLY references relevant to THIS phase type from each SKILL.md's <references_index> </required_reading>

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.

<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.

Observable by design: Plan to debug your own work. Include meaningful error messages, appropriate logging, and clear failure states. </planning_principles>

Read `.planning/STATE.md` and parse: - Current position (which phase we're planning) - Accumulated decisions (constraints on this phase) - Pending todos (candidates for inclusion) - Blockers/concerns (things this phase may address) - Brief alignment status

If STATE.md missing but .planning/ exists, offer to reconstruct or continue without.

Check for codebase map:

ls .planning/codebase/*.md 2>/dev/null

If .planning/codebase/ exists: Load relevant documents based on phase type:

Phase Keywords	Load These
UI, frontend, components	CONVENTIONS.md, STRUCTURE.md
API, backend, endpoints	ARCHITECTURE.md, CONVENTIONS.md
database, schema, models	ARCHITECTURE.md, STACK.md
testing, tests	TESTING.md, CONVENTIONS.md
integration, external API	INTEGRATIONS.md, STACK.md
refactor, cleanup	CONCERNS.md, ARCHITECTURE.md
setup, config	STACK.md, STRUCTURE.md
(default)	STACK.md, ARCHITECTURE.md

Track extracted constraints for PLAN.md context section.

Check roadmap and existing phases:

cat .planning/ROADMAP.md
ls .planning/phases/

If multiple phases available, ask which one to plan. If obvious (first incomplete phase), proceed.

Phase number parsing: Regex ^(\d+)(?:\.(\d+))?$ - Group 1: integer, Group 2: decimal (optional)

If decimal phase: Validate integer X exists and is complete, X+1 exists in roadmap, decimal X.Y doesn't exist, Y >= 1.

Read any existing PLAN.md or DISCOVERY.md in the phase directory.

**Discovery is MANDATORY unless you can prove current context exists.**

<discovery_decision> Level 0 - Skip (pure internal work, existing patterns only)

• ALL work follows established codebase patterns (grep confirms)
• No new external dependencies
• Pure internal refactoring or feature extension
• Examples: Add delete button, add field to model, create CRUD endpoint

Level 1 - Quick Verification (2-5 min)

• Single known library, confirming syntax/version
• Low-risk decision (easily changed later)
• Action: Context7 resolve-library-id + query-docs, no DISCOVERY.md needed

Level 2 - Standard Research (15-30 min)

• Choosing between 2-3 options
• New external integration (API, service)
• Medium-risk decision
• Action: Route to workflows/discovery-phase.md depth=standard, produces DISCOVERY.md

Level 3 - Deep Dive (1+ hour)

• Architectural decision with long-term impact
• Novel problem without clear patterns
• High-risk, hard to change later
• Action: Route to workflows/discovery-phase.md depth=deep, full DISCOVERY.md

Depth indicators:

• Level 2+: New library not in package.json, external API, "choose/select/evaluate" in description, roadmap marked Research: Yes
• Level 3: "architecture/design/system", multiple external services, data modeling, auth design, real-time/distributed </discovery_decision>

If roadmap flagged Research: Likely, Level 0 (skip) is not available.

For niche domains (3D, games, audio, shaders, ML), suggest /gsd:research-phase before plan-phase.

**Intelligent context assembly from frontmatter dependency graph:**

1. Scan all summary frontmatter (cheap - first ~25 lines):

for f in .planning/phases/*/*-SUMMARY.md; do
  # Extract frontmatter only (between first two --- markers)
  sed -n '1,/^---$/p; /^---$/q' "$f" | head -30
done

Parse YAML to extract: phase, subsystem, requires, provides, affects, tags, key-decisions, key-files

2. Build dependency graph for current phase:

• Check affects field: Which prior phases have current phase in their affects list? → Direct dependencies
• Check subsystem: Which prior phases share same subsystem? → Related work
• Check requires chains: If phase X requires phase Y, and we need X, we also need Y → Transitive dependencies
• Check roadmap: Any phases marked as dependencies in ROADMAP.md phase description?

3. Select relevant summaries:

Auto-select phases that match ANY of:

• Current phase name/number appears in prior phase's affects field
• Same subsystem value
• In requires chain (transitive closure)
• Explicitly mentioned in STATE.md decisions as affecting current phase

Typical selection: 2-4 prior phases (immediately prior + related subsystem work)

4. Extract context from frontmatter (WITHOUT opening full summaries yet):

From selected phases' frontmatter, extract:

• Tech available: Union of all tech-stack.added lists
• Patterns established: Union of all tech-stack.patterns and patterns-established
• Key files: Union of all key-files (for @context references)
• Decisions: Extract key-decisions from frontmatter

5. Now read FULL summaries for selected phases:

Only now open and read complete SUMMARY.md files for the selected relevant phases. Extract:

• Detailed "Accomplishments" section
• "Next Phase Readiness" warnings/blockers
• "Issues Encountered" that might affect current phase
• "Deviations from Plan" for patterns

From STATE.md: Decisions → constrain approach. Pending todos → candidates. Blockers → may need to address.

From pending todos:

ls .planning/todos/pending/*.md 2>/dev/null

Assess each pending todo - relevant to this phase? Natural to address now?

Answer before proceeding:

• Q1: What decisions from previous phases constrain this phase?
• Q2: Are there pending todos that should become tasks?
• Q3: Are there concerns from "Next Phase Readiness" that apply?
• Q4: Given all context, does the roadmap's description still make sense?

Track for PLAN.md context section:

• Which summaries were selected (for @context references)
• Tech stack available (from frontmatter)
• Established patterns (from frontmatter)
• Key files to reference (from frontmatter)
• Applicable decisions (from frontmatter + full summary)
• Todos being addressed (from pending todos)
• Concerns being verified (from "Next Phase Readiness")

Understand: - Phase goal (from roadmap) - What exists already (scan codebase if mid-project) - Dependencies met (previous phases complete?) - Any {phase}-RESEARCH.md (from /gsd:research-phase) - Any DISCOVERY.md (from mandatory discovery) - Any {phase}-CONTEXT.md (from /gsd:discuss-phase)

# If mid-project, understand current state
ls -la src/ 2>/dev/null
cat package.json 2>/dev/null | head -20

# Check for ecosystem research (from /gsd:research-phase)
cat .planning/phases/XX-name/${PHASE}-RESEARCH.md 2>/dev/null

# Check for phase context (from /gsd:discuss-phase)
cat .planning/phases/XX-name/${PHASE}-CONTEXT.md 2>/dev/null

If RESEARCH.md exists: Use standard_stack (these libraries), architecture_patterns (follow in task structure), dont_hand_roll (NEVER custom solutions for listed problems), common_pitfalls (inform verification), code_examples (reference in actions).

If CONTEXT.md exists: Honor vision, prioritize essential, respect boundaries, incorporate specifics.

If neither exist: Suggest /gsd:research-phase for niche domains, /gsd:discuss-phase for simpler domains, or proceed with roadmap only.

**BEFORE breaking into tasks, work BACKWARD from the phase goal.**

This step prevents the common failure mode: tasks complete but goal not achieved.

See ~/.claude/get-shit-done/references/goal-backward.md for complete guidance.

1. State the phase goal:

Extract from ROADMAP.md. Reframe if task-shaped:

• Task-shaped: "implement chat system" → Outcome-shaped: "users can chat"
• Task-shaped: "add authentication" → Outcome-shaped: "users can log in securely"

2. Derive observable truths:

Ask: "What must be TRUE for this goal to be achieved?"

List 3-7 truths from the USER's perspective:

• "User can see existing messages"
• "User can type and send a message"
• "Sent message appears in the list"
• "Messages persist across refresh"

Test: Each truth should be verifiable by a human using the app. If you can't test it by clicking around, it's not observable.

3. Derive required artifacts:

For each truth, ask: "What must EXIST for this to be true?"

Map truths to concrete files:

"User can see existing messages" requires:
  - src/components/Chat.tsx (renders messages)
  - src/app/api/chat/route.ts (provides messages)
  - prisma/schema.prisma (Message model)

Test: Each artifact should be a specific file path. If you can't point to where it lives, it's too abstract.

4. Derive key links (wiring):

For each artifact, ask: "What must be CONNECTED for this to function?"

Key links are critical connections:

- Chat.tsx → /api/chat: fetch in useEffect, response mapped to state
- /api/chat GET → database: prisma.message.findMany, result returned
- ChatInput onSubmit → /api/chat POST: fetch call, not just console.log

Test: Wiring is verified by tracing data flow. Does A actually call B?

5. Identify highest-risk links:

Ask: "Where is this most likely to break?"

These get extra verification attention. Common high-risk links:

• Form submit → API call (often stubbed with console.log)
• API handler → database query (often returns hardcoded data)
• Component → real data (often renders placeholder)

6. Document must-haves:

Structure for PLAN.md frontmatter:

must_haves:
  truths:
    - "User can see existing messages"
    - "User can send a message"
    - "Messages persist across refresh"
  artifacts:
    - path: "src/components/Chat.tsx"
      provides: "Message list rendering"
      min_lines: 30
    - path: "src/app/api/chat/route.ts"
      provides: "Message CRUD"
      exports: ["GET", "POST"]
    - path: "prisma/schema.prisma"
      provides: "Message model"
      contains: "model Message"
  key_links:
    - from: "src/components/Chat.tsx"
      to: "/api/chat"
      via: "fetch in useEffect"
      pattern: "fetch.*api/chat"
    - from: "src/app/api/chat/route.ts"
      to: "prisma.message"
      via: "database query"
      pattern: "prisma\\.message"

7. Use must-haves to inform task design:

Tasks should CREATE artifacts and ESTABLISH key links. When writing tasks:

• Each artifact should have a task that creates it
• Each key link should be established (not left as TODO)
• Verification should check the link works, not just that files exist

Why this matters:

Without goal-backward derivation, you get:

• "Create Chat.tsx" ✓ (file exists, but renders placeholder)
• "Create API route" ✓ (file exists, but returns hardcoded data)
• "Phase complete" ✓ (all tasks done)
• "App doesn't work" ✗ (goal not achieved)

With goal-backward derivation:

• Must-haves define what "working" means
• Tasks are designed to achieve must-haves
• Verification checks must-haves after execution
• Gaps found before they compound into later phases

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)
• Task name: Clear, action-oriented
• Files: Which files created/modified (for auto tasks)
• Action: Specific implementation (including what to avoid and WHY)
• Verify: How to prove it worked
• Done: Acceptance criteria

TDD detection: For each potential task, evaluate TDD fit:

TDD candidates (create dedicated TDD plans):

• Business logic with defined inputs/outputs
• API endpoints with request/response contracts
• Data transformations, parsing, formatting
• Validation rules and constraints
• Algorithms with testable behavior
• State machines and workflows

Standard tasks (remain in standard plans):

• UI layout, styling, visual components
• Configuration changes
• Glue code connecting existing components
• One-off scripts and migrations
• Simple CRUD with no business logic

Heuristic: Can you write expect(fn(input)).toBe(output) before writing fn? → 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).

Critical: If external resource has CLI/API (Vercel, Stripe, etc.), use type="auto" to automate. Only checkpoint for verification AFTER automation.

See ~/.claude/get-shit-done/references/checkpoints.md for checkpoint structure.

User setup detection: For tasks involving external services, identify human-required configuration:

External service indicators:

• New SDK: stripe, @sendgrid/mail, twilio, openai, @supabase/supabase-js
• Webhook handlers: Files in **/webhooks/** or **/webhook*
• OAuth integration: Social login, third-party auth
• API keys: Code referencing process.env.SERVICE_* patterns

For each external service, determine:

1. Env vars needed - What secrets must be retrieved from dashboards?
2. Account setup - Does user need to create an account?
3. Dashboard config - What must be configured in external UI?
4. Local dev - Any CLI tools for local testing?

Record in user_setup frontmatter (see write_phase_prompt step).

**Map task dependencies explicitly before grouping into plans.**

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?

2. Build the dependency graph:

Example phase with 6 tasks:

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

Dependency graph:
  A ──→ C ──┐
            ├──→ E ──→ F
  B ──→ D ──┘

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)

3. Identify parallelization opportunities:

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. Detect and prefer vertical slices:

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)

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)

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?

**Compute wave numbers before writing plans.**

Wave assignment algorithm (run in memory before writing any files):

waves = {}  # plan_id -> wave_number

for each plan in plan_order:
  if plan.depends_on is empty:
    plan.wave = 1
  else:
    # Wave = max wave of dependencies + 1
    plan.wave = max(waves[dep] for dep in plan.depends_on) + 1

  waves[plan.id] = plan.wave

Example:

Plan 01: depends_on: []           → wave: 1
Plan 02: depends_on: []           → wave: 1
Plan 03: depends_on: ["01"]       → wave: 2
Plan 04: depends_on: ["02"]       → wave: 2
Plan 05: depends_on: ["03", "04"] → wave: 3

Store wave number with each plan in memory. Write to frontmatter in next step.

**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 grouping, verify each plan fits context budget.

Check depth setting:

cat .planning/config.json 2>/dev/null | grep depth

<depth_aware_splitting> Depth controls compression tolerance, not artificial inflation.

Depth	Typical Plans/Phase	Tasks/Plan
Quick	1-3	2-3
Standard	3-5	2-3
Comprehensive	5-10	2-3

Key principle: Derive plans from actual work. Depth determines how aggressively you combine things, not a target to hit.

• Comprehensive auth phase = 8 plans (because auth genuinely has 8 concerns)
• Comprehensive "add config file" phase = 1 plan (because that's all it is)

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)
• Each plan stays focused: 2-3 tasks, single concern

For quick depth:

• Combine aggressively into fewer plans
• 1-3 plans per phase is fine
• Focus on critical path </depth_aware_splitting>

ALWAYS split if: >3 tasks, multiple subsystems, >5 files in any task, complex domains (auth, payments).

Each plan must be: 2-3 tasks max, ~50% context target, independently committable.

See ~/.claude/get-shit-done/references/scope-estimation.md for complete guidance.

Auto-approve and proceed to write_phase_prompt. Present breakdown with wave structure:

Phase [X] breakdown:

## Execution Waves

**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)

Wait for confirmation. If "adjust": revise. If "start over": return to gather_phase_context.

Use template from `~/.claude/get-shit-done/templates/phase-prompt.md`.

Single plan: Write to .planning/phases/XX-name/{phase}-01-PLAN.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, 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)
• Tasks (XML format with types)
• Verification, Success criteria, Output specification

Plan frontmatter:

---
phase: XX-name
plan: NN
type: execute
wave: N                     # Execution wave (1, 2, 3...). Computed at plan time.
depends_on: []              # Plan IDs this plan requires.
files_modified: []          # Files this plan touches.
autonomous: true            # false if plan has checkpoints requiring user interaction
domain: [optional]
user_setup: []              # Human-required setup (omit if empty)
---

User setup frontmatter (when external services involved):

user_setup:
  - service: stripe
    why: "Payment processing"
    env_vars:
      - name: STRIPE_SECRET_KEY
        source: "Stripe Dashboard → Developers → API keys → Secret key"
      - name: STRIPE_WEBHOOK_SECRET
        source: "Stripe Dashboard → Developers → Webhooks → Signing secret"
    account_setup:
      - url: "https://dashboard.stripe.com/register"
        skip_if: "Already have Stripe account"
    dashboard_config:
      - task: "Create webhook endpoint"
        location: "Stripe Dashboard → Developers → Webhooks → Add endpoint"
        details: "URL: https://[your-domain]/api/webhooks/stripe, Events: checkout.session.completed"
    local_dev:
      - "stripe listen --forward-to localhost:3000/api/webhooks/stripe"

Automation-first rule: Only include setup Claude literally cannot do:

• Account creation (requires human signup)
• Secret retrieval (requires dashboard access)
• Dashboard configuration (requires human in browser)

Do NOT include: npm install, code changes, file creation, CLI commands Claude can run.

Wave is pre-computed: Wave numbers are assigned during planning (see assign_waves step). /gsd:execute-phase reads wave directly from frontmatter and groups plans by wave number. No runtime dependency analysis needed.

Context section - parallel-aware:

Only include prior plan SUMMARY references if this plan genuinely needs decisions/outputs:

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.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.

@path/to/relevant/source.ts
</context>

For plans with checkpoints:

Include checkpoint reference in execution_context:

<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>

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.

Commit phase plan(s):

# Stage all PLAN.md files for this phase
git add .planning/phases/${PHASE}-*/${PHASE}-*-PLAN.md

# Also stage DISCOVERY.md if it was created during mandatory_discovery
git add .planning/phases/${PHASE}-*/DISCOVERY.md 2>/dev/null

git commit -m "$(cat <<'EOF'
docs(${PHASE}): create phase plan

Phase ${PHASE}: ${PHASE_NAME}
- [N] plan(s) in [M] wave(s)
- [X] parallel, [Y] sequential
- Ready for execution
EOF
)"

Confirm: "Committed: docs(${PHASE}): create phase plan"

``` Phase {X} planned: {N} plan(s) in {M} wave(s)

Wave Structure

Wave 1 (parallel): {plan-01}, {plan-02} Wave 2: {plan-03} ...

---

Next Up

[If 1 plan created:] {phase}-01: [Plan Name] - [objective summary]

/gsd:execute-plan .planning/phases/XX-name/{phase}-01-PLAN.md

[If 2+ plans created:] Phase {X}: [Phase Name] - {N} plans in {M} waves

/gsd:execute-phase {X}

<sub>/clear first - fresh context window</sub>

---

Also available:

• 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]

---

</step>

</process>

<task_quality>
**Good tasks:** Specific files, actions, verification
- "Add User model to Prisma schema with email, passwordHash, createdAt"
- "Create POST /api/auth/login endpoint with bcrypt validation"

**Bad tasks:** Vague, not actionable
- "Set up authentication" / "Make it secure" / "Handle edge cases"

If you can't specify Files + Action + Verify + Done, the task is too vague.

**TDD candidates get dedicated plans.** If "Create price calculator with discount rules" warrants TDD, create a TDD plan for it. See `~/.claude/get-shit-done/references/tdd.md` for TDD plan structure.
</task_quality>

<anti_patterns>
- No story points or hour estimates
- 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>

<success_criteria>
Phase planning complete when:
- [ ] STATE.md read, project history absorbed
- [ ] Mandatory discovery completed (Level 0-3)
- [ ] Prior decisions, issues, concerns synthesized
- [ ] **Must-haves derived** (truths, artifacts, key links from goal-backward analysis)
- [ ] 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: must_haves in frontmatter** (for post-execution verification)
- [ ] Each plan: user_setup declared if external services involved
- [ ] Each plan: Objective, context, tasks, verification, success criteria, output
- [ ] Each plan: 2-3 tasks (~50% context)
- [ ] Each task: Type, Files (if auto), Action, Verify, Done
- [ ] **Tasks designed to CREATE artifacts and ESTABLISH key links**
- [ ] Checkpoints properly structured
- [ ] Wave structure maximizes parallelism
- [ ] PLAN file(s) committed to git
- [ ] User knows next steps and wave structure
</success_criteria>