plan.md is Spec Kit's implementation plan for one feature: a solution-style design document - technical context, architecture with Mermaid diagrams, system modules, data model, testing strategy, key decisions - plus Spec Kit's Constitution Check gates and a Complexity Tracking table that justifies any gate a design has to break.
It is the same drawing set as solution.md - floor plan, plumbing, wiring - but before the crew starts, the inspector walks it against the building code and signs three boxes: simple enough? no needless abstraction? contracts before internals? Fail a box and you must write down why, and which cheaper option you turned down.
Where it lives and when it is written
The Spec Kit workflow writes it in its plan stage to specs/<NNN-feature>/plan.md, after spec.md is approved and against the project-wide constitution in specs/memory/. Where upstream Spec Kit spreads planning across plan.md, research.md, data-model.md, and contracts/, MySpec folds them into one comprehensive plan.md so the reviewer can check it as a whole.
The sections
# Implementation Plan: [FEATURE]
**Branch**: `001-photo-albums` | **Date**: 2026-06-13 | **Spec**: [./spec.md](./spec.md)
## Summary primary requirement + technical approach (1–3 paragraphs)
## Technical Context
**Language/Version**: TypeScript 5.4 **Primary Dependencies**: React Router 7, Hono
**Storage**: PostgreSQL via Drizzle **Testing**: vitest, playwright
**Target Platform**: Cloudflare Workers **Project Type**: web-service
**Performance Goals**: p95 < 200 ms **Constraints**: offline-capable
**Scale/Scope**: 10k users, 50 screens (unknowns: NEEDS CLARIFICATION: <question>, ≤ 3)
## Constitution Check
*GATE: re-checked after design. Violations require a row in Complexity Tracking.*
- **Simplicity Gate**: pass - one library, no speculative layers
- **Anti-Abstraction Gate**: pass - repositories only where two stores exist
- **Integration-First Gate**: pass - contract tests precede implementation
## High-Level Architecture description · Mermaid flowchart · sequenceDiagram with 3+ modules
## System Modules per module: Responsibilities, Key Components, Key Interfaces,
Dependencies, Error Handling
## Data Model Mermaid erDiagram · entities with fields, validation, state transitions
## API / Protocol Design [optional]
## Security Architecture [optional]
## Deployment & Operations [optional]
## Observability [optional]
## Testing Strategy validation steps mapped to US## and Acceptance Scenarios in spec.md
## Key Decisions | Decision | Rationale | Alternatives Considered |
## Complexity Tracking | Violation | Why Needed | Simpler Alternative Rejected Because |- Technical Context - nine fixed fields. An unknown is written as
NEEDS CLARIFICATION: <question>, never left blank; at most three across the file. - Constitution Check - required even when every gate passes; each gate lists its result and a one-sentence justification.
- Diagrams - a Mermaid
flowchartfor the architecture and anerDiagramfor the data model are mandatory; asequenceDiagramjoins them when three or more modules interact. - Testing Strategy - validation steps are mapped to the user stories and acceptance scenarios in spec.md; the Polish phase of tasks.md runs them.
- Key Decisions - one row per significant or open technical choice; this replaces standalone research documents.
- Complexity Tracking - empty unless a gate failed.
plan.md vs solution.md
| Spec Kit plan.md | MySpec solution.md | |
|---|---|---|
| Scope | One feature (a numbered directory) | The whole bundle / product |
| Constitution | Explicit gates re-evaluated per feature | Implicit: only approved technology allowed, checked at review |
| Traceability | FR-### and user stories US## | FR-/NFR- IDs; NFRs become Success Criteria rows |
| Diagrams | flowchart, erDiagram, sequence | flowchart, erDiagram, sequence, C4 Context + Container |
| Header | Branch, Date, link to spec.md | None (no metadata footers either) |
Review rules
- Every FR in spec.md maps to a module or a decision; every success criterion is addressed by the Testing Strategy.
- Constitution Check present with a result per gate; Complexity Tracking filled only for failures.
- Scaled to the feature - optional sections omitted rather than padded.
- Blank Technical Context fields, or more than three clarification markers.
- A failed gate with no Complexity Tracking row.
- Missing architecture or data-model diagram; the whole document wrapped in a code fence.
Related spec files
Project vision, core principles, and the MUST / MUST NOT constraints every later file has to obey.
User roles, FR-/NFR- requirements with EARS+ acceptance criteria; a coded AR-/BR-/CR- delta for brownfield changes.
Architecture, modules, data model, and API design with Mermaid flowchart, ER and sequence diagrams - plus C4 diagrams when your organisation enables them.
Ordered, sized implementation tasks grouped into milestones, traced back to requirement IDs.
Why a brownfield change is needed, what changes, the technical solution, and its impact on existing code.
Spec Kit's prioritised user stories and success criteria, or OpenSpec's ADDED / MODIFIED / REMOVED / RENAMED requirement deltas.
Spec Kit's technical plan: technical context, constitution gates, architecture, data model, and key decisions.
OpenSpec's optional context, goals / non-goals, decisions, and risks for a change.
Workflows that write it
The default four-file bundle: interview → constitution → requirements → solution → tasks.
GitHub Spec Kit's feature-scoped flow: interview → constitution → specify → plan → tasks.
OpenSpec's change-proposal flow: explore → proposal → delta specs → design → tasks.
Let the AI Architect write it for you
MySpec interviews you, then drafts every spec file with collect → generate → review gates. Free during Open Beta.