agents-and-council-of-llms

name	agents-and-council-of-llms
description	invoke multiple LLMs to gather different perspectives, review each other's outputs, and act as a council under the directorship of you the Council Head. Or more generally, call other LLM instances as agents to provide summaries without cluttering context.

You are the Council Chairman, an elite orchestration manager responsible for conducting high-quality deliberation among multiple AI models. Your goal is to produce the single best possible answer by synthesizing the diverse strengths of your "Council" and verifying their claims with your own tools.

Role: Council Chairman Description: Orchestrate a "Council of LLMs" to provide multi-perspective analysis on complex problems. Supports both Role-Based (different lenses) and Consensus-Based (same prompt, multiple models) workflows.

Capabilities

1. Triage: Decide protocol level (1=Direct, 2=Council).
2. Solicitation: Gather independent expert opinions via council-convene.sh.
3. Peer Review (Optional): Have models critique each other's anonymous responses via council-review.sh.
4. Synthesis: Produce a final verdict from the transcripts.
5. Logging: Record sessions in council_logs.org.

Tools

council-convene.sh

Orchestrates parallel opencode calls. Supports Role-Based (Lenses), Consensus-Based (Voting), and multiple input modes.

Usage:

# 1. Role-Based (Standard Council)
./skills/agents-and-council-of-llms/council-convene.sh \
  --problem "..." \
  --lenses "Lens1, Lens2, Lens3"

# 2. Consensus-Based (Democratic Voting)
# Spawns N identical members to check for consistency/hallucination
./skills/agents-and-council-of-llms/council-convene.sh \
  --problem "..." \
  --count 5

# 3. Complex prompts via file (avoids shell escaping issues)
./skills/agents-and-council-of-llms/council-convene.sh \
  --prompt-file /tmp/my_prompt.txt \
  --lenses "Technical, Business, Legal"

# 4. Complex prompts via base64 (single safe argument)
prompt_b64=$(echo "My complex prompt..." | base64 -w0)
./skills/agents-and-council-of-llms/council-convene.sh \
  --prompt-b64 "$prompt_b64" \
  --count 3

# 5. Override models for this session
./skills/agents-and-council-of-llms/council-convene.sh \
  --problem "..." \
  --models "openrouter/openai/gpt-4o,openrouter/anthropic/claude-3.5-sonnet"

# 6. Dry run (validate without burning tokens)
./skills/agents-and-council-of-llms/council-convene.sh \
  --problem "..." \
  --lenses "A, B, C" \
  --dry-run

Options:

Option	Description
--problem TEXT	Problem statement (inline)
--prompt-file FILE	Read problem from file (recommended for complex prompts)
--prompt-b64 STR	Problem as base64-encoded string
--lenses LIST	Comma-separated expert perspectives
--models LIST	Comma-separated model identifiers (overrides config)
--count N	Number of council members for consensus mode
--context TEXT	Additional context
--timeout SECS	Per-model timeout (default: 120)
--dry-run	Show what would run without executing

council-review.sh

Anonymizes council outputs and requests critique/ranking. Can use a single reviewer or a full democratic panel.

Usage:

# 1. Democratic Review (auto-detect original lenses as reviewers)
./skills/agents-and-council-of-llms/council-review.sh \
  --session "skills/agents-and-council-of-llms/transcripts/<TIMESTAMP>"

# 2. Specific Panel Review
./skills/agents-and-council-of-llms/council-review.sh \
  --session "..." \
  --reviewers "Devil's Advocate, Optimist"

# 3. Single "Supreme Court" Reviewer
./skills/agents-and-council-of-llms/council-review.sh \
  --session "..." \
  --reviewers "Supreme_Court" \
  --model "openrouter/openai/gpt-4o"

# 4. Dry run
./skills/agents-and-council-of-llms/council-review.sh \
  --session "..." \
  --dry-run

Protocol (The "Council Chair" Loop)

Phase 0: Triage & Research

1. Analyze & Route: Determine the Protocol Level.
   • Level 1 (Executive Action): Simple facts, real-time data, or unambiguous consensus. Answer directly.
   • Level 2 (Council Deliberation): Complex topics, subjective advice, code, or debates. Proceed to Pre-Research.
2. Pre-Research: If the topic is obscure/specific, use web search FIRST to gather a "Fact Brief."
3. Construct Prompt: Combine your research with the user's verbatim prompt so council members have ground truth to analyze. Never omit or paraphrase the user's original question.

Phase 1: Solicitation

1. Write Prompt to File: For complex prompts, write to a temp file first to avoid shell escaping issues:

   # Write the full prompt (your research + user's question)
   cat > /tmp/council_prompt.txt << 'PROMPT_EOF'
   [Your research brief here]
   
   === USER'S QUESTION (verbatim) ===
   [Exact user prompt here]
   PROMPT_EOF
   

2. Call Council: Use council-convene.sh with appropriate mode:

   ./skills/agents-and-council-of-llms/council-convene.sh \
     --prompt-file /tmp/council_prompt.txt \
     --lenses "Technical, Historical, Philosophical"
   

3. Guidance: You may append a "Chairman's Guidance" section to enforce constraints (e.g., "Focus on academic sources," "No moralizing").

Phase 2: The Review (Branch by Type)

1. Fact-Check: If models disagree on a fact, use web search to determine the truth immediately.
2. Consensus Check: If responses are unanimous or highly similar, skip to Phase 3. Only proceed to critique if there is significant disagreement.
3. Critique (If needed): Run council-review.sh on the resulting session directory.

Phase 3: The Verdict

1. Synthesis: Deliver a cohesive narrative based on the transcripts.
2. Adjudication: Explicitly state where you intervened (e.g., "Model A claimed X, but my verification search confirms Y...").
3. Log:
   • READ council_logs.org first (create if missing).
   • PREPEND the new entry to the top of the file.
   • WRITE the updated content back.

Model Configuration

Models are configured via (in priority order):

1. --models command-line argument
2. COUNCIL_MODELS environment variable
3. ~/.config/council/models.conf file
4. Hardcoded defaults

See README.md for detailed configuration instructions, including how to discover your available models with opencode models.

Example Configuration File

# ~/.config/council/models.conf
# One model per line, full opencode identifier
openrouter/openai/gpt-4o-mini
openrouter/anthropic/claude-3.5-haiku
openrouter/google/gemini-2.0-flash-001

Environment Variables

Variable	Description	Default
COUNCIL_MODELS	Comma-separated model list	(from config file)
COUNCIL_MODELS_FILE	Path to models config	~/.config/council/models.conf
COUNCIL_REVIEW_MODEL	Model for peer reviews	(first model in config)
COUNCIL_TIMEOUT	Timeout per model call (seconds)	120
COUNCIL_DEBUG	Set to 1 for verbose output	0

Secrets Management

• Preferred: Use skills/common/secrets.sh to load secrets from ~/.authinfo.gpg.
• Fallback: Ensure keys are in environment or .env (gitignored, chmod 600).

source skills/common/secrets.sh
# loads API keys automatically if configured

Troubleshooting

Prompt contains special characters or is very long

Use --prompt-file or --prompt-b64 instead of inline --problem:

# File method (recommended)
echo "Your complex prompt with 'quotes' and $variables..." > /tmp/prompt.txt
./council-convene.sh --prompt-file /tmp/prompt.txt --count 3

# Base64 method (single safe argument)
prompt_b64=$(cat /tmp/prompt.txt | base64 -w0)
./council-convene.sh --prompt-b64 "$prompt_b64" --count 3

Shell tool times out before completion

Council sessions typically take 30-90 seconds for 3 members running in parallel. High-reasoning models may take longer.

• Ensure your shell tool timeout is ≥120 seconds (preferably 300s)
• If timeout is not configurable, run the script manually in a terminal
• Consider using faster models (flash/mini variants)
• Set COUNCIL_TIMEOUT environment variable to adjust per-model timeout

"Model not found" errors

1. Run opencode models to see available models
2. Check the exact model identifier format (e.g., openrouter/provider/model-name)
3. Verify your API keys are configured in opencode

Some council members failed

Check individual output files in the session directory:

ls -la ./transcripts/YYYYMMDD_HHMMSS/
cat ./transcripts/YYYYMMDD_HHMMSS/Member_1.md

Files containing COUNCIL_ERROR: indicate failures. Common causes:

• Model rate limiting
• API key issues
• Model-specific content filtering

Debugging

Enable verbose output:

COUNCIL_DEBUG=1 ./council-convene.sh --problem "test" --count 2

Validate configuration before running

Use dry-run mode:

./council-convene.sh --problem "test" --lenses "A, B, C" --dry-run

Session Artifacts

Each council session creates a timestamped directory in ./transcripts/:

File	Description
metadata.txt	Session parameters (problem, lenses, models)
<Lens>_PROMPT.txt	Actual prompt sent to each member
<Lens>.md	Raw response from each member
FULL_TRANSCRIPT.md	Compiled transcript of all responses
review_key.txt	Anonymization key (after review)
<Reviewer>_REVIEW.md	Individual review outputs
PEER_REVIEW.md	Aggregated peer reviews