Claude Skill

advisory-board

For an explicitly requested advisory board, roundtable, panel, idea tournament, multi-model review or debate, red-team by several models, or consensus handoff, run an authorized multi-provider process with recorded seats, usage, and evidence.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download timharris707-skills-plugins_clickai-codex_skills_decide_advisory-board-b6a29f5.zip · 672 KB

Install

skills CLI npx skills add https://github.com/timharris707/skills/tree/main/plugins/clickai-codex/skills/decide/advisory-board
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install timharris707-skills@llmmart
Git git clone https://github.com/timharris707/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole timharris707/skills collection as a plugin from our marketplace. Git is the plain clone.

README

Advisory Board

Get a room full of expert advisors for any big decision — before you commit. Bring the board whatever you're weighing — a plan, a draft, a contract, a design, a real-life choice — and several leading AI models each examine it independently, then read each other's notes, argue out the disagreements, and hand you back one clear answer: what's solid, what's risky, and what to do next. You read it like a memo, not a config file. It works for software, but also for product, research, legal, business, and writing decisions.

The default board uses frontier models from Anthropic, OpenAI, Google, and xAI — Claude, Codex, Gemini, and Grok — each sitting in a different seat. Provider-maintained aliases/defaults select the strongest current model at run time, while explicit model overrides remain pinned. Each seat reviews the same source on its own, then reads a packet of the others' findings and answers the strongest objections before a final synthesis turns the debate into one working handoff.

Use it to:

  • weigh a big personal or business decision — a job offer, a price change, going full-time on a side project;
  • get a sharp first read on a draft, a pitch, a cover letter, or a hard email before you send it;
  • pressure-test a plan, design, or architecture before you build;
  • surface risks, stale assumptions, and missing evidence a single opinion would miss;
  • collapse several strong opinions into one clean, plain-English takeaway.

Default behavior: two rounds of review and rebuttal; read-only unless edits are explicitly requested; you see exactly what would be sent to each provider and approve it before anything leaves your machine — redact what's sensitive, or run a fully local board where nothing is sent at all.

Run it your way. Advisory Board is a provider-agnostic agent skill — convene the board through Claude Code, Codex, or whatever harness you prefer. Install it from the repo root, or read SKILL.md directly.

Prefer a polished app instead? Panely is a sibling product built around the same idea — a local-first advisory room. Advisory Board is the open agent skill; Panely is the app. Same maker.

See It In Action

Here's a real board debating a real decision — "Should we relocate our family across the country for this job offer?" The offer looks great on paper: a +37.5% raise. The board's job was to check whether the headline survives contact with the math.

Verdict: Go ahead, with conditions — unanimous, high confidence. (A three-seat board sat for this run.) The reveal all three advisors converged on: the raise is consumed almost entirely by rent, quietly collapsing monthly savings from $2,750 to $537; the $20k "covers the move" sign-on is gross and nets ~$11–13k against an ~$18k move; and the "take-home rises" headline inverts at a realistic tax rate. They didn't say "don't" — they said exactly what to resolve first, and handed back the next steps.

Read it two ways — start with the skim:

  • The 30-second brief: quick-verdict for the relocation decision — the verdict, the must-resolve blockers as one-liners, the top next steps. The teaser you'd forward.
  • The full handoff: the complete record — the round-by-round debate, every consensus blocker, and preserved cross-model dissent (Gemini: "you're shorting your marital operating system").
  • See the input, too: the decision brief the board reviewed — good input in, good output out.

Every run ends in a single, self-contained HTML handoff that opens offline in any browser with no dependencies.

Also built for engineers: point the board at a real codebase and advisors cite exact path:line evidence. Every run also emits a machine-readable verdict.json; scripts/board_verdict.py --gate turns the board's ship | caution | block call into a CI exit code, and scripts/format_output.py reshapes it into a PR comment, Slack message, or TL;DR. See the technical payments idempotency review for a code-grounded run.

More runs to browse: the side-project go-full-time decision, the API rate-limiter readiness review, and the board dogfooding the design of its own next feature — a 3-seat design roundtable with preserved cross-model dissent.

The board reviewing its own PRs: during the v1.13→v1.15 release train, every substantial PR got a 2-seat board review (Claude Opus + Codex gpt-5.5) on a frozen review packet, then a --revise re-review of the fixes — each pair linked by directory suffix (the revise run appends the next numeric suffix to the original run's directory name). Browse the committed rulings: the endorsement-pass review (block → caution across the revise pass), the echo-score review (the board ruled block where a solo review agent had said ship — divergence with recorded dissent), the live-progress review (caution → a clean ship), and the rubric-round review (a split block with preserved cross-seat dissent; the revise pass confirmed both blockers fixed and surfaced a new one). There's also a second design roundtable: the rubric-first deliberation brief — 3 seats, unanimous caution, three preserved dissents.

The look comes from one template, handoff-template.html, so any agent that installs the skill renders the same clean output.

Going Deeper

  • The GitHub Pages guide — the friendly walkthrough: who it's for, how a run works, what you walk away with, and the engineer-grade features (repo grounding, lens presets, CI gating).
  • SKILL.md — the skill itself: the full workflow contract any agent runs.
  • references/ — prompt templates, lens presets, preflight, board composition, data handling, epistemics, verdict schema, output formats, and the handoff/quick-verdict HTML templates.
  • scripts/ — board_verdict.py (CI gate) and format_output.py (PR comment / Slack / TL;DR reshaping).
  • CHANGELOG.md — versioned history; releases tag as advisory-board/vX.Y.Z.

Skill manifest

Advisory Board

Read the Codex desktop binding when this workflow needs harness mechanics, model routing, or recovery.

Bring an idea, problem, plan, or architecture to a board of frontier models sitting in different roles. The board runs in one of three modes, the interaction topology chosen with the user at intake (references/modes.md). Formal Board Review is the default and the protocol this document defines: an independent first round, then rebuttal, then a structured verdict. Roundtable is collaborative, on a shared transcript, with an optional moderator. Competitive runs pitch, then critique, then a blind vote. Whatever the mode, you leave with the strongest conclusion the board can reach together and a clean takeaway, not disconnected opinions.

Must Not

Hard rules, collected here so they are never missed (each is elaborated in context below). Violating one invalidates the run.

  • Never write files or make edits unless the user explicitly asked for edits: the board is read-only by default.
  • Never write artifacts into a tracked git tree without naming the location first; default to the persistent runs root (~/.advisory-board/runs/<slug>-<date>/), or a throwaway /tmp/advisory-board-* folder with --ephemeral.
  • Never substitute a model silently: if a requested model is unavailable, use the nearest same-provider frontier model and say so.
  • Never skip the data-handling disclosure for non-public material, not even when the user says "use defaults." Disclose what leaves the machine and to whom, and get a go-ahead, before any external seat runs (references/data-handling.md).
  • Never present a degraded or dropped seat as a full board: label it on the seat card and in verdict.json (dropped: true) on a Formal Board Review run; Roundtable and Competitive, which emit no verdict.json, record it in run-metadata.md and name it in synthesis.md/results.md (references/modes.md). A board needs at least two seats that actually ran.
  • Never print or store secrets in prompts, packets, artifacts, logs, or metadata: no keys, tokens, cookies, or private environment values.
  • Never launch a run the user hasn't confirmed. The guided intake (references/intake-interview.md) is mandatory: mode, seats, lenses, effort, rounds, and output are the user's choices, made on the record. An already explicit approval of a complete plan satisfies its confirmation; reuse it. "Use defaults" still needs a concrete plan when seats, cost, or data scope have not yet been established.

Core Defaults

  • Use subscription CLIs by default, not provider API keys.
  • Run read-only unless the user explicitly asks for edits.
  • Rounds: 2. Cross-reading: summaries. Final artifact: full handoff (Markdown plus a self-contained HTML view).
  • Write run artifacts to the persistent runs root, ~/.advisory-board/runs/<slug>-<date>/ (a same-day rerun gets a -2 suffix, never an overwrite), so runs stop evaporating and run_board.py history can list them. --runs-root/--out redirect; --ephemeral opts back into a throwaway /tmp/advisory-board-* folder. Every real run announces where its artifacts land on its first output line. Persistence changes only the disk location: artifacts inherit the run's sensitivity handling (references/data-handling.md).
  • Writing artifacts into the reviewed project is itself a write, even on a read-only review: do that only when the user asks or agrees, prefer a dedicated advisory-board/<timestamp>/ (or docs/advisory-board/<timestamp>/) folder, and never write into a tracked git tree without naming the location first.
  • One flag sets the whole cost/depth posture: --tier quick|standard|deep: rounds, cross-reading, and per-seat reasoning together (standard is today's defaults, a deliberate no-op; exact per-tier values live in the registry and scripts/README.md). The tier is a base: explicit flags (--rounds, --cross-reading, per-seat --effort) always override it, and run-recipe.yaml records the resolved selectors and effort values. Provider-maintained aliases deliberately re-resolve on a later run; --model seat=id is the exact-pin escape hatch. Four frontier models at high reasoning across several rounds can take minutes and meaningful tokens: flag a large run before launching it; run_board.py run … --dry-run prints a best-effort estimate.

Modes

The three topologies, their mechanics, hand-runnable protocols for the two the conductor doesn't drive yet, and the intent→mode recommendation table live in references/modes.md. In brief: Formal Board Review is this document's Round Protocol and everything the conductor, verdict chain, and gate support, the default. Roundtable and Competitive run by hand via the portable fallback, produce their own artifact sets, and never feed verdict.json or a gate. The mode is settled at intake, with the user.

Guided Intake (mandatory)

Every run opens with the wizard in references/intake-interview.md, presented as selection cards like the grilling skill's rounds, recommendation first. The sequence, in order:

  1. Preflight first, within authorization. Read the registered CLI capabilities before offering seats. Doctor includes model smoke calls, so announce their count and rough usage and obtain any required provider authorization before running it. A Claude smoke call counts as Anthropic work. Check only authorized providers when the installed command supports selection; otherwise use individual version/auth checks and authorized smoke calls. Report each candidate as unverified, GO, or NO-GO using the preflight definitions. An unapproved, untested seat stays unverified, not launch-ready; do not contact it.
  2. Goal → mode. Hear the goal in the user's words, recommend a mode (and lens preset) from references/modes.md §Choosing a mode, and let the user pick from all three.
  3. Seats. Any 2–10 of the GO providers ("latest frontier of each" is the shortcut); show the seat→provider→lens table before launch; warn on cost for big or deep boards.
  4. Reasoning depth. Highest available (default) / Standard / Quick via --tier; per-seat overrides on request.
  5. Rounds and output. With defaults marked.
  6. Confirm-summary. The resolved plan as one card; nothing launches without this yes.

"Use defaults" resolves steps 2-5 to defaults and goes to step 6, but only after step 1 completes and its findings are applied to the card: the required checks run for the authorized selection (a full doctor sweep is optional), a seat that is not GO is never a default, and below two GO seats there is no defaults board (step 3's fallbacks are settled with the user first). An existing explicit confirmation of the same resolved plan remains valid, and it never waives data-handling consent: if the material isn't clearly public, still disclose which providers will receive it and get an explicit go-ahead before launching any external seat (references/data-handling.md).

Model Lineup

Target the strongest reasoning model each provider offers at run time. Defaults use provider-maintained selectors so new frontier releases do not require a skill edit; explicit --model seat=id overrides pin exact IDs.

  • Claude seat: Anthropic's maintained fable alias at --effort max. Where fable doesn't resolve (older CLI or account), preflight proposes the opus fallback and never applies it silently.
  • Codex seat: --model codex=gpt-6-astra pins the documented Astra identifier when requested, with approved effort. Verify the installed CLI flags, actual account/configuration route, and model resolution during authorized preflight. Confirm the model that answered from CLI evidence; if it cannot be established, keep the seat unverified. A rejected pin is NO-GO; propose a supported alternative for approval rather than silently substituting. An unpinned auto seat follows CLI configuration and proves no particular model. See the capability evidence.
  • Gemini seat: Google's maintained pro alias (latest highest-reasoning Pro model) with the CLI's highest available thinking level.
  • Grok seat: grok-4.5 through the official grok CLI at --effort high, the only model the CLI currently lists.

The selector (fable, pro, grok-4.5, or Codex auto) and the model that actually answered are separate provenance fields. If a CLI cannot report the resolved ID, record unknown rather than pretending. Use an exact --model override for an eval or replay that must not float.

Preflight. Run references/preflight.md before launching: for each seat, check the CLI is present, auth is active (subscription-backed where possible), the requested model resolves, and a one-token smoke ping returns. For a first run or new machine, scoped checks can establish GO; a full doctor is optional. After authorizing all of its smoke calls, run_board.py doctor sweeps every registered provider with per-provider fix-it steps and a viable-board summary: probes and smoke-pings only, it never reads or sends your material; run_board.py toolchain checks CLI currency and (consent-gated) updates or installs. Proceed only with at least two seats GO; fewer isn't a dead end: preflight distinguishes not installed from installed-but-unauthed and names the fallbacks: a same-provider multi-lens board or a local/human seat (references/board-composition.md). Label any degraded or dropped seat in the handoff.

Seats

Give each seat its own angle so the board covers more ground than any single reviewer, and match the lenses to the subject. Pick a ready-made lens set from references/lens-presets.md, or compose your own: software-architecture (default), product-strategy, research-paper, legal-contract, business-decision, writing-editing, red-team (every seat hostile; the stress-test preset), stakeholder-panel (convene "the room this decision would face"). The same lens on two different providers is a valid cross-model pairing; only same-provider-same-lens wastes a seat. For software and technical work, the default split:

  • Claude: architecture, systems, and adversarial design review.
  • Codex: repo-grounded implementation, migration, testing, and execution.
  • Gemini: product, operations, rollout, latency, evaluation, and user-workflow risk.
  • Grok: contrarian synthesis, hidden assumptions, alternatives, and decision-changing evidence.

For non-software subjects (strategy, research, writing, business, policy), assign comparable lenses: e.g. one seat on first-principles soundness, one on execution and feasibility, one on second-order consequences and stakeholder or user risk.

Every seat still answers the full brief; the lens reduces blind spots, it doesn't narrow responsibility.

The board defaults to four seats but isn't fixed at four. For sizing (2–10), the same provider in multiple seats (each duplicate taking its own lens), a human or local-model seat, an Antigravity seat, and minimal "works with what you have" lineups, see references/board-composition.md.

Data Handling

A board sends the same source material to every seat's provider. Before the first call, if the material isn't already public, tell the user what will leave the machine and to whom, and get a go-ahead. For sensitive material, redact the shared source packet; for must-not-leave material, run a local-only board or don't run it. Full guidance: references/data-handling.md.

Repo-grounding & verification

By default a board reviews the text you hand it and is blind to the codebase that text is about, so findings come back conditional on the cited factual base, none confirmed by a seat that read the code. --repo PATH closes that gap: it augments --source (the source file still frames the question; the repo is the evidence base) by handing every seat a read-only snapshot of the repository, one that is .gitignore-respecting, .git-excluded, secret-denylisted, and symlink-confined, so seats verify claims against real code and cite real path:line. Consent binds to the snapshot's scope hash alongside the source-packet hash, and repo-scope-manifest.json records exactly what was in scope at approval.

Grounding then makes the verdict chain trustworthy on code, not just prose: verify --source <repo> --run <out> resolves those citations against the tree and stamps each verified/unverified/refuted: a fabricated citation stamps refuted and validate --gate abstains.

In gate mode (--repo on a gate-bearing run), the safety policy is read XOR network: every seat must be network-isolatable, because a grounded seat that is also networked can read a secret and exfiltrate it. Seats that can't be de-networked (today gemini, antigravity) make a gate+--repo run refuse, the offending seat named as a labeled NO-GO, never silently dropped, and a gate-bearing run never silently falls back to advisory. Advisory + --repo is the home for casual self-review of your own repo (network on, you own the risk) with a loud disclosure.

Be honest about the limits when reporting: a verified stamp means the receipt resolves, not that the inference drawn from it is sound, and it is a statement about the snapshot at approval time. The poisoned-repo and snapshot-drift caveats, and why the snapshot bounds consent rather than physical reads, are in references/data-handling.md §Repo-grounded review.

Round Protocol

This section defines Formal Board Review, the default mode and the only one the conductor drives end-to-end. Roundtable and Competitive replace it with their own phase structures (references/modes.md).

Rubric-first scoring (--rubric, optional). Before round 1 the board can agree its own weighted criteria and then score every round against them, so the verdict is backed by a comparable number as well as prose. Two mechanically-checked passes run first: a proposal fan-out (every seat proposes 3–7 weighted criteria from the same source packet round 1 sees; the conductor mints the proposal ids: a model never mints identity) and a chair merge (one board seat merges every usable proposal into one weighted rubric with an explicit partition; the conductor mechanically reconciles the partition and the weights-sum-to-100 invariant, retries once, then refuses). Too few proposals or an unreconcilable merge refuses the run before any opinion round spends a token, writing rubric-rejected.json; this is the one place in the whole skill that refuses outright rather than degrading. Success writes rubric.json post-consent, pre-rounds, so it survives a later scoring failure. The agreed rubric is injected into every opinion round: each seat emits one SCORE cN: <1-5> line per criterion (a bad or missing line degrades that cell to absent, never imputed, and never making the seat unusable) plus an optional RUBRIC-NOTE: objection (recorded, never debated: scoring under the rubric is accepting it). --rounds auto convergence widens to include score movement. On a --revise --rubric run the prior rubric is carried forward mechanically, so scores stay comparable across revisions. Scores are informational only: the gate never reads them. Injected block and token grammar: references/prompt-templates.md; artifacts and chair-seat resolution: references/verdict-schema.md, scripts/README.md.

Round 1: independent.

  • Give each seat the same source packet and its role lens, nothing else.
  • No other seat's opinions.
  • Require: verdict (with a confidence level: low/medium/high), strongest objections, revised sequence, invariants, risks, and concrete evidence.

Round 2: rebuttal (default).

  • Build a board packet from Round 1: a structured digest (summaries, the default) that puts every seat's take on each topic side by side under a verdict/citation agreement header, where the board agrees and where it splits, or the full prior responses when the token budget allows (full). run_board.py builds this deterministically from each review's own section structure plus the VERDICT: tokens; it never clusters claims by meaning. --digest-format json also writes each round's digest as typed JSON.
  • Ask each seat: what another seat caught that you missed, what changed your view (and whether the change is driven by evidence or mere deference; see references/epistemics.md), what you still dispute, what should become consensus, and what stays unresolved.

Round 3: convergence (optional).

  • Give each seat the Round 2 packet.
  • Ask for the final position, hard dissent, and the smallest viable plan.

Adaptive rounds (auto).

  • Stop early when the board has converged rather than spending a round to rubber-stamp: a shared verdict, high confidence, and no material dissent after a round.
  • Add a round when material dissent or low confidence remains and another exchange could plausibly resolve it, up to the --max-rounds ceiling (default 3).
  • run_board.py --rounds auto makes this concrete: each seat ends its review with a VERDICT: ship|caution|block line, and the conductor measures movement between rounds as a pure function over that token plus the seat's concrete citations, never the prose (the model reasons; the conductor diffs tokens). It keeps going while the board is still moving and stops the moment it goes quiet; the per-round movement and the stop reason are recorded in run-metadata.md (## Convergence).
  • Independence / echo score: convergence can be earned (the seats independently reached the same answer) or social (they read each other and drifted into agreement). Round 2+ seats self-report a BASIS: independent|evidence|deference line, and the conductor scores echo risk over the final round's parsed signals as a coarse low / moderate / high band with a one-line explanation, recorded in run-metadata.md. It flags possible echo; it does not prove independence (references/epistemics.md).

Final synthesis.

  • After the last round, write the handoff: consensus, dissent (and why it matters), revised plan, risks, invariants, evidence, and next actions.
  • Write the handoff for a human who was not in the room. Lead with the bottom line, summary in verdict.json: 3–6 plain sentences saying what was reviewed, what the board decided, why, and what happens next. Every prose field must read as plain English on the first pass: short sentences, no coined compound labels, no unexplained jargon; a finding's title is a complete sentence naming what can go wrong, and mechanism detail lives in the evidence citations, not the prose. This contract binds a hand-authored verdict (the degraded-synthesizer path) exactly as it binds the synthesizer seat.
  • Prefer a neutral synthesizer, a seat that didn't debate or a blind merge, so the chair doesn't grade its own work (references/epistemics.md). If the board is unanimous, include a minority report: the strongest case against the verdict.
  • Label model and round provenance (the model that actually answered, not just the one requested), and split the findings into three explicit buckets: evidence-backed (tied to a file, fact, run, or citation), judgment calls (reasoned but unproven here), and couldn't-verify (claims the board leaned on but didn't check, plus the shared blind spots no seat could see). For each load-bearing conclusion, note what would change it. The couldn't-verify bucket is the main guard against a confident, unanimous, wrong call: three models can converge on the same missing fact (references/epistemics.md).
  • Emit verdict.json alongside the prose (references/verdict-schema.md) so the result can drive a gate or other tooling.

Artifact Standard

Write:

  • round-1/<seat>.md (and round-2/, round-3/ as rounds run)
  • board-packet-round-2.md (and board-packet-round-3.md when needed)
  • final-consensus.md: the handoff in Markdown
  • final-consensus.html: a self-contained, human-readable view of the handoff. Render it deterministically with scripts/render_handoff.py from a handoff-data.json (recommended: guarantees no leftover placeholders or template drift), or fill references/handoff-template.html by hand. render_verdict.py --shape chooses the view (full handoff, quick verdict, or implementation sequence) and --filter trims by severity; a dropped section is stated with counts, never silently elided; see references/output-formats.md.
  • verdict.json: the machine-readable verdict (references/verdict-schema.md); gate or reformat it with scripts/
  • changes.json + revised-draft.*: only with run --output revised-draft. A board-derived revised copy of the source, each edit mapped to the board finding it resolves and mechanically validated, then voted on per edit by the non-revision seats in the endorsement pass (ENDORSE/OBJECT/ABSTAIN; objections are recorded for a human to read, never resolved by another model loop; --no-endorse opts out, leaving a findings-mapped, not board-endorsed, run). The draft is byte-clean (the revised source bytes and nothing else) and the source file is never written: applying the revision is your act. Conflicting findings surface as unresolved entries, never silently reconciled. A code source also gets a git-apply-able revised-draft.patch; a prose source instead gets a word-level redline section in the full-handoff HTML; both are pure views, sha-verified against changes.json before a byte is diffed. Schema and validation: references/changes-schema.md.
  • Grounded citation snippets. When a grounded run resolves a code citation, the cited lines are captured onto the evidence entry so the handoff embeds the receipt itself, self-contained even though the repo snapshot is cleaned up after the run (references/verdict-schema.md).
  • rubric.json + scorecard.json: only with --rubric. The pre-round merged rubric (criteria, weights, chair partition, proposal provenance) and the post-rounds score trajectory with conductor-computed per-seat totals and coarse bands. Both strictly validated; a validation failure warns and writes nothing: the rounds and verdict still stand. Scores never move the verdict or the gate; a severe token↔band contradiction is recorded and surfaced loudly in the verdict summary. Schemas: references/verdict-schema.md, scripts/README.md.
  • run-metadata.md: the provenance record. Commands, the model that actually answered per seat, auth mode (no secrets), per-seat status (ran / degraded / dropped), timings, and source paths. Use references/run-metadata-template.md. When a seat CLI reports its own token usage, record per-seat tokens and a best-effort cost/time line; nothing is ever guessed.

When a seat is degraded or dropped, show it on its HTML seat card (status pill) and in verdict.json (dropped: true); never let a smaller board look like a full one. Derive lighter shares (TL;DR, PR comment, Slack, print/PDF) per references/output-formats.md.

Output contract for the HTML. It is a view of final-consensus.md, not a second source of truth: the two must not disagree. The rendered file must contain no leftover {{tokens}} and no template scaffolding comments, and must stay self-contained (inline CSS only; no external fonts, CDNs, scripts, or remote <link>/<script src>) so it opens offline on a double-click. Follow the template's two-placeholder convention: replace each single {{TOKEN}} in place, and duplicate each BEGIN/END block once per item (delete the sample block if there are none).

How A Run Executes

The conductor, scripts/run_board.py, is the canonical way to drive a board. It owns the load-bearing mechanics in code: the seat-adapter registry (the one place that knows each CLI's flags, isolation, and model-id self-heal), the executable preflight (GO/NO-GO), the hash-bound egress/quarantine gate before any byte leaves, the round fan-outs with the failure protocol, the verdict chain (verify evidence → consensus md/html → validate/gate), and the run history. Synthesis stays your reasoning task: the conductor stops at clean per-round packets and hands them to you (or one neutral seat) to fill verdict.json, then you call the chain. Run scripts/run_board.py run …; a real run is in the repo-root examples/payments-idempotency-review/.

Beyond run, know these run controls exist; exact flags, semantics, and edge rules are in scripts/README.md and --help:

  • Per-seat --timeout and --effort overrides (seat ids as in --model; an ambiguous provider name on a duplicate-provider board is refused, never silently collapsed).
  • --revise <prior run dir>: re-review a revised draft. Round-1 prompts carry a mechanical digest of the prior verdict plus the diff from the previously reviewed draft (sha-verified; omitted loudly when unrecoverable), every injected byte inside the consent packet hash; the new verdict records lineage and the consensus leads with cleared / still-open / new.
  • ask "<question>" --run <dir>: one-round post-verdict cross-examination, from a context packet built only from that run's own artifacts, bounded to the run and re-consented like any egress (the sensitivity floor only ever tightens); writes addendum-N.md.
  • board_verdict.py amend: append-only human tuning of a completed verdict (a confidence change, caveat, or severity note, each with provenance) that never rewrites the board's own words.
  • run --output revised-draft: the board-endorsed revision (see Artifact Standard); requires a verdict, takes --source-type prose|code and --revision-seat; a revision failure leaves the verdict and rounds intact.
  • A live status.json/status.html view of a long run (10–15 minutes is normal), rewritten atomically on every transition: a view, not an artifact of record; --no-live-status drops it, and writing it is best-effort, never able to fail the run.

The rest of this section and the CLI Execution Notes below are the portable, script-free fallback: the same protocol an agent runs by hand where the conductor isn't available. The principles hold either way:

  • Run every seat as its own CLI subprocess, including the Claude seat as a separate claude process, so each reviews the source independently rather than reusing the orchestrator's context. That independence is what makes Round 1 worth anything.
  • Keep the orchestrator and the chair neutral: assemble packets and synthesize, but don't also count yourself as a debating seat. If you must, say so in the handoff and use a minority report to check chair bias (references/epistemics.md).
  • When the source is a repo or local files, decide once how seats reach it and record it in run-metadata.md: either every CLI reads the same shared path, or you build one source packet and hand identical bytes to each seat. Use one method for all seats so they review the same thing.
  • Seats are agentic: they may web-search and read their working directory, which usually helps (live grounding). When you need a clean outside view or isolation, control the working directory and network and hand each seat one neutral source packet. (Running seats from a non-git folder also requires Codex's --skip-git-repo-check.)

For a concrete, copy-pasteable capture pattern, use references/execution-harness.md: prompts written to files, stdout/stderr/exit-code/timeout capture, and ran / degraded / dropped classification folded into run-metadata.md.

CLI Execution Notes

The conductor's seat-adapter registry (scripts/_conductor/registry.py) is the canonical, self-healing source for these mechanics: exact flags, gate-mode isolation, stdin handling, and model-id self-heal, kept current and asserted by tests. When a flag drifts, fix it there, in one place. The templates below are the portable fallback for running a seat by hand without the conductor; they are illustrative and not guaranteed current.

Prefer read-only modes. Confirm every flag against the installed CLI (<cli> --help) before a large run, or just use the conductor, which does.

Claude seat:

claude -p "<seat prompt>" --model fable --effort max --permission-mode plan

-p runs non-interactively; --permission-mode plan keeps it read-only. --effort max requests the deepest reasoning the installed build exposes. On long analytic prompts, plan mode can make the seat return a plan-style summary (and even claim it wrote a file) instead of the full review, so append the {{CLAUDE_OUTPUT_OVERRIDE}} block from references/prompt-templates.md verbatim to the Claude seat's prompt, and treat a short or plan-shaped artifact as a degraded seat to re-run.

Codex seat:

codex exec --sandbox read-only --skip-git-repo-check \
  --config model_reasoning_effort="xhigh" \
  "<seat prompt>" </dev/null

codex exec is the non-interactive form; --sandbox read-only blocks edits. Close stdin with </dev/null: codex exec reads stdin until EOF, so without it the call hangs when orchestrated in the background or any non-interactive pipeline. Pass --skip-git-repo-check so the run doesn't abort with "Not inside a trusted directory" when a seat runs from a neutral, non-git source folder.

Gemini seat:

gemini -p "<seat prompt>" -m pro --approval-mode plan --skip-trust

--approval-mode plan restricts the seat to read-only tools (--skip-trust avoids the untrusted-directory exit that would otherwise force approval-mode back to default). Select the highest available thinking level: prefer a CLI flag or environment variable if the installed CLI exposes one; a settings-file edit is the last resort, with backup and restore-on-failure (references/execution-harness.md §Gemini thinking level). The Gemini CLI may print internal errors to stderr (e.g. model-router retries) yet still return a valid review: judge a seat by whether usable content came back, not by stderr noise or a non-zero exit; treat that as a degraded-but-ran seat, not a failure.

Grok seat:

grok -p "<seat prompt>" --model grok-4.5 --effort high \
  --output-format plain --permission-mode plan --sandbox read-only \
  --no-subagents --no-memory --disable-web-search \
  --disallowed-tools WebFetch

--sandbox read-only and plan mode block edits; the web flags remove search/fetch in gate mode. Override --model only to pin a different exact model ID.

Prompt Templates

Load references/prompt-templates.md when running a board. Use the templates as a starting point, then adapt them to the source material, output type, and project constraints.

Scripts

Optional helpers in scripts/ (Python 3 stdlib, no install): board_verdict.py validates verdict.json, gates CI on the verdict (--gate), and appends human tuning (amend); verify_evidence.py resolves a verdict's typed evidence and stamps each citation verified/unverified/refuted; render_verdict.py/render_handoff.py render the consensus Markdown and HTML deterministically; format_output.py derives the TL;DR / PR comment / Slack / JSON shares; board_changes.py, board_rubric.py, and board_scorecard.py validate their artifacts; render_plan.py renders a planning-document HTML view from its markdown. The skill runs fine without them; they're for wiring a board into CI and other tooling. Flags, exit codes, and composition rules: scripts/README.md.

When To Stop

Stop and ask or report if:

  • no source material is given and none is inferable from an obvious file or repo;
  • fewer than two seats can authenticate or run, a board needs at least two voices;
  • a step would need write access but the user asked for review only;
  • full cross-reading would blow the context budget: fall back to summaries and say so;
  • the material is too sensitive to send to external providers and no local-only board is available (references/data-handling.md).

If a provider is unavailable, or fails partway through, but at least two seats remain, continue as a smaller board and label the missing seat (and the round it dropped out) in the handoff rather than silently omitting it.

Files (skills)
  • agents
    • openai.yaml 236 B
      Loading…
  • references
    • board-composition.md 5.4 KB
      Loading…
    • changes-schema.md 13.4 KB
      Loading…
    • data-handling.md 7.4 KB
      Loading…
    • epistemics.md 7.2 KB
      Loading…
    • execution-harness.md 5.8 KB
      Loading…
    • handoff-template.html 38.4 KB · in bundle
    • implementation-sequence-template.html 20 KB · in bundle
    • intake-interview.md 5.8 KB
      Loading…
    • lens-presets.md 6.1 KB
      Loading…
    • modes.md 10.5 KB
      Loading…
    • output-formats.md 6.7 KB
      Loading…
    • plan-fonts.css 170.3 KB · in bundle
    • plan-template.html 21.4 KB · in bundle
    • preflight.md 7.3 KB
      Loading…
    • prompt-templates.md 17.9 KB
      Loading…
    • quick-verdict-template.html 15.9 KB · in bundle
    • run-metadata-template.md 2.3 KB
      Loading…
    • verdict-schema.md 21.6 KB
      Loading…
  • scripts
    • _conductor
      • artifacts.py 38 KB
        Loading…
      • ask.py 27.1 KB
        Loading…
      • cli.py 109.5 KB
        Loading…
      • config.py 51.6 KB
        Loading…
      • constants.py 21.7 KB
        Loading…
      • convergence.py 21.4 KB
        Loading…
      • delta.py 6.9 KB
        Loading…
      • digest.py 12.3 KB
        Loading…
      • doctor.py 12.3 KB
        Loading…
      • echo_score.py 14.9 KB
        Loading…
      • egress.py 23.1 KB
        Loading…
      • endorsement.py 29 KB
        Loading…
      • grounding.py 33.1 KB
        Loading…
      • history.py 8.8 KB
        Loading…
      • preflight.py 9.5 KB
        Loading…
      • prompts.py 43.6 KB
        Loading…
      • recipe.py 19.8 KB
        Loading…
      • redline.py 9.1 KB
        Loading…
      • registry.py 34.1 KB
        Loading…
      • revise.py 17.5 KB
        Loading…
      • revision.py 53.4 KB
        Loading…
      • rounds.py 25.6 KB
        Loading…
      • rubric.py 69.1 KB
        Loading…
      • scorecard.py 12.1 KB
        Loading…
      • spawn.py 11 KB
        Loading…
      • status.py 24.4 KB
        Loading…
      • synthesizer.py 37.3 KB
        Loading…
      • toolchain.py 10 KB
        Loading…
      • __init__.py 268 B
        Loading…
    • board_changes.py 19.7 KB
      Loading…
    • board_rubric.py 16.7 KB
      Loading…
    • board_scorecard.py 27.2 KB
      Loading…
    • board_verdict.py 41.6 KB
      Loading…
    • format_output.py 9.3 KB
      Loading…
    • README.md 42.3 KB
      Loading…
    • render_handoff.py 25.8 KB
      Loading…
    • render_plan.py 23.5 KB
      Loading…
    • render_tracker.py 12 KB
      Loading…
    • render_verdict.py 96.5 KB
      Loading…
    • run_board.py 7.7 KB
      Loading…
    • verify_evidence.py 45.4 KB
      Loading…
    • _embed_fonts.py 2.3 KB
      Loading…
    • _md.py 10.9 KB
      Loading…
    • _render_engine.py 6.5 KB
      Loading…
    • _severity_filter.py 4.2 KB
      Loading…
    • _verdict_labels.py 9.2 KB
      Loading…
  • CHANGELOG.md 133 KB
    Loading…
  • README.md 7.8 KB
    # Advisory Board
    
    **Get a room full of expert advisors for any big decision — before you commit.** Bring the board whatever you're weighing — a plan, a draft, a contract, a design, a real-life choice — and several leading AI models each examine it independently, then read each other's notes, argue out the disagreements, and hand you back one clear answer: what's solid, what's risky, and what to do next. You read it like a memo, not a config file. It works for software, but also for product, research, legal, business, and writing decisions.
    
    The default board uses frontier models from **Anthropic, OpenAI, Google, and xAI** — Claude, Codex, Gemini, and Grok — each sitting in a different seat. Provider-maintained aliases/defaults select the strongest current model at run time, while explicit model overrides remain pinned. Each seat reviews the same source on its own, then reads a packet of the others' findings and answers the strongest objections before a final synthesis turns the debate into one working handoff.
    
    Use it to:
    
    - weigh a big personal or business decision — a job offer, a price change, going full-time on a side project;
    - get a sharp first read on a draft, a pitch, a cover letter, or a hard email before you send it;
    - pressure-test a plan, design, or architecture before you build;
    - surface risks, stale assumptions, and missing evidence a single opinion would miss;
    - collapse several strong opinions into one clean, plain-English takeaway.
    
    Default behavior: two rounds of review and rebuttal; read-only unless edits are explicitly requested; you see exactly what would be sent to each provider and approve it before anything leaves your machine — redact what's sensitive, or run a fully local board where nothing is sent at all.
    
    **Run it your way.** Advisory Board is a provider-agnostic agent skill — convene the board through Claude Code, Codex, or whatever harness you prefer. Install it from the [repo root](../../../README.md), or read [`SKILL.md`](./SKILL.md) directly.
    
    > **Prefer a polished app instead?** [Panely](https://github.com/timharris707/panely) is a sibling product built around the same idea — a local-first advisory room. Advisory Board is the open agent skill; Panely is the app. Same maker.
    
    ## See It In Action
    
    Here's a real board debating a real decision — *"Should we relocate our family across the country for this job offer?"* The offer looks great on paper: a **+37.5% raise**. The board's job was to check whether the headline survives contact with the math.
    
    > **Verdict: Go ahead, with conditions — unanimous, high confidence.** (A three-seat board sat for this run.) The reveal all three advisors converged on: the raise is *consumed almost entirely by rent*, quietly collapsing monthly savings from **$2,750 to $537**; the $20k "covers the move" sign-on is gross and nets ~$11–13k against an ~$18k move; and the "take-home rises" headline **inverts** at a realistic tax rate. They didn't say "don't" — they said exactly what to resolve first, and handed back the next steps.
    
    **Read it two ways — start with the skim:**
    
    - **The 30-second brief:** [quick-verdict for the relocation decision](https://htmlpreview.github.io/?https://github.com/timharris707/skills/blob/main/examples/should-we-relocate-our-family-across-the-country-for-this-job-offer/quick-verdict.html) — the verdict, the must-resolve blockers as one-liners, the top next steps. The teaser you'd forward.
    - **The full handoff:** [the complete record](https://htmlpreview.github.io/?https://github.com/timharris707/skills/blob/main/examples/should-we-relocate-our-family-across-the-country-for-this-job-offer/final-consensus.html) — the round-by-round debate, every consensus blocker, and preserved cross-model dissent (Gemini: *"you're shorting your marital operating system"*).
    - **See the input, too:** [the decision brief](https://github.com/timharris707/skills/tree/main/examples/should-we-relocate-our-family-across-the-country-for-this-job-offer/decision.md) the board reviewed — good input in, good output out.
    
    Every run ends in a single, self-contained HTML handoff that opens offline in any browser with no dependencies.
    
    **Also built for engineers:** point the board at a real codebase and advisors cite exact `path:line` evidence. Every run also emits a machine-readable [`verdict.json`](https://github.com/timharris707/skills/tree/main/examples/payments-idempotency-review/verdict.json); [`scripts/board_verdict.py`](./scripts/board_verdict.py) `--gate` turns the board's `ship | caution | block` call into a CI exit code, and [`scripts/format_output.py`](./scripts/format_output.py) reshapes it into a PR comment, Slack message, or TL;DR. See the technical [payments idempotency review](https://htmlpreview.github.io/?https://github.com/timharris707/skills/blob/main/examples/payments-idempotency-review/final-consensus.html) for a code-grounded run.
    
    **More runs to browse:** the [side-project go-full-time decision](https://github.com/timharris707/skills/tree/main/examples/side-project-go-full-time-review/), the [API rate-limiter readiness review](https://github.com/timharris707/skills/tree/main/examples/ratelimiter-readiness-review/), and the board [dogfooding the design of its own next feature](https://htmlpreview.github.io/?https://github.com/timharris707/skills/blob/main/examples/dogfood-fixit-design-roundtable/final-consensus.html) — a 3-seat design roundtable with preserved cross-model dissent.
    
    **The board reviewing its own PRs:** during the v1.13→v1.15 release train, every substantial PR got a 2-seat board review (Claude Opus + Codex gpt-5.5) on a frozen review packet, then a `--revise` re-review of the fixes — each pair linked by directory suffix (the revise run appends the next numeric suffix to the original run's directory name). Browse the committed rulings: the [endorsement-pass review](https://github.com/timharris707/skills/tree/main/examples/v1-13-p4-endorsement-pass-pr-review-2026-07-02/) (`block` → `caution` across the revise pass), the [echo-score review](https://github.com/timharris707/skills/tree/main/examples/v1-14-p2-echo-score-pr-review-2026-07-02/) (the board ruled `block` where a solo review agent had said ship — divergence with recorded dissent), the [live-progress review](https://github.com/timharris707/skills/tree/main/examples/v1-14-p3-live-progress-pr-review-2026-07-02/) (`caution` → a clean `ship`), and the [rubric-round review](https://github.com/timharris707/skills/tree/main/examples/v1-15-p2-rubric-round-pr-review-2026-07-02-2/) (a split `block` with preserved cross-seat dissent; [the revise pass](https://github.com/timharris707/skills/tree/main/examples/v1-15-p2-rubric-round-pr-review-2026-07-02-3/) confirmed both blockers fixed and surfaced a new one). There's also a second design roundtable: the [rubric-first deliberation brief](https://github.com/timharris707/skills/tree/main/examples/v1-15-rubric-first-design-brief-2026-07-02/) — 3 seats, unanimous `caution`, three preserved dissents.
    
    The look comes from one template, [`handoff-template.html`](./references/handoff-template.html), so any agent that installs the skill renders the same clean output.
    
    ## Going Deeper
    
    - **[The GitHub Pages guide](https://timharris707.github.io/skills/advisory-board)** — the friendly walkthrough: who it's for, how a run works, what you walk away with, and the engineer-grade features (repo grounding, lens presets, CI gating).
    - **[`SKILL.md`](./SKILL.md)** — the skill itself: the full workflow contract any agent runs.
    - **[`references/`](./references/)** — prompt templates, lens presets, preflight, board composition, data handling, epistemics, verdict schema, output formats, and the handoff/quick-verdict HTML templates.
    - **[`scripts/`](./scripts/)** — `board_verdict.py` (CI gate) and `format_output.py` (PR comment / Slack / TL;DR reshaping).
    - **[`CHANGELOG.md`](./CHANGELOG.md)** — versioned history; releases tag as `advisory-board/vX.Y.Z`.
    
  • SKILL.md 31.9 KB
    ---
    name: advisory-board
    description: "For an explicitly requested advisory board, roundtable, panel, idea tournament, multi-model review or debate, red-team by several models, or consensus handoff, run an authorized multi-provider process with recorded seats, usage, and evidence."
    ---
    
    # Advisory Board
    
    Read the [Codex desktop binding](../../../CODEX.md) when this workflow needs harness mechanics, model routing, or recovery.
    
    Bring an idea, problem, plan, or architecture to a board of frontier models sitting in different roles. The board runs in one of three **modes**, the interaction topology chosen with the user at intake (`references/modes.md`). **Formal Board Review** is the default and the protocol this document defines: an independent first round, then rebuttal, then a structured verdict. **Roundtable** is collaborative, on a shared transcript, with an optional moderator. **Competitive** runs pitch, then critique, then a blind vote. Whatever the mode, you leave with the strongest conclusion the board can reach together and a clean takeaway, not disconnected opinions.
    
    ## Must Not
    
    Hard rules, collected here so they are never missed (each is elaborated in context below). Violating one invalidates the run.
    
    - **Never write files or make edits** unless the user explicitly asked for edits: the board is read-only by default.
    - **Never write artifacts into a tracked git tree** without naming the location first; default to the persistent runs root (`~/.advisory-board/runs/<slug>-<date>/`), or a throwaway `/tmp/advisory-board-*` folder with `--ephemeral`.
    - **Never substitute a model silently**: if a requested model is unavailable, use the nearest same-provider frontier model and say so.
    - **Never skip the data-handling disclosure** for non-public material, not even when the user says "use defaults." Disclose what leaves the machine and to whom, and get a go-ahead, before any external seat runs (`references/data-handling.md`).
    - **Never present a degraded or dropped seat as a full board**: label it on the seat card and in `verdict.json` (`dropped: true`) on a Formal Board Review run; Roundtable and Competitive, which emit no `verdict.json`, record it in `run-metadata.md` and name it in `synthesis.md`/`results.md` (`references/modes.md`). A board needs at least two seats that actually ran.
    - **Never print or store secrets** in prompts, packets, artifacts, logs, or metadata: no keys, tokens, cookies, or private environment values.
    - **Never launch a run the user hasn't confirmed.** The guided intake (`references/intake-interview.md`) is mandatory: mode, seats, lenses, effort, rounds, and output are the user's choices, made on the record. An already explicit approval of a complete plan satisfies its confirmation; reuse it. "Use defaults" still needs a concrete plan when seats, cost, or data scope have not yet been established.
    
    ## Core Defaults
    
    - Use subscription CLIs by default, not provider API keys.
    - Run read-only unless the user explicitly asks for edits.
    - Rounds: 2. Cross-reading: summaries. Final artifact: full handoff (Markdown plus a self-contained HTML view).
    - Write run artifacts to the **persistent runs root**, `~/.advisory-board/runs/<slug>-<date>/` (a same-day rerun gets a `-2` suffix, never an overwrite), so runs stop evaporating and `run_board.py history` can list them. `--runs-root`/`--out` redirect; `--ephemeral` opts back into a throwaway `/tmp/advisory-board-*` folder. Every real run announces where its artifacts land on its first output line. Persistence changes only the disk location: artifacts inherit the run's sensitivity handling (`references/data-handling.md`).
    - Writing artifacts into the reviewed project is itself a write, even on a read-only review: do that only when the user asks or agrees, prefer a dedicated `advisory-board/<timestamp>/` (or `docs/advisory-board/<timestamp>/`) folder, and never write into a tracked git tree without naming the location first.
    - One flag sets the whole cost/depth posture: **`--tier quick|standard|deep`**: rounds, cross-reading, and per-seat reasoning together (`standard` is today's defaults, a deliberate no-op; exact per-tier values live in the registry and `scripts/README.md`). The tier is a **base**: explicit flags (`--rounds`, `--cross-reading`, per-seat `--effort`) always override it, and `run-recipe.yaml` records the resolved selectors and effort values. Provider-maintained aliases deliberately re-resolve on a later run; `--model seat=id` is the exact-pin escape hatch. Four frontier models at high reasoning across several rounds can take minutes and meaningful tokens: flag a large run before launching it; `run_board.py run … --dry-run` prints a best-effort estimate.
    
    ## Modes
    
    The three topologies, their mechanics, hand-runnable protocols for the two the conductor doesn't drive yet, and the intent→mode recommendation table live in `references/modes.md`. In brief: **Formal Board Review** is this document's Round Protocol and everything the conductor, verdict chain, and gate support, the default. **Roundtable** and **Competitive** run by hand via the portable fallback, produce their own artifact sets, and never feed `verdict.json` or a gate. The mode is settled at intake, with the user.
    
    ## Guided Intake (mandatory)
    
    Every run opens with the wizard in `references/intake-interview.md`, presented as selection cards like the `grilling` skill's rounds, recommendation first. The sequence, in order:
    
    1. **Preflight first, within authorization.** Read the registered CLI capabilities before offering seats. Doctor includes model smoke calls, so announce their count and rough usage and obtain any required provider authorization before running it. A Claude smoke call counts as Anthropic work. Check only authorized providers when the installed command supports selection; otherwise use individual version/auth checks and authorized smoke calls. Report each candidate as unverified, GO, or NO-GO using the preflight definitions. An unapproved, untested seat stays unverified, not launch-ready; do not contact it.
    2. **Goal → mode.** Hear the goal in the user's words, recommend a mode (and lens preset) from `references/modes.md` §Choosing a mode, and let the user pick from all three.
    3. **Seats.** Any 2–10 of the GO providers ("latest frontier of each" is the shortcut); show the seat→provider→lens table before launch; warn on cost for big or deep boards.
    4. **Reasoning depth.** Highest available (default) / Standard / Quick via `--tier`; per-seat overrides on request.
    5. **Rounds and output.** With defaults marked.
    6. **Confirm-summary.** The resolved plan as one card; nothing launches without this yes.
    
    "Use defaults" resolves steps 2-5 to defaults and goes to step 6, but only after step 1 completes and its findings are applied to the card: the required checks run for the authorized selection (a full doctor sweep is optional), a seat that is not GO is never a default, and below two GO seats there is no defaults board (step 3's fallbacks are settled with the user first). An existing explicit confirmation of the same resolved plan remains valid, and it never waives data-handling consent: if the material isn't clearly public, still disclose which providers will receive it and get an explicit go-ahead before launching any external seat (`references/data-handling.md`).
    
    ## Model Lineup
    
    Target the strongest reasoning model each provider offers **at run time**. Defaults use provider-maintained selectors so new frontier releases do not require a skill edit; explicit `--model seat=id` overrides pin exact IDs.
    
    - Claude seat: Anthropic's maintained `fable` alias at `--effort max`. Where `fable` doesn't resolve (older CLI or account), preflight proposes the `opus` fallback and never applies it silently.
    - Codex seat: `--model codex=gpt-6-astra` pins the documented Astra identifier when requested, with approved effort. Verify the installed CLI flags, actual account/configuration route, and model resolution during authorized preflight. Confirm the model that answered from CLI evidence; if it cannot be established, keep the seat unverified. A rejected pin is NO-GO; propose a supported alternative for approval rather than silently substituting. An unpinned `auto` seat follows CLI configuration and proves no particular model. See the [capability evidence](../../../CODEX.md#capability-evidence-and-portability).
    - Gemini seat: Google's maintained `pro` alias (latest highest-reasoning Pro model) with the CLI's highest available thinking level.
    - Grok seat: `grok-4.5` through the official `grok` CLI at `--effort high`, the only model the CLI currently lists.
    
    The selector (`fable`, `pro`, `grok-4.5`, or Codex `auto`) and the model that actually answered are separate provenance fields. If a CLI cannot report the resolved ID, record `unknown` rather than pretending. Use an exact `--model` override for an eval or replay that must not float.
    
    **Preflight.** Run `references/preflight.md` before launching: for each seat, check the CLI is present, auth is active (subscription-backed where possible), the requested model resolves, and a one-token smoke ping returns. For a first run or new machine, scoped checks can establish GO; a full doctor is optional. After authorizing all of its smoke calls, `run_board.py doctor` sweeps **every** registered provider with per-provider fix-it steps and a viable-board summary: probes and smoke-pings only, it never reads or sends your material; `run_board.py toolchain` checks CLI currency and (consent-gated) updates or installs. Proceed only with at least two seats GO; fewer isn't a dead end: preflight distinguishes *not installed* from *installed-but-unauthed* and names the fallbacks: a same-provider multi-lens board or a local/human seat (`references/board-composition.md`). Label any degraded or dropped seat in the handoff.
    
    ## Seats
    
    Give each seat its own angle so the board covers more ground than any single reviewer, and match the lenses to the subject. Pick a ready-made lens set from `references/lens-presets.md`, or compose your own: `software-architecture` (default), `product-strategy`, `research-paper`, `legal-contract`, `business-decision`, `writing-editing`, `red-team` (every seat hostile; the stress-test preset), `stakeholder-panel` (convene "the room this decision would face"). The same lens on two different providers is a valid cross-model pairing; only same-provider-same-lens wastes a seat. For software and technical work, the default split:
    
    - Claude: architecture, systems, and adversarial design review.
    - Codex: repo-grounded implementation, migration, testing, and execution.
    - Gemini: product, operations, rollout, latency, evaluation, and user-workflow risk.
    - Grok: contrarian synthesis, hidden assumptions, alternatives, and decision-changing evidence.
    
    For non-software subjects (strategy, research, writing, business, policy), assign comparable lenses: e.g. one seat on first-principles soundness, one on execution and feasibility, one on second-order consequences and stakeholder or user risk.
    
    Every seat still answers the full brief; the lens reduces blind spots, it doesn't narrow responsibility.
    
    The board defaults to four seats but isn't fixed at four. For sizing (2–10), the same provider in multiple seats (each duplicate taking its own lens), a human or local-model seat, an **Antigravity** seat, and minimal "works with what you have" lineups, see `references/board-composition.md`.
    
    ## Data Handling
    
    A board sends the same source material to every seat's provider. Before the first call, if the material isn't already public, tell the user what will leave the machine and to whom, and get a go-ahead. For sensitive material, redact the shared source packet; for must-not-leave material, run a local-only board or don't run it. Full guidance: `references/data-handling.md`.
    
    ### Repo-grounding & verification
    
    By default a board reviews the **text you hand it** and is blind to the codebase that text is about, so findings come back conditional on the cited factual base, none confirmed by a seat that read the code. `--repo PATH` closes that gap: it augments `--source` (the source file still frames the question; the repo is the evidence base) by handing every seat a **read-only snapshot** of the repository, one that is `.gitignore`-respecting, `.git`-excluded, secret-denylisted, and symlink-confined, so seats verify claims against real code and cite real `path:line`. Consent binds to the snapshot's **scope hash** alongside the source-packet hash, and `repo-scope-manifest.json` records exactly what was in scope at approval.
    
    Grounding then makes the verdict chain trustworthy on **code**, not just prose: `verify --source <repo> --run <out>` resolves those citations against the tree and stamps each `verified`/`unverified`/`refuted`: a fabricated citation stamps `refuted` and `validate --gate` abstains.
    
    In **gate mode** (`--repo` on a gate-bearing run), the safety policy is **read XOR network**: every seat must be network-isolatable, because a grounded seat that is also networked can read a secret and exfiltrate it. Seats that can't be de-networked (today **gemini**, **antigravity**) make a gate+`--repo` run **refuse**, the offending seat named as a labeled NO-GO, never silently dropped, and a gate-bearing run never silently falls back to advisory. **Advisory + `--repo`** is the home for casual self-review of your own repo (network on, you own the risk) with a loud disclosure.
    
    Be honest about the limits when reporting: a `verified` stamp means the receipt resolves, not that the inference drawn from it is sound, and it is a statement about the snapshot at approval time. The poisoned-repo and snapshot-drift caveats, and why the snapshot bounds consent rather than physical reads, are in `references/data-handling.md` §Repo-grounded review.
    
    ## Round Protocol
    
    This section defines **Formal Board Review**, the default mode and the only one the conductor drives end-to-end. Roundtable and Competitive replace it with their own phase structures (`references/modes.md`).
    
    **Rubric-first scoring (`--rubric`, optional).** Before round 1 the board can agree its own weighted criteria and then score every round against them, so the verdict is backed by a comparable number as well as prose. Two mechanically-checked passes run first: a **proposal fan-out** (every seat proposes 3–7 weighted criteria from the same source packet round 1 sees; the conductor mints the proposal ids: a model never mints identity) and a **chair merge** (one board seat merges every usable proposal into one weighted rubric with an explicit partition; the conductor mechanically reconciles the partition and the weights-sum-to-100 invariant, retries once, then refuses). Too few proposals or an unreconcilable merge **refuses the run before any opinion round spends a token**, writing `rubric-rejected.json`; this is the one place in the whole skill that refuses outright rather than degrading. Success writes `rubric.json` post-consent, pre-rounds, so it survives a later scoring failure. The agreed rubric is injected into **every** opinion round: each seat emits one `SCORE cN: <1-5>` line per criterion (a bad or missing line degrades that cell to absent, never imputed, and never making the seat unusable) plus an optional `RUBRIC-NOTE:` objection (recorded, never debated: scoring under the rubric *is* accepting it). `--rounds auto` convergence widens to include score movement. On a `--revise --rubric` run the prior rubric is carried forward mechanically, so scores stay comparable across revisions. **Scores are informational only: the gate never reads them.** Injected block and token grammar: `references/prompt-templates.md`; artifacts and chair-seat resolution: `references/verdict-schema.md`, `scripts/README.md`.
    
    **Round 1: independent.**
    
    - Give each seat the same source packet and its role lens, nothing else.
    - No other seat's opinions.
    - Require: verdict (with a confidence level: low/medium/high), strongest objections, revised sequence, invariants, risks, and concrete evidence.
    
    **Round 2: rebuttal (default).**
    
    - Build a board packet from Round 1: a structured digest (`summaries`, the default) that puts every seat's take on each topic side by side under a verdict/citation agreement header, where the board agrees and where it splits, or the full prior responses when the token budget allows (`full`). `run_board.py` builds this deterministically from each review's own section structure plus the `VERDICT:` tokens; it never clusters claims by meaning. `--digest-format json` also writes each round's digest as typed JSON.
    - Ask each seat: what another seat caught that you missed, what changed your view (and whether the change is driven by evidence or mere deference; see `references/epistemics.md`), what you still dispute, what should become consensus, and what stays unresolved.
    
    **Round 3: convergence (optional).**
    
    - Give each seat the Round 2 packet.
    - Ask for the final position, hard dissent, and the smallest viable plan.
    
    **Adaptive rounds (`auto`).**
    
    - Stop early when the board has converged rather than spending a round to rubber-stamp: a shared verdict, high confidence, and no material dissent after a round.
    - Add a round when material dissent or low confidence remains and another exchange could plausibly resolve it, up to the `--max-rounds` ceiling (default 3).
    - `run_board.py --rounds auto` makes this concrete: each seat ends its review with a `VERDICT: ship|caution|block` line, and the conductor measures **movement** between rounds as a pure function over that token plus the seat's concrete citations, never the prose (the model reasons; the conductor diffs tokens). It keeps going while the board is still moving and stops the moment it goes quiet; the per-round movement and the stop reason are recorded in `run-metadata.md` (`## Convergence`).
    - **Independence / echo score:** convergence can be *earned* (the seats independently reached the same answer) or *social* (they read each other and drifted into agreement). Round 2+ seats self-report a `BASIS: independent|evidence|deference` line, and the conductor scores echo risk over the final round's parsed signals as a coarse **low / moderate / high** band with a one-line explanation, recorded in `run-metadata.md`. It **flags** possible echo; it does not prove independence (`references/epistemics.md`).
    
    **Final synthesis.**
    
    - After the last round, write the handoff: consensus, dissent (and why it matters), revised plan, risks, invariants, evidence, and next actions.
    - **Write the handoff for a human who was not in the room.** Lead with the bottom line, `summary` in `verdict.json`: 3–6 plain sentences saying what was reviewed, what the board decided, why, and what happens next. Every prose field must read as plain English on the first pass: short sentences, no coined compound labels, no unexplained jargon; a finding's title is a complete sentence naming what can go wrong, and mechanism detail lives in the evidence citations, not the prose. This contract binds a hand-authored verdict (the degraded-synthesizer path) exactly as it binds the synthesizer seat.
    - Prefer a neutral synthesizer, a seat that didn't debate or a blind merge, so the chair doesn't grade its own work (`references/epistemics.md`). If the board is unanimous, include a minority report: the strongest case against the verdict.
    - Label model and round provenance (the model that actually answered, not just the one requested), and split the findings into three explicit buckets: **evidence-backed** (tied to a file, fact, run, or citation), **judgment calls** (reasoned but unproven here), and **couldn't-verify** (claims the board leaned on but didn't check, plus the shared blind spots no seat could see). For each load-bearing conclusion, note what would change it. The couldn't-verify bucket is the main guard against a confident, unanimous, *wrong* call: three models can converge on the same missing fact (`references/epistemics.md`).
    - Emit `verdict.json` alongside the prose (`references/verdict-schema.md`) so the result can drive a gate or other tooling.
    
    ## Artifact Standard
    
    Write:
    
    - `round-1/<seat>.md` (and `round-2/`, `round-3/` as rounds run)
    - `board-packet-round-2.md` (and `board-packet-round-3.md` when needed)
    - `final-consensus.md`: the handoff in Markdown
    - `final-consensus.html`: a self-contained, human-readable view of the handoff. Render it deterministically with `scripts/render_handoff.py` from a `handoff-data.json` (recommended: guarantees no leftover placeholders or template drift), or fill `references/handoff-template.html` by hand. `render_verdict.py --shape` chooses the view (full handoff, quick verdict, or implementation sequence) and `--filter` trims by severity; a dropped section is stated with counts, never silently elided; see `references/output-formats.md`.
    - `verdict.json`: the machine-readable verdict (`references/verdict-schema.md`); gate or reformat it with `scripts/`
    - `changes.json` + `revised-draft.*`: **only with `run --output revised-draft`**. A board-derived revised copy of the source, each edit mapped to the board finding it resolves and mechanically validated, then voted on per edit by the non-revision seats in the **endorsement pass** (`ENDORSE`/`OBJECT`/`ABSTAIN`; objections are recorded for a human to read, never resolved by another model loop; `--no-endorse` opts out, leaving a *findings-mapped*, not board-endorsed, run). The draft is **byte-clean** (the revised source bytes and nothing else) and the source file is **never written**: applying the revision is your act. Conflicting findings surface as `unresolved` entries, never silently reconciled. A **code** source also gets a git-apply-able `revised-draft.patch`; a **prose** source instead gets a word-level redline section in the full-handoff HTML; both are pure views, sha-verified against `changes.json` before a byte is diffed. Schema and validation: `references/changes-schema.md`.
    - **Grounded citation snippets.** When a grounded run resolves a `code` citation, the cited lines are captured onto the evidence entry so the handoff embeds the receipt itself, self-contained even though the repo snapshot is cleaned up after the run (`references/verdict-schema.md`).
    - `rubric.json` + `scorecard.json`: **only with `--rubric`**. The pre-round merged rubric (criteria, weights, chair partition, proposal provenance) and the post-rounds score trajectory with conductor-computed per-seat totals and coarse bands. Both strictly validated; a validation failure warns and writes nothing: the rounds and verdict still stand. Scores never move the verdict or the gate; a severe token↔band contradiction is recorded and surfaced loudly in the verdict summary. Schemas: `references/verdict-schema.md`, `scripts/README.md`.
    - `run-metadata.md`: the provenance record. Commands, the model that actually answered per seat, auth mode (no secrets), per-seat status (ran / degraded / dropped), timings, and source paths. Use `references/run-metadata-template.md`. When a seat CLI reports its own token usage, record per-seat tokens and a best-effort cost/time line; nothing is ever guessed.
    
    When a seat is degraded or dropped, show it on its HTML seat card (status pill) and in `verdict.json` (`dropped: true`); never let a smaller board look like a full one. Derive lighter shares (TL;DR, PR comment, Slack, print/PDF) per `references/output-formats.md`.
    
    **Output contract for the HTML.** It is a *view* of `final-consensus.md`, not a second source of truth: the two must not disagree. The rendered file must contain no leftover `{{tokens}}` and no template scaffolding comments, and must stay self-contained (inline CSS only; no external fonts, CDNs, scripts, or remote `<link>`/`<script src>`) so it opens offline on a double-click. Follow the template's two-placeholder convention: replace each single `{{TOKEN}}` in place, and duplicate each `BEGIN`/`END` block once per item (delete the sample block if there are none).
    
    ## How A Run Executes
    
    **The conductor, `scripts/run_board.py`, is the canonical way to drive a board.** It owns the load-bearing mechanics in code: the seat-adapter **registry** (the one place that knows each CLI's flags, isolation, and model-id self-heal), the executable **preflight** (GO/NO-GO), the hash-bound **egress/quarantine gate** before any byte leaves, the **round fan-outs** with the failure protocol, the **verdict chain** (`verify` evidence → `consensus` md/html → `validate`/gate), and the **run history**. Synthesis stays your reasoning task: the conductor stops at clean per-round packets and hands them to you (or one neutral seat) to fill `verdict.json`, then you call the chain. Run `scripts/run_board.py run …`; a real run is in the repo-root `examples/payments-idempotency-review/`.
    
    Beyond `run`, know these run controls exist; exact flags, semantics, and edge rules are in `scripts/README.md` and `--help`:
    
    - Per-seat `--timeout` and `--effort` overrides (seat ids as in `--model`; an ambiguous provider name on a duplicate-provider board is refused, never silently collapsed).
    - `--revise <prior run dir>`: re-review a revised draft. Round-1 prompts carry a mechanical digest of the prior verdict plus the diff from the previously reviewed draft (sha-verified; omitted loudly when unrecoverable), every injected byte inside the consent packet hash; the new verdict records lineage and the consensus leads with cleared / still-open / new.
    - `ask "<question>" --run <dir>`: one-round post-verdict cross-examination, from a context packet built only from that run's own artifacts, bounded to the run and re-consented like any egress (the sensitivity floor only ever tightens); writes `addendum-N.md`.
    - `board_verdict.py amend`: append-only human tuning of a completed verdict (a confidence change, caveat, or severity note, each with provenance) that never rewrites the board's own words.
    - `run --output revised-draft`: the board-endorsed revision (see Artifact Standard); requires a verdict, takes `--source-type prose|code` and `--revision-seat`; a revision failure leaves the verdict and rounds intact.
    - A live `status.json`/`status.html` view of a long run (10–15 minutes is normal), rewritten atomically on every transition: a **view, not an artifact of record**; `--no-live-status` drops it, and writing it is best-effort, never able to fail the run.
    
    The rest of this section and the **CLI Execution Notes** below are the **portable, script-free fallback**: the same protocol an agent runs by hand where the conductor isn't available. The principles hold either way:
    
    - Run every seat as its own CLI subprocess, including the Claude seat as a separate `claude` process, so each reviews the source independently rather than reusing the orchestrator's context. That independence is what makes Round 1 worth anything.
    - Keep the orchestrator and the chair neutral: assemble packets and synthesize, but don't also count yourself as a debating seat. If you must, say so in the handoff and use a minority report to check chair bias (`references/epistemics.md`).
    - When the source is a repo or local files, decide once how seats reach it and record it in `run-metadata.md`: either every CLI reads the same shared path, or you build one source packet and hand identical bytes to each seat. Use one method for all seats so they review the same thing.
    - Seats are agentic: they may web-search and read their working directory, which usually *helps* (live grounding). When you need a clean outside view or isolation, control the working directory and network and hand each seat one neutral source packet. (Running seats from a non-git folder also requires Codex's `--skip-git-repo-check`.)
    
    For a concrete, copy-pasteable capture pattern, use `references/execution-harness.md`: prompts written to files, stdout/stderr/exit-code/timeout capture, and `ran` / `degraded` / `dropped` classification folded into `run-metadata.md`.
    
    ## CLI Execution Notes
    
    > The conductor's seat-adapter **registry** (`scripts/_conductor/registry.py`) is the **canonical, self-healing** source for these mechanics: exact flags, gate-mode isolation, stdin handling, and model-id self-heal, kept current and asserted by tests. When a flag drifts, fix it there, in one place. The templates below are the **portable fallback** for running a seat by hand without the conductor; they are illustrative and not guaranteed current.
    
    Prefer read-only modes. Confirm every flag against the installed CLI (`<cli> --help`) before a large run, or just use the conductor, which does.
    
    Claude seat:
    
    ```
    claude -p "<seat prompt>" --model fable --effort max --permission-mode plan
    ```
    
    `-p` runs non-interactively; `--permission-mode plan` keeps it read-only. `--effort max` requests the deepest reasoning the installed build exposes. On long analytic prompts, plan mode can make the seat return a plan-style *summary* (and even claim it wrote a file) instead of the full review, so append the `{{CLAUDE_OUTPUT_OVERRIDE}}` block from `references/prompt-templates.md` verbatim to the Claude seat's prompt, and treat a short or plan-shaped artifact as a degraded seat to re-run.
    
    Codex seat:
    
    ```
    codex exec --sandbox read-only --skip-git-repo-check \
      --config model_reasoning_effort="xhigh" \
      "<seat prompt>" </dev/null
    ```
    
    `codex exec` is the non-interactive form; `--sandbox read-only` blocks edits. Close stdin with `</dev/null`: `codex exec` reads stdin until EOF, so without it the call hangs when orchestrated in the background or any non-interactive pipeline. Pass `--skip-git-repo-check` so the run doesn't abort with "Not inside a trusted directory" when a seat runs from a neutral, non-git source folder.
    
    Gemini seat:
    
    ```
    gemini -p "<seat prompt>" -m pro --approval-mode plan --skip-trust
    ```
    
    `--approval-mode plan` restricts the seat to read-only tools (`--skip-trust` avoids the untrusted-directory exit that would otherwise force approval-mode back to default). Select the highest available thinking level: prefer a CLI flag or environment variable if the installed CLI exposes one; a settings-file edit is the last resort, with backup and restore-on-failure (`references/execution-harness.md` §Gemini thinking level). The Gemini CLI may print internal errors to stderr (e.g. model-router retries) yet still return a valid review: judge a seat by whether usable content came back, not by stderr noise or a non-zero exit; treat that as a degraded-but-ran seat, not a failure.
    
    Grok seat:
    
    ```
    grok -p "<seat prompt>" --model grok-4.5 --effort high \
      --output-format plain --permission-mode plan --sandbox read-only \
      --no-subagents --no-memory --disable-web-search \
      --disallowed-tools WebFetch
    ```
    
    `--sandbox read-only` and plan mode block edits; the web flags remove search/fetch in gate mode. Override `--model` only to pin a different exact model ID.
    
    ## Prompt Templates
    
    Load `references/prompt-templates.md` when running a board. Use the templates as a starting point, then adapt them to the source material, output type, and project constraints.
    
    ## Scripts
    
    Optional helpers in `scripts/` (Python 3 stdlib, no install): `board_verdict.py` validates `verdict.json`, gates CI on the verdict (`--gate`), and appends human tuning (`amend`); `verify_evidence.py` resolves a verdict's typed evidence and stamps each citation `verified`/`unverified`/`refuted`; `render_verdict.py`/`render_handoff.py` render the consensus Markdown and HTML deterministically; `format_output.py` derives the TL;DR / PR comment / Slack / JSON shares; `board_changes.py`, `board_rubric.py`, and `board_scorecard.py` validate their artifacts; `render_plan.py` renders a planning-document HTML view from its markdown. The skill runs fine without them; they're for wiring a board into CI and other tooling. Flags, exit codes, and composition rules: `scripts/README.md`.
    
    ## When To Stop
    
    Stop and ask or report if:
    
    - no source material is given and none is inferable from an obvious file or repo;
    - fewer than two seats can authenticate or run, a board needs at least two voices;
    - a step would need write access but the user asked for review only;
    - full cross-reading would blow the context budget: fall back to summaries and say so;
    - the material is too sensitive to send to external providers and no local-only board is available (`references/data-handling.md`).
    
    If a provider is unavailable, or fails partway through, but at least two seats remain, continue as a smaller board and label the missing seat (and the round it dropped out) in the handoff rather than silently omitting it.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.