llm-cli-council 1.0.0

package/prompts/plan-review.md

@@ -0,0 +1,106 @@
+# Plan Review Prompt Template
+
+This template is sent to each council provider for independent plan review.
+
+---
+
+## Prompt Template
+
+```
+TASK: Review the following implementation plan for completeness, clarity, and technical soundness.
+
+EXPECTED OUTCOME: Provide a structured review with:
+- Assessment of plan quality (1-10 scale)
+- Identified issues or gaps
+- Specific recommendations
+- Final verdict: APPROVE or REQUEST CHANGES
+
+CONTEXT:
+- This is a plan review, not implementation
+- Focus on whether the plan is executable as written
+- Consider: clarity, completeness, technical feasibility, risk management
+
+PLAN CONTENT:
+---
+{PLAN_CONTENT}
+---
+
+CONSTRAINTS:
+- You are one voice in a council of reviewers
+- Keep your review focused and specific
+- Do not implement or modify - only review
+
+MUST DO:
+1. Rate the plan on a 1-10 scale with brief justification
+2. List any missing information or unclear sections
+3. Identify potential risks not addressed
+4. Provide 3-5 specific, actionable recommendations
+5. Give a clear APPROVE or REQUEST CHANGES verdict
+
+MUST NOT DO:
+- Provide generic advice ("add more detail")
+- Suggest complete rewrites
+- Overlap with implementation concerns
+- Be overly verbose
+
+OUTPUT FORMAT:
+RATING: [1-10] - [one-line justification]
+
+GAPS:
+• [Gap 1]
+• [Gap 2]
+
+RISKS:
+• [Risk 1] - [Mitigation suggestion]
+
+RECOMMENDATIONS:
+1. [Specific recommendation]
+2. [Specific recommendation]
+3. [Specific recommendation]
+
+VERDICT: [APPROVE / REQUEST CHANGES]
+CONFIDENCE: [HIGH / MEDIUM / LOW]
+REASONING: [1-2 sentences explaining verdict]
+```
+
+---
+
+## Variable Substitution
+
+| Variable | Source |
+|----------|--------|
+| `{PLAN_CONTENT}` | Contents of plan file or inline plan text |
+
+---
+
+## Provider-Specific Adjustments
+
+### Claude
+No adjustments - template works as-is.
+
+### Codex
+Add prefix: "You are reviewing code-related implementation plans. Focus on technical feasibility."
+
+### Copilot
+Add prefix: "Review this plan from a GitHub/development workflow perspective."
+
+### Gemini
+Add prefix: "Provide a comprehensive review considering multiple perspectives."
+
+### Ollama
+Simplify prompt slightly for smaller models - remove "council" context.
+
+---
+
+## Response Parsing
+
+Expected response sections to parse:
+1. `RATING:` line with number and justification
+2. `GAPS:` bullet list
+3. `RISKS:` bullet list with mitigations
+4. `RECOMMENDATIONS:` numbered list
+5. `VERDICT:` APPROVE or REQUEST CHANGES
+6. `CONFIDENCE:` HIGH, MEDIUM, or LOW
+7. `REASONING:` explanation
+
+If a section is missing, mark as "NOT PROVIDED" in synthesis.

package/rules/council-orchestration.md

@@ -0,0 +1,205 @@
+# Council Orchestration Rules
+
+These rules govern how to coordinate multiple LLM providers as a council.
+
+---
+
+## Core Principles
+
+### 1. Independence First
+Each provider reviews independently without knowledge of other reviews.
+- Never share one provider's output with another during review
+- Prevents groupthink and ensures diverse perspectives
+- Cross-contamination invalidates the council's value
+
+### 2. Parallel Execution
+Always execute provider calls in parallel when possible.
+- Reduces total wait time significantly
+- Use background processes or async patterns
+- Handle timeouts per-provider, not globally
+
+### 3. Graceful Degradation
+Council continues even if some providers fail.
+- Minimum quorum: 2 providers for meaningful synthesis
+- 1 provider: Warn user, present with disclaimer
+- 0 providers: Error with troubleshooting guidance
+
+### 4. Chairman Authority
+Claude (as Chairman) has final synthesis authority.
+- Resolves all conflicts decisively
+- Never leaves decision to user
+- Provides clear reasoning for resolutions
+
+---
+
+## Provider Selection Algorithm
+
+### Quick Mode (Default)
+```
+1. Load task routing from providers.json
+2. Filter to available providers only
+3. Sort by routing priority (lower = better)
+4. Select top 2
+5. If < 2 available, use all available
+```
+
+### Full Mode
+```
+1. Get all available providers from config
+2. Execute all in parallel
+3. Require minimum 2 responses for synthesis
+```
+
+### Privacy Mode
+```
+1. Check if Ollama is available
+2. If yes, use only Ollama
+3. If no, error with installation instructions
+```
+
+---
+
+## Execution Patterns
+
+### Parallel CLI Execution (Bash)
+
+```bash
+# Source platform utilities
+source "${SKILL_DIR}/lib/platform-utils.sh"
+
+# Create temp files for responses (cross-platform)
+RESP_CLAUDE=$(make_temp_file "council_claude")
+RESP_CODEX=$(make_temp_file "council_codex")
+
+# Execute in parallel
+claude -p --print "$PROMPT" > "$RESP_CLAUDE" 2>&1 &
+PID_CLAUDE=$!
+
+codex exec "$PROMPT" > "$RESP_CODEX" 2>&1 &
+PID_CODEX=$!
+
+# Wait with timeout (cross-platform)
+wait_for_pid "$PID_CLAUDE" 120 || kill "$PID_CLAUDE" 2>/dev/null
+wait_for_pid "$PID_CODEX" 120 || kill "$PID_CODEX" 2>/dev/null
+
+# Collect results
+CLAUDE_RESPONSE=$(cat "$RESP_CLAUDE")
+CODEX_RESPONSE=$(cat "$RESP_CODEX")
+
+# Cleanup
+rm "$RESP_CLAUDE" "$RESP_CODEX"
+```
+
+### Timeout Handling
+
+Per-provider timeouts from `providers.json`:
+- Claude: 120s
+- Codex: 120s
+- Copilot: 90s
+- Gemini: 90s
+- Ollama: 180s (local execution can be slower)
+
+On timeout:
+1. Kill the process
+2. Log which provider timed out
+3. Continue with remaining responses
+4. Include timeout info in synthesis
+
+---
+
+## Response Collection
+
+### Expected Response Structure
+
+```
+RATING: [1-10] - [justification]
+GAPS: [bullet list]
+RISKS: [bullet list]
+RECOMMENDATIONS: [numbered list]
+VERDICT: [APPROVE/REQUEST CHANGES]
+CONFIDENCE: [HIGH/MEDIUM/LOW]
+REASONING: [explanation]
+```
+
+### Parsing Rules
+
+1. **Strict sections**: Look for exact headers
+2. **Flexible content**: Accept variations in formatting
+3. **Missing sections**: Mark as "NOT PROVIDED"
+4. **Malformed response**: Include raw response in synthesis with warning
+
+### Response Validation
+
+Valid response must have:
+- [ ] VERDICT present (APPROVE or REQUEST CHANGES)
+- [ ] At least one RECOMMENDATION
+- [ ] Parseable structure
+
+Invalid responses:
+- Include in synthesis with "[MALFORMED RESPONSE]" tag
+- Still count toward quorum
+- Chairman can extract useful content manually
+
+---
+
+## Error Recovery
+
+### Provider Auth Failure
+
+```
+Provider [name] auth error: [error message]
+Continuing with remaining providers.
+Fix: Run `[auth command]` to re-authenticate.
+```
+
+### Network Timeout
+
+```
+Provider [name] timed out after [X]s.
+Continuing with remaining providers.
+```
+
+### All Providers Fail
+
+```
+Council Review Failed
+═══════════════════════════════════════════════════════
+
+All providers failed to respond:
+• Claude: [error]
+• Codex: [error]
+
+Troubleshooting:
+1. Check network connectivity
+2. Verify provider auth: /llm-cli-council:status
+3. Try privacy mode: --mode=privacy
+
+Would you like to proceed without council review?
+```
+
+---
+
+## Logging
+
+For debugging, log:
+1. Selected providers and selection reasoning
+2. CLI commands executed (without full prompt for privacy)
+3. Response times per provider
+4. Parse success/failure per provider
+5. Final synthesis trigger
+
+Log location: `~/.claude/logs/council/` (if logging enabled)
+
+---
+
+## Security Considerations
+
+### Prompt Content
+- Plan content is sent to external providers
+- For sensitive plans, use `--mode=privacy` (Ollama only)
+- Never log full prompt content
+
+### API Keys
+- Each CLI manages its own authentication
+- Council doesn't store or transmit API keys
+- Auth status checked at setup time only

package/rules/synthesis-strategy.md

@@ -0,0 +1,246 @@
+# Synthesis Strategy Rules
+
+These rules govern how Claude (as Chairman) synthesizes multiple provider reviews into unified guidance.
+
+---
+
+## Anti-Paralysis Mandate
+
+The council exists to **clarify**, not **confuse**. Every synthesis must:
+
+1. **Resolve conflicts** - Never present contradictions without resolution
+2. **Prioritize clearly** - Numbered list, most important first
+3. **Limit scope** - Maximum 5 recommendations
+4. **Decide definitively** - Clear APPROVE or REQUEST CHANGES, never "maybe"
+5. **Explain reasoning** - Users should understand WHY
+
+---
+
+## Categorization Framework
+
+### CONSENSUS
+Points where 2+ providers agree (explicitly or implicitly).
+
+Identification:
+- Same issue mentioned by multiple providers
+- Same recommendation (even if worded differently)
+- Same verdict
+
+Handling:
+- Present as established fact
+- High confidence in these points
+- List provider count: "All 3 agree" or "2 of 3 agree"
+
+### CONCERNS
+Points raised by at least one provider that merit attention.
+
+Identification:
+- Valid technical concern
+- Risk or gap not addressed elsewhere
+- Reasonable recommendation
+
+Handling:
+- Present with attribution: "Raised by: [Provider]"
+- Include Chairman assessment of validity/priority
+- Don't dismiss single-provider concerns automatically
+
+### DISSENT
+Where providers explicitly disagree.
+
+Identification:
+- Opposite verdicts (APPROVE vs REQUEST CHANGES)
+- Contradictory recommendations
+- Different assessments of same issue
+
+Handling:
+- Present both positions clearly
+- Chairman MUST resolve with reasoning
+- Never leave user to decide between contradictions
+
+---
+
+## Conflict Resolution
+
+### Verdict Disagreement
+
+**Majority Rule (2+ providers agree):**
+```
+PROVIDER VERDICTS:
+  Claude: APPROVE (HIGH)
+  Codex: REQUEST CHANGES (MEDIUM)
+  Gemini: APPROVE (HIGH)
+
+FINAL VERDICT: APPROVE
+Reasoning: 2 of 3 providers approve with high confidence.
+Codex's concerns are valid but addressed in recommendations.
+```
+
+**Tie (equal split):**
+Apply task-type weighting:
+- Code plans: Codex, Copilot weighted higher
+- Architecture plans: Claude weighted higher
+- General plans: Equal weight, Chairman decides
+
+```
+PROVIDER VERDICTS:
+  Claude: APPROVE (HIGH)
+  Codex: REQUEST CHANGES (HIGH)
+
+FINAL VERDICT: REQUEST CHANGES
+Reasoning: For code-heavy plans, Codex's concerns carry more weight.
+The testing gap they identified is significant.
+```
+
+### Recommendation Conflict
+
+When providers recommend opposite actions:
+
+1. **Evaluate merit** - Which recommendation is better reasoned?
+2. **Consider context** - Which fits the project better?
+3. **Pick one** - Present the chosen recommendation
+4. **Explain** - Brief note on why this over the alternative
+
+```
+DISSENTING VIEWS:
+• Deployment: Claude recommends blue-green, Codex recommends canary
+  Resolution: Blue-green deployment. Simpler for current team size,
+  and the plan doesn't require gradual rollout capabilities.
+```
+
+---
+
+## Weighting by Task Type
+
+### Plan Review Weights
+
+| Provider | Architecture | Code-heavy | General |
+|----------|--------------|------------|---------|
+| Claude | 1.5x | 1.0x | 1.0x |
+| Codex | 1.2x | 1.5x | 1.0x |
+| Copilot | 0.8x | 1.3x | 1.0x |
+| Gemini | 1.0x | 0.8x | 1.2x |
+| Ollama | 0.8x | 0.8x | 0.8x |
+
+Apply weighting to:
+- Verdict tie-breaking
+- Recommendation prioritization (weighted votes)
+- Confidence assessment
+
+### Code Review Weights
+
+| Provider | Security | Performance | Style |
+|----------|----------|-------------|-------|
+| Claude | 1.2x | 1.0x | 1.0x |
+| Codex | 1.3x | 1.3x | 1.2x |
+| Copilot | 1.0x | 1.2x | 1.5x |
+| Gemini | 1.0x | 0.8x | 0.8x |
+| Ollama | 0.8x | 0.8x | 0.8x |
+
+---
+
+## Recommendation Prioritization
+
+### Priority Factors
+
+1. **Consensus weight** - More providers = higher priority
+2. **Severity** - Blockers before nice-to-haves
+3. **Effort** - Quick wins before large efforts (when equal severity)
+4. **Provider expertise** - Weight by task type
+
+### Priority Algorithm
+
+```
+For each unique recommendation:
+  score = 0
+
+  # Consensus bonus
+  score += (provider_count - 1) * 2
+
+  # Severity (from recommendation wording)
+  if "must" or "critical" or "blocker": score += 3
+  if "should" or "important": score += 2
+  if "could" or "consider": score += 1
+
+  # Expertise weight
+  score *= task_weight[provider][task_type]
+
+Sort by score descending
+Take top 5
+```
+
+### Effort Estimation
+
+Standardize provider effort estimates to:
+- **Quick**: < 1 hour of work
+- **Short**: 1-4 hours
+- **Medium**: 1-2 days
+- **Large**: 3+ days
+
+If providers disagree on effort, use highest estimate (conservative).
+
+---
+
+## Output Structure
+
+### Required Sections
+
+1. **Header** - Mode, providers consulted
+2. **CONSENSUS** - Points all/most agree on
+3. **CONCERNS** - Valid points from any provider
+4. **DISSENT** - Conflicts with resolution
+5. **RECOMMENDATIONS** - Max 5, prioritized
+6. **VERDICTS** - Each provider's verdict
+7. **FINAL VERDICT** - Chairman's decision
+
+### Optional Sections
+
+- **WARNINGS** - If quorum not met or responses malformed
+- **NOTES** - Additional context Chairman deems relevant
+
+---
+
+## Quality Gates
+
+Before presenting synthesis, verify:
+
+- [ ] No more than 5 recommendations
+- [ ] All dissent has resolution (no "user should decide")
+- [ ] Final verdict is binary (APPROVE or REQUEST CHANGES)
+- [ ] Reasoning references specific provider input
+- [ ] No raw provider output passed through unchanged
+- [ ] Effort estimates are standardized
+
+If any gate fails, fix before presenting.
+
+---
+
+## Edge Cases
+
+### Single Provider Response
+```
+NOTE: Only [Provider] responded. This lacks council diversity.
+
+[Present provider's review directly with minimal synthesis]
+
+Consider: Run with --mode=full for comprehensive feedback.
+```
+
+### All Approve, No Recommendations
+```
+UNANIMOUS APPROVAL
+
+All providers approve this plan without significant concerns.
+
+Minor suggestions (for consideration, not required):
+[List any minor points mentioned]
+```
+
+### All Request Changes
+```
+STRONG CONSENSUS: Changes Required
+
+All providers identified issues requiring attention.
+Critical items are prioritized below.
+
+[Prioritized recommendations - may exceed 5 for critical issues]
+```