A spec file is a version-controlled Markdown document with a fixed section structure that answers exactly one engineering question - what must never change (constitution), what to build (requirements / spec), how it works (solution / plan / design), what changes (proposal), or in what order (tasks) - so that humans and AI coding agents work from the same source of truth.
A construction project runs on a small set of documents that different trades read at different times. The building code (constitution) never changes for the project. The client brief (requirements) says what the building must do. The architect's blueprint (solution) says how. The construction schedule (tasks) sequences the work. And when the client wants a wall moved after the foundations are poured, a change order (proposal) records why, what, and the knock-on effects. Spec-Driven Development is the same discipline for software, with an AI agent as the crew.
Which workflow writes which file
MySpec runs three methodologies. The MySpec workflow produces the four-file bundle (plus a proposal and requirements delta for brownfield changes); the Spec Kit and OpenSpec workflows reuse those jobs under their own file names and folder layouts so their CLIs keep working. Click a file for its anatomy, a specimen, and the review rules.
| File | Job | MySpec | Spec Kit | OpenSpec |
|---|---|---|---|---|
| constitution.md | Non-negotiable rules | specs/<bundle>/ | specs/memory/ (shared) | - |
| requirements.md | What to build (EARS+) | specs/<bundle>/ · delta for brownfield | - (see spec.md) | - (see delta spec.md) |
| solution.md | How it works (diagrams) | specs/<bundle>/ | - (see plan.md) | - (see design.md) |
| tasks.md | The work plan | specs/<bundle>/ (milestones) | specs/NNN-feature/ (phases, T001) | changes/<id>/ (N.M per capability) |
| proposal.md | The change order | specs/<bundle>/ (brownfield) | - | changes/<id>/ |
| spec.md | Feature spec / delta spec | - | specs/NNN-feature/ | changes/<id>/specs/<capability>/ |
| plan.md | Implementation plan | - | specs/NNN-feature/ | - |
| design.md | Design notes | - (legacy name of solution.md in old bundles) | - | changes/<id>/ (optional) |
Where the files live
Every spec path is relative, rooted at specs/ or openspec/, and at most three directory levels deep - the platform and the MCP server both enforce it. The layout below shows all three methodologies side by side in one repository; a real project usually picks one per session.
repo/
├── specs/ # MySpec + Spec Kit workflows
│ ├── memory/
│ │ └── constitution.md # Spec Kit: one per project, reused by every feature
│ ├── <bundle>/ # MySpec greenfield bundle
│ │ ├── constitution.md
│ │ ├── requirements.md
│ │ ├── solution.md # older bundles: design.md (same file type)
│ │ └── tasks.md
│ ├── <add-oauth-login>/ # MySpec brownfield change
│ │ ├── proposal.md
│ │ ├── requirements.md # Requirements Delta (AR-/BR-/CR-)
│ │ └── tasks.md # optional
│ └── 001-photo-albums/ # Spec Kit feature
│ ├── spec.md
│ ├── plan.md
│ └── tasks.md
└── openspec/ # OpenSpec workflow
├── specs/<capability>/spec.md # long-lived baselines (after apply/archive)
└── changes/<change-id>/
├── proposal.md
├── design.md # optional
├── tasks.md
└── specs/<capability>/spec.md # one delta per capability
When you pull files down with the MCP server's download_spec_file, the remote specs/ root is mirrored under a dot-prefixed .specs/ folder (conventionally gitignored), so a downloaded copy never collides with the repo's own spec folder.
How each file feeds the next
Files are written one at a time, in an order where each can cite the previous ones. That ordering is the whole point: an agent implementing task 12 can trace it to FR-004, which is bound by a constitution rule, which the solution honoured by choosing a specific module. Break the chain and you are back to prompting.
- constitution.md - sets the sandbox. Everything below must comply.
- requirements.md / spec.md - technology-neutral WHAT, every criterion testable. Must not contradict the constitution.
- solution.md / plan.md / design.md - the HOW, using only approved technology, covering every requirement.
- tasks.md - sized, ordered work; every requirement ID has at least one task; every task cites the modules the solution named.
- proposal.md - brownfield only: comes first, grounded in files the agent actually read, and defines the scope the delta requirements and tasks must stay inside.
Each file-writing stage in MySpec runs collect → generate → review: clarifying questions, a draft against the template, then an independent reviewer that rejects drift, missing sections, and unsupported claims before you see it.
All spec file types
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.
The three SDD workflows
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.