Skip to main content

​
Problem Statement

Symphony is a long-running automation service that continuously reads work from an issue tracker (Linear in this specification version), creates an isolated workspace for each issue, and runs a coding agent session for that issue inside the workspace. The service solves four operational problems:
  • It turns issue execution into a repeatable daemon workflow instead of manual scripts.
  • It isolates agent execution in per-issue workspaces so agent commands run only inside per-issue workspace directories.
  • It keeps the workflow policy in-repo (WORKFLOW.md) so teams version the agent prompt and runtime settings with their code.
  • It provides enough observability to operate and debug multiple concurrent agent runs.
Implementations are expected to document their trust and safety posture explicitly. This specification does not require a single approval, sandbox, or operator-confirmation policy; some implementations may target trusted environments with a high-trust configuration, while others may require stricter approvals or sandboxing.

​
Important Boundary

  • Symphony is a scheduler/runner and tracker reader.
  • Ticket writes (state transitions, comments, PR links) are typically performed by the coding agent using tools available in the workflow/runtime environment.
  • A successful run may end at a workflow-defined handoff state (for example Human Review), not necessarily Done.

​
Goals and Non-Goals

​
Goals

Core Goals

  • Poll the issue tracker on a fixed cadence and dispatch work with bounded concurrency
  • Maintain a single authoritative orchestrator state for dispatch, retries, and reconciliation
  • Create deterministic per-issue workspaces and preserve them across runs
  • Stop active runs when issue state changes make them ineligible
  • Recover from transient failures with exponential backoff
  • Load runtime behavior from a repository-owned WORKFLOW.md contract
  • Expose operator-visible observability (at minimum structured logs)
  • Support restart recovery without requiring a persistent database

​
Non-Goals

Out of Scope

  • Rich web UI or multi-tenant control plane
  • Prescribing a specific dashboard or terminal UI implementation
  • General-purpose workflow engine or distributed job scheduler
  • Built-in business logic for how to edit tickets, PRs, or comments (that logic lives in the workflow prompt and agent tooling)
  • Mandating strong sandbox controls beyond what the coding agent and host OS provide
  • Mandating a single default approval, sandbox, or operator-confirmation posture for all implementations

​
System Overview

​
Main Components

The Symphony service consists of the following core components:

Workflow Loader

Reads WORKFLOW.md, parses YAML front matter and prompt body, returns {config, prompt_template}

Config Layer

Exposes typed getters for workflow config values, applies defaults and environment variable indirection, performs validation

Issue Tracker Client

Fetches candidate issues, current states for reconciliation, terminal-state issues during startup cleanup, normalizes tracker payloads

Orchestrator

Owns the poll tick and in-memory runtime state, decides which issues to dispatch/retry/stop/release, tracks session metrics

Workspace Manager

Maps issue identifiers to workspace paths, ensures per-issue workspace directories exist, runs lifecycle hooks, cleans workspaces

Agent Runner

Creates workspace, builds prompt from issue + workflow template, launches the coding agent app-server client, streams agent updates

Status Surface

Optional component that presents human-readable runtime status (terminal output, dashboard, or other operator-facing view)

Logging

Emits structured runtime logs to one or more configured sinks

​
Abstraction Levels

Symphony is organized in these layers for portability:

​
External Dependencies

Symphony relies on the following external dependencies:
  • Issue tracker API: Linear for tracker.kind: linear in this specification version
  • Local filesystem: For workspaces and logs
  • Optional workspace population tooling: For example Git CLI, if used
  • Coding-agent executable: That supports JSON-RPC-like app-server mode over stdio
  • Host environment authentication: For the issue tracker and coding agent

Build docs developers (and LLMs) love

Get started for freeTalk to us