llm-cli-council 1.0.0

package/rules/triggers.md

@@ -0,0 +1,182 @@
+# Council Triggers
+
+These rules define when to automatically invoke the council without explicit command.
+
+---
+
+## Trigger Patterns
+
+### Explicit Triggers (Highest Priority)
+
+User explicitly requests council:
+
+| Pattern | Action |
+|---------|--------|
+| "council review" | Invoke review command |
+| "get council feedback" | Auto-detect type, execute |
+| "ask the council" | Auto-detect type, execute |
+| "llm council" | Auto-detect type, execute |
+| "/llm-cli-council:*" | Execute specified command |
+
+### Contextual Triggers
+
+When these contexts are detected:
+
+| Context | Trigger | Command |
+|---------|---------|---------|
+| Plan exists + "review" mentioned | Auto-suggest | review-plan |
+| Code diff + "review" mentioned | Auto-suggest | review-code |
+| High-stakes decision keywords | Suggest council | review-plan |
+
+### High-Stakes Keywords
+
+When these appear, suggest council review:
+- "production deployment"
+- "breaking change"
+- "major refactor"
+- "security"
+- "architecture decision"
+- "before we proceed"
+
+---
+
+## Auto-Detection Logic
+
+### Plan vs Code Detection
+
+```
+If user mentions "review":
+  If PLAN.md exists OR "plan" in request:
+    → review-plan
+  Else if code diff exists OR file paths mentioned:
+    → review-code
+  Else:
+    → Ask user what to review
+```
+
+### Mode Detection
+
+```
+If "sensitive" or "private" or "confidential" in request:
+  → Suggest --mode=privacy
+
+If "thorough" or "comprehensive" or "all" in request:
+  → Use --mode=full
+
+Default:
+  → Use --mode=quick
+```
+
+---
+
+## Proactive Suggestions
+
+### When to Suggest Council
+
+Suggest (don't auto-invoke) when:
+
+1. **Plan created** - "Would you like council feedback on this plan?"
+2. **Major PR** - "This is a significant change. Council review recommended."
+3. **Before execution** - "Plan ready. Get council review before executing?"
+
+### Suggestion Format
+
+```
+Council Review Available
+─────────────────────────
+This [plan/code] could benefit from multi-perspective review.
+
+Run: /llm-cli-council:review-[type]
+
+Options:
+• --mode=quick (default) - 2 providers, fast feedback
+• --mode=full - All available providers
+• --mode=privacy - Local only, no data sent externally
+```
+
+---
+
+## Non-Triggers
+
+Do NOT invoke council for:
+
+- Simple syntax questions
+- Single-file edits
+- Bug fixes with obvious solutions
+- User explicitly declines ("skip council", "no review needed")
+- Already reviewed content
+- Draft/WIP explicitly marked
+
+---
+
+## Mode Selection Guide
+
+### Quick Mode (Default)
+
+Use when:
+- Standard reviews
+- Time-sensitive feedback needed
+- Plan is straightforward
+
+### Full Mode
+
+Suggest when:
+- "thorough" or "comprehensive" requested
+- High-stakes keywords detected
+- User seems uncertain
+- Complex architectural decisions
+
+### Privacy Mode
+
+Require when:
+- "sensitive", "private", "confidential" mentioned
+- API keys or secrets in content
+- Proprietary business logic
+- User preference set in config
+
+---
+
+## Integration Points
+
+### With Planning Skills
+
+If user is using planning skills (e.g., `/gsd:plan-phase`):
+- Suggest council review after plan completion
+- Don't interrupt planning flow
+
+### With Code Review Skills
+
+If another code review is active:
+- Don't stack reviews
+- Offer council as alternative or supplement
+
+### With Execution
+
+Before plan execution:
+- Check if council review was done
+- If not, offer quick review opportunity
+- Don't block execution (user choice)
+
+---
+
+## User Preferences
+
+Stored in `~/.claude/council-config.json`:
+
+```json
+{
+  "preferences": {
+    "autoSuggest": true,
+    "defaultMode": "quick",
+    "requirePrivacyFor": ["api", "secret", "password"],
+    "skipFor": ["draft", "wip", "test"]
+  }
+}
+```
+
+### Preference Overrides
+
+- `autoSuggest: false` - Never suggest, only respond to explicit commands
+- `defaultMode` - Change default from "quick"
+- `requirePrivacyFor` - Patterns that force privacy mode
+- `skipFor` - Patterns that suppress suggestions

package/skills/llm-cli-council.md

@@ -0,0 +1,122 @@
+---
+name: llm-cli-council
+description: Orchestrate multiple LLM CLIs (Claude, Copilot, Codex, Gemini, Ollama) as a "council" to provide diverse perspectives on plans and code
+version: 1.0.0
+author: LLM CLI Council
+---
+
+# LLM CLI Council
+
+A Claude Code skill that leverages multiple LLM command-line tools to provide diverse perspectives through a "council" approach. Claude acts as Chairman, synthesizing insights from multiple AI assistants into clear, actionable guidance.
+
+## Why Use a Council?
+
+Single LLMs can be biased toward certain solutions. By consulting multiple AI assistants:
+- **Diverse perspectives** catch blind spots
+- **Consensus** builds confidence in recommendations
+- **Dissent** highlights areas needing careful consideration
+
+## Anti-Paralysis Principle
+
+The council NEVER overwhelms with conflicting advice. Instead, it:
+- Synthesizes into max 5 prioritized recommendations
+- Resolves conflicts with clear reasoning
+- Always provides a decisive APPROVE/REQUEST CHANGES verdict
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/llm-cli-council:setup` | Detect and configure available LLM CLIs |
+| `/llm-cli-council:review-plan` | Get council review of a plan |
+| `/llm-cli-council:review-code` | Get council review of code changes |
+| `/llm-cli-council:status` | Show council configuration and provider status |
+| `/llm-cli-council:uninstall` | Remove council configuration |
+
+## Council Modes
+
+| Mode | Providers Used | Use Case |
+|------|----------------|----------|
+| `quick` (default) | 2 best-match providers | Most reviews, fast feedback |
+| `full` | All available providers | High-stakes decisions |
+| `privacy` | Ollama only | Sensitive code, no data leaves machine |
+
+## Supported Providers
+
+- **Claude** (`claude`) - Anthropic's CLI
+- **Copilot** (`copilot`) - GitHub Copilot CLI
+- **Codex** (`codex`) - OpenAI Codex CLI
+- **Gemini** (`gemini`) - Google Gemini CLI
+- **Ollama** (`ollama`) - Local LLM runner
+
+## Configuration
+
+The council uses environment variables for flexible path configuration:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAUDE_COUNCIL_CONFIG_DIR` | `~/.config/claude/council/` | Config directory location |
+| `CLAUDE_COUNCIL_CONFIG_FILE` | `$COUNCIL_CONFIG_DIR/config.json` | Specific config file |
+| `CLAUDE_COUNCIL_LOG_DIR` | `$COUNCIL_CONFIG_DIR/logs/` | Log directory |
+| `CLAUDE_SKILLS_DIR` | `~/.claude/skills/` | Skills installation directory |
+| `CLAUDE_CONFIG_DIR` | `~/.claude/` | Claude's main config directory |
+
+**Path Resolution Priority:**
+1. `$CLAUDE_COUNCIL_CONFIG_DIR` (explicit override)
+2. `$CLAUDE_CONFIG_DIR/council/` (Claude config + council subdir)
+3. `$XDG_CONFIG_HOME/claude/council/` (XDG standard on Linux)
+4. `~/.config/claude/council/` (XDG fallback)
+5. `~/.claude/council/` (legacy compatibility)
+
+## Quick Start
+
+1. Run `/llm-cli-council:setup` to detect available CLIs
+2. Run `/llm-cli-council:review-plan` on your PLAN.md
+3. Receive synthesized council feedback with clear recommendations
+
+## Usage Examples
+
+```
+# Review current plan with 2 providers (quick mode)
+/llm-cli-council:review-plan
+
+# Full council review with all providers
+/llm-cli-council:review-plan --mode=full
+
+# Privacy mode - only local Ollama
+/llm-cli-council:review-plan --mode=privacy
+
+# Review specific file
+/llm-cli-council:review-plan path/to/plan.md
+```
+
+## How It Works
+
+```
+Stage 1: Independent Review
+├── Execute prompts in parallel across providers
+├── Each provider reviews independently
+└── No cross-contamination of opinions
+
+Stage 2: Collect & Analyze
+├── Gather all responses
+├── Identify: CONSENSUS | CONCERNS | DISSENT
+└── Weight responses by domain expertise
+
+Stage 3: Chairman Synthesis (Claude)
+├── Resolve conflicts with reasoning
+├── Create max 5 prioritized recommendations
+├── Provide clear APPROVE/REQUEST CHANGES verdict
+└── Present unified guidance
+```
+
+## Configuration
+
+Council configuration is stored in `~/.claude/council-config.json` after running setup.
+
+## Rules
+
+The council follows strict rules defined in:
+- `rules/council-orchestration.md` - How to coordinate multiple LLMs
+- `rules/synthesis-strategy.md` - How to merge conflicting opinions
+- `rules/triggers.md` - When to automatically invoke council

package/skills/review-code.md

@@ -0,0 +1,225 @@
+---
+name: llm-cli-council:review-code
+description: Get council review of code changes from multiple LLM providers
+invocable: true
+---
+
+# LLM CLI Council - Review Code
+
+This command orchestrates multiple LLM CLIs to review code changes and synthesizes their feedback.
+
+## Usage
+
+```
+/llm-cli-council:review-code [target] [--mode=quick|full|privacy]
+```
+
+### Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `target` | File path, git ref, or "staged" | Staged changes (`git diff --cached`) |
+| `--mode` | Council mode | `quick` (2 providers) |
+
+### Target Options
+
+| Target | Description |
+|--------|-------------|
+| `staged` | Review staged git changes |
+| `HEAD` | Review last commit |
+| `HEAD~3..HEAD` | Review last 3 commits |
+| `main..HEAD` | Review all commits since main |
+| `path/to/file.js` | Review specific file |
+| `path/to/dir/` | Review all files in directory |
+
+---
+
+## Execution Flow
+
+### Step 1: Load Configuration
+
+Read council configuration from `$COUNCIL_CONFIG_FILE`.
+
+If config doesn't exist:
+```
+Council not configured. Run /llm-cli-council:setup first.
+```
+
+### Step 2: Get Code Content
+
+Based on target:
+
+**Staged changes (default):**
+```bash
+git diff --cached
+```
+
+**Git ref:**
+```bash
+git diff {ref}
+# or
+git show {ref}
+```
+
+**File/directory:**
+```bash
+cat {file}
+# or
+find {dir} -type f -exec cat {} \;
+```
+
+### Step 3: Select Providers
+
+Based on mode and task routing for `code-review`:
+- **quick**: Codex, Copilot (preferred) or Claude (fallback)
+- **full**: All available
+- **privacy**: Ollama only
+
+### Step 4: Build Review Prompts
+
+For each selected provider:
+1. Load `${CLAUDE_PLUGIN_ROOT}/prompts/code-review.md` template
+2. Substitute `{CODE_CONTENT}` with diff/code
+3. Substitute `{FILE_LIST}` with affected files
+4. Apply provider-specific prefix adjustments
+
+### Step 5: Execute Parallel Reviews
+
+Same pattern as review-plan - parallel execution with timeout handling.
+
+### Step 6: Collect & Parse Responses
+
+Parse structured sections:
+- RATING
+- ISSUES (by severity)
+- RECOMMENDATIONS
+- VERDICT
+
+### Step 7: Chairman Synthesis
+
+Synthesize with code-review-specific weighting:
+- Codex and Copilot weighted higher for code issues
+- Severity aggregation across providers
+- Deduplicate same issue found by multiple providers
+
+### Step 8: Present Results
+
+```
+COUNCIL CODE REVIEW
+═══════════════════════════════════════════════════════
+
+Target: staged changes (3 files)
+Providers: Codex, Copilot
+Mode: quick
+
+FILES REVIEWED:
+• src/api/auth.ts
+• src/utils/validation.ts
+• tests/auth.test.ts
+
+CRITICAL ISSUES:
+• src/api/auth.ts:45 - SQL injection vulnerability
+  Found by: Codex, Copilot (CONSENSUS)
+  Fix: Use parameterized queries
+
+HIGH ISSUES:
+• src/utils/validation.ts:23 - Missing null check
+  Found by: Codex
+  Fix: Add guard clause before access
+
+MEDIUM ISSUES:
+• src/api/auth.ts:78 - Complex function (cyclomatic: 12)
+  Found by: Copilot
+  Assessment: Valid but not blocking
+
+RECOMMENDATIONS (prioritized):
+1. Fix SQL injection immediately [Quick]
+2. Add null check in validation [Quick]
+3. Consider splitting auth function [Short]
+
+PROVIDER VERDICTS:
+  Codex: REQUEST CHANGES (HIGH) - Security issue
+  Copilot: REQUEST CHANGES (HIGH) - Security issue
+
+FINAL VERDICT: REQUEST CHANGES
+Reasoning: Critical SQL injection vulnerability must be fixed
+before merge. Both providers flagged this with high confidence.
+
+═══════════════════════════════════════════════════════
+```
+
+---
+
+## Issue Aggregation
+
+### Same Issue, Multiple Providers
+
+When providers identify the same issue:
+1. Mark as CONSENSUS
+2. Use most specific file:line reference
+3. Combine fix suggestions
+4. Elevate severity if any provider rates higher
+
+### Conflicting Severity
+
+If providers disagree on severity:
+- Security issues: Use highest severity (conservative)
+- Style issues: Use lowest severity (pragmatic)
+- Other: Chairman decides based on context
+
+---
+
+## Error Handling
+
+### No Git Repository
+```
+Error: Not in a git repository.
+For non-git code review, specify file path:
+  /llm-cli-council:review-code path/to/file.js
+```
+
+### No Changes to Review
+```
+No staged changes found. Options:
+1. Stage changes: git add <files>
+2. Review specific commit: /llm-cli-council:review-code HEAD
+3. Review file directly: /llm-cli-council:review-code path/to/file
+```
+
+### Large Diff Warning
+```
+Warning: Diff is large (>1000 lines).
+This may result in incomplete reviews or timeouts.
+
+Options:
+1. Continue anyway
+2. Review specific files instead
+3. Split into smaller chunks
+```
+
+---
+
+## Integration
+
+### With Git Workflow
+
+```bash
+# Review before commit
+git add .
+/llm-cli-council:review-code staged
+
+# Review before push
+/llm-cli-council:review-code main..HEAD
+
+# Review specific PR
+/llm-cli-council:review-code origin/main..feature-branch
+```
+
+### With Other Review Tools
+
+Council review complements (doesn't replace):
+- Linters (ESLint, Pylint)
+- Type checkers (TypeScript, mypy)
+- Security scanners (Snyk, CodeQL)
+
+Run automated tools first, then council for logic review.

package/skills/review-plan.md

@@ -0,0 +1,191 @@
+---
+name: llm-cli-council:review-plan
+description: Get council review of an implementation plan from multiple LLM providers
+invocable: true
+---
+
+# LLM CLI Council - Review Plan
+
+This command orchestrates multiple LLM CLIs to review an implementation plan and synthesizes their feedback.
+
+## Usage
+
+```
+/llm-cli-council:review-plan [plan-file] [--mode=quick|full|privacy]
+```
+
+### Arguments
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `plan-file` | Path to plan file | Auto-detect PLAN.md in current/project directory |
+| `--mode` | Council mode | `quick` (2 providers) |
+
+---
+
+## Execution Flow
+
+### Step 1: Load Configuration
+
+Read council configuration from `$COUNCIL_CONFIG_FILE`.
+
+If config doesn't exist:
+```
+Council not configured. Run /llm-cli-council:setup first.
+```
+
+### Step 2: Locate Plan Content
+
+Priority order:
+1. Explicit file path argument
+2. `PLAN.md` in current directory
+3. `PLAN.md` in `.planning/` directory
+4. Ask user to provide plan content
+
+### Step 3: Select Providers
+
+Based on mode:
+
+**quick (default):**
+- Read `${CLAUDE_PLUGIN_ROOT}/config/providers.json` task routing for `plan-review`
+- Select top 2 available providers by routing priority
+- Preferred: Claude, Codex. Fallback: Gemini
+
+**full:**
+- Use all available providers from config
+
+**privacy:**
+- Use only Ollama (if available)
+- Error if Ollama not configured
+
+### Step 4: Build Review Prompts
+
+For each selected provider:
+1. Load `${CLAUDE_PLUGIN_ROOT}/prompts/plan-review.md` template
+2. Substitute `{PLAN_CONTENT}` with actual plan
+3. Apply provider-specific prefix adjustments
+4. Prepare CLI invocation command
+
+### Step 5: Execute Parallel Reviews
+
+Run all provider CLIs in parallel using background execution:
+
+```bash
+# Example parallel execution
+claude -p --print "{prompt}" &
+codex exec "{prompt}" &
+wait
+```
+
+Timeout handling:
+- Default: 120 seconds per provider
+- On timeout: Log warning, continue with remaining providers
+- Minimum quorum: 2 providers must respond
+
+### Step 6: Collect Responses
+
+Parse each provider response:
+1. Extract structured sections (RATING, GAPS, RISKS, RECOMMENDATIONS, VERDICT)
+2. Handle malformed responses gracefully
+3. Track which providers responded successfully
+
+### Step 7: Chairman Synthesis
+
+1. Load `${CLAUDE_PLUGIN_ROOT}/prompts/chairman-synthesis.md`
+2. Format all provider reviews into synthesis prompt
+3. Claude (as Chairman) synthesizes into unified guidance
+4. Apply anti-paralysis rules (max 5 recommendations, clear verdict)
+
+### Step 8: Present Results
+
+Display formatted council review:
+
+```
+COUNCIL REVIEW
+═══════════════════════════════════════════════════════
+
+Providers consulted: Claude, Codex
+Mode: quick
+
+CONSENSUS (Both agree):
+• Plan lacks error handling section
+• Database migration strategy is solid
+
+CONCERNS (Raised by at least one):
+• Testing strategy unclear — Raised by: Codex
+  Assessment: Valid - add testing section
+
+DISSENTING VIEWS:
+• Deployment approach: Claude prefers blue-green, Codex prefers canary
+  Resolution: Blue-green is simpler for this scale - go with Claude's recommendation
+
+RECOMMENDATIONS (prioritized):
+1. Add error handling section [Quick]
+2. Clarify testing strategy [Quick]
+3. Consider adding rollback plan [Short]
+
+PROVIDER VERDICTS:
+  Claude: APPROVE (HIGH)
+  Codex: REQUEST CHANGES (MEDIUM)
+
+FINAL VERDICT: REQUEST CHANGES
+Reasoning: While the plan is solid, the missing testing strategy
+is a significant gap that should be addressed before implementation.
+
+═══════════════════════════════════════════════════════
+```
+
+---
+
+## Error Handling
+
+### No Providers Available
+```
+Error: No council providers available.
+Run /llm-cli-council:setup to configure providers.
+```
+
+### Single Provider Only
+```
+Warning: Only 1 provider responded. Results may lack diversity.
+Consider running with --mode=full or checking provider status.
+
+[Present single review with disclaimer]
+```
+
+### All Providers Timeout
+```
+Error: All providers timed out.
+- Check network connectivity
+- Verify provider authentication: /llm-cli-council:status
+- Try privacy mode with local Ollama: --mode=privacy
+```
+
+### Plan Not Found
+```
+No plan found. Please provide:
+1. Path to plan file: /llm-cli-council:review-plan ./my-plan.md
+2. Create PLAN.md in current directory
+3. Paste plan content when prompted
+```
+
+---
+
+## CLI Invocation Reference
+
+| Provider | Command |
+|----------|---------|
+| Claude | `claude -p --print "{prompt}"` |
+| Codex | `codex exec "{prompt}"` |
+| Copilot | `copilot --prompt "{prompt}" --allow-all-tools` |
+| Gemini | `gemini "{prompt}"` |
+| Ollama | `ollama run gpt-oss:20b "{prompt}"` |
+
+---
+
+## Output Options
+
+Future enhancement ideas:
+- `--json` - Output as JSON for programmatic use
+- `--brief` - Only show verdict and top 3 recommendations
+- `--save` - Save full council review to file