Agent skill · software engineering · alirezarezvani
spec-driven-workflow
Use when a feature should be specified before coding (acceptance criteria, spec-first, tests from specs). Writes the spec with spec_generator.py, checks it with spec_validator.py and extracts tests with test_extractor.py.
Why this skill is useful
Provides a structured approach to writing specifications that ensures clarity and accountability, which the AI wouldn't reliably generate on its own.
What it needs
About 9k tokens when loaded. Last updated 2026-08-05. 23,939 stars on the source repository.
What this skill does
Spec-Driven Workflow — POWERFUL Overview Spec-driven workflow enforces a single, non-negotiable rule: write the specification BEFORE you write any code. Not alongside. Not after. Before. This is not documentation. This is a contract. A spec defines what the system MUST do, what it SHOULD do, and what it explicitly WILL NOT do. Every line of code you write traces back to a requirement in the spec. Every test traces back to an acceptance criterion. If it is not in the spec, it does not get built. Why Spec-First Matters 1. Eliminates rework. 60-80% of defects originate from requirements, not implementation. Catching ambiguity in a spec costs minutes; catching it in production costs days. 2. Forces clarity. If you cannot write what the system should do in plain language, you do not understand the problem well enough to write code. 3. Enables parallelism. Once a spec is approved, frontend, backend, QA, and documentation can all start simultaneously. 4. Creates accountability. The spec is the definition of done. No arguments about whether a feature is "complete" — either it satisfies the acceptance criteria or it does not. 5. Feeds TDD directly. Acceptance criteria in Given/When/Then format translate 1:1 into test cases. The spec IS the test plan. The Iron Law If the spec is not written, reviewed, and approved, implementation does not begin. Period. --- The Spec Format Every spec follows this structure. No sections are optional — if a section does not apply, write "N/A — [reason]" so reviewers know it was considered, not forgotten. Mandatory Sections # Section Key Rules --- --------- ----------- 1 Title and Metadata Author, date, status (Draft/In Review/Approved/Superseded), reviewers 2 Context Why this feature exists. 2-4 paragraphs with evidence (metrics, tickets). 3 Functional Requirements RFC 2119 keywords (MUST/SHOULD/MAY). Numbered FR-N. Each is atomic and testable. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills alirezarezvani/spec-driven-workflow--5358ff