@rrr2010/opencode-roundtable 0.2.0

package/README.md

@@ -0,0 +1,198 @@
+# opencode-roundtable
+
+OpenCode plugin that orchestrates **multi-agent round-robin debates**.
+Agents with different personalities debate a topic turn by turn, sharing
+context while keeping their own system prompts and tools.
+
+A built-in observer automatically consolidates every debate into an
+executive summary.
+
+## Installation
+
+### Local (dev)
+
+```bash
+cp src/roundtable.ts ~/.config/opencode/plugins/roundtable.ts
+```
+
+Restart OpenCode. The plugin is auto-loaded from the plugins directory.
+
+### npm (coming soon)
+
+```json
+{
+  "plugin": ["@your-ns/opencode-roundtable"]
+}
+```
+
+Add to `opencode.json` — OpenCode installs it with Bun on startup.
+
+## Features
+
+- **Round-robin debate** — agents speak in sequence, each seeing the full discussion history
+- **Shared context** — tool outputs and discoveries are visible to all participants
+- **Built-in observer** — automatically consolidates the debate into an executive summary (overridable with a specific agent)
+- **Isolated session** — the debate runs in a child session, keeping the main session clean
+- **Extend mode** — continue a concluded roundtable with more rounds or a new topic
+- **Agent discovery** — `available_agents` tool helps the orchestrator know which agents exist
+- **Parallel roundtables** — multiple independent debates can run simultaneously
+- **User intervention** — the human can jump into the debate at any time
+- **Stuck session recovery** — if an extend is aborted mid-way, the next call auto-recovers
+
+## Tool API
+
+### `roundtable()`
+
+```typescript
+roundtable({
+  agents?: string[],    // Names in speaking order (min 2). Required for new debates.
+  prompt: string,       // Topic or challenge. For multi-round, include per-round instructions.
+  rounds?: number,      // Complete rounds (default: 1, max: 50)
+  observer?: string,    // Agent for final consolidation (default: built-in)
+  sessionID?: string,   // ses_xxxx — pass to extend a concluded debate
+  title?: string,       // Custom title (default: auto-generated from prompt)
+})
+```
+
+**Returns:** `{ sessionID: string, summary: string }` after the debate concludes.
+
+**Side effect:** injects system-level prompts into each agent's context (role, topic, turn routing, lifecycle signals).
+
+### `available_agents()`
+
+```typescript
+available_agents()
+```
+
+**Returns:** `"Available agents: pm, dev, rv, ..."` — a formatted string of agent names.
+
+## Usage Examples
+
+### Basic — one round, built-in observer
+
+```typescript
+roundtable({
+  agents: ["pm", "dev"],
+  prompt: "What architecture should we use?",
+})
+```
+
+### Multi-round with per-round instructions
+
+```typescript
+roundtable({
+  agents: ["pm", "dev"],
+  prompt: "Round 1: list pros. Round 2: list cons. Round 3: propose an implementation plan.",
+  rounds: 3,
+})
+```
+
+### Explicit observer
+
+```typescript
+roundtable({
+  agents: ["pm", "dev"],
+  prompt: "Should we migrate to microservices?",
+  rounds: 2,
+  observer: "rv",
+})
+```
+
+### Extend a concluded debate
+
+```typescript
+roundtable({
+  sessionID: "ses_abc123",
+  rounds: 2,
+  prompt: "Dive deeper into operational costs",
+})
+```
+
+The session ID is injected into S1 as a noReply when the roundtable starts — check S1 context to find it.
+
+### Discover agents first
+
+```typescript
+const agents = available_agents()
+// agents => "Available agents: pm, dev, rv, build, plan"
+roundtable({
+  agents: ["pm", "dev"],
+  prompt: "...",
+})
+```
+
+## Configuration
+
+Place `~/.config/opencode/roundtable.json` to override defaults:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/opencode-ai/roundtable/main/docs/roundtable.schema.json",
+  "defaultTimeoutMs": 300000,
+  "loopSimilarityThreshold": 0.85,
+  "toolOutputPreviewMax": 500,
+  "maxRounds": 10,
+  "defaultObserverPrompt": "You are an impartial roundtable observer..."
+}
+```
+
+If the file doesn't exist, it's created automatically with defaults.
+
+## Tips
+
+### Agent selection
+
+Choose agents whose expertise matches the topic:
+
+| Agent | Best for |
+|-------|----------|
+| `pm` | Product decisions, strategy, trade-offs |
+| `dev` | Technical complexity, implementation effort |
+| `rv` | Code review, docs quality, inconsistency detection |
+| `plan` | Architecture planning, scope definition |
+| `build` | Implementation details, execution |
+
+### Multi-round strategy
+
+For complex topics, structure rounds progressively:
+
+1. **Round 1:** Explore — each agent lists their perspective
+2. **Round 2:** Challenge — agents critique each other's positions
+3. **Round 3+:** Converge — propose concrete solutions
+
+Include all round instructions in the `prompt` parameter — all agents see the full agenda.
+
+### Extend mode
+
+- Use the session ID from the S1 noReply message
+- Original topic is preserved; new prompt becomes the continuation
+- Agents must be the same as the original debate
+- Continue an extend for iterative refinement
+
+## Agent colors (recommended)
+
+```json
+{
+  "agent": {
+    "pm":   { "color": "#3498db" },
+    "dev":  { "color": "#2ecc71" },
+    "rv":   { "color": "#e74c3c" },
+    "plan": { "color": "#f39c12" },
+    "build": { "color": "#9b59b6" }
+  }
+}
+```
+
+## Documentation
+
+- [docs/SPEC.md](./docs/SPEC.md) — Full technical specification
+- [docs/IMPLEMENTATION.md](./docs/IMPLEMENTATION.md) — Phased implementation plan
+
+## Requirements
+
+- OpenCode (latest version)
+- No external dependencies
+
+## License
+
+MIT