# 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.