Spec Driven Workflow
Install this when you need Given/When/Then acceptance criteria tied to functional and non-functional requirements so specs are testable before implementation.
Overview
spec-driven-workflow is an agent skill most often used in Validate (also Build pm, Ship testing) that authors Given/When/Then acceptance criteria traced to FR/NFR IDs using a shared pattern library.
Install
npx skills add https://github.com/alirezarezvani/claude-skills --skill spec-driven-workflowWhat is this skill?
- Structured AC template: Given precondition → When trigger → Then observable outcome (+ And)
- Four rules: one scenario per AC, trace to FR-* or NFR-*, testable outcomes, achievable preconditions
- Pattern library seeds auth, APIs, and common feature types with copy-paste markdown blocks
- Happy-path and failure-path examples (e.g. valid login vs wrong password) with explicit status and body assertions
- Each AC names descriptive titles and requirement IDs (FR-1, NFR-*) for audit-ready specs
- 4 structural rules for every acceptance criterion
- AC template uses Given / When / Then / And blocks tied to FR-* or NFR-*
Adoption & trust: 526 installs on skills.sh; 17.5k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your feature spec reads clear in prose but nobody can tell objectively when it is done or how to test edge cases like invalid login.
Who is it for?
Solo builders writing SaaS or API specs who want BDD-style criteria before agents or contractors write code.
Skip if: Throwaway spikes with no test intent, or teams that already maintain a frozen enterprise requirements baseline and only need typo edits.
When should I use this skill?
User is defining features in a spec-driven way and needs Given/When/Then acceptance criteria patterns linked to functional or non-functional requirements.
What do I get? / Deliverables
You leave with numbered, traceable AC blocks—preconditions, triggers, and measurable outcomes—ready to drive implementation and automated or manual test suites.
- Numbered acceptance criteria (AC-N) in Given/When/Then form
- Requirement traceability from each AC to FR/NFR IDs
- Starter patterns for auth and common feature types
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Spec-driven acceptance criteria belong on the Validate shelf first because they lock observable behavior before heavy Build work. Scope is where FR/NFR-linked ACs define what “done” means—patterns here prevent vague stories from entering the codebase.
Where it fits
Draft AC-1 and AC-2 for login happy path and wrong password before estimating the auth milestone.
Attach AC blocks to the implementation plan so the agent knows 200 + JWT is the definition of done.
Map each AC to an automated test case with the same Given/When/Then wording.
Write observable criteria for checkout totals and tax display before enabling paid tiers.
How it compares
Use structured AC patterns instead of vague user stories that lack Given/When/Then test hooks.
Common Questions / FAQ
Who is spec-driven-workflow for?
Indie developers and small teams shipping products with agents who need testable requirements documents, especially for APIs, auth, and regulated observable behavior.
When should I use spec-driven-workflow?
Use it in Validate while scoping FR/NFR and acceptance tests; in Build when refining PM docs and API contracts; and in Ship when turning criteria into regression scenarios—whenever you are defining AC-* rows linked to FR-* or NFR-*.
Is spec-driven-workflow safe to install?
It is documentation and pattern guidance with no bundled executables; still review the Security Audits panel on this Prism page before adding any skill from the catalog.
SKILL.md
READMESKILL.md - Spec Driven Workflow
# Acceptance Criteria Patterns A pattern library for writing Given/When/Then acceptance criteria across common feature types. Use these as starting points — adapt to your domain. --- ## Pattern Structure Every acceptance criterion follows this structure: ``` ### AC-N: [Descriptive name] (FR-N, NFR-N) Given [precondition — the system/user is in this state] When [trigger — the user or system performs this action] Then [outcome — this observable, testable result occurs] And [additional outcome — and this also happens] ``` **Rules:** 1. One scenario per AC. Multiple Given/When/Then blocks = multiple ACs. 2. Every AC references at least one FR-* or NFR-*. 3. Outcomes must be observable and testable — no subjective language. 4. Preconditions must be achievable in a test setup. --- ## Authentication Patterns ### Login — Happy Path ```markdown ### AC-1: Successful login with valid credentials (FR-1) Given a registered user with email "user@example.com" and password "V@lidP4ss!" When they POST /api/auth/login with email "user@example.com" and password "V@lidP4ss!" Then the response status is 200 And the response body contains a valid JWT access token And the response body contains a refresh token And the access token expires in 24 hours ``` ### Login — Invalid Credentials ```markdown ### AC-2: Login rejected with wrong password (FR-1) Given a registered user with email "user@example.com" When they POST /api/auth/login with email "user@example.com" and an incorrect password Then the response status is 401 And the response body contains error code "INVALID_CREDENTIALS" And no token is issued And the failed attempt is logged ``` ### Login — Account Locked ```markdown ### AC-3: Login rejected for locked account (FR-1, NFR-S2) Given a user whose account is locked due to 5 consecutive failed login attempts When they POST /api/auth/login with correct credentials Then the response status is 403 And the response body contains error code "ACCOUNT_LOCKED" And the response includes a "retryAfter" field with seconds until unlock ``` ### Token Refresh ```markdown ### AC-4: Token refresh with valid refresh token (FR-3) Given a user with a valid, non-expired refresh token When they POST /api/auth/refresh with that refresh token Then the response status is 200 And a new access token is issued And the old refresh token is invalidated And a new refresh token is issued (rotation) ``` ### Logout ```markdown ### AC-5: Logout invalidates session (FR-4) Given an authenticated user with a valid access token When they POST /api/auth/logout with that token Then the response status is 204 And the access token is no longer accepted for API calls And the refresh token is invalidated ``` --- ## CRUD Patterns ### Create ```markdown ### AC-6: Create resource with valid data (FR-1) Given an authenticated user with "editor" role When they POST /api/resources with valid payload {name: "Test", type: "A"} Then the response status is 201 And the response body contains the created resource with a generated UUID And the resource's "createdAt" field is set to the current UTC timestamp And the resource's "createdBy" field matches the authenticated user's ID ``` ### Create — Validation Failure ```markdown ### AC-7: Create resource rejected with invalid data (FR-1) Given an authenticated user When they POST /api/resources with payload missing required field "name" Then the response status is 400 And the response body contains error code "VALIDATION_ERROR" And the response body contains field-level detail: {"name": "Required field"} And no resource is created in the database ``` ### Read — Single Item ```markdown ### AC-8: Read resource by ID (FR-2) Given an existing resource with ID "abc-123" When an authenticated user GETs /api/resources/abc-123 Then the response status is 200 And the response body contains the resource with all fields ``` ### Read — Not Found ```markdown ### AC-9: Read non-existent resource returns 404 (FR-2) Given no resource ex