--- slug: "swarm-discussion-skill" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/ischca/swarm-discussion-skill@main/README.md" repo: "https://github.com/ischca/swarm-discussion-skill" source_file: "README.md" branch: "main" --- # swarm-discussion **Team-based + Messaging Multi-Agent Discussion Skill for Claude Code** Multiple experts launch as independent subagents and engage in "true discussions" through messaging, challenging and supplementing each other. Built-in mechanisms prevent echo chambers and ensure genuine debate. ## Features - **Team-based Architecture**: Compose teams using the Teammate API - **Messaging-based Dialogue**: Experts communicate directly with each other - **Structured Disagreement Protocol**: Prevent echo chambers through designed tension, position declarations, and steel-manning requirements - **Argument Graph**: Every claim cites or rebuts prior statements with explicit message ID references - **Quality Gates**: Automatic quality scoring prevents premature consensus - **Tension Map**: Experts are designed with structurally opposing viewpoints - **Position Shift Tracking**: Records when and why experts change their minds - **Cost-aware Modes**: Deep / Standard / Lightweight modes for different needs - **Dynamic Expert Generation**: Automatically define appropriate experts based on the topic - **Live Progress Reporting**: Real-time step-by-step updates during discussion rounds - **Complete Evidence Preservation**: Save all messages with citation chains - **Minority Report**: Dissenting views preserved even when outnumbered - **User Participation**: Use `AskUserQuestion` for direction confirmation ## Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ Discussion Team │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ Expert 1 │ │ Expert 2 │ │ Contrarian │ │Cross-Domain│ │ │ │ (subagent) │◄──────────────►│ (subagent) │◄─────────────►│ │ │ │ inbox ◄───┼──── messages ──┼──► inbox │ messages │ │ │ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ │ │ │ │ │ │ │ │ └──────────────┴──────┬───────┴──────────────┘ │ │ │ │ │ ┌─────────▼─────────┐ │ │ │ Moderator │ │ │ │ - Quality gates │ │ │ │ - Convergence │ │ │ └───────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ## Installation ### Option 1: One-command install (Recommended) Install this skill to Claude Code with a single command: ```bash npx add-skill Ischca/swarm-discussion-skill ``` Or using the newer `npx skills` CLI: ```bash npx skills add Ischca/swarm-discussion-skill ``` ### Option 2: Clone to skills directory Clone this repository to `~/.claude/skills/`: ```bash cd ~/.claude/skills git clone https://github.com/Ischca/swarm-discussion-skill.git swarm-discussion ``` Or manually place `SKILL.md` in `~/.claude/skills/swarm-discussion/`. ## Usage ``` /swarm-discussion "Microservice Transaction Management" ``` ### Discussion Modes | Mode | Experts | Rounds | Calls/Round | Use When | |------|---------|--------|-------------|----------| | **Deep** | 3-4 dynamic + 4 fixed | 3-5 | 8-12 | Unprecedented problems, high-stakes decisions | | **Standard** | 2-3 dynamic + 4 fixed | 2-3 | 5-8 | Typical design decisions, tradeoff analysis | | **Lightweight** | 2 dynamic + 2 fixed | 1-2 | 3-5 | Quick sanity checks, idea validation | ``` /swarm-discussion --mode deep "Should we rewrite the monolith?" /swarm-discussion --mode lightweight "GraphQL or REST for this API?" ``` ### Discussion Flow 1. **Initialization**: Analyze topic, generate experts with stakes & blind spots, design tension map 2. **User Confirmation**: Confirm expert composition and designed tensions 3. **Round Execution**: - All Experts: Position declarations (parallel, before seeing others) - Moderator: Frame based on actual disagreements and tension map - Dynamic Experts: Argue with citations and steel-manning (parallel) - Contrarian: Stress-test the strongest consensus - Dynamic Experts: Respond with explicit position shift tracking - Cross-Domain: Analogies addressing specific messages - Moderator: Quality gate (1-5 score) + convergence check 4. **Next Action**: Follow recommendation / Deep dive / Different angle / Inject constraint / Synthesize / Pause 5. **Synthesis**: Structured output with minority report, argument graph, and position evolution ## Key Improvements Over Basic Multi-Agent Discussion ### Echo Chamber Prevention AI agents naturally tend to agree. This skill combats that through: - **Tension Map**: Experts are designed with structurally opposing viewpoints - **Position Declarations**: Experts commit to positions BEFORE seeing others (prevents anchoring) - **Steel-Manning**: Must accurately restate opposing view before countering - **Disagreement Budget**: Moderator intervenes if agreement is too high or too low - **Contrarian targeting consensus**: Attacks the strongest agreement, not the weakest argument ### Traceability - Every message has a unique ID (`r1-msg-001`) - Arguments reference prior messages explicitly - Argument graph tracks supports/counters/extends/questions relationships - Position shifts record what triggered the change - Synthesis cites specific message IDs for every insight ### Live Progress No more waiting for a full round to finish: - After each step (position declarations, arguments, contrarian stress test, etc.), a concise summary is printed to the user - Same info is appended to `~/.claude/discussions/{id}/progress.md` for async checking - Users can follow along in real-time and decide whether to intervene early ### Quality Control Each round is scored on 5 dimensions: 1. Genuine Disagreement 2. Evidence Quality 3. Steel-Manning 4. Novel Insights 5. Position Evolution If quality drops below 3/5, the Moderator intervenes. ## Fixed Roles | Role | Responsibility | Quality Function | |------|----------------|------------------| | **Moderator** | Facilitate, enforce quality gates, determine convergence | Prevents premature consensus | | **Historian** | Build argument graph, synthesize, generate summaries | Maintains traceability | | **Contrarian** | Stress-test consensus, present counterarguments | Prevents echo chambers | | **Cross-Domain** | Provide analogies from other fields | Prevents domain-locked thinking | ## Dynamic Experts 2-4 experts are automatically generated based on the topic (count varies by mode): ```json { "id": "database-expert", "name": "Database Expert", "expertise": ["RDB", "NoSQL", "Distributed DB"], "thinkingStyle": "pragmatic", "bias": "Prioritizes practicality and performance", "stakes": "Owns the data layer; bad decisions mean data loss", "blindSpots": ["Tends to underestimate application-level complexity"] } ``` ## Evidence/Traces Discussions are saved to `~/.claude/discussions/{id}/`: ``` discussions/{id}/ ├── manifest.json # Metadata, tension map, mode ├── progress.md # Live progress log (viewable anytime) ├── personas/ # Expert definitions (with stakes & blind spots) ├── rounds/ # Messages with IDs, argument graph, position shifts ├── artifacts/ # Synthesis results │ ├── synthesis.json # Structured (with minority report) │ ├── synthesis.md │ ├── open-questions.md │ ├── argument-graph.json # Full argument graph │ └── position-evolution.md # How experts changed their minds └── context/ └── summary.md # Resume context ``` ## Use Cases - Approaches to exceed CAP theorem limitations in distributed systems - Fundamental solutions to LLM hallucination problems - Optimal approaches for legacy system modernization - High-stakes architecture decisions with competing concerns - Exploring solutions for uncharted technical challenges ## Important Notes - Each expert launches as a subagent, so **API calls increase** - Use **Lightweight mode** for quick checks (3-5 calls/round) - Use **Deep mode** only for high-stakes decisions (8-12 calls/round) - Quality over quantity: 2 rounds with genuine disagreement > 5 rounds with polite agreement ## License MIT