spec-driven-workflow

---
name: spec-driven-workflow
description: Use when the user asks to write specs before code, define acceptance criteria, plan features before implementation, generate tests from specs, or follow spec-first practices.
category: Engineering
version: 1.0.0
tools: []
---

# Spec-Driven Workflow

Enforce 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 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. Either a feature 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

```
NO CODE WITHOUT AN APPROVED SPEC.
NO EXCEPTIONS. NO "QUICK PROTOTYPES." NO "I'LL DOCUMENT IT LATER."
```

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.

| # | 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. |
| 4 | **Non-Functional Requirements** | Performance, security, accessibility, scalability, reliability — all with measurable thresholds. |
| 5 | **Acceptance Criteria** | Given/When/Then format. Every AC references at least one FR-* or NFR-*. |
| 6 | **Edge Cases** | Numbered EC-N. Cover failure modes for every external dependency. |
| 7 | **API Contracts** | TypeScript-style interfaces. Cover success and error responses. |
| 8 | **Data Models** | Table format with field, type, constraints. Every entity from requirements must have a model. |
| 9 | **Out of Scope** | Explicit exclusions with reasons. Prevents scope creep during implementation. |

### RFC 2119 keywords

| Keyword | Meaning |
|---------|---------|
| **MUST** | Absolute requirement. Non-conformant without it. |
| **MUST NOT** | Absolute prohibition. |
| **SHOULD** | Recommended. Omit only with documented justification. |
| **MAY** | Optional. Implementer's discretion. |

## Bounded Autonomy Rules

These rules define when you MUST stop and ask for guidance vs. when you can proceed independently.

### Stop and ask when

1. **Scope creep detected.** The implementation requires something not in the spec. Even if it seems obviously needed, stop — the spec might have excluded it deliberately.
2. **Ambiguity exceeds 30%.** If you cannot determine correct behavior from the spec for more than 30% of a requirement, the spec is incomplete. Do not guess.
3. **Breaking changes required.** The implementation would change an existing API contract, database schema, or public interface. Always escalate.
4. **Security implications.** Any change touching authentication, authorization, encryption, or PII handling requires explicit approval.
5. **Performance characteristics unknown.** If a requirement says "MUST complete in < 500ms" but there's no way to measure or guarantee that, escalate before implementing a guess.
6. **Cross-team dependencies.** If the spec requires coordination with another team or service, confirm the dependency before building against it.

### Continue autonomously when

Spec is clear and unambiguous for the current task; all acceptance criteria have passing tests and you're refactoring internals; changes are non-breaking; implementation is a direct translation of a well-defined acceptance criterion; error handling follows established patterns already in the codebase.

### Escalation protocol

When you must stop, provide: the blocked requirement ID (e.g., FR-3); a specific, answerable question — not "what should I do?"; 2+ options with pros/cons; your recommendation with reasoning; and the impact of waiting. Never escalate without a recommendation. Never present an open-ended question. Always give options.

## Workflow — 6 Phases

**Phase 1: Gather Requirements.** Interview: what problem does this solve, who are the users, what does success look like, what should NOT be built. Read existing code before proposing changes. Identify constraints (performance budgets, security requirements, backward compatibility). List every unknown — each one is a risk to surface now, not during implementation. Exit when you can explain the feature to someone unfamiliar with the project in 2 minutes.

**Phase 2: Write Spec.** Fill every section of the template — no section left blank. Number all requirements (FR-*, NFR-*, AC-*, EC-*, OS-*). Use RFC 2119 keywords precisely. Write acceptance criteria in Given/When/Then format. Define API contracts with TypeScript-style types. List explicit exclusions in Out of Scope. Exit when the spec could be handed to a developer who wasn't in the requirements meeting, and they could implement without clarifying questions.

**Phase 3: Validate Spec.** Confirm: every functional requirement has at least one acceptance criterion; every acceptance criterion is testable (no subjective language); API contracts cover all endpoints mentioned in requirements; data models cover all entities mentioned; edge cases cover failure modes for every external dependency; out of scope is explicit about what was considered and rejected; non-functional requirements have measurable thresholds. Exit when all checklist items pass.

**Phase 4: Generate Tests.** Extract test cases from the approved spec before writing implementation code: each acceptance criterion becomes one or more test cases, each edge case becomes a test case. Tests are stubs — they define the assertion but not the implementation, and MUST all fail initially (the red phase of TDD). Exit when every test fails with "not implemented" or equivalent.

**Phase 5: Implement.** Pick one acceptance criterion (start with the simplest), make its test(s) pass with minimal code, run the full test suite for regressions, commit, repeat. Do NOT implement anything not in the spec. Do NOT optimize or refactor before all acceptance criteria pass. If you discover a missing requirement, stop and update the spec first. Exit when all tests pass and all acceptance criteria are satisfied.

**Phase 6: Self-Review.** Run the Self-Review Checklist below before declaring the task complete.

## Self-Review Checklist

Before marking any implementation done, verify ALL of the following: every acceptance criterion has a passing test (no exceptions); every edge case has a test; no scope creep (nothing built beyond the spec — either update the spec or remove it); API contracts match implementation exactly (field names, types, status codes); every error response defined in the spec has a test that triggers it; non-functional requirements are verified with evidence (benchmark, load test, profiling), not assertion; the data model matches the spec with no extra columns or missing constraints; nothing from Out of Scope leaked into the implementation.

## Integration with TDD

Spec-driven workflow and TDD are complementary, not competing: Phases 1-3 (Gather, Write, Validate) happen before any test exists. Phase 4 (Generate Tests) produces the RED state of TDD's red-green-refactor cycle. Phase 5 (Implement) is TDD's GREEN. Phase 6 (Self-Review) corresponds to REFACTOR. The spec tells you WHAT to test; TDD tells you HOW to implement. For red-green-refactor cycle discipline, coverage analysis, and framework-specific test patterns, @mention a teammate with TDD expertise once Phase 4 stubs exist — this workflow owns defining what to build, acceptance criteria authoring, completeness validation, and scope control.

## Anti-Patterns

1. **Coding before spec approval.** "I'll start coding while the spec is being reviewed" — the review will surface changes, and now there's code implementing a rejected design. Implementation does not begin until spec status is "Approved."
2. **Vague acceptance criteria.** "The system should work well" or "the UI should be responsive" is untestable. Every acceptance criterion must be verifiable by a machine; if you can't write a test for it, rewrite the criterion.
3. **Missing edge cases.** Happy path specified, error paths not — developers invent error handling on the fly, causing inconsistent behavior. For every external dependency (API, database, file system, user input), specify at least one failure scenario.
4. **Spec as post-hoc documentation.** "Let me write the spec now that the feature is done" describes what was built, not what should have been built, and cannot catch design errors because the design is already frozen. If the spec was written after the code, relabel it as documentation, not a spec.
5. **Gold-plating beyond spec.** "While I was in there, I also added..." introduces untested, unreviewed code with potential for subtle bugs. If it's not in the spec, it doesn't get built — file a new spec for additional features.
6. **Acceptance criteria without requirement traceability.** An AC that references no FR-* or NFR-* means either a requirement is missing or the criterion is unnecessary. Every AC-* MUST reference at least one FR-* or NFR-*.
7. **Skipping validation.** "The spec looks fine, let's just start" causes missing sections to surface mid-implementation as blocking delays. Always run the full validation checklist before starting implementation, and fix all warnings.