spec-driven-development

Spec-Driven Development

For terminology and concepts, see docs/concepts.md.

spectl CLI

How to run: python3 scripts/spectl.py.

How This Works

Specs describe the system's behavior as a contract: what the system does (requirements) and how it behaves (scenarios). They live in specs/reference/, organized by capability. That's the source of truth.

When something needs to change, you create a change -- a folder under specs/changes/ with artifacts that capture the intent, the behavioral modifications, and optionally the technical approach and implementation plan.

The proposal (proposal.md) is always the entry point. It answers why this change exists and names the capabilities affected. From there, artifacts can develop in the order that makes sense:

• Spec Deltas (deltas/*/spec.md) -- behavioral changes per capability (ADDED/MODIFIED/REMOVED/RENAMED requirements)
• Design (design.md) -- technical approach, when the how isn't obvious
• Tasks (tasks.md) -- implementation checklist, when the work has multiple steps

These artifacts aren't just a planning exercise. They make the change reviewable without reading code: the proposal explains why, the deltas show what's changing in the system's behavioral contract, and the design captures architectural decisions.

When implementation is complete and verified, the change is archived: deltas merge into the reference specs, the change moves to changes/archive/, and the reference reflects the new reality.

When to Use SDD

Use it for: any code changes that reflect changed requirements or behavioral expectations.

Skip it for: simple bugfixes, routine refactors, dependency bumps, doc-only changes, exploratory spikes.

File Ownership

File	Owner	Others May Edit
proposal.md	Propose phase	With user confirmation
deltas/*/spec.md	Propose phase	With user confirmation
design.md	Propose phase	With user confirmation
tasks.md	Propose phase	Apply phase (checkboxes only)
notes/*	Any phase	Freely

Changing a spec may invalidate the design. Always warn the user.

Rules

1. Specs are the source of truth. Code serves specs. Never write specs to describe existing code -- that's backwards.
2. specs/ is for specs only. No code files. deltas/ contains only spec.md files. All code goes elsewhere.
3. Don't fabricate. Only document what was discussed or confirmed. No invented assumptions, no invented constraints. If unsure, ask.
4. Prove your work. Never claim "done" without passing tests or user verification. Walk through each requirement and scenario.
5. Mark unknowns with [CLARIFICATION NEEDED] and resolve them before proceeding.

Don't:

• Over-specify (specs guide, they don't pin down every detail)
• Design before scenarios are clear
• Add "might need" features -- only what's explicitly required
• Let specs go stale -- a spec that doesn't match the code is worse than no spec

Commands

Each command maps to a phase. Only read the reference doc for your current phase.

Command	What it does	Reference
/explore [topic]	Investigate before committing to a proposal	references/explore.md
/propose [description]	Create a change and its artifacts	references/propose.md
/refine [instruction]	Update an existing artifact	Route to artifact reference below
/apply [slug]	Implement and verify a change	references/apply.md
/archive [slug]	Merge deltas into reference, archive the change	references/archive.md

Artifact References

When writing or refining an artifact, read its reference and use its template:

Artifact	Reference	Template
proposal.md	references/propose.md	templates/proposal.md
deltas/*/spec.md	references/spec.md	templates/spec-delta.md
design.md	references/design.md	templates/design.md
tasks.md	references/tasks.md	templates/tasks.md

Refine Routing

/refine determines which artifact to update from the instruction:

• Context, motivation, scope → proposal.md
• Requirements, scenarios, behavior → relevant spec.md in deltas/
• Architecture, technical decisions → design.md
• Task breakdown, progress → tasks.md

If unclear, ask the user.

Directory Structure

specs/
├── reference/                        # Source of truth
│   ├── authentication/
│   │   └── spec.md
│   └── billing/
│       └── spec.md
└── changes/
    ├── archive/                      # Completed changes
    │   └── 2026-03-01-initial-auth/
    └── add-oauth/                    # Active change
        ├── proposal.md               # Why (intent, scope, capabilities)
        ├── deltas/                   # What (per-capability behavioral changes)
        │   ├── session-management/
        │   │   └── spec.md
        │   └── user-auth/
        │       └── spec.md
        ├── design.md                 # How (optional)
        ├── tasks.md                  # Steps (optional)
        └── notes/                    # Learnings (optional)

A delta at deltas/user-auth/spec.md targets reference/user-auth/spec.md. Changes are identified by slug -- look for matching slugs in specs/changes/*/.

Monorepo: Each sub-project has its own specs/ directory. spectl discovers them with -r (recursive). Use --dir to target a specific one.

Interactive vs Autonomous

Interactive (default): Ask the user at each phase for input and confirmation (use AskUserQuestion tool).

Autonomous (when user requests it, e.g. "work on this until done"):

1. Propose: Draft all artifacts. Invoke spec-critic (intra-spec after proposal, intra-spec + spec-code after specs + design).
2. Apply: Implement and verify against all requirements and scenarios. Invoke spec-critic (all) before marking complete.
3. Archive: Invoke spec-sync → validate with spec-critic (inter-spec) → move to archive.

Only pause for genuine ambiguities or when the critic can't resolve after 5 rounds.

Iteration

All phases can be revisited. /refine updates any existing artifact.

• Apply snag → may reveal a design flaw, spec gap, or proposal issue
• Changing a spec may invalidate the design -- always warn the user
• Scope changes require user confirmation in interactive mode; in autonomous mode, document in notes/ and proceed

Critique

The spec-critic agent (sonnet) provides adversarial review. See references/critique.md for checklists.

Mode	Checks
intra-spec	Coherence within the spec
spec-code	Alignment with the codebase
inter-spec	Consistency across specs
all	All three

Verdicts: approved | approved-with-reservations | needs-work | blocked

Invocation: "Consult with the spec-critic agent to review [spec path] (critique mode: [mode])"

When needs-work or blocked: Address concerns, resume the agent, repeat. Escalate to user after 5 rounds.

Sub-Agents

Agent	Role	Definition
spec-critic (sonnet)	Adversarial review of specs and implementation	agents/spec-critic.md
spec-sync (sonnet)	Merges deltas into reference specs during archive	agents/spec-sync.md