council-orchestrator

Council Orchestration Protocol

Overview

Three-phase consensus protocol coordinating multiple LLMs for collaborative decision-making.

Architecture:

• Phase 1: Parallel opinion collection from available LLMs
• Phase 2: Cross-examination peer review
• Phase 3: Chairman synthesis of consensus

Council Members:

• Claude CLI (required minimum)
• OpenAI Codex CLI (optional, enhances consensus)
• Google Gemini CLI (optional, enhances consensus)

Quick Start

Prerequisites Check

# Resolve path to council_utils.sh
if [[ -n "${COUNCIL_PLUGIN_ROOT:-}" ]]; then
    UTILS_PATH="${COUNCIL_PLUGIN_ROOT}/skills/council-orchestrator/scripts/council_utils.sh"
elif [[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]]; then
    UTILS_PATH="${CLAUDE_PLUGIN_ROOT}/skills/council-orchestrator/scripts/council_utils.sh"
else
    UTILS_PATH="${CLAUDE_PROJECT_DIR}/skills/council-orchestrator/scripts/council_utils.sh"
fi

source "$UTILS_PATH"
get_cli_status

Quorum Requirements:

• Minimum: 1 CLI (Claude) - single-model mode for testing
• Recommended: 2+ CLIs - enables peer review and synthesis
• Optimal: All 3 CLIs - full consensus protocol

See detailed prerequisites for CLI installation.

---

Execution Flow

Phase 1: Opinion Collection

Quick Start:

# Initialize working directory
council_init

# Validate user input (security)
validate_user_input "$user_query" || exit 1

# Execute parallel opinion collection
PLUGIN_ROOT=$(get_plugin_root)
"${PLUGIN_ROOT}/skills/council-orchestrator/scripts/run_parallel.sh" "$query" .council

What it does:

• Consults all available LLMs in parallel
• Captures opinions to .council/stage1_*.txt
• Validates outputs and marks absent members
• Checks quorum for proceeding

Output Files:

• .council/stage1_claude.txt (required)
• .council/stage1_openai.txt (if Codex available)
• .council/stage1_gemini.txt (if Gemini available)

Manual Execution: See Phase 1 detailed guide

---

Phase 2: Peer Review

Quick Start:

PLUGIN_ROOT=$(get_plugin_root)
"${PLUGIN_ROOT}/skills/council-orchestrator/scripts/run_peer_review.sh" "$original_question" .council

What it does:

• Each LLM reviews peers' responses anonymously
• Uses structured review template from templates/review_prompt.txt
• Executes reviews in parallel
• Outputs to .council/stage2_review_*.txt

Cross-Review Matrix:

Reviewer	Reviews
Claude	Codex (A) + Gemini (B)
Codex	Claude (A) + Gemini (B)
Gemini	Claude (A) + Codex (B)

Output Files:

• .council/stage2_review_claude.txt
• .council/stage2_review_openai.txt
• .council/stage2_review_gemini.txt

Manual Execution: See Phase 2 detailed guide

---

Phase 3: Chairman Synthesis

Quick Start:

# Generate chairman invocation prompt
PLUGIN_ROOT=$(get_plugin_root)
CHAIRMAN_PROMPT=$("${PLUGIN_ROOT}/skills/council-orchestrator/scripts/run_chairman.sh" \
    "$original_question" \
    .council)

# Invoke chairman sub-agent
# Use Task tool: council-chairman agent

Prompt for Chairman:

Use the council-chairman agent to synthesize the council's responses.

$CHAIRMAN_PROMPT

After chairman completes:

# Retrieve final report for this run
cat .council/final_report.md

What it does:

• Chairman agent reads all Stage 1/2 files
• Analyzes for consensus and disagreements
• Generates comprehensive verdict report
• Writes to .council/final_report.md

Context Isolation:

• Chairman operates in isolated context
• Only has Read/Write tools (no Bash, no external CLIs)
• Ensures unbiased synthesis based solely on files

Manual Execution: See Phase 3 detailed guide

---

Error Handling

Error	Handling	Details
CLI missing	Proceed with available members	See quorum requirements
Rate limit (429)	Exponential backoff, retry once	Rate limit handling
Empty output	Mark member absent in report	Empty output handling
Timeout (>120s)	Terminate, mark absent	Timeout configuration
Quorum failure	Abort council session	Quorum check

Graceful Degradation:

• Council proceeds with available members (minimum 1 required)
• Absent members are noted in final report
• Peer review skipped if <2 responses
• Single-model mode if only Claude available

---

Security Best Practices

⚠️ Important: This skill executes external CLI tools with user-provided input. Follow security guidelines to prevent command injection and ensure safe operation.

Key Security Measures

• Input Validation: All user queries validated before passing to external CLIs
• CLI Verification: Ensure external CLIs (codex, gemini, claude) are from trusted sources
• Temporary Files: All data in .council/ is stored in a dedicated working directory. By default, files are preserved after synthesis so users can review or reuse the final report. Use council_cleanup or /council-cleanup to explicitly remove these files when no longer needed.
• Proper Quoting: All bash scripts use proper variable quoting to prevent injection

Usage

# Always validate user input before processing
# Resolve path to council_utils.sh
if [[ -n "${COUNCIL_PLUGIN_ROOT:-}" ]]; then
    UTILS_PATH="${COUNCIL_PLUGIN_ROOT}/skills/council-orchestrator/scripts/council_utils.sh"
elif [[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]]; then
    UTILS_PATH="${CLAUDE_PLUGIN_ROOT}/skills/council-orchestrator/scripts/council_utils.sh"
else
    UTILS_PATH="${CLAUDE_PROJECT_DIR}/skills/council-orchestrator/scripts/council_utils.sh"
fi

source "$UTILS_PATH"
validate_user_input "$user_query" || {
    error_msg "Invalid input - aborting for security"
    exit 1
}

Detailed Security Information

For comprehensive security guidance including:

• Input sanitization patterns
• CLI authenticity verification
• Threat model and mitigations
• Security audit checklist

See SECURITY.md

---

Output Format

The final output is the Chairman's Markdown report containing:

Report Structure

1. Executive Summary

   • Concise answer to original question
   • Key consensus points
   • Critical recommendations

2. Council Debate Summary

   • Table of significant divergences
   • Resolution of disagreements
   • Attribution to specific models

3. Detailed Analysis

   • Technical accuracy synthesis
   • Code quality assessment (if applicable)
   • Security considerations
   • Alternative approaches

4. Final Recommendation

   • Synthesized best practice
   • Implementation guidance
   • Caveats and edge cases

5. Participation Notes (if applicable)

   • Absent members
   • Degraded council mode notice

---

Additional Resources

Documentation

• REFERENCE.md - Detailed bash implementation and manual execution guide
• EXAMPLES.md - Usage scenarios, troubleshooting, and integration examples
• SECURITY.md - Security best practices and threat mitigation
• METADATA.md - Version history, compatibility, and licensing

Templates

• templates/review_prompt.txt - Peer review prompt template
• templates/chairman_prompt.txt - Chairman invocation template

Scripts

• scripts/council_utils.sh - Shared utility functions
• scripts/run_parallel.sh - Automated Phase 1 execution
• scripts/run_peer_review.sh - Automated Phase 2 execution
• scripts/run_chairman.sh - Chairman prompt generation
• scripts/query_claude.sh - Claude CLI wrapper
• scripts/query_codex.sh - Codex CLI wrapper
• scripts/query_gemini.sh - Gemini CLI wrapper

---

Common Usage Patterns

Full Automated Run

# Resolve path to council_utils.sh
if [[ -n "${COUNCIL_PLUGIN_ROOT:-}" ]]; then
    UTILS_PATH="${COUNCIL_PLUGIN_ROOT}/skills/council-orchestrator/scripts/council_utils.sh"
elif [[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]]; then
    UTILS_PATH="${CLAUDE_PLUGIN_ROOT}/skills/council-orchestrator/scripts/council_utils.sh"
else
    UTILS_PATH="${CLAUDE_PROJECT_DIR}/skills/council-orchestrator/scripts/council_utils.sh"
fi

source "$UTILS_PATH"

# Phase 0: reset working directory for this run
council_cleanup || true
council_init

# Phase 1
validate_user_input "$query" || exit 1
PLUGIN_ROOT=$(get_plugin_root)
"${PLUGIN_ROOT}/skills/council-orchestrator/scripts/run_parallel.sh" "$query" .council

# Phase 2
"${PLUGIN_ROOT}/skills/council-orchestrator/scripts/run_peer_review.sh" "$query" .council

# Phase 3
CHAIRMAN_PROMPT=$("${PLUGIN_ROOT}/skills/council-orchestrator/scripts/run_chairman.sh" "$query" .council)
# [Invoke chairman agent with $CHAIRMAN_PROMPT]

# Output
cat .council/final_report.md

Check Council Status

# Resolve path to council_utils.sh
if [[ -n "${COUNCIL_PLUGIN_ROOT:-}" ]]; then
    UTILS_PATH="${COUNCIL_PLUGIN_ROOT}/skills/council-orchestrator/scripts/council_utils.sh"
elif [[ -n "${CLAUDE_PLUGIN_ROOT:-}" ]]; then
    UTILS_PATH="${CLAUDE_PLUGIN_ROOT}/skills/council-orchestrator/scripts/council_utils.sh"
else
    UTILS_PATH="${CLAUDE_PROJECT_DIR}/skills/council-orchestrator/scripts/council_utils.sh"
fi

source "$UTILS_PATH"
get_cli_status
count_available_members
can_council_proceed && echo "Council ready" || echo "Install more CLIs"

Configuration Management

# View current config
config_list

# Set custom quorum
config_set "min_quorum" "3"

# Enable only specific members
config_set "enabled_members" "claude,gemini"

For more examples see EXAMPLES.md