council

name	council
description	Multi-agent orchestration via xAI Grok models. Invoked when the user says "consult the council", "run a council", "ask the multi-agent", "council review", or when a task requires deep multi-perspective reasoning, architectural debate, code review, or creative divergence that benefits from parallel agent work. Returns a structured result envelope the main seat can parse and continue from.
metadata	{"author":"syntra","version":"2.1"}

Council — Multi-Agent Orchestration Skill

Purpose

The Council is a local multi-agent orchestration system that calls xAI Grok models through the /v1/responses API. It routes tasks to specialized personas, collects their output, optionally synthesizes a final verdict, posts results to Discord for human visibility, and hands a structured result envelope back to the calling OpenClaw seat so execution can continue without ambiguity.

When to Use This Skill

Use this skill when:

• The user explicitly asks to "consult the council", "run a council", or similar.
• A task benefits from multiple perspectives (architecture, code review, brainstorm).
• Deep, sustained reasoning is needed beyond what a single model pass provides.
• Creative divergence or "outside the box" thinking is requested.

Do NOT use this skill for:

• Simple lookups, quick fixes, or tasks a single model handles fine.
• Anything that does not benefit from multi-agent deliberation.

Architecture

council/
├── SKILL.md              ← You are here. Agent-facing instructions.
├── config.env            ← Environment variable template (copy to .env).
├── README.md             ← Human-facing documentation.
└── scripts/
    ├── config.py          ← Centralized configuration, env loading, validation.
    ├── bridge.py          ← xAI API wrapper. Handles auth, retry, response parsing.
    ├── conductor.py       ← Orchestrator. Routes, calls bridge, synthesizes, returns envelope.
    ├── discord.py         ← Discord delivery (webhook or OpenClaw CLI). Supplemental.
    ├── notify.py          ← Main-seat notification via OpenClaw CLI.
    ├── transcript.py      ← Markdown transcript generation.
    ├── validate.py        ← Pre-flight health check and dry-run script.
    └── logs/              ← Runtime logs (auto-created).

Operating Modes

The conductor supports two modes, selected via the --mode flag:

verdict (default)

Synchronous, single-round. One persona is selected based on task classification. The persona's response IS the council verdict. Best for most tasks.

deliberation

Multi-round with parallel execution and model diversity:

• Multiple personas each produce a response in parallel (cutting latency by ~3x).
• Supports model diversity via environment variables: you can specify different model versions per persona slot (e.g., workhorse uses grok-4-0709, creative uses grok-4.20-multi-agent-experimental-beta-0304, speed uses grok-4-1-fast-reasoning).
• The Conductor persona then synthesizes a final verdict from all inputs.
• Use for tasks that genuinely benefit from multiple viewpoints (architecture decisions, tradeoff analysis, creative brainstorming) where latency and model disagreement add value.

How to Invoke

Step 1 — Prepare context

If the user wants the council to review code or a document, read the relevant file(s) and include their content in the prompt string. The council has no filesystem access; everything it needs must be in the prompt.

Step 2 — Run the conductor synchronously

python3 ~/.openclaw/workspace/skills/council/scripts/conductor.py \
  --mode verdict \
  "Your detailed prompt here, including any code or context."

Or for multi-persona deliberation with parallel execution:

python3 ~/.openclaw/workspace/skills/council/scripts/conductor.py \
  --mode deliberation \
  "Your detailed prompt here."

Step 2a — Optional: Configure model diversity for deliberation

Set environment variables to override the model used for each persona in deliberation mode:

# Example: Use different model versions for each council member
COUNCIL_DELIBERATION_WORKHORSE_MODEL=grok-4-0709 \
COUNCIL_DELIBERATION_CREATIVE_MODEL=grok-4.20-multi-agent-experimental-beta-0304 \
COUNCIL_DELIBERATION_SPEED_MODEL=grok-4-1-fast-reasoning \
python3 ~/.openclaw/workspace/skills/council/scripts/conductor.py \
  --mode deliberation \
  "Your detailed prompt here."

Step 3 — Read the result envelope from stdout

The conductor prints a JSON result envelope as its LAST line of stdout. Everything before that line is human-readable progress output (ignore it for machine parsing). The envelope looks like:

{
  "status": "ok",
  "mode": "verdict",
  "routed_to": "workhorse",
  "model": "grok-4-0709",
  "transcript_path": "scripts/council_transcript_20260315_0700.md",
  "summary": "First 300 chars of the final output...",
  "verdict": "The full final output text from the council.",
  "discord_posted": true,
  "main_seat_notified": true
}

If an error occurred:

{
  "status": "error",
  "error": "Description of what went wrong.",
  "mode": "verdict",
  "routed_to": "workhorse"
}

Step 4 — Continue from the envelope

• If status is "ok", read verdict for the council's full output. Use it to answer the user, continue work, or feed into the next step.
• If status is "error", report the error to the user and suggest retrying or falling back to a direct approach.
• The transcript_path is relative to the skill directory. Read it if the user wants the full multi-persona transcript.
• Discord posting and main-seat notification happen automatically. They are supplemental visibility — do NOT wait for or depend on them.
• Prefer native Discord routing first: thread reply → channel send → forum post. Treat webhook as fallback only.

Critical Operating Rules

1. Run synchronously. Do not background the conductor process.
2. Treat stdout as the authoritative result. The JSON envelope on the last line is the machine-readable contract. Discord posts are for human eyes only.
3. Do not parse Discord for the council's output. Ever.
4. Include all context in the prompt. The council cannot read files, browse the web, or access OpenClaw tools. Inline everything it needs.
5. Prefer verdict mode unless the user explicitly asks for multi-persona deliberation or the task clearly benefits from it.
6. If the conductor fails, check validate.py output first:

   python3 ~/.openclaw/workspace/skills/council/scripts/validate.py
   

Personas

Persona	Model Slug	Strengths
WORKHORSE	grok-4.20-beta-0309-reasoning	Sustained technical reasoning, architecture, debug
CREATIVE	grok-4.20-multi-agent-beta-0309	Divergent thinking, novel ideas, creative chaos
SPEED	grok-4-1-fast-reasoning	Rapid answers, summaries, small fixes, lookups
CONDUCTOR	grok-4.20-multi-agent-beta-0309	Synthesis, final verdicts, tiebreaking

In verdict mode, the task classifier selects one persona. In deliberation mode, WORKHORSE, CREATIVE, and SPEED each respond in parallel, then CONDUCTOR synthesizes. Model diversity can be configured via environment variables as described above.

Environment Variables

All configuration is in config.env (or environment variables). Required:

• XAI_API_KEY — xAI API key. Also checks ~/.xai-key and ~/.openclaw/openclaw.json.

Optional (with sensible defaults):

• COUNCIL_DISCORD_THREAD_ID — Highest-priority native target: reply to a specific thread.
• COUNCIL_DISCORD_CHANNEL_ID — Next native fallback: post to this channel via OpenClaw CLI.
• COUNCIL_DISCORD_FORUM_ID — Last native fallback: create a forum post via OpenClaw CLI.
• COUNCIL_DISCORD_WEBHOOK_URL — Webhook fallback only when native Discord routing is unavailable or fails.
• COUNCIL_DISCORD_GUILD_ID — Discord guild ID.
• COUNCIL_DISCORD_MENTION_USER_ID — User to @mention in Discord posts.
• COUNCIL_DISCORD_DRY_RUN — Set to 1 to skip actual Discord posts.
• COUNCIL_OPENCLAW_DRY_RUN — Set to 1 to skip main-seat notification.
• COUNCIL_SESSION_ID — Preferred explicit OpenClaw session target when known.
• COUNCIL_OPENCLAW_AGENT — Default OpenClaw agent target when no session id is supplied (main by default).
• COUNCIL_LOG_LEVEL — debug, info, warning, error (default: info).
• COUNCIL_MAX_RETRIES — API retry count (default: 2).
• COUNCIL_API_TIMEOUT — Seconds to wait for xAI response (default: 180).
• COUNCIL_DELIBERATION_WORKHORSE_MODEL — Override model for workhorse in deliberation mode.
• COUNCIL_DELIBERATION_CREATIVE_MODEL — Override model for creative in deliberation mode.
• COUNCIL_DELIBERATION_SPEED_MODEL — Override model for speed in deliberation mode.