Create Implementation Plan

You are converting a feature specification into a detailed technical implementation plan. The plan bridges the gap between WHAT (spec) and HOW (implementation).

Upstream source: github/spec-kit

Prerequisites

• A feature specification must exist in specs/[###-feature-name]/spec.md
• .speckit/constitution.md should exist with filled-in principles

If no spec exists, instruct the user to run /spec-kit:specify first.

Workflow

Step 1: Identify the Feature

• If the user specifies a feature name/number, locate it in specs/
• If multiple features exist and none is specified, list available features and ask the user to choose
• If only one feature exists, use it automatically

Step 2: Load Context

Read the following files:

• specs/[###-feature]/spec.md (required)
• .speckit/constitution.md (for compliance check)
• Any existing specs/[###-feature]/research.md (if exists, incorporate findings)

Step 3: Constitution Compliance Check (Gate)

Before proceeding, verify planned approach will comply with every constitution principle. For each principle:

Constitution Compliance:
  [PASS] Principle I: [Name] — [How the plan complies]
  [PASS] Principle II: [Name] — [How the plan complies]
  ...

If any principle would be violated, STOP and report the conflict. Do not proceed until resolved.

Step 4: Resolve Clarifications

Check the spec for any [NEEDS CLARIFICATION] markers. For each one:

1. Present the question to the user
2. Collect the answer
3. Note the resolution (user should update the spec separately via /spec-kit:clarify)

Step 5: Phase 0 — Research

Analyze the specification and the current codebase to determine technical context:

• Language/version, frameworks, existing patterns
• Available dependencies and testing infrastructure
• Project structure conventions

Extract unknowns from the spec's Technical Context:

• For each NEEDS CLARIFICATION → research task
• For each technology choice → best practices investigation

Create specs/[###-feature]/research.md:

# Technical Research: [FEATURE]

**Date**: [TODAY]
**Spec**: ../spec.md

## Key Decisions

| Decision | Choice | Rationale | Alternatives Considered |
|----------|--------|-----------|------------------------|
| [Topic]  | [What was chosen] | [Why chosen] | [What else was evaluated] |

## Open Questions
[Any remaining technical uncertainties]

## References
[Relevant documentation or examples]

Step 6: Phase 1 — Design and Contracts

Prerequisites: research.md complete

1. Data Model (specs/[###-feature]/data-model.md):

# Data Model: [FEATURE]

## Entities

### [Entity Name]
- [attribute]: [type] — [description, validation rules]
- [attribute]: [type] — [description]

## Relationships
- [Entity A] → [Entity B]: [relationship type and description]

## State Transitions (if applicable)
- [Entity]: [state-from] → [state-to]: [trigger condition]

## Constraints
- [Business rule or data constraint]

2. Interface Contracts (create specs/[###-feature]/contracts/ directory):

   • Create contract files for each interface the project exposes to users or other systems
   • Examples: REST endpoints, GraphQL schemas, CLI commands, function signatures for libraries
   • Each contract defines: inputs, outputs, error cases, and examples
   • Skip if project is purely internal

3. Create implementation plan specs/[###-feature]/plan.md:

# Implementation Plan: [FEATURE]

**Branch**: `[###-feature-name]` | **Date**: [TODAY] | **Spec**: spec.md

## Summary
[Primary requirement + chosen technical approach in 1-2 sentences]

## Technical Context

**Language/Version**: [detected from codebase or research]
**Primary Dependencies**: [key libraries/frameworks]
**Storage**: [database/file system/API, or N/A]
**Testing**: [framework and strategy]
**Target Platform**: [web/mobile/CLI/library]
**Project Type**: [library/cli/web-service/mobile-app/compiler/desktop-app]
**Performance Goals**: [from spec success criteria]
**Constraints**: [from spec and constitution]
**Scale/Scope**: [e.g., 10k users, 1M LOC]

## Constitution Check

*Passed before Phase 0. Re-checked after design.*

[For each principle — one line confirming compliance or noting how the plan addresses it]

## Project Structure

### Documentation (this feature)
```text
specs/[###-feature]/
├── spec.md
├── plan.md           (this file)
├── research.md       (Phase 0 output)
├── data-model.md     (Phase 1 output)
├── contracts/        (Phase 1 output)
└── tasks.md          (generated by /spec-kit:tasks)

Source Code (repository root)

[Proposed file/directory structure — adjust based on project type]
src/
├── models/
├── services/
└── [...]
tests/
├── contract/
├── integration/
└── unit/

Structure Decision: [Document the selected structure and why]

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because
[e.g., 4th project]	[current need]	[why 3 projects insufficient]

### Step 7: Re-evaluate Constitution Check

After completing the design, re-check compliance with each constitution principle. Update the Constitution Check section in plan.md with the post-design assessment.

### Step 8: Output Summary

Implementation Plan Created: specs/[###-feature-name]/

Files generated: plan.md — Implementation plan research.md — Technical research and decisions data-model.md — Data model definition contracts/ — Interface contracts (if applicable)

Constitution: All principles — COMPLIANT (or list any issues) Phases: [count] implementation phases

Next step: Run /spec-kit:tasks to generate the implementation task list.

## Important Rules

- All file paths must be absolute or relative to the project root.
- The plan must address EVERY functional requirement (FR-###) from the spec.
- The plan must map to EVERY success criterion (SC-###) from the spec.
- Constitution compliance is a hard gate — do not proceed if any principle is violated.
- Favor simplicity. Document any complexity in the Complexity Tracking table with justification.
- Research decisions must include alternatives considered and why they were rejected.
- The plan is a technical document — it can and should mention specific technologies, patterns, and approaches (unlike the spec).