---
name: three-musketeers
description: "Orchestrate a long or complex BUILD through three separate subagents — a Builder that does the work, an Adversarial Reviewer whose only job is to poke holes in it, and a Verifier that confirms it genuinely works by behaving as a user (browser/computer use) — looping until the adversary finds nothing and the verifier passes. Use when the user wants to build something substantial and have a separate agent try to break or critique it and then verify it actually works — e.g. 'build it, have another agent poke holes, then verify it works', 'build, review, and verify this with subagents', 'drive this build with a builder, reviewer, and verifier', 'loop until it's genuinely done'. This is the build/verify phase — NOT planning a sketch (use adom-plan) and NOT auditing a finished artifact (use deep-audit). Triggers: /three-musketeers, three musketeers, builder adversary verifier, adversarial build loop, build and verify with subagents, run the musketeers, all for one."
user-invocable: true
argument-hint: "[task description or path to plan/spec]"
---

# three-musketeers — Builder / Adversary / Verifier build loop

Drive a long-running build through three roles, each a **separate subagent with fresh context**, looping until the work is genuinely done:

| Role | Job | One-line mandate |
|------|-----|------------------|
| **Builder** | Does the actual work | Build it. If the plan is wrong, do the smarter thing and note the change. |
| **Adversarial Reviewer** | Tries to poke holes | Assume it's broken. Find what the builder missed. |
| **Verifier** | Confirms it's genuinely done | Behave as a user. Does the thing actually work? |

"All for one" — three agents, one working build. This skill orchestrates the **build/verify phase**. It is not a planner and not a one-shot auditor (see boundaries below).

## When to use this (and when not)

| Situation | Use |
|-----------|-----|
| Long/complex build you want driven Builder→Adversary→Verifier to convergence | **this skill** |
| You have only a sketch/spec and want it stress-tested before building | **adom-plan** (run it first, then come here) |
| Something is already finished; you want a read-only second opinion | **deep-audit** |
| One small change; just confirm it works | plain edit + **verify** |

This skill *composes* the others: the Builder may invoke domain skills (KiCad, octolux-deploy, etc.) to do the work; the Verifier borrows **verify**'s behavioral approach; for high-stakes reviews the Adversary can escalate into a **deep-audit**-style fan-out.

## The complex-project workflow: plan robustly, then build robustly

three-musketeers is the **build half of a two-stage pipeline** for serious, expensive-to-get-wrong work:

1. **Plan robustly with [`adom-plan`](../adom-plan/SKILL.md)** — expand the sketch, then stress-test it with 6+ adversarial debate agents (Opus vs Sonnet pairs across architecture/implementation/security) plus a red-team consensus pass. Output: a vetted plan with a risk register and action items.
2. **Build robustly with three-musketeers** — hand that plan to the Builder, then loop Builder → Adversary → Verifier until it genuinely works.

The handoff is deliberate: adom-plan hardens *what to build*, three-musketeers hardens *that it was built and actually works*. And because three-musketeers treats the plan as a guide rather than a contract, the Builder is free to correct anything adom-plan got wrong (logging it as a plan amendment) — the two stages reinforce each other instead of locking in early mistakes.

**This pipeline is expensive (many agents, multiple model calls) but highly effective.** Reach for the full plan→build pipeline on high-stakes or long-running projects; for a quick build, three-musketeers alone (or even a single agent) is enough. When you finish an adom-plan run, recommending three-musketeers as the natural next step is the intended flow.

## Core principle: the verifier verifies BEHAVIOR, not plan-conformance

The most important rule in this skill, and the reason it exists:

> **The Verifier confirms the work by acting as a user — running the real flows via browser/computer use — and asking "does this actually work?" It must NEVER pass/fail the work by diffing against the original plan.**

Why: a plan encodes assumptions. A good builder experiments, discovers an assumption was wrong, and adapts to do the smarter thing. A verifier that checks against the *original* plan then raises a **false alarm** — flagging correct work as "not implemented as described." The work was fine; the plan was wrong.

Consequences, baked into the workflow:
- **Don't over-specify.** Leave the builder room to be right where the plan was wrong.
- **The builder amends the plan.** When it deviates, it appends a dated follow-up note explaining what changed and why — this becomes an intentional plan amendment, not a defect.
- **A plan mismatch is a note for the human, never an automatic verifier failure.** The verifier judges the *new* behavior on its merits.

## Model assignment

| Role | Default model | Rationale | Escalate / downgrade |
|------|--------------|-----------|----------------------|
| **Builder** | **Opus** (use the 1M-context variant for long builds) | Adapting when the plan is wrong is exactly the high-judgment work Opus is best at, and builder errors are the most expensive downstream. | Drop to **Sonnet** for mechanical, well-specified builds (boilerplate, pattern-driven migrations) to save cost. |
| **Adversarial Reviewer** | **Opus**, fresh context + a different disposition than the builder | Finding subtle holes is the highest-value adversarial-judgment task; model/disposition diversity surfaces disagreements a single model self-censors. | For high-stakes builds, add a **Sonnet** co-reviewer on enumerable angles (schema/contract/test-coverage), or fan out via deep-audit. |
| **Verifier** | **Sonnet** | Behavioral verification is mostly mechanical execution — drive the UI, run the flows, observe outcomes. Sonnet is cost-effective and reliable at tool-driven use. | Escalate to **Opus** when "is it genuinely done?" is ambiguous or safety-critical. |

Net pattern: **Opus builds, Opus adversarially reviews (diverse context), Sonnet verifies by behavior.** Set each subagent's model with the `model` option when spawning.

## Workflow

### Phase 0 — Scope, locate the plan, set the cycle budget

1. Resolve the target: the task the user described, the `argument-hint` path, an active plan in `/home/adom/.claude/plans/`, or what's in the conversation. If genuinely ambiguous, ask one question.
2. Confirm a plan/spec exists. If there's only a vague sketch, recommend running **adom-plan** first — a thin plan produces a weak loop. A *light* plan is fine (we want room for the builder); a *missing* one is not.
3. Note the **stage** and **how to run/exercise it** (the URL, command, or device the Verifier will drive). The Verifier needs a real way to behave as a user — establish it now.
4. State the lineup to the user before launching: roles, models, and the running target.

### Phase 1 — Builder

Spawn the Builder (see **Builder prompt** below) with the task, the plan, and the working context. The Builder:
- Does the real work, invoking whatever domain skills/tools the task needs.
- When it hits a wrong assumption, **adapts** and appends a `## Build notes — <date>` amendment to the plan file describing the deviation and why.
- Returns a structured summary: what it built, files touched, what it changed about the plan and why, and how to run/exercise the result.

### Phase 2 — Adversarial review

Spawn the Adversarial Reviewer (see **Adversary prompt**) with the builder's summary and the actual artifact. Default: **one focused Opus adversary**. Scale up to a small fan-out (e.g. correctness + security + a Sonnet co-reviewer) only for high-stakes builds, or delegate to **deep-audit** for maximum breadth.

The adversary is **read-only** and returns a findings list: `title | location (file:line) | what's wrong | failure scenario | severity | confidence`. It assumes the work is broken until proven otherwise. "Looks done" is not done.

### Phase 3 — Builder fixes (the loop body)

Hand the adversary's findings back to the Builder (continue the same Builder subagent via SendMessage to preserve its context). The Builder fixes real findings and explicitly rebuts any it disagrees with (a finding can be wrong, too). It returns an updated summary.

### Phase 4 — Behavioral verification

Spawn the Verifier (see **Verifier prompt**, Sonnet) with **how to run the thing** and **what the intended behavior is** — NOT the original plan as a checklist. The Verifier:
- Drives the artifact as a user would (browser use, computer use, CLI flows, the device) using the running target from Phase 0.
- Exercises the real paths, including edge/empty/error states.
- Reports, per flow: what it did, what it observed, PASS/FAIL on **behavior**, and any surprises.
- Flags plan↔behavior differences as **notes for the human**, never as failures.

If no behavioral surface is reachable (pure library, no UI/CLI), the Verifier runs the real test suite and exercises the public API directly — still observing behavior, still not diffing the plan.

### Phase 5 — Convergence control (loop)

Repeat **Phase 2 → 4** until **both**:
1. The adversary produces no new substantive findings (give it one extra "anything left?" round to confirm the well is dry — the tail matters), and
2. The verifier passes on behavior for every intended flow.

This loop is **self-paced** — you decide each round whether to continue, based on whether findings are still landing and verification still failing. Cap pathological loops: if the same finding survives 3 fix attempts, stop and surface it to the user as a genuine disagreement/blocker rather than looping forever. `log` each round's finding count and verifier verdict so the user sees progress.

### Phase 6 — Handoff

Write a handoff to `docs/build-<YYYY-MM-DD>.md` (or project root if no `docs/`; suffix `-2` if it exists). Self-contained, no emojis:

```markdown
# three-musketeers build — <project> — <YYYY-MM-DD>

**Task:** <what was built>  · **Stage:** <…>  · **Rounds:** <N>
**Models:** Builder <model> · Adversary <model> · Verifier <model>

## What was built
<summary of the delivered work + how to run/exercise it>

## Plan amendments (builder was right where the plan was wrong)
<each deviation: what the plan assumed, what the builder did instead, why>

## Adversary findings resolved
| Finding | Location | Severity | Resolution (fixed / rebutted + why) |

## Behavioral verification
| Flow exercised | What the verifier did | Result | Notes |

## Open items / human calls
<surviving disagreements, plan↔behavior notes, anything not reachable to verify>
```

### Phase 7 — Present to user

1. Headline: built + verified, in N rounds, with the run target.
2. Plan amendments (the "builder was right" story is high-value — surface it).
3. Findings resolved vs. open, and the behavioral verdict per flow.
4. Path to the handoff doc.
5. Note the Builder subagent is still resident — offer follow-ups via SendMessage.

## Agent prompt templates

Fill the `{{...}}` slots. Spawn each role as its own subagent with the model from the table.

### Builder prompt

```
You are the BUILDER in a three-role build loop. Your job is to do the actual work.

## Task
{{TASK}}

## Plan / spec (a guide, not a contract)
{{PLAN — may be light on purpose}}

## Working context
{{repo/dir, how to run it, relevant domain skills to use}}

Build it. Use whatever tools and domain skills the task needs.

CRITICAL: The plan encodes assumptions that may be wrong. If you discover a better
way or a broken assumption, DO THE SMARTER THING — do not force the plan. Then append
a "## Build notes — {{DATE}}" section to the plan file documenting what you changed and
why. Deviating correctly is success, not failure.

Return (your final message IS the report):
1. What you built — components, behavior delivered.
2. Files touched (path — one line each).
3. Plan amendments — every deviation, with the wrong assumption and your reasoning.
4. How to run / exercise it — the exact URL, command, or device flow a user would use.
```

### Adversary prompt

```
You are the ADVERSARIAL REVIEWER in a three-role build loop. Your ONLY job is to poke
holes in what the builder did. Assume it is broken until proven otherwise. "Looks done"
is not done. You are STRICTLY READ-ONLY — do not modify anything.

## What the builder claims it built
{{BUILDER SUMMARY}}

## The artifact
{{file pointers / how to inspect}}

Hunt real defects: logic gaps, unhandled edge/empty/error states, race conditions,
attack surface, silent failures, fragile assumptions, things that pass a happy path but
break on the second try. Be concrete — name the failure scenario, not just the smell.

Return:
1. One-paragraph verdict: how broken is this, really?
2. Findings table: title | location (file:line) | what's wrong | failure scenario | severity (Critical/High/Med/Low) | confidence (High/Med/Low)
3. Top must-fixes, ranked.

Cite file:line for every finding. Mark uncertain ones low-confidence. No padding.
```

### Verifier prompt

```
You are the VERIFIER in a three-role build loop. You confirm the work is GENUINELY done
by BEHAVING AS A USER — not by checking it against any plan.

## How to run / exercise it
{{RUN TARGET — URL, command, device, browser/computer-use entry point}}

## Intended behavior (what a user should be able to do)
{{behavior goals — NOT the original plan as a checklist}}

Drive the real thing the way a user would (browser use / computer use / CLI / device).
Exercise the main flows AND the edges: empty, error, repeated actions, bad input.

ABSOLUTE RULE: Do not pass or fail this work by comparing it to the original plan. The
builder may have correctly deviated. Judge the actual behavior on its merits. If behavior
differs from what a plan said, record it as a NOTE FOR THE HUMAN — never an automatic fail.

If there is no UI/CLI to drive (pure library), run the real test suite and exercise the
public API directly — still observe behavior, still don't diff the plan.

Return:
1. Overall behavioral verdict: does it actually work?
2. Per-flow table: flow | what you did | what you observed | PASS/FAIL (behavior) | notes
3. Plan↔behavior differences as human notes (not failures).
4. Anything you could not reach to verify.
```

## Example run

A user has an approved plan to add CSV export to a reporting dashboard.

1. **Builder (Opus)** implements it, but discovers the plan's assumed `/api/report.json` endpoint returns paginated data, not the full set. It adapts — streams all pages server-side — and appends a `## Build notes` amendment to the plan explaining the deviation.
2. **Adversary (Opus, fresh context)** finds two real holes: the export blocks the event loop for large reports, and quotes in cell values aren't escaped (CSV injection). Returns them with file:line and failure scenarios.
3. **Builder** fixes both, rebuts a third low-confidence finding as a non-issue.
4. **Verifier (Sonnet)** drives the dashboard in a browser: clicks Export on an empty report, a 50k-row report, and one with quotes/commas — confirms the file downloads and opens cleanly in a spreadsheet. Notes that behavior differs from the plan (streaming vs. single fetch) — flagged as a human note, **not** a failure, because the export works.
5. **Round 2** adversary finds nothing new; verifier passes. Handoff written to `docs/build-<date>.md` with the plan amendment, resolved findings, and the behavioral checks.

Net: the plan was wrong about pagination, the builder was right, and the verifier confirmed the *real* behavior instead of raising a false "doesn't match the plan" alarm.

## Guidelines

- **Each role is a fresh subagent.** Independence is the point — the adversary must not inherit the builder's blind spots. Use the `model` option per the table; give the adversary a different disposition than the builder.
- **Continue the Builder via SendMessage** across fix rounds so it keeps its context; spawn the adversary and verifier fresh each round so they stay independent.
- **Never let the verifier grade against the plan.** This is the whole point of the skill. Behavior is truth; the plan is a starting guess.
- **Builder deviations are documented, not punished.** The plan-amendment trail is a first-class deliverable.
- **Loop to a dry well, but cap it.** Confirm the adversary has nothing left; stop and escalate to the human if a finding survives 3 fix attempts.
- **Scale to stakes.** Small build → one adversary, one verify pass. High-stakes → fan-out adversary (or deep-audit), Opus verifier, more rounds.
- **Plan first, audit after are different skills.** Sketch with no build → adom-plan. Finished thing → deep-audit. This skill owns the messy middle.