Spec Driven Development
Turn vague feature ideas into a human-reviewed spec before your agent writes implementation code.
Overview
Spec-driven development is a journey-wide agent skill that creates human-reviewed specifications before coding—usable whenever a solo builder needs to lock requirements before committing to implementation.
Install
npx skills add https://github.com/addyosmani/agent-skills --skill spec-driven-developmentWhat is this skill?
- Four gated phases: Specify → Plan → Tasks → Implement with human review between each
- Surfaces assumptions upfront before any spec content is drafted
- Explicit skip rules for one-line fixes and unambiguous self-contained changes
- Treats the spec as shared source of truth between human and agent
- Blocks coding until the current phase is validated
- 4-phase gated workflow: Specify, Plan, Tasks, Implement
- Human review gate at each phase before advancing
Adoption & trust: 5.2k installs on skills.sh; 49.1k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are about to build a feature but only have a vague idea, no shared spec, and risk the agent implementing the wrong thing across many files.
Who is it for?
New features, ambiguous requirements, architectural decisions, and changes that touch multiple modules or take substantial agent time.
Skip if: Single-line fixes, typo corrections, or changes where requirements are already unambiguous and fully self-contained.
When should I use this skill?
Starting a new project, feature, or significant change when no specification exists; requirements unclear, ambiguous, or only a vague idea.
What do I get? / Deliverables
You get a structured, reviewed specification through Specify, Plan, and Tasks so implementation starts only after requirements and done criteria are agreed.
- Structured specification document
- Plan and task breakdown aligned to the spec
- Implementation only after validated phases
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
Clarify a landing-page experiment into a spec with assumptions before any React work starts.
Break a multi-module API feature into Specify → Plan → Tasks before the agent edits services and tests.
Document an architectural choice in a spec when the change spans database, API, and workers.
Derive review checkpoints from the spec so human sign-off matches what was agreed in the Tasks phase.
Extend an existing product area with a mini-spec so production fixes do not drift from documented behavior.
How it compares
Use instead of jumping straight from chat brainstorming into code without a written, phase-gated spec.
Common Questions / FAQ
Who is spec-driven development for?
Solo and indie builders who want a shared written contract with their coding agent before non-trivial implementation work.
When should I use spec-driven development?
At validate/scope when requirements are fuzzy; in build/pm when planning a multi-file feature; before ship/review when you need acceptance criteria; and anytime a task is architectural or likely to exceed a quick fix.
Is spec-driven development safe to install?
It is procedural documentation for planning workflows; review the Security Audits panel on this Prism page before installing any skill from the catalog.
SKILL.md
READMESKILL.md - Spec Driven Development
# Spec-Driven Development ## Overview Write a structured specification before writing any code. The spec is the shared source of truth between you and the human engineer — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing. ## When to Use - Starting a new project or feature - Requirements are ambiguous or incomplete - The change touches multiple files or modules - You're about to make an architectural decision - The task would take more than 30 minutes to implement **When NOT to use:** Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained. ## The Gated Workflow Spec-driven development has four phases. Do not advance to the next phase until the current one is validated. ``` SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT │ │ │ │ ▼ ▼ ▼ ▼ Human Human Human Human reviews reviews reviews reviews ``` ### Phase 1: Specify Start with a high-level vision. Ask the human clarifying questions until requirements are concrete. **Surface assumptions immediately.** Before writing any spec content, list what you're assuming: ``` ASSUMPTIONS I'M MAKING: 1. This is a web application (not native mobile) 2. Authentication uses session-based cookies (not JWT) 3. The database is PostgreSQL (based on existing Prisma schema) 4. We're targeting modern browsers only (no IE11) → Correct me now or I'll proceed with these. ``` Don't silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings *before* code gets written — assumptions are the most dangerous form of misunderstanding. **Write a spec document covering these six core areas:** 1. **Objective** — What are we building and why? Who is the user? What does success look like? 2. **Commands** — Full executable commands with flags, not just tool names. ``` Build: npm run build Test: npm test -- --coverage Lint: npm run lint --fix Dev: npm run dev ``` 3. **Project Structure** — Where source code lives, where tests go, where docs belong. ``` src/ → Application source code src/components → React components src/lib → Shared utilities tests/ → Unit and integration tests e2e/ → End-to-end tests docs/ → Documentation ``` 4. **Code Style** — One real code snippet showing your style beats three paragraphs describing it. Include naming conventions, formatting rules, and examples of good output. 5. **Testing Strategy** — What framework, where tests live, coverage expectations, which test levels for which concerns. 6. **Boundaries** — Three-tier system: - **Always do:** Run tests before commits, follow naming conventions, validate inputs - **Ask first:** Database schema changes, adding dependencies, changing CI config - **Never do:** Commit secrets, edit vendor directories, remove failing tests without approval **Spec template:** ```markdown # Spec: [Project/Feature Name] ## Objective [What we're building and why. User stories or acceptance criteria.] ## Tech Stack [Framework, language, key dependencies with versions] ## Commands [Build, test, lint, dev — full commands] ## Project Structure [Directory layout with descriptions] ## Code Style [Example snippet + key conventions] ## Testing Strategy [Framework, test locations, coverage requirements, test levels] ## Boundaries - Always: [...] - Ask first: [...] - Never: [...] ## Success Criteria [How we'll know this is done — specific, testable conditions] ## Open Questions [Anything unresolved that needs human input] ``` **Reframe instructions as success criteria.** When receiving vague require