Orchestrated Discussions Architecture

Discussion File Format

Discussion files are append-only markdown with structured sections:

---
id: FEAT-001
title: Add Export Feature
status: DESIGN
created: 2026-01-04
phase: design
participants:
  - architect
  - security
  - pragmatist
---

# FEAT-001: Add Export Feature

## Summary
Users need to export data to CSV and PDF formats.

---

## @architect
**2026-01-04 10:30**

We should implement a plugin architecture for exporters:

```plantuml
@startuml
interface Exporter {
  +export(data): bytes
}
class CSVExporter implements Exporter
class PDFExporter implements Exporter
@enduml

This allows easy addition of new formats without modifying core code.

VOTE: +1 (proceed with plugin architecture)

---

@security

2026-01-04 10:45

Consider these security aspects:

1. Sanitize data before export (PII removal option)
2. Rate limit exports to prevent data scraping
3. Audit log all export operations

VOTE: 0 (need clarification on data sensitivity)

---

## System Architecture

┌─────────────────────────────────────────────────────────────────────────┐ │ User │ │ (GUI / TUI / CLI / Git Hook) │ └───────────────────────────────┬─────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Orchestration Layer │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Discussion │ │ Mention │ │ Vote │ │ Status │ │ │ │ Manager │ │ Router │ │ Counter │ │ Promoter │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ └─────────┼────────────────┼────────────────┼────────────────┼────────────┘ │ │ │ │ ▼ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ CmdForge Tools │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ discussion-parser │ discussion-vote-counter │ discussion-*-agent │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ AI Provider (Claude, Codex, Gemini) │ │ │ └─────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────┐ │ Discussion Files │ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │ │ discussions/ │ │ summaries/ │ │ archives/ │ │ │ │ FEAT-001.md │ │ FEAT-001.md │ │ FEAT-000.md │ │ │ │ FEAT-002.md │ │ FEAT-002.md │ │ │ │ │ └───────────────┘ └───────────────┘ └───────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘

## Phase Workflow

┌──────────┐ ┌──────────┐ ┌───────────────┐ ┌──────────┐ ┌──────────┐ │ FEATURE │───▶│ DESIGN │───▶│IMPLEMENTATION │───▶│ TESTING │───▶│ REVIEW │ │ │ │ │ │ │ │ │ │ │ │ Define │ │ Architect│ │ Build it │ │ Verify │ │ Final │ │ problem │ │ solution │ │ │ │ │ │ approval │ └──────────┘ └──────────┘ └───────────────┘ └──────────┘ └──────────┘ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ Consensus Consensus Consensus Consensus Consensus +3 to +2 to +2 to +2 to +3 to advance advance advance advance COMPLETE

## Key Modules

| Module | Purpose |
|--------|---------|
| `discussions.parser` | Parse markdown to structured data |
| `discussions.validator` | Validate discussion format |
| `discussions.orchestrator` | Coordinate agent responses |
| `discussions.voting` | Vote counting and consensus |
| `discussions.promotion` | Status advancement logic |
| `discussions.gui` | Dear PyGui interface |
| `discussions.tui` | urwid terminal interface |

## Configuration

```yaml
# ~/.discussions/config.yml
phases:
  - name: feature
    required_votes: 3
    allowed_voters: [moderator, architect, pragmatist]

  - name: design
    required_votes: 2
    allowed_voters: [architect, security, pragmatist]

  - name: implementation
    required_votes: 2
    allowed_voters: [pragmatist, perfectionist]

personas:
  architect:
    prompt_template: architect.md
    voting_threshold: 0.7  # Conservative

  security:
    prompt_template: security.md
    voting_threshold: 0.8  # Very conservative

  pragmatist:
    prompt_template: pragmatist.md
    voting_threshold: 0.5  # Aggressive