/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                               # fast inline check
/council validate this plan                                    # validation (2 agents)
/council brainstorm caching approaches                         # brainstorm
/council validate the implementation                          # validation (critique triggers map here)
/council research kubernetes upgrade strategies                # research
/council research the CI/CD pipeline bottlenecks               # research (analyze triggers map here)
/council --preset=security-audit validate the auth system      # preset personas
/council --deep --explorers=3 research upgrade automation      # deep + explorers
/council --debate validate the auth system                # adversarial 2-round review
/council --deep --debate validate the migration plan      # thorough + debate
/council                                                       # infers from context

Council works independently — no RPI workflow, no ratchet chain, no

ao

Modes

--quick

--deep

--mixed

--debate

/council --quick validate recent   # inline single-agent check, no spawning
/council recent                    # 2 runtime-native judges
/council --deep recent             # 3 runtime-native judges
/council --mixed recent            # runtime-native + Codex CLI

Spawn Backend (MANDATORY)

Council requires a runtime that can spawn parallel subagents and (for

--debate

--quick

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

After detecting your backend, read the matching reference for concrete spawn/wait/message/cleanup examples:

• Claude feature contract →

  skills/shared/references/claude-code-latest-features.md

• Claude Native Teams →

  skills/shared/references/backend-claude-teams.md

• Codex Sub-Agents / CLI →

  skills/shared/references/backend-codex-subagents.md

• Background Tasks →

  skills/shared/references/backend-background-tasks.md

• Inline (

  --quick

  ) →

  skills/shared/references/backend-inline.md

See also

references/cli-spawning.md

When to Use

--debate

Use

--debate

• Security audits, architecture decisions, migration plans
• Reviews where multiple valid perspectives exist
• Cases where a missed finding has real consequences

Skip

--debate

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

Natural language works — the skill infers task type from your prompt.

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":"..."}

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

--quick

--debate

.agents/council/

Timeout: 120s per agent (configurable via

--timeout=N

Minimum quorum: At least 1 agent must respond for a valid council. If 0 agents respond, return error.

Pre-Flight Checks

1. Multi-agent capability: Detect whether runtime supports spawning parallel subagents. If not, degrade to

   --quick

   .
2. Agent messaging: Detect whether runtime supports agent-to-agent messaging. If not, disable

   --debate

   .
3. Codex CLI judges (--mixed only): Check

   which codex

   , test model availability, test

   --output-schema

   support. Downgrade mixed mode when unavailable.
4. Agent count: Verify

   judges * (1 + explorers) <= MAX_AGENTS (12)

5. 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

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

{
  "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"
      ]
    },
    "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
    }
  }
}

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

--perspectives

--count

Named Perspectives

Named perspectives assign each judge a specific viewpoint. Pass

--perspectives="a,b,c"

--perspectives-file=<path>

/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

--preset

--count

--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

judges * (1 + explorers)

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

SendMessage

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

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

COUNCIL_TIMEOUT

COUNCIL_CODEX_MODEL

-m

COUNCIL_CLAUDE_MODEL

--profile=thorough

COUNCIL_EXPLORER_MODEL

COUNCIL_EXPLORER_TIMEOUT

COUNCIL_R2_TIMEOUT

Flags

--deep

--mixed

--debate

--quick

--timeout=N

--perspectives="a,b,c"

--perspectives-file=<path>

--preset=<name>

--count=N

--count=4

--explorers=N

--explorer-model=M

--technique=<name>

references/brainstorm-techniques.md

--profile=<name>

COUNCIL_CLAUDE_MODEL

--count

--deep

--mixed

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                                        # 2 judges, recent commits
/council --deep --preset=architecture research the auth system  # 3 judges with architecture personas
/council --mixed validate this plan                             # 3 Claude + 3 Codex
/council --deep --explorers=3 research upgrade patterns         # 12 agents (3 judges x 4)
/council --preset=security-audit --deep validate the API        # attacker, defender, compliance
/council --preset=doc-review validate README.md                  # 4 doc judges with named perspectives
/council brainstorm caching strategies for the API              # 2 judges explore options
/council --technique=scamper brainstorm API improvements               # structured SCAMPER brainstorm
/council --technique=six-hats brainstorm migration strategy            # parallel perspectives brainstorm
/council --profile=thorough validate the security architecture       # opus, 3 judges, 120s timeout
/council --profile=fast validate recent                               # haiku, 2 judges, 60s timeout
/council research Redis vs Memcached for session storage        # 2 judges assess trade-offs
/council validate the implementation plan in PLAN.md            # structured plan feedback
/council --preset=doc-review validate docs/ARCHITECTURE.md             # 4 doc review judges
/council --perspectives="security-auditor,perf-critic" validate src/   # named perspectives
/council --perspectives-file=.agents/perspectives/custom.yaml validate # perspectives from file

Fast Single-Agent Validation

User says:

/council --quick validate recent

What happens:

1. Agent gathers context (recent diffs, files) inline without spawning
2. Agent performs structured self-review using council output schema
3. 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:

1. Agent spawns 2 judges (runtime-native backend) with independent perspectives
2. R1: Judges assess independently, write verdicts to

   .agents/council/

3. R2: Team lead sends other judges' verdicts via backend messaging
4. Judges revise positions based on cross-perspective evidence
5. 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:

1. Agent spawns 3 Claude judges + 3 Codex judges (6 total)
2. Each judge spawns 2 explorer sub-agents (6 x 3 = 18 total agents, exceeds MAX_AGENTS)
3. Agent auto-scales to 2 judges per vendor (4 x 3 = 12 agents at limit)
4. Explorers perform parallel deep-dives, return sub-findings to judges
5. Judges consolidate explorer findings with own research

Result: Cross-vendor research with deep exploration, capped at 12 total agents.

Troubleshooting

--quick

--debate

--debate

--explorers=N

--explorers

--count

brew install codex

.agents/council/

ls -ld .agents/council/

--timeout=300

COUNCIL_TIMEOUT

Migration from /judge

/council

/judge

/judge recent

/council validate recent

/judge 2 opus

/council recent

/judge 3 opus

/council --deep recent

The

/judge

/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

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

• 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

Degradation

If no multi-agent capability is detected, council falls back to

--quick

--debate

Judge Naming

Convention:

council-YYYYMMDD-<target>

council-20260206-auth-system

Judge names:

judge-{N}

judge-1

judge-2

judge-{perspective}

judge-error-paths

judge-feasibility

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 orchestration

• skills/standards/SKILL.md

  — Language-specific coding standards

• skills/research/SKILL.md

  — Codebase exploration (complementary to council research mode)