Intake: erst fragen, dann handeln

Ein Intake ist die Liste der Fragen, die ein Pack beantwortet haben muss, bevor es zu arbeiten beginnt. Ohne ihn füllt ein Agent bei einer dünnen Anfrage die Lücken mit Vermutungen, und du merkst es erst im Ergebnis. Mit ihm stellt der Agent wenige Fragen auf einmal, in deiner Sprache, hält jede Antwort mit ihrem Status fest und erzeugt ein Briefing, das zum Vertrag für alles wird, was das Pack danach tut. Lies diese Seite, wenn du ein Pack mit Intake nutzt (in 0.23.0 das Design-Pack) oder deinem eigenen Pack einen geben willst.

Warum zuerst fragen#

Ein Pack handelt nach dem, was es weiß. Einen Bildschirm für „ein Dashboard“ zu entwerfen, ohne zu wissen, wer es nutzt, auf welchem Gerät und für welche Aufgabe, ergibt eine generische Vorlage, die niemandem passt. Die Kosten der fehlenden Antwort zeigen sich erst, wenn die Arbeit getan ist. Ein Intake zieht diese Kosten nach vorn: Jede Frage sagt, ob das Pack ohne sie starten kann, was es vorschlägt, wenn es dir egal ist, und was schiefgeht, wenn du es nicht weißt.

Drei Dateien sind beteiligt. Der Intake (intake.yaml) wird mit dem Pack geliefert. Die Antwortdatei ist JSON und wird nur von bmad-plus intake record geschrieben. Das Briefing ist Markdown und wird nur von bmad-plus intake render geschrieben. Dein Assistent stellt die Fragen; der Befehl fragt nie etwas und ruft kein Modell auf.

Jede Antwort hat einen Status#

Das Pack ist bereit, wenn jede Pflichtfrage (must-have) beantwortet oder mit ihrem Risiko als unbekannt markiert ist. „Bereit“ heißt nicht, dass die Risiken verschwunden sind: Das Briefing listet sie unter „Open questions“, und ein Ergebnis, das auf einem unbekannten must-have beruht, soll das Risiko im ersten Absatz wiederholen. Einen Wert, den du selbst gewählt hast, erfasst du mit --set, auch wenn er dem Standard entspricht; --default heißt nur „ich akzeptiere deinen Vorschlag“.

Die Datei intake.yaml, Feld für Feld#

Der Validator ist streng: Ein unbekanntes Feld, ein falscher Typ oder eine verletzte Regel ist ein Fehler und wird nie stillschweigend ignoriert. Derselbe Validator läuft bei bmad-plus intake check und beim Bau von BMAD+ selbst.

Die Schleife: Plan, Frage, Erfassen, Rendern#

1. 01

   Planen

   Der Befehl listet die nächsten Fragen: zuerst die Pflichtfragen, dann die übrigen in Dateireihenfolge, höchstens max_per_message. Er endet mit 0, wenn alles bereit ist, und mit 2, solange ein must-have offen ist.

   Im Terminal deines Projekts

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

2. 02

   Fragen

   Der Assistent stellt diese Fragen in einer Nachricht, in deiner Sprache, mit Auswahl oder Grenzen, und schlägt den Standardwert vor, wenn es einen gibt. Er bläht die Nachricht nicht auf und fragt nicht nach, was schon erfasst ist.

3. 03

   Erfassen

   Jede Antwort wird gegen Typ und Grenzen der Frage geprüft und abgelehnt, wenn sie nicht passt (nichts wird geschrieben). UNKNOWN erfasst das Risiko; --default erfasst den Vorschlag. Eine Frage lässt sich pro Aufruf nur einmal setzen.

   Im Terminal deines Projekts

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

4. 04

   Wiederholen, bis es bereit ist

   Plane erneut. Sobald es ready meldet, wird nicht mehr gefragt, auch wenn optionale Fragen offen sind: Der Assistent nennt die offenen und macht weiter, außer du möchtest fortfahren.

5. 05

   Das Briefing rendern

   Das Briefing listet jeden Abschnitt und jede Antwort mit Status, danach die offenen Fragen mit ihren Risiken. Es ist die Eingabe für den nächsten Schritt des Packs.

   Im Terminal deines Projekts

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

Ein vollständiges Beispiel: das Design Read des Design-Packs#

Der einzige in 0.23.0 gelieferte Intake gehört zum Design-Pack. Atelier, sein Agent, führt ihn vor jeder Designarbeit aus (/design read). Er hat 13 Fragen in 5 Abschnitten, 3 davon Pflicht: die Oberfläche, die Zielgruppe und die Aufgabe, die die Seite erfüllen muss. Die drei Regler (variance, motion, density) und der Stack haben absichtlich keinen Standardwert: Einen offenen Regler setzt Atelier aus der Oberfläche, und das Briefing vermerkt, dass er abgeleitet wurde.

Hier ein echter Lauf der CLI 0.23.0 auf diesem Intake (ein Dashboard für Buchhalter, Antworten auf Französisch eingegeben). Zuerst die Gültigkeit, dann der Plan mit Exit-Code 2, dann drei Antworten, dann das Briefing.

$ 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)
# In der echten Ausgabe folgen drei weitere optionale Fragen (brand_assets, design_system, aesthetic_family). Der Exit-Code ist 2: nicht bereit.
$ 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 -->

# Die Liste „Ask next“, die record nach jedem Block ausgibt, ist hier weggelassen. Der letzte Befehl zeigt die ersten drei Zeilen des Briefings.

Das zweite Protokoll setzt mit einem anderen Szenario fort (eine Landingpage für eine Kaffeebar) und zeigt die beiden anderen Status: einen mit --default akzeptierten Standard, einen mit --set gewählten Wert und einen als unbekannt markierten Regler. Beachte, dass der Plan mit einem unbekannten Regler „ready“ bleibt, weil er kein must-have ist, und dass das folgende Briefing den Status jeder Antwort zeigt.

$ 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.
# Die von record gedruckten „Ask next“-Listen sind weggelassen.

# 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 baut anschließend aus diesem Briefing. Die Regeln dafür stammen aus dem Design-Pack: Eine Antwort behält ihren Status in jedem Ergebnis (ein Standard oder eine Ableitung wird an der Stelle gekennzeichnet, an der sie verwendet wurde; ein unbekanntes must-have reist mit seinem Risiko), und ein offener Regler wird aus der Oberfläche gesetzt und als abgeleitet vermerkt.

Starte den Design-Intake, bevor du irgendetwas baust. Nutze bmad-plus intake plan, um zu sehen, was offen ist, stelle mir höchstens sechs Fragen auf einmal in meiner Sprache, Pflichtfragen zuerst, schlage die Standardwerte vor, erfasse mit Risiko, was ich nicht weiß, und rendere dann das Briefing und zeige es mir, bevor du beginnst.

Einen Intake für dein eigenes Pack schreiben#

Jede Datei in deinem Projekt kann ein Intake sein: bmad-plus intake check|plan|record|render nehmen einfache projektrelative Pfade. Das Beispiel unten ist ein ausgedachtes Pack namens releasekit. Es hat zwei must-haves mit je einem Risiko, einen ehrlichen Standard (die Zielgruppe ist „both“, sofern nichts anderes gesagt wird), eine begrenzte Zahl und eine freie Liste.

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

Validiere zuerst. Die Datei unten ist absichtlich kaputt (ein must-have mit Standardwert und ohne Risiko, eine Auswahl mit nur einem Wert); der Validator meldet alle drei Probleme auf einmal. Danach validiert das Terminal die einwandfreie Datei und durchläuft die Schleife damit.

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"
# Exit-Code 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.

Fragen schreiben, die ihren Platz verdienen#

• Mache eine Frage nur dann zum must-have, wenn das Pack ohne sie wirklich nichts Nützliches tun kann. Der Risikosatz ist der Test: Wenn du nicht sagen kannst, was schiefgeht, ist es kein must-have.
• Gib einen Standard nur, wenn er ehrlich ist, also wenn die meisten ihn wählen würden und ein falscher Tipp wenig kostet. Ein Standard erscheint im Briefing als Vorschlag und gilt daher nie als Wort des Nutzers.
• Bevorzuge choice gegenüber Freitext, wenn die Antwort eine Entscheidung im Pack steuert: Der Wert ist prüfbar, das Briefing bleibt von Lauf zu Lauf vergleichbar.
• Begrenze Zahlen mit min und max: Ein abgelehnter Wert fällt bei record auf und nicht erst im Ergebnis.
• Halte max_per_message niedrig (3 bis 6). Ein langes Formular wird schlecht beantwortet und überflogen.
• Nutze feeds, um zu sagen, welches Artefakt jede Antwort prägt. Das kostet nichts und lässt Prüfende eine Entscheidung zu einer Frage zurückverfolgen.
• Schreibe ask in der einfachen Sprache, die du mit einem Kunden verwendest. Der Assistent übersetzt sie für den Nutzer, wenn language user ist; schreibe nicht mehrere Sprachen in eine Datei.

Wo die Datei liegt#

In einem Projekt legst du die Datei beliebig ab und übergibst sie mit --intake; dem Assistenten muss gesagt werden, wo sie liegt (eine Zeile in deinem Adapter oder in dem Skill, der die Arbeit steuert). Um sie Teil eines Packs im BMAD+-Quell-Repository zu machen, ergänzt du beim Pack in registry.yaml intake: intake.yaml (der Pfad ist relativ zum Pack-Verzeichnis): Der Build validiert sie dann, der Installer kopiert sie und bmad-plus doctor verlangt sie. Die Registry ist eine Datei des Quell-Repositorys; sie wird nicht in dein Projekt installiert. Siehe die Registry-Seite.

Schreibe eine Intake-Datei unter intake/release-notes.yaml mit den Fragen, die wir vor Release Notes immer vergessen: die Version, ob etwas bricht, wer die Notes liest, die Highlights und eine Längengrenze. Mache nur die Version und die Frage zu Breaking Changes zu must-haves, jeweils mit dem Risiko bei Unbekanntem. Gib einen Standard nur dort, wo er ehrlich ist. Führe danach bmad-plus intake check darauf aus und behebe alle gemeldeten Probleme, bevor du mir die Datei zeigst.

Sicherheit und Grenzen#

• Antworten werden nur über record geschrieben, das Briefing nur über render. Bearbeite keines von beiden von Hand.
• render überschreibt ein Briefing nur, wenn die Datei mit der Besitzmarke desselben Intakes beginnt (Zeile 2). Es ersetzt nie ein Briefing, das es nicht selbst geschrieben hat. record überschreibt nur eine Antwortdatei desselben Intakes.
• Keiner der beiden Befehle schreibt unter .git/, _bmad/, .bmad-plus/ oder node_modules/ oder über einen Symlink.
• Was du eingegeben hast, wird als eingerückter Block unter Answer: gedruckt, sodass ein Wert nie zu einer Überschrift oder einem Listenpunkt des Briefings werden kann.
• Ändert sich die Intake-Datei, nachdem Antworten erfasst wurden, meldet plan die Abweichung. record --reset beginnt die Antwortdatei für dieselbe Intake-ID leer von vorn; eine Datei, die zu einem anderen Intake gehört, setzt es nie zurück.
• Das Pack darf seine Pipeline oder einen Schwarm nicht starten, solange ein must-have weder beantwortet noch als unbekannt markiert ist. Die Befehle prüfen das nicht selbst: Es ist eine Anweisung in den Skills von Autopilot und Nexus, die den Assistenten anweisen, zuerst den Intake jedes beteiligten Packs auszuführen, in Discovery.
• Die Laufzeit fragt nichts, erfindet nichts und ruft kein Modell auf. Ein abgelehnter Wert ändert nichts auf der Platte.