Symphony

What Symphony is

Symphony is an open specification for orchestrating fleets of AI coding agents against a ticket tracker: it polls a tracker for workable issues, dispatches them to coding-agent sessions running in parallel, tracks each agent's turns and retries, and gates how far an agent gets before a human (or another check) has to approve. It was originally written against Linear as the tracker.

orboto ships a Symphony adapter: a small set of REST endpoints, shaped exactly to what Symphony's tracker interface expects, plus a setup wizard that provisions everything a Symphony fork needs to point at your orboto workspace instead of Linear. If you're already running (or plan to run) a Symphony-based agent fleet and want it working your orboto backlog, this is the integration for that.

If you instead want orboto's own built-in agent dispatch - no separate orchestrator to run - see Work routing and fleets and Run an agent fleet instead. Symphony is for teams who are already standardized on the Symphony orchestration model and want orboto as its tracker backend.

What it connects

A Symphony fork talks to orboto through a handful of endpoints under /integrations/symphony/*, each returning data already shaped as Symphony's normalized "Issue" - priority mapped to its 1-4 integer scale, labels lower-cased, blockers joined in, and a ready-to-use git branch name computed server-side:

Status is mapped by category, not by a project's per-status display name, since names get renamed ("To Do" → "Backlog") but categories are stable across every project and instance:

Field mapping

Setup

Setup lives at Admin → Integrations → Symphony - a five-step guided wizard that replaces the manual work of creating a service account, assigning it to projects, minting an API key, and hand-writing a WORKFLOW.md config block. It's safe to re-run: it reuses an existing service account and its project memberships rather than creating duplicates.

1. Service account. Pick an existing bot/service-account user, or create a new one by entering an email and display name (a sensible default is something like symphony-bot@yourcompany.com, "Symphony"). This is the identity every Symphony-dispatched action will be attributed to.
2. Projects to authorize. Check every project you want Symphony to see. Click Apply - the wizard adds the service account to each checked project (skipping ones it's already a member of) and shows a per-project result.
3. API key. Click Mint API key. The key is shown exactly once - copy it immediately into wherever your Symphony fork's deploy environment reads ORBOTO_TOKEN from. If you navigate away before copying it, mint a new one; the old one still works until you revoke it, but its plaintext is gone for good.
4. WORKFLOW.md snippet. The wizard assembles a ready-to-use config block from what you picked in steps 1-3 - your instance's own address, the ORBOTO_TOKEN reference, and the project key(s) you authorized. Copy or Download it as WORKFLOW.md and drop it into your Symphony fork's repository (wherever your fork's config loader expects it). Replace the placeholder prompt body with your team's actual task instructions - what "done" means, branch naming, PR conventions - before you rely on it.
5. Test connection. Click Run test to confirm the service account can actually reach each authorized project through the adapter endpoints before you wire up a real Symphony deployment against it.

Choosing a starting configuration

The generated WORKFLOW.md is a reasonable default for a small-to-medium team: moderate concurrency, a 30-second poll interval, generous per-turn budgets. Depending on how your team wants to run its fleet, you may want to tune it toward one of two other shapes once you have the wizard's output as a starting point:

• Higher concurrency, AI-heavy. More agents running in parallel, longer turn budgets, and the push-triggered re-polling described below turned on so dispatch reacts to changes immediately instead of waiting for the next poll tick.
• Conservative, human-in-the-loop. A single agent at a time, manual approval required on file changes and commands, and a longer turn timeout to absorb the time a human reviewer takes without tripping Symphony's stall detection.

Both are the same WORKFLOW.md shape - the settings your Symphony fork's config schema exposes for concurrency, approval policy, and timeouts - just tuned differently. Start from what the wizard generates and adjust from there.

Usage

Once your Symphony fork is deployed with the generated config:

• On its normal poll interval (30 seconds by default), Symphony fetches candidate issues from GET /integrations/symphony/candidates and dispatches agents against whichever ones fit its concurrency limits.
• Push-triggered re-polling (optional): subscribe a webhook to the symphony.candidates_changed event (Admin → Webhooks → Add, event filter set to just that event) so your fork can flag its candidate list dirty and re-poll immediately on a status, assignee, or priority change, instead of waiting out the poll interval. This event is also available as an n8n Trigger event if you'd rather react to it from a workflow than build the listener into your fork directly.
• As agents work, each ticket they touch shows an Agent tab in its ticket detail view (once at least one lifecycle event has been recorded for it) with the session's activity - started, each turn, and how it ended - so a human glancing at the ticket sees what an agent already did without leaving orboto.
• Symphony's own dispatch loop decides claiming, status moves, comments, and PR links through the coding agent's normal tool use - the adapter only supplies read access to issue data plus the small write surface for activity events above. It never mutates a ticket's status or content directly through these endpoints itself.

Troubleshooting