# digilogd-cmd/ai-dev-director architecture

> Architecture diagram of the GitHub repository digilogd-cmd/ai-dev-director, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/digilogd-cmd/ai-dev-director
- Repository: https://github.com/digilogd-cmd/ai-dev-director

## Overview

AI DEV DIRECTOR turns a user goal into an ORDER, has AI CLI roles propose and review code, verifies changes in an isolated Git worktree, then exposes passing results for explicit human handling. It also supports milestone missions, autonomous recovery, TRIAD research, and a local console. The graph preserves these distinct product branches and the shared safety, provider, process, and persistence layers. Some subsystem details come from README or source-index references rather than inspected implementation excerpts; those edges are cited accordingly.

Main entry points: [`core/orchestrator.py`](https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/orchestrator.py) (Run Orchestrator), [`core/process_runner.py`](https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/process_runner.py) (CLI Process Runner), [`core/mission.py`](https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/mission.py) (Mission Planner), [`director.py`](https://github.com/digilogd-cmd/ai-dev-director/blob/main/director.py) (CLI Commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["CLI Commands<br/>[director.py]"]
  node_console_server["Console Server"]
  node_dashboard["Classic Dashboard"]
  node_trinity["TRINITY Console<br/>[trinity.js]"]
end

subgraph group_workflow["Build Workflow"]
  node_orchestrator["Run Orchestrator<br/>[orchestrator.py]"]
  node_mission["Mission Planner<br/>[mission.py]"]
  node_head["HEAD Roles<br/>[claude_head.py]"]
  node_order["ORDER Schema<br/>[order.py]"]
  node_builder["File Builder"]
  node_reviewer["Independent Reviewers<br/>[claude_reviewer.py]"]
  node_worktree["Git Worktrees<br/>[git_manager.py]"]
  node_verifier["Build Verifier<br/>[verifier.py]"]
  node_result["Result Handling<br/>[result_manager.py]"]
end

subgraph group_research["Research Mode"]
  node_research["TRIAD Research"]
  node_research_runner["Research Runner<br/>[research_runner.py]"]
end

subgraph group_runtime["AI Runtime"]
  node_provider["Provider Failover"]
  node_process["CLI Process Runner<br/>[process_runner.py]"]
  node_usage["Usage Ledger<br/>[usage.py]"]
end

subgraph group_platform["Safety and State"]
  node_scope_guard["Scope Guard<br/>[safety.py]"]
  node_autopilot["Autonomy Policy<br/>[autopilot.py]"]
  node_state[("Run State<br/>[state_machine.py]")]
end

node_user(("User"))
node_ai_clis["Subscription AI CLIs"]

node_user -->|"starts run"| node_cli
node_cli -->|"starts run"| node_orchestrator
node_cli -->|"starts mission"| node_mission
node_user -->|"uses console"| node_console_server
node_trinity -.->|"sends requests"| node_console_server
node_console_server -->|"serves operations"| node_dashboard
node_dashboard -->|"starts runs"| node_orchestrator
node_dashboard -->|"controls missions"| node_mission
node_mission -->|"runs milestones"| node_orchestrator
node_orchestrator -->|"requests plan"| node_head
node_head -->|"produces ORDER"| node_order
node_orchestrator -->|"requests files"| node_builder
node_orchestrator -->|"requests review"| node_reviewer
node_orchestrator -->|"checks scope"| node_scope_guard
node_orchestrator -->|"creates worktree"| node_worktree
node_orchestrator -->|"runs verification"| node_verifier
node_orchestrator -->|"checks autonomy"| node_autopilot
node_orchestrator -->|"records run"| node_state
node_user -->|"handles PASS"| node_result
node_result -->|"applies or discards"| node_worktree
node_research -->|"runs research"| node_research_runner
node_research -->|"implements experiment"| node_orchestrator
node_orchestrator -->|"selects provider"| node_provider
node_provider -->|"resolves CLI"| node_process
node_head -->|"invokes CLI"| node_process
node_builder -->|"invokes CLI"| node_process
node_reviewer -->|"invokes CLI"| node_process
node_process -->|"runs commands"| node_ai_clis
node_process -->|"records calls"| node_usage
node_mission -->|"persists progress"| node_state
node_provider -->|"stores health"| node_state

click node_cli "https://github.com/digilogd-cmd/ai-dev-director/blob/main/director.py"
click node_console_server "https://github.com/digilogd-cmd/ai-dev-director/blob/main/companion_server.py"
click node_dashboard "https://github.com/digilogd-cmd/ai-dev-director/blob/main/dashboard_server.py"
click node_trinity "https://github.com/digilogd-cmd/ai-dev-director/blob/main/console/trinity.js"
click node_orchestrator "https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/orchestrator.py"
click node_mission "https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/mission.py"
click node_head "https://github.com/digilogd-cmd/ai-dev-director/blob/main/agents/claude_head.py"
click node_order "https://github.com/digilogd-cmd/ai-dev-director/blob/main/schemas/order.py"
click node_builder "https://github.com/digilogd-cmd/ai-dev-director/blob/main/agents/proposal_builder.py"
click node_reviewer "https://github.com/digilogd-cmd/ai-dev-director/blob/main/agents/claude_reviewer.py"
click node_scope_guard "https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/safety.py"
click node_worktree "https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/git_manager.py"
click node_verifier "https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/verifier.py"
click node_result "https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/result_manager.py"
click node_autopilot "https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/autopilot.py"
click node_research "https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/research_orchestrator.py"
click node_research_runner "https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/research_runner.py"
click node_provider "https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/provider_manager.py"
click node_process "https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/process_runner.py"
click node_usage "https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/usage.py"
click node_state "https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/state_machine.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_console_server,node_dashboard,node_trinity,node_user toneBlue
class node_orchestrator,node_mission,node_head,node_order,node_builder,node_reviewer,node_worktree,node_verifier,node_result toneAmber
class node_research,node_research_runner toneMint
class node_provider,node_process,node_usage toneRose
class node_scope_guard,node_autopilot,node_state,node_ai_clis toneIndigo
```

## Components

### User Interfaces

- [CLI Commands](https://github.com/digilogd-cmd/ai-dev-director/blob/main/director.py): `director.py`
- [Console Server](https://github.com/digilogd-cmd/ai-dev-director/blob/main/companion_server.py): `companion_server.py`
- [Classic Dashboard](https://github.com/digilogd-cmd/ai-dev-director/blob/main/dashboard_server.py): `dashboard_server.py`
- [TRINITY Console](https://github.com/digilogd-cmd/ai-dev-director/blob/main/console/trinity.js): `console/trinity.js`

### Build Workflow

- [Run Orchestrator](https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/orchestrator.py): `core/orchestrator.py`
- [Mission Planner](https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/mission.py): `core/mission.py`
- [HEAD Roles](https://github.com/digilogd-cmd/ai-dev-director/blob/main/agents/claude_head.py): `agents/claude_head.py`
- [ORDER Schema](https://github.com/digilogd-cmd/ai-dev-director/blob/main/schemas/order.py): `schemas/order.py`
- [File Builder](https://github.com/digilogd-cmd/ai-dev-director/blob/main/agents/proposal_builder.py): `agents/proposal_builder.py`
- [Independent Reviewers](https://github.com/digilogd-cmd/ai-dev-director/blob/main/agents/claude_reviewer.py): `agents/claude_reviewer.py`
- [Git Worktrees](https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/git_manager.py): `core/git_manager.py`
- [Build Verifier](https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/verifier.py): `core/verifier.py`
- [Result Handling](https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/result_manager.py): `core/result_manager.py`

### Research Mode

- [TRIAD Research](https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/research_orchestrator.py): `core/research_orchestrator.py`
- [Research Runner](https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/research_runner.py): `core/research_runner.py`

### AI Runtime

- [Provider Failover](https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/provider_manager.py): `core/provider_manager.py`
- [CLI Process Runner](https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/process_runner.py): `core/process_runner.py`
- [Usage Ledger](https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/usage.py): `core/usage.py`

### Safety and State

- [Scope Guard](https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/safety.py): `core/safety.py`
- [Autonomy Policy](https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/autopilot.py): `core/autopilot.py`
- [Run State](https://github.com/digilogd-cmd/ai-dev-director/blob/main/core/state_machine.py): `core/state_machine.py`

### Other components

- **User**
- **Subscription AI CLIs**

## Connections

- User → CLI Commands: starts run
- CLI Commands → Run Orchestrator: starts run (evidence: `director.py`)
- CLI Commands → Mission Planner: starts mission (evidence: `director.py`)
- User → Console Server: uses console
- TRINITY Console → Console Server: sends requests
- Console Server → Classic Dashboard: serves operations (evidence: `companion_server.py`)
- Classic Dashboard → Run Orchestrator: starts runs (evidence: `dashboard_server.py`)
- Classic Dashboard → Mission Planner: controls missions (evidence: `dashboard_server.py`)
- Mission Planner → Run Orchestrator: runs milestones
- Run Orchestrator → HEAD Roles: requests plan (evidence: `core/orchestrator.py`)
- HEAD Roles → ORDER Schema: produces ORDER (evidence: `agents/claude_head.py`)
- Run Orchestrator → File Builder: requests files (evidence: `core/orchestrator.py`)
- Run Orchestrator → Independent Reviewers: requests review (evidence: `core/orchestrator.py`)
- Run Orchestrator → Scope Guard: checks scope (evidence: `core/orchestrator.py`)
- Run Orchestrator → Git Worktrees: creates worktree (evidence: `core/orchestrator.py`)
- Run Orchestrator → Build Verifier: runs verification (evidence: `core/orchestrator.py`)
- Run Orchestrator → Autonomy Policy: checks autonomy (evidence: `core/orchestrator.py`)
- Run Orchestrator → Run State: records run (evidence: `core/orchestrator.py`)
- User → Result Handling: handles PASS
- Result Handling → Git Worktrees: applies or discards (evidence: `core/result_manager.py`)
- TRIAD Research → Research Runner: runs research (evidence: `core/research_orchestrator.py`)
- TRIAD Research → Run Orchestrator: implements experiment
- Run Orchestrator → Provider Failover: selects provider (evidence: `core/orchestrator.py`)
- Provider Failover → CLI Process Runner: resolves CLI (evidence: `core/provider_manager.py`)
- HEAD Roles → CLI Process Runner: invokes CLI (evidence: `agents/claude_head.py`)
- File Builder → CLI Process Runner: invokes CLI (evidence: `agents/proposal_builder.py`)
- Independent Reviewers → CLI Process Runner: invokes CLI (evidence: `agents/claude_reviewer.py`)
- CLI Process Runner → Subscription AI CLIs: runs commands
- CLI Process Runner → Usage Ledger: records calls (evidence: `core/process_runner.py`)
- Mission Planner → Run State: persists progress (evidence: `core/mission.py`)
- Provider Failover → Run State: stores health (evidence: `core/provider_manager.py`)