Adversarial Friends

Hand your spec, plan, or review to agent CLIs — claude, codex, agy, opencode — under adversarial lenses, then merge their critiques into one ranked findings report.

It automates a workflow you may already do by hand: run a review, paste the findings into a different model, ask whether they hold up, carry the argument back. Doing that manually means holding a claim ledger in your head. This keeps the ledger on disk.

📋 Contents

• Why more than one model
• Install
• Quickstart
• How it works
• Lenses
• What you get back
• What's implemented
• Documentation
• Development

🎯 Why more than one model

A single reviewer produces confident prose. Several reviewers produce claims that can be compared — and the disagreements are where the real problems are.

This tool's own design spec was built exactly this way:

That unproven claim was later confirmed and fixed. No single reviewer's pass would have surfaced all of it — see the revision history in the design spec for the full account.

📦 Install

Requires Python 3.11+ and at least one agent CLI. Judging modes additionally require two independent non-host friends. The runner itself is stdlib-only — zero runtime dependencies.

uv tool install adversarial-friends

# From git, for a version that is not yet released
uv tool install git+https://github.com/livingstaccato/adversarial-friends

# From a local checkout
git clone https://github.com/livingstaccato/adversarial-friends
cd adversarial-friends
uv tool install .

# Without installing at all
python -m adversarial_friends doctor

Then confirm what's actually available:

afriend doctor

doctor reports shared readiness — including ready, reachable-unconfigured, unavailable, disabled, host-excluded, and policy-blocked — plus what each friend can genuinely enforce. For Ollama, reachability alone is insufficient because dispatch also requires a model.

🚀 Quickstart

afriend run docs/my-design.md --mode report

The host is the orchestrator. In Codex, Codex remains the orchestrator and is included as a friend by default. The report labels it host-self-review (advisory), independent=false: it contributes findings and advisory verdicts, but cannot satisfy two-independent-friend admission, --require-friends participation, judging quorum, gate clearance, or loop convergence. Judging modes need two independent non-host friends in addition to any host; a report can be host-only. Non-Codex hosts are excluded by default. --include-self and --exclude-self are mutually exclusive overrides.

Manage persistent user defaults, including a default Ollama model, with:

afriend providers list
afriend providers enable claude
afriend providers disable opencode
afriend providers set-model ollama qwen3:8b
afriend providers clear-model ollama

For one automatic roster, --enable-provider NAME and --disable-provider NAME override those defaults. Disabled providers are not probed. An explicit --friend roster remains authoritative and may name the host or a disabled provider.

External-tool authority is separate from provider selection. The repeatable required-value form is --allow-external-tools=PROVIDER; the explicit global grant is --allow-external-tools=*. Unknown, duplicate, or mixed * plus provider grants are invalid, and the old valueless form is invalid. --unsafe-extra-args requires the global * grant plus --i-accept-unsandboxed. Grants do not change provider defaults and must be repeated as the same normalized set on resume.

Stdout carries one thing — the run directory. Read report.md inside it:

cat "$(afriend run docs/my-design.md --mode report)/report.md"

Pick your reviewers and lenses explicitly:

afriend run spec.md --friend codex:security --friend claude:ops

A third slot picks the model — required for ollama, which has no default:

afriend run spec.md --friend ollama:security:qwen3:0.6b

⚠️ --friend replaces discovery rather than adding to it. One --friend flag means a one-friend roster. A report with one friend is allowed as a recorded downgrade in run.json and report.md rather than being presented as a full review. crossexam, gate, and loop require at least two independent non-host friends; with fewer, they refuse with exit 3 before a run directory is created.

Runtime depends on the slowest selected friend, document size, and mode. Progress goes to stderr: a line per friend as it finishes, and a heartbeat naming whatever is still outstanding, so a quiet run is distinguishable from a hung one. --no-progress silences it for a caller that captures both streams together; reducing --timeout turns slow friends into failures rather than making them faster.

⚙️ How it works

Every friend gets its own prompt built from its own lens, runs in its own isolated directory, in its own process group:

The snapshot includes untracked files (git stash create omits them), and the working tree is never touched — a friend reviewing your repo can't see a half-staged index or scribble on your checkout.

Corroboration is the point

Two friends independently reaching the same conclusion is the strongest signal this tool produces, so deduplication is built to never destroy it:

Dedup is deliberately exact-match — whitespace and case only. Two friends describing one defect in different words produce two claims, which costs a round. Guessing at equivalence would corrupt the ledger, which is worse.

Claim states in cross-examination

Every claim --mode crossexam produces ends in one of eight states. Two of them — deadlocked and settled-upheld — deliberately need a human, and the report says so rather than quietly resolving them.

The gate loop

--mode gate is the one that fails a build, and clearing it is a back-and-forth rather than a single command:

🔬 Lenses

A lens is prose, not a config string. Its text is injected into that friend's prompt, so it shapes what the friend actually looks for.

scope is the one lens that doesn't demand a concrete failure scenario; "this is more than you need" is a legitimate finding without one. Claims from it are marked (advisory) in the report so they never carry the same weight as a reproducible defect.

📂 What you get back

<run-dir>/
├── report.md          ← ranked findings, corroboration, downgrades
├── run.json           ← machine-readable: friends, statuses, downgrades
├── claims.jsonl       ← append-only ledger: claims, aliases
├── artifact/          ← frozen copy of what was reviewed, hashed
└── round-1/
    ├── <friend>.prompt ← exactly what this friend was asked
    ├── <friend>.raw    ← its unmodified stdout
    ├── <friend>.err    ← its stderr (always present, even when empty)
    ├── <friend>.meta   ← argv, exit code, duration, timeout, orphan status
    └── <friend>.sandbox ← the OS policy it ran under, when one was applied

Runs land under ${XDG_STATE_HOME:-~/.local/state}/adversarial-friends/runs/, or wherever --out points.

Everything a friend was asked and everything it said is on disk. When a run comes back thin, that's what you read — not a guess.

✅ What's implemented

All four modes run.

afriend run docs/design.md --mode crossexam
afriend run docs/design.md --mode gate       # exit 1 while anything blocks
afriend resolve <run-id> --claim c-0001@1 \
    --disposition fixed --evidence src/auth.py:38

Disagreement is the output rather than a problem: two judges who still disagree at --max-rounds leave the claim deadlocked, and the report quotes both sides verbatim instead of resolving it by majority.

A resolution is an attestation, and the tool says so. It cannot know a defect is gone — only whether the location you named actually changed since the run started. A fix that landed outside the reviewed artifact is fine. --disposition fixed requires a verifiably changed location; unchanged or unverifiable evidence is refused. Use accepted-risk when verification is intentionally unavailable.

Deduplication is judgment the runner declines to fake. --merge exact (the default) merges only identical claims and always finishes unaided; --merge orchestrator stops with exit 10, writes the claims to REQUEST.json, and waits for you to say which are duplicates:

afriend run docs/design.md --merge orchestrator   # exit 10, writes REQUEST.json
# ...fill in the merges, save as RESPONSE.json...
afriend run --resume <run-id>                     # round 1 is not re-run

Resume verifies the original frozen artifact hash and saved Git snapshot before dispatch; it never substitutes current files. Security grants are also never restored from run.json: options such as --allow-external-tools=PROVIDER grants (or the global =* grant) must be repeated as the same normalized set. For 0.2.0 metadata, the report says external authority is legacy-unknown instead of inventing a historical guarantee.

Tired of --friend flags? afriend init writes a roster from what is actually installed, and ~/.config/adversarial-friends/roster.toml is picked up automatically. A repo-local roster never is — a cloned repo does not get to choose who reviews it (§13).

The same halt serves unparseable output (§14.2): repair is a pure transformation with no model call, so when it fails the runner asks you to read the raw text rather than discarding whatever the friend found.

There is no --max-spend-usd. A dollar cap needs per-CLI cost reporting nobody has captured, and a flag that silently never fires is worse than none — you would set it and believe you were protected. Use --max-calls, which is derived from your roster and actually enforced.

Agy's controlled reviewer is staged into the run's isolated workspace; it does not edit global Agy configuration. The staged agent and --sandbox are defense in depth, but sandbox does not mean external tools were denied. Agy remains external_tools=uncontrolled because its CLI cannot prove every plugin/MCP integration disabled invocation-locally. That is an accepted best-effort limitation: Agy is policy-blocked by default, while --allow-external-tools=agy records it as explicitly-allowed.

There is no gemini adapter: the gemini CLI returns an ineligible-tier error on the individual free tier, and Google's own supported path from there is Antigravity — which is agy.

Exit codes

A ceiling outranks everything below it, so a CI wrapper can read 11 as "retry" and 1 as "block" without ambiguity.

📚 Documentation

Using it as a skill or plugin

The skill payload ships inside the wheel as package data, and is mirrored under plugins/ for loaders that can't install a Python package:

# Claude Code
/plugin marketplace add /path/to/adversarial-friends/plugins

Plugins package capabilities; the Adversarial Friends plugin contributes the underlying skill, and that skill invokes the afriend CLI. The CLI never runs automatically by itself. In Codex, implicit skill selection is deliberately narrow: a request must start with afriend, say afriend to ..., or explicitly name Adversarial Friends. Direct skill selection also works. Generic “review this,” “poke holes,” “second opinion,” and architectural decision requests stay ordinary Codex work.

The package must therefore be installed for the skill to work — afriend doctor is the check. Conversational forms such as afriend docs/design.md map to afriend run docs/design.md; they are not additional CLI syntax.

🛠 Development

make install    # uv sync
make test       # pytest
make quality    # every portable CI gate, wheel checks, and tests
make diagrams   # re-render docs/architecture/*.puml

make quality runs every portable CI gate, including wheel construction and isolated installation. Linux CI additionally installs bubblewrap and requires the real OS-confinement tests to execute; macOS cannot reproduce that Linux- specific assertion locally. Use make act-ci for the closest local Linux run.

Two gates catch drift that is otherwise silent:

• plugin-sync — src/adversarial_friends/assets/ is canonical; the plugins/ tree is a byte-identical mirror. Edit assets, then make plugin-sync-copy.
• version-sync — VERSION must match the version field in every plugin manifest.

See AGENTS.md for repository layout and conventions.

📄 License

MIT — see LICENSE.