Quickstart.

Tout l'outil est une boucle : vous décrivez la mission, votre agent construit, puis le check vous renvoie construire ou vous laisse sortir.

Le chemin en une minute : voir une garde passer au vert

Le moyen le plus rapide de voir une garde passer est la mission de référence livrée avec l'outil, qui arrive déjà remplie :

npx runward init --example    # scaffold the filled "request-triage" reference mission
runward check                 # exits 0 — every deliverable is filled

init --example copie une mission complète et pré-remplie, ainsi que le code du plancher de référence vers lequel pointent ses manifestes, posé sous code/. Sous runward check --strict, la preuve se résout donc vers des fichiers réels au lieu de rester non vérifiée.

C'est le seul cas où un échafaudage neuf est au vert d'emblée :

• de manière simple : chaque livrable est rempli ;
• sous --strict : chaque pointeur se résout.

Utilisez-le pour voir toute la chaîne, puis démarrez la vôtre avec npx runward init (sans --example) pour des gabarits vierges.

Ce que runward init écrit réellement

À lancer dans le dossier que vous voulez amorcer (par défaut le répertoire courant) :

npx runward init            # interactive wizard
npx runward --yes init      # non-interactive: greenfield, floor tier, no tool profiles

init pose une base neutre, indépendante de tout fournisseur : aucun harnais IA n'est privilégié.

Ce que contient la base neutre

Concrètement, il écrit :

• AGENTS.md à la racine du projet : la charte de l'agent, le fichier "loi", toujours écrit. AGENTS.md est le standard ouvert lu par une longue liste d'agents (Codex, Cursor, Copilot, Windsurf, Cline, Zed, Amp, opencode, goose, Junie, Warp et d'autres), si bien qu'aucun outil unique n'est favorisé. Il énonce les frontières non négociables :
  • l'architecture contraint le modèle (et non l'inverse) ;
  • les frontières avant la stack ;
  • la complexité différée jusqu'à un déclencheur ;
  • une frontière déterministe ;
  • et la sécurité sur les actions et non sur l'affichage.
• .agents/skills/runward-<phase>/SKILL.md : des skills de phase indépendants de tout fournisseur, au format ouvert convergé SKILL.md, toujours écrits aux côtés de la charte. Ils font remonter les règles de métier d'une phase de construction par pertinence, au moment de l'action ; ils aident un agent à appliquer les règles mais ne les font jamais respecter : runward check --strict est la seule autorité.
• runward/ : l'état de la mission. init y copie les gabarits de livrables (note de cadrage, contrat de mission, note d'architecture, topologie d'exécution, matrice de décision, note de plancher, notes de gouvernance, contrat de port, runbook, note de passation, gabarit d'ADR, plus quelques notes d'échafaudage non gardées : reference-stack, shared-bricks, gap-analysis).
• runward/workflows/ : la méthode exécutable que suit votre agent, à partir de method.md (puis frame, architect, floor, iterate, govern, handover, brownfield, review, decision-loop, verify).
• runward/rules/ : les règles de métier que l'agent applique pendant la construction.
• runward/adapters/ : un câblage de garde en échantillon inerte (git pre-commit, CI, fin de tour par harnais). runward ne les installe jamais ; c'est vous qui les câblez (voir ci-dessous).

Aucun canal de harnais par défaut

Aucun canal de harnais n'est écrit par défaut. Avec --yes, la liste des profils d'outils est vide ; l'assistant ne pré-coche rien.

Un canal par harnais (par exemple .claude/, .cursor/) est optionnel via --tools claude,cursor,... : un ajout par-dessus la base neutre, que l'agent peut recommander pour le harnais détecté uniquement sur approbation de l'opérateur.

Écrasement, simulation et choix enregistrés

• init n'écrase jamais un fichier existant sauf si vous passez --force ; les chemins existants sont signalés comme skip.
• RUNWARD_DRY_RUN=1 planifie les écritures sans toucher au disque.
• L'assistant enregistre aussi votre mode d'entrée (greenfield / brownfield) et votre palier d'arrêt (cadrage / plancher / chaîne complète) : le choix du sponsor, révisable.

La boucle de construction : décrire → l'agent construit → vérifier

runward encadre ; votre agent construit. La boucle est :

1. Décrivez le produit à votre agent. Pointez-le vers AGENTS.md et runward/workflows/method.md. Le premier jour, vous et votre sponsor remplissez runward/framing.md : le problème, la valeur, un critère de succès observable, plancher contre cible. C'est une conversation, pas du code ; n'architecturez pas avant que la garde de cadrage soit passée.

2. L'agent construit face à la mission. Il écrit le vrai code du produit, et pour chaque livrable gardé il remplit un manifeste ## Rule conformance : chaque règle de métier CRITICAL/HIGH rattachée à cette phase est prise en compte selon l'un de ces états :

   • applied : avec un pointeur typé que la garde peut vérifier (file:PATH[:LINE][#SYMBOL], test:PATH[::NAME], adr:NNNN) ou de la prose ;
   • deviated : avec un ADR ;
   • n/a : avec une vraie raison.

   runward manifest --sync amorce les lignes manquantes ; l'agent remplit la décision.

3. Lancez la garde.

runward check            # gap audit: which deliverable is missing / started / filled
runward check --strict   # also verify every phase's rule-conformance manifest + evidence

Répétez : remplissez le ou les livrables nommés, relancez runward check. L'agent peut piloter toute la boucle ; runward check --json émet un unique objet JSON déterministe (verdict, garde courante, état par livrable, code de sortie) pour qu'un agent raisonne sur des données, pas sur du texte extrait.

Ce que signifie "une garde qui passe"

Comment les livrables sont classés

runward check lit l'état de la mission et classe chaque livrable attendu comme filled, in-progress (des balises subsistent), untouched (gabarit brut) ou missing. Un livrable ne compte comme filled que lorsqu'il s'écarte de façon significative du gabarit livré : plusieurs lignes nouvelles et assez de mots nouveaux, pas une édition d'un octet, de sorte que vous ne pouvez pas passer une garde en laissant l'échafaudage en place.

Gardes et codes de sortie

• Garde courante = la première phase dont les livrables ne sont pas tous remplis. À mesure que vous remplissez une phase, le pointeur avance vers la suivante : la garde de cette phase a été franchie.
• Code de sortie 0 (propre) exige que chaque livrable attendu à travers toutes les phases soit rempli, et sous --strict que chaque règle CRITICAL/HIGH rattachée soit prise en compte, et, quand les hooks sont activés (--hooks), que les éventuels hooks passent. C'est pourquoi un runward init vierge ne peut pas atteindre le code de sortie 0 tant que la chaîne entière n'est pas remplie ; seul init --example est au vert immédiatement. Le message en cas de succès : "All expected deliverables are filled. Cross gates on evidence, not on paperwork."
• Code de sortie 1 = des écarts subsistent (livrables non remplis, ou écarts de conformité sous --strict, ou hooks en échec).
• Code de sortie 2 = aucune mission trouvée ici ou au-dessus (runward init n'a jamais été lancé). Une racine de mission est un répertoire contenant runward/framing.md.

Ce que --strict ajoute

Sous --strict, la garde fait plus que vérifier la présence :

• les pointeurs applied doivent se résoudre vers un contenu réel et non vide ;
• la preuve d'une règle signée doit correspondre à sa signature: ;
• un pointeur périmé (dérive) échoue ;
• et le sceau de preuve, s'il existe, doit être intact.

C'est la partie déterministe, zero-LLM : elle prouve qu'une décision a été tracée et pointe vers quelque chose de réel, jamais que le code est correct, et elle ne peut pas être détournée par du texte injecté ; relancez-la et obtenez le même verdict.

Preuve documentaire, pas un passage à l'exécution

Une garde qui passe est une preuve documentaire, pas un passage à l'exécution. La garde confirme que les décisions sont tracées ; elle n'exécute explicitement pas votre code : runward n'est pas un runtime. La preuve comportementale est votre propre suite de tests, que runward signale comme présente/fraîche mais qu'il n'exécute ni ne lit jamais. De même, le workflow verify (une passe contradictoire cite-contre-apply) est indicatif et ne bloque jamais la garde. Vous franchissez sur les deux preuves.

Sceller et câbler (optionnel, sur votre accord)

Sceller une garde au vert

Une fois qu'une garde --strict est au vert, vous pouvez la sceller : runward check --freeze hache chaque fichier de preuve résoluble dans runward/evidence-lock.json (SHA-256, committé). Un fichier scellé qui change ou disparaît ensuite fait échouer check --strict jusqu'à ce que vous re-vérifiiez et re-scelliez ; il refuse de sceller une garde au rouge.

Câbler la garde pour qu'elle tourne automatiquement

Pour faire tourner la garde automatiquement, câblez l'un des échantillons inertes de runward/adapters/ au moment naturel de votre harnais (git pre-commit, un check requis de CI, ou un hook de fin de tour).

runward n'installe rien et n'écrit jamais dans .git/ (ADR-0012) : runward wire est en lecture seule : il détecte le harnais et pointe vers l'échantillon correspondant ; l'opérateur (ou l'agent, sur approbation explicite) fait le câblage. Sur un harnais undetermined, l'agent demande quel outil vous utilisez plutôt que de deviner.

"Agent-operable" signifie qu'un agent peut piloter tout cela de bout en bout, y compris le câblage sur votre accord, non que runward modifie silencieusement votre dépôt.

Référence des commandes pour ce quickstart

Commande	Effet	Codes de sortie
npx runward init	Poser la base neutre : AGENTS.md, .agents/skills/, runward/ (workflows, rules, adapters, gabarits de livrables)	0
npx runward init --example	Poser la mission de référence request-triage remplie (au vert de manière simple et sous --strict)	0
npx runward --yes init	Défauts non interactifs : greenfield, palier plancher, aucun profil d'outil	0
npx runward init --tools claude,cursor,…	Ajouter des canaux par harnais par-dessus la base (optionnel)	0
runward check	Audit des écarts de livrables ; nomme la garde courante	0 propre · 1 écarts · 2 aucune mission
runward check --strict	Vérifier aussi le manifeste de conformité aux règles et la preuve de chaque phase (déterministe, zero-LLM)	0 propre · 1 écarts · 2 aucune mission
runward check --json	Même verdict sous forme d'un unique objet JSON lisible par machine	identique à ci-dessus
runward check --freeze	Sceller une garde stricte au vert dans runward/evidence-lock.json ; refuse sur une garde au rouge	0 propre · 1 écarts · 2 aucune mission

Pourquoi ce choix

Le défaut de base neutre (ADR-0030)

Le défaut de base neutre (n'écrire que AGENTS.md + .agents/skills, aucun canal par harnais) est un choix délibéré d'indépendance vis-à-vis des fournisseurs, consigné dans ADR-0030. L'alternative écartée était de présélectionner ou de privilégier un harnais IA (par exemple écrire .claude/ par défaut) ; cela favoriserait un outil au détriment de ses pairs. À la place, la base n'utilise que des standards ouverts et convergés (AGENTS.md et le format SKILL.md) que 14+ harnais lisent, et tout câblage spécifique à un outil est une option explicite via --tools que l'opérateur ajoute ensuite.

Ne jamais installer la garde (ADR-0012)

De même, runward n'installe jamais la garde lui-même (ADR-0012) : les adapters sont des échantillons inertes que l'opérateur câble, ce qui écarte l'alternative d'écrire silencieusement dans .git/ ou dans une configuration de harnais, si bien que l'opérateur reste toujours propriétaire de la garde.