$mdflowblog
$cat spec-driven-development-markdown-specs.md

Spec-Driven Development: Where Your Markdown Specs Should Live

12 min readby MDflowview as .md
A stack of glowing emerald blueprint spec cards flowing along wireframe lines into an assembled isometric structure of interlocking blocks, on a dark terminal-grid background

Ask a coding agent to "add billing" and you will get something — plausible, fast, and subtly not what you meant. Ask it again next week and you will get something different, because the only record of what you wanted was a chat prompt that scrolled away. The bottleneck in AI-assisted engineering in 2026 is not the model's ability to write code. It is capturing intent precisely enough that the code is right the first time — and keeping that intent around.

Spec-driven development is the answer the industry converged on. You write a specification first, in plain markdown, and treat it as the source of truth your AI agent plans from, builds from, and validates against. It has moved from a niche practice to a standard professional workflow with startling speed: GitHub's Spec Kit passed 120,000 stars in its first months and integrates with 30+ coding agents; AWS shipped Kiro around the same idea; and every major tool — Cursor, Claude Code, Copilot, Antigravity — now has a flavor of it. The methodology is settled. The question almost no guide answers is the practical one: where should those markdown specs actually live?

TL;DR — Spec-driven development (SDD) makes a markdown spec the source of truth your AI agent builds from, produced in phases (spec → plan → tasks → implement) that are each a reviewable .md file. Repo-local specs belong in the repo. But your durable, cross-cutting specs — PRDs, architecture decisions, API contracts, standards — outlive any one branch and are read by many repos and agents, so they belong in a shared, versioned markdown workspace. MDflow is built to be that hub: agents read and write specs over MCP and an HTTP API, every change is version-tracked, and each spec has a raw .md twin any tool can fetch. Start free.

What is spec-driven development?

Spec-driven development is a workflow where a written specification — not an ad-hoc prompt — is the primary artifact, and your AI coding agent uses it as the contract for generating, testing, and validating code. You describe what to build and why before any code exists, in structured markdown, and the agent works from that document instead of guessing from a one-line request.

The insight is old (specs predate AI by decades) but newly urgent. A large language model is a context engine: it produces exactly as good an output as the context you hand it. A throwaway prompt is thin, ambiguous context that vanishes after one turn. A spec is thick, reviewed, durable context that any agent — or any teammate — can pick up and act on identically. As GitHub puts it, the spec becomes "the source of truth your tools and AI agents use."

In practice, the leading toolkits break the work into ordered phases, and each phase produces a markdown file that feeds the next:

PhaseWhat it capturesTypical file
SpecWhat to build and why — user stories, acceptance criteriaspec.md / requirements.md
PlanHow to build it — architecture, tech choices, data modelplan.md / design.md
TasksThe work, broken into discrete, trackable stepstasks.md
ImplementThe agent executes the tasks against the spec(code)

GitHub Spec Kit runs this as slash commands — /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement — writing spec.md, plan.md, and tasks.md into a specs/<feature>/ folder, plus a constitution.md of durable project principles under .specify/memory/. AWS Kiro uses requirements.md (in EARS "WHEN… THE SYSTEM SHALL…" notation), design.md, and tasks.md under .kiro/specs/. Different names, same shape: plain markdown, reviewed before code, kept as the record of intent.

Why spec-driven development is useful

For developers

It front-loads the thinking, which is where the errors are. The expensive mistakes in software are not typos; they are building the wrong thing, or building it on an assumption nobody wrote down. A spec forces those decisions into the open before an agent has generated 800 lines around them. AWS reported cases where features that would take ~40 hours shipped in under 8 when authored spec-first, because the agent spent its speed on the right target instead of a plausible wrong one.

Concretely, developers get:

  • Reviewable intent. A spec is a pull request for the idea — a diff your team can comment on before code exists, when changing course is cheap.
  • Repeatability. Re-run the same spec and get the same shape of result. Hand it to a different agent and the intent survives the switch.
  • An audit trail. When someone asks "why does billing work this way?" six months later, the answer is a versioned document, not a lost Slack thread.
  • Less prompt fatigue. You stop re-explaining the project every session; the spec is the explanation.

For AI agents

A spec is the structured context an agent needs to stop guessing. Coding agents already read standing-instruction files — AGENTS.md, CLAUDE.md, llms.txt — for how a project works. Spec-driven development extends that from how the repo works to what this feature must do. Given a spec.md and plan.md, an agent has the acceptance criteria to test against, the architecture to respect, and the task list to work through — so its output is checkable against a written contract rather than against your memory of what you asked for. The spec is also what lets multiple agents (or the same agent across sessions) collaborate without drift: they share one source of truth instead of diverging chat histories.

Which specs benefit most — and where each belongs

Not every spec wants the same home. The practical split is by lifespan and reach:

  1. Feature specs (spec.md, plan.md, tasks.md for one feature) — tightly coupled to a branch. Keep them in the repo, beside the code, so they version and merge with it. This is what Spec Kit and Kiro do, and it is correct.
  2. Agent instruction files (AGENTS.md, CLAUDE.md, llms.txt) — repo-scoped standing rules. Keep them in the repo too.
  3. Product requirements (PRDs) — the what and why that predates the code and outlives any single implementation. Referenced by design, QA, docs, and multiple repos.
  4. Architecture Decision Records (ADRs) and system design — cross-cutting, long-lived, read by every team that touches the system.
  5. API contracts and interface specs — the agreement between services and teams; they belong to no single repo that consumes them.
  6. Standards, conventions, glossaries — the coding standards, naming rules, and domain vocabulary that every repo and every agent should read the same way.

Categories 3–6 are where the "put it in the repo" advice breaks down. A PRD stuffed in repo-a/docs/ is invisible to repo-b's coding agent. An API contract that lives in the provider's repo is a second-class citizen in every consumer's repo. A standards doc copied into five repos is five docs that drift. These durable, cross-cutting specs need a shared home that is versioned, reviewable, and — critically in 2026 — readable and writable by the agents that consume them. That is the gap.

How MDflow fits

MDflow is a hosted, versioned markdown workspace that both humans and AI agents can read and write — which makes it the natural home for the durable specs that should not be trapped in one repo. Your feature specs stay in Git where they belong; your PRDs, ADRs, API contracts, and standards live in a shared workspace every agent and teammate can reach.

What already lines up today

Specs are plain markdown you own. MDflow stores documents as markdown-native files — the exact format Spec Kit, Kiro, and every coding agent already speak. A spec written in MDflow is the same artifact an agent reads; there is no export step and no proprietary wrapper.

Folder descriptions are retrieval context. Each folder has a description that states what its documents are for. Put your PRDs in a "Product specs" folder and your API contracts in an "Interface contracts" folder, describe each accurately, and mdflow_get_context ranks those folder descriptions first when an agent asks for "the billing spec" — returning the right document body, not your whole workspace. It is spec retrieval without standing up a vector database.

Agents read and write over MCP and an HTTP API. This is the differentiator. Over MDflow's remote MCP server, Claude and the ChatGPT app connect with an OAuth sign-in (no token to paste), while Claude Code, Cursor, and Codex authenticate with a Personal Access Token. An agent can pull the current spec as context and write a proposed update back — so the workspace is a two-way collaboration surface, not a read-only doc dump. Producers, not just readers (more on that here).

Version history on every change. A spec is only a source of truth if you can see how it changed and who changed it. Every edit in MDflow is tracked, so when an agent or a teammate revises the API contract, the diff is there — the audit trail spec-driven development promises, made real for the specs that live outside Git.

Sharing and raw .md twins for review and reach. Share a spec for review, or append .md to its share link to get plain markdown with YAML frontmatter over open CORS — so any tool, CI job, or agent that can fetch a URL can read the canonical spec. Your PRD becomes an addressable contract, not a doc locked in an app.

Together: feature specs version in the repo; the durable specs that many repos and agents depend on live in one shared, versioned, agent-readable place — and the same mdflow_get_context call works from Claude, ChatGPT, Cursor, or a script.

Where we are headed

This is direction, not a dated commitment: serving a whole collection of related specs to an agent as one cross-linked bundle (PRD + ADRs + API contract for a system, retrieved together); richer typed frontmatter so specs carry status, owner, and version as structured metadata; and tighter round-trips for agent-proposed spec changes that a human reviews before they land — closing the loop from "agent reads the spec" to "agent helps maintain the spec."

The bottom line

Spec-driven development won the argument: in 2026, the markdown spec is the source of truth your AI agents build from, and the phases that produce it — spec, plan, tasks — are each a reviewable .md file rather than a prompt that scrolls away. Feature specs belong in the repo. But the specs with the longest lives and the widest reach — PRDs, architecture decisions, API contracts, standards — are read by many repos and many agents, and they need a home that is shared, versioned, and agent-readable.

MDflow is built to be that home: markdown-native storage your agents already understand, folder descriptions that double as retrieval context, read-and-write access over MCP and an HTTP API, full version history, and raw .md twins any tool can fetch. Write the spec once, and let both your team and your agents build from the same truth.

Start free · Connect an AI agent · Read the API docs

Frequently asked questions

What is spec-driven development?

Spec-driven development (SDD) is a workflow where you write a specification first — in plain markdown — and treat it as the source of truth that your AI coding agent uses to plan, generate, test, and validate code. Instead of one-off prompts, each phase (spec, plan, tasks, implementation) produces a markdown artifact that feeds the next, so the intent is captured, reviewable, and reusable rather than lost in a chat log.

Where should markdown specs live?

Two kinds of specs exist. Repo-local specs (feature spec.md, plan.md, tasks.md, AGENTS.md) belong in the code repository beside the code they describe, so they version with it. Durable, cross-cutting specs — product requirements, architecture decisions, API contracts, coding standards, glossaries — are better in a shared, versioned markdown workspace both humans and agents can read and write, because they outlive any single feature branch and are referenced from many repos.

What files does spec-driven development use?

The common tools converge on a small set of markdown files. GitHub Spec Kit produces spec.md, plan.md, and tasks.md per feature under a specs/ folder, plus a constitution.md of project principles. AWS Kiro produces requirements.md, design.md, and tasks.md under .kiro/specs. Coding agents also read AGENTS.md, CLAUDE.md, and llms.txt for standing instructions. All of them are plain markdown.

How does MDflow help with spec-driven development?

MDflow is a hosted, versioned markdown workspace your coding agents can read and write over MCP and an HTTP API. It is the place for the durable specs that should not live in one repo — PRDs, architecture notes, API contracts, standards — with folder descriptions that act as retrieval context, full version history on every change, sharing for review, and raw .md twins so any agent can fetch a spec by URL. Agents pull the spec they need with mdflow_get_context and can write proposed spec updates back.

Is spec-driven development just writing a PRD?

No. A PRD is one input. Spec-driven development turns the whole intent-to-code path into reviewable markdown artifacts and hands them to an agent as structured context: a spec of what and why, a plan of how, and a task list to execute. The point is that the spec — not the chat prompt — is the durable source of truth, so work is repeatable, auditable, and portable across tools and teammates.

Further reading

← all posts./start-free →