Spec-Driven Development Workflow
A practical SOP for applying Spec-Driven Development across agency projects, organized around the 5 Ws and the required structure every spec must follow.
1. WHY — The Purpose of SDD
SDD exists because AI coding agents (Claude Code, Cursor, Copilot) can now turn a sufficiently precise spec into working code in minutes, which shifts the bottleneck from writing code to writing the spec well.
Core rationale:
The specification is the primary artifact, not the code.
It eliminates two failure modes: "vibe coding" (AI guessing from chat) and traditional agile vagueness (stories left intentionally open to interpretation).
A well-formed spec serves two audiences simultaneously: humans (PM, client, QA, devs) and AI coding agents — both need it unambiguous.
Ambiguity in a spec is treated as a defect, not a feature.
Practical test: if QA cannot write test cases directly from the spec without asking questions, the spec isn't ready.
2. WHO — Roles and Ownership
Role | Primary Responsibilities |
Project Manager (PM) | Owns PRD, TRD (if applicable), and the spec backlog. Decides at kickoff which stages the project needs. Drafts specs, iterates with Eng Lead, maintains the tracking doc. |
Engineering Lead | Reviews PRD for technical feasibility. Co-authors TRD sections involving data, calculations, and integrations. Writes and maintains implementation.md. Operates the AI coding agent. |
Designer | Maintains the design system (tokens, components). Delivers Figma per stage ahead of spec write-up. Flags missing design-system support. |
QA | Reviews each spec's Acceptance Criteria before "Ready" status. Has read access to PRD and TRD. Writes test cases per spec. |
Client | Signs off on initial PRD and TRD. Reviews end-of-stage demos. Source of truth for business-rule accuracy. Does not review individual specs by default. |
3. WHAT — Artifacts and Required Spec Structure
3.1 The Artifacts Pipeline
PRD (what & why)
SKILL FIND PRD GAPS AND IMPROVEMENTS - PENDING
Iterate back to PRD
SKILL TO CREATE TRD - PENDING
SKILL FIND TRD GAPS AND IMPROVEMENTS - PENDING
DEV VALIDATES
SKILL sdd-stage-planner
Document Stages (groups of features/flows)
SKILL sdd-spec-writer
Specs (one per feature/flow inside the Stages)
implementation.md (the AI's table of contents, which is going to make reference to the stages/specs folders)
Code.
3.2 Required Structure for Every Spec
Every spec file must contain the following sections — this is the minimum:
# [Spec Name]
Stage: [N]
Status: Draft | Ready | In Progress | Done | Blocked
Depends on: [other spec names, or "none"]
Source: §[X] of TRD, [Figma file link], [PRD section]
## 1. Context
One paragraph. Who triggers this, why it exists, where it sits in the user journey.
## 2. Behavior
- UI behavior (referencing design tokens, not hex codes)
- State transitions
- Validation rules
- Error states and recovery
- Loading and empty states
## 3. Business Rules
The non-UI logic. Reference TRD section if repeating canonical content.
## 4. Data
- What data this spec reads
- What data this spec writes
- Schema additions or changes implied
- API endpoints (if known) or "see implementation.md"
## 5. Permissions
Which roles can do what. Reference the TRD permission matrix.
## 6. Acceptance Criteria
A testable checklist. QA reads this to write test cases.
## 7. Open Questions
TBDs, deferred decisions, items to verify with the client.
3.3 The Four Mandatory Questions Every Spec Answers
If a spec does not explicitly answer all four, it is not ready for engineering:
What is this? (One paragraph: feature, user, trigger.)
What does it do? (UI behavior, business rules, formulas, validation, error states.)
What does it depend on? (Other specs, parameters, integrations, existing data.)
How do we know it works? (Testable acceptance criteria.)
4. WHERE — Location of Each Artifact
Artifact | Location | Format |
PRD | Project drive (Google Docs) | Markdown or Doc |
TRD | Project drive, then committed to repo as docs/TRD.md | Markdown |
Spec files | Repo under docs/specs/stage-N/spec-name.md | Markdown |
Repo root or docs/ | Markdown | |
Tracking Doc | External tool (Plutio) | Per-tool |
Design tokens / system | Figma + repo (tokens.json or Tailwind config) | Per-tool |
Rule: Specs do not embed pixel-level styling. They reference the design system. If a token doesn't exist, the spec logs it as a designer dependency rather than absorbing the hex code.
5. WHEN — Triggers and Cadence
5.1 When to Use SDD (and to What Depth)
The PM decides at kickoff and writes the decision into the tracking doc as a one-liner:
Project Profile | PRD | TRD | Specs | Stages |
Small — single-screen tool, internal demo, MVP landing page | Yes | Yes | Yes | Single stage |
Medium — multi-screen app, standard CRUD, no complex calculations | Yes | Yes | Yes | 2–4 stages |
Large — many roles, calculations, integrations, regulatory considerations | Yes | Yes | Yes for every flow | Many, sequenced |
Existing project mid-flight | n/a | Don't retrofit | Add specs only for new work | n/a |
Test for whether a TRD is justified: "explicitly you have to tell the AI like these plus this minus this divided into is what should give the result".
5.2 Cadence and Ceremonies
Sprint length: 1 week baseline;
Kickoff (once): decide artifact set, set up tracking doc.
Sprint planning (weekly): PM, Eng Lead, devs — what ships this week.
Sprint review (weekly): demo, status update, QA handoff.
Cross-project team retro: every 2 weeks.
Buffer: +20% on sprint estimates for projects with significant external integrations.
5.3 Status Lifecycle of a Spec
Draft → Ready → In Progress → Done (or Blocked). A spec moves to Ready only after QA confirms acceptance criteria are testable and the Eng Lead has reviewed the data/permissions sections.
6. Operational Rules (Non-Negotiables)
These rules apply to every project using SDD:
PMs draft specs in Claude on the web, never in Claude Code. Specs are documentation, reviewed and committed as Markdown.
No spec is AI-generated and immediately fed back to AI without a human review. PM (and Eng Lead for technical sections) reads every line.
Claude Code consumes specs via implementation.md, not via copy-pasted prompts. The repo is the context.
Tool choice is per-project, decided by the Engineering Lead at kickoff and written into the tracking doc.
No silent gaps in the TRD. Every TBD has an explicit Open Question with an owner and due date.
No retroactive artifact changes. If a project escalates, add the missing artifact going forward — never backfill.
7. PM "One-Stop-Shop" Checklist (Pinned to Every Tracking Doc)
Per sprint (weekly): sprint planning held, sprint review held, tracking doc updated, client check-in if scheduled, async client comms sent.
Per stage: stage demo to client, QA pass on previous stage before next starts, implementation.md status updated.
Per project (recurring): mid-project and end-of-project customer success micro-surveys, bi-weekly team review, Apple Dev account check if shipping to App Store.
Per project (one-time): PRD signed off, TRD signed off (if applicable), tech stack written into implementation.md, stages defined, tracking doc set up with stages and specs.