Council

Council#

Orchestrate a multi-judge validation council with platform-neutral multi-persona orchestration, producing a consolidated verdict report.

Note

Generated artifacts use the platform orchestration adapter. Claude can use agent teams where available; Codex and OpenCode ask before subagents and otherwise use the sequential persona fallback.

Description#

The council skill runs multiple independent judge personas that review a document from different perspectives, debate across rounds, and produce a consolidated verdict. Each persona uses an isolated context when platform support is available, providing genuinely independent analysis.

Modes:

  • validate (default): Judges assess feasibility, correctness, and risks

  • brainstorm: Judges explore creative ideas and practical applications

  • research: Judges evaluate methodology, evidence, and completeness

Relationship to debate:

  • Debate uses HydraMCP for multi-model review (Claude, GPT, ollama, etc.)

  • Council uses platform-native persona orchestration for multi-agent review within Claude

You can chain them: council first for internal adversarial review, then debate to cross-validate with another model family.

Triggers#

The skill activates when you mention:

  • Running a council review

  • Multi-judge validation

  • Council this plan

Explicit invocation:

/wf:council

Input Format#

The council takes a markdown file with optional YAML frontmatter.

Create a council input file or use an existing plan document:

# Create a council input file
vi .claude/council.md  # or .codex/council.md / .opencode/council.md

Search order:

  1. Explicit path provided by the user

  2. the platform default input file in the current repository root

  3. If not found, shows a minimal example for the user to create

Frontmatter Fields#

All fields are optional. If frontmatter is omitted entirely, all defaults apply.

Field

Type

Default

Description

judges

list

auto-generated (3)

Judge definitions (name + perspective)

rounds

int

2

Number of inter-judge debate rounds

mode

string

"validate"

validate / brainstorm / research

verdict_threshold

int

majority

Judges that must agree for PASS (default: ceil(N/2))

output_dir

string

"resources/agent-docs/reviews/councils"

Where transcripts are written

context_budget_kb

int

100

Max total KB for embedded @file context

Judge fields (when provided):

  • name: Display name for the judge

  • perspective: System instructions defining their review angle

Example Frontmatter#

Full example (custom judges):

---
rounds: 2
mode: validate
verdict_threshold: 2
output_dir: resources/agent-docs/reviews/councils
judges:
  - name: Feasibility Reviewer
    perspective: >
      You review for technical feasibility and implementation risk.
  - name: Security Reviewer
    perspective: >
      You review for security, scalability, and operational concerns.
  - name: Maintainability Reviewer
    perspective: >
      You review for code maintainability, testing, and long-term cost.
---

Minimal example (auto-generated judges, all defaults):

---
# No frontmatter needed — or use an empty block:
---

The plan body alone is enough. Three judges are auto-generated from the plan content, and all settings use their defaults.

Overriding just one default:

---
rounds: 3
mode: brainstorm
---

All other fields keep their defaults. Judges are auto-generated.

@file Auto-Detection#

Same mechanism as the debate skill. The council scans the markdown body for @path/to/file references and embeds their contents into judge prompts.

Detection rules:

  • Pattern: @ followed by a path containing / or .

  • Must be preceded by whitespace or start-of-line

  • References inside fenced code blocks are skipped

  • Files are resolved relative to the repo root

  • Missing files produce a warning (not an error)

Embedding with budget:

Each file is read and checked against the context_budget_kb budget:

  • If it fits: embed the full file content in a fenced code block

  • If it exceeds the remaining budget: call smart_read with the plan topic as query, embed the condensed result marked [CONDENSED via smart_read]

Set context_budget_kb: 0 to disable file embedding entirely.

Workflow#

  1. Find and parse input file

    • Locate the markdown file using the search order

    • Split YAML frontmatter from markdown body

    • Apply defaults for missing fields

    • Determine mode and calculate verdict threshold

  2. Detect and embed context files

    • Scan body for @file references outside code fences

    • Read and embed files within budget

  3. Auto-generate judges (only if judges omitted)

    • Generate 3 complementary judge roles based on mode and content

    • Validate mode: feasibility, security, maintainability

    • Brainstorm mode: creativity, practicality, user impact

    • Research mode: methodology, evidence quality, completeness

  4. Create agent team

    • Start a session-scoped persona execution run

    • Lead coordinates all communication and writes output files

  5. Spawn judges and seed context

    • Each persona receives the full plan, embedded context, and role-specific instructions

    • Each persona produces an initial assessment with PASS/WARN/FAIL verdict

  6. Execute debate rounds

    • For each round, each judge receives all other judges’ latest responses

    • Judges update positions, defend or revise verdicts

  7. Consolidate verdicts

    • Count final PASS/WARN/FAIL verdicts

    • Apply threshold logic for overall verdict

    • Write points of agreement, contention, and recommendations

  8. Clean up agent team

    • Cleanup runs unconditionally, even on error

  9. Write transcript

    • Write to output_dir/council-YYYY-MM-DD-HHMMSS.md

Verdict Logic#

The overall verdict is determined by comparing judge verdicts against the threshold:

  • PASS: PASS count >= verdict_threshold

  • FAIL: FAIL count > (num_judges - verdict_threshold)

  • WARN: Everything else

The default threshold is majority (ceil(N/2)), so for 3 judges, at least 2 must PASS for an overall PASS.

Transcript Format#

# Council Verdict Report

**Topic:** Migrate Auth to JWT
**Document:** platform default input file
**Date:** 2026-02-18 14:30:00
**Mode:** validate
**Rounds:** 2
**Verdict Threshold:** 2 of 3

## Judges

| # | Name | Perspective | Final Verdict |
|---|------|-------------|---------------|
| 1 | Feasibility Reviewer | Technical feasibility... | PASS |
| 2 | Security Reviewer | Security concerns... | WARN |
| 3 | Maintainability Reviewer | Long-term cost... | PASS |

## Overall Verdict: PASS

[summary]

## Round 1

### Feasibility Reviewer

[response]

...

## Consolidated Findings

### Points of Agreement
### Points of Contention
### Recommendations

## Verdict Summary

| Judges PASS | Judges WARN | Judges FAIL | Threshold | Overall |
|-------------|-------------|-------------|-----------|---------|
| 2           | 1           | 0           | 2 of 3    | PASS    |

Example Usage#

Council review with default judges:

> /wf:council using docs/plans/migration-plan.md

Council review from default location:

> # Create the platform default input file with your plan
> /wf:council

Brainstorm mode with custom judges:

> /wf:council using ideas/new-feature.md

Where the file includes mode: brainstorm in its frontmatter.

Error Handling#

  • Plan file not found: Shows minimal example for the user to create

  • Platform-native persona orchestration unavailable: Use the generated sequential fallback and record the downgrade

  • Judge fails to respond: Error recorded in transcript, remaining judges continue

  • ``@file`` not found: Warning in transcript, file skipped

  • ``smart_read`` fails: File skipped, warning logged

  • Frontmatter parse error: Reports the YAML error and line number

  • Team cleanup fails: Warning logged, does not block output

Limits#

  • Judges: 3 recommended, 2-5 supported. More judges = more tokens.

  • Rounds: 2 recommended. Above 3 the transcript may approach context limits.

  • Token cost: Each persona is a full agent session. A 3-judge, 2-round council costs approximately 6 agent turns plus coordination overhead. Use judiciously.

  • Context budget: Default 100 KB. Set to 0 to disable file embedding.

  • Non-deterministic: Real output varies between runs.

  • One team per session: Claude Code supports one agent team per session. Do not run council while another team is active.

Integration with Debate#

Council and debate complement each other:

  1. Run a council review for internal multi-perspective validation

  2. If the council produces WARN or FAIL, address the findings

  3. Run a debate using a different model family via HydraMCP to cross-validate

  4. Compare conclusions across both approaches

This gives you both multi-agent (council) and multi-model (debate) coverage.

Contents