Specs-Driven Development
Specs-driven development is the planning layer of Buildpad’s AI workflow. You describe what you want in plain English, your AI generates three structured documents — requirements.md, design.md, tasks.md — and you review each one before any code is written. It pairs with Phased Development, which governs how the resulting tasks are built.
This workflow is built into Kiro via its native Specs feature. Other AI IDEs can produce similar artifacts manually, but lack the structured review gates between phases — if you’re using GitHub Copilot, Antigravity, or another IDE without native specs support, follow Phased Development instead, which is Buildpad’s natively supported workflow across all AI IDEs.
The Three Spec Phases
Each phase produces one document. You approve it before the next phase starts.
| Phase | Document | What’s in it | What to review |
|---|---|---|---|
| 1. Requirements | requirements.md | User stories and acceptance criteria | Are all the user-facing features listed? Anything missing? |
| 2. Design | design.md | Technical architecture, data models, page structure | Does the shape match your mental model? Are the data models reasonable? |
| 3. Tasks | tasks.md | Numbered, discrete implementation steps grouped by checkpoint | Does the task list cover every requirement? Are checkpoints in sensible places? |
The artifacts live in your project under .kiro/specs/<feature-name>/:
- requirements.md
- design.md
- tasks.md
Checkpoints in tasks.md
tasks.md is a numbered list of discrete work items. Tasks are grouped by checkpoints — natural pause points where you stop, run the app, and verify what’s built before continuing. The Vibe Coder tutorial uses checkpoints at Tasks 3, 8, and 15 to separate the data layer, UI layer, and access-control layer.
Run tasks sequentially via the Run task button next to each item. Don’t skip ahead — each checkpoint depends on the previous one being verified.
Specs vs. Phases
Specs and phases are complementary layers, not alternatives:
| Layer | Answers | Output |
|---|---|---|
| Specs (planning) | What gets built? | requirements.md, design.md, tasks.md |
| Phases (execution) | How does it get built incrementally? | PHASES.md progress tracker |
A typical flow: create a spec for a feature → review the three documents → execute tasks.md step-by-step within the appropriate phase (data tasks in Phase 1, UI tasks in Phase 2, and so on).
How to Use Specs in Kiro
- Open the Kiro pane (the ghost icon in the activity bar).
- Click the
+button under Specs. - Describe what you want to build in plain English.
- When prompted, choose Feature, then Requirements-First.
- Kiro generates
requirements.md. Review it; ask Kiro to revise if anything is missing. - Approve to move to Design, then to Tasks.
- Run tasks one at a time, stopping at each checkpoint to verify.
Don’t let Kiro skip the review steps. The whole point of specs-driven development is to catch missing requirements before code lands — the cost of fixing a missed acceptance criterion in requirements.md is a sentence; the cost in deployed code is a refactor.
Why Specs-First
- Catch missing requirements while cheap — issues found in
requirements.mdcost a sentence to fix; issues found in deployed code cost a refactor - AI accuracy on bounded scope — generating code from an approved
tasks.mdis far more reliable than generating from an open-ended prompt - Shared review artifact —
requirements.mdis something a non-technical stakeholder can read and approve, the same way they’d approve a wireframe - Reproducible plan — re-read
requirements.mdanddesign.mdat any time to remember why something was built the way it was
Related
- Kiro setup — install Kiro and connect to your Buildpad backend
- Phased Development — the 6-phase execution methodology that pairs with specs
- Tutorial: Plan Your App with AI — a hands-on walkthrough of creating your first spec
- Kiro Specs documentation — the official feature reference