my-council

/my-council — Parallel Critics + Separate Synthesis

v0.1.0 — Generic-purpose port of upstream chrisblattman/claudeblattman/skills/council.md v1.3. 8 personas, 4 named panels (generic / business-idea / research / decision). Single-round + separate synthesis design. No specflow coupling.

Dispatches N critic agents in parallel against the same input, collects raw outputs as data, and runs a separate synthesis pass in fresh context that reconciles into a single verdict + structured patch list. Hard cap 5. Single-round only. Never majority-votes on narrative output.

Cross-talk between critics produces conformity drift (arXiv 2510.07517, 2509.05396, 2511.07784); single-round-with-synthesis is the empirically better design (Karpathy 2025; multi-agent literature 2026).

Quick Start

The fastest path that works out of the box, using the bundled personas:

/my-council file:docs/<doc>.md                               # default: generic panel (5 critics)
/my-council file:docs/<pitch>.md --type business-idea        # business-idea panel (4)
/my-council file:docs/<research>.md --type research          # research panel (3)
/my-council "Should we accept X?" --type decision            # decision panel (2)

All four default panels are backed by persona files shipped in ${CLAUDE_PLUGIN_ROOT}/agents/ — no BYO required.

Config

Environment variables (read at dispatch time; defaults baked in):

MY_COUNCIL_CRITIC_MODEL=opus       # or sonnet for cheaper runs
MY_COUNCIL_SYNTHESIS_MODEL=opus
MY_COUNCIL_MAX_CRITICS=5
MY_COUNCIL_DEFAULT_N=3

Models are set here, not in persona frontmatter. Next-model migration = edit two env vars.

Invocation

Primary: /my-council <topic> or /my-council file:<path> [flags]

Natural-language triggers:

• "council this" / "spin up a council on X" / "panel of advisors"
• "pressure-test this pitch" / "review this business idea" → auto-set --type business-idea
• "stress-test this research" / "review this paper / report / brief" → auto-set --type research
• "should I X" / "go-no-go on Y" / "accept-or-reject Z" → auto-set --type decision
• Meta-reference guard: sentences about councils as a topic are not invocations. On low confidence, ask one line.

When NOT to invoke

• Per-issue iteration on a single paragraph. Council is for whole-document review; for iterating on a paragraph, use a direct edit loop.
• Re-runs on the same input you already addressed. One run per input version is the discipline.
• Tasks better served by a domain-oracle skill (e.g., shipbroking-oracle for offshore-vessel commercial questions). The council is a generalist; specialists outperform generalists in their domain.

Flags

Flag	Effect
--type <name>	Use a named default panel. Names: generic (default), business-idea, research, decision.
--panel a,b,c	Explicit persona list, in order. Names must match persona file basenames in EITHER the plugin layer OR the user layer (see Persona discovery). Overrides --type if both are given.
--skip a,b	After resolving the panel via --type or default, remove the listed personas from it.
--n K	Truncate the resolved panel to the first K members. Useful when the panel's natural size exceeds your needs or MY_COUNCIL_MAX_CRITICS.
--mixed <vendor>	Swap ONE Claude critic for a cross-vendor peer where <vendor> is codex or gemini. Vendor-to-persona auto-mapping in Phase 4. Graceful fallback to all-Claude if the peer CLI is missing. Direction: Claude → peer only (asymmetry rule).

Hard cap: MY_COUNCIL_MAX_CRITICS (default 5). Larger resolved panels halt rather than dispatch, with a "narrow with --skip or --n" message.

Default panels

Resolved from --type or keyword inference. All persona names below reference files shipped in ${CLAUDE_PLUGIN_ROOT}/agents/.

--type	Members	Use case	N
generic (default)	skeptic, pragmatist, strategist, customer-voice, operator	anything not fitting a more specific panel — the long tail	5
business-idea	strategist, pragmatist, customer-voice, skeptic	pitches, GTM, market entry, partnership review, product proposals	4
research	researcher, skeptic, ethicist	reports, briefings, claims, market analyses, lit reviews	3
decision	skeptic, operator	go/no-go, accept/reject, single-question decisions	2

Keyword inference (only used if --type not given and the invocation came via natural-language trigger): "research / study / report / claim" -> research; "decision / should I / go-no-go" -> decision; "pitch / business idea / GTM / market entry" -> business-idea; anything else -> generic; ambiguous -> ask one line.

Upstream's paper and grant panels are intentionally not included: my-council does not ship the academic-review personas (academic-editor, harsh-referee, methodologist, grant-strategist, funder-officer) those panels require. Upstream's skill-review panel is also out of scope for v0.1.0 — that panel is mostly useful inside a plugin-development workflow. If you need any of these, author the persona files at ~/.claude/agents/<name>.md and invoke via --panel <list>.

Persona discovery

Two-layer filesystem discovery. Merge into a single registry keyed by basename.

1. Plugin layer (shipped, guaranteed present): Glob ${CLAUDE_PLUGIN_ROOT}/agents/*.md. Strip .md. Plugin personas dispatch as subagent_type: my-council:<name>.
2. User layer (operator-extensible, opt-in): Glob ~/.claude/agents/*.md AND ~/.claude/agents/*-agent.md AND ~/.claude/agents/experts/*.md. Strip .md and any -agent suffix. If the folder does not exist, treat as empty. User personas dispatch as bare subagent_type: <name>.

Collision rule: plugin layer wins. The framework's persona contracts must remain stable; a user-level file cannot silently override a plugin persona. On collision, emit exactly one line before dispatch:

my-council: <name> resolved from plugin (user copy at ~/.claude/agents/<name>.md shadowed)

Dispatch phases

Phase 1 — Parse and resolve

1. Parse $ARGUMENTS. Determine if the positional is a topic (plain text) or a file path (with or without file: prefix).
2. If a file path: Read it. The file content is the critic input.
3. Discover personas across the two layers (see Persona discovery above). Build the registry.
4. Resolve the panel in this precedence:
   • --panel a,b,c -> use those names verbatim, in order. Ignores --type if both are given.
   • --type X -> look up the named panel in the table above. Unknown name -> halt and list the available names.
   • Neither, but natural-language trigger present -> run keyword inference; ambiguous -> ask.
   • Neither and no trigger -> use generic (the documented default).
5. Apply --skip a,b if present: remove those names from the resolved list. Empty result after skip -> halt and ask.
6. Apply --n K if present: truncate to the first K members.
7. Validate every remaining name appears in the merged persona registry. Missing names -> halt with the precise list of unresolved persona names AND the two folders searched. No silent fallback to general-purpose.
8. Enforce hard cap of MY_COUNCIL_MAX_CRITICS. Larger -> halt with "narrow with --skip or --n" message.

Phase 2 — Meta-reference guard

If invocation arrived via a natural-language trigger (not explicit /my-council), dispatch one short classification Task call to decide whether this is an invocation or a meta-reference. If META or UNCLEAR, ask one line before continuing. Skip this phase if the invocation was explicit (/my-council ...).

Phase 3 — Dispatch announcement

Print one line before the parallel Task calls:

$PANEL_NAME panel: dispatched N critics on $MY_COUNCIL_CRITIC_MODEL

No terminal period. $PANEL_NAME is the resolved panel name (generic / business-idea / research / decision) or custom for --panel invocations. If $MY_COUNCIL_CRITIC_MODEL resolves to a long versioned string (e.g. claude-opus-4-7-20260512), display the short label (e.g. opus-4.7).

Phase 4 — Peer swap (only if --mixed <vendor> set)

If --mixed <vendor> was passed (codex or gemini), swap ONE Claude critic in the resolved panel for a cross-vendor peer. Preserves the panel size; only one critic is swapped. Mark the swapped slot so Phase 5 dispatches it as a Bash call to the peer CLI rather than as a Task call.

Vendor-to-persona auto-mapping (first match in the resolved panel wins):

Peer vendor	Preferred swap targets (in order)	Rationale
codex	skeptic, then operator	empirical rigor + pre-mortem framing (operator's persona explicitly cites Klein, HBR 2007)
gemini	researcher, then futurist	long-context synthesis + broad domain coverage / forward-aging horizon

If none of the preferred targets are present in the resolved panel, swap the LAST critic in the resolved order (deterministic, not random).

CLI presence check: before marking the swap, verify the peer binary exists via command -v codex (or command -v gemini). If missing, print exactly one line:

my-council: <vendor> CLI not installed; continuing with all-Claude panel

...and unmark the swap. Graceful degradation; do not halt.

Asymmetry rule: Claude -> peer only. Do NOT propose the inverse (peer-first-then-Claude) panel in the same run; asymmetric dismissal of the Claude critics during synthesis is the known failure mode. One peer swap per run, max.

Phase 5 — Parallel dispatch

Send ONE message with N tool calls (true parallelism, not sequential).

For each non-swapped persona, dispatch a Task call:

• subagent_type: per the registry built in Phase 1 (plugin-namespaced as my-council:<name> or bare; see Persona discovery).
• model: value of MY_COUNCIL_CRITIC_MODEL (explicit, overrides any persona frontmatter).
• description: 3-5 word summary (e.g., "Skeptic review of pitch").
• prompt: structured prompt containing:
  • The persona's name + reminder it's parallel with N-1 others (no cross-talk)
  • The input (topic or file content)
  • Instruction to render its persona's structured output block exactly per its persona definition
  • Instruction to NOT see or speculate about other critics' outputs

If Phase 4 marked one slot for peer dispatch, include ONE additional Bash call in the same parallel message. Bash invokes the peer CLI with the persona's prompt content. Write the peer's stdout to a tempfile created by mktemp -t my-council-peer-XXXXXX.md (or platform equivalent); capture the path. The peer prompt is the same structured prompt the Task would have received — persona name, parallel-with-others reminder, input, output-shape instruction, no-cross-talk instruction — formatted as plain text for the CLI. Exact invocation is per the vendor's --help (Codex: codex exec ...; Gemini: gemini -p "..." or stdin); the model resolves the right flags at dispatch time.

Phase 6 — Collect

Collect raw critic outputs. Do NOT inline-synthesize. If a peer was dispatched, the peer output is on disk at the tempfile path; the Claude critics' outputs are in Task results.

Phase 7 — Separate synthesis dispatch

One more Task call:

• subagent_type: general-purpose (fresh context, no critic conversation history)
• model: value of MY_COUNCIL_SYNTHESIS_MODEL
• description: "Synthesise critic verdicts"
• prompt: the synthesis template (below) + the resolved panel's branch + raw critic outputs (Reading the peer tempfile inline if applicable) + the original input + N (the panel size)

Synthesis template (common preamble):

You are the synthesis pass for a my-council review. N critics ran in parallel
against the same input. You read their raw outputs as DATA (not as conversation).
Produce ONE reconciled verdict per the panel-type branch below.

Hard rules:
- Preserve numbers and citations VERBATIM from critic outputs.
- Do not invent findings.
- Do not majority-vote narrative. Report disagreement honestly.
- One paragraph of operator framing at the top (no more than six sentences), then the structured output.
- If a peer-vendor critic was included, identify it in the per-critic verdict line
  (e.g., "gemini-2.5-pro (swapped for researcher)"). Treat it as one critic among N;
  do not weight it specially.

Panel-type branches:

• generic / business-idea / research:

  1. VERDICT (one word, lowercase): ship | revise | kill
     • revise if at least ceil(N/2) critics said REVISE or stronger
     • kill only if a critic flagged a structural blocker the others align on
  2. TOP 3 BLOCKERS — load-bearing findings across the lenses. Cite spec sections, document headings, file paths verbatim.
  3. TOP 3 REQUIRED PATCHES — actionable, attributed to which critic raised them.
  4. OPTIONAL PATCHES — 3-6 lower-priority items.
  5. PER-CRITIC VERDICT — one line per critic, anchored to that critic's load-bearing question, quote their CONFIDENCE verbatim.

  For research, the verdict vocabulary reads as "publish | revise | retract" in context — same logic, contextual wording.

• decision:

  1. RECOMMENDED ACTION (one of the options the input proposed): the recommendation, in one sentence.
  2. TOP 3 RISKS — what could go wrong, attributed to which critic raised them.
  3. TOP 3 REASONS IN FAVOR — what makes this the right call, attributed.
  4. PER-CRITIC VERDICT — one line per critic with CONFIDENCE.

Phase 8 — Emit

Emit the synthesis to the operator. Include the raw critic outputs (and the peer output if applicable) inside a <details> collapsible at the bottom for verification.

Phase 9 — Log

Append one row to ~/.claude-assistant/logs/my-council-invocations.csv (or skip if the log file does not exist):

timestamp,run_id,invoked_from,input,panel_resolved,critic_count,mixed_vendor,synthesis_verdict,model_critic,model_synthesis

The CSV schema includes mixed_vendor (empty when --mixed was not used) so cross-vendor runs are trackable in retrospect.

Calibration discipline

• One run per input version. Re-running on the same input re-samples noise; high-confidence multi-critic findings are stable, low-confidence single-critic findings vary by design.
• The verdict + top-3 blockers + required patches are the contract. Address them. Don't expand scope mid-cycle.
• Optional patches are operator's call. Most should be skipped.
• Verdict gates next step. REVISE means "address the named patches, then ship" — not "patch forever."
• New issues that emerge during patching go to the NEXT version's review, not a re-litigation of this one.

Why a Council

Multiple critics with explicit lenses outperform one general critic on review/decision tasks. The pattern:

• Parallel — each critic sees the same input and produces output independently.
• Separate synthesis — a fresh-context model reads the raw critic outputs as data, not as conversation history.
• Single round — no iterative debate. Round 2+ documented to drift toward conformity (2025-2026 multi-agent literature).
• Hard cap 5 — beyond 5 critics, you get diminishing returns and harder synthesis.

Out of scope

• Round 2 / iterative debate (single-round only).
• Majority voting on narrative output (conformity bias).
• LLM-proposed persona generation. Personas are filesystem-resident; the operator owns the panel library.
• Per-transport synthesis branches beyond the two above. Additional branches added as needed.

Performance Logging

echo "$(date +%Y-%m-%d),my-council,TOOL_CALLS,${N_CRITICS}-critics-${PANEL_TYPE}" >> ~/.claude-assistant/logs/skill-performance.csv

Mixed-mode setup

--mixed requires the peer CLI on PATH. The skill degrades gracefully if either is missing (one-line notice, continues with all-Claude panel).

• Codex CLI: ships with the OpenAI Codex desktop app. Verify with command -v codex. Authenticate per OpenAI's instructions before first use.
• Gemini CLI: npm install -g @google/gemini-cli. Verify with command -v gemini. Authenticate per Google's instructions before first use.

Mixed mode is most useful for empirical claims (does this library exist, does this benchmark hold, is this regex correct, is this API surface real) where cross-model verification adds real signal. For pure judgement work, the lens diversity comes from the persona prompts more than from the underlying model — all-Claude is usually sufficient.

Architectural notes

• The council is general-purpose — works on any text artefact that benefits from multi-lens review. Persona prompts are stack-agnostic and domain-agnostic; each persona researches as needed (WebFetch / WebSearch / Bash).
• Persona discovery is filesystem-based and layered. The plugin layer ships the framework personas at ${CLAUDE_PLUGIN_ROOT}/agents/<name>.md — guaranteed present after install, dispatched as subagent_type: my-council:<name>. The user layer at ~/.claude/agents/<name>.md is the operator's extension point: dropping a persona file there makes it dispatchable via --panel <name> with no plugin version bump. On basename collision the plugin copy wins.