Router /sdd <sub>

/sdd — les 17 commandes du cycle

Le router /sdd regroupe toutes les commandes du cycle Spec Driven Development : du cadrage initial jusqu'aux audits, en passant par l'Intent Statement, la phase Research, la SPEC, l'Execution Gate et le Drift Lock.

Les routers (aiad-sdd 1.7)

Depuis aiad-sdd 1.7, les commandes du framework — 33 aujourd'hui : 17 /sdd et 16 /aiad — sont regroupées en 3 routers — /sdd, /aiad et /aiad-help — pour réduire le poids du system prompt à froid (−94 % de frontmatter chargé une fois les alias rétro-compatibles retirés). Les corps des sous-commandes sont stockés dans .claude/sdd/ et .claude/aiad/, chargés uniquement à la demande par le router via Read : seul le contenu de la commande invoquée occupe le contexte.

Dual-mode : --guided / --fast

Chaque commande accepte deux modes d'exécution, plus une auto-détection :

Vue d'ensemble

/sdd init — cadrage initial

Quand. Au démarrage d'un projet, juste après npx aiad-sdd init.

Ce que ça fait. Affiche d'abord le message de redémarrage (recharger les commandes fraîchement installées en session), puis guide la rédaction des 3 artefacts fondamentaux. Pour le PRD et l'ARCHITECTURE, la commande propose deux voies : déléguer aux assistants /sdd prd et /sdd arch, ou compléter les templates manuellement. Skill invoquée : human-authorship-check — les « POURQUOI » du PRD appartiennent à l'humain.

Sortie. PRD.md, ARCHITECTURE.md et AGENT-GUIDE.md complétés, prêts à être committés dans .aiad/.

/sdd prd — assistant PRD

Quand. Pour renseigner .aiad/PRD.md avec un discovery produit structuré.

Ce que ça fait. L'agent joue un PM expérimenté : 7 étapes guidées (problème, personas, North Star, Outcome Criteria avec baseline → cible, périmètre v1, risques, roadmap v2) ou, en fast path, 6 questions posées en un seul bloc. Le PRD ne contient jamais de « comment » technique. Skill invoquée : human-authorship-check.

Sortie. .aiad/PRD.md complet + résumé de validation (North Star, personas, top 3 critères).

/sdd arch — assistant ARCHITECTURE

Quand. Une fois le PRD renseigné — c'est un prérequis vérifié par la commande.

Ce que ça fait. L'agent joue un architecte : NFRs chiffrées (p95, disponibilité, RPS), stack justifiée par le PRD, découpage en composants, diagramme ASCII de la request-path réelle, sécurité, principes et ADRs. Génère systématiquement le résumé condensé ≤ 500 tokens destiné au Context Engineering Budget.

Sortie. .aiad/ARCHITECTURE.md complet + ADRs dans .aiad/adrs/ le cas échéant.

/sdd intent — capture d'intention

Quand. Avant de rédiger une SPEC, pour chaque user story à implémenter.

Ce que ça fait. Guide la rédaction des 5 champs (POURQUOI MAINTENANT, POUR QUI, OBJECTIF, CONTRAINTES, CRITÈRE DE DRIFT), vérifie la paternité humaine via la skill human-authorship-check (si FAIL, le fichier n'est pas créé), puis matérialise le cycle en graphe crash-recoverable (npx aiad-sdd cycle init INTENT-NNN). Peut sortir un verdict JNSP si l'intention n'est pas mûre — c'est un résultat valide.

Sortie. .aiad/intents/INTENT-NNN-[nom].md + mise à jour de _index.md.

/sdd research — gate GO/NO-GO

Quand. Entre l'Intent et la SPEC, pour évaluer la viabilité de l'intention vue du code réel.

Ce que ça fait. Lance un Discovery obligatoire (agent Explore read-only) qui ancre chaque constat dans le code (chemin:ligne — sans ancrage, le verdict reste JNSP), synthétise faisabilité et risques, puis fait trancher l'humain : GO | CONDITIONAL GO | DEFER | NO-GO. Le verdict est durci par le scorer déterministe npx aiad-sdd research (exit 0/1/2). Skills invoquées : human-authorship-check, regulatory-veto, grill-me (en --guided).

Sortie. .aiad/research/RESEARCH-NNN-<slug>.md + verdict machine. DEFER/NO-GO ferment la porte de /sdd spec.

/sdd spec — rédaction de SPEC

Quand. Une fois l'Intent validé et la Research en GO / CONDITIONAL GO (prérequis Discovery vérifié — court-circuit explicite admis pour une intention triviale, tracé dans la SPEC).

Ce que ça fait. Décompose en tâches atomiques (1 SPEC = 1 PR), affiche un plan de parallélisme en waves dès que 2 SPECs ou plus sont identifiées, puis rédige chaque SPEC au format complet (comportement, cas limites, critères, interface, budget contexte, DoOD). Le flag --ears active la variante EARS (aiad-sdd 1.11) et le linter strict. Skills invoquées : reasons-canvas (option si l'Intent est complexe), ears-validator (strict en EARS, indicatif en prose).

La doctrine v1.9 ajoute deux sections nommées : « Points d'arrêt de l'agent » (facultative : quand l'agent revient vers l'humain — approbation, avis d'expert, pluralité de points de vue, témoin) et « Périmètre d'exécution de l'agent » (requise si la SPEC implique des credentials ou un accès en écriture à une ressource partagée, « Non applicable » sinon). Prochaine version — à paraître : ces deux sections intégrées aux gabarits prose et EARS du paquet, et une ligne « Contexte hérité au point de fork » dans l'estimation du budget de contexte.

Sortie. Fichier(s) SPEC-NNN-[nom].md dans .aiad/specs/ + mise à jour des index et de l'Intent parent.

/sdd gate — Execution Gate

Quand. Avant tout lancement d'agent de code, pour valider la SPEC.

Ce que ça fait. Score les 5 critères SQS + le Test de l'Étranger. Dès qu'une action est irréversible ou que l'agent dispose de credentials, la Gate vérifie aussi plafonds, seuil d'arrêt et périmètre d'exécution. SQS ≥ 4/5 → Gate OUVERTE et préparation du Context Engineering Budget ; sinon plan de remédiation. Si la SPEC déclare Format : EARS : 0 violation → bonus +1 sur la Testabilité ; ≥ 1 violation → critère 2 forcé à 0. Un critère non scorable produit une Gate INCONNUE (verdict JNSP, fail-closed). Skills invoquées : sqs-scoring, ears-validator, grill-me (en --guided).

Prochaine version — à paraître. Avant tout scoring SQS, la commande lance le pré-contrôle déterministe npx aiad-sdd gate-precheck <SPEC>, qui lit la section « Périmètre d'exécution de l'agent » hors modèle : PASS (exit 0) → on poursuit ; FAIL (exit 1 — action irréversible sans seuil d'arrêt, credentials ou ressources partagées sans isolation ni sorties réseau déclarées) → Gate FERMÉE sans scoring ; JNSP (exit 2 — SPEC introuvable ou tableau incomplet) → Gate INCONNUE. Voir CLI — gate-precheck.

Sortie. Score SQS + décision OUVERTE / OUVERTE avec réserve / FERMÉE / INCONNUE + plan de remédiation si fermée.

/sdd exec — lancement d'exécution agent

Quand. Gate ouverte, SPEC en statut ready, contexte préparé.

Ce que ça fait. Vérifie les prérequis (SPEC ready, SQS ≥ 4/5, Intent actif, Discovery, dépendances), assemble le contexte minimal (AGENT-GUIDE condensé + ARCHITECTURE résumée + SPEC active), vérifie le budget (< ≈ 50K tokens — heuristique de sobriété assumée, non sourcée), qualifie la gouvernance, puis découpe l'exécution en tranches verticales testables validées par mini-gates (npx aiad-sdd mini-gate). Le prompt inclut le contrat JNSP (TODO-JNSP: plutôt qu'inventer). Skills invoquées : sqs-scoring, context-budget, regulatory-veto (un VETO empêche le lancement).

Sortie. Prompt agent assemblé + plan phasé .aiad/exec/EXEC-<SPEC>-plan.md + statut SPEC → in-progress, puis code + tests conformes.

/sdd resume — reprise de session

Quand. Session agent interrompue (timeout, erreur, limite de contexte, choix volontaire).

Ce que ça fait. Reconstruit un contexte plus léger que le contexte initial : lit l'état réel du cycle (npx aiad-sdd cycle next) et du plan phasé (npx aiad-sdd exec-status), inventorie le travail fait via git, puis formule un prompt de reprise minimal. Si l'état n'est pas reconstructible à 100 %, verdict JNSP — jamais de relance en aveugle. Skills invoquées : context-budget, drift-detection.

Sortie. Résumé d'état structuré + nouvelle session opérationnelle reprenant à l'étape exacte.

/sdd split — découpage de SPEC

Quand. SPEC trop volumineuse (> 200 lignes), échec d'atomicité à la Gate, > 2 relances agent ou budget > ≈ 50K tokens (heuristique de sobriété assumée, non sourcée).

Ce que ça fait. Propose un pattern de découpage — par couche technique, par cas d'usage (happy path / edge cases / erreurs), par dépendance ou par domaine métier — puis pré-valide chaque sous-SPEC avec la skill sqs-scoring : chacune doit pouvoir passer la Gate indépendamment. Au-delà de 5 sous-SPECs, l'Intent est trop ambitieux → retour à /sdd intent.

Sortie. 2 à N sous-SPECs avec dépendances explicites et ordre d'exécution, SPEC parente en statut split.

/sdd context — audit du budget de contexte

Quand. Après une session agent, pour boucler le feedback du Context Engineering Budget.

Ce que ça fait. Compare l'estimation de la SPEC §6 avec le contexte réellement injecté, puis applique la skill context-budget : 5 métriques de santé M1–M5 (taux utile, relances, ratio, cohérence, durée) et un score 0–5/5. Le context rot (M4 + M5) est le signal le plus dangereux : il dégrade silencieusement. Depuis aiad-sdd 1.19.0, l'empreinte mesurée de la SPEC (npx aiad-sdd footprint <SPEC>) s'affiche à côté de l'estimation.

Prochaine version — à paraître. L'audit compte le contexte hérité aux points de fork : quand un sous-agent hérite de la conversation parente, sa délégation coûte le contexte parent au moment du fork en plus de son travail propre. Une ligne « Contexte hérité (délégations) » s'ajoute au tableau estimation / réel, et un diagnostic signale les délégations tardives (contexte hérité > 50 % du total) : déléguer plus tôt dans la session.

Sortie. Rapport d'audit avec recommandations + mise à jour de la SPEC §6 et des Lessons / Human Learnings si un pattern est détecté.

/sdd validate — validation du code agent

Quand. À la fin de chaque session d'implémentation, avant le Drift Lock.

Ce que ça fait. Validation triple : technique (lint, types, tests, build), fonctionnelle (chaque critère §3 coché contre le code), gouvernance (agents Tier 1). Vérifie aussi le Critère de Drift de l'Intent parent, et propose en option une review --cross-model par un modèle tiers en contexte frais (additive-only). Skills composées : ears-validator + drift-detection + regulatory-veto. Un UNKNOWN Tier 1 vaut VETO (fail-closed) ; des TODO-JNSP: non résolus produisent un verdict JNSP.

Sortie. Verdict VALIDÉ / CORRECTIONS MINEURES / ÉCHEC / JNSP avec rapport actionnable.

/sdd drift-check — Anti-Drift Check

Quand. Avant chaque PR, et en rituel de fin d'itération.

Ce que ça fait. Combine deux contrôles depuis aiad-sdd 1.10 : l'heuristique git (skill drift-detection — code modifié sans SPEC mise à jour dans la même PR) et la mesure machine-vérifiable (skill traceability, via npx aiad-sdd trace --fail-on-gap). Des annotations @spec absentes donnent un verdict INCONNU — jamais OK par défaut, et traité comme un DRIFT par les hooks et la CI.

Sortie. Verdict OK / DRIFT / INCONNU + mises à jour proposées + entrée CHANGELOG-ARTEFACTS.md. Ne jamais merger en état de drift.

/sdd trace — matrice de traçabilité

Quand. Pour mesurer la chaîne Intent ↔ SPEC ↔ Code ↔ Tests, à la demande ou en CI.

Ce que ça fait. Scanne les annotations @intent / @spec / @verified-by / @governance, croise avec .aiad/intents/ et .aiad/specs/, et produit les matrices Forward et Backward. Les gaps sont classés (orphelins, SPECs validées sans code — bloquants ; code non tracé, code sans tests) avec plan de remédiation. Skill invoquée : traceability.

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

/sdd fact — capture de fait technique

Quand. Un écart est constaté entre comportement livré et désiré, sans justifier un cycle Intent complet (bug mineur, comportement inattendu, drift partiel).

Ce que ça fait. Capture l'écart précis (livré vs désiré), qualifie l'impact (fonctionnel / sécurité / performance / conformité spec) et décide l'action parmi quatre options : patch immédiat, nouveau Intent, ajustement de SPEC, ou dette technique documentée. Skills invoquées : drift-detection, regulatory-veto si dimension sécurité/conformité.

Sortie. .aiad/facts/FACT-NNN.md avec décision tracée et lien vers la SPEC concernée.

/sdd security — audit sécurité

Quand. Après toute implémentation impliquant des accès, des données utilisateur, des secrets ou un composant IA — recommandé avant toute PR critique.

Ce que ça fait. Audit sur 4 axes : OWASP Top 10 (y compris injection de prompt), gestion des secrets, permissions des agents (Harness Engineering — minimal necessary permissions) et conformité réglementaire via la skill regulatory-veto. Un pattern non classifiable sort en JNSP et est traité comme un risque (fail-closed) — jamais « safe » par absence de preuve.

Sortie. Rapport structuré (risques critiques / moyens / bonnes pratiques / zones JNSP) persisté dans .aiad/metrics/security/YYYY-MM-DD-SPEC-NNN.md.

/sdd audit — audit qualité

Quand. Avant ou pendant la validation, notamment pour les fonctionnalités à fort enjeu technique ou après plusieurs itérations d'un même composant.

Ce que ça fait. Couvre 4 dimensions : conformité code ↔ SPEC critère par critère, qualité du code (complexité, couplage, lisibilité), dette technique (délibérée / accidentelle / bit rot), cohérence avec les conventions de l'AGENT-GUIDE. Tout drift détecté déclenche une proposition de mise à jour de SPEC (Drift Lock). Skills invoquées : drift-detection, ears-validator.

Sortie. Rapport persisté dans .aiad/metrics/audit/YYYY-MM-DD-SPEC-NNN.md avec recommandations BLOQUANT / IMPORTANT / SUGGESTION.