Cycle step 3 · /sdd spec

SPEC — the living specification

The SPEC bridges business intent and concrete implementation by AI agents. It is the agent's work instruction for a given feature — and the framework's best-ROI investment: a quality SPEC lets an agent generate more than 80% of the correct code on the first pass.

Spec as Living Invariant

SDD Mode's first founding principle positions the SPEC as a living invariant: it is not a transient document — it remains the source of truth between human intent and agent code, before, during and after implementation. Three stances exist in the spec-driven ecosystem:

The argument is not merely documentary: a session anchored on a SPEC consumes on average 41.7% fewer tokens than a session without a specification (R2Code, arXiv 2026). The SPEC is a stable anchor point against context rot.

The sections of a SPEC

An AIAD SPEC is standardized. It contains twelve core sections:

1. the activation scope — injected alone (default) or combined with other SPECs (cross-cutting features);
2. the context — reference to the parent Intent Statement, objective, expected outcome;
3. the scope — explicit in scope and out of scope;
4. the impacted files — to create or modify, exhaustive list;
5. the technical interface — endpoints, types, database schemas;
6. the detailed behaviour — nominal flow and edge cases (at least 3 explicit edge cases);
7. the validation rules — with schemas;
8. the business rules to apply;
9. the expected tests — scenarios to implement;
10. the usage examples — concrete, request/response;
11. the Definition of Done (DoOD) — the "Done" criteria;
12. the Drift Criterion — the concrete rule for detecting that the SPEC has become obsolete.

**Drift Criterion**: this SPEC is in drift if the file
`auth/validator.ts` is modified without updating the
Technical Interface section.

Two sections to frame the agent (doctrine v1.9)

Doctrine v1.9 adds two sections, referred to by their label. They translate into the SPEC what the human actually delegates to the agent — see Agent autonomy.

A SPEC must not grow heavier with a field filled in out of ritual: outside the intended cases, the "Agent execution scope" section fits in two words. The harness permission mode does not appear in it as a containment measure — a permission mode is not a control.

The four quality criteria

These four criteria feed directly into the Spec Quality Score evaluated at /sdd gate. A SPEC that does not satisfy them must never be handed to an agent. Beyond 200 lines, the SPEC is too large: head for /sdd split.

The EARS variant (v1.11) — the anti-ambiguity option

Since v1.11, acceptance criteria can be written in the EARS format (Easy Approach to Requirements Syntax) via /sdd spec --ears. The SPEC is then based on the .aiad/specs/spec-ears-template.md template and declares Format : EARS in its header — that signal is what activates the strict ears-validator linter at the Gate. Each criterion follows one of five patterns:

Ubiquitous          The <system> SHALL <response>.
Event-driven        WHEN <trigger>, the <system> SHALL <response>.
State-driven        WHILE <state>, the <system> SHALL <response>.
Optional feature    WHERE <feature>, the <system> SHALL <response>.
Unwanted behaviour  IF <condition>, THEN the <system> SHALL <response>.

The linter applies rules R1–R7: forbidden words (should, might, fast, user-friendly, intuitive…), a single SHALL per criterion, an explicit trigger (WHEN/WHILE/IF/WHERE), an explicit subject, an observable verb (return, log, reject — never understand), numeric quantification ("within 200ms p95", not "quickly") and no compound conjunctions.

EARS remains optional: the prose and EARS formats coexist, and no migration is imposed. Reserve it for SPECs where ambiguity would be costly: security, payments, regulatory compliance, public API contracts. The trade-off: roughly +30% verbosity and a learning curve.

The REASONS Canvas option (SPDD)

When the parent Intent is complex or ambiguous, /sdd spec offers the REASONS Canvas — Kevlin Henney's SPDD tool — as a framing step: it structures the justification of the intent before switching to the standard AIAD SPEC format. The two approaches are compatible: the Canvas enriches the WHY, it does not replace the SPEC format.

Splitting with /sdd split

When the Gate fails on atomicity, when the SPEC exceeds 200 lines, when the agent needs more than two re-prompts or when the context budget explodes, you split. Three patterns guide the split:

Each sub-SPEC must be able to pass the Gate independently, and the sub-SPECs together must cover 100% of the parent. When the split yields several SPECs, /sdd spec produces a parallelism plan (waves and a dependency graph) validated by the PE before writing begins.