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

```bash
# 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
# Output: Phase: initial_feedback, Votes: READY: 1, CHANGES: 2

# Interactive mode
discussions ui auth-discussion.md
```

## Installation

```bash
pip install orchestrated-discussions

# For TUI support
pip install orchestrated-discussions[tui]
```

### Requirements

- Python 3.10+
- [SmartTools](https://github.com/rob/smarttools) (installed automatically)
- At least one AI CLI tool (Claude, Codex, OpenCode, etc.)

## Quick Start

```bash
# Create your first discussion
discussions new "My Feature" --template feature

# See bundled participants
discussions participants list

# Run a turn
discussions turn my-feature.md @architect @pragmatist

# Add your own comment
discussions comment my-feature.md "I think we should..." --vote READY
```

## How It Works

1. **Discussions** are markdown files with structured comments
2. **Participants** are AI personas with distinct perspectives (architect, security, pragmatist, etc.)
3. **Phases** guide the discussion through stages (feedback → review → vote)
4. **Votes** (READY/CHANGES/REJECT) determine consensus
5. **Markers** (Q:, TODO:, DECISION:) capture structured information

## Documentation

- [Design Document](docs/DESIGN.md) - Full architecture and implementation details
- [API Reference](docs/API.md) - Python API documentation
- [Participant Guide](docs/PARTICIPANTS.md) - Creating custom personas

## 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