council

External AI Council

Orchestrate multiple external AI consultants to provide thorough, consensus-driven feedback on plans, code, and architectural decisions.

Pre-Flight Checks (MANDATORY)

Before invoking any consultant, verify:

# Check CLI availability — codex is independent, but omp now gates 3 of the 4
# external consultants (Gemini, GLM, Kimi), not just one
command -v codex >/dev/null 2>&1 || echo "WARN: codex CLI not found"
command -v omp >/dev/null 2>&1 || echo "WARN: omp CLI not found (needed for Gemini, GLM, and Kimi)"

If any CLI is missing, inform user and proceed with available consultants only.

Rate Limit Handling

External CLIs may hit rate limits. Handle gracefully:

| Scenario | Detection | Action | |----------|-----------|--------| | Rate limited | CLI returns 429 or "rate limit" error | Wait 30s, retry once | | Repeated limits | 2+ rate limits from same CLI | Skip that consultant, proceed with others | | All rate limited | All CLIs rate limited | Abort with clear error, suggest waiting |

Retry Strategy

# Exponential backoff for rate limits
retry_with_backoff() {
  local max_retries=2
  local delay=30
  for i in $(seq 1 $max_retries); do
    "$@" && return 0
    echo "Rate limited, waiting ${delay}s..."
    sleep $delay
    delay=$((delay * 2))
  done
  return 1
}

Staggered Launch (if rate limits frequent)

Instead of all 4 simultaneously, stagger by 5 seconds:

t=0s:  Launch Gemini
t=5s:  Launch Codex
t=10s: Launch GLM
t=15s: Launch Kimi

Available Consultants

External Consultants (Model Diversity)

Invoked via CLI. Each brings a different AI model's perspective. All receive the same prompt for consensus.

| Agent | CLI | Strength | Expertise Weight | |-------|-----|----------|------------------| | council:gemini-consultant | omp -p --no-tools --model google-antigravity/gemini-3.7-flash | Architecture, security | Security: 0.9, Architecture: 0.85 | | council:codex-consultant | codex | PR review, bugs | Debugging: 0.9, Security: 0.8 | | council:glm-consultant | omp -p --no-tools --model zai/glm-5.3:max | Alternative views, algorithms | Algorithms: 0.85, Architecture: 0.80 | | council:kimi-consultant | omp -p --no-tools --model kimi-code/k3 | Code analysis, algorithms | Code Quality: 0.80, Algorithms: 0.80 |

Claude Subagents (Concern Depth — Review Workflows Only)

Invoked via Task tool. Each has a different concern and native codebase access (Read, Grep, Glob, Bash).

| Agent | Model | Concern | Unique Capability | |-------|-------|---------|-------------------| | council:claude-deep-review | opus | Security, bugs, performance | Traces input paths, follows call chains, profiles hot paths | | council:claude-codebase-context | sonnet | Quality, compliance, history, documentation | Reads CLAUDE.md rules, greps codebase patterns, runs git blame |

Dual-Layer Architecture (Review Workflows)

┌─────────────────────────────────────────────────────────────────┐
│                     /council review                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Layer 1: External Consultants (PARALLEL)                       │
│  ┌──────────┬──────────┬──────────┬──────────┐                  │
│  │ Gemini   │ Codex    │ GLM      │ Kimi     │                  │
│  │ (same    │ (same    │ (same    │ (same    │                  │
│  │  prompt) │  prompt) │  prompt) │  prompt) │                  │
│  └──────────┴──────────┴──────────┴──────────┘                  │
│   ← Same prompt │ ← Model diversity │ ← Consensus               │
│                                                                 │
│  Layer 2: Claude Subagents (PARALLEL)                           │
│  ┌────────────────────────────┬────────────────────────────┐    │
│  │ Deep Review                │ Codebase Context           │    │
│  │ (opus)                     │ (sonnet)                   │    │
│  │ Security + Bugs + Perf     │ Quality + Compliance +     │    │
│  │ Read/Grep/Glob/Bash        │ History + Docs             │    │
│  │                            │ Read/Grep/Glob/Bash        │    │
│  └────────────────────────────┴────────────────────────────┘    │
│   ← Different concerns │ ← Native tool access │ ← Depth         │
│                                                                 │
│  Layer 3: Scoring                                               │
│  ┌─────────────────────────────────────────────────────┐        │
│  │ council:review-scorer (sonnet)                       │        │
│  │ Scores ALL findings from both layers 0-100          │        │
│  │ Filters at threshold (>= 80)                        │        │
│  └─────────────────────────────────────────────────────┘        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Both layers launch simultaneously — external consultants (4) and Claude subagents (2) run in parallel.

Blind Mode (--blind)

By default, Claude subagents use native tool access. With the --blind flag, they run via claude -p CLI instead — losing tool access but reviewing under the same constraints as external consultants.

/council review --blind    → Claude subagents invoked via CLI, no tool access
/council review            → Claude subagents invoked via Task, full tool access (default)

Use --blind when you want to compare Claude's blind opinion against its tool-assisted findings, or when you want all reviewers on equal footing.

Timeout and Failure Handling

Per-Consultant Timeout

• Default timeout: 120 seconds per consultant
• If timeout: Mark as failed, proceed with available responses

Partial Success Modes

| Available | Action | |-----------|--------| | 4/4 | Full synthesis | | 3/4 | Proceed with note: "[X] consultant unavailable" | | 2/4 | Proceed with warning: "Limited council - only 2 responses" | | 1/4 | Proceed in single-consultant mode with strong warning: "Single consultant only — no cross-model validation" | | 0/4 | Abort with error: "Council unavailable - all consultants failed" |

Structured Response Format

Each consultant MUST return structured output:

{
  "consultant": "gemini|codex|glm|kimi|claude-deep-review|claude-codebase-context",
  "success": true|false,
  "fallback": false,
  "confidence": 0.0-1.0,
  "severity": "critical|high|medium|low|none",
  "findings": [
    {
      "type": "security|performance|quality|architecture|bug|documentation",
      "severity": "critical|high|medium|low",
      "description": "...",
      "location": "file:line",
      "recommendation": "..."
    }
  ],
  "summary": "One-paragraph summary"
}

Location field: MANDATORY for code review findings (/council review). Must be file:line format (e.g. src/api.ts:42). Optional for non-code reviews (/council plan, /council adversarial, /council consensus).

Response Validation (Post-Collection)

After collecting each consultant's response, validate it before passing findings to scoring or synthesis. This is a mandatory workflow step, not an advisory check.

FOR each consultant response:
  1. Parse response as JSON
     IF parse fails:
       → mark success: false, reason: "invalid_response_format"
       → log: "{consultant}: INVALID — invalid_response_format"
       → SKIP to next consultant

  2. Check required top-level fields: consultant (string), success (boolean), findings (array), summary (string)
     IF any missing OR wrong type:
       → mark success: false, reason: "invalid_response_format", detail: "Missing or invalid required field: <field>"
       → log: "{consultant}: INVALID — Missing or invalid required field: <field>"
       → SKIP to next consultant

  2b. Normalize optional top-level fields used by quick-mode and scoring:
      - fa