Intake : demander d’abord, agir ensuite

Un intake est la liste des questions auxquelles un pack doit avoir une réponse avant de se mettre au travail. Sans lui, un agent qui reçoit une demande maigre comble les trous par des suppositions, et vous le découvrez dans le livrable. Avec lui, l’agent pose quelques questions à la fois, dans votre langue, enregistre chaque réponse avec son statut et produit un brief qui devient le contrat de tout ce que fait ensuite le pack. Lisez cette page si vous utilisez un pack qui livre un intake (en 0.23.0, le pack Design) ou si vous voulez en donner un à votre propre pack.

Pourquoi demander d’abord#

Un pack agit sur ce qu’il sait. Concevoir un écran pour « un tableau de bord » sans savoir qui l’utilise, sur quel appareil et pour quelle tâche produit un gabarit générique qui ne convient à personne. Le coût de la réponse manquante ne se voit qu’une fois le travail fait. L’intake déplace ce coût au début : chaque question dit si le pack peut démarrer sans elle, ce qu’il propose si cela vous est égal, et ce qui tourne mal si vous ne savez pas.

Trois fichiers interviennent. L’intake (intake.yaml) est livré avec le pack. Le fichier de réponses est du JSON, écrit uniquement par bmad-plus intake record. Le brief est du Markdown, écrit uniquement par bmad-plus intake render. C’est votre assistant qui pose les questions ; la commande ne demande jamais rien et n’appelle aucun modèle.

Chaque réponse a un statut#

Le pack est prêt quand chaque question indispensable (must-have) a reçu une réponse ou est marquée inconnue avec son risque. « Prêt » ne veut pas dire que les risques ont disparu : le brief les liste sous « Open questions », et un livrable construit sur un must-have inconnu doit répéter le risque dans son premier paragraphe. Une valeur que vous avez choisie vous-même s’enregistre avec --set, même si elle égale la valeur par défaut ; --default ne sert qu’à dire « j’accepte ce que vous proposez ».

Le fichier intake.yaml, champ par champ#

Le validateur est strict : un champ inconnu, un mauvais type ou une règle enfreinte est une erreur, jamais ignorée en silence. Le même validateur tourne quand vous appelez bmad-plus intake check et quand BMAD+ lui-même est construit.

La boucle : plan, question, enregistrement, rendu#

1. 01

   Planifier

   La commande liste les questions à poser ensuite : les indispensables d’abord, puis les autres dans l’ordre du fichier, max_per_message au plus. Elle sort avec 0 quand c’est prêt et 2 tant qu’un must-have reste ouvert.

   Dans le terminal du projet

   npx bmad-plus intake plan --intake FILE --answers FILE

2. 02

   Poser les questions

   L’assistant pose ces questions en un seul message, dans votre langue, avec les choix ou les bornes, et propose la valeur par défaut quand il y en a une. Il ne délaye pas son message et ne redemande pas ce qui est déjà enregistré.

3. 03

   Enregistrer

   Chaque réponse est contrôlée selon le type et les bornes de la question et refusée si elle ne convient pas (rien n’est écrit). UNKNOWN enregistre le risque ; --default enregistre la proposition. Une question ne peut être renseignée qu’une fois par appel.

   Dans le terminal du projet

   npx bmad-plus intake record --intake FILE --answers FILE --set id=VALUE --default other_id

4. 04

   Répéter jusqu’à « prêt »

   Replanifiez. Quand le plan dit « ready », on arrête de poser des questions, même s’il reste des questions facultatives : l’assistant nomme celles qui restent ouvertes et continue, sauf si vous voulez poursuivre.

5. 05

   Rédiger le brief

   Le brief liste chaque section et chaque réponse avec son statut, puis les questions ouvertes avec leurs risques. C’est l’entrée de l’étape suivante du pack.

   Dans le terminal du projet

   npx bmad-plus intake render --intake FILE --answers FILE --out brief.md

Un exemple complet : le design read du pack Design#

Le seul intake livré en 0.23.0 appartient au pack Design. Atelier, son agent, l’exécute avant tout travail de design (/design read). Il compte 13 questions en 5 sections, dont 3 indispensables : la surface, le public et la tâche que la page doit accomplir. Les trois réglages (variance, motion, density) et la stack n’ont volontairement aucune valeur par défaut : un réglage laissé ouvert est fixé par Atelier à partir de la surface, et le brief note qu’il a été déduit.

Voici une exécution réelle de la CLI 0.23.0 sur cet intake (un tableau de bord pour des comptables, réponses saisies en français). D’abord la validité, puis le plan avec son code de sortie 2, puis trois réponses, puis le brief.

$ npx bmad-plus intake check .agents/skills/pack-design/intake.yaml
.agents/skills/pack-design/intake.yaml: valid intake design-read (design), 13 questions, 3 must-have.
$ npx bmad-plus intake plan --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json
design-read (design): not ready — 0 answered, 0 defaulted, 0 unknown, 13 not asked yet.
Must-haves still open: surface_kind, audience, job
Ask next (at most 6 per message):
  - surface_kind [choice] Which surface is this? A marketing landing page, a dashboard, a data table, a form, an auth or onboarding flow, a mobile screen, an email, a chat or AI surface, a checkout, a settings page, or something else? (must-have; choices: landing, dashboard, table, form, auth, onboarding, mobile, email, ai-chat, checkout, settings, other)
  - audience [text] Who uses it, and in what situation (device, time pressure, expertise, frequency)? (must-have)
  - job [text] What is the one job this page must get done, and how will you know it did? (must-have)
# Trois questions facultatives de plus suivent dans la sortie réelle (brand_assets, design_system, aesthetic_family). Le code de sortie est 2 : pas prêt.
$ npx bmad-plus intake record --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json --set surface_kind=dashboard --set "audience=Comptables en cabinet, sur ordinateur, en fin de mois" --set "job=Repérer les factures en retard et relancer en un clic"
Recorded surface_kind, audience, job in _bmad-output/design/intake.json.
design-read (design): ready — 3 answered, 0 defaulted, 0 unknown, 10 not asked yet.
$ npx bmad-plus intake render --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json --out _bmad-output/design/brief.md
Brief written to _bmad-output/design/brief.md (3022 bytes); the intake is ready.
$ head -n 3 _bmad-output/design/brief.md
# Design read
<!-- owned by bmad-plus intake design-read; written by bmad-plus intake render, do not edit -->

# La liste « Ask next » que record affiche après chaque lot est omise ici. La dernière commande montre les trois premières lignes du brief.

La seconde transcription poursuit avec un autre scénario (une landing page pour un bar à café) et montre les deux autres statuts : une valeur par défaut acceptée avec --default, une valeur choisie avec --set et un réglage marqué inconnu. Le plan reste « ready » avec un réglage inconnu parce que ce n’est pas un must-have, et le brief qui suit lit le statut de chaque réponse.

$ npx bmad-plus intake record --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json --set surface_kind=landing --set "audience=Urban professionals who buy coffee most days; on a phone, on the way to work, a few seconds of attention" --set "job=Get a first-time visitor to open a loyalty card; success is the sign-up button being tapped"
Recorded surface_kind, audience, job in _bmad-output/design/intake.json.
design-read (design): ready — 3 answered, 0 defaulted, 0 unknown, 10 not asked yet.
$ npx bmad-plus intake record --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json --set brand_assets=partial --default design_system --default aesthetic_family --set motion=3 --set variance=UNKNOWN
Recorded brand_assets, motion, variance, design_system, aesthetic_family in _bmad-output/design/intake.json.
design-read (design): ready — 5 answered, 2 defaulted, 1 unknown, 5 not asked yet.
Unknown: variance
$ npx bmad-plus intake render --intake .agents/skills/pack-design/intake.yaml --answers _bmad-output/design/intake.json --out _bmad-output/design/brief.md
Brief written to _bmad-output/design/brief.md (3043 bytes); the intake is ready.
# Les listes « Ask next » affichées par record sont omises.

# Design read
<!-- owned by bmad-plus intake design-read; written by bmad-plus intake render, do not edit -->

Intake `design-read` of pack `design` — 5 answered, 2 defaulted, 1 unknown, 5 not asked yet. Ready.

## Who and why

### audience (must-have)

Who uses it, and in what situation (device, time pressure, expertise, frequency)?

Answer:
    Urban professionals who buy coffee most days; on a phone, on the way to work, a few seconds of attention
Feeds: brief.md#audience

### design_system

Is a design system or component library already in use?

Answer (proposed default, not confirmed by the user):
    none
Feeds: brief.md#design-system

### variance

Layout variance, from 1 (symmetric and safe) to 10 (asymmetric and bold)? Leave it open and Atelier sets it from the surface.

Answer: unknown
Feeds: brief.md#dials

## Open questions

- variance: unknown
- density: not asked yet
- stack: not asked yet
- accessibility_target: not asked yet
- languages: not asked yet
- required_states: not asked yet

Atelier construit ensuite à partir de ce brief. Les règles qu’il suit viennent du pack Design : une réponse garde son statut dans tous les livrables (un défaut ou une déduction est signalé là où il a servi, un must-have inconnu voyage avec son risque), et un réglage laissé ouvert est fixé d’après la surface et noté comme déduit.

Lance l’intake de design avant de construire quoi que ce soit. Utilise bmad-plus intake plan pour voir ce qui reste ouvert, pose-moi au plus six questions à la fois dans ma langue en commençant par les indispensables, propose les valeurs par défaut, enregistre ce que je ne sais pas avec son risque, puis rédige le brief et montre-le-moi avant de commencer.

Écrire l’intake de votre propre pack#

N’importe quel fichier de votre projet peut être un intake : bmad-plus intake check|plan|record|render acceptent de simples chemins relatifs au projet. L’exemple ci-dessous est un pack fictif appelé releasekit. Il a deux must-have avec un risque chacun, un défaut honnête (le public est « both » sauf indication contraire), un nombre borné et une liste libre.

schema_version: 1
id: release-notes
pack: releasekit
title: Release notes brief
language: user
max_per_message: 4
sections:
  - id: release
    title: The release
    questions:
      - id: version
        ask: Which version is being released?
        kind: text
        must_have: true
        feeds: [brief.md#release]
        risk_if_unknown: The notes cannot say what changed in which version.
      - id: audience
        ask: Who reads the notes?
        kind: choice
        choices: [developers, end-users, both]
        default: both
        feeds: [brief.md#audience]
  - id: content
    title: What goes in
    questions:
      - id: breaking_changes
        ask: Is anything breaking for existing users?
        kind: boolean
        must_have: true
        risk_if_unknown: A breaking change ships without a migration note.
      - id: highlights
        ask: What are the highlights, one per item?
        kind: list
      - id: max_words
        ask: How long may the notes be?
        kind: number
        min: 50
        max: 2000
        default: 300

Validez d’abord. Le fichier ci-dessous est volontairement cassé (un must-have avec un défaut et sans risque, un choix à une seule valeur) ; le validateur signale les trois problèmes d’un coup. Le terminal valide ensuite le fichier correct et déroule la boucle dessus.

schema_version: 1
id: broken-demo
pack: releasekit
title: A deliberately broken intake
sections:
  - id: release
    title: The release
    questions:
      - id: version
        ask: Which version is being released?
        kind: text
        must_have: true
        default: "1.0.0"
      - id: audience
        ask: Who reads the notes?
        kind: choice
        choices: [everyone]

$ npx bmad-plus intake check intake/broken.yaml
intake/broken.yaml: not a valid intake
  - sections[0].questions[0]: a must-have question needs "risk_if_unknown"
  - sections[0].questions[0]: a must-have question takes no "default"; the user answers it
  - sections[0].questions[1]: a choice needs at least two distinct non-empty "choices"
# Code de sortie 1.
$ npx bmad-plus intake check intake/release-notes.yaml
intake/release-notes.yaml: valid intake release-notes (releasekit), 5 questions, 2 must-have.
$ npx bmad-plus intake plan --intake intake/release-notes.yaml --answers notes/answers.json
release-notes (releasekit): not ready — 0 answered, 0 defaulted, 0 unknown, 5 not asked yet.
Must-haves still open: version, breaking_changes
Ask next (at most 4 per message):
  - version [text] Which version is being released? (must-have)
  - breaking_changes [boolean] Is anything breaking for existing users? (must-have)
  - audience [choice] Who reads the notes? (choices: developers, end-users, both; default: "both")
  - highlights [list] What are the highlights, one per item?
$ npx bmad-plus intake record --intake intake/release-notes.yaml --answers notes/answers.json --set version=UNKNOWN --set breaking_changes=yes --default audience --set "highlights=faster install, new swarm command"
Recorded version, breaking_changes, highlights, audience in notes/answers.json.
release-notes (releasekit): ready — 2 answered, 1 defaulted, 1 unknown, 1 not asked yet.
Ask next (at most 4 per message):
  - max_words [number] How long may the notes be? (default: 300)
Unknown: version — risk: The notes cannot say what changed in which version.
$ npx bmad-plus intake record --intake intake/release-notes.yaml --answers notes/answers.json --set max_words=40
Intake: max_words: value must be at least 50
$ npx bmad-plus intake record --intake intake/release-notes.yaml --answers notes/answers.json --set max_words=250
Recorded max_words in notes/answers.json.
release-notes (releasekit): ready — 3 answered, 1 defaulted, 1 unknown, 0 not asked yet.
Unknown: version — risk: The notes cannot say what changed in which version.
$ npx bmad-plus intake render --intake intake/release-notes.yaml --answers notes/answers.json --out notes/brief.md
Brief written to notes/brief.md (921 bytes); the intake is ready.

# Release notes brief
<!-- owned by bmad-plus intake release-notes; written by bmad-plus intake render, do not edit -->

Intake `release-notes` of pack `releasekit` — 3 answered, 1 defaulted, 1 unknown, 0 not asked yet. Ready.

## The release

### version (must-have)

Which version is being released?

Answer: unknown — risk: The notes cannot say what changed in which version.
Feeds: brief.md#release

### audience

Who reads the notes?

Answer (proposed default, not confirmed by the user):
    both
Feeds: brief.md#audience

## What goes in

### breaking_changes (must-have)

Is anything breaking for existing users?

Answer:
    yes

### highlights

What are the highlights, one per item?

Answer:
    faster install
    new swarm command

### max_words

How long may the notes be?

Answer:
    250

## Open questions

- version (must-have): unknown — risk: The notes cannot say what changed in which version.

Écrire des questions qui méritent leur place#

• Ne faites d’une question un must-have que si le pack ne peut vraiment rien faire d’utile sans elle. La phrase de risque est le test : si vous ne savez pas dire ce qui tourne mal, ce n’est pas un must-have.
• Ne donnez un défaut que s’il est honnête, c’est-à-dire que la plupart des gens le choisiraient et qu’une mauvaise supposition coûte peu. Un défaut apparaît dans le brief comme une proposition, il ne passe donc jamais pour la parole de l’utilisateur.
• Préférez un choice au texte libre quand la réponse pilote une décision du pack : la valeur peut être testée et le brief reste comparable d’une exécution à l’autre.
• Bornez les nombres avec min et max : une valeur refusée est attrapée à record, pas découverte dans le livrable.
• Gardez max_per_message bas (3 à 6). Un long formulaire est mal rempli et lu en diagonale.
• Utilisez feeds pour dire quel artefact chaque réponse façonne. Cela ne coûte rien et permet à un relecteur de remonter d’une décision à une question.
• Écrivez ask dans la langue simple que vous emploieriez avec un client. L’assistant la traduit pour l’utilisateur quand language vaut user ; n’écrivez pas plusieurs langues dans un même fichier.

Où vit le fichier#

Dans un projet, placez le fichier où vous voulez et passez-le avec --intake ; il faut dire à l’assistant où il se trouve (une ligne dans votre adaptateur ou dans la compétence qui pilote le travail). Pour l’intégrer à un pack du dépôt source de BMAD+, ajoutez intake: intake.yaml au pack dans registry.yaml (le chemin est relatif au dossier du pack) : le build le valide alors, l’installateur le copie et bmad-plus doctor l’exige. Le registre est un fichier du dépôt source ; il n’est pas installé dans votre projet. Voir la page sur le registre.

Écris un fichier d’intake dans intake/release-notes.yaml avec les questions que nous oublions toujours avant de rédiger des notes de version : la version, s’il y a une rupture, qui lit les notes, les points forts et une limite de longueur. Ne rends indispensables que la version et la question sur les ruptures, chacune avec le risque si elle reste inconnue. Ne mets de valeur par défaut que là où elle est honnête. Lance ensuite bmad-plus intake check dessus et corrige tous les problèmes signalés avant de me montrer le fichier.

Sécurité et limites#

• Les réponses ne s’écrivent que par record, le brief que par render. Ne modifiez ni l’un ni l’autre à la main.
• render n’écrase un brief que si le fichier commence par la marque de propriété du même intake (ligne 2). Il ne remplace jamais un brief qu’il n’a pas écrit. record n’écrase qu’un fichier de réponses du même intake.
• Aucune des deux commandes n’écrit sous .git/, _bmad/, .bmad-plus/ ou node_modules/, ni à travers un lien symbolique.
• Ce que vous avez saisi est affiché en bloc indenté sous Answer:, de sorte qu’une valeur ne peut jamais devenir un titre ou un élément de liste du brief.
• Si le fichier d’intake change après l’enregistrement de réponses, plan signale l’incohérence. record --reset repart d’un fichier de réponses vide pour le même id d’intake ; il ne réinitialise jamais un fichier qui appartient à un autre intake.
• Le pack ne doit pas démarrer son pipeline ni un essaim tant qu’un must-have n’est ni répondu ni marqué inconnu. Les commandes ne le contrôlent pas elles-mêmes : c’est une consigne des compétences autopilot et Nexus, qui demandent à l’assistant de passer d’abord l’intake de chaque pack concerné, en Discovery.
• Le runtime ne demande rien, n’invente rien et n’appelle aucun modèle. Une valeur refusée ne change rien sur le disque.