symphony-setup

Symphony のセットアップ

Symphony をセットアップします。これは、Linear のチケットを自律型 Codex エージェントによってプルリクエストに変換する、OpenAI のオーケストレーターです。

事前確認

まず次の確認を実行し、いずれかに失敗した場合は中止して、続行する前に解決してください。

1. codex — codex --version を実行します。インストール済みで、認証済みである必要があります。
2. mise — mise --version を実行します。Elixir／Erlang のバージョン管理に必要です。
3. gh — gh auth status を実行します。インストール済みで、認証済みである必要があります。エージェントは gh を使って PR を作成し、残存する PR をクローズします。これがない場合、エラーが通知されずに失敗します。
4. LINEAR_API_KEY — test -n "$LINEAR_API_KEY" && echo "set" || echo "missing" を実行します。セッションをまたいで有効である必要があります（export だけでなく、シェルの設定ファイルに記述してください）。
5. Linear MCP — Linear MCP を利用できることを確認します。利用できない場合は、次の手順でセットアップしてください。
   • Claude Code：claude mcp add --transport http linear https://mcp.linear.app/mcp
   • Codex：codex mcp add linear --url https://mcp.linear.app/mcp
   • その他のクライアント：Linear MCP のドキュメントを参照してください。
6. Git クローン認証 — after_create フックは、ユーザーの操作なしで git clone を実行します。ユーザーのリポジトリのクローン URL が対話なしで機能することを確認してください：git clone --depth 1 <url> /tmp/test-clone && rm -rf /tmp/test-clone。パスワードの入力を求める HTTPS は、エラーが通知されずに失敗します。パスフレーズなしの SSH キー、または認証情報ヘルパー／トークンを使う HTTPS を使用してください。

続行する前に、結果をユーザーに報告してください。

Symphony をビルドする

始めやすいように、フォークを使用します。

git clone https://github.com/odysseus0/symphony
cd symphony/elixir
mise trust && mise install
mise exec -- mix setup
mise exec -- mix build

注：mise install は、プラットフォーム向けの Erlang／Elixir のプリコンパイル済みバイナリが利用できる場合、それらをダウンロードします。利用できない場合はソースからコンパイルするため、10～20 分かかることがあります。開始前にユーザーに知らせてください。

ユーザーのリポジトリを準備する

可能な限り自動検出し、不足している情報の確認または入力だけをユーザーに依頼してください。

リポジトリ情報を自動検出する

• リポジトリのパス — 現在のディレクトリで git rev-parse --show-toplevel を実行します。Git リポジトリ内にいない場合は、ユーザーに確認してください。
• クローン URL — git remote get-url origin を実行します。対話なしで機能することを確認してください：git clone --depth 1 <url> /tmp/test-clone && rm -rf /tmp/test-clone。
• セットアップコマンド — ロックファイル／マニフェストから推測し、ユーザーに確認してください。

Linear プロジェクトを自動検出する

Linear MCP を使ってプロジェクトを一覧表示します。リストを提示し、ユーザーに選んでもらってください。slugId は、WORKFLOW.md の tracker.project_slug に設定する値です。

ワークフローの状態を自動確認・作成する

ユーザーがプロジェクトを選んだら、Linear MCP を使ってチームのワークフローの状態を確認します。カスタム状態が 3 つ必要です。不足している状態がある場合は、curl で作成してください。

curl -s -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: $LINEAR_API_KEY" \
  -d '{"query": "mutation($input: WorkflowStateCreateInput!) { workflowStateCreate(input: $input) { success workflowState { id name } } }", "variables": {"input": {"teamId": "<team-id>", "name": "<name>", "type": "started", "color": "<color>"}}}'

名前	色
Rework	#db6e1f
Human Review	#da8b0d
Merging	#0f783c

作成する前に、ユーザーに確認してください。

アプリ／UI を自動検出する

ユーザーに尋ねる前に、プロジェクトに起動可能な UI があるか確認してください。

• package.json の依存関係に electron または electron-builder がある → Electron アプリ
• 依存関係に react-scripts、next、vite、nuxt がある → 開発サーバーを備えた Web アプリ
• package.json に start または dev スクリプトがある → 開発サーバーがある可能性が高い
• Procfile、docker-compose.yml がある → 実行環境を備えたサービス

検出できた場合は、確認結果（フレームワーク、起動スクリプト、デフォルトポート）に基づいて launch-app スキルを提案してください。ユーザーに確認し、必要に応じて調整します。何も検出されない場合は、UI があるか尋ねてください。純粋なライブラリ／CLI／API の場合は、起動スキルを省略します。

スキルとワークフローをインストールする

Symphony からユーザーのリポジトリに 2 つのものをインストールします。

1. スキル — skills.sh を使ってインストールします（エージェントはワークスペースのクローン内でこれらを必要とします）。

   cd <user's repo>
   npx skills add odysseus0/symphony -a codex -s linear land commit push pull debug --copy -y
   

   ワークスペースのクローン内でシンボリックリンクが機能しなくなるため、--copy フラグは必須です。-s フラグは symphony-setup（メタスキルで、ワーカーには不要）を除外します。
2. elixir/WORKFLOW.md — Markdown 本文を含むファイル全体をコピーします。プロンプト本文には、エージェントの効果を高める状態機械、計画プロトコル、検証戦略が含まれています。

WORKFLOW.md のフロントマターを修正する

変更は 2 つあります。

1. プロジェクトのスラッグ

tracker:
  project_slug: "<user's project slug>"

2. after_create フック

完全に置き換えます。デフォルトでは Symphony リポジトリ自体がクローンされます。

hooks:
  after_create: |
    git clone --depth 1 <user's repo clone URL> .
    <user's setup commands, if any>

それ以外はすべてそのままにしてください。 フォークのサンドボックス、approval_policy、ポーリング間隔、並行処理の設定には、適切なデフォルト値が設定されています。

アプリ起動スキル（該当する場合）

ユーザーのプロジェクトに、実行時テストが必要な UI またはアプリがある場合は、ユーザーのリポジトリに .agents/skills/launch-app/SKILL.md を作成します。

---
name: launch-app
description: Launch the app for runtime validation and testing.
---

# Launch App

<launch command and any setup steps specific to the user's project>
<how to verify the app is running>
<how to connect for testing — e.g., agent-browser URL, localhost port>

WORKFLOW.md のプロンプトでは、アプリに関わる変更に対して、エージェントに「実行時の検証を行う」よう指示しています。このスキルがないと、エージェントはアプリの起動方法が分かりません。アプリを含まないリポジトリ（ライブラリ、CLI、API）の場合は、この手順を省略してください。

コミットしてプッシュ

.agents/skills/、WORKFLOW.md、および作成した場合は launch-app スキルをユーザーのリポジトリにコミットしてプッシュします。プッシュは必須です。エージェントはリモートからクローンするため、プッシュされていない変更はワーカーから見えません。

プッシュ後に、git log origin/$(git branch --show-current) --oneline -1 を実行して確認します。コミットが表示されるはずです。

起動前：アクティブなチケットを確認

Symphony を起動する前に、Linear MCP を使ってアクティブな状態（Todo、In Progress、Rework）のチケットをすべて一覧表示します。Symphony は新しいチケットだけでなく、すべてのアクティブなチケットに対して、直ちにエージェントを割り当てます。

一覧をユーザーに見せ、これらすべての作業を開始してよいか確認します。まだ引き渡す準備ができていないチケットは、Backlog に戻します。

実行

cd <symphony-path>/elixir
mise exec -- ./bin/symphony <repo-path>/WORKFLOW.md \
  --i-understand-that-this-will-be-running-without-the-usual-guardrails

guardrails フラグは必須です。Symphony は danger-full-access サンドボックスで Codex エージェントを実行します。

Phoenix ウェブダッシュボードを有効にするには、--port <port> を追加します。

確認

ユーザーに Linear でテスト用チケットを Todo に移動してもらいます。最初のワーカーがチケットを取得するか確認します。失敗した場合は、次のチェックリストを実行します。

• Symphony を実行しているシェルで LINEAR_API_KEY を利用できますか？
• codex は認証済みですか？
• gh auth status は成功しますか？
• リポジトリのクローン URL は、対話操作なしで機能しますか？
• .agents/skills/ と WORKFLOW.md はリモートにプッシュされていますか？
• カスタムの Linear 状態（Rework、Human Review、Merging）は追加されていますか？

セットアップ後の開始方法

Symphony が稼働したら、ユーザーが最初のワークフローを進められるよう支援します。

機能をチケットに分割する

ユーザーに大きな機能のアイデアがあります。Linear MCP を使ってチケットに分割します。各チケットについて、次のようにします。

• 明確なタイトルと、受け入れ条件を含む説明を設定します
• 順序が重要な場合は、ブロック関係を設定します
• エージェントがチケットを取得できるよう、Symphony プロジェクトに割り当てます
• ブロッカーのないチケットから Todo で開始します

最初の実行

いくつかのチケットを Todo に移動し、様子を確認します。ユーザーに、次のような流れを説明します。

• 待機中のエージェントは数秒以内にチケットを取得します
• 各エージェントは実装前に、Linear のコメントとして計画を作成します
• GitHub に symphony ラベル付きの PR が作成されます
• エージェントがチケットの状態を変更すると、Linear ボードも更新されます

実行中に調整する

WORKFLOW.md の変更は約 1 秒以内にホットリロードされるため、再起動は不要です。よくある調整項目は次のとおりです。

• agent.max_concurrent_agents — API の制限やリポジトリの複雑さに応じて、同時実行数を増減します
• agent.max_turns — 複雑なチケットでは増やし、トークン消費を抑えるには減らします
• polling.interval_ms — Symphony が新規または変更済みのチケットを確認する頻度を設定します