@statechange/council 0.8.0 → 0.9.1

package/package.json

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

package/skills/council-create-councilor/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: council-create-councilor
+description: Create a new AI Council councilor from a person, book, body of work, or concept. Builds the ABOUT.md with frontmatter and system prompt, registers it, and verifies it loads. Use when the user wants to add a new perspective to their council.
+license: MIT
+metadata:
+  author: ai-council
+  version: "1.0"
+---
+
+# Create a Council Councilor
+
+Build and register a new councilor for the AI Council.
+
+## Prerequisites
+
+```bash
+# Ensure council is installed
+which council || npm install -g @statechange/council
+```
+
+## Procedure
+
+### Step 1: Gather Source Material
+
+Determine what the councilor is based on. This could be:
+
+- **A person/author**: Research their key ideas, frameworks, and perspectives. If they have books in the conversation or accessible online, fetch and read them.
+- **A book**: Extract the core thesis, key frameworks, and actionable principles.
+- **A concept/role**: Define the perspective, methodology, and decision-making lens.
+- **A URL**: Fetch the content and distill the perspective it represents.
+
+If source material is available as a URL or file, fetch it:
+
+```bash
+curl -sL "https://example.com/source" -o /tmp/councilor-source.txt
+```
+
+### Step 2: Choose an ID
+
+The councilor ID is the directory name. Use lowercase, hyphenated:
+
+- Person: `first-last` (e.g., `neal-ford`, `chip-huyen`)
+- Concept: `the-role` (e.g., `the-strategist`, `the-critic`)
+- Book-based: `author-name` or `book-slug`
+
+### Step 3: Write the ABOUT.md
+
+Create the councilor directory and ABOUT.md:
+
+```bash
+mkdir -p ~/.ai-council/councilors/COUNCILOR_ID
+```
+
+The ABOUT.md has two parts:
+
+#### Part 1: YAML Frontmatter
+
+```yaml
+---
+name: "Display Name"
+description: "One-line description of their perspective and expertise"
+interests: ["topic1", "topic2", "topic3", "topic4", "topic5"]
+backend: "anthropic"
+model: "claude-sonnet-4-6"
+temperature: 0.7
+avatar: "https://api.dicebear.com/9.x/personas/svg?seed=UniqueSlug&backgroundColor=b6e3f4"
+---
+```
+
+**Field guidance:**
+
+- **name**: How they appear in discussions. Use their real name for real people, a title for archetypes.
+- **description**: What they bring to the council. Under 120 chars.
+- **interests**: 5-8 terms reflecting their domains. Used for councilor selection matching.
+- **backend**: Which LLM backend to use. `anthropic` or `google` are recommended. Use `google` with `gemini-flash-latest` for cheaper councilors.
+- **model**: Specific model ID. Good defaults:
+  - Anthropic: `claude-sonnet-4-6` (balanced), `claude-haiku-4-5-20251001` (fast/cheap)
+  - Google: `gemini-flash-latest` (fast/cheap)
+- **temperature**: 0.5-0.6 for analytical thinkers, 0.7 for balanced, 0.8-0.9 for creative/provocative
+- **avatar**: For real people, prefer downloading a public-domain image as `avatar.jpg` in the councilor directory and setting `avatar: "avatar.jpg"`. Use DiceBear URL as fallback for fictional personas. Background colors: `b6e3f4` (blue), `ffd5dc` (pink), `c0aede` (purple), `d1d4f9` (lavender), `ffeab6` (yellow).
+
+#### Part 2: System Prompt
+
+Write this directly after the frontmatter closing `---`:
+
+```markdown
+You are [Name], [role/credentials]. You serve on a council of experts.
+
+**[Book/Framework Title]**: [Core thesis in 2-3 sentences]. [Key ideas as a structured list or paragraphs, covering 3-6 main principles/frameworks].
+
+When contributing to a discussion:
+- [Specific behavioral instruction 1]
+- [Specific behavioral instruction 2]
+- [Specific behavioral instruction 3]
+- [Specific behavioral instruction 4]
+- [What makes their perspective unique]
+
+Keep your responses focused and substantive. Aim for 2-4 paragraphs per turn.
+```
+
+**System prompt principles:**
+- Ground the persona in specific ideas, not vague personality traits
+- Name their frameworks and methods explicitly — these are what make the councilor useful
+- Behavioral instructions should describe HOW they engage, not just what they know
+- End with the standard "2-4 paragraphs per turn" instruction
+
+#### For source-material-heavy councilors
+
+If you have large reference text (book content, articles, essays), append it after the system prompt:
+
+```markdown
+---
+
+## Reference Material: [Title]
+
+Draw on the following source material when contributing to discussions.
+
+[Full text here]
+```
+
+For large texts, use file concatenation to avoid LLM output limits:
+
+```bash
+# Write header (frontmatter + system prompt) to temp file
+cat > /tmp/councilor-header.md << 'HEADER'
+---
+name: "..."
+...
+---
+System prompt here...
+
+---
+
+## Reference Material: Title
+
+Draw on the following source material when contributing to discussions.
+
+HEADER
+
+# Concatenate header + source body
+cat /tmp/councilor-header.md /tmp/source-body.txt > ~/.ai-council/councilors/COUNCILOR_ID/ABOUT.md
+```
+
+### Step 4: Register the Councilor
+
+```bash
+council councilor add ~/.ai-council/councilors/COUNCILOR_ID
+```
+
+### Step 5: Verify
+
+```bash
+council list 2>/dev/null | grep -A 2 "COUNCILOR_ID"
+```
+
+Confirm the councilor appears with correct name, backend, and interests.
+
+## Examples
+
+### From a person/author
+
+User: "Make a councilor based on Simon Sinek"
+
+1. Research Simon Sinek's key ideas (Start With Why, infinite games, leadership)
+2. Create `~/.ai-council/councilors/simon-sinek/ABOUT.md`
+3. Register with `council councilor add ~/.ai-council/councilors/simon-sinek`
+
+### From a concept
+
+User: "I need a security-focused councilor"
+
+1. Define the security perspective (threat modeling, OWASP, zero trust, attack surface)
+2. Create `~/.ai-council/councilors/the-security-hawk/ABOUT.md`
+3. Register
+
+### From a URL
+
+User: "Make a councilor based on this article: https://example.com/manifesto"
+
+1. Fetch the URL content
+2. Extract the key ideas and frameworks
+3. Create the councilor with the article content as reference material
+4. Register
+
+## Common Mistakes
+
+- **Too vague**: "You are a business expert who gives good advice" — useless. Name specific frameworks and methods.
+- **Too long**: System prompts over ~2KB before reference material. Keep the core prompt tight; put bulk text in reference material section.
+- **Wrong temperature**: Using 0.9 for an analytical thinker or 0.5 for a creative provocateur.
+- **Missing interests**: These are used for matching in the discuss-idea skill. Always include 5-8 relevant terms.
+- **Creating in project directory**: Always use `~/.ai-council/councilors/` — never put councilors in a project's local `./council/` directory.

package/skills/council-discuss-idea/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: council-discuss-idea
+description: Run a council discussion on any topic, idea, or URL. Automatically selects relevant councilors from those installed, runs a multi-round debate, and returns only the summary. Full transcript is saved to a temp file for optional deep-dive. Use when you need expert perspectives on a strategy, architecture, product, or business problem.
+license: MIT
+metadata:
+  author: ai-council
+  version: "2.0"
+---
+
+# Council Discuss Idea
+
+Run a focused council discussion and return a clean summary. The full debate transcript is saved to a temp file — not loaded into context — so the caller can grep it if needed.
+
+## Prerequisites
+
+Council CLI must be installed. If `council` is not found:
+
+```bash
+npm install -g @statechange/council
+```
+
+A secretary backend must be configured (it produces the summary). Check with:
+
+```bash
+council config show
+```
+
+## Procedure
+
+### Step 1: Discover Available Councilors
+
+```bash
+council list 2>/dev/null | grep -E '^\w|^  Backend|^  Interests'
+```
+
+Parse the output to get councilor IDs and their interests/descriptions. Only use councilors that are actually listed — do not assume any are available.
+
+### Step 2: Select Councilors for the Topic
+
+Based on the topic and each councilor's listed interests/description, pick 3-5 councilors that are most relevant. Guidelines:
+
+- **Always include diverse perspectives** — at least one who will naturally challenge the idea
+- **Match by interests** — the councilor list shows each one's interests, use those to match
+- **Prefer fewer, more relevant councilors** over many loosely related ones
+- **3-5 is ideal** — enough for cross-pollination, not so many it dilutes focus
+
+### Step 3: Run the Discussion
+
+```bash
+council discuss "THE TOPIC OR QUESTION" \
+  --councilors id1,id2,id3,id4 \
+  --rounds 2 \
+  --format json \
+  --output /tmp/council-discussions \
+  2>&1
+```
+
+**Important notes:**
+- The topic can include URLs — they will be automatically fetched and included as context
+- Use `--rounds 2` for good depth (round 1 = initial takes, round 2 = cross-pollination)
+- Use `--format json` so the full structured output is saved
+- Use `--output /tmp/council-discussions` to keep transcripts in a predictable location
+- The CLI streams output to stderr while running — capture both stdout and stderr
+
+### Step 4: Extract the Summary
+
+The JSON output file contains the full discussion. Extract just the summary:
+
+```bash
+# Find the most recent output file
+TRANSCRIPT=$(ls -t /tmp/council-discussions/council-*.json 2>/dev/null | head -1)
+
+# Extract the summary (the secretary's synthesis)
+cat "$TRANSCRIPT" | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+summary = data.get('summary', '')
+if summary:
+    print(summary)
+else:
+    # No secretary summary — fall back to last round turns
+    for turn in data.get('turns', []):
+        if turn['round'] == data.get('rounds', 1):
+            print(f\"**{turn['councilorName']}**: {turn['content']}\n\")
+"
+```
+
+### Step 5: Return Results to the Caller
+
+Present to the user:
+
+1. **The summary** — this is the primary output. It contains convergence, divergence, and synthesis.
+2. **The transcript path** — mention it so the user (or agent) can dive deeper: "Full transcript saved to `{TRANSCRIPT}`"
+3. **Brief councilor attribution** — which councilors participated (names only)
+
+**Do NOT** dump the full transcript into the response. The whole point is keeping context clean.
+
+If the user wants to explore a specific councilor's take or a specific point of contention, THEN grep the transcript file:
+
+```bash
+# Find what a specific councilor said
+grep -A 50 '"councilorName": "Neal Ford"' "$TRANSCRIPT"
+
+# Or read the full markdown for human consumption
+cat /tmp/council-discussions/council-*.md | head -200
+```
+
+## Example
+
+User says: "What do you think about building a SaaS that helps restaurants manage food waste using computer vision?"
+
+```bash
+# Step 1: Check who's available
+council list 2>/dev/null | grep -E '^\w'
+
+# Step 2: Pick relevant councilors (suppose we found these)
+# marc-andreessen (market/startups), chip-huyen (AI/CV), daniel-priestley (business model), chan-kim (market creation), critic (stress test)
+
+# Step 3: Run it
+council discuss "Should we build a SaaS that helps restaurants manage food waste using computer vision? The idea is to use cameras in kitchens to identify and quantify food waste, then provide actionable insights to reduce it. Target market is mid-to-large restaurant chains (50+ locations)." \
+  --councilors marc-andreessen,chip-huyen,daniel-priestley,chan-kim,critic \
+  --rounds 2 \
+  --format json \
+  --output /tmp/council-discussions \
+  2>&1
+
+# Step 4: Get the summary
+TRANSCRIPT=$(ls -t /tmp/council-discussions/council-*.json | head -1)
+python3 -c "import json; d=json.load(open('$TRANSCRIPT')); print(d.get('summary','No summary generated'))"
+```
+
+Then respond with the summary + transcript path.

package/skills/council-install-councilor/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: council-install-councilor
+description: Install councilors from git repos, local directories, or shared collections. Use when the user wants to add an existing councilor they didn't create — from GitHub, a team repo, or a local path. Also handles multi-councilor repos that contain several councilors in one repository.
+license: MIT
+metadata:
+  author: ai-council
+  version: "1.0"
+---
+
+# Install a Councilor
+
+Add existing councilors to your AI Council from git repos or local directories.
+
+## Prerequisites
+
+```bash
+which council || npm install -g @statechange/council
+```
+
+## When to Use
+
+- The user wants to install a councilor from GitHub or another git host
+- The user has a local directory with councilor(s) they want to register
+- The user wants to install a shared collection of councilors from a team repo
+- The user says "add councilor", "install councilor", "import councilor", or "get councilor from..."
+
+## Procedure
+
+### Install from a Git Repository
+
+```bash
+council councilor add https://github.com/user/councilor-repo.git
+```
+
+What happens:
+1. The repo is cloned to `~/.ai-council/councilors/<repo-name>/`
+2. If the repo root has an `ABOUT.md`, it's registered as a single councilor
+3. If the repo root has NO `ABOUT.md`, child directories are scanned — each one with an `ABOUT.md` is registered as a separate councilor (multi-councilor repo)
+
+URL detection: anything starting with `http://`, `https://`, or ending with `.git` is treated as a git URL.
+
+### Install from a Local Directory
+
+```bash
+council councilor add /path/to/councilor-directory
+```
+
+The directory must contain an `ABOUT.md` with valid YAML frontmatter. The councilor is registered by reference (not copied) — it stays where it is on disk.
+
+### Install Multiple from a Local Collection
+
+If you have a directory containing multiple councilor subdirectories:
+
+```bash
+# Register each subdirectory individually
+for d in /path/to/collection/*/; do
+  if [ -f "$d/ABOUT.md" ]; then
+    council councilor add "$d"
+  fi
+done
+```
+
+### Verify Installation
+
+```bash
+# List all registered councilors
+council councilor list
+
+# Or see full details
+council list
+```
+
+## Managing Installed Councilors
+
+### List registered councilors
+
+```bash
+council councilor list
+```
+
+Shows each councilor's ID, source (local/git), path, and when it was added.
+
+### Remove a councilor
+
+```bash
+# Unregister only (keeps files on disk)
+council councilor remove councilor-id
+
+# Unregister AND delete cloned files (for git-sourced councilors)
+council councilor remove councilor-id --yes
+```
+
+### Update a git-sourced councilor
+
+Git-sourced councilors are cloned repos. To update:
+
+```bash
+cd ~/.ai-council/councilors/councilor-name
+git pull
+```
+
+## Troubleshooting
+
+### "No ABOUT.md found"
+
+The directory must contain an `ABOUT.md` at its root with valid YAML frontmatter (name, description, backend, interests).
+
+### Councilor shows but won't work in discussions
+
+Check that the councilor's backend has a configured API key:
+
+```bash
+council config show
+```
+
+### Councilor from git repo not appearing
+
+For multi-councilor repos, each councilor subdirectory needs its own `ABOUT.md`. Check the cloned directory:
+
+```bash
+ls ~/.ai-council/councilors/repo-name/
+```