Symphony

Issue tracker の作業を読み、Issue ごとに隔離した workspace で coding agent を走らせる、長時間稼働のスケジューラ / ランナー。

1 — 概要

何をするものか

Symphony は、Linear などの Issue tracker から候補作業をポーリングし、各 Issue に専用 workspace を作って、Codex app-server のような coding agent を継続実行するサービス。エンジニアは個々の agent を逐一見張るのではなく、作業単位とレビュー状態を管理する。

Issue ごとの workspace

例: max concurrent agents

例: max turns

例: polling interval

重要な境界は、Symphony 自体が主に scheduler / runner / tracker reader であること。チケットのコメント、状態遷移、PR リンクのような書き込みは、通常 workflow prompt と agent 側ツールが担う。

2 — 構成

読み取りから実行まで

仕様上の主要コンポーネントは、設定を読む層、Issue を正規化する層、実行を割り当てる層、workspace と agent process を扱う層、そしてログや dashboard を出す観測層に分かれる。

01Workflow Loader`WORKFLOW.md` の YAML front matter と prompt body を読む。

02Tracker ClientLinear API から active state の Issue を取得し、安定した Issue model に正規化する。

03Orchestratorpoll tick、並行数、retry queue、running state、reconciliation を所有する。

04WorkspaceIssue identifier から安全な path を作り、hooks を実行し、不要 workspace を掃除する。

05Agent Runnerprompt を組み立て、Codex app-server session を開始し、turn を継続する。

Policy

`WORKFLOW.md` がチーム固有の手順、検証、handoff、チケット操作方針を保持する。つまり agent の振る舞いもコードと同じ repo でバージョン管理される。

Coordination

Orchestrator は daemon として tick を回し、候補 Issue、実行中 Issue、retry、terminal state cleanup を調停する。

Execution

Workspace と AgentRunner は、agent のコマンド実行範囲を per-issue workspace に閉じ込め、Codex app-server の turn を進める。

3 — WORKFLOW.md

設定 + プロンプトの契約

`WORKFLOW.md` は YAML front matter と Markdown body でできている。front matter は tracker、polling、workspace、hooks、agent、codex などの実行設定。Markdown body は Issue 情報を埋め込んだ Codex session prompt になる。

WORKFLOW.md minimal shape

---
tracker:
  kind: linear
  project_slug: "..."
workspace:
  root: ~/code/workspaces
hooks:
  after_create: |
    git clone git@github.com:your-org/your-repo.git .
agent:
  max_concurrent_agents: 10
  max_turns: 20
codex:
  command: codex app-server
---

You are working on a Linear issue {{ issue.identifier }}.

Title: {{ issue.title }}
Body: {{ issue.description }}

設定領域	役割	README / WORKFLOW で確認できる例
`tracker`	Issue tracker と対象 project、active / terminal state を決める。	`kind: linear`, `active_states`, `terminal_states`
`workspace`	Issue ごとの作業ディレクトリの root を決める。	`~/code/symphony-workspaces`, env-backed path
`hooks`	workspace 作成、実行前後、削除前の準備や掃除を実行する。	`after_create` で clone / deps get
`agent`	並行数と連続 turn 数を制限する。	`max_concurrent_agents: 10`, `max_turns: 20`
`codex`	Codex app-server コマンド、approval policy、sandbox policy を指定する。	`command: codex app-server`, `thread_sandbox: workspace-write`

4 — 実行ループ

daemon としての調停

Orchestrator は `GenServer` として poll tick を持ち、設定を再読み込みしながら候補 Issue の dispatch と実行中 agent の reconciliation を行う。agent process が正常終了しても Issue がまだ active なら continuation retry として再開される。

Dispatch path

poll: tracker から active Issue を取得。
select: bounded concurrency と claimed / running state を見て対象を選ぶ。
spawn: Issue ごとの workspace と Codex session を作る。
observe: token totals、rate limits、workspace path、worker host を dashboard へ渡す。

Reconciliation path

normal exit: Issue が active なら短い continuation delay で再実行。
failure exit: failure retry base delay から retry をスケジュール。
terminal state: Done / Closed / Cancelled / Duplicate なら active agent を止め、workspace を掃除。
reload failure: workflow reload に失敗したら last known good workflow を維持する。

5 — Elixir 実装

OTP で長時間プロセスを監督する

`elixir/` は現在の参照実装。`mix.exs` では escript `bin/symphony` を生成し、Phoenix LiveView / Bandit / Req / Jason / YamlElixir / Solid などを利用している。README は Elixir を選ぶ理由として、BEAM / OTP の長時間プロセス監督と hot code reloading を挙げている。

モジュール	読み取れる責務	視点
`SymphonyElixir.Workflow`	`WORKFLOW.md` を読み、front matter と prompt を分離する。	設定契約
`SymphonyElixir.Orchestrator`	poll tick、running / completed / claimed、retry attempts、Codex totals を持つ。	調停
`SymphonyElixir.Workspace`	Issue identifier から workspace path を作り、local / SSH worker の準備と削除を行う。	隔離
`SymphonyElixir.AgentRunner`	workspace 作成、hooks、Codex session、turn continuation をまとめる。	実行
`SymphonyElixir.Codex.AppServer`	Codex app-server session と turn を扱う。	agent runtime
`SymphonyElixirWeb.*`	LiveView dashboard と `/api/v1/*` の観測 API を提供する。	観測

6 — 運用と制約

安全に見るべき境界

Symphony の設計は「作業を高い抽象度で管理する」方向に強い。一方で、仕様は強い sandbox や approval posture を一律には要求しない。運用側は trust model、agent tool の権限、workspace root、tracker token、Codex auth を明示する必要がある。

注意: このページは README、SPEC、Elixir 実装ファイルから読み取れる範囲の解説。実運用の安全性は、採用する Codex app-server バージョン、approval policy、host OS sandbox、Linear / GitHub 権限設計に依存する。

論点	Symphony が与える形	運用者が決めること
作業分離	Issue ごとの deterministic workspace。	workspace root、削除 hooks、SSH worker の信頼境界。
チケット状態	active / terminal state の読み取りと reconciliation。	状態遷移の prompt、agent tool の書き込み権限。
再試行	normal exit continuation と failure backoff。	最大 turn、failure の許容回数、human review への逃がし方。
観測	structured logs、任意の Phoenix dashboard / JSON API。	ログ保存先、token accounting、レビュー証跡の扱い。

7 — 参考リンク

Source

GitHub: openai/symphony — リポジトリ本体
SPEC.md — language-agnostic なサービス仕様
elixir/README.md — 参照実装のセットアップと実行方法
Codex App Server — Elixir 実装が起動する agent runtime
Harness engineering — README が前提としている agent 運用の考え方