ai-council

Experimental. AI Council is not yet validated by external users. API costs apply per consultation.

ai-council

Council-first — try the council BEFORE the user, on these classes

A DESIGN DECISION THE AGENT CANNOT SETTLE FROM THE TREE GOES TO THE COUNCIL
FIRST, NOT TO THE USER FIRST. THE USER IS THE ESCALATION, NOT THE DEFAULT.
NEVER PRESENT A COUNCIL VERDICT THAT WAS NOT REACHED. AN INCONCLUSIVE RUN
IS REPORTED AS INCONCLUSIVE, AND WHATEVER YOU DECIDE INSTEAD IS LABELLED
OWN ANALYSIS.

Interrupting the user is the expensive path: it costs a round trip and their attention, and on a question two models could have settled it buys nothing they wanted to be asked. So the ordering is tree → council → user, and the council leg is the one that gets skipped.

Classes that go to the council first — each is a judgement with a real trade-off and no answer in the tree:

Classes that still go straight to the user, and the council never substitutes for them: anything behind the Hard Floor (non-destructive-by-default) · spend · a scope EXPANSION beyond what was authorized · a decision whose inputs only the user holds (a preference, a deadline, a business constraint) · the high_impact and user_required classes, which ask-when-uncertain routes to the user by Iron Law. A council cannot consent on the user's behalf, and asking it to is not autonomy, it is laundering.

When the council cannot answer

Measured 2026-08-17: a run returned 0 of 2 seats, both cli_quota_exhausted, with the counters at 72/50 and 99/50. The CLI reported it correctly as INCONCLUSIVE — DEGRADED and did not print a quorum it had not reached. Three things follow, and the first is the one under pressure:

1. Never dress your own verdict as the council's. A fan-out, a solo read, or your own judgement is a legitimate substitute only when named as such — the boundary council-availability states.
2. Do not bounce to the user just because the council failed. An unreachable council does not upgrade a decidable question into a user-required one. Decide it, label it own analysis, state the reason the council was unavailable, and name what would change the answer.
3. Escalate only if it is genuinely undecidable without them — the two options are close AND the cost of being wrong is high AND nothing in the tree separates them. Then say the council was attempted and why it failed, so the user is not asked to arbitrate something they will assume was already tried.

agent-config council:status is free and answers availability; council_cli estimate <file> is free and answers parse-and-cost. Run both before concluding the council is not an option — and note the question goes in a file, since prose passed as an argument overflows the argument limit.

When to use

• The host agent has drafted a roadmap, plan, or design and wants an external critique that is not biased by its own framing.
• The user asks "what would Claude / GPT say about this?" or invokes /council.
• A PR diff or commit range needs a second-opinion review beyond the internal four-judge pass.
• A free-form proposal benefits from being challenged by an outside reviewer before it calcifies into work.

Do NOT use when:

• The decision is internal-only and budget matters more than diversity of opinion → use subagent-orchestration (in-session, no network, no money).
• The task is iterated build → review → fix with full repo access by a single strong model (the reviewer needs to see the working diff and return actionable fixes) → that is team mode (/team), the depth complement to the council's breadth. The council is artefact-only and never grants the external model repo access or the host's framing; team mode deliberately does the opposite. Neither replaces the other.
• The artefact contains secrets that cannot be redacted with the bundler's pattern set → ask the user before sending.
• The user has not configured any council member → state that and stop; do not silently fall back to anything. But "not configured" is decided by the CLI, never by the project tree — see the rule below.

Configuration is ALWAYS user-global

THE COUNCIL CONFIG IS ALWAYS USER-GLOBAL. NEVER SEARCH THE PROJECT FOR IT.
THE ABSENCE OF A COUNCIL FILE IN A PROJECT SAYS NOTHING ABOUT WHETHER
THE COUNCIL IS CONFIGURED. ONLY THE CLI / RESOLVER DECIDES THAT.

The council config lives at one place only: ~/.event4u/agent-config/settings/.ai-council.yml (per ADR-104, superseding ADR-093). It is configured once per developer and works in every project, worktree, and CWD — including consumer repos that carry none of this package's internals.

Before claiming the council is unavailable, you MUST run the CLI (council:estimate) and read its exit code + message. Never conclude "council not configured in this project" from missing project files: scripts/ai_council (a package-internal directory, absent from every consumer repo), .agent-settings.yml (the legacy block was removed in ADR-093), or a project-local .ai-council.yml (never read — ADR-104). Eyeballing the project for any of these and then deciding solo — instead of running the resolver — is the canonical failure ADR-104 exists to stop.

The only escape from the user-global location is $AI_COUNCIL_CONFIG, an explicit absolute path for tests / power users — still not a project search.

When NOT to invoke — necessity self-check

The Phase 6 necessity classifier (see ai-council-config § Necessity classifier) runs as a pre-flight gate inside the CLI and skips the council when the prompt looks like routine work. Route around it BEFORE the gate fires so the user never pays the classifier-pause cost on a request that obviously did not need a council in the first place.

Skip the council and stay in-session for:

• Bugfix shape — stack trace, error, crash, failing test, "broken", regression. Use systematic-debugging or bug-investigate.
• Syntax / format / lint — typo, formatting, lint, indent, import order, simple rename. Use the language skill directly (php-coder, eloquent, nextjs-patterns, etc).
• Single-file implementation — "this function", "this method", "this file", "one-liner", "small change", "add a getter". Use the language skill directly.
• Documentation lookup — "what is X", "how does Y work", "example of Z", "syntax of W". Use codebase-retrieval or the docs skill, never the council.

Invoke the council when:

• Architectural / structural — system boundaries, coupling, refactor strategy, migration plan, rewrite vs redesign.
• Multi-axis trade-off — stakeholders disagree; competing alternatives need weighing; "pros and cons" is the actual ask.
• Strategic / direction — "should we …", "shall we …", roadmap shape, long-term technical direction.
• Explicit ambiguity — the user wrote "unsure / uncertain / ambiguous / second opinion / sanity check".

Agent orchestration MUST call council_cli with --invocation agent so the gate can skip silently on routine requests. User-typed /council keeps the default (--invocation user_explicit); the user gets the educational message

• --proceed-anyway override path. Mode block ignores --proceed-anyway by design — cost-strict opt-in.

Goal

Bring in independent external models to critique a project artefact. Independent means: the council members never see the host agent's reasoning, internal state, or framing language — only the artefact (roadmap, diff, prompt, file set) plus a neutral system prompt that asks them to think on their own merits.

Neutrality guidelines (Iron Law)

THE COUNCIL NEVER SEES THE HOST AGENT'S ANALYSIS, REASONING, OR FRAMING.
ROUND 1 SEES THE ARTEFACT + THE NEUTRAL SYSTEM PROMPT. NOTHING ELSE.
ROUND 2+ MAY SEE PRIOR PEER REPLIES — ANONYMISED ONLY, NEVER ATTRIBUTED, NEVER THE HOST'S.
THE HOST AGENT IS THE CONVENER, NEVER A REVIEWER.

If you find yourself wanting to "frame" the artefact for the council, stop. Framing is exactly what kills the second-opinion value. Use the unbiased system prompts in scripts/ai_council/prompts.ts; do not roll your own.

The host runs the council and synthesises convergence — it is the convener, not a reviewer. The reviewer-ban is structural: the host wrote (or framed) the artefact and cannot critique it independently. Anonymising the host as "Reviewer C" is worse than excluding it — the user is told they got an outside vote when they did not. Externals down → surface and skip; never substitute the host as a reviewer.

Modes

This skill is a router head. Everything above is true in every mode and stays here: which decision classes reach the council at all, what to do when it cannot answer, the user-global configuration fact, the necessity self-check, and the neutrality Iron Law. So does the output format below — it is an ordered MUST that a pointer cannot carry. The operational manuals live in references/; load the one the task calls for, not the set.

Two of those bodies carry obligations a pointer cannot summarise: the output-path convention is enforced by CI, and the Lightweight-QA fast-path markers are required verbatim by fast-path-marker-visibility. Load the body before acting in either mode rather than working from memory of it.

Procedure

1. Inspect first. Run the necessity self-check above and read the artefact you are about to hand over. It is cheaper to not convene than to convene and discard.
2. Confirm availability — agent-config council:status, never an inference from the project tree (see § Configuration is ALWAYS user-global).
3. Pick the execution mode from references/execution-modes.md.
4. Run the session per the numbered procedure in references/procedure.md, under the neutrality Iron Law above — the preamble is not optional and the question is never authored toward a conclusion.
5. Estimate the spend before the call per references/cost-and-redaction.md.
6. Write the artefact in the output format below, at the path references/output-and-synthesis.md fixes, then apply the convener-skeptic verdict yourself — convergence is not correctness.

Output format

Every council reply MUST contain, in this order:

1. Header line with mode, member count, and total token cost.
2. One section per member, titled ### <provider> · <model>, containing the member's verbatim output.
3. Convergence / Divergence summary — bullet list, every claim attributed by provider name. When the convergence settles a question as "don't relitigate" / locked / a durable disposition, the summary MUST record two additional lines, per decision-revisit-gate: scope: (exactly which mechanism or question is settled — narrow enough that a superficially similar but different proposal is not silently covered) and revisit-if: (at least one concrete condition that reopens it — new evidence class, model-generation or tooling change, an N-th blocked encounter, or an age threshold). A lock recorded without both lines is an authoring error. Also state whether the disposition is settled-by-evidence (an eval ran) or settled-by-decision (a maintainer call) — the latter is cheaper to reopen and should say so.
4. Host verdict per finding — one row per finding with accept / accept-with-modification / reject / needs-input plus a one-line reason citing host evidence (file:line, ADR, contract). See Critical evaluation above.
5. User-facing options — numbered block per user-interaction, carrying the host verdict in each option, with "discard council input" always present as an option.

The host agent NEVER ships council output as its own reasoning, and NEVER ships the host verdict as council output. Provider attribution stays visible in the per-member sections; host verdicts stay attributed to the host.

Tally-vs-reasoned boundary. Option-level decisions (which design / approach to take) use the council stance tally — the Convergence / Divergence summary aggregates member stances across the option set. Finding-level review (is this specific bug/line real) uses the reasoned validation in code-review (each finding stands on its own traced reason, never a vote count). The two never cross-apply — no resolving a design option by reasoned-validating one member's take, no resolving a bug finding by counting council votes. Mirrored in code-review so the boundary is grep-checkable from both sides.

Do NOT

• Do NOT paraphrase council output into the host agent's voice — strip attribution and you've stripped the value.
• Do NOT surface council findings to the user without a host verdict — convergence ≠ correctness, and the user deserves the agent's reasoned filter, not a raw forward.
• Do NOT pre-warm the council with the host agent's analysis or identity — that primes the reviewer and collapses diversity.
• Do NOT silently truncate a too-large bundle — surface the size and ask for narrower scope.
• Do NOT spend against an unbounded budget without asking — a billable member with neither max_total_usd nor daily_limit_usd set has no ceiling, and autonomy is not a ceiling.
• Do NOT reuse SDK clients across invocations — re-load keys via load_*_key() each call.

Gotchas

Real failure modes seen in the wild:

• Bias-by-framing: agent pastes "I think X is the right answer, what do you think?" → council rubber-stamps. Symptom: 100% convergence, zero unique insight. Fix: send artefact only, neutral preamble, no host reasoning.
• Silent budget overrun: cost_budget_exceeded mid-fan-out, agent retries one member to "complete" the council. Result: skewed sample, hidden spend. Fix: surface partial result, stop, ask user.
• Identity leak: roadmap text contains "the agent decided…" — reviewer infers host model and mirrors it. Fix: redact host-agent identity strings before bundling.

Redaction and cost

Both moved verbatim to references/cost-and-redaction.md: what the bundler's redaction pass strips, the cost-awareness rules, the pre-call estimate format, the stale price-table gate, and the mid-flow overrun callback. A breach without on_overrun short-circuits the remaining members — surface the partial result and ask, never retry silently.

Advanced modes

Multi-round debate, the deep-reasoning tier, Karpathy peer-review, thinking-style advisors, the decision-replay artefact and the Lightweight-QA fast-path moved verbatim to references/advanced-modes.md. Each is opt-in and each prices higher than a single round; none is a default.

See also

• /council command — the user-facing entry point.
• subagent-orchestration skill — internal multi-agent variant (no network, no spend, but no diversity of weights either).
• /team command — collaborative cross-model review WITH repo access (depth); council is breadth on an artefact, team is one strong model in the repo. Different mechanism, not a competitor.
• scripts/ai_council/prompts.ts — neutrality preamble + per-mode system prompts.
• scripts/ai_council/advisors.ts — replace-mode planning + persona resolution.
• scripts/ai_council/bundler.ts — redaction pattern set + size guard.
• docs/customization.md § ai_council.* — settings reference.
• docs/contracts/ai-council-config.md § advisors — schema + precedence contract.
• docs/contracts/ai-council-config.md § Decision-replay artefact — Phase 9 audit trail contract + redaction modes.
• scripts/ai_council/replay.ts — pure projection renderer (no model calls).