Polyphony, Multi-Agent Orchestration

Container-isolated workspaces for parallel agent execution. Each agent gets its own Docker container with a full git clone on its own branch. No conflicts, independent tests, clean PRs.

---

Architecture (6 Layers)

1. Work Source, Tasks from GitHub Issues (gh api) or local SQLite queue
2. Orchestrator, Supervisor loop: discover -> claim -> route -> provision -> run -> verify -> land
3. Router, Pure function: Task x Policy -> RunSpec (5-dimension complexity scoring)
4. Identity Broker, Resolves named credentials to volume mounts + env overlays
5. Workspace Manager, Per-task git clone --reference, branch checkout, cleanup
6. Worker Runtime, Docker container create/start/stop/logs lifecycle

---

Task Lifecycle

DISCOVERED -> CLAIMED -> ROUTED -> PROVISIONED -> RUNNING -> VERIFYING -> LANDED
                                                     |           |
                                                     v           v
                                                   FAILED --> BLOCKED
                                                     |
                                                     v
                                                   CLAIMED (retry)

---

Prerequisites

• Docker or OrbStack installed and running
• At least one agent CLI available (Claude, Codex, or Kimi)
• CLI subscriptions configured (not API keys)

Check:

command -v docker &>/dev/null || command -v orbctl &>/dev/null

---

Configuration

All config lives in ~/.polyphony/:

File	Purpose
config.yaml	Workspace root, poll interval, max concurrency
identities.yaml	Named credential bundles with volume paths
agents.yaml	Agent profiles (CLI commands, strengths)
routing.yaml	Routing rules and fallback chains

Initialize with: polyphony init

---

Routing Rules