Skip to content

README.en.md

Latest commit

 

History

History
267 lines (189 loc) · 10 KB

README.en.md

File metadata and controls

267 lines (189 loc) · 10 KB
Raw

🎭 claude-discuss-kit

Multi-agent discussion kit for Claude Code

27 personas × 4 critique modes · recommendation-first customization · optional Mem0 history

🇰🇷 한국어 · 🇺🇸 English

License Status Claude Code Release Stars Bash Platform

🎉 0.2.0 is the first functional release. Real skills/discuss/SKILL.md, 9 agent definitions, and rule extracts are now installed by the bootstrap. The recommendation-first flow and 4-stage customization wizard are live. See Roadmap for what's ahead.

📑 Table of Contents

✨ Why this kit

Most multi-agent setups for Claude Code give you a fixed roster and a fixed "everyone agrees in the end" loop. This kit goes the other way:

You get What it means
9 agents (researcher / planner / coder / qa / scout / searcher / designer / docs / gitops) Real role separation, not generic "expert N"
3 personas per agent = 27 combos Conservative / Innovative / Balanced — pick per agent, per session
4 critique modes (cooperative / standard / critical / devil's-advocate) Force dissent when you need it, allow consensus when you don't
Step 0.6 recommendation-first flow Kit suggests a team setup, you accept or customize in 4 stages
SKILL_DEPTH=1 recursion guard Discussions never spiral into nested discussions
Mem0 T06 / T07 history (optional) Past consensus and counterarguments auto-injected into next discussion
Local file fallback Works without Mem0. History saved under ~/.claude/discuss-history/.

🚀 Quickstart

💻 Platform requirements Linux or macOS with Bash ≥ 4.0. macOS ships Bash 3.2 by default — install Bash 4+ via Homebrew (brew install bash) and run /opt/homebrew/bin/bash install.sh. Windows users: WSL2 recommended.

Option 1 — one-liner install (recommended)

curl -fsSL https://raw.githubusercontent.com/DaeSeokSong/claude-discuss-kit/main/install.sh | bash

This will:

  1. Check that Claude Code ≥ 2.0.0 is installed.
  2. Detect optional MCP servers (Mem0, tmux) and report status.
  3. Back up any conflicting files under ~/.claude.backup-<timestamp>/.
  4. Copy kit files into ~/.claude/.
  5. Run the smoke test.

Option 2 — clone and inspect first

git clone https://github.com/DaeSeokSong/claude-discuss-kit.git
cd claude-discuss-kit
bash install.sh --dry-run    # preview every change, write nothing
bash install.sh              # interactive install

Option 3 — Claude Code plugin

If your Claude Code build supports the plugin system:

claude plugin install https://github.com/DaeSeokSong/claude-discuss-kit

(See .claude-plugin/marketplace.json for the manifest contract.)

💬 First Discussion

After install, start any new Claude Code session and type:

/discuss "Should we use approach A or B for X?"

The kit will respond with a recommendation-first proposal:

Recommended setup
  Team: planner (critical) + qa (devil's-advocate) + coder (standard)
  Personas: conservative / balanced / balanced
  Rounds: ≤ 2
[1] Accept this setup
[2] Customize (4-stage wizard)

Stage 1 (pool) → Stage 2 (team) → Stage 3 (persona per agent) → Stage 4 (critique mode per agent).

Each stage takes seconds. You stay in control.

📦 Dependency Matrix

Dependency Required? What happens without it
Claude Code CLI ≥ 2.0.0 Yes Install aborts.
bash ≥ 4.0 Yes Install aborts. macOS users: brew install bash.
Mem0 MCP No History saved to ~/.claude/discuss-history/ instead.
tmux No Panel visualizations disabled, text-only output.
Tavily MCP No searcher agent falls back to WebFetch / WebSearch.
Atlassian MCP No docs agent can only write local markdown.

Install detects each optional dep and prints a one-line status. No silent failures.

🎭 Persona Catalog (preview)

Full catalog ships in claude/rules/agent-personas.md. Sketch:

Agent Conservative Innovative Balanced
researcher citation-strict novelty-seeking tradeoff-mapper
planner risk-averse ambitious-scope phased-rollout
coder defensive-coding refactor-eager minimal-diff
qa regression-paranoid edge-case-hunter coverage-balanced
scout precise-grep wide-search layered-lookup
searcher high-precision-low-recall broad-survey source-diverse
designer accessibility-first novel-visual clarity-balanced
docs strict-template narrative structured-narrative
gitops clean-history rapid-merge feature-flag-aware

⚔️ Critique Modes

Mode When to use
cooperative Brainstorming — agents build on each other.
standard Default — agents disagree where reasonable, converge where possible.
critical Stress-test — agents must surface at least one risk per round.
devil's-advocate Forced dissent — at least one agent must oppose the consensus. Useful for architecture decisions and pre-mortems.

Set per agent. You can mix (e.g., coder=standard, qa=devil's-advocate, planner=critical).

📁 What gets installed (0.2.0)

~/.claude/
├── skills/discuss/SKILL.md           # ~790 lines — full recommendation-first flow + 4-stage wizard
├── commands/discuss.md               # thin wrapper
├── agents/
│   ├── INDEX.md                      # 10-line catalog
│   ├── researcher.md / planner.md / coder.md / qa.md
│   ├── scout.md / searcher.md / designer.md / docs.md / gitops.md
├── rules/
│   ├── agent-routing.md              # TeamCreate vs Agent decision, SKILL_DEPTH guard
│   └── agent-personas.md             # 27 personas × 4 critique modes
└── rules-lazy/
    └── mem0-templates.md             # T06 (save consensus) + T07 (search prior) + local fallback

Total: 15 files, ~2700 lines. Run install.sh --dry-run to see exactly what would change before any write.

🗑️ Uninstall

bash uninstall.sh                              # remove only kit files
bash uninstall.sh --restore ~/.claude.backup-* # restore the backup taken by install

uninstall.sh only touches files this kit ships. Your other ~/.claude/ content is left alone.

🗺️ Roadmap

Version Scope Status
0.1.1 Skeleton, license, bootstrap, manifest, smoke-test, Bash 4+ guard ✅ Released
0.2.0 Real SKILL.md, 9 agent definitions, persona catalog, critique modes, Mem0 T06/T07 templates ✅ Released
0.3.0 Examples gallery, history viewer, Mem0 fallback polish, persona auto-tuning 🚧 Next
0.4.0 tmux panel mode, video demos, multilingual prompt templates 📋 Planned
0.5.0 Plugin marketplace listing, optional Tavily/Atlassian adapters 📋 Planned
1.0.0 Stability freeze, semver guarantee, contributor guide 🎯 Target

📚 Examples

examples/ will grow with curated discussion transcripts (ship in 0.3.0):

  • architecture-discussion.md — picking a baseline before committing
  • code-review-discussion.md — qa devil's-advocate vs coder
  • paper-critique.md — researcher + searcher + qa on a paper claim
  • hyperparameter-debate.md — planner phased-rollout vs coder refactor-eager

🤝 Contributing

Issues and PRs welcome. For feedback on 0.2.0, open an issue with the feedback-0.2.0 label.

Local dev

git clone https://github.com/DaeSeokSong/claude-discuss-kit.git
cd claude-discuss-kit
bash install.sh --dry-run            # never writes anything
bash tests/smoke-test.sh /tmp/fake   # smoke test against a throwaway dir

📜 License

Apache License 2.0. See NOTICE for attribution.

🙏 Acknowledgements

Built on top of patterns from the Claude Code agent ecosystem. Inspired by:

  • Anthropic's "Building effective agents" engineering writeups
  • Multi-agent coordination protocols in CrewAI and AutoGen
  • Devil's advocate practices in software pre-mortem reviews

The recommendation-first + 4-stage customization flow is original to this kit.

Made with Claude Code by @DaeSeokSong

If this kit saves you a few "but did everyone really agree?" minutes, star the repo so others can find it. ⭐