spec-driven-workflow – Agents & Automation skill for AI agents

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

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.

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. |

| 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. |

See [spec_format_guide.md](references/spec_format_guide.md) for the complete template with section-by-section examples, good/bad requirement patterns, and feature-type templates (CRUD, Integration, Migration).

See [acceptance_criteria_patterns.md](references/acceptance_criteria_patterns.md) for a full pattern library of Given/When/Then criteria across authentication, CRUD, search, file upload, payment, notification, and accessibility scenarios.

---

Bounded Autonomy Rules

These rules define when an agent (human or AI) MUST stop and ask for guidance vs. when they 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 the correct behavior from the spec for more than 30% of a given 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 that touches authentication, authorization, encryption, or PII handling requires explicit approval.

5. Performance characteristics unknown. If a requirement says "MUST complete in < 500ms" but you have 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:

1. Spec is clear and unambiguous for the current task.

2. All acceptance criteria have passing tests and you are refactoring internals.

3. Changes are non-breaking — no public API, schema, or behavior changes.

4. Implementation is a direct translation of a well-defined acceptance criterion.

5. Error handling follows established patterns already documented in the codebase.

Escalation Protocol

When you must stop, provide:

## Escalation: [Brief Title]

**Blocked on:** [requirement ID, e.g., FR-3]
**Question:** [Specific, answerable question — not "what should I do?"]
**Options considered:**
  A. [Option] — Pros: [...] Cons: [...]
  B. [Option] — Pros: [...] Cons: [...]
**My recommendation:** [A or B, with reasoning]
**Impact of waiting:** [What is blocked until this is resolved?]

Never escalate without a recommendation. Never present an open-ended question. Always give options.

See references/bounded_autonomy_rules.md for the complete decision matrix.

---

Workflow — 6 Phases

Phase 1: Gather Requirements

Goal: Understand what needs to be built and why.

1. Interview the user. Ask:

• What problem does this solve?
• Who are the users?
• What does success look like?
• What explicitly should NOT be built?

2. Read existing code. Understand the current system before proposing changes.

3. Identify constraints. Performance budgets, security requirements, backward compatibility.

4. List unknowns. Every unknown is a risk. Surface them now, not during implementation.

Exit criteria: You can explain the feature to someone unfamiliar with the project in 2 minutes.

Phase 2: Write Spec

Goal: Produce a complete spec document following The Spec Format above.

1. Fill every section of the template. No section left blank.

2. Number all requirements (FR-*, NFR-*, AC-*, EC-*, OS-*).

3. Use RFC 2119 keywords precisely.

4. Write acceptance criteria in Given/When/Then format.

5. Define API contracts with TypeScript-style types.

6. List explicit exclusions in Out of Scope.

Exit criteria: The spec can be handed to a developer who was not in the requirements meeting, and they can implement the feature without asking clarifying questions.

Phase 3: Validate Spec

Goal: Verify the spec is complete, consistent, and implementable.

Run spec_validator.py against the spec file:

python spec_validator.py --file spec.md --strict

Manual validation checklist:

• [ ] 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 in requirements
• [ ] 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 criteria: Spec scores 80+ on validator, and all manual checklist items pass.

Phase 4: Generate Tests

Goal: Extract test cases from acceptance criteria before writing implementation code.

Run test_extractor.py against the approved spec:

python test_extractor.py --file spec.md --framework pytest --output tests/

1. Each acceptance criterion becomes one or more test cases.

2. Each edge case becomes a test case.

3. Tests are stubs — they define the assertion but not the implementation.

4. All tests MUST fail initially (red phase of TDD).

Exit criteria: You have a test file where every test fails with "not implemented" or equivalent.

Phase 5: Implement

Goal: Write code that makes failing tests pass, one acceptance criterion at a time.

1. Pick one acceptance criterion (start with the simplest).

2. Make its test(s) pass with minimal code.

3. Run the full test suite — no regressions.

4. Commit.

5. Pick the next acceptance criterion. Repeat.

Rules:

• Do NOT implement anything not in the spec.
• Do NOT optimize before all acceptance criteria pass.
• Do NOT refactor before all acceptance criteria pass.
• If you discover a missing requirement, STOP and update the spec first.

Exit criteria: All tests pass. All acceptance criteria satisfied.

Phase 6: Self-Review

Goal: Verify im

… (full content is in the download package)