Spec-Driven Development

Structured development workflow with adaptive depth. Right ceremony for the right scope.

Workflow

specify --> plan* --> tasks* --> execute ^___________________________| (verify after each task)

Adaptive pipeline: Specify and Execute always run; Plan and Tasks auto-skip when scope is small enough. Verification is continuous throughout Execute.

Context Loading Strategy

Base load (~15k tokens):

• .agents/project.md (context, if exists)

• .artifacts/state.md (persistent memory)

• Current feature spec.md

On-demand:

• .agents/codebase/*.md (brownfield)

• decisions.md (designing or executing from user decisions)

• plan.md (executing)

• tasks.md (executing)

• research/*.md (new technologies)

Never simultaneous:

• Multiple feature specs

• Multiple codebase docs

Target: <40k tokens total context Reserve: 160k+ tokens for work, reasoning, outputs

Triggers

Feature-Level (auto-sized)

Trigger Pattern Reference

Create new feature, specify feature specify.md

Modify feature, improve feature specify.md (brownfield)

Discuss feature, capture context, how should this work discuss.md

Create technical plan plan.md

Research technology, cache research research.md

Create tasks tasks.md

Execute task, implement task execute.md

Validate, UAT, verify work validate.md (within Execute)

Quick fix, quick task, small change, bug fix quick-mode.md

List features, show status status-specs.md

Project-Level

Trigger Pattern Reference

Record decision, log blocker, add deferred idea state-management.md

Guidelines

Trigger Pattern Reference

How to write specs spec-writing.md

How to decompose tasks tasks.md

Codebase exploration codebase-exploration.md

Research patterns research.md

Baseline discovery baseline-discovery.md

Extract from PRD/docs doc-extraction.md

Coding principles coding-principles.md

Status workflow, when to update status status-workflow.md

Cross-References

specify.md -------> discuss.md (when gray areas detected) specify.md -------> quick-mode.md (when Small scope) specify.md -------> plan.md (when Large/Complex, spec complete) specify.md -------> execute.md (when Medium, skip plan/tasks) plan.md ----------> tasks.md (when Large/Complex) plan.md ----------> research.md (if new tech) tasks.md ---------> execute.md execute.md -------> coding-principles.md (loaded before coding) execute.md -------> validate.md (interactive UAT, Complex scope) execute.md -------> tasks.md (safety valve: >5 inline steps)

Auto-Sizing

Complexity determines depth, not a fixed pipeline. Before starting any feature, assess its scope and apply only what's needed:

Scope What Specify Plan Tasks Execute

Small ≤3 files, one sentence Quick mode -- skip pipeline entirely

Medium Clear feature, <10 tasks Spec (brief) Skip -- explore inline Skip -- steps implicit Implement + verify per step

Large Multi-component feature Full spec + requirement IDs Full plan Full breakdown + dependencies Implement + verify per task

Complex Ambiguity, new domain Full spec + discuss gray areas Research + full plan Breakdown + parallel plan Implement + verify per task + interactive UAT

Rules:

• Specify and Execute are always required -- you always need to know WHAT and DO it

• Plan is skipped when the change is straightforward (no architectural decisions, no new patterns)

• Tasks is skipped when there are ≤3 obvious steps (they become implicit in Execute)

• Discuss is triggered within Specify only when the agent detects ambiguous gray areas that need user input

• Interactive UAT is triggered within Execute only for Complex scope with user-facing features

• Quick mode is the express lane -- for bug fixes, config changes, and small tweaks

• Verification is continuous -- quality gates and acceptance criteria run after each task or range, never deferred to the end

Safety valve: Even when Tasks is skipped, Execute ALWAYS starts by listing atomic steps inline (see execute.md). If that listing reveals >5 steps or complex dependencies, STOP and create a formal tasks.md -- the Tasks phase was wrongly skipped.

Project Structure

.artifacts/ ├── state.md # Decisions, blockers, lessons, deferred ideas (persistent) ├── features/ │ └── {ID}-{name}/ │ ├── spec.md # WHAT: Requirements (always created) │ ├── decisions.md # WHY: Decisions on gray areas (only when discuss triggered) │ ├── plan.md # HOW: Architecture (only for Large/Complex) │ ├── tasks.md # WHEN: Tasks (only for Large/Complex) │ └── designs/ # Visual references (optional) ├── quick/ # Quick mode tasks │ └── NNN-{slug}/ │ └── task.md └── research/ # Research cache (reusable across features) └── {topic}.md

Project context (generated by project-index skill):

.agents/ ├── project.md # Project context └── codebase/ # Codebase analysis

Note: .agents/ is generated by the project-index skill. If it exists, spec-driven uses and updates it. If not, Specify suggests running project-index for better context (especially for brownfield projects). All feature artifacts stay within .artifacts/ .

Templates

Context Template

Feature spec spec.md

Discuss context decisions.md

Technical plan plan.md

Task breakdown tasks.md

Project state state.md

Quick task quick-task.md

Codebase exploration exploration.md

Research cache research.md

Knowledge Verification Chain

When researching, designing, or making any technical decision, follow this chain in strict order. Never skip steps.

Step 1: Codebase -> check existing code, conventions, and patterns already in use Step 2: Project docs -> README, docs/, inline comments, .agents/codebase/ Step 3: Context7 MCP -> resolve library ID, then query for current API/patterns Step 4: Web search -> official docs, reputable sources, community patterns Step 5: Flag uncertain -> "I'm not certain about X -- here's my reasoning, but verify"

Rules:

• Never skip to Step 5 if Steps 1-4 are available

• Step 5 is ALWAYS flagged as uncertain -- never presented as fact

• NEVER assume or fabricate. If you cannot find an answer, say "I don't know" or "I couldn't find documentation for this". Inventing APIs, patterns, or behaviors causes cascading failures across plan -> tasks -> implementation. Uncertainty is always preferable to fabrication.

Guidelines

DO:

• Separate content by purpose: spec=WHAT, plan=HOW, tasks=WHEN

• Follow status flow: draft -> ready -> in-progress -> done

• Use sequential Feature IDs (001, 002)

• Reuse research cache across features (.artifacts/research/)

• Consume .agents/ for project context and codebase info (optional -- use if exists)

• Update .agents/codebase/ with new discoveries during plan phase (if it exists)

• Update .artifacts/state.md with decisions and blockers as they arise

• Auto-size depth based on complexity -- skip phases that add no value

• Verify continuously during Execute -- after each task or range, not as a separate phase

DON'T:

• Reuse Feature IDs from previous features

• Mix spec, plan, and task content in a single file

• Skip status transitions (e.g., jumping from draft to done)

• Create feature-specific research files outside .artifacts/research/

• Generate .agents/ content (that's project-index's responsibility)

• Force full pipeline on small/medium changes -- respect auto-sizing

• Assume or fabricate when information is unavailable -- follow Knowledge Verification Chain

• Defer all verification to the end -- verify per task/range during Execute

Error Handling

• No .artifacts/: Create it (features/ and research/ are created on demand)

• Spec not found: List available features

• Open questions blocking architecture: Resolve before planning (trigger discuss)

• Plan not found: Suggest plan before tasks (or skip if Medium scope)

• Tasks not found: Suggest tasks before execute (or skip if Medium scope)

• Scope misjudged: Safety valve catches it -- redirect to appropriate phase