Le registre et les compétences

Derrière chaque liste, chaque nombre et chaque fichier d’instructions généré de BMAD+, il y a un seul fichier : registry.yaml, à la racine du dépôt source de BMAD+. Il déclare les packs, leurs agents, compétences, fichiers de données, disposition d’installation, runtimes et étiquettes de conformité, les adaptateurs, la doctrine de traitement des données et plus encore. Tout ce qui en aval est généré à partir de lui : une liste, un nombre ou un adaptateur ne peut donc pas s’écarter des déclarations. Cette page s’adresse à qui veut comprendre ce contrat, lire les fichiers générés en confiance, ou étendre BMAD+ dans un fork ou une distribution d’équipe.

Ce que déclare le registre#

uses_skills : ce qu’un agent pilote#

Un pack ou une persona liste les ids de compétences qu’il pilote. Le générateur résout chaque id : ce doit être une compétence de n’importe quel pack, d’un external_module ou de Core, et un id que personne ne livre fait échouer le build. La liste du socle affiche alors - drives: design, design-review, redesign après la persona, et les instructions générées disent à l’agent de lire le SKILL.md de chaque compétence listée avant d’agir. Voici la déclaration réelle de la persona du pack Design.

  design:
    order: 9
    display_name: "Design"
    required: false
    runtime: [node]
    agents: [design-engine]
    personas:
      - { id: design-engine, name: Atelier, role: Design Engine, description: "Senior product designer and design engineer: surfaces, tokens, accessibility, audits, redesigns", uses_skills: [design, design-review, redesign] }
    skills: []
    external_module: { package: design-skill, version: "0.2.1", skills: [design, design-review, redesign] }
    pack_dir: pack-design
    install_layout: packaged
    doctor:
      pack_agents: [design-engine.md]
      required_resources: [SKILL.md]
    intake: intake.yaml
    cohabitation_warning: "Overlaps Sentinel's UX-review role and Dev Studio's Rachel (UX Designer); ..."

external_module : des compétences venues d’un paquet npm#

Un pack peut prendre ses compétences dans un paquet publié plutôt que dans l’arbre de BMAD+. Le pack Design est le premier : ses trois compétences viennent de design-skill, épinglé à la version exacte 0.2.1. Le paquet est une dépendance exacte de BMAD+ et figure dans la doctrine de traitement des données. À la construction, le générateur résout le paquet, vérifie que sa version égale celle qui est déclarée et que skills/<id>/SKILL.md existe pour chaque compétence listée. À l’installation, BMAD+ résout le paquet depuis sa propre installation, refuse une version différente et ne copie que le dossier skills/ du paquet dans .agents/skills/<id>/, par la même copie gérée et inventoriée par hash que tout autre fichier (aucun lien symbolique n’est suivi). Le tarball livre aussi un outil en ligne de commande de liaison que BMAD+ n’exécute jamais. bmad-plus doctor exige les trois SKILL.md ; la désinstallation retire les compétences copiées avec le reste des fichiers gérés.

pipelines : des étapes ordonnées avec une porte#

Un pack peut déclarer des pipelines : un enchaînement ordonné de ses propres workflows ou agents, chaque étape avec une porte (require_approval, notify_only ou auto). Nexus déroule un pipeline déclaré étape par étape avec le comportement de point de contrôle configuré, après l’intake du pack. Les ids de pipeline doivent être uniques dans le pack et chaque étape nomme exactement un workflow ou un agent existant dans le pack. Aucun pack ne déclare de pipeline en 0.23.0 : le champ existe, est validé et compris par autopilot, et sert aux packs qui en ont besoin. L’exemple est le format de la spécification, pas un contenu livré.

pipelines:
  - id: full-build
    title: From interview to private preview
    steps:
      - { workflow: discovery, gate: require_approval }
      - { workflow: positioning, gate: require_approval }
      - { agent: brandsite-art, gate: notify_only }
      - { workflow: preview, gate: require_approval }

Des déclencheurs qui doivent viser des choses réelles#

.agents/data/role-triggers.yaml pilote le changement de rôle. Le contrôle npm run check:triggers (dans le dépôt source) le valide par rapport au registre : une clé de premier niveau doit être un nom court d’agent Core (strategist, architect-dev, quality, orchestrator) ou un id de pack ; default_role doit être l’un des auto_triggers de la clé ; chaque rôle a une liste non vide de patterns ; contexts et reasoning, quand ils existent, sont des listes d’identifiants en snake_case ; sous une clé de pack, chaque id de rôle est un id de persona ou de pipeline de ce pack ; et un motif exact répété dans deux rôles de la même clé est une erreur. Trois contextes de Core renvoient aux fonctions de cette page : swarm_declared et panel_requested (Parallel Supervisor), et pack_pipeline_declared (autopilot).

Ce qui est généré, et les contrôles qui le gardent honnête#

Ce qu’est une compétence#

Une compétence est un dossier avec un SKILL.md : un en-tête avec un name et une description (qui dit quand l’utiliser, avec des mots que votre assistant peut reconnaître), puis la procédure. Les contenus plus longs sont dans un dossier ref/ à côté, les gabarits dans templates/. Chaque agent est aussi une compétence : agent-strategist/SKILL.md est Atlas. L’hôte charge le SKILL.md dont il a besoin, d’où l’importance de la description : c’est elle qui fait qu’un assistant choisit la compétence. Les six compétences Core ci-dessous sont livrées avec chaque installation.

D’autres compétences viennent avec leurs packs : dev-studio (le répartiteur du pack), les compétences design, design-review et redesign copiées depuis design-skill, les compétences bmad-osint-investigate et bmad-osint-investigator du paquet OSINT. Les packs SEO et Design portent aussi un SKILL.md de routage qui réagit quand vous écrivez /seo ou /design dans un message ; ce sont des mots-clés de demande, pas des commandes slash enregistrées par votre client.

Ajouter un agent ou un pack avec Maker#

Maker est l’Agent Creator du pack Maker. Il conçoit un agent avec vous en quatre phases (découverte, conception avec votre validation, génération, validation) et écrit un paquet sous _bmad-output/ready-to-integrate/. Ses capacités : CA créer un agent, QA agent rapide avec moins de questions, EA modifier sur place le SKILL.md d’un agent existant (sans passer par ce dossier), VA valider un paquet d’agent (format, manifeste, codes de capacité uniques, qualité des déclencheurs), PA empaqueter pour l’intégration, TP afficher le gabarit.

1. 01

   Créer et valider l’agent

   Demandez CA à Maker, répondez à ses questions de découverte, validez le tableau de conception, puis lancez VA sur le résultat.

2. 02

   Le copier dans un clone du dépôt

   Placez le dossier de l’agent sous src/bmad-plus/agents/ (agent « loose ») ou dans un dossier de pack (pack « packaged »).

3. 03

   Le déclarer dans registry.yaml

   Ajoutez ou étendez un pack : agents, personas (avec uses_skills s’il pilote des compétences), skills, install_layout, doctor, et si besoin intake, pipelines, cohabitation_warning. Ajoutez des déclencheurs de rôle dans role-triggers.yaml sous l’id du pack si vous voulez l’activation automatique.

4. 04

   Régénérer et contrôler

   Lancez npm run build, node tools/build/generate-adapters.js --adopt, puis npm run build:check, npm run check:counts et npm run check:triggers. Chaque échec nomme le champ à corriger.

5. 05

   L’installer dans un projet jetable

   Lancez l’installateur depuis votre clone avec --packs core,<your-pack> puis doctor : il ne doit signaler aucune erreur. Le contrat d’installation du dépôt (npm run test:install-contract) vérifie la même chose pour chaque pack.

Dans un projet installé, sans clone, vous pouvez quand même placer vos propres dossiers de compétences sous .agents/skills/. BMAD+ traite les fichiers qu’il n’a pas installés comme les vôtres : bmad-plus doctor les signale comme non possédés (un avertissement, pas une erreur), et la mise à jour comme la désinstallation les laissent en place. Ils ne sont pas inscrits dans la liste des agents, donc le socle ne les mentionne pas ; ajoutez une ligne à votre propre fichier d’instructions ou à l’adaptateur si vous voulez que l’assistant les trouve.

Maker, crée un agent de support client pour notre équipe : il trie les tickets entrants, rédige des réponses dans notre ton et escalade à un humain tout ce qui touche à la facturation. Pose-moi tes questions de découverte en un seul lot, montre-moi le tableau de conception (nom, rôles, capacités avec codes de deux lettres, déclencheurs, dépendances) et attends ma validation avant de générer. Puis valide le paquet et dis-moi ce qu’il reste à déclarer dans le registre.