PHASE 1
The Idea
Capture intent in a single Markdown file — the what, the who, the constraints, and the definition of done.
→ idea.md
Spec-Driven Development · A Vedoma project
Your idea
is the
source code.
A ready-to-use scaffold for building with GenAI the intentional way. Start from a Markdown idea, generate a specification, and let the spec — not a chat window — drive the build.
Get the scaffold
$ gh repo clone Vedoma/sdd-starter
Read the quickstart → no CLI · no install · just files
3 phases
Idea → Spec → Build
1 file
to start: idea.md
0 setup
clone, copy, go
MIT
open source
01 / What it is
A scaffold, not
a framework.
sdd-starter is a repository of pre-wired folders, templates, and workflow files that encode Spec-Driven Development. There is nothing to install and no runtime — you clone it, copy the files into your project, and you are ready to work.
GenAI made it trivial to produce code. It did nothing to make that code correct. The missing layer isn't a better prompt — it's a specification. sdd-starter gives your AI agent the structure to turn intent into a spec, and the spec into software.
"An idea, made precise, is already half-built."
02 / The pipeline
Idea → SDD → Scaffold.
STEP 01
idea.md
You write the intent
One Markdown file. Plain language: what you're building, for whom, and the constraints that matter.
STEP 02
spec/
The agent specifies
Your GenAI agent reads idea.md through the scaffold's workflows and produces a structured, reviewable specification.
STEP 03
build
The spec drives code
Implementation follows the spec phase by phase. Every change traces back to a decision you already made.
03 / Why not vibe coding
Prompt & pray
Vibe coding
- ✕Intent lives in a chat log that scrolls away
- ✕Every session re-explains the same context
- ✕No shared artifact to review or hand off
- ✕Correctness is a vibe, not a check
Spec & build
sdd-starter
- ✓Intent is a committed file: idea.md
- ✓The spec is context every agent can load
- ✓A reviewable artifact you can diff and share
- ✓Every build traces back to the spec
04 / How to use it
Four moves to your first spec.
01
Clone the scaffold
Pull the repository down anywhere. It's just files — no dependencies to resolve.
$ gh repo clone Vedoma/sdd-starter
02
Copy files into your project
Drop the scaffold into a fresh or existing repo. That's the entire install.
$ cp -r sdd-starter/. your-project/
$ cd your-project
$ cd your-project
03
Write your idea
Open idea.md and describe what you want in plain language. This
file is the source of truth.
# idea.md
## What
A CLI that…
## Who · ## Constraints · ## Done
## What
A CLI that…
## Who · ## Constraints · ## Done
04
Generate the spec with your agent
Point your GenAI agent at the pre-wired workflow in .sdd/. It
reads idea.md and writes spec/ — then you build.
› "Follow .sdd/phase-1
and spec my idea.md"
▸ spec/ generated ✓
and spec my idea.md"
▸ spec/ generated ✓
05 / The three phases
PHASE 2
The Spec
The agent expands the idea into a structured specification: scope, interfaces, data, and acceptance criteria.
→ spec/
PHASE 3
The Build
Implementation proceeds against the spec, one reviewable slice at a time — guided, traceable, and correct by construction.
→ src/
06 / What's in the box
Pre-wired folders
idea, spec, and phase directories already laid out the way SDD expects them.
Workflow files
The .sdd/ prompts that turn your idea into a spec — tuned and ready for any agent.
Templates included
Starter idea.md and spec templates so you fill in blanks instead of a blank page.
Agent-agnostic
Works with whatever GenAI tool you already use. No lock-in, no proprietary runtime.
Zero install
No package to add, nothing to build. Clone, copy the files, and you are working.
Spec-sync CI
Built-in CI checks flag drift between spec/ and the actual codebase, keeping your specification clean and current as the project evolves.
07 / FAQ
Is there a CLI to install?
No. sdd-starter is a scaffold, not a tool — it is a repository of folders, templates, and workflow files. You clone it and copy those files into your project. There is nothing to install and no runtime to keep up to date.
Which AI agent does it work with?
Any of them. The scaffold ships plain-Markdown workflow files that describe each phase; you point whatever GenAI agent you already use at them. It is deliberately agent-agnostic — no lock-in.
How is this different from just prompting?
Prompting keeps your intent in a chat log that scrolls away and has to be re-explained every session. SDD makes intent a committed artifact — idea.md and the generated spec — that any agent or teammate can load, review, and build against.
Do I have to start a new project?
No. Copy the scaffold into an existing repository just as easily as a fresh one. The files sit alongside your code; only idea.md and spec/ are new to your workflow.
Is it free?
Yes — MIT licensed and open source. Fork it, rename it, and adapt the templates and workflows to the way your team actually builds.
Stop prompting.
Start specifying.
Clone the scaffold and write your first idea.md in the next five minutes.
$ gh repo clone Vedoma/sdd-starter