tomtdhzz/requirement-orchestrator

Requirement Orchestrator

Transformez une demande logicielle en un travail indépendamment vérifiable tout en gardant un seul agent de contrôle responsable du périmètre, des dépendances, des preuves et de l'intégration. Cette compétence est un orchestrateur, pas un générateur de prompts.

Sélectionner un mode sémantique

• analyze : étudier la demande et la base de code, maintenir le registre et produire un plan d'exécution sans modifier le code. C'est le mode par défaut lorsque l'implémentation n'a pas été demandée.
• diagnose : reproduire et expliquer un échec signalé, en séparant la cause racine confirmée, les preuves, les inconnues et les pistes de réparation recommandées. Le diagnostic est le livrable ; ne modifiez pas le code.
• execute : envoyer des travaux délimités, examiner les résultats renvoyés et terminer l'intégration. N'entrez que lorsque l'utilisateur a autorisé l'implémentation ou l'exécution.
• challenge : tester une exigence, une décomposition ou une conception existante pour les omissions et les risques sans modifier son objectif de produit confirmé. Voir references/challenge.md.

Ce sont des modes sémantiques au niveau de la compétence. Ils n'invoquent ni n'exigent le mode Plan natif d'une plateforme, EnterPlanMode ou des agents Explore/Plan obligatoires. Utilisez les modes natifs uniquement lorsqu'ils sont indépendamment utiles et compatibles avec les contraintes de l'utilisateur.

Pour une tâche à cause racine unique sans délégation, utilisez directement la boucle de contrôle. Lisez references/spec-driven.md pour façonner la spécification (exigences, scénarios d'acceptation, contrats). Lisez references/context-grounding.md avant de décomposer dans une base de code existante. Lisez references/decomposition.md lorsqu'il y a plus d'une tâche candidate, une limite de service/domaine, une décision de planification ou un échec de construction/déploiement où l'état du dépôt peut être causal. Lisez references/verification.md pour les normes de preuve d'acceptation. Lisez references/ledger.md lorsque le travail implique plusieurs tâches, agents, sessions ou plateformes. Lisez references/mutation.md lorsque l'exécution réécrit, supprime ou propage un changement sur plus d'un artefact existant, ou écrit dans un système externe. Exécutions effectuées : references/examples/feature-example.md et references/examples/bug-example.md.

En mode diagnose, signalez l'échec observé ou reproduit, la cause racine confirmée et les preuves, les éléments non vérifiés, l'impact et les pistes de réparation recommandées. Arrêtez-vous là, sauf si l'utilisateur autorise séparément execute.

Boucle de contrôle

1. Établissez l'objectif, le périmètre, les critères d'acceptation, les contraintes et les faits de code vérifiés. Définissez d'abord les inconnues (references/context-grounding.md), puis exprimez le résultat sous forme de spécification — exigences, scénarios d'acceptation et contrats (references/spec-driven.md). Enquêtez sur les faits découvrables ; interrogez l'utilisateur uniquement pour les décisions qui affectent matériellement le périmètre, l'acceptation ou la direction. Avant de décomposer, consultez la base de connaissances des capacités (voir references/knowledge-base.md) pour extraire les compétences existantes pertinentes pour l'objectif et une comparaison dans le même domaine ; préférez réutiliser ou importer une capacité connue plutôt que de rechercher à partir de zéro, et enregistrez les capacités choisies dans le registre.
   • Lisez les leçons de projet antérieures si elles sont présentes (references/experience.md) et traitez-les comme des faits candidats à vérifier, pas comme une vérité absolue.
   • Pour une construction non triviale, après la spécification, produisez une conception technique (references/tech-design.md) — architecture, conception détaillée, alternatives, préoccupations transversales — et persistez les artefacts sous la disposition docs/ (references/deliverables.md).
2. Pour un bogue ou un échec signalé, tentez une reproduction proportionnée locale avant de revendiquer une cause racine. Comparez l'échec observé avec le rapport. Tant qu'il n'est pas reproduit ou soutenu par des preuves directes équivalentes, étiquetez les déclarations de cause racine comme des hypothèses et indiquez ce qui reste non vérifié.
3. Choisissez un axe de décomposition principal et créez des tâches délimitées. Dérivez les contrats partagés et figez-les avant les travaux dépendants ou parallèles (references/spec-driven.md). Enregistrez explicitement les dépendances et les contrats inter-tâches. Reflétez les groupes de tâches résultants dans un TODO phasé (voir Surface de progression).
4. Gardez exactement un agent de contrôle. Le contrôleur possède le registre, les décisions d'envoi, l'état de la révision, la re-planification et l'intégration finale.
5. N'envoyez que des tâches avec un contrat complet. Lisez references/agent-contract.md avant le premier envoi. Avant d'envoyer des écritures vers un système autre que l'arbre de travail local, exécutez la vérification préalable du système cible ci-dessous.
6. Acceptez un résultat de travailleur dans review, vérifiez ses preuves et ses limites par rapport aux normes de preuve d'acceptation (references/verification.md), puis marquez-le completed ou renvoyez-le avec des constatations spécifiques. Pour une mutation en masse ou externe, vérifiez par une relecture indépendante et un delta structurel, pas par le nombre de succès signalé par l'outil.
7. Recalculez les dépendances affectées après les découvertes, les échecs ou les changements de périmètre. Retravaillez la branche affectée la plus petite.
8. Déclarez la demande terminée uniquement après que les vérifications au niveau des tâches, les contrats inter-tâches et chaque scénario d'acceptation réussissent ensemble ; la porte de bout en bout est définie dans references/verification.md. Une fois terminé, ajoutez toutes les leçons spécifiques au projet qualifiantes au journal des expériences (references/experience.md). Améliorer la compétence elle-même à partir de l'exécution est une action facultative distincte — proposée uniquement lorsqu'une leçon est générale et récurrente, appliquée uniquement si l'utilisateur la choisit, jamais automatique (voir references/experience.md).

Surface de progression

Maintenez un TODO phasé visible synchronisé avec le registre afin que l'utilisateur voie les phases et la progression au niveau des étapes, pas seulement du texte. Le registre reste la source de vérité détaillée (dépendances, périmètres, contrats, preuves) ; le TODO phasé est sa vue de progression.

• Initialisez une phase par groupe de décomposition, puis une phase d'acceptation finale (pour un flux de bogue, 对照 / 修复 / 验证 ; pour un flux de fonctionnalité, les groupes de fonctionnalités suivis de 全量验收). Chaque élément est une tâche délimitée ou une étape de vérification, formulée comme un résultat en 5 à 10 mots.
• Pilotez-la avec la liste de tâches native de la plateforme, jamais avec un arbre formaté à la main. Sur Claude/omp, utilisez l'outil todo : init avec list: [{phase, items}], puis start/done par élément. Sur Codex, utilisez son mécanisme plan/update-plan.
• Faites avancer l'état à partir de progrès réels : marquez un élément en cours lorsque sa tâche est envoyée, et terminé seulement après que le contrôleur enregistre completed dans le registre. Les compteurs de phase (N/M) suivent alors l'acceptation vérifiée, pas l'envoi.
• Gardez les deux cohérents : un élément TODO correspond exactement à une tâche de registre ou une étape de vérification. Recalculez les deux ensemble lors de la re-planification.
• En mode analyze et diagnose, les phases sont des étapes d'investigation ou de diagnostic et leur achèvement ne modifie aucun code.

Artefacts livrables

Séparez les documents publiables de l'état d'orchestration interne : les documents destinés aux lecteurs vont sous docs/ (spécification docs/prd/, conception docs/tech-design/) ; le registre, le plan et les leçons sont un état de travail interne sous .ai-work/ — jamais sous docs/, et dans gitignore pour un projet publiable. Voir references/deliverables.md.

Pour toute construction non triviale, produisez une conception technique après la spécification et avant execute : architecture, conception détaillée, alternatives envisagées et préoccupations transversales (references/tech-design.md). Ignorez-la pour une correction à cause racine unique où la spécification plus une liste de tâches suffit.

Révisez vous-même chaque livrable Markdown généré avant la remise : relisez-le et confirmez qu'il s'affiche comme le lecteur le verra — structure intacte, blocs fenced/Mermaid effectivement analysés (affichez-les, ne regardez pas), liens résolus. Un échec d'analyse/d'affichage est un défaut à corriger maintenant. Voir references/deliverables.md et la ligne Document / diagram artifact dans references/verification.md.

Lorsque le livrable est un projet autonome, « terminé » inclut le fait d'être publiable : un README (quoi/pourquoi, prérequis, installation, exemples d'utilisation, configuration, architecture, test, limitations, licence, avertissement), une LICENSE et un .gitignore qui exclut la sortie de construction, les secrets et .ai-work/. Vérifiez que les commandes du README s'exécutent réellement. Voir references/deliverables.md.

Vérification préalable du système cible

Avant d'envoyer des écritures vers un système autre que l'arbre de travail local — un wiki, un système de tickets, une base de données ou une API distante — vérifiez au préalable :

• l'autorisation d'écriture et le périmètre exact dont les opérations prévues ont besoin, y compris la suppression ou le déplacement si le plan l'exige ;
• les limites de taux et si les échecs sont silencieux ; choisissez une concurrence sûre et une nouvelle tentative ou un backoff ;
• que le résultat peut être relu pour vérification.

Découvrez une capacité manquante ici, pas en milieu de lot. Si une autorisation ou un périmètre requis est indisponible, traitez-le comme un blocage : indiquez exactement ce qui manque et la plus petite concession qui débloque, et arrêtez-vous avant toute application partielle.

Routage des plateformes

• Pour Codex, lisez references/codex-adapter.md.
• Pour Claude, lisez references/claude-adapter.md.
• Lors du transfert de contrôle entre eux, écrivez et confirmez un instantané de remise avant que l'ancien contrôleur n'arrête d'envoyer.
• Trellis est facultatif. Lisez references/trellis-adapter.md uniquement lorsque ses signaux d'escalade s'appliquent ou que l'utilisateur le demande.

Limites non négociables

Ce sont des invariants de type NE DOIT PAS quel que soit le libellé ; gardez-les peu nombreux et précis. Ailleurs dans cette compétence, graduez la force des règles avec les mots-clés RFC 2119 — DOIT / DEVRAIT / PEUT, significatifs uniquement en majuscules — et utilisez la retenue : réservez DOIT / NE DOIT PAS pour l'exactitude ou le préjudice, laissez les préférences comme DEVRAIT / PEUT. Associez chaque interdiction avec le « faites plutôt » positif : pour les agents, les règles uniquement négatives sont peu fiables (elles signalent le comportement même qu'elles interdisent), donc un petit ensemble de limites strictes plus des valeurs par défaut positives est la forme robuste, pas une liste de contrôle obligatoire sans cesse croissante.

• Ne traitez pas la position dans l'arbre des tâches comme une dépendance d'exécution.
• Ne laissez pas les travailleurs étendre silencieusement leur périmètre d'écriture.
• N'exécutez pas d'agents d'écriture en parallèle à moins que les dépendances ne soient résolues, les périmètres d'écriture ne se chevauchent pas, les contrats partagés ne soient figés et la validation ne soit indépendante.
• Un travailleur peut soumettre un travail pour révision ; seul le contrôleur peut le marquer terminé.
• Lorsque vous modifiez des artefacts existants, ne videz pas et ne réécrivez pas quoi que ce soit que la tâche n'a pas créé et ne peut pas régénérer ; insérez ou corrigez sur place, marquez-le avec un marqueur de réexécution sûr, et vérifiez par une relecture indépendante.
• N'affirmez pas une valeur dérivée — une classification, une étiquette, un résumé, une évaluation de risque ou une recommandation — au-delà de sa source vérifiée ; marquez une dérivation non vérifiée comme telle plutôt que de fabriquer une valeur.
• N'activez pas Trellis simplement parce que .trellis/ existe.
• analyze et diagnose sont en lecture seule. Une autorisation de plateforme ou une approbation de plan natif n'autorise pas les modifications. Entrez execute uniquement après qu'une instruction utilisateur distincte autorise l'implémentation.
• Ne remettez pas un livrable sans le consommer comme son lecteur le fera — affichez le document et exécutez les commandes README/usage depuis la racine du dépôt exactement comme écrites. (Faites plutôt : affichez les diagrammes, exécutez les commandes, corrigez les ruptures avant la remise.)
• N'appelez pas un projet autonome terminé sans un README fonctionnel, une LICENSE et un .gitignore, ou avec des artefacts internes .ai-work/ validés. (Faites plutôt : livrez l'échafaudage publiable ; gardez l'état d'orchestration hors du dépôt.)