The Canonical Vocabulary of Spec-Driven Development

The Structure of Spec-Driven Development

Constitution · Specification · Plan · Tasks

Day 2 · shared vocabulary before we build

We've used "spec," "constitution," and "feature" loosely. Let's define them precisely — using the canonical SDD vocabulary the industry has converged on.

The One Sentence

In spec-driven development, intent is the source of truth. You write what and why as durable, executable artifacts; the agent generates the how (the code) from them.

GitHub's framing of the shift:

from "code is the source of truth" → "intent is the source of truth." AI is what makes a specification executable — so the spec determines what gets built.

The Layered Structure (top to bottom)

SDD artifacts form a hierarchy of decreasing scope, increasing detail:

CONSTITUTION   ── project-wide, persistent, non-negotiable principles
    │            (applies to every feature, forever)
    ▼
SPECIFICATION  ── one feature: the WHAT and WHY (no tech)
    │            (user journeys, requirements, success criteria)
    ▼
PLAN           ── one feature: the HOW (stack, architecture, constraints)
    │            (technical decisions, data models, contracts)
    ▼
TASKS          ── one feature: small, reviewable, testable units of work
    │            ("create endpoint X that validates Y")
    ▼
IMPLEMENTATION ── the generated code, one task at a time

Each layer constrains the one below it. The constitution outranks everything.

Artifact 1 — The Constitution

WHY — some principles must hold across every feature, or the project drifts as it grows.

WHAT — the project's non-negotiable principles: core values, technical constraints, team conventions, governance rules.

HOW — written once, versioned, lives at the project root (.specify/memory/constitution.md in Spec Kit). Re-read on every spec, plan, and generation.

WHEN — first, before any feature. Updated rarely — when the project's rules change.

The constitution trumps all other instructions. If anything conflicts with it, the constitution wins. Examples: "Security-first — validate all inputs." "Every feature is a standalone library." "All code documented."

Constitution — How to Recognise It

A good constitutional principle is:

• Project-wide — applies to every feature, not one
• Durable — true for the life of the project
• Non-negotiable — a hard rule, not a preference
• Testable as a gate — you can check any artifact against it

"Use Tailwind for styling" → constitution (project-wide convention). "This button is teal" → not constitution (that's a feature detail).

This is the same idea as Day 1's CLAUDE.md — ambient, always-on rules — scaled to the whole project.

Artifact 2 — The Specification

WHY — the agent can't read your mind; the what and why must be explicit before any how.

WHAT — one feature's requirements: user journeys, experiences, what success looks like. Deliberately no tech stack.

HOW — generated from a high-level prompt, then refined. A living artifact that evolves as you learn.

WHEN — per feature, first. The "Specify" phase.

Questions it answers: Who uses this? What problem does it solve? How do they interact with it? What outcomes matter? It is not about frameworks or architecture — that's the next layer.

Artifact 3 — The Plan

WHY — once the what is fixed, the agent needs the how before it can build well.

WHAT — the technical plan: stack, architecture, data models, API contracts, constraints, NFRs, compliance.

HOW — generated from the spec + your technical direction; checked against the constitution.

WHEN — per feature, after the spec. The "Plan" phase.

This is where you say "we standardise on X," "integrate with legacy Y," "hit performance target Z." "A coding agent needs to understand the rules of the game before it starts playing."

Artifact 4 — The Tasks

WHY — a whole plan is too big to generate or review in one shot; small units stay correct and checkable.

WHAT — small, reviewable, independently testable chunks of work, each tied to a spec/plan section.

HOW — the agent decomposes spec + plan into a task list; each task is implementable and verifiable in isolation.

WHEN — per feature, after the plan. The "Tasks" phase.

Not "build authentication" → but "create a user-registration endpoint that validates email format." Small tasks give the agent a way to validate its own work — like TDD for the AI.

The Workflow (GitHub Spec Kit's four phases)

Specify → Plan → Tasks → Implement

Each phase has one job and a checkpoint. You don't advance until the current artifact is validated.

• Specify — agent writes the spec; you verify it captures intent
• Plan — agent writes the technical plan; you verify constraints
• Tasks — agent breaks it into units; you verify coverage
• Implement — agent codes task by task; you review focused changes

Your role isn't just to steer — it's to verify at each gate. The AI generates the artifacts; you ensure they're right.

What Is a "Feature"?

The unit of work in SDD. Worth pinning down because it scopes everything:

• A feature = one coherent capability, specced and built as a unit
• Each feature gets its own spec, plan, and tasks (e.g. specs/001-search/)
• Multiple features can be in flight at once, each with its own artifacts
• The constitution is shared across all of them

StackLog features: entry feed · tag filtering · full-text search · weekly summary. Each is a feature with its own spec → plan → tasks. The constitution applies to all.

Three Frameworks, One Vocabulary

Spec Kit, BMAD, and AI-DLC describe the same shift with different names. Don't let the terms confuse you:

Same pipeline every time: principles → what → how → units → build → verify. We use BMAD hands-on; Spec Kit gives the cleanest names; AI-DLC gives the lifecycle framing.

The Extra Spec Kit Gates (worth knowing)

Beyond the four core phases, Spec Kit adds quality gates — useful concepts even if we don't use the tool:

• Clarify — the agent asks you questions to remove ambiguity before planning
• Analyze — cross-checks spec + plan + tasks for inconsistencies and constitution violations (read-only)
• Checklist — "unit tests for English": validates the spec's completeness for blind spots (UX, security, accessibility)

These map onto BMAD's Reviewer thinking — catching drift before code, not after.

Where SDD Shines

The canonical three sweet spots:

• Greenfield (0→1) — a little upfront spec makes the AI build what you intend, not a generic pattern
• Feature work in existing systems (N→N+1) — the spec forces clarity on how new code fits the old; most powerful here
• Legacy modernisation — capture lost business logic in a fresh spec, rebuild without inherited debt

The core benefit: separate the stable "what" from the flexible "how" — so you can iterate without expensive rewrites.

Anchor This

Constitution — project-wide, non-negotiable principles. Outranks everything. Specification — one feature's what & why. No tech. Plan — that feature's how. Stack, architecture, contracts. Tasks — small, testable units the agent builds one by one.

Principles → What → How → Units → Build → Verify. Intent is the source of truth. The code is its output.

References

• GitHub — "Spec-driven development with AI" + Spec Kit (github.com/github/spec-kit)
• Microsoft for Developers — "Spec-driven development / AI-native engineering"
• DeepLearning.AI — "Spec-Driven Development with Coding Agents"
• AI-DLC (specs.md) — lifecycle framing