ghcp-llm-council 0.4.0

package/LICENSE

@@ -0,0 +1,42 @@
+MIT License
+
+Copyright (c) 2026 Vivekananda Gavini and ghcp-llm-council contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+================================================================================
+Third-party components bundled with this software
+================================================================================
+
+The frontend bundles two third-party libraries under their respective
+licenses. Their license texts and notices are reproduced verbatim in
+`skills/llm-council/server/public/vendor/LICENSES/`.
+
+* marked v12.0.0 — MIT License
+  Copyright (c) 2018+ MarkedJS, Copyright (c) 2011-2018 Christopher Jeffrey
+  See: skills/llm-council/server/public/vendor/LICENSES/marked-MIT.txt
+
+* DOMPurify v3.2.4 — Apache License 2.0 OR Mozilla Public License 2.0
+  Copyright (c) Cure53 and other contributors
+  See: skills/llm-council/server/public/vendor/LICENSES/Apache-2.0.txt
+       skills/llm-council/server/public/vendor/LICENSES/MPL-2.0.txt
+
+The original copyright notices in those minified files are preserved
+unchanged.
+

package/README.md

@@ -0,0 +1,221 @@
+<p align="center">
+  <img src="assets/logo.svg" width="80" alt="LLM Council" />
+</p>
+
+<h1 align="center">LLM Council</h1>
+
+<p align="center">
+  Multi-model deliberation for GitHub Copilot CLI.<br/>
+  Five models debate. One chairman synthesises. You watch it live.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/ghcp-llm-council"><img src="https://img.shields.io/npm/v/ghcp-llm-council?color=blue" alt="npm version" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node 20+" />
+  <a href="https://github.com/thevgavini/ghcp-llm-council/stargazers"><img src="https://img.shields.io/github/stars/thevgavini/ghcp-llm-council?style=social" alt="GitHub stars" /></a>
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> · <a href="#how-it-works">How it works</a> · <a href="#usage">Usage</a> · <a href="#configuration">Configuration</a> · <a href="#development">Development</a>
+</p>
+
+---
+
+## What is this?
+
+LLM Council is a **skill** (plugin) for [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli). Instead of getting one model's opinion, you get a structured debate between five frontier models — with peer review, anonymous ranking, and a chairman's synthesis.
+
+Think of it as a panel of senior engineers reviewing your question. Each brings a different perspective (Anthropic, OpenAI, Meta, DeepSeek, Mistral), they critique each other's answers without knowing who said what, and a chairman distils the best reasoning into one definitive response.
+
+Everything runs locally through your existing Copilot subscription and GitHub token. No extra API keys, no external services, no data leaving your machine beyond the model inference calls you're already making.
+
+## How it works
+
+```
+Question ──► 5 councillors answer in parallel (Stage 1)
+                    │
+                    ▼
+         Responses anonymised (A, B, C, D, E)
+                    │
+                    ▼
+         Each councillor ranks all responses (Stage 2)
+                    │
+                    ▼
+         Rankings aggregated (Borda count)
+                    │
+                    ▼
+         Chairman reads everything, writes synthesis (Stage 3)
+                    │
+                    ▼
+         Final answer ──► CLI + Browser UI + Disk
+```
+
+A local web UI shows every stage unfolding in real time. No external API keys required — uses your existing Copilot subscription and `gh auth` token.
+
+### Architecture
+
+<p align="center">
+  <img src="assets/architecture.svg" alt="System Architecture" width="100%" />
+</p>
+
+### Deliberation flow
+
+<p align="center">
+  <img src="assets/deliberation-flow.svg" alt="Deliberation Flow" width="100%" />
+</p>
+
+## Default council
+
+| Model | Vendor | Role | Backend |
+|-------|--------|------|---------|
+| Claude Sonnet 4.6 | Anthropic | Councillor | Copilot inference (`task`) |
+| GPT-5.2 | OpenAI | Councillor | Copilot inference (`task`) |
+| Llama 3.3 70B | Meta | Councillor | GitHub Models |
+| DeepSeek V3 | DeepSeek | Councillor | GitHub Models |
+| Mistral Medium 2505 | Mistral | Councillor | GitHub Models |
+| **Claude Opus 4.7** | **Anthropic** | **Chairman** | Copilot inference (`task`) |
+
+Two inference paths, zero extra credentials:
+- **`task` backend** — models dispatched through Copilot's built-in inference (your subscription covers it)
+- **`github-models` backend** — models called via `models.github.ai` using your `gh auth token`
+
+## Install
+
+### One-liner (npx)
+
+```bash
+npx ghcp-llm-council install
+```
+
+### Manual
+
+```powershell
+# 1. Install GitHub CLI (if you don't have it)
+winget install GitHub.cli
+
+# 2. Authenticate (required for model inference)
+gh auth login
+
+# 3. Clone and install the skill
+git clone https://github.com/thevgavini/ghcp-llm-council.git
+cd ghcp-llm-council
+.\install-skill.ps1
+```
+
+### Uninstall
+
+```bash
+npx ghcp-llm-council uninstall
+```
+
+Restart your Copilot CLI session after installing. Requires Node 20+ and GitHub Copilot CLI.
+
+## Usage
+
+In any Copilot CLI session:
+
+```
+ask the council: should we use a monorepo or polyrepo for our microservices?
+```
+
+The skill:
+1. Asks you to pick a mode (general, review, design, plan, research)
+2. Spins up a local server, opens the browser UI
+3. Dispatches all councillors in parallel
+4. Runs peer review + ranking
+5. Chairman synthesises a final answer
+6. Returns the synthesis in chat and persists to disk
+
+### Follow-ups
+
+```
+follow up: what about the CI/CD complexity tradeoff?
+```
+
+Runs a fresh 3-stage deliberation on the existing conversation thread.
+
+### File context
+
+```
+council: review src/auth.cjs for security holes
+```
+
+The skill auto-detects file references and passes them to every councillor inline.
+
+## Modes
+
+| Mode | Best for | Trigger words |
+|------|----------|---------------|
+| `general` | Open Q&A, opinions, explanations | _(default)_ |
+| `review` | Code review, security audit | "review", "audit", "find bugs" |
+| `design` | Architecture decisions, tech choices | "design", "should I use X or Y" |
+| `plan` | Implementation roadmaps | "plan", "roadmap", "how would you build" |
+| `research` | Deep dives, learning | "explain", "how does X work" |
+
+Each mode has tuned prompts for councillors and chairman. Mode packs can override the council lineup (e.g., `review` mode uses Opus as both councillor and chairman).
+
+## Configuration
+
+Defaults: `skills/llm-council/defaults/council.json`  
+Per-project override: `<cwd>/.llm-council/state/council.json`
+
+```json
+{
+  "council": [
+    {"id": "claude-sonnet-4.6", "vendor": "Anthropic", "display": "Claude Sonnet 4.6", "backend": "task"},
+    {"id": "gpt-5.2",           "vendor": "OpenAI",    "display": "GPT-5.2",           "backend": "task"},
+    {"id": "meta/llama-3.3-70b-instruct", "vendor": "Meta", "display": "Llama 3.3 70B", "backend": "github-models"}
+  ],
+  "chairman": "claude-opus-4.7",
+  "chairman_backend": "task",
+  "min_responses_to_proceed": 2,
+  "councillor_timeout_seconds": 120
+}
+```
+
+Add any model supported by Copilot inference or GitHub Models. The council scales to any size.
+
+## Project structure
+
+```
+skills/llm-council/
+├── SKILL.md              # Agent instructions (the skill contract)
+├── bin/council.cjs       # CLI helper (init, patch, advance, synthesize)
+├── server/               # Zero-dependency HTTP + WebSocket server
+│   ├── start.cjs         # Entry point
+│   └── public/           # Browser UI (vanilla JS, live cards)
+├── defaults/council.json # Default model lineup
+└── prompts/              # Mode-specific prompt templates
+    ├── general/          # councillor.md + chairman.md
+    ├── review/
+    ├── design/
+    ├── plan/
+    └── research/
+```
+
+State lives in `<cwd>/.llm-council/` — add to `.gitignore`.
+
+## Development
+
+```bash
+node skills/llm-council/server/start.cjs   # Launch server standalone for UI dev
+node skills/llm-council/server/stop.cjs    # Tear down
+```
+
+Tests live on the `tests/suite` branch:
+
+```bash
+git checkout tests/suite
+npm test
+```
+
+## Inspired by
+
+[karpathy/llm-council](https://github.com/karpathy/llm-council) — the original multi-model deliberation concept. This project brings it into the Copilot CLI ecosystem with live visualisation, zero external credentials, domain-specific modes (review, design, plan, research) with tuned prompts, and a skill-native interface that runs entirely from your terminal.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+Bundles [marked](https://github.com/markedjs/marked) (MIT) and [DOMPurify](https://github.com/cure53/DOMPurify) (Apache-2.0 / MPL-2.0) in the frontend. Full notices in [`server/public/vendor/LICENSES/`](skills/llm-council/server/public/vendor/LICENSES/).

package/bin/install.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL_NAME = 'llm-council';
+
+function main() {
+  const command = process.argv[2] || 'install';
+
+  if (command === '--help' || command === '-h') {
+    console.log(`
+  ghcp-llm-council — Multi-model deliberation skill for GitHub Copilot CLI
+
+  Usage:
+    npx ghcp-llm-council install    Install the skill (default)
+    npx ghcp-llm-council uninstall  Remove the skill
+    npx ghcp-llm-council --help     Show this help
+`);
+    process.exit(0);
+  }
+
+  if (command === 'uninstall') {
+    uninstall();
+  } else {
+    install();
+  }
+}
+
+function getSkillDest() {
+  const home = os.homedir();
+  return path.join(home, '.copilot', 'skills', SKILL_NAME);
+}
+
+function install() {
+  const source = path.resolve(__dirname, '..', 'skills', SKILL_NAME);
+  const destRoot = path.join(os.homedir(), '.copilot', 'skills');
+  const dest = path.join(destRoot, SKILL_NAME);
+
+  if (!fs.existsSync(source)) {
+    console.error(`\x1b[31mError: Source skill not found at: ${source}\x1b[0m`);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(destRoot, { recursive: true });
+
+  if (fs.existsSync(dest)) {
+    console.log('\x1b[33mReplacing existing installation...\x1b[0m');
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+
+  console.log(`\x1b[36mInstalling '${SKILL_NAME}' skill...\x1b[0m`);
+  copyDirSync(source, dest);
+
+  console.log(`\x1b[32m✓ Installed to: ${dest}\x1b[0m`);
+  console.log('\x1b[36mRestart your Copilot CLI session, then say: ask the council <your question>\x1b[0m');
+}
+
+function uninstall() {
+  const dest = getSkillDest();
+
+  if (!fs.existsSync(dest)) {
+    console.log('\x1b[33mSkill not installed — nothing to remove.\x1b[0m');
+    process.exit(0);
+  }
+
+  fs.rmSync(dest, { recursive: true, force: true });
+  console.log(`\x1b[32m✓ Removed skill from: ${dest}\x1b[0m`);
+}
+
+function copyDirSync(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "ghcp-llm-council",
+  "version": "0.4.0",
+  "description": "A GitHub Copilot CLI skill that runs your question past a council of LLMs — multi-model deliberation with live UI.",
+  "author": "Vivekananda Gavini",
+  "license": "MIT",
+  "type": "commonjs",
+  "engines": { "node": ">=20" },
+  "bin": {
+    "ghcp-llm-council": "./bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "github-copilot",
+    "copilot-cli",
+    "copilot-skill",
+    "llm",
+    "multi-model",
+    "ai-council",
+    "deliberation",
+    "claude",
+    "gpt",
+    "llama",
+    "deepseek",
+    "mistral"
+  ],
+  "scripts": {
+    "start": "node skills/llm-council/server/start.cjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thevgavini/ghcp-llm-council.git"
+  },
+  "homepage": "https://github.com/thevgavini/ghcp-llm-council#readme",
+  "bugs": {
+    "url": "https://github.com/thevgavini/ghcp-llm-council/issues"
+  }
+}

package/skills/llm-council/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: llm-council
+description: MUST USE whenever the user asks the council, asks a panel of LLMs, requests multiple model opinions on a question, says "ask the council", "council take", "get the council to weigh in", or wants several models to deliberate. Runs a 3-stage deliberation (parallel first opinions, anonymised peer review, chairman synthesis) and shows it live in a local web UI.
+---
+
+# llm-council
+
+A panel of LLMs deliberates on the user's question across three stages — independent first opinions, anonymised peer review, and a chairman's synthesis — visualised live in a local web UI.
+
+## When to use
+
+Use this skill when the user:
+
+- Says "ask the council X", "council: X", "get a council take on X", "multi-model opinion on X".
+- Explicitly asks for several models to weigh in on a hard or judgment-heavy question.
+- Says "follow up: X" or "ask the council a follow-up: X" — treat as a follow-up to the most recent conversation.
+
+Do not use this skill for:
+
+- Routine single-opinion questions.
+- Tool-using tasks (code editing, file reading, command execution) — councillors are constrained to answer from their own knowledge only.
+
+## The contract: you MUST complete all 3 stages before responding to the user
+
+The single most common failure mode of this skill is the agent declaring "council convened" and stopping without actually running the deliberation. **Do not do this.** Every invocation must run all three stages end-to-end. The user is watching a browser UI; if you stop early, they see empty thinking-state cards forever.
+
+## How it works — every step uses one helper
+
+You do not compose HTTP calls or write to files directly. Use the bundled helper:
+
+```
+node <skill_dir>/bin/council.cjs <subcommand> [--flags]
+```
+
+`<skill_dir>` is the directory containing this `SKILL.md`. Every helper subcommand prints a single JSON line on stdout (success object or `{"error":"..."}`). Multi-line text payloads (councillor responses, ranker outputs, synthesis) are read from **stdin** to avoid shell escaping issues.
+
+## Two backends per councillor
+
+Each councillor (and the chairman) has a `backend` field:
+
+- **`task`** — dispatched by you via the `task` tool with `model` set to the councillor's `id`. Use this for Anthropic + OpenAI models exposed through ghcp CLI. No extra credentials needed (uses the user's Copilot inference).
+- **`github-models`** — dispatched via the helper's `call` subcommand, which posts to `models.github.ai/inference/chat/completions` using the user's `gh auth token`. No extra credentials beyond `gh auth login`. Use this for Meta Llama, DeepSeek, Mistral, Microsoft Phi, Cohere — vendors NOT exposed through `task`.
+
+The default council mixes both backends. Inspect the `council` array from `init`'s output: each entry has `id`, `vendor`, `display`, `backend`.
+
+## Modes — pick the right prompt set for the question
+
+Five modes are available; each ships its own `councillor` and `chairman` prompts tuned for the question shape:
+
+| Mode | Use when the user asks for… | Triggering language |
+|---|---|---|
+| `general` (default) | Open-ended Q&A, explanations, opinions | "ask the council X" with no other framing |
+| `review` | Code or change review, security analysis | "review", "audit", "what's wrong with this code", "find bugs in", "security check" |
+| `design` | Architecture or technology choice | "design", "should I use X or Y", "what's the best approach for", "architecture for" |
+| `plan` | Step-by-step implementation roadmap | "plan", "roadmap", "how would you build", "implementation plan for" |
+| `research` | Learn about a topic; explain without recommending | "explain", "how does X work", "what is the state of", "deep dive into" |
+
+### MANDATORY: pre-flight mode confirmation in the CLI
+
+Before calling `init`, **you must offer the user a mode choice using the `ask_user` tool** so they can pick from a list without typing. Don't skip this even if the question seems obvious — the user might disagree with your read.
+
+1. Classify the user's question into one of the five modes using the triggering language above. When the question doesn't fit any specialist mode, recommend `general`.
+2. Use the `ask_user` tool with a `choices` array. Put the recommended mode first with "(Recommended)" appended. Example:
+
+   ```
+   question: "Which council mode for this question?"
+   choices: ["design (Recommended)", "general", "review", "plan", "research"]
+   ```
+
+3. Map the user's selection to the mode name (strip the "(Recommended)" suffix if present). If the user provides freeform text that isn't a mode name, treat it as a clarification of the question — re-classify and ask again.
+
+4. Once confirmed, proceed to Step 0 with `--mode <chosen>`.
+
+For follow-ups (`follow up: ...`), skip this step — the conversation already has a mode and the helper inherits it automatically. If the user explicitly says "follow up but as X", pass `--mode X` on `follow-up`.
+
+## File context — `--files` on init / follow-up
+
+When the question is about specific code (especially in `review` mode), pass the files directly so every councillor sees the same source:
+
+```
+node <skill_dir>/bin/council.cjs init --mode review --files src/auth.cjs,src/middleware.cjs --question "Review these for security holes"
+```
+
+The helper reads each file, caps it at 50 KB (200 KB total across all `--files`), prepends a `--- FILE: <path> ---` block to the question, and stores the augmented question. The councillors then see the file contents inline. Don't paste files into the question text yourself — let the helper do it so size caps and the file-block framing are consistent.
+
+If the user mentioned filenames in their question (e.g., "review src/auth.cjs"), grep them out and pass them via `--files` automatically — don't make the user re-type them.
+
+## The mandatory loop
+
+### Step 0 — Initialise
+
+```
+node <skill_dir>/bin/council.cjs init --question "<the user's exact question>" [--mode review|design|plan|research|general] [--files path1,path2,...]
+```
+
+Parse JSON output: `url`, `conversation_id`, `turn_id`, `mode`, `prompts_dir`, `council`, `chairman`, `chairman_backend`, `councillor_timeout_seconds`, `min_responses_to_proceed`.
+
+Tell the user once: **"Council convened at \<url\>. Watch live as the deliberation unfolds."**
+
+> If the user said "follow up", use `follow-up --question "..." --cid <previous conversation id>` instead.
+
+### Step 1 — First opinions
+
+**For each councillor in `council`, do one of two things based on its `backend`:**
+
+**Backend = `task`** (parallel, agent-driven):
+- Dispatch a `task` sub-agent in **background** mode.
+- `model` = the councillor's `id`. `agent_type` = `general-purpose`.
+- `prompt` = entire contents of `<skill_dir>/<prompts_dir>/councillor.md` + a blank line + the user's exact question (where `<prompts_dir>` came from init's output, e.g. `prompts/review`).
+- Group all `task`-backend councillor dispatches in a single response (parallel tool calls).
+
+**Backend = `github-models`** (synchronous, helper-driven):
+- For each one, run (on Windows PowerShell):
+  ```powershell
+  $prompt = (Get-Content <skill_dir>/<prompts_dir>/councillor.md -Raw) + "`n`n" + $userQuestion
+  $resp   = $prompt | node <skill_dir>/bin/council.cjs call --backend github-models --model <councillor.id>
+  ```
+- On bash / zsh:
+  ```bash
+  printf '%s\n\n%s' "$(cat <skill_dir>/<prompts_dir>/councillor.md)" "$userQuestion" \
+    | node <skill_dir>/bin/council.cjs call --backend github-models --model <councillor.id>
+  ```
+- The helper prints the response text on stdout (latency metadata on stderr).
+- These can be run sequentially (each takes 1-4s).
+
+**As each councillor's response arrives (task or github-models), immediately PATCH the server:**
+
+```powershell
+$response | node <skill_dir>/bin/council.cjs patch-councillor `
+  --tid <turn_id> --cid <conversation_id> `
+  --id <councillor_id> --status ok --latency-ms <elapsed>
+```
+
+If a councillor times out, returns garbage, or errors, PATCH with `--status timeout|error|empty` and pipe the error message to stdin.
+
+Once `min_responses_to_proceed` councillors have succeeded, advance:
+
+```
+node <skill_dir>/bin/council.cjs advance --tid <turn_id> --cid <conversation_id> --stage 2
+```
+
+If fewer than `min_responses_to_proceed` succeed, advance to `--stage -1`, tell the user, and stop.
+
+### Step 2 — Anonymised peer review
+
+Build label map: `Response A` → 1st surviving councillor's id, `Response B` → 2nd, etc.
+
+```
+node <skill_dir>/bin/council.cjs set-label-map --tid <turn_id> --cid <conversation_id> --map '{"Response A":"claude-sonnet-4.6", "Response B":"gpt-5.2", ...}'
+```
+
+**For each surviving councillor (acting as a ranker), dispatch in its native backend** (same task vs github-models split):
+
+The ranker prompt is `<skill_dir>/prompts/ranker.md` (shared across modes — the anonymised ranking process is the same regardless of question type) with `{{QUESTION}}` and `{{RESPONSES}}` substituted (responses labelled A, B, C, D etc joined by blank lines).
+
+As each ranking returns:
+
+```powershell
+$rankingText | node <skill_dir>/bin/council.cjs patch-ranking `
+  --tid <turn_id> --cid <conversation_id> `
+  --ranker <model_id>
+```
+
+(The helper parses `FINAL RANKING:` automatically.)
+
+Once all rankings are in:
+
+```
+node <skill_dir>/bin/council.cjs aggregate --tid <turn_id> --cid <conversation_id>
+```
+
+### Step 3 — Chairman synthesis
+
+Single dispatch using `chairman` + `chairman_backend` from init's output.
+
+The chairman prompt is `<skill_dir>/<prompts_dir>/chairman.md` (mode-specific, from init's output) with `{{QUESTION}}`, `{{STAGE1}}` (each councillor's response prefixed `Model: <id>\nResponse: <text>\n\n`), and `{{STAGE2}}` (each ranker's raw text prefixed `Model: <id>\nRanking: <raw>\n\n`).
+
+If `chairman_backend == task`, dispatch a `task` sub-agent. If `github-models`, use the `call` helper.
+
+When the chairman returns:
+
+```powershell
+$synthesis | node <skill_dir>/bin/council.cjs synthesize `
+  --tid <turn_id> --cid <conversation_id> `
+  --model <chairman_id>
+```
+
+### Step 4 — Respond to the user
+
+After Step 3, tell the user:
+
+> "Synthesis ready at \<url\>. Final answer below."
+
+Then paste the chairman's synthesis as markdown in the chat.
+
+**You are NOT done before this step.**
+
+## Follow-ups
+
+When the user says "follow up: X" or similar, treat as a new turn on the most recent conversation:
+
+```
+node <skill_dir>/bin/council.cjs follow-up --question "X" --cid <previous_conversation_id>
+```
+
+Then run Steps 1–4 exactly as above. Each turn is independent — councillors do not see prior turns' content. (This matches Karpathy's reference design.)
+
+## Reading browser-side events (optional, advanced)
+
+If you want to support a future browser-initiated input mode, you can periodically read the events file:
+
+```
+node <skill_dir>/bin/council.cjs read-events
+```
+
+Returns `{"events":[...]}` and drains the file atomically. The browser has no composer yet — this returns empty in normal operation; the subcommand is kept for future iteration.
+
+## Failure handling
+
+- **All councillors fail Stage 1.** Advance to `--stage -1` with an error PATCH on the turn. Tell the user; ask whether to retry.
+- **Some councillors fail.** Continue with survivors as long as `min_responses_to_proceed` is met. Browser shows failed cards with retry buttons (browser-initiated retry isn't wired up — the user can re-ask in the CLI).
+- **A ranker's text is unparseable** (no `FINAL RANKING:` section + no fallback matches). The helper's parser handles this — it returns an empty array, which the aggregator silently excludes. The raw text stays visible in the UI.
+- **Chairman fails.** Re-dispatch once. If it fails twice, synthesise a short notice ("Chairman failed; raw councillor responses and rankings are available above") and PATCH that as the synthesis text so the conversation can still persist.
+- **Server died mid-loop.** `init` will detect and restart on next call. For in-flight state loss, re-init with the same question (a duplicate conversation is acceptable; the user can delete from the sidebar later — that UX doesn't exist yet, so just acknowledge in chat).
+- **Config references a `task` model you don't support.** PATCH the councillor with `--status error` and a message; continue with the rest. Tell the user to edit `<cwd>/.llm-council/state/council.json` (or `<skill_dir>/defaults/council.json`).
+
+## Quick command reference
+
+| Helper | Purpose |
+|---|---|
+| `init --question "..." [--mode general\|review\|design\|plan\|research] [--files a,b,c]` | Start server (if needed), create conversation + turn, return ids + `mode` + `prompts_dir` + council config |
+| `follow-up --question "..." --cid <cid> [--mode ...] [--files ...]` | New turn on existing conversation; inherits the conversation's mode unless overridden |
+| `doctor [--deep] [--json] [--timeout-ms N]` | Probe every councillor + chairman. github-models backends get a real ping; task backends are listed as `~ skipped` (only the agent can probe those). Prints a table + a JSON sentinel. Run before init when diagnosing missing-councillor issues. |
+| `call --backend github-models --model <id> [--max-tokens N] [--timeout-ms N]` (stdin: prompt) | Synchronously call a GitHub Models model. Returns response text on stdout, `{latency_ms, usage}` on stderr |
+| `patch-councillor --tid X --cid Y --id <model> --status ok --latency-ms N` (stdin: response) | Push one councillor's response |
+| `advance --tid X --cid Y --stage N` | Transition turn to next stage |
+| `set-label-map --tid X --cid Y --map '{...}'` | Set anonymisation map |
+| `patch-ranking --tid X --cid Y --ranker <model>` (stdin: raw text) | Push one ranking; parser runs automatically |
+| `aggregate --tid X --cid Y` | Compute + PATCH aggregate rankings |
+| `synthesize --tid X --cid Y --model <chairman>` (stdin: synthesis md) | PATCH stage 3, persists to disk |
+| `read-events` | Drain browser-side events file (future use) |
+| `status` | Show server info + conversation count |
+
+## Per-session state lives under `<cwd>/.llm-council/`
+
+```
+.llm-council/
+  state/
+    server-info     (URL, port, pid)
+    server.pid
+    server.log
+    events          (JSONL, browser-side events for future use)
+    council.json    (runtime config override)
+  conversations/
+    <conv-id>.json  (persisted on PATCH stage:3)
+```