Council

/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 CLI required. Zero setup beyond initial install.

Modes

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

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:

1. Canonical mutation + ack sequence is explicit, single-path, and non-contradictory.
2. Consume-at-most-once path is crash-safe with explicit atomic boundary and restart recovery semantics.
3. Status/precedence behavior is defined with a field-level truth table and anomaly reason codes for conflicting evidence.
4. 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

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

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

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

Flags

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, web-security
/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

Migration from judge

/council replaces the old judge skill. Migration:

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 orchestration
• skills/standards/SKILL.md — Language-specific coding standards
• skills/research/SKILL.md — Codebase exploration (complementary to council research mode)

Reference Documents

• references/backend-background-tasks.md
• references/backend-claude-teams.md
• references/backend-codex-subagents.md
• references/backend-inline.md
• references/brainstorm-techniques.md
• references/claude-code-latest-features.md
• references/model-profiles.md
• references/presets.md
• references/quick-mode.md
• references/ralph-loop-contract.md
• ../shared/references/backend-background-tasks.md
• ../shared/references/backend-claude-teams.md
• ../shared/references/backend-codex-subagents.md
• ../shared/references/backend-inline.md
• ../shared/references/claude-code-latest-features.md
• ../shared/references/ralph-loop-contract.md