Router /sdd <sub>

/sdd — the 17 cycle commands

The /sdd router groups every command of the Spec Driven Development cycle: from initial framing to the audits, through the Intent Statement, the Research phase, the SPEC, the Execution Gate and the Drift Lock.

The routers (aiad-sdd 1.7)

Since aiad-sdd 1.7, the framework's commands — 33 today: 17 /sdd and 16 /aiad — are grouped into 3 routers — /sdd, /aiad and /aiad-help — to reduce the cold-start weight of the system prompt (−94% of frontmatter loaded once the backward-compatible aliases are removed). The subcommand bodies are stored in .claude/sdd/ and .claude/aiad/, loaded only on demand by the router via Read: only the content of the invoked command occupies the context.

Dual-mode: --guided / --fast

Each command accepts two execution modes, plus auto-detection:

Overview

/sdd init — initial framing

When. At project start, right after npx aiad-sdd init.

What it does. First displays the restart message (reload the freshly installed commands in session), then guides the writing of the 3 foundational artifacts. For the PRD and the ARCHITECTURE, the command offers two paths: delegate to the /sdd prd and /sdd arch assistants, or fill in the templates manually. Skill invoked: human-authorship-check — the PRD's "WHYs" belong to the human.

Output. PRD.md, ARCHITECTURE.md and AGENT-GUIDE.md completed, ready to be committed into .aiad/.

/sdd prd — PRD assistant

When. To fill in .aiad/PRD.md with a structured product discovery.

What it does. The agent plays an experienced PM: 7 guided steps (problem, personas, North Star, Outcome Criteria with baseline → target, v1 scope, risks, v2 roadmap) or, on the fast path, 6 questions asked in a single block. The PRD never contains any technical "how". Skill invoked: human-authorship-check.

Output. A complete .aiad/PRD.md + validation summary (North Star, personas, top 3 criteria).

/sdd arch — ARCHITECTURE assistant

When. Once the PRD is filled in — a prerequisite the command verifies.

What it does. The agent plays an architect: quantified NFRs (p95, availability, RPS), a stack justified by the PRD, component breakdown, an ASCII diagram of the real request path, security, principles and ADRs. Systematically generates the condensed summary ≤ 500 tokens intended for the Context Engineering Budget.

Output. A complete .aiad/ARCHITECTURE.md + ADRs in .aiad/adrs/ where applicable.

/sdd intent — intent capture

When. Before writing a SPEC, for each user story to implement.

What it does. Guides the writing of the 5 fields (WHY NOW, FOR WHOM, OBJECTIVE, CONSTRAINTS, DRIFT CRITERION), verifies human authorship via the human-authorship-check skill (on FAIL, the file is not created), then materialises the cycle as a crash-recoverable graph (npx aiad-sdd cycle init INTENT-NNN). It may return a JNSP verdict ("Je Ne Sais Pas" — I don't know) if the intent is not mature — that is a valid result.

Output. .aiad/intents/INTENT-NNN-[name].md + update of _index.md.

/sdd research — GO/NO-GO gate

When. Between the Intent and the SPEC, to assess the viability of the intent as seen from the real code.

What it does. Launches a mandatory Discovery (read-only Explore agent) that anchors every finding in the code (path:line — without anchoring, the verdict stays JNSP), synthesises feasibility and risks, then has the human decide: GO | CONDITIONAL GO | DEFER | NO-GO. The verdict is hardened by the deterministic scorer npx aiad-sdd research (exit 0/1/2). Skills invoked: human-authorship-check, regulatory-veto, grill-me (in --guided).

Output. .aiad/research/RESEARCH-NNN-<slug>.md + machine verdict. DEFER/NO-GO close the door to /sdd spec.

/sdd spec — SPEC writing

When. Once the Intent is validated and the Research is at GO / CONDITIONAL GO (Discovery prerequisite verified — an explicit bypass is allowed for a trivial intent, traced in the SPEC).

What it does. Decomposes into atomic tasks (1 SPEC = 1 PR), displays a wave-based parallelism plan as soon as 2 or more SPECs are identified, then writes each SPEC in the full format (behaviour, edge cases, criteria, interface, context budget, DoOD). The --ears flag enables the EARS variant (aiad-sdd 1.11) and the strict linter. Skills invoked: reasons-canvas (optional when the Intent is complex), ears-validator (strict in EARS, advisory in prose).

Doctrine v1.9 adds two named sections: "Agent stop points" (optional: when the agent comes back to the human — approval, expert opinion, plurality of viewpoints, witness) and "Agent execution perimeter" (required if the SPEC involves credentials or write access to a shared resource, "Not applicable" otherwise). Next release — upcoming: both sections built into the package's prose and EARS templates, and an "Inherited context at the fork point" line in the context budget estimate. See Agent autonomy.

Output. SPEC-NNN-[name].md file(s) in .aiad/specs/ + update of the indexes and of the parent Intent.

/sdd gate — Execution Gate

When. Before launching any coding agent, to validate the SPEC.

What it does. Scores the 5 SQS criteria + the Stranger Test. As soon as an action is irreversible or the agent holds credentials, the Gate also checks the ceilings, the stop threshold and the execution perimeter. SQS ≥ 4/5 → Gate OPEN and preparation of the Context Engineering Budget; otherwise a remediation plan. If the SPEC declares Format : EARS: 0 violations → +1 bonus on Testability; ≥ 1 violation → criterion 2 forced to 0. A criterion that cannot be scored produces an UNKNOWN Gate (JNSP verdict, fail-closed). Skills invoked: sqs-scoring, ears-validator, grill-me (in --guided).

Next release — upcoming. Before any SQS scoring, the command runs the deterministic pre-check npx aiad-sdd gate-precheck <SPEC>, which reads the "Agent execution perimeter" section outside the model: PASS (exit 0) → carry on; FAIL (exit 1 — irreversible action without a stop threshold, credentials or shared resources without declared isolation or network egress) → Gate CLOSED without scoring; JNSP (exit 2 — SPEC not found or incomplete table) → Gate UNKNOWN. See CLI — gate-precheck.

Output. SQS score + decision OPEN / OPEN with reservation / CLOSED / UNKNOWN + remediation plan if closed.

/sdd exec — agent execution launch

When. Gate open, SPEC in ready status, context prepared.

What it does. Verifies the prerequisites (SPEC ready, SQS ≥ 4/5, active Intent, Discovery, dependencies), assembles the minimal context (condensed AGENT-GUIDE + summarised ARCHITECTURE + active SPEC), checks the budget (< ≈ 50K tokens — an assumed, unsourced sobriety heuristic), qualifies governance, then slices the execution into testable vertical slices validated by mini-gates (npx aiad-sdd mini-gate). The prompt includes the JNSP contract (TODO-JNSP: rather than inventing). Skills invoked: sqs-scoring, context-budget, regulatory-veto (a VETO prevents the launch).

Output. Assembled agent prompt + phased plan .aiad/exec/EXEC-<SPEC>-plan.md + SPEC status → in-progress, then conformant code + tests.

/sdd resume — session resumption

When. Agent session interrupted (timeout, error, context limit, deliberate choice).

What it does. Rebuilds a context lighter than the initial one: reads the real state of the cycle (npx aiad-sdd cycle next) and of the phased plan (npx aiad-sdd exec-status), inventories the work done via git, then formulates a minimal resumption prompt. If the state cannot be reconstructed 100%, the verdict is JNSP — never a blind relaunch. Skills invoked: context-budget, drift-detection.

Output. Structured state summary + a new operational session resuming at the exact step.

/sdd split — SPEC splitting

When. Oversized SPEC (> 200 lines), atomicity failure at the Gate, > 2 agent relaunches or budget > ≈ 50K tokens (an assumed, unsourced sobriety heuristic).

What it does. Proposes a splitting pattern — by technical layer, by use case (happy path / edge cases / errors), by dependency or by business domain — then pre-validates each sub-SPEC with the sqs-scoring skill: each must be able to pass the Gate independently. Beyond 5 sub-SPECs, the Intent is too ambitious → back to /sdd intent.

Output. 2 to N sub-SPECs with explicit dependencies and execution order, parent SPEC in split status.

/sdd context — context budget audit

When. After an agent session, to close the Context Engineering Budget feedback loop.

What it does. Compares the SPEC §6 estimate with the context actually injected, then applies the context-budget skill: 5 health metrics M1–M5 (useful rate, relaunches, ratio, consistency, duration) and a 0–5/5 score. Context rot (M4 + M5) is the most dangerous signal: it degrades silently. Since aiad-sdd 1.19.0, the SPEC's measured footprint (npx aiad-sdd footprint <SPEC>) is displayed next to the estimate.

Next release — upcoming. The audit counts the inherited context at fork points: when a sub-agent inherits the parent conversation, its delegation costs the parent context at the time of the fork on top of its own work. An "Inherited context (delegations)" line is added to the estimate / actual table, and a diagnostic flags late delegations (inherited context > 50% of the total): delegate earlier in the session.

Output. Audit report with recommendations + update of SPEC §6 and of the Lessons / Human Learnings if a pattern is detected.

/sdd validate — agent code validation

When. At the end of each implementation session, before the Drift Lock.

What it does. Triple validation: technical (lint, types, tests, build), functional (every §3 criterion checked against the code), governance (Tier 1 agents). Also verifies the Drift Criterion of the parent Intent, and optionally offers a --cross-model review by a third-party model in a fresh context (additive-only). Composed skills: ears-validator + drift-detection + regulatory-veto. A Tier 1 UNKNOWN counts as a VETO (fail-closed); unresolved TODO-JNSP: markers produce a JNSP verdict ("Je Ne Sais Pas" — I don't know).

Output. Verdict VALIDATED / MINOR FIXES / FAILED / JNSP with an actionable report.

/sdd drift-check — Anti-Drift Check

When. Before every PR, and as an end-of-iteration ritual.

What it does. Combines two checks since aiad-sdd 1.10: the git heuristic (drift-detection skill — code modified without the SPEC updated in the same PR) and the machine-verifiable measurement (traceability skill, via npx aiad-sdd trace --fail-on-gap). Missing @spec annotations yield an UNKNOWN verdict — never OK by default, and treated as a DRIFT by the hooks and the CI.

Output. Verdict OK / DRIFT / UNKNOWN + proposed updates + a CHANGELOG-ARTEFACTS.md entry. Never merge in a drift state.

/sdd trace — traceability matrix

When. To measure the Intent ↔ SPEC ↔ Code ↔ Tests chain, on demand or in CI.

What it does. Scans the @intent / @spec / @verified-by / @governance annotations, cross-references them with .aiad/intents/ and .aiad/specs/, and produces the Forward and Backward matrices. Gaps are classified (orphans, validated SPECs without code — blocking; untraced code, code without tests) with a remediation plan. Skill invoked: traceability.

Output. Snapshots .aiad/metrics/traceability/trace.{md,json,html} + verdict OK / GAP.

/sdd fact — technical fact capture

When. A gap is observed between delivered and desired behaviour, without justifying a full Intent cycle (minor bug, unexpected behaviour, partial drift).

What it does. Captures the precise gap (delivered vs desired), qualifies the impact (functional / security / performance / spec conformance) and decides the action among four options: immediate patch, new Intent, SPEC adjustment, or documented technical debt. Skills invoked: drift-detection, regulatory-veto if there is a security/compliance dimension.

Output. .aiad/facts/FACT-NNN.md with a traced decision and a link to the affected SPEC.

/sdd security — security audit

When. After any implementation involving access controls, user data, secrets or an AI component — recommended before any critical PR.

What it does. Audit across 4 axes: OWASP Top 10 (including prompt injection), secret management, agent permissions (Harness Engineering — minimal necessary permissions) and regulatory compliance via the regulatory-veto skill. An unclassifiable pattern exits as JNSP and is treated as a risk (fail-closed) — never "safe" through absence of evidence.

Output. Structured report (critical risks / medium risks / good practices / JNSP zones) persisted in .aiad/metrics/security/YYYY-MM-DD-SPEC-NNN.md.

/sdd audit — quality audit

When. Before or during validation, especially for features with high technical stakes or after several iterations on the same component.

What it does. Covers 4 dimensions: code ↔ SPEC conformance criterion by criterion, code quality (complexity, coupling, readability), technical debt (deliberate / accidental / bit rot), consistency with the AGENT-GUIDE conventions. Any detected drift triggers a SPEC update proposal (Drift Lock). Skills invoked: drift-detection, ears-validator.

Output. Report persisted in .aiad/metrics/audit/YYYY-MM-DD-SPEC-NNN.md with BLOCKING / IMPORTANT / SUGGESTION recommendations.