planning

Planning Skill

Plan Location

Plans are stored alongside their specs:

changes/YYYY/MM/DD/<id>-<name>/<NN-change-name>/PLAN.md

This keeps all change documentation (spec + plan) together in one location.

Workflow Integration

Plans are created as part of the /sdd workflow:

1. User creates or imports a change via /sdd I want to create a new feature
2. Spec solicitation creates SPEC.md
3. User reviews and approves spec via /sdd I want to approve the spec
4. This skill creates PLAN.md immediately after spec approval
5. User reviews and approves plan via /sdd I want to approve the plan
6. Implementation can begin via /sdd I want to start implementing

Plan creation requires an approved SPEC.md as input — it does not run independently.

Input

Schema: schemas/input.schema.json

Accepts change ID, path to approved SPEC.md, and workflow ID.

Output

Schema: schemas/output.schema.json

Returns path to created PLAN.md and review status.

SPEC.md vs PLAN.md Separation

File	Purpose	Contains	Does NOT Contain
SPEC.md	What to build and how	Requirements, design, API contracts, implementation details, test cases	Execution order, agent assignments
PLAN.md	Execution coordination	Phases, agent assignments, dependencies, expected files, progress tracking	Implementation details, code patterns, specific coding tasks

Key principle: Because plans focus on execution coordination (not implementation details), the SPEC.md must be comprehensive enough that an implementer can complete each phase by reading only the spec. Plans reference specs; they don't duplicate them.

Plan Content Guidelines

Acceptable in plans:

• Standards references per phase (which standards skills apply to each agent's work)
• Methodology-level task descriptions (e.g., "Implement Model layer" not "Implement domain logic")
• Brief code snippets as constraints or guidelines (e.g., "interface must include X field")
• High-level examples showing intent
• File paths and component names
• Phase sequencing and dependencies
• Extensive test lists (tests define WHAT, not HOW)

Not appropriate in plans:

• Full implementations or complete code blocks
• Step-by-step coding instructions
• Line-by-line change lists
• Algorithm implementations (belong in spec)

SPEC.md: Thorough Technical Specification

SPEC.md is a complete technical specification. It must be:

• Self-sufficient: Anyone reading the spec understands the change fully without other docs
• Thorough: Covers all aspects (functional, non-functional, security, errors, observability)
• Technical: Includes schemas, algorithms, data models, API contracts
• Testable: Every requirement has clear acceptance criteria

Key sections:

• Background and current state (context)
• Functional and non-functional requirements
• Technical design (architecture, data model, algorithms)
• API contracts with request/response schemas
• Security considerations
• Error handling strategy
• Observability (logging, metrics, traces)
• Testing strategy with specific test cases
• Domain updates (glossary, definitions)
• Dependencies and migration plan

Domain Documentation in Specs

Domain documentation is specified in SPEC.md during planning, not discovered during implementation.

The SPEC.md file includes a ## Domain Updates section that explicitly lists:

• Glossary Terms - exact terms to add/modify in specs/domain/glossary.md
• Definition Specs - domain definition files to create/update in specs/domain/definitions/
• Architecture Docs - updates needed in specs/architecture/

Testing Strategy in Specs

The SPEC.md file includes a ## Testing Strategy section that defines:

• Unit Tests - what behaviors need unit tests (implemented via TDD during execution)
• Integration Tests - what integrations need testing
• E2E Tests - what user flows need end-to-end tests

This approach ensures:

1. All requirements (domain, tests, verification) are fully understood before implementation
2. Implementation simply executes the specified updates (no discovery)
3. Clear traceability from spec to implementation

Dynamic Phase Generation

Plans are generated dynamically based on the SPEC.md's Components section.

Component Source of Truth

SPEC.md is the source of truth for required components.

The planning skill:

1. Reads the ## Components section from SPEC.md
2. May read sdd/sdd-settings.yaml for existing component details (delegate to the project-settings skill for the settings schema — it returns typed component objects with name, type, and type-specific settings like server_type, databases, provides_contracts)
3. Does NOT ask about tech stack or which components to use

If SPEC.md says a component is needed but it's not in sdd-settings.yaml yet, that's expected - the component will be created during implementation.

DO NOT ask tech stack questions during planning. Component discovery already determined what's needed.

Generation Algorithm

1. Read required components from SPEC.md ## Components section
2. Reference existing components from sdd/sdd-settings.yaml for details
3. Check for new components: If SPEC.md ## Components lists new components not yet in sdd-settings.yaml, prepend a "Phase 1: Component Scaffolding" phase and shift subsequent phase numbers. If all components already exist, omit the scaffolding phase. This applies to all change types (feature, refactor).
4. Order by dependency graph: Invoke techpacks.dependencyOrder for the active tech pack namespace to get the topological order of component types. Use this order for phase sequencing.
5. Assign agents and standards: Invoke techpacks.readManifest and read components.<type>.agent for each affected component type. For standards, invoke techpacks.routeSkills(phase: plan-generation, component_type: <type>) — the skills router returns the relevant standards for each component.
6. Add final phases: Read lifecycle.testing.agent and lifecycle.verification.agent from the manifest for the testing and review phases.

Testing Strategy

Test Type	When	Agent
Unit tests	During implementation (TDD)	Component's assigned agent (from manifest)
Integration tests	After all implementation phases	lifecycle.testing.agent from manifest
E2E tests	After all implementation phases	lifecycle.testing.agent from manifest

Phase Structure

• Each phase is independently reviewable
• Domain updates execute first (from SPEC.md)
• Component phases follow dependency order
• Phases build on each other sequentially

Implementation State Tracking

Plans include sections for tracking implementation progress:

Expected Files

• Files to Create - new files this change will add
• Files to Modify - existing files this change will update

Implementation State

• Current Phase - which phase is in progress
• Status - pending, in_progress, blocked, complete
• Completed Phases - checklist of completed phases
• Actual Files Changed - updated during implementation with real files
• Blockers - any issues blocking progress
• Resource Usage - tokens (input/output), turns, and duration per phase

This enables:

1. Session resumption from any point
2. Audit trail of what actually changed
3. Progress visibility for stakeholders
4. Resource usage analysis (cost and time estimation for similar changes)

PR Size Guidelines

Each phase should result in a reviewable PR:

Metric	Target	Maximum
Lines changed	< 400	800
Files changed	< 15	30
Acceptance criteria	< 5	8

If a phase exceeds limits:

1. Split into sub-phases (e.g., Phase 2a, Phase 2b)
2. Each sub-phase gets its own PR
3. Document splits in plan

Epic Plans

For type: epic changes, delegate to the change-creation skill with type: epic. It handles the full epic lifecycle: directory structure, parent and child SPEC.md/PLAN.md creation, workflow tracking, and implementation sequencing.

---

Template: Implementation Plan (Feature)

---
title: Implementation Plan: [Change Name]
change: [change-name]
type: feature
spec: ./SPEC.md
issue: [PROJ-XXX]
created: YYYY-MM-DD
sdd_version: [X.Y.Z]
---

# Implementation Plan: [Change Name]

## Overview

**Spec:** [link to spec]
**Issue:** [link to issue]

## Affected Components

<!-- Read from SPEC.md ## Components section (source of truth) -->
<!-- May reference sdd-settings.yaml for existing component details -->
- <component-type-a>
- <component-type-b>
- <component-type-c>

## Phases

<!-- Phases are generated dynamically based on affected components -->
<!-- Domain updates are executed from SPEC.md before code phases -->

<!-- INCLUDE Phase 1 ONLY if SPEC.md lists new components not in sdd-settings.yaml. OMIT entirely if all components already exist. -->
### Phase 1: Component Scaffolding (if new components)
**Agent:** Read the agent assigned to the scaffolding-related component type from the manifest via `techpacks.readManifest`. Use the `components.<type>.agent` field.
**Standards:** Invoke `techpacks.routeSkills(phase: project-scaffolding)` to load scaffolding standards.

**Outcome:** New component directories and boilerplate created, `sdd-settings.yaml` updated

**Deliverables:**
- Component directories scaffolded per SPEC.md Components section
- sdd-settings.yaml updated with new component entries

### Phase N: [Component Implementation]

<!-- Repeat for each affected component in dependency order. Read agent and standards from manifest. -->

**Agent:** Read `components.<type>.agent` from the tech pack manifest via `techpacks.readManifest`.
**Component:** `<component-type>`
**Standards:** Invoke `techpacks.routeSkills(phase: implementation, component_type: <type>)` to load relevant standards.

**Outcome:** Component functionality complete per SPEC.md

**Deliverables:**
- Implementation matching spec requirements
- Unit tests passing (if applicable)

### Phase N+1: Integration & E2E Testing
**Agent:** Read `lifecycle.testing.agent` from the manifest.
**Standards:** Invoke `techpacks.routeSkills(phase: testing)`.

**Outcome:** All integration and E2E tests passing

**Deliverables:**
- Test suites passing

### Phase N+2: Review
**Agent:** Read `lifecycle.verification.agent` from the manifest.
**Standards:** Invoke `techpacks.routeSkills(phase: verification)`.

**Outcome:** Implementation verified against SPEC.md and standards

## Dependencies

- [External dependencies or blockers]

## Tests

<!-- Extensive test list - tests define WHAT, not HOW -->

### Unit Tests
- [ ] `test_[behavior_description]`

### Integration Tests
- [ ] `test_[integration_description]`

### E2E Tests
- [ ] `test_[user_flow_description]`

## Risks

| Risk | Mitigation |
|------|------------|
| [Risk] | [How to mitigate] |

---

Template: Implementation Plan (Bugfix)

---
title: Implementation Plan: [Change Name]
change: [change-name]
type: bugfix
spec: ./SPEC.md
issue: [BUG-XXX]
created: YYYY-MM-DD
sdd_version: [X.Y.Z]
---

# Implementation Plan: [Change Name]

## Overview

**Spec:** [link to spec]
**Issue:** [link to issue]

## Affected Components

<!-- List components where the bug manifests -->
- [component]

## Phases

### Phase 1: Investigation
**Agent:** Read `components.<type>.agent` from the tech pack manifest via `techpacks.readManifest` (based on affected component type).
**Standards:** Invoke `techpacks.routeSkills(phase: implementation, component_type: <type>)`.

**Outcome:** Root cause identified and documented in SPEC.md

**Deliverables:**
- Documented root cause
- Clear reproduction steps

### Phase 2: Implementation
**Agent:** Read `components.<type>.agent` from the tech pack manifest via `techpacks.readManifest`.
**Standards:** Invoke `techpacks.routeSkills(phase: implementation, component_type: <type>)`.

**Outcome:** Bug fixed with regression test per SPEC.md

**Deliverables:**
- Working fix
- Regression test passing

### Phase 3: Integration Testing
**Agent:** Read `lifecycle.testing.agent` from the manifest.
**Standards:** Invoke `techpacks.routeSkills(phase: testing)`.

**Outcome:** All tests passing, no regressions

**Deliverables:**
- All tests passing

### Phase 4: Review
**Agent:** Read `lifecycle.verification.agent` from the manifest.
**Standards:** Invoke `techpacks.routeSkills(phase: verification)`.

**Outcome:** Fix verified against SPEC.md acceptance criteria and standards

## Tests

<!-- Extensive test list - tests define WHAT, not HOW -->

### Regression Tests
- [ ] `test_[bug_does_not_recur]`

### Unit Tests
- [ ] `test_[fixed_behavior]`

## Notes

- Prioritize minimal, focused changes
- Update this plan as investigation reveals more details

---

Template: Implementation Plan (Refactor)

---
title: Implementation Plan: [Change Name]
change: [change-name]
type: refactor
spec: ./SPEC.md
issue: [TECH-XXX]
created: YYYY-MM-DD
sdd_version: [X.Y.Z]
---

# Implementation Plan: [Change Name]

## Overview

**Spec:** [link to spec]
**Issue:** [link to issue]

## Affected Components

<!-- List components being refactored -->
- [component]

## Phases

### Phase 1: Preparation
**Agent:** Read `components.<type>.agent` from the tech pack manifest via `techpacks.readManifest` (based on affected component type).
**Standards:** Invoke `techpacks.routeSkills(phase: implementation, component_type: <type>)`.

**Outcome:** Test coverage verified, affected areas documented per SPEC.md

**Deliverables:**
- Test coverage report
- Affected area documentation

### Phase 2: Implementation
**Agent:** Read `components.<type>.agent` from the tech pack manifest via `techpacks.readManifest`.
**Standards:** Invoke `techpacks.routeSkills(phase: implementation, component_type: <type>)`.

**Outcome:** Refactoring complete per SPEC.md following component standards, all tests passing

**Deliverables:**
- Refactored code following component standards
- All existing tests passing

### Phase 3: Integration Testing
**Agent:** Read `lifecycle.testing.agent` from the manifest.
**Standards:** Invoke `techpacks.routeSkills(phase: testing)`.

**Outcome:** No behavior changes, all tests passing

**Deliverables:**
- All tests passing
- No behavior changes verified

### Phase 4: Review
**Agent:** Read `lifecycle.verification.agent` from the manifest.
**Standards:** Invoke `techpacks.routeSkills(phase: verification)`.

**Outcome:** Refactoring goals verified, no regressions, standards compliance confirmed

## Tests

<!-- Extensive test list - tests define WHAT, not HOW -->
<!-- For refactors, existing tests should already cover behavior -->

### Existing Tests (must pass)
- [ ] All unit tests pass before refactor
- [ ] All unit tests pass after refactor

### Performance Tests (if applicable)
- [ ] `test_[performance_not_degraded]`

## Notes

- All tests must pass before and after refactoring
- No functional changes should be introduced
- Update this plan as implementation progresses