team-discuss

Multi-agent tool for structured, multi-round discussions with dialectic analysis, random speaking order, shared state, and integration of real sub-agents for...

Team-Discuss Skill

Multi-agent collaborative discussion tool for efficient collaboration and alignment.

Features

• Multi-round discussions: Automatic progression until consensus or round limit
• Dialectical logic: Automatic citation detection, fallacy identification, argument quality assessment
• Random speaking order: Eliminates first-mover advantage
• Shared state: File-based persistence with concurrent access support
• Real agent integration: Call real sub-agents via sessions_spawn

Use Cases

1. Technology selection discussions - SQLite vs PostgreSQL, React vs Vue, etc.
2. Architecture design reviews - Multi-role collaboration (architect, frontend, backend, tester)
3. Product decision making - Feature prioritization, UX trade-offs
4. Philosophical debates - Free will vs determinism, ethics in AI, consciousness theories
5. Scientific controversies - Interpretations of quantum mechanics, origins of life
6. Policy analysis - Economic strategies, environmental policies, social reforms
7. Creative collaborations - Story plot decisions, character development, artistic direction
8. Any topic requiring multi-perspective analysis

Quick Start

1. Create Discussion

from core import SharedStore, DiscussionOrchestrator
from models import Discussion, DiscussionConfig, Participant, AgentRole

# Initialize
store = SharedStore(base_dir="./discussions")
orchestrator = DiscussionOrchestrator(store)

# Create discussion
discussion = Discussion(
    id="my-discussion-001",
    topic="Which storage layer should we use?",
    description="SQLite vs PostgreSQL technology selection",
    max_rounds=3,
    config=DiscussionConfig(consensus_threshold=0.75),
    participants=[
        Participant(agent_id="architect", role_id=AgentRole.ARCHITECT),
        Participant(agent_id="backend", role_id=AgentRole.DEVOPS),
    ]
)

store.create_discussion(discussion)

2. Define Agent Callbacks

async def agent_callback(discussion_id, round_num, previous_messages):
    # Build prompt
    prompt = build_prompt(round_num, previous_messages)
    
    # Call real agent
    response = await sessions_spawn(
        runtime="subagent",
        agentId="architect",
        mode="run",
        task=prompt
    )
    
    return response, MessageType.PROPOSAL

callbacks = {
    "architect": agent_callback,
    "backend": agent_callback,
}

3. Run Discussion

# Run discussion
result = await orchestrator.run_discussion(discussion.id, callbacks)

# View results
print(f"Status: {result.status}")
print(f"Rounds: {result.current_round}")
print(f"Consensus: {result.consensus_level}")

Dialectical Logic

Automatic Detection

from core import DialecticEngine

dialectic = DialecticEngine()
analysis = dialectic.analyze_message(message, previous_messages)

print(f"Quality: {analysis.quality}")  # strong/moderate/weak/fallacious
print(f"Score: {analysis.score}")
print(f"Citation: {analysis.has_citation}")
print(f"Fallacies: {analysis.fallacies}")

Detected Fallacy Types

• ad_hominem - Personal attack
• straw_man - Straw man fallacy
• false_dichotomy - False dilemma
• hasty_generalization - Hasty generalization
• appeal_to_authority - Appeal to authority
• slippery_slope - Slippery slope

Bias Prevention Mechanisms

1. Random Speaking Order

# First round random shuffle, subsequent rounds rotate
order = coordinator.determine_speaking_order(
    participants,
    SpeakingOrder.ROUND_ROBIN
)

2. Mandatory Citation

From round 2, agents must cite opponent's original words:

I disagree with @architect's view:
> "Choosing PostgreSQL is not premature optimization"

This statement is misleading...

3. Devil's Advocate

Assign an agent to play devil's advocate:

# Assign tester as Devil's Advocate
# Even if they agree internally, they must defend the minority position

Project Structure

team-discuss/
├── src/
│   ├── core/
│   │   ├── shared_store.py      # Shared state storage
│   │   ├── orchestrator.py      # Multi-round orchestrator
│   │   ├── dialectic.py         # Dialectical logic engine
│   │   └── coordinator.py       # Coordinator logic
│   ├── agents/
│   │   └── bridge.py            # Agent bridge
│   └── models.py                # Data models
├── examples/
│   └── run_real_discussion.py   # Real discussion example
└── tests/
    └── test_integration.py      # Integration tests

Configuration Options

DiscussionConfig

DiscussionConfig(
    max_rounds=5,                    # Maximum rounds
    min_rounds_before_consensus=2,   # Minimum rounds before consensus
    consensus_threshold=0.75,        # Consensus threshold (75% agreement)
    token_budget=50000,              # Token budget
)

Speaking Order

SpeakingOrder.FREE           # Free speaking (random)
SpeakingOrder.ROUND_ROBIN    # Round robin (recommended)
SpeakingOrder.ROLE_BASED     # Role-based priority

Examples

Technology Selection Discussion

# Run example
cd /root/.openclaw/workspace/data/projects/team-discuss
python3 examples/run_real_discussion.py

Philosophical Debate Example

# Create a philosophical discussion
discussion = Discussion(
    id="philosophy-debate-001",
    topic="Does free will exist, or is everything determined?",
    description="Philosophical debate on free will vs determinism",
    max_rounds=3,
    participants=[
        Participant(agent_id="philosopher1", role_id=AgentRole.REVIEWER),
        Participant(agent_id="scientist", role_id=AgentRole.ARCHITECT),
        Participant(agent_id="skeptic", role_id=AgentRole.TESTER),
    ]
)

Philosophical debates benefit from:

• Dialectical logic - Detects logical fallacies common in abstract reasoning
• Mandatory citation - Ensures philosophers engage with specific arguments
• Multi-round structure - Allows deep exploration of complex concepts

Sample output:

🔄 Round 1 started
💬 @architect (Architect):
   I support using PostgreSQL...
   📊 Quality: moderate (70.0 points)

💬 @backend (Backend Dev):
   I support using SQLite...
   📊 Quality: moderate (60.0 points)

✅ Round 1 ended

🔄 Round 2 started
💬 @architect:
   Responding to @backend:
   > "Premature optimization is the root of all evil"
   This statement confuses...
   📊 Quality: strong (85.0 points)
   📌 Citation: ✓

✅ Round 2 ended

✓ Discussion completed!
Final status: max_rounds_reached
Consensus level: partial

Best Practices

1. Topic Design

• Clear, specific, debatable
• Avoid overly broad topics (e.g., "what's the best technology")
• Provide necessary context

2. Agent Selection

• Cover different perspectives (architecture, dev, test, product)
• Avoid homogeneity (don't use all backend devs)
• Consider adding Devil's Advocate

3. Round Settings

• Simple topics: 2-3 rounds
• Complex topics: 5 rounds
• Set min_rounds_before_consensus to prevent premature convergence

4. Result Interpretation

• CONSENSUS_REACHED - Consensus reached, can execute directly
• MAX_ROUNDS_REACHED - Requires human judgment
• COMPLETED - Discussion ended naturally

Troubleshooting

Agent Not Responding

orchestrator = DiscussionOrchestrator(
    store=store,
    response_timeout=180  # Increase timeout
)

Version Conflicts

Shared storage uses optimistic locking, automatically retries on conflict.

Storage Location

store = SharedStore(base_dir="/path/to/discussions")

Extension Development

Custom Agent Bridge

class MyAgentBridge:
    async def generate_response(self, ...):
        # Custom calling logic
        pass

Custom Dialectic Rules

class MyDialecticEngine(DialecticEngine):
    def _detect_fallacies(self, content):
        # Add custom fallacy detection
        pass

Related Links

• Project path: /root/.openclaw/workspace/data/projects/team-discuss
• Example code: examples/run_real_discussion.py
• Integration tests: tests/test_integration.py

Version History

• v0.1.0 - Basic features: shared storage, multi-round orchestration, dialectical logic
• v0.2.0 - Real agent integration (sessions_spawn)
• v0.3.0 - CLI interface, Web UI (planned)

Roadmap

Coming Soon

Feature	Status	Description
Devil's Advocate	🚧 In Development	Auto-assign minority role, ensure opposition voices heard
Stance Change Rewards	🚧 In Development	Reward agents for rationally changing position
CLI Interface	📋 Planned	Command-line tool for creating/viewing/managing discussions
REST API	📋 Planned	HTTP API for remote calls
Web UI	📋 Planned	Visual discussion dashboard

Release Plan

• v0.2.1 - Devil's Advocate + Stance Change Rewards
• v0.3.0 - CLI Interface + REST API
• v0.4.0 - Web UI Dashboard

📦 Published to clawhub.com

---

中文简介

Team-Discuss 是一个多 Agent 协作讨论工具，支持多轮迭代、辩证逻辑分析、随机发言顺序等特性，帮助团队高效对齐方案。

核心功能

• ✅ 多轮讨论，自动推进
• ✅ 辩证逻辑，检测论证质量
• ✅ 随机发言顺序，消除偏向性
• ✅ 共享状态，持久化存储
• ✅ 真实 Agent 集成

快速开始

cd /root/.openclaw/workspace/data/skills/team-discuss
python3 example.py

项目路径

/root/.openclaw/workspace/data/projects/team-discuss/

即将发布

• 🚧 Devil's Advocate 机制
• 🚧 立场变更奖励
• 📋 CLI 接口
• 📋 REST API
• 📋 Web UI 仪表盘

📦 已发布到 clawhub.com