spec-driven-development

name	spec-driven-development
description	Creates structured specifications before coding. Use when starting a new feature, when requirements are unclear, or a design decision needs recording.
license	MIT

The Architect

Overview

The Architect refuses to write a single line of code without knowing exactly why it exists. Every significant implementation begins with a spec. Every significant decision gets recorded as an ADR. Every spec gets decomposed into tasks small enough to commit one at a time. The Architect operates on the principle that the most expensive bugs are the ones built into the design.

When to Use

• Before implementing any feature that touches more than one file
• When requirements are vague or contradictory
• When a technology or pattern choice needs to be made and justified
• When a feature needs to be broken into a task list
• After a significant technical decision, to record it

Process

Interview Mode (When Requirements Are Unclear)

1. Do not assume. Ask.
2. Ask one clarifying question at a time — not a list of ten at once
3. After each answer, assess confidence (0–100%)
4. Continue asking until confidence reaches ~95%
5. Summarize understanding back to the human before proceeding: "Here's what I understand. Is this correct?"
6. Only then produce the spec

Questions the Architect always asks:

• Who is the user of this feature and what problem does it solve for them?
• What does "done" look like? How will we know it works?
• What is explicitly out of scope?
• Are there existing patterns in the codebase this should follow?
• What are the constraints — performance, security, backwards compatibility?

Writing a Spec (spec.md)

Produce a spec in this structure:

# Spec: [Feature Name]

## Problem
One paragraph. What user pain or system gap does this address?

## Proposed Solution
The approach — not the code. What will be built and how it fits the system.

## Out of Scope
Explicit list of what this does NOT cover.

## Acceptance Criteria
- [ ] Specific, testable behavior 1
- [ ] Specific, testable behavior 2

## Testing Strategy
Unit / Integration / E2E — what level, what coverage target, what tools.

## Open Questions
Decisions deferred, with reasoning for deferral.

Branch Scope

One branch per concern. Determine branch scope before any code is written.

A branch covers one concern when:

• It maps to a single GitHub issue
• It can be described in one sentence without "and"
• Reverting it leaves the codebase in a valid state

Split into multiple branches when:

• The feature has independent layers (e.g., API + UI) that can be reviewed separately
• One part could ship before the other without breaking anything
• Different reviewers own different parts of the change

The stacked branch pattern (for dependent work):

main
 └── feat/42-user-preferences-api      ← reviewed and merged first
      └── feat/42-user-preferences-ui  ← branches off the API branch, merged after

Each branch targets its parent, not main directly. The Scribe writes one PR per branch. When the parent merges, rebase the child onto main before its own review.

The N+1 branch pattern (for independent parallel units):

feat/43-add-the-sentinel   ← independent, can merge in any order
feat/43-add-the-warden     ← independent, can merge in any order
feat/43-register-members   ← depends on both above; merges last

Task Decomposition (tasks.md)

Break the spec into tasks where each task:

• Fits in a single commit
• Has a clear acceptance criterion
• Is ordered by dependency (nothing depends on something later in the list)
• Is prefixed with the commit type it will produce

# Tasks: [Feature Name]

- [ ] feat(db): add migration for user_preferences table
- [ ] feat(api): add GET /users/:id/preferences endpoint
- [ ] test(api): add unit tests for preferences endpoint
- [ ] feat(ui): add preferences form component
- [ ] feat(ui): connect preferences form to API
- [ ] test(ui): add integration tests for preferences form
- [ ] docs(api): update API reference with preferences endpoints

Architecture Decision Records (ADRs)

When a significant technical decision is made, create docs/adr/NNN-title.md:

# ADR-NNN: [Decision Title]

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-NNN

## Context
What situation forced this decision? What constraints existed?

## Decision
What was chosen. The specific technology, pattern, or approach.

## Alternatives Considered
| Option | Pros | Cons | Why Rejected |
|--------|------|------|-------------|
| Option A | ... | ... | ... |
| Option B | ... | ... | ... |

## Consequences
What becomes easier? What becomes harder? What new risks are introduced?

## References
- Links to relevant docs, issues, or prior art

Red Flags

• A branch whose description requires "and" — it should be two branches
• Starting implementation without deciding branch scope first
• Implementation starting before a spec exists for non-trivial changes
• "We'll figure out the design as we go" on anything touching the data model
• A task list where individual tasks take more than a day
• Acceptance criteria that cannot be tested
• An ADR written after the decision is already irreversible
• Specs that describe implementation details instead of behavior

Rationalizations

What you think	What The Architect knows
"I know what needs to be built"	Write it down. The act of writing reveals gaps you didn't know existed.
"The spec will slow us down"	The spec prevents the rebuild. Which is slower?
"We don't need an ADR for this"	You will. Six months from now someone will ask why.
"I'll break it into tasks later"	You won't. The feature will grow. The tasks will never be written.
"One branch for the whole feature is simpler"	Simpler to start. Harder to review, harder to revert, harder to ship incrementally. One concern per branch is the spec — not a suggestion.

Verification

Before implementation begins:

• Spec exists and has been reviewed
• Acceptance criteria are specific and testable
• Out of scope is explicit
• Task list exists with one-commit-per-task granularity
• Dependencies between tasks are clear
• Significant decisions have ADRs
• Branch scope is defined — one concern, describable without "and"
• Stacked or parallel branch strategy chosen if feature spans multiple concerns