An unopinionated spec-driven development workflow for AI coding assistants.
Drop this folder into any project and give your AI a structured, consistent way to build software — from idea to tested implementation. No scripts, no tooling, no branching strategy. Just a few files and a process.
- Quick Start
- What Is AI Spec-Driven Development?
- The Human Loop
- Why This Beats Plain Prompting
- Why sdd-starter and Not Something Else
- What's in This Repo
- Two Types of Specs
- The Workflow
- A Minimal Spec Example
- AI Compatibility
- Adapting the Workflow
- Handling Bugs
- Extending the Workflow
- Adding sdd-starter to an Existing Project
- The Goal of sdd-starter
- Similar Projects
- License
Step 1 — From your project's root folder, run:
curl -fsSL https://github.com/DarkoDamjanovic/sdd-starter/archive/main.tar.gz \
| tar -xz sdd-starter-main/specs \
&& mv sdd-starter-main/specs specs \
&& rmdir sdd-starter-mainStep 2 — Tell your AI to fill in the project description:
Read specs/PROJECT.md, then fill it in for this project: [describe your project, its users, and what problem it solves]
Step 3 — Tell your AI to create your first spec:
Read specs/WORKFLOW.md, then create a new spec for: [describe your feature in plain language]
That's it. Your AI knows what to do next.
AI coding assistants are powerful but directionless. Ask one to "add a login feature" and it will — but it will make dozens of invisible decisions along the way: what the API looks like, how errors are handled, what the UI does, and what gets tested. Those decisions may contradict each other, contradict your product vision, or simply not be what you had in mind.
Spec-Driven Development (SDD) solves this by separating what from how from do it.
Before any code is written, there is a spec. The spec describes what the feature does, who it is for, and what success looks like — in plain language, without implementation details. The AI reads the spec, proposes a plan, and only then implements. Every step is visible and approved before the next one begins.
The result: AI that builds what you actually want, in a way you can follow, with a record of every decision made along the way.
With this workflow, you do not write specs. You do not write code. You do not write tests.
What you do is this:
Goal → AI Creates → Steer → Review → Goal → AI Creates → Steer → Review → ...
Goal — You describe what you want, in plain language. A sentence or two. "Users should be able to log in with email and password." That is enough.
AI Creates — The AI expands your idea into a full spec, then a plan, then a task list, then working code, then tests. All of it. You never touch a template.
Steer — You read what the AI produced and redirect where needed. "The error message should be friendlier." "Skip the remember-me checkbox for now." "This API shape doesn't match what we discussed." Small corrections, not rewrites.
Review — You verify the outcome. Does it work? Does it match the spec? Approve and move on.
Then the next goal begins.
The AI does the volume. You provide the direction, taste, and judgment. That division of labor is the entire point.
| Without specs | With sdd-starter |
|---|---|
| AI invents requirements as it codes | Requirements are written and approved before coding |
| Context is lost between sessions | Every session starts by reading the same spec files |
| Hard to know what was built and why | Every decision is recorded in decisions.md |
| AI drifts across features | All features follow the same lifecycle and structure |
| Tests are an afterthought | Tests are defined from acceptance criteria, before implementation |
| Changing your mind is expensive | Change the spec first — the rest follows |
There are heavier frameworks for spec-driven development. Most of them require custom tooling, scripts that run in CI, or a specific Git branching model to function.
sdd-starter does none of that.
- No hidden scripts. Everything is plain Markdown files. Open them in any editor.
- No branching required. You do not need feature branches, PR workflows, or merge strategies. You just tell your AI which feature to work on next. It reads
INDEX.md, understands the current state, and picks up exactly where things left off. - No lock-in. The workflow is text. Copy it, modify it, delete the parts you don't need.
- Zero footprint. Everything lives inside a single
specs/folder. Don't like it? Delete the folder and your project is exactly as it was before. Nothing else is touched. - Works at any scale. The same process fits a solo weekend project, a small team, a microservice, a CLI tool, or a large product.
The only thing sdd-starter installs is a folder.
specs/
WORKFLOW.md ← The rules. Read this first.
PROJECT.md ← Your project description and personas. Fill this in.
INDEX.md ← Live status dashboard of all features and foundation items.
templates/
feature/ ← Templates for user-facing features (6 files)
foundation/ ← Templates for infrastructure and platform work (6 files)
When you start a project, you will also create:
specs/
features/
<feature-name>/ ← One folder per feature
foundation/
<item-name>/ ← One folder per infrastructure item
Every piece of work belongs to one of two categories.
A feature is something a user experiences. It is always written from the user's perspective — a user story, acceptance criteria, UI flows, and API contracts. The test plan is derived from the acceptance criteria. The name reflects what the user accomplishes, not what the code does.
Examples: user-registration, send-message, export-report
A foundation item is infrastructure or platform work that has no direct user experience but enables features to be built. It has a technical goal, a list of deliverables, and an explicit list of which features depend on it. Foundation specs must reach implemented or done status before any dependent feature can move to in-progress.
Examples: auth-infrastructure, design-system, ci-pipeline, database-schema
The rule is simple: if a user can describe what they want to do with it, it is a feature. If only an engineer would care that it exists, it is foundation.
Don't want this separation? Tell your AI: "Remove the distinction between feature and foundation specs from the workflow. Treat everything as a single spec type."
SDD has three phases. Each requires your approval before the next begins.
Spec ──▶ Implement ──▶ Test
▲ │
└──── next feature ────┘
- You describe the feature in plain language — 1–3 sentences
- AI writes
requirements.mdandplan.md— together in one step or sequentially, your call - You review and approve both (or steer)
- AI writes
test.mdfrom the acceptance criteria andtasks.md— a checklist of bite-sized implementation steps, in dependency order - You review and approve — status becomes
planned
- AI works through the task list, checking off items as it goes
- After every task, it runs available automated tests
- Non-obvious choices go into
decisions.md - Anything deferred or discovered goes into
todo.md - When every task is checked off — status becomes
implemented
- AI runs automated tests and checks off
[auto]items intest.md - You verify
[manual]items on a real build - Any bugs found revert status to
in-progress - When everything passes — status becomes
done
Don't want this three-phase structure? Tell your AI: "Simplify the workflow to a single phase: write a spec, then implement it. Remove the separate planning and testing phases."
Every feature and infrastructure item lives in INDEX.md with its current status. Your AI keeps it in sync. When you start a new session, it reads this file and knows exactly what is in progress, what is blocked, and what is next. You never need to explain the project state — it is already written down.
Don't like how INDEX.md works? Tell your AI: "Change INDEX.md to [describe what you want instead]."
---
status: draft
created: 2025-01-15
updated: 2025-01-15
---
# User Login
## User Story
> As a registered user, I want to sign in with my email and password,
> so that I can access my account.
## Acceptance Criteria
- **Given** a registered user, **When** they submit valid credentials, **Then** they are redirected to the dashboard
- **Given** a login attempt, **When** the credentials are invalid, **Then** a clear error message is shown
- **Given** a successful login, **When** the app is restarted, **Then** the session is still activeThat is enough for AI to write a full technical plan, a test suite, and a complete task checklist. You wrote three acceptance criteria. AI does the rest.
Acceptance criteria use BDD format — Given / When / Then. When AI writes test.md, it starts with a coverage table that maps each criterion to one or more test cases. Every criterion must be covered before the feature can move to done.
sdd-starter works with any AI coding assistant that reads project files.
Any capable model works. That said, this workflow gets the most out of models that reason well across long documents and maintain coherence across many files simultaneously. Claude (by Anthropic) is currently the strongest choice for this — it handles large specs, long task lists, and multi-file reasoning better than any other model available today.
Configuring your AI. To make your AI automatically follow the workflow whenever it touches spec files, ask it:
"Make sure you always read
specs/WORKFLOW.mdbefore working on any file inside thespecs/folder. Configure this so it happens automatically in every session."
Your AI knows where its own configuration lives — CLAUDE.md, .github/copilot-instructions.md, .cursorrules, or whatever your tool uses — and will set it up for you.
Nothing here is fixed.
WORKFLOW.md is a text file. If something does not fit your project, change it. Running a CLI tool with no UI? Remove the UI sections from the spec template. Solo project where approval gates slow you down? Tell the AI to skip them. Need an extra review step for security-sensitive features? Add it.
The fastest way to adapt it is to ask your AI directly:
"This is a backend-only service. Update the workflow to remove all UI-related sections."
"I want a lighter process — skip the separate plan approval and go straight to tasks."
"Add a
security.mdfile to every feature spec."
The AI updates WORKFLOW.md and the templates to reflect the change. The new process is live in the next session.
The workflow is itself a spec. Treat it like one.
A bug is a gap between a spec and reality. Before fixing anything, identify which side of that gap the bug lives on.
The spec describes the correct behavior, and the code is wrong. The spec does not need to change. Tell your AI to find the acceptance criterion that the bug violates and fix the code until that criterion passes.
Read specs/<feature>/requirements.md and specs/<feature>/test.md.
The following behavior is broken: [describe the bug].
Identify which acceptance criterion this violates and fix it.
Add a regression test to test.md.
The spec does not cover this behavior at all. The spec is incomplete. Update the spec first — add the missing acceptance criterion — then fix the code. The bug becomes a spec gap, and closing it is just normal SDD work.
Read specs/<feature>/requirements.md.
This case is not covered: [describe the bug].
Add it as an acceptance criterion, then fix the code to satisfy it.
In both cases, root cause notes go in decisions.md and any follow-up work goes in todo.md. No separate bug-tracking process is needed — the spec files are the record.
Found a bug in the SDD workflow itself? The workflow is a spec — treat it the same way. Tell your AI what is wrong or confusing, and it will update WORKFLOW.md and the templates to fix it.
Something in WORKFLOW.md is unclear/wrong: [describe the problem].
Fix it so that [describe the desired behavior].
The updated workflow is live in the next session.
PRs are welcome too — if you've improved your local workflow and think others would benefit, open a pull request.
Want to add features to the workflow itself? The fastest path is to ask your AI. The workflow is plain Markdown — your AI can read it, understand the structure, and add whatever you need.
A few examples:
Trigger spec creation with a slash command. Tell your AI: "Create a slash command /new-feature that reads WORKFLOW.md and walks me through creating a new feature spec." Now starting a spec is a single keystroke instead of a copy-paste from templates.
Auto-update INDEX.md with a hook. Tell your AI: "Set up a hook that updates INDEX.md whenever a spec status changes."
Add a risk assessment to specs. Tell your AI: "Add a risk section to the feature spec template that covers security implications, data privacy, and rollback strategy."
The pattern is always the same: describe what you want, and let the AI figure out where it fits. The workflow is a text file — anything you can describe, your AI can add.
There is no single right way. Several strategies work depending on the size of the project and how much existing code you want to cover. Choose the one that fits.
Strategy 1 — Forward only (recommended for large projects)
Don't touch existing code. From today, all new features and modifications go through SDD. Existing code is treated as legacy — it works, leave it alone.
Tell your AI:
Read specs/PROJECT.md and fill it in based on the existing codebase. Then create a specs/INDEX.md entry for each major existing area, marked as `done`. From now on, all new work goes through WORKFLOW.md.
Strategy 2 — Touch it, spec it
No upfront backfill. Instead, the rule is: before you modify any part of the codebase, write a spec for it first. Specs accumulate naturally as work happens.
Tell your AI:
Before changing anything in [area], write a spec for it first using WORKFLOW.md. Treat the existing behaviour as the baseline — spec what is there, then spec what we are changing.
Strategy 3 — Selective backfill
Identify the parts of the codebase that are most critical, most frequently changed, or hardest to understand. Backfill specs for those areas only — reverse-specced from the existing code.
Tell your AI:
Read the code in [folder or area] and write a requirements.md for it as if it were already implemented. Describe what it does, who uses it, and what the acceptance criteria would be. Mark it as `done`.
Strategy 4 — Full backfill
Spec everything. Only practical for small-to-medium projects. Gives you a complete picture and a clean starting point.
Tell your AI:
Read the entire codebase and create a spec for every major feature and infrastructure item. Use WORKFLOW.md templates. Mark all existing items as `done` and build out INDEX.md from scratch.
No strategy is wrong. The goal is that future work has a spec. How much of the past you document is up to you.
This is meant to be the last SDD framework you use. Not because it is the best one — but because it should be the last one you need.
Once you have experienced spec-driven development in action — once you have seen an AI read a spec, propose a plan, and build exactly what was described — you understand the pattern. And once you understand the pattern, you do not need someone else's framework anymore. You can create your own.
The ideal outcome is this: after using sdd-starter on one or two projects, you open a new project and tell your AI:
"Let's create an SDD framework for this project."
And it does. Tailored to your stack, your team, your preferences. No starter repo needed. No templates to copy. Just you, your AI, and a process you already understand.
sdd-starter exists to teach the pattern, not to own it.
Two other spec-driven development projects worth knowing:
spec-kit — A CLI toolkit that implements a six-step SDD workflow: constitution → specify → plan → tasks → implement. Like sdd-starter, specs are written and approved before any code is written. Unlike sdd-starter, it requires installing a CLI tool (specify-cli) and invokes steps via slash commands inside an AI session. Works with 20+ AI agents.
Kiro — An agentic IDE (macOS/Windows/Linux) by Amazon where spec-driven development is a first-class feature. A prompt is turned into a structured spec and implementation plan before the agent writes any code. Kiro also adds hooks, steering files, and MCP integration. Heavier than sdd-starter — a full IDE rather than a folder of Markdown files.
sdd-starter adds explicit workflow phases — Spec, Implement, and Test — each requiring your approval before the next begins. Features move through a tracked lifecycle from draft to planned to implemented to done, visible at a glance in INDEX.md. Neither spec-kit nor Kiro expose this kind of phase-gated progression as a first-class concept.
This is free and unencumbered software released into the public domain. Do whatever you want with it — use it, copy it, modify it, sell it, don't credit it. No conditions.