Orchestrator/shared/AI-Orchestrator

AI-Orchestrator

A Python implementation of the Symphony specification — a service that orchestrates coding agents to get project work done.

Symphony turns project work into isolated, autonomous implementation runs, allowing teams to manage work instead of supervising coding agents.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    AI-Orchestrator                        │
├─────────────────────────────────────────────────────────┤
│  Policy Layer        │ WORKFLOW.md (repo-defined)        │
│  Configuration Layer │ Typed config from front matter    │
│  Coordination Layer  │ Orchestrator (poll/dispatch)      │
│  Execution Layer     │ Workspace + Agent subprocess      │
│  Integration Layer   │ Linear adapter                    │
│  Observability Layer │ Logs + HTTP status surface        │
└─────────────────────────────────────────────────────────┘

Components

• Workflow Loader — Reads and parses WORKFLOW.md (YAML front matter + prompt template)
• Config Layer — Typed getters, defaults, env var resolution, validation
• Issue Tracker Client — Linear GraphQL adapter with pagination and normalization
• Orchestrator — Poll loop, dispatch, concurrency, retries, reconciliation
• Workspace Manager — Per-issue workspace lifecycle and hooks
• Agent Runner — Codex app-server subprocess integration
• HTTP Server — Optional REST API and dashboard for observability

Quick Start

Requirements

• Python 3.11+
• A Linear API key (set LINEAR_API_KEY env var)
• Codex CLI installed (codex app-server)

Installation

cd AI-Orchestrator
pip install -e .

Configuration

Create a WORKFLOW.md in your project root:

---
tracker:
  kind: linear
  api_key: $LINEAR_API_KEY
  project_slug: your-project-slug
polling:
  interval_ms: 30000
workspace:
  root: ~/symphony_workspaces
agent:
  max_concurrent_agents: 5
  max_turns: 20
codex:
  command: codex app-server
  approval_policy: auto-edit
  turn_timeout_ms: 3600000
---

You are working on issue {{ issue.identifier }}: {{ issue.title }}

{{ issue.description }}

{% if attempt %}
This is retry attempt {{ attempt }}. Review previous work and continue.
{% endif %}

Running

# Run with default WORKFLOW.md in current directory
ai-orchestrator

# Run with explicit workflow path
ai-orchestrator /path/to/WORKFLOW.md

# Run with HTTP server
ai-orchestrator --port 8080

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

# Type checking
mypy src/

License

Apache License 2.0