spec-driven-development
/spec-driven-development
Spec-first workflow where an executable, testable specification is written before code and becomes the single source of truth that tests verify against, flowing spec → acceptance criteria → tasks → implementation. Use when: write the spec before the code, run a spec-first workflow, derive acceptance criteria from a spec, decompose a spec into tasks, make the spec the source of truth, spec kit style development.
- Author
- andreibesleaga ↗
- Repository
- gabbe ↗
- Licence
- CC-BY-4.0
- Last repository change
- 24.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.
CC-BY-4.0, otwarta.
What it does and when to use it
Spec-first workflow where an executable, testable specification is written before code and becomes the single source of truth that tests verify against, flowing spec → acceptance criteria → tasks → implementation. Use when: write the spec before the code, run a spec-first workflow, derive acceptance criteria from a spec, decompose a spec into tasks, make the spec the source of truth, spec kit style development.
Original author description
Spec-first workflow where an executable, testable specification is written before code and becomes the single source of truth that tests verify against, flowing spec → acceptance criteria → tasks → implementation. Use when: write the spec before the code, run a spec-first workflow, derive acceptance criteria from a spec, decompose a spec into tasks, make the spec the source of truth, spec kit style development.
How it works
- Goal
- Steps
- Constraints
- Output Format
- Security & Guardrails
SKILL.md preview
---
name: spec-driven-development
description: "Spec-first workflow where an executable, testable specification is written before code and becomes the single source of truth that tests verify against, flowing spec → acceptance criteria → tasks → implementation. Use when: write the spec before the code, run a spec-first workflow, derive acceptance criteria from a spec, decompose a spec into tasks, make the spec the source of truth, spec kit style development."
license: CC-BY-SA-4.0
metadata:
source: "agents/skills/coding/spec-driven-development.skill.md"
tags: "coding, process, spec-driven, sdlc, requirements"
core: "false"
context_cost: "medium"
---
# Spec-Driven Development
## Goal
Invert the usual order: write the specification *first*, make it concrete and testable, and
treat it as the single source of truth that the implementation must satisfy and the tests must
verify against. In a spec-driven (Spec Kit-style) workflow the spec is not prose that rots in a
wiki — it is an executable contract. Work flows spec → acceptance criteria → tasks →
implementation, mapping onto the project phases S01 (Requirements) → S02 (Design) → S03
(Specification) → S04 (Tasks) before S05 (Implementation). The deliverable is a **spec-driven
workflow plan**: the spec, the acceptance criteria derived from it, the task decomposition, and
the verification linkage that keeps code, tests, and spec in agreement.
## Steps
1. **Capture requirements as the spec's intent (S01).** Before writing the spec, pin down *what*
and *why* — the user need, scope, and non-goals — separate from *how*. This anchors the spec
so it specifies behavior, not a premature implementation. Record explicit out-of-scope items
so the spec can't quietly expand.
2. **Resolve design constraints (S02).** Settle the architectural decisions and constraints the
spec must respect (interfaces, quality attributes, tech constraints) via `arch-design.skill`,
so the specification is grounded in a feasible design rather than wishful behavior.
3. **Write the executable/testable specification (S03).** Make the spec *verifiable*: every
requirement stated so a test can pass or fail against it. Prefer concrete, observable behavior
(inputs, outputs, error cases, edge cases, invariants) over adjectives. Where possible express
it in an executable form — given/when/then scenarios, contract/schema definitions, or runnable
examples — so the spec itself can be checked, not just read. This spec is now the single source
of truth.
4. **Derive acceptance criteria from the spec.** Turn each spec requirement into explicit,
binary acceptance criteria ("given X, when Y, the system returns Z"; "rejects W with error E").
Acceptance criteria are the bridge between the spec and the tests — each criterion becomes one
or more verifications. No criterion may introduce behavior absent from the spec; if it must,
the spec is amended first.
5. **Decompose into tasks (S04).** Break the spec + acceptance criteria into atomic, independently
verifiable tasks (small units, each traceable to specific criteria). Every task carries a link
back to the spec section and acceptance criteria it fulfills, so the traceability is explicit
and gaps are visible.
6. **Implement against the spec (S05).** Write code and tests to satisfy the acceptance criteria.
Tests verify *against the spec* — they assert the specified behavior, so a passing suite means
"matches the spec," and a spec change forces a test change. Pair with `tdd-cycle.skill` to write
the criterion's test before its code.
7. **Keep the spec authoritative.** When reality diverges (a missed case, a changed requirement,
an impossible criterion), update the *spec first*, then propagate to acceptance criteria,
tasks, tests, and code. Code that drifts from the spec is a defect in one of the two — never
let undocumented behavior accumulate. Maintain the spec→criteria→task→test traceability as the
record that the system does what it claims.
## Constraints
- The spec is the **single source of truth**. When code and spec disagree, one of them is wrong;
resolve by amending the spec deliberately, never by silently letting code define behavior.
- A spec is only useful if it is **testable**. Requirements that cannot be turned into a
pass/fail criterion are aspirations, not spec — rewrite them as observable behavior or remove
them.
- Tests verify *against the spec*, so a green suite means "conforms to the current spec," **not**
"is correct" — the spec itself can be wrong or incomplete. State this honestly; spec-driven
development moves correctness questions up to spec review, it does not eliminate them.
- Every acceptance criterion and task MUST trace to a spec section; untraced work is either
gold-plating or a spec gap. Surface both rather than absorbing them.
- Changes flow spec → criteria → tasks → tests → code, never the reverse. A code change that
alters behavior without a spec update is an undocumented divergence to flag.
## Output Format
Produce a **spec-driven workflow plan** containing:
- The specification: requirements and non-goals (S01), respected design constraints (S02), and
the executable/testable behavior statements (S03) — inputs, outputs, error and edge cases,
invariants.
- The acceptance criteria derived from each spec requirement, each binary and observable.
- The task decomposition (S04), each task linked to its spec section and acceptance criteria.
- The verification linkage: which test verifies which criterion, and the spec→criteria→task→test
traceability map.
- An honesty note: tests confirm conformance to the spec, not absolute correctness; the spec must
be reviewed on its own merits. Cross-reference `tdd-cycle.skill` for the test-first inner loop
and `arch-design.skill` for the design phase.
## Security & Guardrails
### 1. Skill Security
- **Risk**: "Tests pass" is reported as "the system is correct," when it only means the code
conforms to a spec that may itself be wrong or incomplete. Mitigation: every report MUST scope
the claim to spec-conformance and require the spec to be reviewed independently; the agent MUST
NOT present spec conformance as proof of correctness.
- **Risk**: The spec is silently weakened to make a failing test pass. Mitigation: spec changes
MUST be explicit, reviewed, and version-controlled like code; the agent MUST refuse to edit the
spec merely to accommodate broken code without surfacing the change for human approval.
### 2. System Integration Security
- **Risk**: Security and compliance requirements live only in the implementation and never enter
the spec, so they are untested and can be dropped in a refactor. Mitigation: require security,
authz, data-handling, and compliance requirements to be first-class, testable spec items with
their own acceptance criteria and traceable tests.
- **Risk**: Implementation adds undocumented behavior (a hidden endpoint, an extra side effect)
not in the spec, expanding attack surface invisibly. Mitigation: treat any behavior absent from
the spec as a divergence to flag; the traceability map MUST expose code paths that map to no
spec section.
### 3. LLM & Agent Guardrails
- **Risk**: The agent invents acceptance criteria or tasks describing behavior the spec never
stated, then builds and tests to its own fiction. Mitigation: every criterion and task MUST
trace to a spec section; the agent MUST amend the spec first (with human review) before adding
derived behavior, and MUST mark agent-proposed requirements as unconfirmed.
- **Risk**: The agent writes tests that assert the implementation it just wrote rather than the
spec, making them tautological and unable to catch spec violations. Mitigation: tests MUST be
derived from acceptance criteria/spec, not reverse-engineered from the code; the agent MUST
verify each test would fail if the specified behavior were violated.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · andreibesleaga/gabbe | 100 | CC-BY-4.0 |
| magnus919/agent-skills | 100 | MIT |
| lucasouzadev/agent-kit-skill | 100 | MIT |
| FrancoStino/opencode-skills-collection | 100 | MIT |
| DanielCryer/spec-workflow | 100 | MIT |
| ctoforaday/special-circumstances | 100 | MIT |
| krzysztofsurdy/code-virtuoso | 100 | MIT |
| rafidone/agent-skills | 100 | MIT |
| sickn33/agentic-awesome-skills | 100 | MIT |
Database snapshot: 13.11.2026 · package version 076faa99a95f (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100spec-driven-workflow
Use when the user asks to write specs before code, define acceptance criteria, plan features before implementation, generate tests from specifications, or follow spec-first development practices. - 90spec-driven
Guide spec-driven development workflow (Requirements → Design → Tasks → Implementation) with approval gates between phases. Use when user wants structured feature planning or says "use spec-driven" or "follow the spec process". - 100specops
Spec-driven development workflow where specs are the source of truth, paired with a plan protocol for tracking work-in-flight as a micro-DAG. Use this skill whenever starting new features, planning implementation, writing specs, reviewing code against specs, working in or with a… - 100spec-coder
Structured spec-first development workflow with multi-role expert review gates: clarify requirements, author spec documents (requirements/design/tasks), generate code from spec, verify with real tests, and iterate while keeping spec and code in sync. Use when user wants to build… - 100spec-driven-development-engineering
Engineering practice: Spec-driven development — Keep a versioned spec in the repository as the source of truth that people and coding agents implement against, with requirement IDs traced into tasks, tests and pull requests, so behaviour and intent never quietly drift apart. Use… - 100spec-dd
This skill should be used when the user asks to "write specifications", "create test specifications", "specification-driven development", "spec-first", "behavioral specs", "derive test scenarios", "test implementation specification", "check specification alignment", "review…