Software Factory

Dissipez d'abord tout doute sur le périmètre. Figez les obligations. Déléguez chaque phase lourde à un sous-agent frais. Prouvez la complétion avec un Vérificateur indépendant qui n'a pas écrit le code.

┌──────────┐   ┌──────┐   ┌────────┐   ┌───────┐   ┌────────┐
│ DISCOVER │ → │ PLAN │ → │ CHECKS │ → │ BUILD │ → │ VERIFY │
└──────────┘   └──────┘   └────────┘   └───────┘   └────────┘
 0 doutes       confirmer   obligations   lots       auteur != vérif.

Cinq mouvements, trois artefacts durables sous .specs/features/<feature>/, et un Orchestrateur Léger dans le chat principal qui ne gonfle jamais sa fenêtre de contexte.

DISCOVER : Un sous-agent scout en lecture seule scanne le codebase et renvoie un résumé d'ambiguïté compact (~30 lignes). Le chat principal interroge l'utilisateur avec des options concrètes et des valeurs par défaut recommandées jusqu'à ce qu'il n'y ait plus aucune hypothèse non confirmée (Confirmé ? oui pour chaque ligne). Voir discovery.md.
PLAN : Un sous-agent planner écrit .specs/features/<feature>/plan.md (Problème, Flux, Impact, Relations, Surface, Atterrissage, Critères, Hors périmètre, Hypothèses, Observable, Sources) et exécute validate_plan.py. L'utilisateur donne un avis rapide sur plan.md. Voir plan.md.
CHECKS : Après la validation de plan.md, la boucle post-plan autonome commence. Un sous-agent specifier dérive .specs/features/<feature>/checks.md (revendications + preuves, jointure de couverture, politique de test, balayé, arithmétique de passation) et exécute validate_checks.py. Voir checks.md.
BUILD : Un sous-agent builder par lot écrit les tests strictement à partir des vérifications, implémente le code, exécute les preuves, met à jour checks.md, et commit en utilisant check_commit.py. Voir build.md.
VERIFY (et boucle FIX) : Un sous-agent verifier indépendant (jamais le builder) audite <feature_base>..HEAD par rapport à chaque vérification, écrit .specs/features/<feature>/verification.md, et exécute validate_verification.py. Si une vérification échoue, un sous-agent fixer résout les lacunes classées et un nouveau verifier revérifie (jusqu'à 3 rounds). Voir verify.md et orchestration.md.

Pourquoi cette forme

Les agents de codage échouent sur les fonctionnalités complexes pour deux raisons prévisibles :

Gonflement de la fenêtre de contexte : Lorsqu'une seule session de chat explore le dépôt, interroge l'utilisateur, écrit le plan, dérive les vérifications, écrit les tests et le code, et vérifie son propre travail, la fenêtre de contexte se remplit et déclenche une compression avec perte.
Exigences non confirmées et angles morts d'auto-revue : Deviner silencieusement le comportement du produit (Confirmé ? non) ou laisser l'auteur auto-certifier la complétion livre les propres angles morts de l'auteur.

software-factory résout les deux :

Orchestrateur Léger (<15k tokens dans le chat principal) : Le chat principal agit strictement comme coordinateur et intervieweur de l'utilisateur. Toute la lecture du codebase, la rédaction d'artefacts, le codage, les tests et la vérification s'exécutent dans des sous-agents éphémères isolés (scout, planner, specifier, builder, verifier, fixer) qui communiquent exclusivement via les fichiers .specs/features/<feature>/ sur le disque et les commits git. Protocole de dispatch complet : orchestration.md.
Petit ensemble d'obligations gelées + Vérificateur indépendant : Il n'y a pas de liste de tâches granulaires ou de catalogue de composants (Objet/Emplacement/Interfaces par classe) qui deviendrait obsolète. Les portes à sens unique reçoivent une forme littérale dans Atterrissage ; le placement réversible est décidé dans le diff.

Règles critiques

L'ensemble épinglé. Elles s'appliquent à chaque profil :

Zéro hypothèse non confirmée (Confirmé ? oui). Ne devinez jamais le comportement du produit ou du périmètre silencieusement. Chaque zone grise révélée pendant DISCOVER doit être demandée avec des options concrètes et une valeur par défaut recommandée, ou explicitement déléguée par l'utilisateur (Confirmé ? oui). validate_plan.py rejette toute ligne où Confirmé ? est non ou vide.
Orchestrateur Léger & Limite Stricte 1 Sous-Agent Par Phase (scout != planner != specifier != builder != verifier). Gardez le chat principal sous ~15k tokens. Ne fusionnez jamais deux phases en un seul appel de sous-agent :
- scout SEULEMENT explore et renvoie le résumé d'ambiguïté ~30 lignes.
- planner SEULEMENT écrit plan.md + exécute validate_plan.py, puis s'arrête et se termine.
- specifier SEULEMENT écrit checks.md + exécute validate_checks.py, puis s'arrête et se termine (il NE DOIT JAMAIS écrire de fichiers de test ou de code d'implémentation ni continuer dans BUILD).
- builder SEULEMENT s'exécute après que specifier soit revenu. Pour les fonctionnalités multi-lots (S1, S2, ...), dispatchez un sous-agent builder séparé par lot séquentiellement afin que chaque lot s'exécute dans une fenêtre de contexte fraîche et rapporte la progression à l'utilisateur.
- verifier SEULEMENT s'exécute dans un sous-agent frais après que le builder final ait commité.
Chaque vérification est une revendication observable avec une valeur concrète plus la preuve — le sélecteur de test ou la commande exacte dont le code de sortie la tranche. Pas de preuve, pas de vérification.
Les tests affirment ce que disent les vérifications, jamais ce que le code se trouve à faire. N'écrivez jamais un test en lisant l'implémentation.
N'affaiblissez jamais une assertion, ne supprimez jamais un test et n'en sautez jamais un pour faire passer une suite. Une vérification vraiment erronée est un stop-et-demande, pas une modification.
Les vérifications et les lignes de Politique de test sont fixes une fois approuvées. Dans plan.md, Atterrissage, Relations et Surface sont additifs — une porte découverte pendant la construction reçoit une ligne avant le code qui la ferme, et une ligne que l'utilisateur a approuvée n'est jamais réécrite. Flux et Impact sont gardés vrais dans le commit qui change le chemin.
Le Vérificateur est un sous-agent frais, jamais l'auteur, jamais optionnel, jamais en attente d'être demandé. L'Orchestrateur le dispatch immédiatement après que le dernier commit de la fonctionnalité atterrit sur <feature_base>..HEAD avec chaque vérification.
Le profil est un plancher et est appliqué par validate_verification.py.
La porte de complétion est un script, pas un sentiment : validate_verification.py doit sortir avec 0.
Rayon d'explosion : un spec approuvé autorise les modifications locales et les commits locaux. git push, le déploiement et les modifications de données de production nécessitent un feu vert explicite pour cette action.

Profil

Le projet déclare combien s'exécute, dans AGENTS.md ou équivalent. En l'absence de déclaration : light.

## software-factory

profile: light
budget: 150k

Profil	Ajoute	Ne peut pas attraper
`light` (défaut)	les preuves s'exécutent à `HEAD` avec chaque test nommé montré comme existant et exécuté, une assertion localisée par vérification, les lacunes de niveau et d'échantillonnage, `Balayé existant` relu	un membre d'ensemble sans preuve ; un test qui passerait sous une mauvaise implémentation
`standard`	la jointure `Couverture` recalculée, les lignes de `Politique de test` avec un verdict chacune, une faute par surface d'assertion	une vérification qui contredit une source contraignante ; un écran que personne n'a construit
`ui`	les sources contraignantes ouvertes et comparées, l'énumération par écran de la copie et de l'agencement	seulement l'espacement, la couleur et le poids de police, énumérés par écran

validate_verification.py échoue un rapport dont le profil diffère de celui sous lequel checks.md a été approuvé, échoue un rapport standard sans lignes de faute ou sans couverture recalculée, et échoue un rapport ui sans section de sources contraignantes.

Artefacts

.specs/
├── STATE.md                    # Journal des décisions (AD-NNN) + instantané de passation
├── LESSONS.md                  # rendu par scripts/lessons.py - jamais éditée à la main
├── lessons.json                # propriété de la machine
└── features/<feature>/
    ├── plan.md                 # problème, flux, impact, relations, surface, atterrissage, critères, hypothèses (tous oui), observable
    ├── checks.md               # revendications + preuves, jointure de couverture, politique de test, balayé, lots de passation
    └── verification.md         # le rapport du Vérificateur indépendant

Créez chaque fichier lorsque sa phase produit du contenu. Pour un changement d'environ trois fichiers sans porte à sens unique et zéro ambiguïté de périmètre, écrivez seulement checks.md avec un paragraphe ## Intention et sautez plan.md.

Cinq sections de conception limitées dans `plan.md`

Section	Passe en revue	Gardé hors de
`Flux`	le chemin, une ligne par saut	tout module qui n'existe ni n'est créé par une porte — c'est du placement
`Impact`	ce qui change en dessous : termes, et données existantes	les registres de risques
`Relations`	entités, cardinalité, contraintes unidirectionnelles	colonnes et types
`Surface`	route, entrée, sortie, statuts	la spécification du corps de la requête, et les identifiants de vérification — ceux-ci n'existent pas encore
`Atterrissage`	les portes à sens unique, avec la forme littérale et l'alternative rejetée	tout ce qu'un refactor inverse

Flux

Discover — Dispatchez le sous-agent scout en lecture seule pour inspecter le dépôt, .specs/STATE.md et .specs/LESSONS.md et renvoyer un résumé d'ambiguïté d'environ 30 lignes. Parcourez avec l'utilisateur les véritables zones grises du produit et du périmètre (au plus 2 questions par tour, options concrètes avec valeur par défaut recommandée) à travers les surfaces Observable et les 9 dimensions implicites jusqu'à ce qu'il n'y ait plus 0 doutes : discovery.md.
Plan — Dispatchez le sous-agent planner avec les décisions de découverte confirmées pour écrire .specs/features/<feature>/plan.md et passer validate_plan.py. Présentez plan.md à l'utilisateur pour un avis rapide : plan.md.
Checks — Une fois plan.md approuvé, exécutez-vous de manière autonome. Dispatchez un sous-agent specifier dédié pour dériver .specs/features/<feature>/checks.md (revendications + preuves, jointure Couverture, Balayé, et dimensionnement des lots ## Passation) et passer validate_checks.py, puis terminez ce sous-agent avant que tout code ou test ne soit écrit : checks.md.
Build — Après que specifier ait terminé, dispatchez un sous-agent builder frais par lot (S1, S2, ...) séquentiellement. Chaque builder écrit les tests à partir des vérifications pour son lot assigné, implémente, exécute les preuves, enregistre Limite dans checks.md, commit avec check_commit.py, et se termine : build.md.
Verify & Fix — Dispatchez un sous-agent verifier frais sur <feature_base>..HEAD pour écrire verification.md et exécuter validate_verification.py. Si ÉCHEC, dispatchez un sous-agent fixer et revérifiez (jusqu'à 3 rounds) : verify.md.
Orchestration & Dispatch de Sous-agents — Règles de l'Orchestrateur Léger, budgets de fenêtre de contexte, et mappings multi-agents (antigravity, claude, codex) : orchestration.md.
Mémoire Durable — Décisions du projet (STATE.md), passation de session, et leçons fondées sur la vérification (lessons.py) : memory.md.

Scripts

Résolvez <skill-dir> comme le répertoire contenant ce SKILL.md et invoquez python3 <skill-dir>/scripts/<name>.py. Passez --root lorsque le répertoire de travail courant diffère de la racine du projet. Un code de sortie non nul signifie ARRÊT et correction.

Quand	Commande
Inspecter la phase du pipeline & le prochain rôle de sous-agent	`orchestrate.py status <feature> --root <dir>`
Générer une invite de sous-agent isolée	`orchestrate.py prompt --role <scout
Exécuter la porte de phase via l'orchestrateur	`orchestrate.py gate --phase <plan
Dispatcher un sous-agent via CLI (ou `--dry-run`)	`orchestrate.py dispatch --role --agent <antigravity
Avant de présenter `plan.md`	`validate_plan.py <feature>`
Avant de démarrer `BUILD`	`validate_checks.py <feature>`
Avant chaque commit	`check_commit.py --message "<msg>"`
Avant de déclarer terminé	`validate_verification.py <feature>`
À la distillation	`lessons.py add ...`
Après avoir modifié un validateur, un script ou un template	`selftest.py`

Sous-agents et passation

Chaque phase est strictement isolée dans sa propre invocation de sous-agent (scout -> planner -> specifier -> builder [S1] -> builder [S2] -> ... -> verifier -> fixer). Ne combinez jamais specifier (CHECKS) et builder (BUILD) dans le même sous-agent. Pendant BUILD, lorsqu'une fonctionnalité a plusieurs lots (S1, S2, ...), dispatchez un sous-agent builder séparé par lot séquentiellement afin que chaque builder démarre avec une fenêtre de contexte propre, termine rapidement, commite son lot sur vert et renvoie une mise à jour de progression à l'Orchestrateur Léger.

Lorsque le dernier lot de builder revient vert, l'Orchestrateur dispatch immédiatement le sous-agent verifier indépendant dans le même tour sans demander à l'utilisateur.

Chaîne de connaissances

Dans l'ordre strict : code existant et conventions, docs du projet, documentation de bibliothèque (Context7 si disponible), recherche web, puis marquer comme incertain. N'inventez jamais une API, un drapeau, une commande ou un comportement.

Comportement de sortie

Produisez l'artefact ; ne racontez pas la phase. Commencez par le verdict. Énoncez les décisions de manière définitive. Supprimez le remplissage et les hésitations mécaniques. Gardez les en-têtes de section en anglais (ils sont un schéma vérifié par les portes).

brenoacker/agent-skills

Qu'est-ce que agent-skills ?

Demander à votre IA préférée

Documentation