@statechange/council 0.1.0

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@statechange/council",
+  "version": "0.1.0",
+  "description": "CLI + GUI for orchestrating round-robin AI counsellor discussions with structured debate and freeform modes",
+  "type": "module",
+  "license": "MIT",
+  "main": "dist-electron/main.js",
+  "bin": {
+    "council": "./dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "council/creative/",
+    "council/critic/",
+    "council/strategist/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/statechangelabs/council.git"
+  },
+  "keywords": [
+    "ai",
+    "council",
+    "debate",
+    "llm",
+    "multi-agent",
+    "anthropic",
+    "openai",
+    "google",
+    "ollama",
+    "claude-code",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.tsx",
+    "start": "node dist/cli.js",
+    "dev:gui": "vite",
+    "build:gui": "vite build",
+    "package": "electron-builder",
+    "prepublishOnly": "tsc"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@excalidraw/excalidraw": "^0.18.0",
+    "@google/genai": "^1.43.0",
+    "@google/generative-ai": "^0.21.0",
+    "@lobehub/icons": "^4.6.0",
+    "autoprefixer": "^10.4.24",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "dotenv": "^16.4.0",
+    "glob": "^11.0.0",
+    "gray-matter": "^4.0.3",
+    "ink": "^5.0.1",
+    "ink-spinner": "^5.0.0",
+    "lucide-react": "^0.575.0",
+    "meow": "^13.2.0",
+    "ollama": "^0.5.0",
+    "openai": "^4.80.0",
+    "postcss": "^8.5.6",
+    "react": "^18.3.1",
+    "react-dom": "18",
+    "react-markdown": "^10.1.0",
+    "tailwind-merge": "^3.5.0",
+    "tailwindcss": "3",
+    "tailwindcss-animate": "^1.0.7",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "18",
+    "@vitejs/plugin-react": "^5.1.4",
+    "concurrently": "^9.2.1",
+    "electron": "^40.6.0",
+    "electron-builder": "^26.8.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.2",
+    "vite": "^7.3.1",
+    "vite-plugin-electron": "^0.29.0",
+    "vite-plugin-electron-renderer": "^0.14.6"
+  }
+}

package/skills/council-manage/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: council-manage
+description: Manage AI Council counsellors and discussions from the command line. Create, list, edit, and configure counsellors. Run discussions with topic selection and counsellor filtering. Use when the user wants to work with AI Council via CLI or needs help managing their council setup.
+license: MIT
+metadata:
+  author: ai-council
+  version: "1.0"
+---
+
+# Council Manage
+
+Manage AI Council counsellors and run discussions from the command line.
+
+## Installation
+
+If `council` is not already installed, install it globally from NPM:
+
+```bash
+npm install -g @statechange/council
+```
+
+Or run commands directly with `npx @statechange/council`.
+
+## When to Use
+
+- The user wants to create, edit, or delete a counsellor
+- The user wants to list their counsellors and check their status
+- The user wants to run a discussion from the CLI
+- The user asks about council configuration or troubleshooting
+
+## Counsellor Structure
+
+Each counsellor lives in a directory under the council path (default `./council/`), with an `ABOUT.md` file containing YAML frontmatter and a system prompt:
+
+```
+council/
+  my-counsellor/
+    ABOUT.md
+```
+
+### ABOUT.md Format
+
+```markdown
+---
+name: "Display Name"
+description: "One-line description of this counsellor's perspective"
+interests: ["topic1", "topic2", "topic3"]
+backend: "anthropic"          # anthropic | openai | google | ollama
+model: "claude-sonnet-4-5-20250929"  # optional, uses backend default if omitted
+temperature: 0.7              # 0.0 - 2.0, optional
+---
+
+You are [name], a [description of role and personality].
+
+[Detailed system prompt instructions...]
+```
+
+### Available Backends and Default Models
+
+| Backend | Default Model | Requires API Key |
+|---------|--------------|-----------------|
+| anthropic | claude-sonnet-4-5-20250929 | Yes (ANTHROPIC_API_KEY) |
+| openai | gpt-4o | Yes (OPENAI_API_KEY) |
+| google | gemini-2.0-flash | Yes (GOOGLE_API_KEY) |
+| ollama | llama3.2 | No (local) |
+
+## CLI Commands
+
+### List counsellors
+
+```bash
+council list
+council list --council ./path/to/council/
+```
+
+### Run a discussion
+
+```bash
+# Inline topic
+council discuss "Should we adopt microservices?"
+
+# Topic from file
+council discuss ./topics/architecture.md
+
+# With options
+council discuss "Topic" --rounds 3 --format md --output ./results
+
+# Specific counsellors only
+council discuss "Topic" --counsellors ./council/strategist ./council/critic
+```
+
+### Manage counsellor registry
+
+```bash
+# Register a counsellor from a local directory
+council counsellor add ./path/to/counsellor
+
+# Register counsellor(s) from a git repository
+council counsellor add https://github.com/user/some-counsellor.git
+
+# List all registered counsellors
+council counsellor list
+
+# Unregister a counsellor (--yes auto-deletes cloned files for git sources)
+council counsellor remove my-counsellor
+council counsellor remove my-counsellor --yes
+```
+
+Registered counsellors are stored in `~/.ai-council/config.json` under the `counsellors` key. Git-cloned counsellors are placed at `~/.ai-council/counsellors/<name>/`.
+
+URL detection: paths starting with `http://`, `https://`, or ending with `.git` are treated as git URLs; everything else is a local path.
+
+Multi-counsellor repos: if the cloned root has no `ABOUT.md`, child directories are scanned for counsellors.
+
+### Check configuration
+
+```bash
+council config show     # Show backend status
+council config scan     # Find API keys
+council config import   # Import found keys
+```
+
+## Creating a New Counsellor
+
+To create a new counsellor:
+
+1. Create a directory: `mkdir council/new-counsellor`
+2. Create `council/new-counsellor/ABOUT.md` with the frontmatter and system prompt
+3. Verify with `council list`
+
+### Building a Counsellor from Source Material
+
+When creating a counsellor based on a real person, historical figure, or body of work, the ABOUT.md should have three distinct layers:
+
+**Layer 1: Frontmatter** — identity and metadata:
+```yaml
+---
+name: "Display Name"
+description: "One-line summary of their perspective and what they bring to the council"
+interests: ["core-topic-1", "core-topic-2", "core-topic-3"]
+backend: "anthropic"
+temperature: 0.7
+avatar: "avatar.jpg"  # local file preferred; DiceBear URL as fallback for generic personas
+---
+```
+
+**Layer 2: System prompt** — the "who you are" section written directly after the frontmatter. This should:
+- Establish the persona: "You are [Name], [role]. You sit on a council of experts and bring [perspective]."
+- Define their **intellectual framework** as a structured list of 3-6 core principles or methods of analysis, each with a brief explanation
+- Provide **behavioral instructions** for how they should engage in discussion (what to emphasize, what to question, how to relate to other perspectives)
+- Set a **personality/style note** (e.g. rhetorically forceful, measured and empirical, provocative but grounded)
+- End with: "Keep your responses focused and substantive. Aim for 2-4 paragraphs per turn."
+
+**Layer 3: Reference material** — the bulk source text appended below. Separated by a markdown horizontal rule and a heading like `## Reference Material: [Title]`. Include a one-line instruction telling the counsellor to draw on this material. Then the full text.
+
+#### Build Process for Source-Material Counsellors
+
+Because pasting large reference texts directly into an LLM output can trigger content filtering, use a **concatenation approach**:
+
+1. **Download the source material** to a temp file:
+   ```bash
+   curl -o /tmp/source.txt "https://example.com/source-text"
+   ```
+
+2. **Write only the header** (frontmatter + system prompt + reference intro) to a temp file using the Write tool or a heredoc. This is the part you author — keep it under ~2KB.
+
+3. **Extract the relevant portion** of the source (e.g. strip Project Gutenberg headers/footers):
+   ```bash
+   sed -n '/START_MARKER/,/END_MARKER/p' /tmp/source.txt | sed '1d;$d' > /tmp/source-body.txt
+   ```
+
+4. **Concatenate** header + body into the final ABOUT.md:
+   ```bash
+   cat /tmp/header.md /tmp/source-body.txt > council/new-counsellor/ABOUT.md
+   ```
+
+This keeps the authored content (which goes through the LLM) small, and the bulk reference text is handled entirely through file operations.
+
+#### Tips
+
+- **Interests**: Pick 5-8 terms that reflect the counsellor's core domains. These appear as tags in the UI and help users understand what the counsellor brings.
+- **Avatar**: Prefer a real image of the person or what they're most associated with. For historical figures, authors, philosophers etc., download a public-domain portrait from Wikimedia Commons into the counsellor directory as `avatar.jpg` (use the Wikipedia API to find a thumbnail URL, then `curl -o council/<name>/avatar.jpg <url>`). Set `avatar: "avatar.jpg"` in frontmatter — relative paths are resolved automatically. Only fall back to DiceBear (`https://api.dicebear.com/9.x/personas/svg?seed=SlugHere&backgroundColor=hexWithoutHash`) for fictional or generic personas where no real image applies.
+- **Temperature**: 0.7 is a good default. Go higher (0.8-0.9) for creative/provocative thinkers, lower (0.5-0.6) for analytical/precise ones.
+- **Source material size**: The full Communist Manifesto (~77KB) works fine. Larger texts will too but may increase token costs per discussion turn. Consider excerpting if a source exceeds ~200KB.
+- **Multiple sources**: You can append several reference texts with separate `## Reference Material:` headings.
+- **Public domain sources**: Project Gutenberg (gutenberg.org) is a good source. Always strip the PG header/footer boilerplate.
+
+## Troubleshooting
+
+### Counsellor shows as red / has issues
+
+Usually means the backend API key is missing. Fix with:
+```bash
+council config show   # Check which keys are missing
+council config scan   # Look for keys
+council config import # Import found keys
+```
+
+### Discussion fails with backend errors
+
+1. Check the backend is configured: `council config show`
+2. For ollama: ensure `ollama serve` is running
+3. For cloud backends: verify the API key is valid and has credits
+
+## GUI Alternative
+
+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
+bun install && bun run dev:gui
+```
+- **Settings page**: Configure API keys, test connections, see available models
+- **Counsellors page**: Browse, create, edit, delete counsellors with a form editor
+- **Discussion page**: Start discussions with counsellor selection and real-time streaming

package/skills/council-setup-keys/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: council-setup-keys
+description: Find AI API keys scattered across env files, shell profiles, and project directories, then consolidate them into the AI Council config at ~/.ai-council/config.json. Use when setting up AI Council, when counsellors show missing API key errors, or when the user asks to configure backends.
+license: MIT
+metadata:
+  author: ai-council
+  version: "1.0"
+---
+
+# Council Setup Keys
+
+Find and consolidate AI API keys into the AI Council configuration.
+
+## Installation
+
+If `council` is not already installed, install it globally from NPM:
+
+```bash
+npm install -g @statechange/council
+```
+
+Or run commands directly with `npx @statechange/council`.
+
+## When to Use
+
+- The user asks to set up or configure AI Council
+- Counsellors are showing red / missing API key warnings
+- The user wants to find their API keys from other projects
+- The user says something like "find my keys", "setup my backends", or "configure API keys"
+
+## Steps
+
+### 1. Check current configuration status
+
+Run the config show command to see what's already configured:
+
+```bash
+council config show
+```
+
+This shows each backend (anthropic, openai, google, ollama) and whether it has a key from the config file or environment.
+
+### 2. Scan standard locations
+
+Run the built-in scanner to check env files and shell profiles:
+
+```bash
+council config scan
+```
+
+This searches:
+- `.env`, `.env.local`, `.env.development`, `.env.production` in the current directory
+- `~/.env`, `~/.bashrc`, `~/.bash_profile`, `~/.zshrc`, `~/.zshenv`, `~/.zprofile`, `~/.profile`
+- `~/.config/fish/config.fish`
+- Current process environment variables
+
+### 3. Search additional project directories
+
+The built-in scanner covers standard locations, but keys are often in project `.env` files. Search common project directories for any the scanner missed:
+
+```bash
+# Search for API key assignments in .env files across common directories
+grep -r "ANTHROPIC_API_KEY\|OPENAI_API_KEY\|GOOGLE_API_KEY\|GEMINI_API_KEY" \
+  ~/Documents/ ~/Projects/ ~/Code/ ~/Developer/ ~/repos/ ~/src/ \
+  --include=".env*" -l 2>/dev/null
+```
+
+If additional files are found, pass them to the scanner:
+
+```bash
+council config scan /path/to/found/.env /other/path/.env
+```
+
+### 4. Import discovered keys
+
+Once you've confirmed which keys are available, import them:
+
+```bash
+council config import
+```
+
+Or with additional paths:
+
+```bash
+council config import /path/to/extra/.env
+```
+
+This writes keys to `~/.ai-council/config.json`, skipping any backend that already has a key configured.
+
+### 5. Verify the result
+
+Run show again to confirm all backends are configured:
+
+```bash
+council config show
+```
+
+### 6. Report to the user
+
+Tell the user:
+- Which backends are now configured
+- Which backends are still missing keys (and what env var or key they need)
+- That they can also configure keys in the Electron GUI under Settings
+- For ollama: no key needed, just ensure ollama is running locally
+
+## Key Environment Variables
+
+| Backend | Env Variable | Key Prefix |
+|---------|-------------|------------|
+| Anthropic | `ANTHROPIC_API_KEY` | `sk-ant-` |
+| OpenAI | `OPENAI_API_KEY` | `sk-` |
+| Google | `GOOGLE_API_KEY` or `GEMINI_API_KEY` | `AI` |
+| Ollama | (none needed) | — |
+
+## Config File Location
+
+`~/.ai-council/config.json`
+
+```json
+{
+  "backends": {
+    "anthropic": { "apiKey": "sk-ant-..." },
+    "openai": { "apiKey": "sk-..." },
+    "google": { "apiKey": "AI..." }
+  }
+}
+```