187 lines
8.1 KiB
Markdown
187 lines
8.1 KiB
Markdown
# BMAD V6 Phase 4 Automation via Paperclip + OpenCode
|
||
|
||
Dieses Setup führt BMAD-V6 Phase 4 (Implementation) automatisiert mit
|
||
drei getrennten Agents aus. Phasen 1–3 und das manuelle Sprint Planning
|
||
müssen vorab abgeschlossen sein.
|
||
|
||
## Architektur in einem Satz
|
||
|
||
Paperclip orchestriert die Task-Hierarchie; ein Supervisor-Agent
|
||
routet Tasks an einen Dev-Worker (`create-story`, `dev-story`) oder
|
||
einen QA-Engineer (`code-review`, `retrospective`), die beide in
|
||
frischen OpenCode-Sessions mit **unterschiedlichen Modellen** arbeiten.
|
||
Der Ablauf ist strikt sequenziell: ein Epic nach dem anderen, jeder
|
||
Agent an maximal einem Ticket gleichzeitig.
|
||
|
||
## Rollenübersicht
|
||
|
||
| Agent | Rolle | Task-Typen | Modell-Empfehlung |
|
||
| --------------- | ------------ | ----------------------------------- | --------------------------- |
|
||
| PM-Supervisor | Orchestrator | pflegt Graph, routet, meldet | günstiges, textstarkes |
|
||
| Dev-Worker | Entwickler | `create-story`, `dev-story` | starkes Code-Modell |
|
||
| QA-Engineer | Reviewer | `code-review`, `retrospective` | **anderes** Modell als Dev |
|
||
|
||
Warum unterschiedliche Modelle: Adversariales Review profitiert
|
||
nachweislich davon, dass ein *anderes* Modell als der Autor hinschaut.
|
||
Strukturelle Asymmetrie, keine kosmetische.
|
||
|
||
## Sequenzierungs-Garantien
|
||
|
||
Der Supervisor erzwingt drei harte Policies bei jedem Ready-Setzen:
|
||
|
||
1. **Single-Epic-Policy (A):** Nur ein Epic zur Zeit aktiv. Epic N+1
|
||
startet erst nach Abschluss der Retrospektive von Epic N.
|
||
2. **Single-Task-per-Agent-Policy (B):** Jeder Agent bearbeitet genau
|
||
einen Task. Paperclips atomisches Task-Checkout verstärkt das auf
|
||
Infrastruktur-Ebene.
|
||
3. **Strikte Story-Ordnung (C):** Innerhalb eines Epics werden Stories
|
||
strikt in Reihenfolge abgearbeitet: 1.1 bis approved, dann 1.2 bis
|
||
approved, dann 1.3 und so weiter. Keine Vor-Arbeit, keine
|
||
Parallelität über Story-Grenzen hinweg.
|
||
|
||
Resultat: Ein Task pro Agent, höchstens zwei Agents gleichzeitig aktiv
|
||
am selben Story-Strang (z.B. Dev macht dev-story, QA wartet ready auf
|
||
das folgende code-review), strikt sequentiell innerhalb der Epic- und
|
||
Story-Reihenfolge.
|
||
|
||
## Idempotenz-Invariante
|
||
|
||
Jede Task-Anlage durchläuft eine Duplikats-Prüfung. Der Supervisor legt
|
||
nie zwei Tasks mit identischem Kompositschlüssel `(type, epic_id,
|
||
story_id, retry_count)` an. Gilt für Bootstrap, Retry-Logik und
|
||
Patrol-autonome Aktionen gleichermaßen.
|
||
|
||
Dev- und QA-Worker erkennen Duplikate bei ihrer eigenen Task-Zuweisung
|
||
(Pre-Flight-Check) und melden sie zurück, falls die Supervisor-Idempotenz
|
||
versagt hat – damit der Root-Cause sichtbar wird.
|
||
|
||
## Proaktive Patrol
|
||
|
||
Der Supervisor läuft nicht nur bei Events (`task_completed`) los,
|
||
sondern patrouilliert zusätzlich alle 15 Minuten (konfigurierbar). Im
|
||
Patrol inspiziert er den gesamten Task-Graphen und löst Blocker autonom
|
||
auf:
|
||
|
||
- **Stuck Tasks** (Agent hängt > Task-Timeout) → reset to ready
|
||
- **Orphan Ready Tasks** (ready, aber kein Agent assigned) → re-assign
|
||
- **Verlorenes Ready-Setting** (Vorgänger completed, Folge blocked) →
|
||
nachholen
|
||
- **Duplikate** (gleicher Kompositschlüssel) → jüngere stillschweigend
|
||
cancellen, Original behalten
|
||
- **Leerlauf** (kein Task aktiv, aber Goal offen) → nächsten korrekten
|
||
Task identifizieren und ready setzen
|
||
- **Dirty worktree** (uncommitted changes) → WIP-Commit mit
|
||
erkennbarer Message, Flow läuft weiter, kein Code-Verlust
|
||
|
||
Zwingende Operator-Eskalationen (keine autonome Aktion):
|
||
|
||
- **Retry-Limit erreicht** (3× needs-rework – inhaltliche Entscheidung)
|
||
- **Fehlender Agent** (dereferenziert oder gelöscht – Governance)
|
||
- **Meta-Stall > 1 h** (trotz wiederholter Patrol-Aktionen kein
|
||
Fortschritt – autonome Mittel sind erschöpft)
|
||
|
||
Patrol-Reports landen als Comment am Parent-Issue nur dann, wenn
|
||
tatsächlich Blocker gefunden oder Aktionen durchgeführt wurden. Kein
|
||
Spam bei sauberem Lauf.
|
||
|
||
## Dateien in diesem Bundle
|
||
|
||
```
|
||
bmad-paperclip/
|
||
├── skills/
|
||
│ ├── monitor-bmad-progress/SKILL.md # PM-Supervisor
|
||
│ ├── execute-bmad-dev-tasks/SKILL.md # Dev-Worker
|
||
│ └── execute-bmad-qa-tasks/SKILL.md # QA-Engineer
|
||
├── config/
|
||
│ ├── company.yaml # High-Level-Referenz
|
||
│ └── agents.jsonc # Konkrete Agent-Configs
|
||
├── bootstrap/
|
||
│ └── initial-task.json # Einziger Task, den du manuell anlegst
|
||
├── docs/
|
||
│ └── RUNBOOK.md # Schritt-für-Schritt mit API-Calls
|
||
└── README.md # Diese Datei
|
||
```
|
||
|
||
**Wo fange ich an?** Lies dieses README für den Überblick, dann arbeite
|
||
`docs/RUNBOOK.md` Schritt für Schritt ab.
|
||
|
||
## Voraussetzungen (ganz wichtig!)
|
||
|
||
Der Supervisor weigert sich zu starten, wenn Folgendes fehlt:
|
||
|
||
1. **`_bmad-output/planning-artifacts/PRD.md`** – Phase 2
|
||
2. **`_bmad-output/planning-artifacts/architecture.md`** – Phase 3
|
||
3. **Epic-Quelle** – eine der vier unterstützten Varianten (siehe unten)
|
||
4. **`_bmad-output/implementation-artifacts/sprint-status.yaml`** –
|
||
**Du führst `bmad-sprint-planning` selbst vorab aus.** Das ist nicht
|
||
Teil der Automation.
|
||
5. **Clean Git-Worktree** – keine uncommitteten Changes
|
||
|
||
**Erkannte Epic-Layouts (Auto-Detection):**
|
||
|
||
1. `epics-and-stories.md` – consolidated Single-File
|
||
2. `epics.md` – Single-File
|
||
3. `epics/epic-*.md` – per-epic Ordner
|
||
4. `epics/index.md` + Shards – geshardetes Layout
|
||
|
||
Sowohl Supervisor als auch Worker erkennen automatisch, welches Layout
|
||
dein Projekt hat. Falls keins gefunden wird, bricht der Bootstrap mit
|
||
präziser Fehlermeldung ab.
|
||
|
||
## OpenCode-Adapter
|
||
|
||
Paperclip hat seit Februar/März 2026 einen first-class OpenCode-Adapter
|
||
(`opencode_local`), analog zu `claude_local` – mit Model-Discovery,
|
||
Run-Log-Streaming und Skill-Injection eingebaut. Kein eigener
|
||
HTTP-Adapter nötig. `agents.jsonc` nutzt diesen direkt.
|
||
|
||
**Bewusste Abweichung vom Default:** Dev und QA nutzen
|
||
`sessionBehavior: "new"`, nicht `"resume-or-new"`. Grund: BMAD-Doku
|
||
verlangt fresh chats pro Workflow – Context-Carryover zwischen BMAD-
|
||
Skills verschlechtert die Qualität messbar. Supervisor behält
|
||
`"resume-or-new"`, weil er den Graph-State über Heartbeats hinweg
|
||
verstehen muss.
|
||
|
||
## Retry-Logik bei `needs-rework`
|
||
|
||
- Max 3 Retries pro Story (konfigurierbar)
|
||
- Retry-Dev-Task geht immer an Dev-Worker, nie an QA
|
||
- Review-Findings fließen als `previous_review_findings`-Metadata in
|
||
den Retry-Prompt ein – Dev sieht genau, was zu fixen ist
|
||
- Bei Erreichen des Retry-Limits: Eskalation mit vier Handlungsoptionen
|
||
(Skip / Rewrite / Epic abbrechen / Stopp)
|
||
|
||
## Status-Reporting
|
||
|
||
Der Supervisor postet kurze Status-Comments am Parent-Issue bei:
|
||
|
||
- Bootstrap fertig (Epic-/Story-Zahlen, Layout, Zeitschätzung)
|
||
- Jede Story approved (Ein-Zeilen-Update)
|
||
- Retry gestartet (Findings-Summary)
|
||
- Retry-Limit erreicht (VOLLE Findings + Handlungsoptionen)
|
||
- Epic complete (Retro-Summary, Retry-Zahl, Dauer)
|
||
- Kritischer Fehler (präzise Detail-Info)
|
||
- Workflow complete (Gesamt-Summary)
|
||
|
||
Optional: Webhook auf `issue_comment_created` für Push-Notifications.
|
||
|
||
## Warum diese Trennung in drei Agents
|
||
|
||
**Supervisor separat vom Worker:** Sonst hast du einen Agent, der
|
||
plant UND arbeitet – exakt das Antipattern, vor dem BMADs Doku bei
|
||
Multi-Agent-Systemen warnt. Entscheidungen konzentrieren sich beim
|
||
Supervisor, was Debugging und Audit vereinfacht.
|
||
|
||
**Dev separat von QA:** BMADs adversarial-review funktioniert
|
||
nachweislich besser mit "Information asymmetry – Run reviews with
|
||
fresh context". Zwei unterschiedliche Modelle sind die strukturell
|
||
stärkste Form dieser Asymmetrie. Reviewer mit gleichem Modell und
|
||
Frischem Context ist zweitbeste Lösung – aber das Paperclip-Setup
|
||
erlaubt dir trivial, unterschiedliche Modelle zu pinnen, also warum
|
||
nicht.
|
||
|
||
**Alle drei in OpenCode, nicht ein Mix von Runtimes:** Paperclip
|
||
könnte theoretisch QA als `claude_local` und Dev als `opencode_local`
|
||
mischen. Macht das Setup komplexer, bringt aber nichts Wesentliches
|
||
– die Modell-Diversität kommt schon aus dem `OPENCODE_MODEL`-Pinning.
|