Apache Magpie — Configuration

setup

Cette compétence est le seul artefact du framework qu'un projet adoptant versionne. Chaque autre compétence d'Apache Magpie (sécurité, gestion des PR, issues) est un lien symbolique ignoré par Git pointant vers l'instantané ignoré par Git dans <snapshot-dir> que cette compétence gère.

Le modèle d'adoption est instantané + surcharges agentiques + mises à jour conscientes des dérives (pas de sous-module, pas de place de marché, pas de copie vendue) :

• Le framework est téléchargé dans <snapshot-dir> et ignoré par Git dans le dépôt de l'adoptant. L'instantané est un artefact de construction, pas du code source.
• Trois méthodes d'installation sont supportées (voir docs/setup/install-recipes.md pour des recettes prêtes à copier-coller) :
  • svn-zip — zip signé et publié depuis la distribution ASF (recommandé pour la production une fois les versions publiées).
  • git-tag — fixé à un tag Git spécifique.
  • git-branch — suit la pointe d'une branche (par défaut : main, le chemin WIP).
• Deux fichiers de verrouillage enregistrent la version du framework. Le fichier versionné déclare la version à laquelle le projet se fixe ; le fichier local enregistre ce que chaque machine a réellement téléchargé. Les dérives entre eux sont détectées et corrigées par /magpie-setup upgrade.
• Les liens symboliques rendent les compétences du framework appelables comme si elles se trouvaient dans le dépôt de l'adoptant. Chaque lien symbolique est nommé magpie-<compétence-du-framework> — chaque compétence du framework est installée avec un préfixe magpie- afin d'être dans un espace de noms et de ne jamais entrer en collision avec les propres compétences de l'adoptant (par exemple, l'instantané skills/pr-management-triage/ devient magpie-pr-management-triage, invoqué par /magpie-pr-management-triage). .agents/skills/ est l'unique emplacement canonique : ses entrées magpie-* pointent vers <snapshot-dir>/skills/<compétence-du-framework>/. Chaque autre cible de l'agent (.claude/skills/, .github/skills/, …) reçoit un lien symbolique relais par compétence qui pointe vers l'entrée canonique (.claude/skills/magpie-<n> → ../../.agents/skills/magpie-<n>) — quelle que soit la disposition que le projet adoptant utilisait auparavant (voir agents.md). Les liens symboliques sont ignorés par Git car leurs cibles disparaissent lors d'un nouveau clone avant l'exécution de /magpie-setup.
• Les modifications spécifiques à l'adoptant des workflows du framework sont placées sous forme d'instructions lisibles par l'agent dans .apache-magpie-overrides/<nom-compétence>.md (versionné). Elles invalident ou modifient les étapes que la compétence du framework exécuterait autrement. Voir overrides.md pour le contrat et docs/setup/agentic-overrides.md pour la justification de conception.

Auto-adoption locale (uniquement le dépôt du framework). Le seul dépôt qui ne peut pas être adopté via le mécanisme d'instantané est le dépôt du framework Apache Magpie lui-même — un instantané distant du framework dans lui-même serait circulaire. Au lieu de cela, il s'auto-adopte avec method:local : chaque magpie-<compétence> canonique dans .agents/skills/ est un lien symbolique versionné pointant vers la source dans le dépôt ../../skills/<compétence>/, et chaque autre cible d'agent active (agents.md) — .claude/skills/ (Claude Code), .github/skills/ (chargeur de compétences de GitHub), et tout autre éventuel — reçoit un lien symbolique relais versionné (magpie-<compétence> → ../../.agents/skills/magpie-<compétence>) — sans instantané, sans téléchargement distant et sans copie. Cela rend les propres compétences du framework appelables lors du développement du framework, et chaque contributeur les obtient actives sur un clone frais sans aucune étape de configuration. adopt détecte structurellement le dépôt du framework et y redirige automatiquement (voir adopt.md → Auto-adoption locale).

Les deux fichiers de verrouillage

Le modèle de fichier de verrouillage du framework sépare ce à quoi le projet se fixe (versionné) de ce que cette machine a réellement téléchargé (local). Cette séparation est le fondement de la détection des dérives et du support multi-installateur.

<committed-lock> — .apache-magpie.lock

Versionné à la racine du dépôt de l'adoptant. La version fixée du projet. Modifié uniquement par /magpie-setup ; ne pas modifier à la main.

# .apache-magpie.lock — versionné ; la version fixée du projet.

method: <git-branch | git-tag | svn-zip>
url:    <voir le format par méthode ci-dessous>

# Pour method=git-branch :
ref:    main

# Pour method=git-tag :
ref:    v1.0.0          # le nom du tag
commit: <SHA>           # le commit vers lequel pointait le tag lors du versionnement

# Pour method=svn-zip :
ref:    1.0.0           # le numéro de version
sha512: <hash>          # le SHA-512 du zip publié (pour vérification lors d'un nouveau téléchargement)

Le prochain adoptant qui exécutera /magpie-setup adopt lira ce fichier et réinstallera la même version que celle déclarée par le projet. C'est le cœur de la promesse "adopter une fois, tous les utilisateurs suivants obtiennent la même chose".

<local-lock> — .apache-magpie.local.lock

Ignoré par Git à la racine du dépôt de l'adoptant. L'empreinte de l'instantané local. Enregistre ce que cette machine a téléchargé et quand.

# .apache-magpie.local.lock — ignoré par Git ; par machine.

source_method:    <git-branch | git-tag | svn-zip>
source_url:       <URL depuis laquelle l'instantané a été réellement téléchargé>
source_ref:       <branche / tag / version réellement téléchargé>
fetched_commit:   <SHA du commit sur le disque maintenant>
fetched_at:       <horodatage ISO-8601>

La vérification des dérives lors de chaque invocation d'une compétence du framework compare ce fichier avec <committed-lock> et signale toute incohérence comme une proposition de /magpie-setup upgrade.

Fichiers détaillés dans ce répertoire

Fichier	Objectif
adopt.md	Parcours d'adoption initiale — reconnaître un instantané existant vs nécessité d'amorçage, écrire les deux fichiers de verrouillage, demander à l'utilisateur quelles familles de compétences connecter, créer les liens symboliques ignorés par Git, créer le squelette .apache-magpie-overrides/, installer le hook post-clone, mettre à jour la documentation du projet. La sous-action par défaut.
upgrade.md	Rafraîchir l'instantané ignoré par Git en fonction du verrou versionné, réconcilier les éventuelles surcharges agentiques + liens symboliques avec la nouvelle structure du framework, signaler les conflits. Gère le flux de correction des dérives.
verify.md	Vérification en lecture seule — instantané présent + intact, les deux fichiers de verrouillage synchronisés, les liens symboliques pointent vers des cibles actives, .gitignore correct, .apache-magpie-overrides/ existe, statut des dérives (versionné vs local), la compétence setup elle-même est à jour.
agents.md	Le registre des cibles de l'agent — quels répertoires reçoivent les liens symboliques des compétences du framework selon les fournisseurs, et le modèle canonique-plus-relais : .agents/skills/ est l'unique emplacement canonique (liens vers l'instantané/source) ; chaque autre cible (claude-code, github, et autres natifs comme Windsurf/Goose) reçoit un lien symbolique relais par compétence vers .agents/skills/. Définit la sélection des cibles actives, la portabilité du format SKILL.md, et la couche Claude-Code uniquement (bac à sable/hooks). La source de vérité que chaque sous-action consulte pour l'ensemble des cibles.
overrides.md	Gestion des fichiers de surcharge agentique — ouvrir/créer une surcharge pour une compétence du framework, lister les surcharges existantes, aider à la réconciliation lorsque le framework modifie la structure de la compétence sous-jacente lors d'une mise à niveau.
unadopt.md	Inverser l'adoption — supprimer l'instantané, les verrous, les liens symboliques, le hook post-clone, les entrées .gitignore, les sections d'adoption dans README.md / AGENTS.md / CONTRIBUTING.md, et la compétence setup versionnée elle-même. Préserve .apache-magpie-overrides/ par défaut ; --purge-overrides le supprime également. Affiche le plan de suppression complet avant toute écriture.

Règles d'or

Règle d'or 1 — ne jamais modifier l'instantané. Le <snapshot-dir> est un artefact de construction, ignoré par Git et en lecture seule du point de vue de l'adoptant. Toute modification souhaitée par un adoptant doit être placée dans .apache-magpie-overrides/ (où elle est versionnée et survit à la prochaine upgrade). La compétence, et toute autre compétence du framework consultant les surcharges à l'exécution, n'écrit jamais dans <snapshot-dir>.

Règle d'or 2 — <committed-lock> est la version fixée du projet ; <local-lock> est la vérité par machine. Ils servent des objectifs différents et vivent à des endroits différents :

• <committed-lock> déclare quelle version le projet utilise. Modifié par l'adoptant qui exécute /magpie-setup adopt en premier (ou qui exécute plus tard /magpie-setup upgrade et accepte la nouvelle version fixée). La modifier est une action délibérée au niveau du projet ; la modification apparaît dans le git diff de la PR qui l'a proposée.
• <local-lock> enregistre ce que cette machine a installé. Mis à jour silencieusement par /magpie-setup adopt et /magpie-setup upgrade. Par développeur, par clone, par arbre de travail.

Règle d'or 3 — les dérives sont détectées, les dérives sont corrigées. Chaque compétence du framework (et /magpie-setup verify) vérifie <committed-lock> vs <local-lock> au début de son exécution. En cas d'incohérence, la compétence signale l'écart et propose /magpie-setup upgrade. L'utilisateur accepte ou reporte ; s'il accepte, upgrade :

1. Supprime <snapshot-dir> complètement.
2. Réinstalle en fonction du verrou versionné (la nouvelle version choisie par le projet).
3. Rafraîchit les liens symboliques des compétences du framework ignorés par Git — ajoute toute nouvelle compétence du framework couverte par le choix de famille de l'utilisateur, supprime toute compétence du framework qui a été renommée ou supprimée.
4. Réconcilie les surcharges agentiques avec la nouvelle structure du framework (signale les conflits ; ne réécrit jamais automatiquement).
5. Met à jour <local-lock> avec le nouveau téléchargement.

Règle d'or 4 — .gitignore maintient le dépôt de l'adoptant propre. Trois éléments sont ignorés par Git dans le dépôt de l'adoptant :

• <snapshot-dir> (l'intégralité de l'instantané du framework — potentiellement des gigaoctets).
• <local-lock> (état par machine).
• Les liens symboliques magpie-* que setup adopt crée dans chaque répertoire cible actif — les liens canoniques dans .agents/skills/ (ils ciblent l'instantané ignoré par Git) et les relais dans .claude/skills/ / .github/skills/ / autres (ils ciblent les entrées canoniques) — les deux seraient pendants dans un clone frais. La seule exception non ignorée dans chaque répertoire est magpie-setup.

Versionné : cette compétence (setup, en tant que .agents/skills/magpie-setup/ canonique plus ses relais), le <committed-lock>, le répertoire .apache-magpie-overrides/, les entrées .gitignore elles-mêmes, toute mise à jour de la documentation du projet effectuée par la sous-action adopt.

Règle d'or 5 — .agents/skills/ est canonique ; tout le reste ne fait que relayer vers lui. Quelle que soit la façon dont un projet adoptant organisait auparavant ses .claude/skills/ ou .github/skills/, adopt câble toujours le framework de la même manière : les liens canoniques magpie-* vivent dans .agents/skills/, et chaque autre cible active (.claude, .github, autres) reçoit des liens symboliques relais par compétence pointant vers les entrées canoniques (.claude/skills/magpie-<n> → ../../.agents/skills/magpie-<n>). Les propres compétences natives (non-magpie-) de l'adoptant dans ces répertoires sont laissées intactes. Voir agents.md.

Règle d'or 6 — copier cette compétence, lier symboliquement le reste ; le tout sous le préfixe magpie-. Cette compétence (source skills/setup/) est la seule compétence du framework qui est copiée dans un dépôt adoptant — versionnée en tant que .agents/skills/magpie-setup/ canonique, avec des liens symboliques relais versionnés vers elle depuis .claude/skills/magpie-setup et .github/skills/magpie-setup. Toutes les autres compétences du framework sont liées symboliquement (lien canonique vers l'instantané ignoré par Git, plus relais), chacune nommée magpie-<compétence-du-framework> (par exemple magpie-security-issue-import → <snapshot-dir>/skills/security-issue-import/). Le préfixe magpie- met chaque compétence du framework dans son propre espace de noms afin qu'elle ne collisionne jamais avec les propres compétences de l'adoptant. Mélanger copie et lien symbolique — copier une compétence de sécurité, par exemple — crée un risque de maintenance : les copies dérivent de la source de vérité du framework, et le mécanisme de détection des dérives (qui suppose que la version du framework est celle dans <snapshot-dir>) s'applique silencieusement de manière incorrecte.

Règle d'or 7 — les surcharges agentiques sont lues à l'exécution. Chaque compétence du framework qui supporte les surcharges commence son exécution en vérifiant .apache-magpie-overrides/<cette-compétence>.md pour des instructions spécifiques à l'adoptant et les applique avant d'exécuter le comportement par défaut. Le fichier de surcharge est un simple markdown que l'agent interprète — pas de moteur de template, pas d'outil de correctif. Voir docs/setup/agentic-overrides.md pour le contrat.

Règle d'or 8 — deux familles sont toujours installées ; les autres sont optionnelles. Deux familles de compétences sont câblées inconditionnellement à chaque exécution d'adopt / upgrade / init d'arbre de travail et l'utilisateur ne se voit jamais demander à leur sujet :

• setup-* — toute compétence du framework dont le nom source commence par setup- sauf le bootstrap setup lui-même (qui est copié en tant que magpie-setup selon la règle 6, non lié symboliquement). Concrètement : setup-isolated-setup-install, setup-isolated-setup-update, setup-isolated-setup-verify, setup-override-upstream, setup-shared-config-sync, plus toute nouvelle compétence setup-* que le framework pourrait ajouter à l'avenir — chacune liée symboliquement en tant que magpie-setup-*.
• list-* — la famille de découverte ; toute compétence du framework dont le nom source commence par list-. Aujourd'hui, il s'agit uniquement de list-skills (liée symboliquement en tant que magpie-list-skills) ; le préfixe permet au framework de faire croître