amorçage

Vous installez (ou rétrofitez) un ensemble de conventions axées sur la documentation dans le dépôt actuel. L'état final est un dépôt qui peut être piloté à la fois par des humains et des agents de codage à partir d'un petit ensemble de fichiers canoniques. Reprenez le mécanisme décrit ici — rien concernant un autre projet.

Étape 1 — Détecter la situation

Inspectez le dépôt avant de poser des questions. Réutilisez les réponses explicites et les approbations déjà fournies dans cette session ; ne les remplacez jamais par des profils par défaut ni ne les redemandez. Avant d'écrire, résumez la racine d'artefact résolue, la profondeur, la file d'attente, la porte et les modes de coordination/intégration par rapport à ces réponses. Si un hôte reflète un dossier sélectionné dans un bac à sable, identifiez le chemin cible réel et comment les sorties vérifiées atteignent le dossier sélectionné ; ne considérez jamais une cible intacte comme complète simplement parce qu'un miroir de test a réussi.

Dépôt vierge (pas de source, pas de documentation) : vous échafaudez à partir de zéro.
Dépôt existant : vous rétrofitez.
- Lisez tout README.md, CONTRIBUTING.md, AGENTS.md, CLAUDE.md, docs/, adr/, .github/ actuels avant de proposer des modifications.
- Préservez le contenu existant. Fusionnez, n'écrasez pas. Si les conventions existantes sont en conflit avec celles ci-dessous, signalez le conflit dans votre résumé d'évaluation.
- Si des ADR existent déjà dans un autre format, proposez un plan de migration (renumérotation, conservation, traduction) plutôt que de créer une arborescence parallèle.
Dépôt déjà docflow (contient AGENTS.md + CONVENTIONS.md + un catalogue ADR) : vous ajoutez à une configuration existante, pas d'échafaudage. Ne pas ré-échafauder le cœur ni redemander les questions réglées — lisez les choix enregistrés dans CONVENTIONS.md/AGENTS.md (forme ADR, cycle de vie des statuts, racine d'artefact, mode multi-agent, et quelles couches optionnelles existent déjà). Proposez ensuite d'activer toute couche optionnelle désactivée encore absente — plan/, _agent/, GLOSSARY.md, domains/, ou la deuxième forme ADR (le modèle technique) — et écrivez uniquement celles choisies, par fusion, sous la racine d'artefact enregistrée, en laissant tout le reste intact. Posez uniquement les questions nécessaires aux nouvelles couches (par exemple, la question de coordination lors de l'activation de _agent/ — où un seul rédacteur sans à la fois une porte de vérification enregistrée et une file d'attente de plan se retrouve sans _agent/ du tout, et la couche n'est tout simplement pas nécessaire). Ceci est le point d'entrée pour ajouter une couche que vous avez différée lors du premier amorçage. Un dépôt contenant toujours des fichiers de coordination qu'un échafaudage antérieur a écrits les conserve : laissez-les en place ici et laissez la compétence d'audit signaler la disposition.

L'activation de GLOSSARY.md écrit le squelette canonique, jamais une réécriture. Lorsque la couche est choisie et que le fichier est absent, écrivez-le à partir de templates/GLOSSARY.md — l'en-tête et le prose optionnels, puis le tableau Terme | Définition enregistré dans CONVENTIONS.md §Glossaire généré. Si le fichier existe déjà, laissez-le intact : l'activation de la couche n'ajoute rien, et add-convention étend le fichier existant dans la forme canonique ou audit propose une migration consentie.

L'activation de la deuxième forme ADR est un changement de schéma, pas une copie de fichier. C'est la seule couche différée qui modifie un choix déjà enregistré, donc écrivez-la en une seule fois ou pas du tout : remplacez §Formes ADR dans CONVENTIONS.md par le texte à deux formes, ajoutez les puces d'ordre de section technique et de forme à AGENTS.md, écrivez adr/0000-template-technique.md, et régénérez INDEX.md avec la colonne Forme. Les ADR existants conservent leurs numéros et restent des capacités — un champ shape: absent signifie déjà capacité, donc aucun ADR n'est réécrit et rien n'est renuméroté. La moitié du changement laisse le dépôt dans l'état que la vérification croisée de l'Étape 4.5 appelle une contradiction : un modèle technique qu'un schéma à forme unique ne sélectionnera jamais.

Un dépôt déjà sur l'encodage d'intervalle hérité reçoit l'offre de migration à la place. Certains dépôts à deux formes ont été échafaudés avant que la forme ne devienne un champ déclaré et l'encodent dans le numéro : §Formes ADR enregistre un seuil (capacité en dessous, technique à ou au-dessus), et adr/ contient un modèle numéroté autre que 0000 (par exemple, adr/0100-modèle.md. L'un ou l'autre signal seul l'identifie. Un tel dépôt n'a pas de couche manquante — il a déjà les deux formes — donc ne proposez pas le changement de schéma ci-dessus, qui le laisserait avec deux encodages rivaux. Proposez la migration vers le champ déclaré, aux mêmes conditions que la compétence d'audit utilise :
- Affichez d'abord la carte des anciens vers les nouveaux numéros, comme un essai à blanc : les ADR de capacité conservent leurs numéros ; les ADR techniques prennent les numéros suivant le plus grand ADR de capacité, dans leur ordre relatif d'origine. À côté, listez les références qui suivent (dépend-de, remplace / remplacé-par, les liens relatifs adr/NNNN-*.md, INDEX.md, les listes README.md de domaine, les lignes ADR propriétaire dans plan/todo/) et ce qui reste comme historique (pieds de page plan/fait/, messages de commit, étiquettes).
- N'écrivez rien sans une confirmation explicite de cette carte. Refuser est un résultat valide : le dépôt conserve l'encodage d'intervalle et continue de passer ses propres règles.
- Sur confirmation, appliquez la migration exactement comme l'audit de la compétence l'étape de migration spécifie — renumérotez, apposez shape: sur chaque ADR, réécrivez chaque référence dans le catalogue, remplacez le modèle de limite avec adr/0000-modèle-technique.md, réécrivez §Formes ADR vers le champ déclaré et supprimez toute clause d'exception d'ADR de référence, régénérez INDEX.md avec la colonne Forme — et atterrissez-le comme un commit dont le message liste chaque paire ancien-nouveau. Cette procédure est la seule source de vérité ; ne paraphrasez pas une seconde variante ici.
- Continuez ensuite la ré-exécution normalement pour les couches qui sont vraiment absentes (plan/, _agent/, GLOSSARY.md, domaines/).

Indiquez dans une ligne la situation qui s'applique avant de poser les questions d'évaluation.

Étape 2 — Disposition cible

<repo>/
  AGENTS.md              # règles strictes pour les agents de codage — point d'entrée
  CLAUDE.md              # une ligne : @AGENTS.md
  README.md              # résumé du projet pour les humains (préserver si existe)
  CONVENTIONS.md         # règles de rédaction : ADR, nommage, statut, audit, git
  INDEX.md               # tableau généré de tous les ADR
  GLOSSARY.md            # termes partagés (optionnel — voir Q7)
  adr/
    0000-modèle.md       # modèle ADR de capacité (toujours)
    0000-modèle-technique.md  # modèle ADR technique (uniquement si deux formes — voir Q2)
    NNNN-kebab-slug.md   # un ADR par décision, numérotation contiguë
  domains/<slug>/README.md   # optionnel (voir Q7)
  plan/
    README.md
    to-do/NNNN-slug.md
    fait/<AAAA-MM-JJ>-slug.md
  _agent/                # le contrat de fonctionnement de l'agent (voir Q5) — optionnel
    ROLES.md             # qui écrit quoi (plusieurs rédacteurs uniquement)
    LOCKS.md             # le mutex de revendication de fichier (checkout partagé uniquement)
    promps/autonome.md   # comment se comporte une exécution sans surveillance (uniquement avec une
                         #   porte de vérification — Q8 — ET une file d'attente de plan — Q4a)
  fédération.md          # multi-dépôt uniquement (Q11) : pointeur de retour de ce dépôt
  index-fédération.md    # multi-dépôt uniquement (Q11) : index des membres — dépôt d'accueil uniquement

Emplacement. L'arborescence ci-dessus montre l'option racine. AGENTS.md et CLAUDE.md se trouvent toujours à la racine du dépôt ; adr/, plan/, _agent/, INDEX.md et CONVENTIONS.md vont sous la racine d'artefact choisie en Q12 (par défaut .docflow/, par exemple .docflow/adr/, .docflow/plan/).

Découverte. Les outils localisent la racine d'artefact sans lire CONVENTIONS.md en premier : un dossier .docflow/ à la racine du dépôt est la racine ; pour toute autre racine, l'amorçage écrit un fichier .docflow à la racine du dépôt — un pointeur d'une ligne, racine: <chemin> (par exemple racine: docs/, racine: .). Aucun des deux présents signifie un dépôt pré-contrat (les outils sondent docs/, puis la racine du dépôt, pour un CONVENTIONS.md nommant une racine d'artefact) ou pas un dépôt docflow.

agent/ est le contrat de fonctionnement de l'agent — qui écrit quoi, le seul vrai mutex, et comment se comporte une exécution sans surveillance. Elle ne contient rien que git n'enregistre déjà : aucune copie des livraisons, aucun tableau de bord de ce qui est en cours, aucun instantané de l'état actuel, aucune passation. Lequel des trois fichiers ci-dessus existe découle entièrement de Q5, Q8 et Q4a, et un dépôt sans répertoire _agent/ du tout est un résultat valide.

Couches centrales vs optionnelles. Seule la centrale est toujours écrite : AGENTS.md, CLAUDE.md, CONVENTIONS.md, adr/0000-modèle.md et INDEX.md. Un dépôt avec seulement ceux-ci est un dépôt docflow valide et léger — un catalogue ADR classique avec des conventions. Tout le reste est une couche optionnelle : la file d'attente plan/ (Q4a), le contrat _agent/ (Q5 + Q8 + Q4a — un seul rédacteur sans à la fois une porte de vérification et une file d'attente de plan n'en obtient rien), GLOSSARY.md et domaines/ (Q7). Omettre toute couche optionnelle est un état valide, pas une erreur ; une compétence de cycle de vie qui a besoin d'une couche absente refuse proprement et nomme ce qui manque.

Pour un produit multi-dépôt (un produit réparti sur plusieurs dépôts — voir Q11), deux fichiers supplémentaires apparaissent : fédération.md, un petit pointeur de retour que chaque dépôt membre transporte, et index fédération.md, la liste des membres faisant autorité qui ne vit que dans le dépôt d'accueil/établissement. Tous les artefacts de fédération — fédération.md, index fédération.md et le récapitulatif RÉCAPITULATIF.md dérivé — sont placés sous la racine d'artefact configurée. Un dépôt autonome n'en a aucun.

Étape 3 — Conventions à installer

Les ADR sont la source de vérité. Une décision par ADR. Les divisions deviennent de nouveaux ADR qui remplacent ; n'étendez jamais la portée d'un ADR existant.
Jusqu'à deux formes ADR, déclarées par champ. Un dépôt qui les distingue enregistre la distinction dans le champ de métadonnées shape: de chaque ADR (capacité ou technique ; un champ absent signifie capacité) — jamais dans une plage de numéros. Chaque ADR prend le numéro contigu suivant quelle que soit sa forme, et chaque forme a son propre modèle, tous deux numérotés 0000.
- ADR de capacité (ce que le système doit faire). Ordre des sections : métadonnées → Contexte → Énoncé de capacité → Récits utilisateur / scénarios → Critères d'acceptation → Hors champ → Questions ouvertes → Références → Historique des révisions → Approbations.
- ADR technique (comment c'est construit). Ordre des sections : métadonnées → Contexte → Décision → Justification → Conséquences → Critères d'acceptation → Hors champ → Questions ouvertes → Références → Historique des révisions → Approbations. La justification doit nommer les alternatives envisagées et donner des raisons de rejet spécifiques (pas « plus simple » / « plus idiomatique »).
Cycle de vie des statuts : Proposé → Accepté → Implémenté → (Remplacé | Obsolète). Les états terminaux sont accessibles depuis n'importe quel état antérieur. Le statut pilote le placement dans le dossier plan : Accepté → plan/to-d/, Implémenté → plan/fait/.
Noms de fichiers : adr/NNNN-kebab-slug.md, rembourré à zéro sur 4 chiffres, contigu, sans écarts réservés. Les références croisées utilisent des chemins relatifs.
Les critères d'acceptation sont testables et numérotés. Les tests sont liés à eux dans la mesure du possible.
Discipline d'audit. Les modifications substantielles d'ADR ajoutent une ligne à l'Historique des révisions. Les modifications éditoriales (fautes de frappe, mise en forme, corrections de liens) sont exclues mais signalées comme éditorial dans le message de commit. Le tableau des approbations se remplit lorsqu'un ADR est Accepté et se met à jour à chaque révision substantielle ultérieure.
INDEX.md est régénéré à partir des métadonnées ADR après toute modification d'ADR. Traitez comme dérivé, pas édité à la main.
plan/ est la file d'attente de travail. Lorsque le travail est livré, git mv plan/to-d/X plan/fait/<date>-X, toute suppression de statut d'élément de plan, avancement du statut de l'ADR propriétaire et régénération d'INDEX.md sont regroupés dans le commit d'achèvement. Sous intégration directe vers le tronc, ce commit est poussé vers la branche d'intégration et le pied de page du fichier déplacé nomme le SHA HEAD (et l'identifiant de l'artefact de déploiement le cas échéant). Sous intégration par pull-request, ces modifications sont le dernier commit sur la branche de pull-request avant qu'elle ne soit marquée comme prête, le pied de page nomme la pull request, et la fusion est l'événement d'achèvement.
La coordination est un contrat, pas un journal. _agent/ contient uniquement ce que git ne peut pas vous dire, et chaque mode (Q5) prescrit exactement ses propres fichiers — rien d'autre n'y est écrit. Dans un checkout partagé, un agent ajoute une ligne à _agent/LOCKS.md (<id-agent> | <chemin> | <horodatage ISO-8601>) avant de modifier et la supprime lors du commit ; ce registre est l'unique vrai mutex, et un élément de file d'attente est revendiqué sur l'élément lui-même. Dans des worktrees séparés, un élément de file d'attente est revendiqué en poussant claim/<clé-élément> — le nom du fichier de la file d'attente sans son extension — plus un brouillon de pull request à partir de celui-ci lorsque l'intégration est basée sur une pull request ; la poussée est ce qui exclut le deuxième rédacteur, et aucun registre n'est conservé. Sous un seul rédacteur il n'y a rien à sérialiser et rien à revendiquer. Aucun mode ne conserve un état de livraison dupliqué, un tableau de bord de ce qui est en vol, ou un instantané de l'état actuel : l'historique git et plan/fait/ sont l'enregistrement, et les branches actives et les pull requests sont ce qui est en vol.
Contrat Git. Commits conventionnels. Pied de page Justification obligatoire sur les commits touchant un ADR. Commits signés sauf si l'utilisateur se désengage. Pas de bande-annonce Co-Authored-By pour le travail d'agent sauf si l'utilisateur en demande une.
AGENTS.md est le point d'entrée des règles strictes ; CLAUDE.md est la ligne unique @AGENTS.md pour les agents compatibles qui le lisent.
Les ADR sont des artefacts internes — jamais visibles par l'utilisateur. Les numéros ADR, les titres ADR et l'existence du catalogue ADR ne doivent JAMAIS apparaître dans les chemins de code produit qui atteignent un utilisateur : chaînes d'interface utilisateur, corps de réponse d'API, messages d'erreur, lignes de journal émises aux clients, documentation publique, notes de version, communications de support marketing. Les ADR sont pour les constructeurs, pas pour les utilisateurs. Les références SONT autorisées dans : les commentaires de code (// voir a ...

[La suite a été tronquée pour la traduction]

EvolveHQ/docflow

Qu'est-ce que docflow ?

Demander à votre IA préférée

Documentation

amorçage

Étape 1 — Détecter la situation

Étape 2 — Disposition cible

Étape 3 — Conventions à installer

Individual skills in this repo