swarm-discussion-skill

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# 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

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:

npx add-skill Ischca/swarm-discussion-skill

Or using the newer npx skills CLI:

npx skills add Ischca/swarm-discussion-skill

Option 2: Clone to skills directory

Clone this repository to ~/.claude/skills/:

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

Initialization: Analyze topic, generate experts with stakes & blind spots, design tension map
User Confirmation: Confirm expert composition and designed tensions
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
Next Action: Follow recommendation / Deep dive / Different angle / Inject constraint / Synthesize / Pause
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:

Genuine Disagreement
Evidence Quality
Steel-Manning
Novel Insights
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):

{
  "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