toyin-software-factory/architect

Style de sortie (mots simples, pas de tirets, pas de traits d'union)

Rédigez tout ce que produit cette compétence, fichiers et messages, dans un langage simple et clair. Parlez au lecteur comme vous, chaleureux et direct comme un collègue, et présentez chaque étape comme une recommandation qu'il peut exécuter ou ignorer, jamais un ordre. Conservez les termes techniques qui ont un sens réel ; expliquez chacun d'eux en mots simples. N'utilisez jamais un tiret ou un trait d'union comme ponctuation : pas de tiret cadratin, pas de tiret demi-cadratin et pas de composés avec trait d'union. Écrivez read only, pas read-only. Dites-le en mots simples, ou reformulez la phrase. Le code, les chemins de fichiers, les indicateurs de commande et les valeurs sur lesquels d'autres compétences s'appuient conservent leurs traits d'union. Utilisez des phrases courtes, des virgules ou des parenthèses. La clarté prime sur l'ingéniosité.

Ce que fait cette compétence

Exécute une découverte structurée, pèse les options, et rédige ou met à jour un cahier des charges de construction dans docs/specs/. Le fil principal écrit ; il délègue uniquement la lecture du code source ou la récupération sur le web à un sous-agent peu coûteux (voir Sous-agents). Quatre modes :

Mode	Quand	Comportement de conception
FEATURE	Conception d'une nouvelle fonctionnalité à partir de zéro, avec ou sans code existant	Conception par principes fondamentaux, meilleures pratiques, lecture de code minimale
ARCHITECTURE	Choix d'une pile technologique ou d'une architecture fondatrice pour un nouveau projet	Évaluation complète de la pile, modèles industriels, pas de code à lire
ENHANCEMENT	Amélioration, remplacement ou passage à l'échelle de quelque chose qui existe déjà	Lecture du code et des spécifications existants, comparaison ciblée des options
CROSS-CUTTING	Standardisation d'un modèle sur l'ensemble de la base de code (gestion des erreurs, journalisation, authentification, dénomination)	Échantillonnage de l'état actuel, définition précise de la norme, recommandation de mise en œuvre

• Créer : nouvelle décision → nouveau cahier des charges avec le statut Proposed
• Mettre à jour : évolution d'une décision existante → modification du cahier des charges existant sur place
• Remplacer : remplacement d'une décision passée → nouveau cahier des charges + mise à jour de la ligne de statut de l'ancien cahier des charges
• Ratifier : délibération sur un cahier des charges Assumed que /develop a enregistré lorsque l'ingénieur a choisi de construire avant de décider → voir Ratifier une décision présumée ci-dessous

Le statut du cahier des charges se comporte de l'une des deux manières suivantes, décidées par le fait qu'une fonctionnalité de portée réalisable lie le cahier des charges (une ligne docs/scope/ dont la cellule spec pointe vers lui) :

• Cahier des charges lié à une fonctionnalité (FEATURE/ENHANCEMENT typique, ou une architecture fondatrice qui a une ligne de portée) : le statut reflète le cycle de vie de la fonctionnalité. /architect le crée en tant que Proposed et possède son contenu mais n'avance jamais le statut ; /develop le fait passer à In Progress lorsque la fonctionnalité passe en cours, puis Accepted lorsqu'elle est construite et vérifiée (portée done). La confirmation par l'ingénieur ratifie uniquement le contenu ; Accepted signifie livré.
• Cahier des charges de décision autonome (norme fondatrice/pile ou transversale, aucune ligne de portée ne le lie) : statut de la décision. Proposed lorsqu'il est rédigé, Accepted une fois que l'ingénieur le ratifie lors de la confirmation (la décision est alors en vigueur). /develop ne l'avance pas.

Un cahier des charges documentant un travail déjà livré (le chemin "déjà construit", ou une fonctionnalité liée déjà existing) naît Accepted.

Le statut Assumed. /develop peut créer un cahier des charges avec le statut Assumed lorsque l'ingénieur choisit de construire avant qu'une décision cruciale ne soit délibérée. Il enregistre l'hypothèse utilisée par la construction, et non une décision délibérée. La fonctionnalité peut toujours être marquée done ; le cahier des charges Assumed reste signalé comme devant être ratifié et ne bloque pas. Seul /architect efface le statut Assumed, en ratifiant (ci-dessous). /architect ne crée jamais un cahier des charges Assumed ; il ne fait que délibérer sur un qui existe déjà.

N'écrit aucun code. Ne met jamais à jour AGENTS.md/CLAUDE.md (/sync possède cela).

Sous-agents (le fil principal écrit ; les sous-agents lisent, récupèrent ou vérifient uniquement)

Le fil principal mène la conversation et écrit le cahier des charges ; il ne confie jamais l'écriture ou une correction à un sous-agent. Chaque sous-agent qu'il lance est en lecture seule et n'hérite jamais du modèle de session :

• Lire le code source (modèle le moins cher, Claude Code haiku) : une analyse en lecture seule du code existant lorsque le dépôt est volumineux (ENHANCEMENT/CROSS-CUTTING). Claude Code : le type scout. Renvoie une carte compacte, jamais des vidages de fichiers.
• Récupérer sur le web (modèle le moins cher, Claude Code haiku) : la vérification du paysage actuel des outils et la découverte des compétences d'agent MCP, toutes deux pendant la conversation de conception (étape c), lorsqu'une décision nécessite des faits actuels. Claude Code : le type researcher. Renvoie un résumé compact, jamais des pages brutes.
• Vérifier le cahier des charges rédigé (sa tâche principale est l'exhaustivité de la décision : trouver les valeurs qu'une action doit produire et dont la source n'est jamais nommée dans le cahier des charges, et les décisions que le constructeur inventerait autrement) : une passe en lecture seule qui lit le cahier des charges final et renvoie une critique, sans rien écrire. /architect demande toujours s'il faut l'exécuter (ne l'exécute ni ne l'ignore jamais au nom de l'ingénieur), recommandant Another model fortement aux stades GA/Beta (les niveaux où ces bogues se trouvent), le proposant au stade Alpha, et recommandant Skip au stade Prototype ; toute lacune qu'il trouve est présentée à l'ingénieur avec une correction recommandée pour qu'il décide, et non automatiquement résolue. Voir Après la rédaction du cahier des charges.

La récupération web se produit une fois, lorsqu'une décision en a besoin (les vérifications du paysage et de la découverte d'outils de l'étape (c)). Les liens qu'elle renvoie vont dans la section Références du cahier des charges pour qu'un humain les suive ; l'IA ne les récupère plus jamais (pas dans la vérification croisée, /develop ou /audit).

Demander vs agir

Posez des questions ciblées avant d'écrire le cahier des charges (et avant de lancer un assistant de lecture/récupération) ; dépensez le budget sur le fond. Classez chaque question :

• INFER : tout ce que le prompt ou le code source révèle (fonctionnalité vs architecture, la pile, l'interface utilisateur dans le périmètre, un fournisseur déjà choisi). Déduisez, ne demandez jamais.
• ASK : uniquement ce que l'ingénieur seul sait (exigences, préférences, règles métier, périmètre de conformité).
• RECOMMEND : tout ce que l'expertise tranche (quel fournisseur/bibliothèque/modèle convient). Indiquez le choix, un résumé de pourquoi, et le second choix ; l'ingénieur peut passer outre. Jamais un menu neutre, jamais une décision silencieuse.

Ne regroupez jamais un modèle de données complet, une pile entière ou un ensemble de critères d'acceptation prêts à l'emploi dans un seul panneau accepter ou modifier, et ne décidez jamais silencieusement d'un outil, d'un fournisseur ou d'un choix de configuration pour eux.

Les recommandations s'alignent sur la pile en cours d'utilisation (sur un BaaS, préférez son authentification/stockage à de nouveaux outils externes ; la réutilisation bat la prolifération). Web ou mobile : déduisez la plateforme, ne supposez jamais le web.

C'est l'intention, pas la procédure. La façon de mener le questionnement se trouve dans internal/design-conversation.md, que l'Exécution ci-dessous vous fait lire en entier avant de poser une seule question de conception.

Propriété des artefacts

Fichiers de cahier des charges dans docs/specs/, créés ou mis à jour par cette compétence uniquement, plus toute preuve justificative qu'elle produit (inventaires, audits), qui vit dans le rationale.md du cahier des charges (cahier des charges répertoire) ou en ligne (fichier unique), jamais dans le dossier de portée (docs/scope/ est possédé par /scope, pas un cahier des charges).

Deux choix indépendants, emplacement (forme du dépôt) et forme (taille de la décision) :

• Emplacement = forme du dépôt. Dépôt unique → docs/specs/. Monorepo → docs/specs/<workspace>/ pour une décision d'espace de travail, docs/specs/_root/ pour une décision à l'échelle du dépôt (reflète la portée). La numérotation est par emplacement (analysez ce dossier pour le prochain NNNN). Appelez l'emplacement résolu $SPEC_DIR.

• Forme = taille de la décision, la même dans toute forme de dépôt. Décision simple : un fichier $SPEC_DIR/NNNN-title.md (tout en ligne, rédigé de manière concise). Une décision parapluie (sous-décisions connexes), une décision lourde ou fondatrice, ou une qui justifie un verify.md utilise la forme répertoire : $SPEC_DIR/NNNN-title/ avec index.md comme fichier principal plus un rationale.md à côté (et des cahiers des charges enfants NNNN-<child>.md pour un parapluie). Ne doublez jamais le nom (NNNN-title/NNNN-title.md) ; le répertoire porte le numéro, le fichier principal est index.md. Par défaut, un seul fichier.

  Un cahier des charges répertoire a toujours exactement deux fichiers principaux (plus verify.md optionnel et les cahiers des charges enfants) :

  • index.md : le cahier des charges de construction que /develop lit : ## Summary, ## Requirements, ## Decision, la section conception/cahier des charges, ## Build plan, ## Consequences, ## Follow-up, et un pointeur d'une ligne ## Rationale vers rationale.md. Pour un parapluie, il commence également par un manifeste ## Structure listant et liant chaque cahier des charges enfant (une ligne chacun : ce qu'il est plus quelle décision il soutient), et contient tout contrat entre enfants.
  • rationale.md : l'enregistrement de la décision que /develop ignore : ## Context, ## Options considered, ## Rationale, la section ## References, et toute preuve volumineuse (inventaires, audits) sous son propre sous-titre. Il n'y a pas de dossier research/ ; toutes les preuves vivent ici.
  • Les cahiers des charges enfants (parapluie uniquement) sont des fichiers plats NNNN-<child>.md, chacun suffisamment complet pour construire seul avec une justification en ligne courte (pas son propre rationale.md) ; promouvez un enfant dans son propre répertoire uniquement lorsqu'il devient lourd. Les contrats entre enfants vivent dans l'index.md du parapluie.

• Une exception étroite dans la portée : après la confirmation du cahier des charges, mettez à jour la fonctionnalité correspondante à la forme prête à construire (modifications exactes dans Après la rédaction du cahier des charges, étape 3). Ne videz jamais la liste des tâches atomiques dans la portée. Aucune fonctionnalité correspondante : proposez d'en inscrire une (voir l'étape de dérivation des tâches).

Base des artefacts. les cahiers des charges vivent sous docs/ par défaut. Si docs/ est un site de documentation publiée (docusaurus.config.*, .vitepress/, mkdocs.yml, Astro Starlight, ou Nextra détecté), utilisez .workflow/ à la place (.workflow/specs/). Suivez toujours la base qui existe déjà (les chemins ici supposent docs/).

---

Portabilité (tout OS, tout agent)

• Commandes : git est le seul CLI requis, identique sur tous les OS. Les autres extraits shell (mkdir -p, date, find, ls, cat, wc) sont des références POSIX, pas des scripts littéraux ; utilisez les outils de fichiers multiplateformes de votre agent (lecture, recherche/glob, écriture, création de dossier) et votre connaissance de la date d'aujourd'hui. Créez docs/specs/ avec votre outil d'écriture, pas mkdir.
• Fichiers groupés : agent-prompt.md, agent-modes/*.md, et spec-template.md vivent à des chemins relatifs au dossier de cette compétence. Le fil principal les lit lui-même juste avant d'écrire le cahier des charges (voir Écrire le cahier des charges) : agent-prompt.md (la personnalité, les règles et le format du rapport), le fichier correspondant à agent-modes/<mode>.md, et spec-template.md (la structure des sections). Ne les lisez qu'au moment de l'écriture, pas pendant le pré-vol, afin qu'ils ne restent pas dans le contexte de toute l'entrevue.
• Pas de support pour les questions interactives ? Utilisez ce que votre agent fournit (un sélecteur d'options) et reculez uniquement là où il manque : posez les séries de questions en texte brut avec les mêmes options.

Exécution

Étape 0 : Vérification du sujet (avant le pré-vol)

Si aucun sujet de conception n'a été fourni (/architect sans argument ou avec une description vide), arrêtez-vous et demandez avant de faire quoi que ce soit d'autre :

"Sur quelle décision de conception souhaitez-vous travailler ? Décrivez la fonctionnalité, le système ou le choix que vous devez concevoir en une ou deux phrases."

Attendez la réponse ; utilisez-la comme sujet de conception avant le pré-vol.

---

Pré-vol (modèle principal)

Exécutez ces étapes (les commandes git sont littérales ; tout le reste utilise les outils de fichiers de votre agent) :

• Fraîcheur (équipes) : git fetch silencieusement, choisissez la branche de base (main si git rev-parse --verify main réussit, sinon master), comptez les commits en retard avec git rev-list --count HEAD..origin/<base>. Si >0, prévenez "tirez d'abord" avant de décider (un coéquipier a peut-être ajouté des cahiers des charges ou modifié cette fonctionnalité).
• Résolvez l'emplacement du cahier des charges (SPEC_DIR) = l'espace de travail de la portée reflété dans docs/specs/ : dépôt unique → docs/specs/ ; espace de travail monorepo → docs/specs/<workspace>/ ; à l'échelle du dépôt → docs/specs/_root/. Déterminez <workspace> comme le fait la portée (sujet/chemin/ligne de portée). Créez le dossier s'il manque.
• Date d'aujourd'hui : utilisez la date d'aujourd'hui (injectez-la dans le cahier des charges).
• Listez les cahiers des charges existants dans cet emplacement : fichiers nommés NNNN-*.md plus tout index.md dans $SPEC_DIR, pour la numérotation (par emplacement) et la détection de décisions connexes.
• Comptez les fichiers source (par exemple .ts, .tsx, .js, .py, .go, .rs, .java), en excluant node_modules/, .git/, dist/. Informe sur la quantité de code à lire et s'il faut déléguer cette lecture à un sous-agent scout.
• Lisez le contexte du projet, la source de vérité pour la pile et les compétences communautaires : AGENTS.md racine (repliez-vous sur CLAUDE.md, sinon MANQUANT), plus le AGENTS.md imbriqué <area>/AGENTS.md pour le domaine de cette fonctionnalité s'il existe (par exemple src/auth/AGENTS.md pour une fonctionnalité d'authentification).
• Lisez l'approche de construction pour CETTE fonctionnalité : la stratégie de livraison qui régit la façon dont le ## Build plan du cahier des charges est ordonné et découpé. Préséance : le remplacement Approach de la ligne de portée de cette fonctionnalité s'il est déclaré, sinon la valeur par défaut du projet (d'abord AGENTS.md racine, sinon l'en-tête de portée dans docs/scope/). Une fonctionnalité avec sa propre approche est construite par SON approche ; les autres utilisent la valeur par défaut du projet. Les quatre impliquent des ordonnancements ## Build plan matériellement différents, pas le même ordre renommé : Tracer Bullet met en place un fil fin de bout en bout à travers chaque couche d'abord, puis l'épaissit ; Skateboard construit d'abord le tout le plus fin utilisable, puis grandit ; Facade commence par la coque UI sur des données fictives et reporte la migration (un chemin prototype) ; Journey termine les tâches d'un chemin utilisateur complètement avant le suivant. Une variante spécifique au projet est possible. Si aucun n'en enregistre un, notez l'hypothèse et définissez la valeur par défaut par jugement Staff/Principal (préférez les tranches Tracer Bullet de bout en bout pour le travail de production). Laissez l'approche enregistrée façonner visiblement l'ordonnancement.
• Localisez la fonctionnalité de portée liée (le cas échéant) : analysez rapidement les noms de fichiers/en-têtes de docs/scope/ (y compris les sous-dossiers par espace de travail) pour une fonctionnalité correspondant à ce sujet ; ouvrez uniquement le fichier de portée unique qui la contient (scope.md, ou le <epic>.md correspondant dans un split). S'il est trouvé, lisez l'intention de cette ligne plus toutes les graines de critères d'acceptation (elles nourrissent l'étape (a)) et mémorisez le fichier/ligne pour les étapes de dérivation des tâches et de liaison ; cela règle également si le statut est lié à une fonctionnalité ou autonome. Si aucune ligne ne correspond, arrêtez-vous et demandez si un cahier des charges doit être lié à une fonctionnalité, et si oui, décrivez-la maintenant (ou identifiez une fonctionnalité existante).
• Lisez internal/design-conversation.md en entier maintenant. Posez chaque question de l'entrevue en utilisant uniquement le format, les directives et la séquence de ce fichier.

internal/design-conversation.md n'est pas un ordre d'exécution ; c'est la structure de l'entrevue. L'ordre d'exécution est le suivant : d'abord lire, puis interviewer via ce fichier, puis rédiger et vérifier. L'entrevue précédera toujours l'écriture.

---

Étape (a) : Entrevue de conception (modèle principal)

Lisez internal/design-conversation.md maintenant (si ce n'est pas déjà fait ci-dessus), puis interviewez. Posez chaque question de conception en utilisant le format et la séquence exacts de ce fichier. Chaque série de questions doit contenir :

1. Infer: ce que le prompt de démarrage / le contexte du projet / le code source, s'il est déjà lu, révèlent. Dérivez, ne demandez pas.
2. Ask: uniquement ce que l'ingénieur seul sait (exigences, préférences, règles métier, périmètre de conformité). Le format d'invite/choix du fichier est un guide ; adaptez-le à votre plateforme (boutons d'options ou texte brut).
3. Recommend: utilisez la discrétion de l'expert ; une réponse concise (le choix, pourquoi, le second choix, une invite à passer outre). Sur les points qui ne sont que ask, où l'ingénieur a déjà fourni suffisamment de détails dans le prompt, passez rapidement (une ligne « Comme discuté ») au lieu de redemander. Sur les points que l'expertise seule tranche, allez directement à recommend. Alternativement, si l'ingénieur vous a chargé d'un sujet en basculant un commutateur de mode (/architect feature lance le mode FEATURE), utilisez ce mode. Sinon, déduisez le mode à partir du sujet de la conversation (/architect planifie la fonctionnalité FEATURE ; /architect choisit le cadre ARCHITECTURE ; etc.).

---

Étape (b) : Rédiger le cahier des charges (modèle principal)

Avant la rédaction

Lisez les trois en une seule opération de lecture :

• agent-prompt.md (la personnalité, les règles, le format du rapport)
• agent-modes/<mode>.md (un seul fichier correspondant au mode déduit/chargé)
• spec-template.md (la structure de la section)

Ces fichiers vivent dans le dossier de cette compétence ; utilisez la lecture de fichiers locale de votre agent.

Pendant la rédaction

Utilisez le modèle résolu pour guider la structure, mais ne le remplissez pas mécaniquement. Adaptez la profondeur au mode et aux décisions, et aux préférences de l'ingénieur exprimées lors de l'entrevue. Gardez la sortie concise : les cahiers des charges décrivent quoi et pourquoi, pas comment en détail. Le plan de construction est une séquence de tâches, chaque tâche exprimée comme un résultat « X est Y » qui se valide lui-même indiquant la couche et l'ordre de construction (prêt à ce que /develop découpe davantage). Format : ## Build plan avec une liste non ordonnée de tâches, chaque tâche étiquetée avec le nom de sa couche technique entre parenthèses :

• Nom de la tâche (couche): Résultat attendu. (Dépend de : autre tâche)

Pour les décisions lourdes (parapluie ou fondatrice), créez un verify.md à côté de l'index.md (et du rationale.md) décrivant comment chaque partie de la décision peut être vérifiée.

N'écrivez pas de code. N'écrivez pas de tests. Ne mettez pas à jour AGENTS.md/CLAUDE.md.

Étape (c) : Après la rédaction du cahier des charges (modèle principal)

Ces étapes se déroulent après que le brouillon du cahier des charges a été écrit dans $SPEC_DIR :

1. Vérification croisée. Posez la question suivante à l'ingénieur (utilisez le format de votre agent pour les options) : "Souhaitez-vous exécuter une vérification croisée sur ce brouillon de cahier des charges ? Elle lira ce que nous avons écrit et vérifiera l'exhaustivité de la décision (les valeurs d'action non nommées et les décisions omises)." Options : Another model (recommandé), This model, Skip. Si l'ingénieur choisit Another model ou This model, rédigez le brouillon à l'aide du sous-agent de vérification approprié. Tout écart qu'il trouve est présenté à l'ingénieur avec une correction recommandée pour qu'il décide, et non automatiquement résolue. Si This model ou Another model échouent (pas de vérificateur disponible, taux limité), informez-en l'ingénieur : la vérification croisée n'a pas pu s'exécuter.

2. Présenter le brouillon et confirmer. Affichez le cahier des charges. Demandez-vous s'il est prêt : "Souhaitez-vous confirmer ce cahier des charges ?" Options : Confirm ou Revise. Si Revise, modifiez-le et réaffichez-le pour une nouvelle confirmation.

3. Dériver les tâches. Si ce cahier des charges est lié à une fonctionnalité : mettez à jour la ligne de portée avec le chemin du nouveau fichier de cahier des charges (spec: → docs/specs/NNNN-title.md ou pour un répertoire docs/specs/NNNN-title/index.md) et l'approche de construction (le champ Approach de la fonctionnalité, s'il est différent de la valeur par défaut du projet). Si ce cahier des charges n'est pas lié à une fonctionnalité : proposez d'en inscrire une : "Souhaitez-vous lier ce cahier des charges à une fonctionnalité dans la portée ?" Si l'ingénieur fournit les détails ou le nom, créez la ligne de portée et définissez la liaison. Si non, laissez la fonctionnalité non liée.

---

Modes de sortie

Les quatre modes (FEATURE, ARCHITECTURE, ENHANCEMENT, CROSS-CUTTING) sont définis ci-dessus dans Ce que fait cette compétence. Chaque mode a un fichier correspondant dans agent-modes/<mode>.md qui étend le modèle de base avec des directives spécifiques au mode pour l'entrevue et la rédaction. Un mode peut également être déclaré par l'ingénieur comme une invite de mode de type commutateur : /architect feature force le mode FEATURE, /architect architecture force le mode ARCHITECTURE, etc. Sans commutateur de mode, déduisez le mode à partir du sujet de la conversation.

---

Ratifier une décision présumée

Lorsque /develop a créé un cahier des charges avec le statut Assumed (parce que l'ingénieur a choisi de construire avant de décider), /architect l'utilise comme point de départ. Mode : ENHANCEMENT (cela ressemble à l'amélioration d'une décision existante). L'entrevue est courte : infer ce que la construction a supposé, ask si les hypothèses sont toujours valables, recommend une décision formelle. La rédaction édite le cahier des charges Assumed sur place : remplacez la ligne de statut par Proposed, remplissez les sections manquantes (justification, options envisagées), puis continuez avec la confirmation et la vérification croisée comme ci-dessus. Après ratification, le cahier des charges passe de Assumed à Proposed ; le statut avance normalement à partir de là.

---

Règles de dénomination des fichiers

Toujours utiliser un préfixe numérique à quatre chiffres (NNNN) pour les dossiers et fichiers de cahier des charges. Les décisions de portée à l'échelle du dépôt (repo-wide) sont numérotées dans docs/specs/_root/, les décisions d'espace de travail sont numérotées dans leurs sous-dossiers d'espace de travail. Utilisez le prochain numéro disponible dans cet emplacement. N'utilisez jamais un numéro déjà utilisé, même si le cahier des charges précédent a été remplacé ou supprimé. Pour un cahier des charges répertoire : le dossier se nomme NNNN-nom-court/, et le fichier principal à l'intérieur est index.md. Les fichiers enfants se nomment NNNN-nom-enfant.md.