| name | council |
| description | Multi-model consensus council. Spawns parallel judges with configurable perspectives. Modes: validate, brainstorm, research. Triggers: "council", "get consensus", "multi-model review", "multi-perspective review", "council validate", "council brainstorm", "council research". |
| skill_api_version | 1 |
| context | {"window":"isolated","intent":{"mode":"task"},"sections":{"exclude":["HISTORY"]},"intel_scope":"full"} |
| metadata | {"tier":"judgment","dependencies":["standards"],"replaces":"judge"} |
/council — Multi-Model Consensus Council
Spawn parallel judges with different perspectives, consolidate into consensus. Works for any task — validation, research, brainstorming.
Quick Start
/council --quick validate recent
/council validate this plan
/council brainstorm caching approaches
/council validate the implementation
/council research kubernetes upgrade strategies
/council research the CI/CD pipeline bottlenecks
/council --preset=security-audit validate the auth system
/council --deep --explorers=3 research upgrade automation
/council --debate validate the auth system
/council --deep --debate validate the migration plan
/council
Council works independently — no RPI workflow, no ratchet chain, no ao CLI required. Zero setup beyond initial install.
Modes
| Mode | Agents | Execution Backend | Use Case |
|---|
--quick | 0 (inline) | Self | Fast single-agent check, no spawning |
| default | 2 | Runtime-native (Codex sub-agents preferred; Claude teams fallback) | Independent judges (no perspective labels) |
--deep | 3 | Runtime-native | Thorough review |
--mixed | 3+3 | Runtime-native + Codex CLI | Cross-vendor consensus |
--debate | 2+ | Runtime-native | Adversarial refinement (2 rounds) |
/council --quick validate recent
/council recent
/council --deep recent
/council --mixed recent
Spawn Backend (MANDATORY)
Council requires a runtime that can spawn parallel subagents and (for --debate) send messages between agents. Use whatever multi-agent primitives your runtime provides. If no multi-agent capability is detected, fall back to --quick (inline single-agent).
Required capabilities:
- Spawn subagent — create a parallel agent with a prompt (required for all modes except
--quick)
- Agent messaging — send a message to a specific agent (required for
--debate)
Skills describe WHAT to do, not WHICH tool to call. See skills/shared/SKILL.md for the capability contract.
After detecting your backend, read the matching reference for concrete spawn/wait/message/cleanup examples:
- Shared Claude feature contract →
skills/shared/references/claude-code-latest-features.md
- Local mirrored contract for runtime-local reads →
references/claude-code-latest-features.md
- Claude Native Teams →
references/backend-claude-teams.md
- Codex Sub-Agents / CLI →
references/backend-codex-subagents.md
- Background Tasks →
references/backend-background-tasks.md
- Inline (
--quick) → references/backend-inline.md
See also references/cli-spawning.md for council-specific spawning flow (phases, timeouts, output collection).
When to Use --debate
Use --debate for high-stakes or ambiguous reviews where judges are likely to disagree:
- Security audits, architecture decisions, migration plans
- Reviews where multiple valid perspectives exist
- Cases where a missed finding has real consequences
Skip --debate for routine validation where consensus is expected. Debate adds R2 latency (judges stay alive and process a second round via backend messaging).
Incompatibilities:
--quick and --debate cannot be combined. --quick runs inline with no spawning; --debate requires multi-agent rounds. If both are passed, exit with error: "Error: --quick and --debate are incompatible."--debate is only supported with validate mode. Brainstorm and research do not produce PASS/WARN/FAIL verdicts. If combined, exit with error: "Error: --debate is only supported with validate mode."
Task Types
| Type | Trigger Words | Perspective Focus |
|---|
| validate | validate, check, review, assess, critique, feedback, improve | Is this correct? What's wrong? What could be better? |
| brainstorm | brainstorm, explore, options, approaches | What are the alternatives? Pros/cons? |
| research | research, investigate, deep dive, explore deeply, analyze, examine, evaluate, compare | What can we discover? What are the properties, trade-offs, and structure? |
Natural language works — the skill infers task type from your prompt.
First-pass rigor gate for plan/spec validation (MANDATORY)
When mode is validate and the target is a plan/spec/contract (or contains boundary rules, state transitions, or conformance tables), judges must apply this gate before returning PASS:
- Canonical mutation + ack sequence is explicit, single-path, and non-contradictory.
- Consume-at-most-once path is crash-safe with explicit atomic boundary and restart recovery semantics.
- Status/precedence behavior is defined with a field-level truth table and anomaly reason codes for conflicting evidence.
- Conformance includes explicit boundary failpoint tests and deterministic assertions for replay/no-duplicate-effect outcomes.
Verdict policy for this gate:
- Missing or contradictory gate item: minimum
WARN.
- Missing deterministic conformance coverage for any gate item: minimum
WARN.
- Critical lifecycle invariant not mechanically verifiable:
FAIL.
Architecture
Context Budget Rule (CRITICAL)
Judges write ALL analysis to output files. Messages to the lead contain ONLY a
minimal completion signal: {"type":"verdict","verdict":"...","confidence":"...","file":"..."}.
The lead reads output files during consolidation. This prevents N judges from
exploding the lead's context window with N full reports via SendMessage.
Consolidation runs inline as the lead — no separate chairman agent. The lead
reads each judge's output file sequentially with the Read tool and synthesizes.
Execution Flow
┌─────────────────────────────────────────────────────────────────┐
│ Phase 1: Build Packet (JSON) │
│ - Task type (validate/brainstorm/research) │
│ - Target description │
│ - Context (files, diffs, prior decisions) │
│ - Perspectives to assign │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Phase 1a: Select spawn backend │
│ codex_subagents | claude_teams | background_fallback │
│ Team lead = spawner (this agent) │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────────────┴─────────────────┐
▼ ▼
┌───────────────────────┐ ┌───────────────────────┐
│ RUNTIME-NATIVE JUDGES│ │ CODEX AGENTS │
│ (spawn_agent or teams)│ │ (Bash tool, parallel)│
│ │ │ Agent 1 (independent │
│ Agent 1 (independent │ │ or with preset) │
│ or with preset) │ │ Agent 2 │
│ Agent 2 │ │ Agent 3 │
│ Agent 3 (--deep only)│ │ (--mixed only) │
│ (--deep/--mixed only)│ │ │
│ │ │ Output: JSON + MD │
│ Write files, then │ │ Files: .agents/ │
│ wait()/SendMessage to │ │ council/codex-* │
│ lead │ │ │
│ Files: .agents/ │ └───────────────────────┘
│ council/claude-* │ │
└───────────────────────┘ │
│ │
└─────────────────┬─────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ Phase 2: Consolidation (Team Lead — inline, no extra agent) │
│ - Receive MINIMAL completion signals (verdict + file path) │
│ - Read each judge's output file with Read tool │
│ - If schema_version is missing from a judge's output, treat │
│ as version 0 (backward compatibility) │
│ - Compute consensus verdict │
│ - Identify shared findings │
│ - Surface disagreements with attribution │
│ - Generate Markdown report for human │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Phase 3: Cleanup │
│ - Cleanup backend resources (close_agent / TeamDelete / none) │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Output: Markdown Council Report │
│ - Consensus: PASS/WARN/FAIL │
│ - Shared findings │
│ - Disagreements (if any) │
│ - Recommendations │
└─────────────────────────────────────────────────────────────────┘
Graceful Degradation
| Failure | Behavior |
|---|
| 1 of N agents times out | Proceed with N-1, note in report |
| All Codex CLI agents fail | Proceed with runtime-native judges only, note degradation |
| All agents fail | Return error, suggest retry |
| Codex CLI not installed | Skip Codex CLI judges, continue with runtime judges only (warn user) |
| No multi-agent capability | Fall back to --quick (inline single-agent review) |
| No agent messaging | --debate unavailable, single-round review only |
| Output dir missing | Create .agents/council/ automatically |
Timeout: 120s per agent (configurable via --timeout=N in seconds).
Minimum quorum: At least 1 agent must respond for a valid council. If 0 agents respond, return error.
Pre-Flight Checks
- Multi-agent capability: Detect whether runtime supports spawning parallel subagents. If not, degrade to
--quick.
- Agent messaging: Detect whether runtime supports agent-to-agent messaging. If not, disable
--debate.
- Codex CLI judges (--mixed only): Check
which codex, test model availability, test --output-schema support. Downgrade mixed mode when unavailable.
- Agent count: Verify
judges * (1 + explorers) <= MAX_AGENTS (12)
- Output dir:
mkdir -p .agents/council
Quick Mode (--quick)
Single-agent inline validation. No subprocess spawning, no Task tool, no Codex. The current agent performs a structured self-review using the same output schema as a full council.
When to use: Routine checks, mid-implementation sanity checks, pre-commit quick scan.
Execution: Gather context (files, diffs) -> perform structured self-review inline using the council output_schema (verdict, confidence, findings, recommendation) -> write report to .agents/council/YYYY-MM-DD-quick-<target>.md labeled as Mode: quick (single-agent).
Limitations: No cross-perspective disagreement, no cross-vendor insights, lower confidence ceiling. Not suitable for security audits or architecture decisions.
Packet Format (JSON)
The packet sent to each agent. File contents are included inline — agents receive the actual code/plan text in the packet, not just paths. This ensures both Claude and Codex agents can analyze without needing file access.
If .agents/ao/environment.json exists, include it in the context packet so judges can reason about available tools and environment state.
Judge prompt boundary:
- Do NOT include
.agents/ references in judge prompts.
- Do NOT instruct judges to search
.agents/ directories. Judges operate on the council packet only.
{
"council_packet": {
"version": "1.0",
"mode": "validate | brainstorm | research",
"target": "Implementation of user authentication system",
"context": {
"files": [
{
"path": "src/auth/jwt.py",
"content": "<file contents inlined here>"
},
{
"path": "src/auth/middleware.py",
"content": "<file contents inlined here>"
}
],
"diff": "git diff output if applicable",
"spec": {
"source": "bead na-0042 | plan doc | none",
"content": "The spec/bead description text (optional — included when wrapper provides it)"
},
"prior_decisions": [
"Using JWT, not sessions",
"Refresh tokens required"
],
"empirical_results": "(optional) test output, CLI flag verification, or Wave 0 findings — include when evaluating feasibility"
},
"perspective": "skeptic (only when --preset or --perspectives used)",
"perspective_description": "What could go wrong? (only when --preset or --perspectives used)",
"output_schema": {
"verdict": "PASS | WARN | FAIL",
"confidence": "HIGH | MEDIUM | LOW",
"key_insight": "Single sentence summary",
"findings": [
{
"severity": "critical | significant | minor",
"category": "security | architecture | performance | style",
"description": "What was found",
"location": "file:line if applicable",
"recommendation": "How to address",
"fix": "Specific action to resolve this finding",
"why": "Root cause or rationale",
"ref": "File path, spec anchor, or doc reference"
}
],
"recommendation": "Concrete next step",
"schema_version": 2
}
}
}
Empirical Evidence Rule
When evaluating implementation feasibility (e.g., "will this CLI flag work?", "can these tools coexist?"), always include empirical test results in context.empirical_results. Judges reasoning from assumptions produce false verdicts — a Codex judge once gave a false FAIL on -s read-only because Wave 0 test output was not in the packet. The rule: run the experiment first, then let judges evaluate the evidence.
Wrapper skills (/vibe, /pre-mortem) should include relevant test output when the council target involves tooling behavior, flag combinations, or runtime compatibility.
Perspectives
Perspectives & Presets: Use Read tool on skills/council/references/personas.md for persona definitions, preset configurations, and custom perspective details.
Auto-Escalation: When --preset or --perspectives specifies more perspectives than the current judge count, automatically escalate judge count to match. The --count flag overrides auto-escalation.
Named Perspectives
Named perspectives assign each judge a specific viewpoint. Pass --perspectives="a,b,c" for free-form names, or --perspectives-file=<path> for YAML with focus descriptions:
/council --perspectives="security-auditor,performance-critic,simplicity-advocate" validate src/auth/
/council --perspectives-file=.agents/perspectives/api-review.yaml validate src/api/
YAML format for --perspectives-file:
perspectives:
- name: security-auditor
focus: Find security vulnerabilities and trust boundary violations
- name: performance-critic
focus: Identify performance bottlenecks and scaling risks
Flag priority: --perspectives/--perspectives-file override --preset perspectives. --count always overrides judge count. Without --count, judge count auto-escalates to match perspective count.
See references/personas.md for all built-in presets and their perspective definitions.
Explorer Sub-Agents
Explorer Details: Use Read tool on skills/council/references/explorers.md for explorer architecture, prompts, sub-question generation, and timeout configuration.
Summary: Judges can spawn explorer sub-agents (--explorers=N, max 5) for parallel deep-dive research. Total agents = judges * (1 + explorers), capped at MAX_AGENTS=12.
Debate Phase (--debate)
Debate Protocol: Use Read tool on skills/council/references/debate-protocol.md for full debate execution flow, R1-to-R2 verdict injection, timeout handling, and cost analysis.
Summary: Two-round adversarial review. R1 produces independent verdicts. R2 sends other judges' verdicts via backend messaging (send_input or SendMessage) for steel-manning and revision. Only supported with validate mode.
Agent Prompts
Agent Prompts: Use Read tool on skills/council/references/agent-prompts.md for judge prompts (default and perspective-based), consolidation prompt, and debate R2 message template.
Consensus Rules
| Condition | Verdict |
|---|
| All PASS | PASS |
| Any FAIL | FAIL |
| Mixed PASS/WARN | WARN |
| All WARN | WARN |
Disagreement handling:
- If Claude says PASS and Codex says FAIL → DISAGREE (surface both)
- Severity-weighted: Security FAIL outweighs style WARN
DISAGREE resolution: When vendors disagree, the spawner presents both positions with reasoning and defers to the user. No automatic tie-breaking — cross-vendor disagreement is a signal worth human attention.
Output Format
Report Templates: Use Read tool on skills/council/references/output-format.md for full report templates (validate, brainstorm, research) and debate report additions (verdict shifts, convergence detection).
All reports write to .agents/council/YYYY-MM-DD-<type>-<target>.md.
Configuration
Partial Completion
Minimum quorum: 1 agent. Recommended: 80% of judges. On timeout, proceed with remaining judges and note in report. On user cancellation, shutdown all judges and generate partial report with INCOMPLETE marker.
Environment Variables
| Variable | Default | Description |
|---|
COUNCIL_TIMEOUT | 120 | Agent timeout in seconds |
COUNCIL_CODEX_MODEL | gpt-5.3-codex | Override Codex model for --mixed. Set explicitly to pin Codex judge behavior; omit to use user's configured default. |
COUNCIL_CLAUDE_MODEL | sonnet | Claude model for judges (sonnet default — use opus for high-stakes via --profile=thorough) |
COUNCIL_EXPLORER_MODEL | sonnet | Model for explorer sub-agents |
COUNCIL_EXPLORER_TIMEOUT | 60 | Explorer timeout in seconds |
COUNCIL_R2_TIMEOUT | 90 | Maximum wait time for R2 debate completion after sending debate messages. Shorter than R1 since judges already have context. |
Flags
| Flag | Description |
|---|
--deep | 3 Claude agents instead of 2 |
--mixed | Add 3 Codex agents |
--debate | Enable adversarial debate round (2 rounds via backend messaging, same agents). Incompatible with --quick. |
--timeout=N | Override timeout in seconds (default: 120) |
--perspectives="a,b,c" | Custom perspective names (each name sets the judge's system prompt to adopt that viewpoint) |
--perspectives-file=<path> | Load named perspectives from a YAML file (see Named Perspectives below) |
--preset=<name> | Built-in persona preset (security-audit, architecture, research, ops, code-review, plan-review, doc-review, retrospective, product, developer-experience) |
--count=N | Override agent count per vendor (e.g., --count=4 = 4 Claude, or 4+4 with --mixed). Subject to MAX_AGENTS=12 cap. |
--explorers=N | Explorer sub-agents per judge (default: 0, max: 5). Max effective value depends on judge count. Total agents capped at 12. |
--explorer-model=M | Override explorer model (default: sonnet) |
--technique=<name> | Brainstorm technique (scamper, six-hats, reverse). Case-insensitive. Only applicable to brainstorm mode — error if combined with validate/research. If omitted, unstructured brainstorm (current behavior). See references/brainstorm-techniques.md. |
--profile=<name> | Model quality profile (thorough, balanced, fast). Error if unrecognized name. Overridden by COUNCIL_CLAUDE_MODEL env var (highest priority), then by explicit --count/--deep/--mixed. See references/model-profiles.md. |
CLI Spawning Commands
CLI Spawning: Use Read tool on skills/council/references/cli-spawning.md for team setup, Claude/Codex agent spawning, parallel execution, debate R2 commands, cleanup, and model selection.
Examples
/council validate recent
/council --deep --preset=architecture research the auth system
/council --mixed validate this plan
/council --deep --explorers=3 research upgrade patterns
/council --preset=security-audit --deep validate the API
/council --preset=doc-review validate README.md
/council brainstorm caching strategies for the API
/council --technique=scamper brainstorm API improvements
/council --technique=six-hats brainstorm migration strategy
/council --profile=thorough validate the security architecture
/council --profile=fast validate recent
/council research Redis vs Memcached for session storage
/council validate the implementation plan in PLAN.md
/council --preset=doc-review validate docs/ARCHITECTURE.md
/council --perspectives="security-auditor,perf-critic" validate src/
/council --perspectives-file=.agents/perspectives/custom.yaml validate
Fast Single-Agent Validation
User says: /council --quick validate recent
What happens:
- Agent gathers context (recent diffs, files) inline without spawning
- Agent performs structured self-review using council output schema
- Report written to
.agents/council/YYYY-MM-DD-quick-<target>.md labeled Mode: quick (single-agent)
Result: Fast sanity check for routine validation (no cross-perspective insights or debate).
Adversarial Debate Review
User says: /council --debate validate the auth system
What happens:
- Agent spawns 2 judges (runtime-native backend) with independent perspectives
- R1: Judges assess independently, write verdicts to
.agents/council/
- R2: Team lead sends other judges' verdicts via backend messaging
- Judges revise positions based on cross-perspective evidence
- Consolidation: Team lead computes consensus with convergence detection
Result: Two-round review with steel-manning and revision, useful for high-stakes decisions.
Cross-Vendor Consensus with Explorers
User says: /council --mixed --explorers=2 research Kubernetes upgrade strategies
What happens:
- Agent spawns 3 Claude judges + 3 Codex judges (6 total)
- Each judge spawns 2 explorer sub-agents (6 x 3 = 18 total agents, exceeds MAX_AGENTS)
- Agent auto-scales to 2 judges per vendor (4 x 3 = 12 agents at limit)
- Explorers perform parallel deep-dives, return sub-findings to judges
- Judges consolidate explorer findings with own research
Result: Cross-vendor research with deep exploration, capped at 12 total agents.
Troubleshooting
| Problem | Cause | Solution |
|---|
| "Error: --quick and --debate are incompatible" | Both flags passed together | Use --quick for fast inline check OR --debate for multi-round review, not both |
| "Error: --debate is only supported with validate mode" | Debate flag used with brainstorm/research | Remove --debate or switch to validate mode — brainstorming/research have no PASS/FAIL verdicts |
| Council spawns fewer agents than expected | --explorers=N exceeds MAX_AGENTS (12) | Agent auto-scales judge count. Check report header for actual judge count. Reduce --explorers or use --count to manually set judges |
| Codex judges skipped in --mixed mode | Codex CLI not on PATH | Install Codex CLI (brew install codex). Model uses user's configured default — no specific model required. |
No output files in .agents/council/ | Permission error or disk full | Check directory permissions with ls -ld .agents/council/. Council auto-creates missing dirs. |
| Agent timeout after 120s | Slow file reads or network issues | Increase timeout with --timeout=300 or check COUNCIL_TIMEOUT env var. Default: 120s. |
Migration from judge
/council replaces the old judge skill. Migration:
| Old | New |
|---|
| judge recent | /council validate recent |
| judge 2 opus | /council recent (default) |
| judge 3 opus | /council --deep recent |
The judge skill is deprecated. Use /council.
Multi-Agent Architecture
Council uses whatever multi-agent primitives your runtime provides. Each judge is a parallel subagent that writes output to a file and sends a minimal completion signal to the lead.
Deliberation Protocol
The --debate flag implements the deliberation protocol pattern:
Independent assessment → evidence exchange → position revision → convergence analysis
- R1: Spawn judges as parallel subagents. Each assesses independently, writes verdict to file, signals completion.
- R2: Lead sends other judges' verdict summaries to each judge via agent messaging. Judges revise and write R2 files.
- Consolidation: Lead reads all output files, computes consensus.
- Cleanup: Shut down judges via runtime's cleanup mechanism.
Communication Rules
- Judges → lead only. Judges never message each other directly. This prevents anchoring.
- Lead → judges. Only the lead sends follow-ups (for debate R2).
- No shared task mutation by judges. Lead manages coordination state.
Ralph Wiggum Compliance
Council maintains fresh-context isolation (Ralph Wiggum pattern) with one documented exception:
--debate reuses judge context across R1 and R2. This is intentional. Judges persist within a single atomic council invocation — they do NOT persist across separate council calls. The rationale:
- Judges benefit from their own R1 analytical context (reasoning chain, not just the verdict JSON) when evaluating other judges' positions in R2
- Re-spawning with only the verdict summary (~200 tokens) would lose the judge's working memory of WHY they reached their verdict
- The exception is bounded: max 2 rounds, within one invocation, with explicit cleanup
Without --debate, council is fully Ralph-compliant: each judge is a fresh spawn, executes once, writes output, and terminates.
Degradation
If no multi-agent capability is detected, council falls back to --quick (inline single-agent review). If agent messaging is unavailable, --debate degrades to single-round review with a note in the report.
Judge Naming
Convention: council-YYYYMMDD-<target> (e.g., council-20260206-auth-system).
Judge names: judge-{N} for independent judges (e.g., judge-1, judge-2), or judge-{perspective} when using presets/perspectives (e.g., judge-error-paths, judge-feasibility). Use the same logical names across both Codex and Claude backends.
See Also
skills/vibe/SKILL.md — Complexity + council for code validation (uses --preset=code-review when spec found)skills/pre-mortem/SKILL.md — Plan validation (uses --preset=plan-review, always 3 judges)skills/post-mortem/SKILL.md — Work wrap-up (uses --preset=retrospective, always 3 judges + retro)skills/swarm/SKILL.md — Multi-agent orchestrationskills/standards/SKILL.md — Language-specific coding standardsskills/research/SKILL.md — Codebase exploration (complementary to council research mode)
Reference Documents
