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 an executable phase prompt (PLAN.md). PLAN.md IS the prompt that Claude executes - not a document that gets transformed.

<planning_principles> 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) - Deferred issues (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.

Read parallelization settings from config.json:

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:

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. Deferred issues → candidates. Blockers → may need to address.

From ISSUES.md:

cat .planning/ISSUES.md 2>/dev/null

Assess each open issue - relevant to this phase? Waiting long enough? Natural to address now? Blocking something?

Answer before proceeding:

• Q1: What decisions from previous phases constrain this phase?
• Q2: Are there deferred issues 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)
• Issues being addressed (from ISSUES.md)
• 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.

Decompose phase into tasks and identify TDD candidates.

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.

**Restructure task grouping for parallel execution when enabled.**

Skip if: Parallelization disabled in config (from read_parallelization_config step).

If enabled, analyze task groupings:

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

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

3. Restructure for vertical slices (if beneficial):

   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)

   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

   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)

4. Set plan frontmatter for parallelization:

   For each plan, determine:

   • depends_on: [plan-ids] — explicit dependencies (empty if independent)
   • files_modified: [paths] — files this plan will modify

   /gsd:execute-phase uses these to detect parallelization opportunities automatically.

Output: Task groupings optimized for independence, frontmatter values determined.

After tasks, assess against quality degradation curve.

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)
• 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:

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

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.

Auto-approve and proceed to write_phase_prompt. Present breakdown inline:

Phase [X] breakdown:

### Tasks ({phase}-01-PLAN.md)
1. [Task] - [brief] [type]
2. [Task] - [brief] [type]

Autonomous: [yes/no]

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.

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, 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)
• Tasks (XML format with types)
• Verification, Success criteria, Output specification

Plan frontmatter:

---
phase: XX-name
plan: NN
type: execute
depends_on: [plan IDs this plan requires, or empty array]
files_modified: [files this plan will modify]
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.

Context section population from frontmatter analysis:

Inject automatically-assembled context package from read_project_history step:

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

# 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]
</context>

This ensures every PLAN.md gets optimal context automatically assembled via dependency graph, making execution as informed as possible.

Context section population (parallel-aware):

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

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) created
- [X] total tasks defined
- Ready for execution
EOF
)"

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

``` Phase {X} planned: {N} plan(s) created in .planning/phases/XX-name/

---

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 ready

/gsd:execute-phase {X}

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

---

Also available:

• Review/adjust tasks before executing [If 2+ plans: - /gsd:execute-plan {phase}-01-PLAN.md - run plans one at a time interactively] [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
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
- [ ] PLAN file(s) exist with XML structure
- [ ] 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
- [ ] PLAN file(s) committed to git
- [ ] User knows next steps
</success_criteria>