@statechange/council 0.1.0 → 0.2.0

package/README.md

@@ -1,124 +1,143 @@
 # @statechange/council
 
-A CLI + Electron GUI for orchestrating round-robin AI counsellor discussions. Build a council of AI personas — each with their own backend, model, personality, and source material — and have them debate topics in structured or freeform formats.
+Build a council of AI personas and have them debate any topic. Each counsellor has their own LLM backend, model, personality, and source material. Run discussions in a structured **debate** format or an open **freeform** group chat — via the CLI, an Electron GUI, or Claude Code skills.
 
-## Quick Start with Claude Code Skills
+## Getting Started with Claude Code Skills
 
-The fastest way to get started is through [Claude Code](https://claude.com/claude-code) skills. Install the package, and the skills handle the rest:
+The fastest path is to add the skills to [Claude Code](https://claude.com/claude-code). They handle installation, configuration, counsellor creation, and running discussions for you.
 
 ```bash
-npm install -g @statechange/council
+npx skills add statechangelabs/ai-council
 ```
 
-Then in Claude Code:
+This gives you two skills:
 
-- **`/council-manage`** — Create counsellors, run discussions, manage your council. Ask it to "create a counsellor based on [person]" or "run a debate about [topic]".
-- **`/council-setup-keys`** — Find API keys scattered across your env files and shell profiles, then consolidate them into `~/.ai-council/config.json`.
+| Skill | What it does |
+|-------|-------------|
+| `/council-manage` | Create counsellors, run discussions, manage your council. Try: *"create a counsellor based on Warren Buffett"* or *"run a debate about whether AI should be open source"* |
+| `/council-setup-keys` | Finds API keys scattered across your env files and shell profiles, then imports them into `~/.ai-council/config.json` |
 
-The skills know how to use the CLI, create counsellors from source material, and troubleshoot configuration issues.
+The skills will install the `council` CLI automatically if it's not already on your system.
 
 ## Install
 
 ```bash
-# Global install (recommended for CLI use)
+# Global install (gives you the `council` command)
 npm install -g @statechange/council
 
-# Or run directly
+# Or run one-off without installing
 npx @statechange/council discuss "Should we adopt microservices?"
 ```
 
-## CLI Usage
+## CLI
+
+### Run a discussion
 
 ```bash
-# Run a freeform discussion (default)
+# Freeform (default) — open group chat, everyone sees everything
 council discuss "Should we pivot to enterprise?" --rounds 3
 
-# Run a structured debate
+# Debate — structured constructive/rebuttal format
 council discuss "Should AI be open source?" --mode debate --rounds 3
 
-# Use specific counsellors
+# Pick specific counsellors
 council discuss "Topic" --counsellors ./council/strategist ./council/critic
 
 # Topic from a file
 council discuss ./topics/architecture.md
+```
 
-# List available counsellors
-council list
+### Manage counsellors
 
-# View past discussions
-council history
-council history <id>
+```bash
+council list                                  # Show available counsellors
+council counsellor add ./path/to/counsellor   # Register from local directory
+council counsellor add https://github.com/user/counsellors.git  # From git
+council counsellor remove my-counsellor       # Unregister
 ```
 
-### Discussion Modes
+### View history
+
+```bash
+council history        # List past discussions
+council history <id>   # View a specific discussion
+```
 
-**Freeform** (default) — Open group chat. Every counsellor sees the full conversation history on every turn. The first speaker sets the tone and later speakers react.
+### Configure backends
 
-**Debate** — Structured argument with three key differences:
-1. **Round 1 (Constructive)**: Each counsellor argues their position based only on the question — no visibility into what others said.
-2. **Rebuttal rounds**: Counsellors see the constructives plus only the previous round. Speaker order is shuffled each round.
-3. **Interim summaries**: A brief secretary summary after each round, creating a running debate narrative.
+```bash
+council config show                    # See what's configured
+council config scan                    # Find API keys across your system
+council config scan ~/project/.env     # Scan additional paths
+council config import                  # Import discovered keys into config
+```
 
-### Options
+### All CLI options
 
 ```
---council, -c       Path to council directory (default: ./council/)
---counsellors       Specific counsellor directory paths (space-separated)
---rounds, -r        Number of discussion rounds (default: 2)
---mode, -m          freeform or debate (default: freeform)
---output, -o        Output directory (default: ./output)
---format, -f        md, json, or both (default: both)
---infographic, -i   Generate an infographic after discussion
+council discuss <topic> [options]
+
+  --mode, -m          freeform or debate (default: freeform)
+  --rounds, -r        Number of discussion rounds (default: 2)
+  --council, -c       Path to council directory (default: ./council/)
+  --counsellors       Specific counsellor directory paths (space-separated)
+  --output, -o        Output directory (default: ./output)
+  --format, -f        md, json, or both (default: both)
+  --infographic, -i   Generate an infographic after discussion
 ```
 
 ## GUI
 
-Launch the Electron app for a visual interface with real-time streaming, counsellor management, and discussion history:
+The Electron app gives you a visual interface with real-time streaming, point-and-click counsellor management, and full discussion history.
 
 ```bash
-# Development
-council-gui          # if installed globally
-# or from source:
+# From the cloned repo
+git clone https://github.com/statechangelabs/ai-council.git
+cd ai-council
+bun install
 bun run dev:gui
 ```
 
-The GUI includes:
-- Counsellor selection chips with health indicators
-- Freeform/Debate mode toggle with explanatory tooltips
-- Real-time streaming of counsellor responses
-- Round dividers and interim summaries in debate mode
-- Secretary summary with Excalidraw position diagrams
-- Infographic generation (OpenAI / Google)
-- Full discussion history with search
+### What you get
 
-## Configuration
+- **Discussion page** — Topic input with file attachments, counsellor selection chips, freeform/debate mode toggle, real-time streaming of responses, round dividers and interim summaries in debate mode, inject messages mid-discussion
+- **Counsellors page** — Browse, search, create, edit, and delete counsellors with a form editor or raw ABOUT.md editing; register external counsellors from local paths or git repos
+- **History page** — Browse past discussions, view full transcripts with round summaries, copy as markdown, generate infographics
+- **Settings page** — Configure API keys per backend, test connections, see available models
 
-### API Keys
+## Discussion Modes
 
-Backends need API keys (except Ollama which runs locally). Keys can come from:
+### Freeform
 
-1. **Environment variables**: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`
-2. **Config file**: `~/.ai-council/config.json`
-3. **`.env` file** in the project root
+The default. An open group chat where every counsellor sees the full conversation history on every turn. The first speaker sets the tone and later speakers react to what's been said. Counsellor order stays the same each round.
 
-Use the CLI to find and import keys:
+### Debate
 
-```bash
-council config show              # See what's configured
-council config scan              # Find keys in env files and shell profiles
-council config scan ~/project/.env  # Scan additional paths
-council config import            # Import discovered keys
-```
+A structured argument format designed to prevent pile-on and anchoring bias:
+
+1. **Round 1 — Constructive**: Each counsellor argues their position based *only* on the question. They can't see what anyone else said. Even a "critic" persona has to stand up their own argument first.
 
-Or configure in the GUI under Settings.
+2. **Rebuttal rounds (2+)**: Counsellors now see the constructive round plus *only* the previous rebuttal round — not the entire history. This keeps context growth bounded. Speaker order is shuffled each round so nobody is always first or last.
+
+3. **Interim summaries**: If a secretary is configured, a brief summary is generated after every round, tracking emerging agreements, disagreements, and shifts in position.
+
+## Configuration
+
+### API Keys
+
+Each backend needs an API key (except Ollama, which runs locally). Keys are resolved in order:
+
+1. `~/.ai-council/config.json` (managed by `council config import` or the GUI)
+2. Environment variables: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`
+3. `.env` file in the working directory
 
 ### Secretary
 
-Add a `secretary` block to `~/.ai-council/config.json` to enable post-discussion summaries and debate interim summaries:
+Enable post-discussion summaries (and debate interim summaries) by adding a `secretary` block to `~/.ai-council/config.json`:
 
 ```json
 {
-  "backends": { ... },
+  "backends": { "..." : "..." },
   "secretary": {
     "backend": "anthropic",
     "model": "claude-sonnet-4-5-20250929"
@@ -126,9 +145,18 @@ Add a `secretary` block to `~/.ai-council/config.json` to enable post-discussion
 }
 ```
 
+### Supported Backends
+
+| Backend | Default Model | API Key |
+|---------|--------------|---------|
+| anthropic | claude-sonnet-4-5-20250929 | `ANTHROPIC_API_KEY` |
+| openai | gpt-4o | `OPENAI_API_KEY` |
+| google | gemini-2.0-flash | `GOOGLE_API_KEY` |
+| ollama | llama3.2 | None (local) |
+
 ## Creating Counsellors
 
-Each counsellor is a directory with an `ABOUT.md` file:
+A counsellor is a directory containing an `ABOUT.md` file with YAML frontmatter and a system prompt:
 
 ```
 council/
@@ -137,7 +165,7 @@ council/
     avatar.jpg    # optional
 ```
 
-### ABOUT.md Format
+### ABOUT.md format
 
 ```markdown
 ---
@@ -151,55 +179,58 @@ avatar: "avatar.jpg"
 ---
 
 You are The Strategist. You sit on a council of experts and bring a
-strategic lens to every discussion...
+strategic lens to every discussion.
+
+When contributing:
+- Think about second and third-order effects
+- Consider offensive and defensive strategic positions
+- Ground your thinking in frameworks when relevant
+- Be direct and opinionated
+
+Keep your responses focused. Aim for 2-4 paragraphs per turn.
 ```
 
-### Supported Backends
+### Frontmatter fields
 
-| Backend | Default Model | API Key |
-|---------|--------------|---------|
-| anthropic | claude-sonnet-4-5-20250929 | `ANTHROPIC_API_KEY` |
-| openai | gpt-4o | `OPENAI_API_KEY` |
-| google | gemini-2.0-flash | `GOOGLE_API_KEY` |
-| ollama | llama3.2 | None (local) |
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Display name |
+| `description` | Yes | One-line summary of this counsellor's perspective |
+| `backend` | Yes | `anthropic`, `openai`, `google`, or `ollama` |
+| `model` | No | Specific model ID; uses backend default if omitted |
+| `temperature` | No | 0.0–2.0; higher = more creative (default varies by backend) |
+| `interests` | No | Tags shown in the UI |
+| `avatar` | No | Path to local image or URL |
 
-### Registering External Counsellors
+### Included counsellors
 
-```bash
-# From a local directory
-council counsellor add ./path/to/counsellor
+The package ships with three starter counsellors:
 
-# From a git repository
-council counsellor add https://github.com/user/my-counsellors.git
+| Counsellor | Backend | Perspective |
+|-----------|---------|-------------|
+| **The Strategist** | Anthropic (Haiku) | Strategic business advisor — positioning, growth, competitive advantage |
+| **The Creative** | Anthropic (Opus) | Lateral thinker — unexpected analogies, reframing, unconventional connections |
+| **The Critic** | Google (Gemini Flash) | Devil's advocate — stress-tests ideas, surfaces assumptions, finds failure modes |
 
-# List registered counsellors
-council counsellor list
+### Building counsellors from source material
 
-# Remove
-council counsellor remove my-counsellor
-```
+You can create counsellors based on real people or bodies of work by appending reference material below the system prompt. The `/council-manage` skill in Claude Code can automate this — ask it to *"create a counsellor based on [person or book]"* and it'll handle downloading source text, writing the system prompt, and assembling the ABOUT.md.
 
 ## Logging
 
-Errors are logged to `~/.ai-council/council.log` with timestamps, context, and full stack traces. Check this file when a counsellor fails to respond or a summary doesn't generate.
+Errors are logged to `~/.ai-council/council.log` with timestamps, context tags, and full stack traces. Check this file when a counsellor fails to respond or a summary doesn't generate.
 
 ## Development
 
 ```bash
-# Install dependencies
+git clone https://github.com/statechangelabs/ai-council.git
+cd ai-council
 bun install
 
-# CLI development
-bun run dev -- discuss "topic"
-
-# GUI development
-bun run dev:gui
-
-# Build CLI
-bun run build
-
-# Build GUI
-bun run build:gui
+bun run dev -- discuss "topic"     # CLI development
+bun run dev:gui                    # GUI development
+bun run build                      # Build CLI
+bun run build:gui                  # Build GUI
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statechange/council",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI + GUI for orchestrating round-robin AI counsellor discussions with structured debate and freeform modes",
   "type": "module",
   "license": "MIT",
@@ -19,7 +19,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/statechangelabs/council.git"
+    "url": "https://github.com/statechangelabs/ai-council.git"
   },
   "keywords": [
     "ai",

package/skills/council-manage/SKILL.md

@@ -206,7 +206,7 @@ council config import # Import found keys
 
 All of the above can also be done in the Electron GUI (requires cloning the repo):
 ```bash
-git clone https://github.com/statechangelabs/council.git && cd council
+git clone https://github.com/statechangelabs/ai-council.git && cd council
 bun install && bun run dev:gui
 ```
 - **Settings page**: Configure API keys, test connections, see available models