orchestrated-discussions/README.md

# Orchestrated Discussions

**Multi-agent AI discussion orchestration with voting and phases.**

Conduct structured discussions between multiple AI personas, each with distinct perspectives, expertise, and voting behavior. Built on the Unix philosophy - each component is a composable SmartTool that can be tested and debugged independently.

## Key Features

- **Structured Discussions**: Append-only markdown files with metadata, comments, and markers
- **AI Participants**: Customizable personas (architect, security, pragmatist, etc.)
- **Phase-based Workflows**: Templates define discussion phases with different goals
- **Voting & Consensus**: READY/CHANGES/REJECT votes with configurable thresholds
- **Dual UI**: Both graphical (Dear PyGui) and terminal (urwid) interfaces
- **Unix Philosophy**: All logic lives in SmartTools, Python layer is thin orchestration

## Quick Start

```bash
# Install in development mode
pip install -e ".[dev]"

# Create a discussion
discussions new "Add user authentication" --template feature

# Run a turn with specific participants
discussions turn auth-discussion.md @architect @security @pragmatist

# Check status
discussions status auth-discussion.md

# Add a human comment with vote
discussions comment auth-discussion.md "Looks good to me" --vote ready

# Launch interactive UI (GUI by default)
discussions ui

# Or use terminal UI
discussions ui --tui
```

## Installation

```bash
# Clone and install
git clone https://gitea.brrd.tech/rob/orchestrated-discussions.git
cd orchestrated-discussions
pip install -e ".[dev]"

# For TUI support only
pip install -e ".[tui]"
```

## Docker

Run without installing anything locally (dependencies fetched automatically):

```bash
# Clone the repo
git clone https://gitea.brrd.tech/rob/orchestrated-discussions.git
cd orchestrated-discussions

# Build (automatically clones SmartTools from Gitea)
docker-compose build

# Run tests
docker-compose run --rm test

# Use the CLI
docker-compose run --rm cli discussions participants
docker-compose run --rm cli discussions status examples/brainstorm_notification_system.discussion.md

# Interactive shell
docker-compose run --rm shell
```

### Requirements

- Python 3.10+
- [SmartTools](https://gitea.brrd.tech/rob/SmartTools) (installed automatically)
- At least one AI CLI tool (Claude, Codex, etc.)

## How It Works

1. **Discussions** are markdown files with structured comments and metadata
2. **Participants** are AI personas implemented as SmartTools
3. **Phases** guide discussion through stages (feedback -> review -> vote)
4. **Votes** (READY/CHANGES/REJECT) determine consensus
5. **Markers** (Q:, TODO:, DECISION:, CONCERN:) capture structured information

### Architecture

```
User/CLI/UI
    │
    ▼
┌──────────────────────────────────────────┐
│          Orchestrated Discussions         │
│  - Thin orchestration layer (runner.py)  │
│  - File I/O, turn sequencing             │
│  - Calls SmartTools via subprocess       │
└────────────────────┬─────────────────────┘
                     │ stdin/stdout
                     ▼
┌──────────────────────────────────────────┐
│         SmartTools (discussion-*)        │
│                                          │
│  Utility:      parser, validator         │
│  Orchestration: vote-counter, router     │
│  Participants: architect, security, etc. │
└────────────────────┬─────────────────────┘
                     │
                     ▼
              AI Providers (claude, etc.)
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `discussions new <title>` | Create a new discussion file |
| `discussions status <file>` | Show discussion status, votes, and consensus |
| `discussions turn <file> [@participants]` | Run a discussion turn |
| `discussions comment <file> <text>` | Add a human comment |
| `discussions participants` | List available participant SmartTools |
| `discussions advance <file> --phase <id>` | Advance to a specific phase |
| `discussions ui [directory]` | Launch interactive UI |

### Examples

```bash
# Create feature discussion
discussions new "Add caching layer" --template feature -c "We need to improve API response times"

# Create brainstorm session
discussions new "Notification System Design" --template brainstorm

# Run turn with all participants
discussions turn my-feature.md

# Run turn with specific participants
discussions turn my-feature.md @architect @security

# Add human comment with vote
discussions comment my-feature.md "I agree with the concerns" --vote changes

# Check consensus status
discussions status my-feature.md
```

## Templates

Templates define the workflow phases for different discussion types.

### Feature Template (3 phases)

| Phase | Goal | Voting |
|-------|------|--------|
| `initial_feedback` | Gather diverse perspectives | No |
| `detailed_review` | Deep dive into implementation | No |
| `consensus_vote` | Reach agreement | Yes (67% READY) |

### Brainstorm Template (6 phases)

| Phase | Goal | Voting |
|-------|------|--------|
| `seed` | Frame the problem | No |
| `diverge` | Generate ideas freely | No |
| `cluster` | Group ideas into themes | Yes (50% READY) |
| `sketch` | Create rough diagrams | No |
| `reality_check` | Ground in reality | No |
| `decide` | Commit to approach | Yes (67% READY) |

## Bundled SmartTools

### Utility Tools (code-only)

| Tool | Purpose |
|------|---------|
| `discussion-parser` | Extract structured JSON from discussion markdown |
| `discussion-validator` | Validate discussion format |
| `discussion-summarizer` | Generate summary files (AI) |

### Orchestration Tools (code-only)

| Tool | Purpose |
|------|---------|
| `discussion-vote-counter` | Count votes, determine consensus |
| `discussion-mention-router` | Route @mentions to participants |
| `discussion-status-promoter` | Check status transitions |
| `discussion-turn-appender` | Append responses to discussion |
| `discussion-config` | Modify discussion metadata |

### Participant Tools (AI)

| Tool | Alias | Perspective |
|------|-------|-------------|
| `discussion-architect` | `@architect` | Systems thinking, scalability |
| `discussion-security` | `@security` | Threat modeling, vulnerabilities |
| `discussion-pragmatist` | `@pragmatist` | MVP focus, shipping velocity |
| `discussion-moderator` | `@moderator` | Facilitation, phase management |
| `discussion-diagram-editor` | `@diagram-editor` | PlantUML diagram creation |

## Discussion File Format

```markdown
<!-- DISCUSSION -->
<!-- Title: Feature X Implementation -->
<!-- Phase: initial_feedback -->
<!-- Status: OPEN -->
<!-- Template: feature -->
<!-- Participants: architect, security, pragmatist -->

# Feature X Implementation

## Context
We need to implement feature X that allows users to...

---

Name: AI-Architect
Looking at this from a systems perspective...

Q: Have we considered using the adapter pattern here?
@pragmatist What's your view on complexity vs. speed?

VOTE: CHANGES

---

Name: Human
I agree with the architect's concerns.

VOTE: READY

---
```

### Markers

| Marker | Purpose | Example |
|--------|---------|---------|
| `VOTE:` | Cast a vote | `VOTE: READY` |
| `Q:` | Ask a question | `Q: What about caching?` |
| `TODO:` | Action item | `TODO: Research rate limits` |
| `DECISION:` | Record decision | `DECISION: Use PostgreSQL` |
| `CONCERN:` | Raise concern | `CONCERN: Security implications` |
| `DIAGRAM:` | Reference diagram | `DIAGRAM: diagrams/flow.puml` |
| `@alias` | Mention participant | `@security What do you think?` |

## User Interfaces

### GUI (Default)

Built with Dear PyGui for native graphics support.

```bash
discussions ui
# or
python -m src.discussions.ui
```

**Features:**
- Native image viewing for PlantUML diagrams
- Split-pane diagram viewer (source + rendered)
- Tabbed interface for discussions, diagrams, output
- **Read/Stop button** on each comment for TTS (changes to "Stop" while reading)

**Keyboard Shortcuts:**
| Key | Action |
|-----|--------|
| `Q` | Quit |
| `R` | Refresh |
| `T` | Run turn |
| `C` | Add comment |
| `D` | View diagrams |
| `Esc` | Close dialogs |

### TUI (Terminal)

Built with urwid for terminal-only environments.

```bash
discussions ui --tui
# or
python -m src.discussions.ui --tui
```

**Features:**
- ASCII diagram preview via `plantuml -tutxt`
- Works over SSH, no X11 required
- Lightweight dependencies
- **Read/Stop button** on each comment for TTS (toggles while reading)

**Keyboard Shortcuts:**
| Key | Action |
|-----|--------|
| `q` | Quit |
| `r` | Run turn |
| `d` | View diagrams |
| `Up/Down` | Navigate |
| `Enter` | Select |
| `Esc` | Close dialogs |

## Testing SmartTools Directly

The Unix philosophy means you can test each tool independently:

```bash
# Parse a discussion
cat examples/brainstorm_notification_system.md | discussion-parser | jq .

# Count votes
cat examples/voted_discussion.md | discussion-parser | discussion-vote-counter

# Route mentions
cat examples/feature_discussion.md | discussion-parser | discussion-mention-router

# Full pipeline manually
./scripts/run-turn.sh examples/feature_discussion.md
```

## Project Structure

```
orchestrated-discussions/
├── src/discussions/
│   ├── cli.py           # CLI entry point
│   ├── discussion.py    # Discussion model, file I/O
│   ├── markers.py       # Marker parsing (VOTE, Q, TODO, etc.)
│   ├── participant.py   # Participant discovery from ~/.smarttools/
│   ├── runner.py        # Turn orchestration (calls SmartTools)
│   ├── voting.py        # Consensus calculation
│   └── ui/
│       ├── gui.py       # Dear PyGui interface
│       ├── tui.py       # urwid terminal interface
│       └── widgets.py   # Shared UI components
├── smarttools/          # Bundled SmartTool configs
├── templates/           # Discussion workflow templates
├── examples/            # Example discussion files
├── scripts/             # Manual orchestration scripts
├── tests/               # pytest tests
└── docs/                # Design documentation
```

## Documentation

- [Design Document](docs/DESIGN.md) - Full architecture and SmartTool specs
- [Implementation Plan](docs/IMPLEMENTATION.md) - Phased development plan
- [Pipeline Schema](docs/PIPELINE_SCHEMA.md) - Turn pipeline configuration

## Project Context

This is part of a three-project ecosystem:

1. **SmartTools** - AI provider abstraction and tool execution
2. **Orchestrated Discussions** (this project) - Multi-agent conversation orchestration
3. **CascadingDev** - Git-driven automation (uses both above)

## License

MIT