symphony-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Symphony Setup

Symphony 搭建指南

Set up Symphony — OpenAI's orchestrator that turns Linear tickets into pull requests via autonomous Codex agents.

搭建Symphony —— OpenAI推出的编排器，可通过自主Codex Agent将Linear工单转换为Pull Request。

Preflight checks

前置检查

Run these checks first and stop if any fail — resolve before continuing:

codex
— run
```
codex --version
```
. Must be installed and authenticated.
mise
— run
```
mise --version
```
. Needed for Elixir/Erlang version management.
gh
— run
```
gh auth status
```
. Must be installed AND authenticated. Agents use
```
gh
```
to create PRs and close orphaned PRs. Silent failure without it.

LINEAR_API_KEY
— run

test -n "$LINEAR_API_KEY" && echo "set" || echo "missing"

. Must persist across sessions (shell config, not just

export

Linear MCP — verify Linear MCP is available. If not, set it up:

Claude Code:

claude mcp add --transport http linear https://mcp.linear.app/mcp

Codex:

codex mcp add linear --url https://mcp.linear.app/mcp

Other clients: see Linear MCP docs

Git clone auth — the
```
after_create
```
hook runs
```
git clone
```
unattended. Verify the user's repo clone URL works non-interactively:
```
git clone --depth 1 <url> /tmp/test-clone && rm -rf /tmp/test-clone
```
. HTTPS with password prompts will silently fail. Use SSH keys (no passphrase) or HTTPS with credential helper / token.

Report results to the user before proceeding.

请先运行以下检查，若任意检查失败则停止操作——解决问题后再继续：

codex
—— 运行
```
codex --version
```
。必须已安装并完成身份验证。
mise
—— 运行
```
mise --version
```
。用于管理Elixir/Erlang版本。
gh
—— 运行
```
gh auth status
```
。必须已安装且完成身份验证。Agent会使用
```
gh
```
创建PR并关闭孤立PR，若无此工具会静默失败。
LINEAR_API_KEY
—— 运行
```
test -n "$LINEAR_API_KEY" && echo "set" || echo "missing"
```
。该密钥需在会话间持久化（配置在shell中，而非仅通过
```
export
```
临时设置）。
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文档
Git克隆权限 ——
```
after_create
```
钩子会自动运行
```
git clone
```
。请验证用户的仓库克隆URL可无交互执行：
```
git clone --depth 1 <url> /tmp/test-clone && rm -rf /tmp/test-clone
```
。带密码提示的HTTPS方式会静默失败，请使用无密码的SSH密钥，或带凭据助手/令牌的HTTPS方式。

在继续操作前，请将检查结果告知用户。

Build Symphony

构建Symphony

Use the fork — easier to get started with:

bash

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

Note:

mise install

downloads precompiled Erlang/Elixir if available for the platform. If not, it compiles from source — this can take 10-20 minutes. Let the user know before starting.

使用复刻版本 —— 更易快速上手：

bash

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分钟。开始前请告知用户。

Prepare the user's repo

准备用户的代码仓库

Auto-detect as much as possible. Only ask the user to confirm or fill gaps.

尽可能自动检测信息，仅在必要时请用户确认或补充缺失内容。

Auto-detect repo info

自动检测仓库信息

Repo path —
```
git rev-parse --show-toplevel
```
from the current directory. If not in a git repo, ask.

Clone URL —

git remote get-url origin

. Verify it works non-interactively:

git clone --depth 1 <url> /tmp/test-clone && rm -rf /tmp/test-clone

Setup commands — infer from lockfiles/manifests. Confirm with the user.

仓库路径 —— 在当前目录运行
```
git rev-parse --show-toplevel
```
。若当前不在git仓库中，请询问用户。

克隆URL —— 运行

git remote get-url origin

。请验证该URL可无交互执行：

git clone --depth 1 <url> /tmp/test-clone && rm -rf /tmp/test-clone

。

搭建命令 —— 从锁文件/清单中推断。请与用户确认。

Auto-discover Linear project

自动发现Linear项目

Use Linear MCP to list projects. Present the list and let the user pick. The

slugId

is what goes in WORKFLOW.md's

tracker.project_slug

使用Linear MCP列出所有项目。将列表展示给用户并让其选择。

slugId

需填入WORKFLOW.md的

tracker.project_slug

字段。

Auto-check and create workflow states

自动检查并创建工作流状态

After the user picks a project, use Linear MCP to check the team's workflow states. Three custom states are required. If any are missing, create them via

curl

bash

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>"}}}'

Name	Color
Rework	`#db6e1f`
Human Review	`#da8b0d`
Merging	`#0f783c`

Confirm with the user before creating.

用户选择项目后，使用Linear MCP检查团队的工作流状态。需要三个自定义状态。若缺失任意状态，可通过

curl

创建：

bash

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`

创建前请与用户确认。

Auto-detect app/UI

自动检测应用/UI

Check whether the project has a launchable UI before asking:

```
electron
```
or
```
electron-builder
```
in package.json dependencies → Electron app
```
react-scripts
```
,
```
next
```
,
```
vite
```
,
```
nuxt
```
in dependencies → web app with dev server
```
start
```
or
```
dev
```
script in package.json → likely has a dev server
```
Procfile
```
,
```
docker-compose.yml
```
→ service with runtime

If detected, propose a

launch-app

skill based on what you find (framework, start script, default port). Confirm with the user and adjust. If nothing detected, ask whether there's a UI — for pure libraries/CLIs/APIs, skip the launch skill.

在询问用户前，先检查项目是否有可启动的UI：

package.json依赖中包含
```
electron
```
或
```
electron-builder
```
→ Electron应用
依赖中包含
```
react-scripts
```
、
```
next
```
、
```
vite
```
、
```
nuxt
```
→ 带开发服务器的Web应用
package.json中有
```
start
```
或
```
dev
```
脚本 → 通常带有开发服务器
存在
```
Procfile
```
、
```
docker-compose.yml
```
→ 带运行时的服务

若检测到，请根据发现的内容（框架、启动脚本、默认端口）提议添加

launch-app

skill。请与用户确认并调整。若未检测到，请询问是否存在UI——对于纯类库/CLI/API项目，可跳过该skill。

Install skills and workflow

安装Skill与工作流

Install two things from Symphony into the user's repo:

Skills — install via skills.sh (agents need these in their workspace clone):
bash
```
cd <user's repo>
npx skills add odysseus0/symphony -a codex -s linear land commit push pull debug --copy -y
```
The
```
--copy
```
flag is required — symlinks would break in workspace clones. The
```
-s
```
flag excludes
```
symphony-setup
```
(meta-skill, not needed by workers).
elixir/WORKFLOW.md
— copy the entire file including the markdown body. The prompt body contains the state machine, planning protocol, and validation strategy that makes agents effective.

将以下两项从Symphony安装到用户的仓库中：

Skill —— 通过skills.sh安装（Agent在工作区克隆中需要这些Skill）：
bash
```
cd <user's repo>
npx skills add odysseus0/symphony -a codex -s linear land commit push pull debug --copy -y
```
```
--copy
```
参数是必需的——符号链接会在工作区克隆中失效。
```
-s
```
参数会排除
```
symphony-setup
```
（元Skill，Worker无需使用）。
elixir/WORKFLOW.md
—— 复制整个文件，包括Markdown正文。提示正文中包含状态机、规划协议和验证策略，这些是Agent高效工作的关键。

Patch WORKFLOW.md frontmatter

修补WORKFLOW.md前置内容

Two changes:

需进行两处修改：

1. Project slug

1. 项目Slug

yaml

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

yaml

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

2. after_create hook

2. after_create钩子

Replace entirely — the default clones the Symphony repo itself:

yaml

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

Leave everything else as-is. Sandbox, approval_policy, polling interval, and concurrency settings all have good defaults in the fork.

完全替换默认内容——默认钩子会克隆Symphony自身的仓库：

yaml

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

其余内容保持不变。复刻版本中的沙箱、审批策略、轮询间隔和并发设置均已配置合理的默认值。

App launch skill (if applicable)

应用启动Skill（若适用）

If the user's project has a UI or app that needs runtime testing, create

.agents/skills/launch-app/SKILL.md

in their repo:

markdown

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

若用户的项目有需要运行时测试的UI或应用，请在其仓库中创建

.agents/skills/launch-app/SKILL.md

：

markdown

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

Launch App

启动应用


The WORKFLOW.md prompt tells agents to "run runtime validation" for app-touching changes. Without this skill, agents won't know how to launch the app. For non-app repos (libraries, CLIs, APIs), skip this.

<针对用户项目的启动命令及相关搭建步骤> <验证应用是否运行的方法> <测试连接方式——例如agent-browser URL、本地端口>


WORKFLOW.md中的提示会告知Agent在涉及应用的变更时“运行运行时验证”。若无此Skill，Agent将不知道如何启动应用。对于非应用类仓库（类库、CLI、API），可跳过此步骤。

Commit and push

提交并推送

Commit

.agents/skills/

WORKFLOW.md

, and

launch-app

skill (if created) to the user's repo and push. Push is critical — agents clone from the remote, so unpushed changes are invisible to workers.

After pushing, verify:

git log origin/$(git branch --show-current) --oneline -1

should show your commit.

将

.agents/skills/

、

WORKFLOW.md

以及

launch-app

skill（若已创建）提交到用户的仓库并推送。推送操作至关重要——Agent会从远程仓库克隆代码，未推送的变更对Worker不可见。

推送后，请验证：

git log origin/$(git branch --show-current) --oneline -1

应显示你的提交记录。

Pre-launch: check active tickets

启动前：检查活跃工单

Before starting Symphony, use Linear MCP to list all tickets in active states (

Todo

In Progress

Rework

). Symphony will immediately dispatch agents for every active ticket — not just new ones.

Show the list to the user and ask if they're comfortable with all of these being worked on. Move anything they're not ready to hand off back to Backlog.

启动Symphony前，使用Linear MCP列出所有活跃状态（

Todo

、

In Progress

、

Rework

）的工单。Symphony会立即为所有活跃工单分配Agent——不仅是新工单。

请将列表展示给用户，询问是否确认所有工单都可交由Agent处理。将用户尚未准备好移交的工单移回Backlog。

Run

运行Symphony

bash

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

The guardrails flag is required — Symphony runs Codex agents with

danger-full-access

sandboxing.

Add

--port <port>

to enable the Phoenix web dashboard.

bash

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

--i-understand-that-this-will-be-running-without-the-usual-guardrails

参数是必需的——Symphony会使用

danger-full-access

沙箱模式运行Codex Agent。

添加

--port <port>

参数可启用Phoenix Web仪表盘。

Verify

验证

Have the user push a test ticket to Todo in Linear. Watch for the first worker to claim it. If it fails, run this checklist:

```
LINEAR_API_KEY
```
available in the shell running Symphony?
```
codex
```
authenticated?
```
gh auth status
```
passing?
Repo clone URL works non-interactively?
```
.agents/skills/
```
and
```
WORKFLOW.md
```
pushed to remote?
Custom Linear states (Rework, Human Review, Merging) added?

请用户在Linear中推送一个测试工单到Todo状态。观察第一个Worker是否认领该工单。若失败，请运行以下检查清单：

运行Symphony的shell中是否存在
```
LINEAR_API_KEY
```
？
```
codex
```
是否已完成身份验证？
```
gh auth status
```
是否通过？
仓库克隆URL是否可无交互执行？
```
.agents/skills/
```
和
```
WORKFLOW.md
```
是否已推送到远程仓库？
是否已添加自定义Linear状态（Rework、Human Review、Merging）？

Getting started after setup

搭建完成后的入门操作

Once Symphony is running, help the user with their first workflows:

Symphony运行后，可帮助用户完成以下初始工作流：

Break down a feature into tickets

将功能拆分为工单

The user has a big feature idea. Use Linear MCP to break it into tickets. For each ticket:

Clear title and description with acceptance criteria
Set blocking relationships where order matters
Assign to the Symphony project so agents can pick them up
Start with tickets that have no blockers in Todo

若用户有大型功能需求，使用Linear MCP将其拆分为工单。每个工单需包含：

清晰的标题和带有验收标准的描述
在有顺序要求的地方设置阻塞关系
分配到Symphony项目，以便Agent可认领
先将无阻塞的工单设置为Todo状态

First run

首次运行

Push a few tickets to Todo and watch. Walk the user through what to expect:

Idle agents claim tickets within seconds
Each agent writes a plan as a Linear comment before implementing
PRs appear on GitHub with the
```
symphony
```
label
The Linear board updates as agents move tickets through states

推送几个工单到Todo状态并观察。向用户说明预期流程：

空闲Agent会在数秒内认领工单
每个Agent在实现前会在Linear中写入计划评论
GitHub上会出现带有
```
symphony
```
标签的PR
随着Agent将工单在状态间流转，Linear看板会自动更新

Tune on the fly

实时调整

WORKFLOW.md hot-reloads within ~1 second — no restart needed. Common adjustments:

```
agent.max_concurrent_agents
```
— scale up/down based on API limits or repo complexity
```
agent.max_turns
```
— increase for complex tickets, decrease to limit token spend
```
polling.interval_ms
```
— how often Symphony checks for new/changed tickets

WORKFLOW.md支持热重载——约1秒内生效，无需重启。常见调整项：

```
agent.max_concurrent_agents
```
—— 根据API限制或仓库复杂度增减Agent数量
```
agent.max_turns
```
—— 复杂工单可增加该值，减少令牌消耗则可降低该值
```
polling.interval_ms
```
—— Symphony检查新工单/变更工单的频率