Symphony Setup SKILL.md

SKILL.md

name	symphony-setup
description	Set up and manage Symphony (Elixir) instances for different projects. Creates WORKFLOW.md, provisions directories, registers Zo managed services, and provides CLI tools for status, spawning, and admin. Reusable across any Linear-backed project.
compatibility	Created for Zo Computer
metadata	author orchestrator runtime tracker fanahova.zo.computer codex-app-server symphony-elixir linear

Symphony Setup Skill

Overview

This skill provisions and manages Symphony (Elixir/OTP) instances for different projects on this Zo Computer. Symphony is an agent orchestration runtime that polls Linear for work, creates isolated per-issue workspaces, and runs Codex in app-server mode.

One shared Symphony runtime clone at /home/workspace/symphony/elixir serves all project instances. Each project gets its own self-contained instance directory under /home/workspace/symphony-instances/<name>/ containing the cloned project repo, the per-issue workspaces, logs, and local state.

Architecture

/home/workspace/symphony/elixir              # Shared Symphony runtime (single clone)
/home/workspace/.symphony/projects.json      # Project registry

/home/workspace/symphony-instances/<name>/   # Self-contained instance
  ├── repo/                                  # Cloned project repo (WORKFLOW.md inside)
  ├── workspaces/                            # Per-issue Symphony workspaces
  ├── logs/                                  # Instance logs (incl. token-usage.jsonl)
  └── state/                                 # Local state (notification dedupe, etc.)

Prerequisites

1. Symphony runtime cloned at /home/workspace/symphony and built (mix setup && mix build).
2. Linear API key saved as LINEAR_API_KEY in Settings → Advanced.
3. Codex installed and authenticated for codex app-server mode.
4. mise available for Elixir/Erlang version management.
5. A Linear project with issues in active states (Todo, In Progress, Rework, etc.).

Quick Start

# Initialize a new Symphony instance for a project
bun /home/workspace/Skills/symphony-setup/scripts/symphony.ts init \
  --name my-project \
  --linear-slug <LINEAR_PROJECT_SLUG_ID> \
  --repo-url git@github.com:org/repo.git \
  --port 3047

# Check status of a project instance
bun /home/workspace/Skills/symphony-setup/scripts/symphony.ts status --name my-project

# Spawn work on a specific Linear issue
bun /home/workspace/Skills/symphony-setup/scripts/symphony.ts spawn --name my-project --issue PROJ-42

# List all registered projects
bun /home/workspace/Skills/symphony-setup/scripts/symphony.ts list

# Refresh/poll immediately
bun /home/workspace/Skills/symphony-setup/scripts/symphony.ts refresh --name my-project

Commands

init — Provision a new Symphony instance

Creates the WORKFLOW.md, directories, and Zo managed service for a project.

Required flags:

• --name — Project identifier (lowercase, used for directory naming and service label)
• --linear-slug — Linear project slugId (find it in the Linear project URL)
• --repo-url — Git repo URL for the hooks.after_create clone step

Optional flags:

• --port — HTTP port for the Symphony dashboard/API (default: auto-assign from 3047+)
• --max-concurrent — Max concurrent agents (default: 4)
• --max-turns — Max Codex turns per agent (default: 20)
• --poll-interval — Polling interval in ms (default: 15000)
• --approval-policy — Codex approval policy (default: never)
• --thread-sandbox — Codex thread sandbox mode (default: workspace-write)
• --danger-full-access — Use danger-full-access sandbox instead of workspace-write
• --active-states — Comma-separated active Linear states (default: Todo,In Progress,Rework)
• --terminal-states — Comma-separated terminal Linear states (default: Done,Closed,Cancelled,Canceled,Duplicate)
• --git-name — Git committer name (default: from Zo user profile)
• --git-email — Git committer email (default: from Zo user profile)
• --after-run-hook — Path to an after_run hook script (optional)
• --no-service — Create config but skip Zo service registration
• --no-startup-flags — Omit the --i-understand-that-this-will-be-running-without-the-usual-guardrails flag

This command:

1. Creates a project config entry in /home/workspace/.symphony/projects.json
2. Provisions /home/workspace/symphony-instances/<name>/{repo,workspaces,logs,state}/
3. Clones --repo-url into instance/repo/
4. Generates a WORKFLOW.md at instance/repo/WORKFLOW.md (so it is version-controlled)
5. Registers a Zo managed HTTP service (unless --no-service)

status — Check Symphony instance status

Shows running/retrying/waiting issues for a project by querying its Symphony API.

spawn — Start work on a Linear issue

Moves a Linear issue to In Progress and requests a Symphony refresh poll.

refresh — Request immediate Symphony poll

list — List all registered projects

remove — Remove a project instance

Stops the Zo service, removes directories, and deletes the project config entry.

WORKFLOW.md Template

The init command generates a WORKFLOW.md from the following template structure:

---
tracker:
  kind: linear
  api_key: $LINEAR_API_KEY
  project_slug: <LINEAR_SLUG>
  active_states: [...]
  terminal_states: [...]
polling:
  interval_ms: <INTERVAL>
workspace:
  root: /home/workspace/symphony-instances/<name>/workspaces
hooks:
  after_create: |
    gh repo clone <REPO_URL> .
    git config user.email "<GIT_EMAIL>"
    git config user.name "<GIT_NAME>"
agent:
  max_concurrent_agents: <MAX_CONCURRENT>
  max_turns: <MAX_TURNS>
codex:
  command: codex [flags] app-server
  approval_policy: <POLICY>
  thread_sandbox: <SANDBOX>
---
<prompt template>

The Markdown prompt body is generated with sensible defaults that include:

• Issue context rendering ({{ issue.identifier }}, {{ issue.title }}, etc.)
• Repository and product context (from --repo-url)
• Operating rules (work in workspace, read AGENTS.md, keep focused)
• Linear workflow rules (state transitions, workpad, PR handling)
• Engineering bar (reproduce first, test, lint, typecheck)

Customize the generated WORKFLOW.md after init to add project-specific context, product philosophy, and domain rules.

Port Allocation

Ports are allocated starting from 3047. The init command auto-selects the next available port, or you can specify one explicitly with --port. Existing project ports are tracked in the project registry to avoid collisions.

Adding a New Project — Full Workflow

1. Create a Linear project and note its slugId (from the project URL).
2. Run init with the project details.
3. Review and customize the generated WORKFLOW.md:
   • Add product-specific context and philosophy.
   • Adjust active/terminal states to match your Linear workflow.
   • Add custom hooks (e.g., after_run for notifications).
   • Tune Codex command, model, and sandbox settings.
4. Verify the Symphony service is running: check the Zo Services page.
5. Create Linear issues in the project and move them to Todo.
6. Use spawn or let Symphony poll naturally.

Customizing Per-Project

After init, the WORKFLOW.md is the primary customization surface. Common customizations:

• Prompt body: Add product context, coding conventions, domain-specific instructions.
• hooks.after_create: Add dependency installation, config setup, etc.
• hooks.after_run: Add notification scripts (see SpikeLab's notify-review-ready.ts as an example).
• codex.command: Change model, add --config flags, switch approval policy.
• agent.max_turns / max_concurrent_agents: Scale for project needs.

Existing Project: SpikeLab

SpikeLab is already registered in the project registry (port 3046):

• Instance: /home/workspace/symphony-instances/spikelab/
• Repo: /home/workspace/symphony-instances/spikelab/repo/
• Workflow: /home/workspace/symphony-instances/spikelab/repo/WORKFLOW.md
• Service: spikelab-symphony (svc_OAmAmTOeUVs)
• Skill: Skills/spikelab-cto

Troubleshooting

• Service crash-looping: Check WORKFLOW.md YAML is valid. Nested maps (like polling and workspace) must use multi-line YAML, not inline key: value syntax.
• Symphony not picking up issues: Verify LINEAR_API_KEY is set, the Linear slug is correct, and issues are in an active state.
• Agent failing: Check logs at /home/workspace/symphony-instances/<name>/logs/. Common issues: missing codex binary, stale workspaces, or Git auth failures in after_create.
• Port conflicts: Use list to see allocated ports; specify --port explicitly if needed.

File References

• Symphony spec: /home/workspace/symphony/SPEC.md
• Symphony Elixir README: /home/workspace/symphony/elixir/README.md
• Symphony runtime: /home/workspace/symphony/elixir/bin/symphony
• Project registry: /home/workspace/.symphony/projects.json