======= 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: .. code-block:: text /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: .. code-block:: bash # 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. .. list-table:: :header-rows: 1 :widths: 20 10 15 55 * - 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):** .. code-block:: yaml --- 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):** .. code-block:: yaml --- # 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:** .. code-block:: yaml --- 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 ----------------- .. code-block:: markdown # 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:** .. code-block:: text > /wf:council using docs/plans/migration-plan.md **Council review from default location:** .. code-block:: text > # Create the platform default input file with your plan > /wf:council **Brainstorm mode with custom judges:** .. code-block:: text > /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.