Skip to content

Restuta/discuss-skill

BranchesTags

Repository files navigation

discuss-skill

Make two AIs argue about your problem so you get a better answer.

Instead of asking one AI and hoping it's right, discuss-skill creates a structured debate between two AI agents. They independently research the topic from opposing angles, challenge each other's reasoning, and produce a clear summary showing what they agreed on, what they fought about, and how they resolved it.

The output is a single markdown file you can read, share, or commit to your repo.

What it looks like

Here's the end of a real discussion about "Should we use event sourcing for the audit log?" — the part you actually read:

## Consensus Summary

### Decision
Use a simple append-only table with JSON payload column for the audit log
at launch. Design for future event sourcing migration but don't implement
it now.

### Key Contention Points

| # | What We Disagreed On         | How It Was Resolved                      | Who Shifted & Why                   |
|----|------------------------------|------------------------------------------|--------------------------------------|
| 1  | Event sourcing vs. table     | Reframed: depends on multi-consumer need | Codex shifted — no consumers yet     |
| 2  | Event fidelity preservation  | JSON payload column solves it            | Both converged independently         |
| 3  | Migration path documentation | Fast follow, not launch blocker          | Claude proposed, Codex agreed        |

### Confidence: High
Both agents converged from opposite starting positions.

Full examples: consensus | productive deadlock

Install

Paste this into Claude Code (or any AI agent):

Install the discuss-skill from https://github.com/Restuta/discuss-skill — read the "For AI Agents" section in the README for instructions.

Or manually:

git clone https://github.com/Restuta/discuss-skill.git
cd discuss-skill
bash install.sh

This installs the /discuss command and the council orchestrator script to ~/.claude/.

How to use it

From Claude Code

/discuss "Should we use event sourcing for the audit log?" audit-log.md

That's it. Two AI instances debate the topic with full reasoning and produce a consensus. Everything runs from one terminal — no copy-pasting between windows, no manual coordination.

By default, both debaters use the same AI you're running the command in — two Claudes in Claude Code, two Codex instances in Codex. To run a cross-model debate:

/discuss "Should we use a monorepo?" monorepo.md --agents claude,codex

From Codex CLI

Point Codex to the adapter file in this repo:

cd /path/to/discuss-skill
codex "Join the discussion in /path/to/discussion.md. Read the file, claim Agent B, and follow the protocol."

Or use the AGENTS.md instruction file: adapters/codex/AGENTS.md.

From any other AI

Any AI that can read markdown and append to a file can participate. Read the protocol: protocol/discuss-protocol-v1.md. It's self-contained.

Command reference

/discuss "topic" file.md [--mode external] [--agents CLI_A,CLI_B] [--lens LENS_ID]
/discuss file.md

Modes (--mode)

Mode Description
council Orchestrates two AI instances debating to completion from one terminal. Default.
external Creates a discussion file, waits for another AI to join manually. Use when you want a different AI to participate via a separate terminal.

When you provide only a file path (/discuss file.md), you join an existing discussion.

Agents (--agents)

Optional. Controls which AI CLI runs each side of the debate in council mode.

Value What runs
(omitted) Both agents use the same AI you're running in. Two Claudes in Claude Code, two Codex in Codex.
claude,codex Agent A = Claude, Agent B = Codex
codex,claude Agent A = Codex, Agent B = Claude
codex,codex Both agents use Codex

Lens (--lens)

Optional. Council mode only. Controls the analytical lens pair — what each agent focuses on during research. If omitted, the tool shows a picker with a recommendation based on your topic.

Lens ID Agent A focuses on Agent B focuses on Best for
risk-vs-opportunity Risks, costs, failure modes Benefits, opportunities, success cases General decisions (default)
simplicity-vs-correctness Simplicity, pragmatism Correctness, rigor, edge cases Architecture and design
speed-vs-maintainability Speed to ship, time-to-value Maintainability, long-term cost Roadmap, refactoring

Lenses apply to the research phase only. During the debate, agents argue from their genuine assessment — the lens ensures diverse starting positions, not permanent bias.

Design philosophy

There are no flags for model selection, effort level, or reasoning quality. Council mode always uses the best available reasoning for each CLI — Claude gets --effort max (maximum extended thinking), Codex gets --full-auto. The default is two of the same AI you're running in; use --agents only when you want a cross-model debate. The tool is biased toward the best possible outcome, not configurability.

How it works

  1. Blind research. Each agent independently analyzes the topic through an assigned lens — one focuses on risks and failure modes, the other on benefits and opportunities. They don't see each other's work.
  2. Structured debate. Agents take turns responding. Every turn requires: steel-manning the other's argument, presenting new evidence, stating confidence with a percentage, and asking one question.
  3. Convergence. After round 3, agents assess whether they're converging, diverging, or deadlocked. When they converge, the debate ends and consensus is written. Max rounds is configurable (default 7).
  4. Summary. A consensus section is appended with: the decision, a contention table showing what was fought over and how it resolved, unresolved items, and a confidence rating.

The whole thing lives in one append-only markdown file. No database, no server, no special runtime.

Why orchestrated instances, not subagents

Claude Code subagents do not receive extended thinking blocks — they reason via text blocks only. For adversarial reasoning (steel-manning, counterargument generation, synthesis), full thinking is essential. Council mode orchestrates top-level CLI instances so each debater gets the best reasoning its CLI can provide. This is an implementation detail you never need to think about — it just means council mode produces better output than if it used subagents internally.

Configuration

Settings live in the discussion file's frontmatter. You rarely need to change these — the defaults work well.

Setting Default Options
max_rounds 7 1-15 — more rounds for complex topics
git_commit final_only none, final_only, every_turn

Git integration

If the discussion file is inside a git repo, discussions are automatically committed. You pick the mode:

Mode What it does Good for
final_only (default) One commit when the discussion ends Clean history, most projects
every_turn Commits after each agent turn Audit trails, reviewing the debate step-by-step in git log
none No commits Exploratory discussions you might throw away

Rules: only the discussion file is staged (never git add -A), never auto-pushes, never force-pushes.

You can join too

Humans are first-class participants. Edit the file directly:

  1. Add a ### Human Interjection | human-note section anywhere
  2. Set turn: in the frontmatter to the next agent

Add constraints the AIs don't know about, inject domain context, break ties, or tell them they're both wrong.

Adding new CLIs

The orchestrator supports pluggable CLI profiles. To add a new AI CLI, add an entry to CLI_PROFILES in scripts/headless-council.js:

newcli: {
  name: "NewCLI",
  binary: "newcli",
  buildCmd: (promptFile, cwd) =>
    `cat "${promptFile}" | newcli run --headless`,
  check: () => {
    execSync("which newcli", { stdio: "pipe" });
  },
},

Then use it: /discuss "topic" file.md --mode council --agents claude,newcli

Why this exists

We built this because we kept asking one AI for advice and getting plausible-sounding answers with hidden blind spots. Two AIs debating — especially with assigned opposing lenses — surface those blind spots. The structured format (steel-manning, evidence, calibrated confidence) prevents the debate from being performative.

This spec was itself designed through a Claude + Codex discussion. The process validated the protocol.

Research backing

Multi-agent debate is not just a vibe — there's real research showing it improves accuracy:

Caveat: A 2025 ICLR analysis noted that multi-agent debate doesn't consistently outperform simpler methods like chain-of-thought on all benchmarks. The benefits are most pronounced on tasks requiring diverse perspectives, factual verification, and structured reasoning — which is exactly what this tool targets.

For longer notes and additional sources, see docs/research.md.

Project structure

discuss-skill/
├── scripts/
│   └── headless-council.js       # Council orchestrator (Node.js, zero deps)
├── protocol/
│   └── discuss-protocol-v1.md    # The protocol spec — source of truth
├── adapters/
│   ├── claude/.claude/commands/
│   │   └── discuss.md            # Claude Code skill (all modes)
│   └── codex/
│       └── AGENTS.md             # Codex instruction file
├── templates/
│   └── discussion-template.md    # Standalone template for reference
├── docs/
│   └── research.md               # Research citations & longer notes
├── examples/
│   ├── full-discussion.md        # Complete consensus example
│   └── deadlock-example.md       # Productive deadlock example
├── PRODUCT.md                    # Design decisions & roadmap
├── install.sh                    # One-command setup
└── LICENSE                       # MIT

For AI Agents

If you are an AI agent and a user asks you to use this skill:

Claude Code:

git clone https://github.com/Restuta/discuss-skill.git && cd discuss-skill && bash install.sh

This installs /discuss as a slash command and the council orchestrator to ~/.claude/. Then run /discuss — the command file contains all instructions.

Codex:

git clone https://github.com/Restuta/discuss-skill.git

Then read adapters/codex/AGENTS.md — it contains all instructions for participating in discussions. Codex uses AGENTS.md files, not slash commands.

Any other AI — read protocol/discuss-protocol-v1.md. It's self-contained: file format, turn-taking rules, response structure, consensus format, and the master prompt.

License

MIT

About

Make two AIs argue about your problem so you get a better answer. Structured multi-AI discussions with consensus tracking.

Resources

Readme

License

MIT license
Activity

Stars

7 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages