claude-advisor-panel

name	claude-advisor-panel
description	Run a customizable cross-vendor advisor board (formerly advisor-panel; that name remains a working alias) through the agent-harness runtime primitive when a high-stakes change needs independent review evidence.

Advisor Board

Use this skill when a plan, implementation diff, release closeout, or other high-stakes artifact needs an independent cross-vendor review board. This skill was formerly named advisor-panel; that name still resolves as an alias, so existing instructions that say "advisor-panel" keep working.

Source Of Truth

The advisor-board (formerly advisor-panel) implementation is owned by agent-harness:

• Runtime primitive: phase_loop_runtime.panel_invoker
• Board model: phase_loop_runtime.advisor_board (seats, boards, resolver, validation)
• Entry points (runnable default): advisor_board.composition.compose_review_board + panel_invoker.invoke_board, exposed as the phase-loop advisor-board <artifact> CLI. The legacy available_panel_legs/invoke_panel/invoke_panel_request stay in place for the governed review/pre-merge gates (unchanged, byte-identical golden).
• Governed workflow integration: phase-loop governed review/pre-merge paths

Do not call dotfiles advisor-panel scripts, copy provider-specific shell scripts, or introduce a separate implementation in the skill body. The skill is a thin operator guide over the runtime primitive.

Boards & Availability-Aware Composition

Named boards live in phase_loop_runtime.advisor_board.presets; the default review board is code-review, a 4-vendor cross-vendor panel — one seat per frontier vendor (grok, claude, codex, gemini), each at its MAXIMUM thinking with a DISTINCT review lens (adversarial / correctness / red-team / alternative-approach).

Composition is AVAILABILITY-AWARE (composition.compose_review_board): it targets 4 independent reviewers (hard floor 3) and NEVER collapses to 1–2 when vendors are down. Each vendor that is both present on PATH AND authenticated gets one lens-distinct seat first; the remaining seats are BACKFILLED onto the available (up + authed) vendors with DIFFERENT lenses. So 2 vendors up still yields a full 4-seat board, and 1 vendor up yields 4 distinct-lens seats on that vendor. The bare advisor-board (default/premerge) board is unchanged — the byte-frozen 3-leg panel.

Three Ways To Feed Material

There are THREE DISTINCT ways to give the panel material. The #114 fix names them accurately: artifact_ref and brief_ref are Read-file-and-stage conveniences, while context_refs is the true by-reference mode.

• Inline (artifact="...") — small material passed as a string, written verbatim into review-bundle.md. A large inline artifact logs a steering warning.
• Read-file-and-stage (artifact_ref="path/to/bundle.md", or a list) — the runtime READS the local file(s) off disk and stages their bytes into review-bundle.md (a single path verbatim; multiple paths under per-file headers). This keeps YOUR context lean, but the file CONTENTS still land in the staged bundle every leg reads. Use it when you WANT the legs to read the material verbatim. artifact_ref wins over artifact if both are given.
• brief_ref="path/to/brief.md" — a Read-file-and-stage path for a large review brief; staged as review-instructions.md. Omit it to use the built-in review/advisory brief.
• TRUE by-reference (context_refs=["path/to/large.pdf", ...], #114) — the runtime stages ONLY a path + metadata manifest (path, size, sha256, MIME/extension, and PDF page count when cheap) plus an instruction telling each leg to OPEN the files with its own local tools. Raw file contents are not read into the bundle or prompt by this runtime path. Use it for LARGE or PRIVATE local material when the selected provider/backing can access the same local file path. A missing/unreadable path fails CLOSED naming the path, unless you pass context_refs_soft_warn=True (logs a warning and emits an UNREADABLE manifest entry). Pathnames and hashes can disclose sensitive metadata, and a leg may disclose file contents after it intentionally inspects a referenced file unless an output policy forbids disclosure.

Bounding A Slow Leg

Legs fan out concurrently, so panel wall-clock ≈ max(leg), not sum. Each leg's default timeout is INPUT-SCALED (~600s floor + ~12s/KB, capped at 1800s): a ~150-line artifact is roughly ~11 min/leg, and a genuinely max-effort frontier review of a large bundle can approach the cap. Pass timeouts_by_leg={"gemini": 300} (or PanelRequest.timeout_seconds_by_leg) to BOUND a slow/stalled leg so it fails ITS leg instead of hanging the whole panel. A transient CLI stall (an empty turn or a "timeout waiting for response" marker) is retried once, but only when it fails FAST, so a retry can never double a slow leg's wall-clock.

Use

Optional governed research

For current external evidence, opt in with ResearchPolicy(enabled=True) on the board. The runtime requires the exact published pmcp==1.20.0 scoped_advisor_audit.v1 capability, creates unique per-seat locks/audits, and exposes only PMCP health/catalog/describe/invoke backed by Firecrawl and Bright Data research tools. It disables Codex native web search/apps, derives success from the completed correlated audit rather than model prose, and emits only privacy-safe tool IDs, statuses, source hashes, and digests. Harness still runs only through the subscription TUI adapter—never an API, SDK, direct HTTP call, gateway backing, or native Task Agent. Gemini/agy, Grok, Omnigent, native-host, and custom-spawn research seats fail closed as research_profile_unenforceable.

Fable and Opus seats are subscription-TUI only. The runtime requires the homebrew self-PTY backing and rejects alternate backings before gateway access. It launches the exact requested model only after a metadata-only probe proves a logged-in first-party subscription, scrubs tokens, API helpers, custom request headers, alternate endpoints, and cloud-provider selectors, and isolates user/project/local settings. Never fill the seat with a native Task Agent and never add an API/SDK/direct-HTTP fallback. Inside a driving host session where the nested TUI adapter cannot run, the seat fails closed as UNAVAILABLE/tui_adapter_required; retry from a host where the adapter can run.

Today's TUI adapter has no typed classifier-refusal capability. Refusal-looking transcript text remains degraded/error evidence and cannot trigger fallback. A future typed adapter may allow one Opus TUI retry only for independently attested defensive-security work, then fails closed on a second refusal.

1. Prefer the repo's governed phase-loop path when reviewing phase execution or pre-merge work.
2. For a standalone smoke or diagnostic, run phase-loop advisor-board <artifact> (or, in-process, compose with compose_review_board and pass the material's path via artifact_ref to phase_loop_runtime.panel_invoker.invoke_board).
3. Require every leg to end with AGREE, PARTIALLY AGREE, or DISAGREE.
4. Treat EMPTY, TIMEOUT, ERROR, DEGRADED, and UNAVAILABLE as structured evidence, not successful reviews.
5. Keep provider API keys and custom authorization headers out of the environment; the runtime strips known API-key variables and request-header overrides and uses local subscription CLIs.

Standalone Smoke Shape

from phase_loop_runtime.advisor_board.composition import compose_review_board
from phase_loop_runtime.panel_invoker import invoke_board

# Availability-aware by default: compose_review_board seats only vendors that are
# BOTH on PATH and authenticated (unauthed vendors are dropped and backfilled).
board = compose_review_board()
result = invoke_board(board, "", artifact_ref="path/to/bundle.md")
for leg in result.legs:
    print(leg.seat_key, leg.status)

Under Harness Code, expect a default Harness seat to report UNAVAILABLE with detail="tui_adapter_required" and no native-fill request. This is an explicit unavailable seat, not authorization to bypass the TUI/auth boundary.