Spec-Driven Development in Markdown: What spec.md, plan.md, and tasks.md Actually Do
Quick answer
Spec-driven development splits a feature into three Markdown files instead of one long prompt. spec.md describes what you're building and why. plan.md describes how you'll build it. tasks.md breaks that plan into an ordered checklist an AI coding agent can work through step by step. Each file feeds the next: plan.md gets generated by reading spec.md, and tasks.md by reading both. GitHub's Spec Kit popularized this exact three-file convention, but the pattern itself works with any agent that can read project files. Below: what actually writes to each file, then when the setup earns its keep and when it's more process than a small change deserves.
How it actually works
spec.md — the what and why
spec.md is the feature specification — user-facing behavior and goals, captured before anyone decides how to build it. In Spec Kit's command set, /speckit.specify creates it and /speckit.clarify refines it, appending clarification answers back into the same file. Tech stack and architecture don't belong here. The documentation frames it plainly as the "what" before the "how."
plan.md — the how
plan.md is where the technology choices live: framework, architecture decisions, technical constraints. /speckit.plan reads spec.md and writes plan.md — it never edits the spec back. That one-way read is the real value of splitting these into two files. You can throw out an implementation approach in plan.md and regenerate it without touching a single requirement in spec.md.
tasks.md — the ordered checklist
/speckit.tasks reads both spec.md and plan.md and writes tasks.md: an actionable, dependency-ordered list organized into phases — Setup, Foundational, one phase per user story, then Polish — with markers for which tasks can run in parallel. /speckit.implement then reads tasks.md (plus any checklists) and executes in that order. It's allowed to read checklist checkbox state as a gate, but not to change the checkmarks itself. That stays under human control, on purpose.
The read/write chain, end to end
Laid out in sequence, the file dependencies look like this:
/speckit.specify→ writes spec.md/speckit.clarify→ reads and updates spec.md/speckit.plan→ reads spec.md, writes plan.md/speckit.tasks→ reads spec.md + plan.md, writes tasks.md/speckit.analyze→ reads all three, read-only — reports conflicts, gaps, and ambiguities without editing anything/speckit.implement→ reads tasks.md, writes source code/speckit.converge→ reads all three plus the codebase, appends findings to tasks.md
Spec Kit's own quickstart offers a shorter path — specify, plan, tasks, implement, converge — for small features, and the full nine-step path above for production work, adding a one-time /speckit.constitution plus /speckit.clarify, /speckit.checklist, and /speckit.analyze as quality gates.
None of this is meant to get thrown away once the code ships. Spec Kit's documentation is explicit that it doesn't prescribe how teams maintain spec.md, plan.md, and tasks.md after requirements change — they're designed to stay in the repo as living documents under version control, not one-time scaffolding. That's the same instinct behind keeping AI context files in plain text and Markdown: a file an agent can re-read later is worth more than a chat history that scrolls out of view.
When to use it (and when to skip it)
This is a good fit for multi-step features, production work, or anything where a coding agent would otherwise lose the thread across a long session — forgetting a decision made three prompts ago, or re-deriving requirements you already settled. Spec Kit's own two-path quickstart makes the trade-off explicit: five steps for something small, nine for something that needs quality gates before it ships.
It's overkill for a one-off script, a small bug fix, or exploratory prototyping where the requirements are still shifting under you. Writing a spec, a plan, and a task list for a five-line fix is more process than the change deserves.
What actually makes a spec file useful to an agent, regardless of whether you use Spec Kit's exact commands: concrete commands and file paths beat vague descriptions — "React 18 with TypeScript," not "a React project." Define explicit boundaries for what the agent can always do, should ask about first, and should never do. And don't cram it all into one giant file. As the number of directives in a spec grows, an agent's compliance with all of them tends to drop — so large specs read better split into sections and fed in as needed, rather than dumped in one shot. That holds whether you're running Spec Kit's full nine-step process or working alongside AI coding assistants with a lighter, hand-rolled version of the same three-file idea.
Frequently Asked Questions
What's the difference between spec.md and plan.md?
spec.md captures the what and why — user-facing behavior and goals, written before any implementation decision. plan.md captures the how — tech stack, architecture, and technical constraints — and gets generated by reading spec.md, not the other way around. Keeping them separate means you can change your mind about the implementation in plan.md without touching the requirements in spec.md.
Does tasks.md replace a project management tool?
No. tasks.md is a dependency-ordered checklist scoped to a single feature, generated from spec.md and plan.md and organized into phases like Setup, Foundational, per-user-story work, and Polish. It's meant to be read by a coding agent executing the work in order, not to track a team's whole backlog.
Do I need to use GitHub's Spec Kit specifically to work this way?
No. Spec Kit is one implementation of spec-driven development with its own command names and file conventions. But the underlying pattern — a spec file, a plan file, a task file, all in Markdown, all under version control — works with any AI coding agent that can read project files, including a plain three-file convention you set up by hand.
Are spec.md, plan.md, and tasks.md meant to be deleted after the feature ships?
Not by default. Spec Kit treats them as living documents that stay in the repo and get updated as requirements change, rather than throwaway scaffolding. Some teams do archive or prune them per feature — the tooling doesn't force either choice.
How Carets fits in
Whether or not you adopt Spec Kit's exact command set, the underlying pattern is three plain Markdown files that need to stay readable, editable, and easy to jump between — spec.md, plan.md, tasks.md. That's exactly the kind of file Carets is built to hold: Markdown and code in one native editor for iPhone, iPad, and Mac, with syntax highlighting so a fenced code block or a task list actually looks like one while you're reading it.
Keep spec.md, plan.md, and tasks.md as separate files inside a Carets project, tagged by feature, so you can pull up "what am I building and why" without wading through the implementation plan to find it. Your files stay plain text, so none of this locks into a proprietary format — a spec you write today opens the same way in a year, in whatever editor or agent you're using by then.
If you want the same read-it-anywhere approach for your project's other Markdown files, a Markdown style guide for technical docs is a good next stop. Carets is free to try on the App Store for iPhone, iPad, and Mac.