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

# 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

# Clone and install
git clone https://github.com/rob/orchestrated-discussions.git
cd orchestrated-discussions
pip install -e ".[dev]"

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

Requirements

• Python 3.10+
• 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

# 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

<!-- 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.

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.

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:

# 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 - Full architecture and SmartTool specs
• Implementation Plan - Phased development plan
• Pipeline Schema - 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