Le dépôt AI Software Factory décrit le passage d’une mission produit et d’un ticket à une demande de fusion construite par Archon. L’installation et les contrôles des workflows ne sont qu’un début. Le guide de la première heure précise que la validation réelle de bout en bout reste à effectuer. Ce guide suit le commit de la fabrique 9e2d85298b45497031009597a6ae0811b66fe6d6 et sa révision Archon fixée fad09169ea1b43512bc7ee88470d47f960a3e0f8. Il repose sur la lecture de la documentation et du code, pas sur une installation ou une exécution réalisée par BIG CHANGE.

Il s’adresse à une équipe qui contrôle le dépôt d’une application ou un PRD, ses autorisations GitHub et son compte fournisseur de modèles. Le mainteneur décrit explicitement le clonage et l’installation de la fabrique dans votre propre dépôt. L’arborescence fixée ne comporte ni licence ni avis ; ce guide n’établit pas de droits plus larges de réutilisation ou de redistribution. La licence MIT d’Archon s’applique au code Archon distinct. Ne placez aucun secret du fournisseur dans les tickets, les instructions, les journaux ou les comptes rendus de revue.

Le grand changement

  • Ce qui change : Cette implémentation relie le périmètre produit, la planification des tickets, le code, la revue indépendante et les contrôles d’exécution au moyen d’un pack de workflows Archon fixé. La fabrique fournit les entrées du projet et le lanceur ; le pack partagé porte les étapes d’IA.
  • Pourquoi cela compte : L’équipe peut suivre une proposition depuis le ticket jusqu’aux modifications précises, au résultat de CI et au candidat exécuté avant de décider d’une fusion. Les seuls diagnostics d’installation laissent cette chaîne incomplète ; le mainteneur indique que l’intégration réelle reste à valider.
  • À surveiller : La première preuve utile est un véritable ticket dont la révision livrée réussit des parcours significatifs et une validation réservée indépendante, avec coûts et dossier de revue visibles. Planification et déploiement restent des décisions séparées après cette revue.

1. Vérifier le dépôt, les autorisations et la source fixée

Les instructions d’installation du mainteneur demandent Git, Python 3.10 ou ultérieur, gh authentifié avec la portée workflow, un dépôt distant GitHub, un agent de programmation, Bun et uv. Git doit également pouvoir envoyer les fichiers de workflows (gh auth setup-git). Avant une exécution, vérifiez les commandes existantes de test, de démarrage et de CI, la protection des branches, l’accès GitHub, l’authentification du fournisseur et la facturation des modèles. N’accordez que les droits nécessaires sur le dépôt et les workflows.

Clonez la fabrique hors du dépôt de l’application et sélectionnez le commit indiqué. Depuis la racine de l’application, la commande d’installation documentée est :

Terminal
git clone https://github.com/coleam00/ai-software-factory ~/ai-software-factory
git -C ~/ai-software-factory checkout 9e2d85298b45497031009597a6ae0811b66fe6d6
python ~/ai-software-factory/bin/factory.py init

Utilisez python3 si nécessaire. L’installateur copie les modèles de fabrique et de projet, puis installe la source Archon indiquée dans pack.json. À ce commit, le README et le pack indiquent tous deux fad09169ea1b43512bc7ee88470d47f960a3e0f8. L’installateur n’authentifie aucun fournisseur, ne sélectionne aucun niveau de modèle et ne lance aucune planification. Examinez les fichiers modifiés avant de les accepter dans votre dépôt.

Configurez le fournisseur choisi et les identifiants de modèles pris en charge selon les instructions Archon installées. Définissez les vraies commandes d’analyse statique et de tests unitaires dans harness/harness.config.json. Si GitHub ne peut pas fournir la protection des branches, indiquez dans required_checks les tâches de CI nécessaires à la fusion. Vérifiez protected_paths pour que toute modification de la mission, du banc de validation ou des règles de la fabrique exige une intervention humaine. Le modèle laisse vides les commandes ordinaires de contrôle et required_checks : le copier ne suffit pas à établir un critère d’acceptation utilisable.

2. Définir la mission et les contrôles du produit existant

Dans MISSION.md, indiquez l’objectif du produit, ses limites strictes et des demandes plausibles hors périmètre. Dans harness/END-TO-END.md, décrivez deux à cinq parcours que l’application réalise déjà, avec la valeur visible pour l’utilisateur. Un parcours dépendant d’une fonctionnalité non construite bloquerait la première livraison. Dans .factory/holdout/HOLDOUT.md, écrivez des cas distincts combinant des comportements ou explorant des cas limites. Le nom du dossier ne les cache pas à un développeur ayant accès à la même copie du dépôt ; placez les cas réellement privés ailleurs et ne les transmettez qu’à la vérification.

Pour un dépôt ne contenant qu’un PRD, le README demande de tirer du document la mission, les parcours prévus et les commandes du banc de validation. Le premier ticket proposé doit rendre le produit exécutable et préciser la commande de démarrage, les chemins de contrôle de santé et d’identité de version, les tests et la CI. Examinez cette proposition avant d’autoriser la publication des tickets.

Transformez les parcours en entrées de scénario attendues par les workflows d’exécution Archon. Suivez le fichier installé factory/RUNTIME_HOST.md pour préparer un instantané de l’application à partir du commit livré, un état neuf, les contrôles de santé et d’identité de version, ainsi que les commandes de lancement Python ou Node autorisées. L’hôte documenté ne prend pas en charge les bases distantes, les conteneurs ou les ressources cloud comme ressources d’exécution qu’il gère. Une application qui les utilise exige un dispositif de vérification justifié séparément ; un contrôle local réussi ne prouverait pas leur isolation.

Avant de vous fier à l’évaluateur, établissez une référence réussie exerçant une vraie valeur utilisateur, montrez qu’une faute volontaire pertinente provoque un échec et vérifiez qu’une mauvaise identité du candidat produit un verdict non concluant. Le guide de l’hôte donne les entrées de la suite et les champs exacts attendus, dont expectations_passed: true et baseline_verified: true. Conservez le retour natif réel et l’identité du candidat comme preuves. Une assertion qui ne vérifie que le chargement d’une page, ou un test qui crée directement l’état final, est trop faible.

3. Vérifier l’installation, puis choisir une tâche

Depuis la racine de l’application, exécutez :

Terminal
python factory/consumer.py doctor
python factory/consumer.py list

doctor vérifie la source fixée, les capacités des commandes et les workflows disponibles. list affiche les workflows découverts. Aucun ne prouve qu’un fournisseur peut terminer un ticket, que la CI réussira ou que l’application démarrera. Corrigez les erreurs signalées avant la livraison ; laissez la planification désactivée.

Pour une base de code existante, rédigez un petit ticket avec un résultat clair et des contrôles d’acceptation. Le README documente cette commande pour passer du triage à la livraison et à la revue, jusqu’à une demande de fusion :

Terminal
python factory/consumer.py run archon-ship --input target=https://github.com/OWNER/REPO/issues/1 --input discovery_publication=preview --detach --json

Remplacez l’URL par celle d’un ticket que vous contrôlez. L’option explicite discovery_publication=preview empêche la création de tickets pour les constats voisins issus de la revue ; sinon, le workflow fixé archon-ship utilise auto par défaut. N’utilisez archon-lifecycle qu’une fois prêts son scénario d’exécution et ses entrées de validation réservée. Passez le ticket comme target, les chemins correspondants comme scenario et holdout, puis merge_mode=approve et discovery_publication=preview. Fournissez aussi un merge_method approuvé pour le projet : merge, squash ou rebase. N’utilisez par exemple merge_method=squash que si le dépôt l’autorise. Ce workflow comprend la vérification d’exécution et des cas réservés, la réparation et un contrôle avant fusion. Le mode d’approbation maintient une décision humaine avant fusion ; l’indication « prêt » du workflow ne remplace pas cette décision. Avec l’hôte d’exécution de la fabrique, l’option documentée --runtime-host fonctionne uniquement au premier plan et ne peut accompagner ni --detach ni --resume.

Pour un PRD, la commande documentée de préparation du backlog est :

Terminal
python factory/consumer.py run archon-backlog --input 'prd=docs/PRD.md' --input publication=approve

Remplacez docs/PRD.md, entre guillemets dans la commande, par le vrai chemin de votre PRD relatif à la copie de l’application. Examinez les tickets ordonnés proposés avant leur publication. Configurez l’hôte d’exécution selon le démarrage et le contrat d’identité déclarés par le premier ticket, puis faites passer ce ticket dans archon-lifecycle avec les parcours et les cas réservés préparés. Contrôlez le premier ticket aussi soigneusement que les suivants.

4. Évaluer les modifications et le résultat exécuté avant approbation

Conservez l’identifiant d’exécution renvoyé. Le programme de commande expose get <run-id> --json --events et status --all --json pour suivre l’avancement et les preuves. Comparez le ticket et le plan à MISSION.md ; lisez les modifications réelles de la demande de fusion et la revue indépendante de sa dernière révision ; vérifiez la CI exigée et le rapport sur les chemins protégés. Exécutez les parcours du produit sur la révision livrée et examinez les résultats natifs d’exécution et des cas réservés, identité du candidat comprise. Comparez le résultat utilisateur observé aux critères du ticket. Le réviseur doit renvoyer une demande déficiente pour réparation ; le README décrit archon-deliver --adopt <run id> pour une livraison retenue dans la file de fusion.

Seule une personne autorisée sur le dépôt doit approuver la fusion, une fois ces contrôles réussis. Le déploiement exige ses propres commandes de déploiement, de santé et d’identité, ainsi qu’une relecture de la révision après déploiement ; une demande fusionnée ne prouve pas un déploiement. Gardez la planification désactivée pendant ce premier ticket, puis décidez séparément d’activer ou non une exécution récurrente.

Les indications de coût du mainteneur ne donnent aucun prix fixe par exécution. Elles recommandent de mesurer les jetons dès le premier jour et d’observer les appels de modèles sur un petit ticket avant d’activer une boucle. Les frais dépendent du fournisseur, des modèles et des conditions du compte. BIG CHANGE n’a pas mesuré les dépenses de cette fabrique.

Une exécution active exige aussi une décision explicite d’arrêt. Dans le code du programme de commande, halt bloque les nouveaux lancements et les continuations, tandis que cancel <run-id> vise le travail actif. pause arrête les lancements du minuteur mais permet les réveils de travaux déjà en cours. Aucune de ces commandes ne dispense de vérifier l’état réel de l’exécution et les modifications du dépôt distant.

Sources et lectures complémentaires