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.