#!/usr/bin/env bash
# council.sh — Reference implementation for council orchestration.
#
# This script is NOT executed directly. It documents the orchestration
# logic the main agent follows when invoking the council skill.
#
# See references/prompts.md for all prompt templates.
#
# ─── PARAMETERS ────────────────────────────────────────────────────
#
# mode:   personality (default) | dp
# flow:   parallel (default) | sequential | debate
# rounds: 1 (default) | 2-5
# tier:   light (default) | medium | heavy
#
# ─── MODE SELECTION ────────────────────────────────────────────────
#
# personality: 3 advisors (Pragmatist, Visionary, Skeptic) + 1 Referee
#   - Best for opinion/judgment calls, strategy, brainstorming
#   - Diversity comes from personality lenses
#
# dp: 2 groups (D + P), each with Freethinker + Arbiter, + 1 Meta-Arbiter
#   - Best for problem-solving, technical design, generating approaches
#   - Diversity comes from structural cognitive style
#   - Group D = Deterministic (grounded, feasibility-first)
#   - Group P = Probabilistic (exploratory, reframing-first)
#
# ─── PERSONALITY MODE: PARALLEL FLOW ──────────────────────────────
#
# Single round (rounds=1):
#   1. Spawn 3 advisors in parallel (sessions_spawn, mode=run)
#   2. Collect all 3 outputs (push-based completion)
#   3. Spawn referee with all outputs
#   4. Deliver to user
#
# Multi-round (rounds=N):
#   1. ROUND 1: Spawn 3 advisors in parallel (opening position prompt)
#   2. Collect outputs
#   3. ROUND 2..N-1: Respawn all 3 in parallel (rebuttal prompt)
#      - Each gets: own prior output + all other advisors' prior output
#   4. Collect outputs each round
#   5. ROUND N: Respawn all 3 in parallel (final position prompt)
#      - Each gets: full debate transcript summary
#   6. Collect final outputs
#   7. Spawn referee with FULL debate transcript (all rounds)
#   8. Deliver to user
#
# ─── PERSONALITY MODE: SEQUENTIAL FLOW ───────────────────────────
#
# Single round (rounds=1):
#   1. Spawn advisor 1 → collect output
#   2. Spawn advisor 2 with advisor 1's output → collect
#   3. Spawn advisor 3 with advisor 1+2 outputs → collect
#   4. Spawn referee with all outputs
#
# Multi-round (rounds=N):
#   1. ROUND 1: Sequential as above
#   2. ROUND 2..N: Each advisor sees ALL prior round outputs
#   3. Spawn referee with full thread
#
# ─── PERSONALITY MODE: DEBATE FLOW ───────────────────────────────
#
# Always multi-round (min 2, default 3):
#   1. ROUND 1: Parallel opening takes
#   2. ROUND 2..N-1: Cross-rebuttals (parallel, each sees all others)
#   3. ROUND N: Final positions (parallel, full transcript)
#   4. Spawn referee with full debate + evolution notes
#
# ─── D/P MODE: PARALLEL FLOW ─────────────────────────────────────
#
# Single round (rounds=1):
#   1. Spawn D-Freethinker and P-Freethinker in parallel (ideation)
#   2. Collect both sets of ideas
#   3. Spawn D-Arbiter and P-Arbiter in parallel (assessment)
#      - D-Arbiter gets D ideas, P-Arbiter gets P ideas
#   4. Collect both shortlists
#   5. Spawn Meta-Arbiter with both group shortlists (merge)
#   6. Deliver to user
#
# Multi-round (rounds=N):
#   1. ROUND 1: Parallel ideation → parallel assessment → bridge packets
#      - Bridge = summary of shortlist, assumptions, risks, asks
#   2. ROUND 2..N: Each group receives other's bridge packet
#      - Freethinkers revise/extend ideas incorporating bridge info
#      - Arbiters re-evaluate with cross-group context
#   3. FINAL: Meta-Arbiter receives final shortlists from both groups
#   4. Deliver to user
#
# Subagent calls per run:
#   - Single round: 5 (2 freethinkers + 2 arbiters + 1 meta)
#   - Multi-round:  4N + 1 (2 freethinkers + 2 arbiters per round + 1 meta)
#
# ─── D/P MODE: SEQUENTIAL FLOW ───────────────────────────────────
#
# Single round (rounds=1):
#   1. Spawn D-Freethinker → collect ideas
#   2. Spawn D-Arbiter with D ideas → collect shortlist
#   3. Spawn P-Freethinker → collect ideas
#   4. Spawn P-Arbiter with P ideas → collect shortlist
#   5. Spawn Meta-Arbiter with both shortlists → deliver
#
# Note: Less useful for D/P mode since groups are independent.
# Parallel is the natural D/P flow. Sequential is supported but
# doesn't add much because groups don't see each other until the bridge.
#
# ─── MODEL TIER SELECTION ─────────────────────────────────────────
#
# light:  advisors=default, referee=default
# medium: advisors=default, referee=stronger (e.g. opus-tier)
# heavy:  advisors=stronger, referee=stronger
#
# For D/P mode:
# light:  freethinkers=default, arbiters=default, meta=default
# medium: freethinkers=default, arbiters=default, meta=stronger
# heavy:  freethinkers=stronger, arbiters=stronger, meta=stronger
#
# ─── SUBAGENT LABELING ────────────────────────────────────────────
#
# Personality mode:
#   Agent ids:
#     council-pragmatist
#     council-visionary
#     council-skeptic
#     council-referee
#   Labels can still be council-r{round}-{role} for bookkeeping, but sessions should target
#   the dedicated council agent ids above.
#
# D/P mode:
#   Agent ids:
#     council-d-freethinker
#     council-d-arbiter
#     council-p-freethinker
#     council-p-arbiter
#     council-meta-arbiter
#   Labels can still be council-r{round}-{group}-{role} for bookkeeping, but sessions should target
#   the dedicated council agent ids above.
#
# ─── ROLE-AWARE MODEL TIERING ─────────────────────────────────────
#
# light:
#   advisors/freethinkers/arbiters -> dedicated council role agents on litellm/gpt-5-mini
#   referee/meta-arbiter           -> dedicated synthesis agents on openai-codex/gpt-5.4
#
# medium:
#   advisors/freethinkers/arbiters -> dedicated council role agents on litellm/gpt-5-mini
#   referee/meta-arbiter           -> dedicated synthesis agents on openai-codex/gpt-5.4
#
# heavy:
#   preserve dedicated role agent ids; prefer strongest synthesis on referee/meta-arbiter.
#   Only override advisor models upward when the task is genuinely high-stakes or unusually complex.
#
# Principle: mission-specific synthesis gets the stronger model first; broad advisor diversity stays cheap
# unless the topic quality/risk clearly justifies escalation.
#
# Example sessions_spawn targeting:
#   sessions_spawn(... agentId="council-pragmatist" ...)
#   sessions_spawn(... agentId="council-referee" ...)
#   sessions_spawn(... agentId="council-meta-arbiter" ...)
#
# Single-round labels may still look like council-pragmatist / council-meta for readability,
# but the runtime target should be the dedicated council agent id.
#
# Canonical executable source of truth:
#   references/roster.json
#   scripts/council-plan.py
#
# Resolve mode+tier there first, then spawn using the returned agent ids/model overrides.
#
# ─── WORD COUNT GUIDANCE ──────────────────────────────────────────
#
# Personality mode:
#   Round 1 (opening):  200-400 words
#   Middle rounds:      200-300 words
#   Final round:        150-250 words
#
# D/P mode:
#   Freethinker:  3-5 ideas, 100-200 words each
#   Arbiter:      Scored shortlist, 50-100 words per idea evaluation
#   Meta-Arbiter: 300-500 words total synthesis
#
# This keeps multi-round debates from exploding in token cost.