Spec-Driven Development

Spec-Driven Development (SDD) is a way to formalise the agentic workflow so it stays consistent, repeatable, and under your control as the project grows.

The core idea

Write down what you want to build before you ask the agent to build it. The spec lives as a file in the repo — not just in your head, not just in the chat. Every agent session starts by reading it.

This simple change fixes most of the problems with vibe coding: the agent stops forgetting, stops contradicting itself, and stops solving the wrong problem.

The constitution

Every project starts with a constitution — a small set of files that describe the whole:

• specs/brief.md — the business description of the app: what problem it solves, who it is for, what it must do. Everything else is derived from it.
• specs/tech-design.md — the high-level implementation plan: how each requirement will be solved, which standard BC features to use, and where custom code is genuinely needed
• specs/roadmap.md — the ordered list of features to build, with a status and done-criteria for each
• AGENTS.md — the project rules: what this project is, how the team works, where the coding standards live

The constitution is written once and updated as decisions change.

The feature loop

Once the constitution is in place, every feature follows the same short loop:

1. Spec — produce requirements.md, plan.md, and acceptance.md for this feature on a dedicated branch
2. Implement — the agent builds from the spec; it can compile, test, and fix autonomously
3. Test — confirm the feature works in the actual product; all automated tests pass
4. Docs — write the user documentation and update the CHANGELOG
5. Finalise — merge the feature branch, update the roadmap, replan if anything shifted

The loop is the same for every feature. Small features take one session. Large features take several. The structure doesn't change.

Skills — automating the loop

Repeatable steps become skills — reusable agent workflows stored as markdown files and scripts. Instead of writing the same spec prompt for every project, you write it once as a skill and invoke it by name. The workshop ships several skills you'll use from the first feature.

Why it works

Spec-driven development is a simple idea, but it works because it makes the agent a persistent worker. Close the chat, switch models, change harness — the specs are still there. The agent reads them and picks up exactly where you left off. You don't re-explain. You just continue.

---

Enough theory. Let's build something.

The app we're building →