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](./schemas/input.schema.json)

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

Output

Schema: [schemas/output.schema.json](./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 g