Llm council

LLM Council

A deliberative council framework that integrates with gstack's specialist roles. Tiered Claude models act as named council members shaped by role and persona. Opus chairs — receiving a distilled brief, ruling, remanding for deeper analysis, or issuing conditional decisions. All sessions are committed to Obsidian as Congressional Records for longitudinal learning and agentic feedback loops.

---

Architecture

Problem Input
     │
     ▼
┌─────────────┐
│  DISPATCHER │  Sonnet — decomposes problem, assigns sub-questions to seats
└─────────────┘
     │
     ├──► Haiku Scouts (parallel subagents)   → gut checks, edge cases, devil's advocate
     ├──► Sonnet Analysts (parallel subagents) → domain depth, risk, implementation paths
     │
     ▼
┌──────────────────┐
│  CHAIRMAN BRIEF  │  Sonnet — compresses all output, preserves dissent
└──────────────────┘
     │
     ▼
┌──────────────┐
│  OPUS CHAIR  │  Rule → final decision
│              │  Remand → one targeted question back to Analyst
│              │  Conditional → path-dependent ruling
└──────────────┘
     │
     ▼
┌──────────────────────┐
│  OBSIDIAN LOG WRITER │  Appends Congressional Record to vault
└──────────────────────┘

---

Council Seats & Token Budget

Seat	Model	Role	Budget
Scout ×2	claude-haiku-4-5-20251001	Fast gut-checks, edge cases, adversarial takes	~300 tok each
Analyst ×2	claude-sonnet-4-6	Domain depth, risk surface, trade-off mapping	~800 tok each
Briefer	claude-sonnet-4-6	Compresses member output → Chairman Brief	~600 tok
Chairman	claude-opus-4-8	Rules, remands once, or issues conditional ruling	~1000 tok
Log Writer	claude-haiku-4-5-20251001	Formats and writes Obsidian record	~400 tok

Target total: ~4200 tokens per deliberation. On remand: add ~400 tok (Analyst) + ~200 tok (Brief append).

---

gstack Integration

The council is designed as a cross-cutting layer over gstack roles. It activates when a gstack phase produces a decision point requiring multi-perspective deliberation.

gstack Phase	When to invoke council
/office-hours	Idea has multiple viable directions; need structured pressure-test
/plan	Competing architectural approaches; need risk + domain analysis
/review	PR introduces non-obvious trade-offs or reversibility concerns
/qa	Test strategy has coverage gaps with different risk profiles
/ship	Deployment has conditional paths (rollback triggers, feature flags)
/retro	Post-sprint: deliberate on what to change vs. preserve

Model routing alignment with gstack: gstack already routes Sonnet for actions and Opus for analysis. The council extends this: Haiku scouts handle high-volume intake; Sonnet analysts handle structured reasoning; Opus chairs only the final synthesis. This mirrors gstack's benchmark-models philosophy.

---

Step 0 — Config Resolution

Resolve vaultPath and this skill's log/plan directory before doing anything else. Same 4-step order in every skill this plugin bundles (p10, llm-council, the-cabinet) — do not deviate, this consistency is what keeps the lookup unambiguous:

1. TOTO_VAULT_PATH env var, if set — always wins.
2. <plugin-root>/settings.local.json, if the plugin was installed via claude plugin add and the file exists.
3. Global ~/.claude/CLAUDE.md prose (the legacy convention — still honored, not removed).
4. Hardcoded default (~/.toto/vault), if nothing above resolved.

Print which source won (e.g. resolved vaultPath from: env TOTO_VAULT_PATH) before proceeding — this line is load-bearing, not cosmetic: without it, an env var silently shadowing a settings.local.json override becomes an invisible footgun.

First-run / no cached resolution beyond the hardcoded default: if there's an interactive session (TTY available), ask the user for vaultPath (and this skill's log/plan dir, if it differs from the default) via AskUserQuestion, then write the answer to <plugin-root>/settings.local.json (source #2 above) so future runs skip the prompt. If writing fails (e.g. read-only plugin dir), use the answered value for this run only and warn that the prompt will repeat next time.

No interactive session available (headless, CI, scripted claude plugin add): do NOT wait on AskUserQuestion — it has no path to a human here. Fall through to source #4 (hardcoded default) and emit a fail-loud stderr warning naming the exact remediation: set TOTO_VAULT_PATH=<path> or create <plugin-root>/settings.local.json before running in a non-interactive environment. Never proceed silently as if a value were confirmed when it wasn't.

---

Step 1 — Dispatch

Decompose the problem into 4 sub-questions (2 scout, 2 analyst). Rules:

Scout sub-questions:
  - "What could break about this in 6 months?"
  - "What's the simplest version that still works?"
  - "What assumption are we making that could be wrong?"
  - "What does the opposing view look like?"

Analyst sub-questions:
  - "What are the implementation trade-offs?"
  - "What's the risk surface: security, perf, ops burden, reversibility?"
  - "How does this behave at scale or under failure?"
  - "What does best practice / prior art say here?"

Never send the full problem raw. Decompose first, assign, then spawn.

Step 2 — Council Session (parallel subagents)

Each member receives: persona prompt + sub-question + minimal context (problem + constraints). Members may spawn Haiku context subagents to read files or run checks.

Step 3 — Chairman Brief (Sonnet)

Agent tool call: model: 'claude-sonnet-4-6', subagent_type: 'general-purpose'. Compressing 4 members' output into one brief while preserving dissent is synthesis, not search — general-purpose is the right fit here.

## Council Brief — [DECISION TITLE]
**Date:** [ISO date]
**Problem:** [one sentence]
**Stakes:** [what goes wrong if chosen poorly]
**gstack phase:** [which phase triggered this]

### Scout Findings
- [Skeptic]: ...
- [Minimalist]: ...

### Analyst Findings
- [Domain Expert]: ...
- [Risk Auditor]: ...

### Points of Agreement
[...]

### Points of Disagreement
[Preserve positions exactly — do not flatten or average]

### Open Questions for Chairman
[Unresolved items Opus should weigh in on]

Step 4 — Chairman Ruling (Opus)

Agent tool call: model: 'claude-opus-4-8', subagent_type: 'general-purpose'. Already correctly scoped to receive only the compressed brief, not raw member output — keep it that way, this is the cheapest tier to get wrong.

Opus receives only the brief. Three valid responses:

A) Rule:

## Chairman's Ruling
**Decision:** [clear, actionable]
**Reasoning:** [why this path]
**Conditions:** [what must hold]
**Dissent acknowledged:** [address disagreements directly]

B) Remand (once per deliberation):

## Remand Order
**To:** Analyst (Sonnet)
**Question:** [specific, scoped]
**Why:** [what this unlocks for the ruling]

After remand: Analyst responds (~400 tok), Briefer appends to brief, Opus rules.

C) Conditional Ruling:

## Chairman's Ruling (Conditional)
**If [condition A]:** [decision + reasoning]
**If [condition B]:** [decision + reasoning]
**Chairman's read:** [which condition likely applies and why]

---

Personas

Persona	Instruction
Skeptic	Find the failure mode. What breaks in 6 months? What's assumed away?
Minimalist	What's the smallest change that achieves the goal? Resist scope creep.
Domain Expert	Apply deep technical knowledge. What does best practice say?
Risk Auditor	Map the risk surface: security, perf, ops burden, reversibility.
Optimist	What's the best-case upside? What becomes possible if this works?
Pragmatist	What ships, what's maintainable, what the team can actually execute?

Default config: Scout 1 = Skeptic, Scout 2 = Minimalist, Analyst 1 = Domain Expert, Analyst 2 = Risk Auditor.

---

Prompt Templates

Scout prompt

You are a [PERSONA] on an engineering council. Answer concisely (3-5 sentences):

SUB-QUESTION: [question]
CONTEXT: [problem + constraints]

Stay in role. Be direct. If you need to read a file or run a check to answer well,
you may spawn a bash subagent (Haiku, max 2). Append findings to your response.

Analyst prompt

You are a [PERSONA] on an engineering council. Structured analysis (under 200 words):

SUB-QUESTION: [question]
CONTEXT: [problem + constraints]

Format:
- Finding: [main point]
- Evidence: [support or file reference]
- Trade-off: [what this costs or risks]
- Recommendation: [your seat's view]

You may spawn up to 2 Haiku subagents to read files or run checks. Append results.

Chairman prompt

You are the Chairman of an engineering council operating within a gstack engineering
environment. You have received the following council brief. Issue a ruling, remand once
for more information, or issue a conditional ruling.

[CHAIRMAN BRIEF]

Rules:
- Read the brief fully before responding.
- If you remand, be specific and scoped — not the whole problem.
- If you rule, be decisive. Acknowledge dissent and resolve it.
- If path-dependent, issue a conditional ruling with your read on which applies.
- Your decision should be the best engineering choice available.
- You may remand only once.

---

Obsidian Congressional Record

After every council session (ruling or conditional), the Log Writer (Haiku) appends a structured record to the Obsidian vault.

Vault configuration

Uses vaultPath and council.logDir (default Council/Congressional-Records) resolved in Step 0.

Record format

File: {vaultPath}/{council.logDir}/YYYY-MM-DD-{slug}.md

---
date: YYYY-MM-DD
session: [slug]
gstack_phase: [phase]
decision: [one-line summary]
chairman_action: ruled | remanded | conditional
models_used: [haiku×2, sonnet×3, opus×1]
tokens_spent: [approximate]
tags: [council, engineering, gstack, {domain-tag}]
---

# Council Session: [TITLE]

## Problem
[one paragraph]

## Council Composition
| Seat | Persona | Model |
|---|---|---|
...

## Key Findings
[bullet summary of scout + analyst outputs]

## Points of Disagreement
[preserved verbatim from brief]

## Chairman's Ruling
[full ruling text]

## Conditions & Follow-up
[any conditions stated, linked issues, next actions]

## Session Notes
[anything unusual: remand issued, context subagents used, gstack modules consulted]

Feedback loop mechanism

Records accumulate in Council/Congressional-Records/. A companion index file Council/INDEX.md is updated with each session (date, decision, outcome tag).

This enables:

• Auto-research: agentic sessions can query past rulings before new deliberations
• Pattern detection: /retro can surface recurring disagreements or reversed decisions
• Training signal: the record corpus can be used as fine-tuning or RAG context for future council sessions, progressively improving ruling quality

---

Token Guardrails

• Simple problem, one clear answer: skip council, answer directly
• Brief exceeds 800 tokens before Chairman: trim scout outputs first
• Remand Analyst response: cap at 400 tokens
• Log Writer: Haiku only, cap at 400 tokens
• Never send Chairman the raw thread — always the compressed brief

---

Output to User

1. Chairman's Ruling (verbatim)
2. Key dissent (if any — never buried)
3. Council summary (2-3 sentences: what scouts/analysts surfaced)
4. Obsidian record path (confirm log written)
5. Token spend (optional, useful for calibration)

---

When NOT to use this skill

• Factual lookups with no trade-off
• Tasks where speed > deliberation quality
• Problems already fully specified with one correct answer
• Casual / conversational exchanges
• gstack phases where a single specialist role is clearly sufficient