A portable council of specialist review personas for high-stakes engineering decisions. You convene 3–6 orthogonal reviewers, they critique your artifact from independent angles, and an orchestrator runs a bounded reflection debate (critique-before-concede, ≤4 rounds), then synthesizes one decision-grade answer with ranked issues, named dissents, and a false-consensus flag. Built to disagree with you — catch what a single pass misses.

⚠ Research-grade, not production-grade. This is a tool I built for myself and am publishing openly. Current dogfood journal snapshot: net-new catch rate is high (54/56 = 96%), but it is still mostly author/operator-run. The lens-baseline arm now passes its current gate (26/28 council beat same-lens single pass), and the strict blinded-judge Phase 2 arm is in progress (29/50 distinct rooms judged; 30 judged rows; 28/30 self-vs-blind agreement). Treat all metrics as directional dogfood evidence until issue #1 completes the 50-run Phase 2 decision.

Current work is tracked in docs/ROADMAP.md. Historical implementation plans remain archived for context.

# Read the maturity disclaimer above before relying on output as decision-grade.
npx @zhachory1/agent-fleet install --tool claude        # Claude Code (copies durable payloads)
# OR: npx @zhachory1/agent-fleet install --tool cursor    # Cursor   (→ ./.cursor/rules/)
# OR: npx @zhachory1/agent-fleet install --tool opencode  # opencode (→ ./.agent-fleet/)
# OR: npx @zhachory1/agent-fleet install --tool codex     # Codex    (→ ./.agent-fleet/ + ~/.codex/skills/{council,ship})
# OR: npx @zhachory1/agent-fleet install --tool cave      # Cave     (→ ./.cave/{agents,skills,prompts})
# OR: npx @zhachory1/agent-fleet install --print | pbcopy # any chat: paste the prompt

# Optional local clone for examples/dev:
git clone https://github.com/Zhachory1/agent-fleet ~/code/agent-fleet
cd ~/code/agent-fleet && bash examples/first-council/run.sh  # isolated tmpdir

examples/first-council/ is a complete, runnable council on a fictional-but-realistic PRD (checkout feature-flag). Includes the input artifact, the operator's solo decision, the per-persona POSITION blocks from a 2-round debate, the final synthesis with verdict + ranked issues + named dissents, and a net-new-vs-solo table. On that example council, the council surfaced 4 BLOCKERs/MAJORs the solo decision didn't name. Read it before deciding whether to install.

• You want a managed product — this is a prompt structure + bash helpers, not a service.
• You don't already use an AI coding agent (Claude Code / Cursor / Cave / opencode / Codex / chat).
• You're not willing to write your decision before the council convenes — Step 0 is the whole point.
• You want a CI gate / merge-blocker. This is a thinking tool; the output requires judgment.
• You need pristine evidence the tool works. The validation arm is still open.

your decision  ──▶  /council <task>
                      ├─ Step 0   — write your solo decision + risks you already see
                      ├─ Step 0.5 — same-lenses single-pass baseline (validation arm)
                      ├─ Step 2   — pick 3-6 personas by task (17 in catalog)
                      ├─ Step 3   — round 1: each persona reviews in isolation, blind
                      │             rounds 2..N (default 2, cap 4): each persona sees peers'
                      │             FULL prior positions and must REFUTE-FIRST before conceding
                      │             ↳ default-3 auto-included: red-team + mvp + occams-razor
                      │             ↳ deterministic convergence + capitulation detector
                      └─ Step 5   — synthesis: ranked issues, named dissents, false-consensus flag
                          Step 6  — journal the run (refuses unless transcript was captured)

Personas are stateless one-shot reviewers; the orchestrator (your AI coding agent) sequences everything and holds the transcript. The reflection debate (each persona reads peers' full prior positions, must refute before conceding) is what distinguishes a council from "ask 4 LLMs the same question and average." Red-team carries a hardened concession rule. Full design rationale: docs/PRD.md, docs/DD.md.

Core six (n≥18 validation runs each):

Promoted dogfood-validated ten (added 2026-06; promoted after ≥3 logged real runs with acted_on=true per agents/INDEX.md. Promotion removes the [experimental] frontmatter warning, but evidence is still mostly operator-run dogfood, not external validation):

Experimental one (still carries [experimental] in YAML frontmatter so selection UIs surface the warning):

The adversarial pair red-team + pre-mortem are methodologically distinct (red-team attacks the artifact as written; pre-mortem assumes it shipped + failed and reasons backward). The mvp persona is deliberately oppositional to red-team + pre-mortem: they find more risks, mvp cuts non-blocking scope. Picking mvp WITH either of them for any decision that's been through 2+ review rounds gives the reflection debate a real argument to resolve.

Full catalog with overlap matrix + selection decision tree + persona-pairing recommendations: agents/INDEX.md. Frontmatter detail (the model: haiku field is Claude-Code-specific metadata for cheaper spawned agents; strip it from your local copy if your tool errors on unknown frontmatter) is in AGENTS.md.

Personas + bash helpers are portable everywhere. What varies by tool is round-1 isolation — whether each persona's first POSITION is generated in a context that has not seen the other personas' POSITIONs (true parallel via subagent primitive) or sequentially in the same context ("single-context"). Reflection rounds (round 2+) work in both modes — each persona still reads peers' prior-round POSITIONs and must REFUTE-FIRST before conceding.

Honest disclosure on the difference: parallel mode guarantees personas don't influence each other's round-1 POSITIONs; single-context mode has known round-1 contamination risk (persona 4 has seen personas 1–3's outputs in-context even if prompted to ignore them) and measured lower agreement in this dogfood sample. A 10-pair measurement on this repo found parallel self-vs-blinded-judge agreement at 10/10 vs single-context at 8/10 (mean paired delta +20pp, median 0pp; 8/10 pairs tied, 2/10 favored parallel). Treat that as directional, not universal external evidence: single-context remains usable, but prefer true parallel subagents when your tool has them. See docs/measurement/parallel-vs-single-context.md.

Install only the agent prompts/personas/skills into the AI TUI's normal user/project resource folder. Do not move your codebase, vendor this repo into another repo, or paste giant prompts into app config when a resource folder exists.

Use --dir DIR when this repo does not know your TUI by name. It copies the generic payload into DIR/agents, DIR/skills/{council,ship}, and DIR/prompts/{council-orchestrator.md,ship-orchestrator.md}; uninstall with npx @zhachory1/agent-fleet install --dir DIR --uninstall.

Spawned personas and ship agents default to cheaper model: haiku; parent/orchestrator stays on your selected model. To install spawned agents with another model, run AGENT_FLEET_SUBAGENT_MODEL=<model> npx @zhachory1/agent-fleet install ... and rerun the installer to change it later.

If you are an AI agent doing the install, run npx @zhachory1/agent-fleet install --agent-instructions first. The same decision tree is also in INSTALL.md and install.manifest.json.

install.sh remains as the compatibility fallback for environments without npm/npx. Fallback Claude installs symlink from your local clone unless AGENT_FLEET_INSTALL_COPY=1 is set:

git clone https://github.com/Zhachory1/agent-fleet ~/code/agent-fleet
cd ~/code/agent-fleet
bash install.sh --tool claude

npx @zhachory1/agent-fleet install --tool claude  # copies agents → ~/.claude/agents, skills → ~/.claude/skills/{council,ship}
# in Claude Code:  /council review this diff …
npx @zhachory1/agent-fleet install --tool claude --uninstall  # reversible

npx @zhachory1/agent-fleet install --tool codex     # → ~/.codex/{skills/{council,ship},agent-fleet} + ./.agent-fleet refs
npx @zhachory1/agent-fleet install --tool opencode  # → ./.agent-fleet/
# then ask the agent: "act as the council orchestrator in ./.agent-fleet/council-orchestrator.md"

npx @zhachory1/agent-fleet install --tool cave      # → ./.cave/{agents,skills,prompts}

npx @zhachory1/agent-fleet install --tool cursor    # → ./.cursor/rules/

npx @zhachory1/agent-fleet install --dir ~/.mewrite   # → ~/.mewrite/{agents,skills,prompts}

npx @zhachory1/agent-fleet install --print   # prints the orchestrator prompt — paste into chat
# then paste 3-6 relevant agents/*.md persona prompts when asked

export AGENT_FLEET_HOME=~/code/agent-fleet

# Core (used by every run)
$AGENT_FLEET_HOME/lib/transcript.sh show [council-<slug>]   # full per-persona reasoning, boxed
$AGENT_FLEET_HOME/lib/transcript.sh rooms                   # past councils
$AGENT_FLEET_HOME/lib/journal.sh stats [N]                  # catch rate / false-alarm / gate verdict
$AGENT_FLEET_HOME/lib/journal.sh --help                     # see all flags

journal.sh append refuses unless the run's transcript was captured first — you cannot record a council whose thinking was not persisted.

If agents/_overlay.md exists, every persona loads it into its system prompt for your org's domain specifics. The overlay is loaded verbatim — treat it as code you are running. Inspect any overlay before trusting it:

$AGENT_FLEET_HOME/lib/overlay.sh show   # prints content + SHA256 + path
$AGENT_FLEET_HOME/lib/overlay.sh lint   # advisory: scans for suspicious patterns

The lint is heuristic and advisory — a clean lint does NOT prove an overlay is safe. Starter presets for common org shapes live in agents/_overlay.example/:

Each preset is edited heavily before installing. ml-scientist + ab-critic get noticeably sharper with a domain-rich overlay — the cost of running them against the bare skeleton is real. To add a public-safe preset, follow agents/_overlay.example/CONTRIBUTING.md.

Every catch-rate number above is self-reported by the operator. The blinded-judge mechanism narrows that bias channel: a fresh-context LLM (different account or different model family) judges whether the council's synthesis surfaced a net-new issue the solo decision missed — seeing only the artifact + solo + per-persona positions + operator synthesis + persona list, NOT the operator's post-hoc note or identity. Returns one binary NET_NEW_CATCH: true|false with a verbatim EVIDENCE quote.

This feature narrows the bias channel from author-judges-author to LLM-judges-LLM. It does not by itself upgrade the evidence tier to external human validation. That requires non-author operators and/or human judges running the workflow on their own artifacts.

# Phase 1: first 5 dual-judged councils establish noise floor; --phase1 required
$AGENT_FLEET_HOME/lib/blind-judge.sh judge council-<slug> --phase1 judge-a

# Phase 2: list candidate rooms, then judge one; --phase1 forbidden after Phase 1 closes
$AGENT_FLEET_HOME/lib/blind-judge.sh candidates
$AGENT_FLEET_HOME/lib/blind-judge.sh judge council-<slug>

# Optional non-interactive fresh CLI judges when available:
$AGENT_FLEET_HOME/lib/blind-judge.sh judge council-<slug> --judge-cli claude
$AGENT_FLEET_HOME/lib/blind-judge.sh judge council-<slug> --judge-cli agy --model-family claude

# Rescue legacy rooms that predate the durable-artifact change:
$AGENT_FLEET_HOME/lib/blind-judge.sh backfill-artifact council-<slug> --from <path>

The canonical rubric is lib/blind-judge-prompt.v2.txt (visible by design; changes bump the filename version and are git-history-visible). Full design

• Phase 1/Phase 2 calibration in docs/features/blinded-judge/PRD.md. Current state: Phase 1 calibration is complete; strict Phase 2 is in progress at 29/50 distinct judged rooms (30 judged rows; 28/30 self-vs-blind agreement). Issue #1 tracks the 50-run decision and README/stats update. See the Phase 2 runbook and the 2026-07-05 room audit for candidate selection and current local readiness.

for t in test/test_*.sh; do bash "$t"; done

CI runs the same loop on every push and PR (see badge above).

See CONTRIBUTING.md. The highest-leverage external contribution today is running councils cold on your own work and writing down the friction, especially whether the first-run install path and overlay presets match a non-author workflow.

MIT — Copyright (c) 2026 Zhachory Volker.