Stop Managing Agents. Start Managing Work.

Most teams using AI coding agents are doing it wrong. Not the code quality — the coordination layer. They're watching terminal sessions, babysitting prompts, and manually handing off context between runs. They've replaced a human developer with an AI developer, but kept all the human overhead.

OpenAI's Symphony (released this week as an engineering preview) proposes a cleaner model: manage work, not agents. Engineers interact with Linear. Symphony handles the rest. The coding agent is an implementation detail.

It's a small conceptual shift with large operational consequences. Here's why it matters — and what it would take to run like this.

The Current Pattern (And Its Cost)

Right now, the typical AI coding workflow goes: create a task, write a prompt, spawn an agent, watch it run, fix what it breaks, repeat. The engineer is the scheduler, the context-passer, the failure-handler, and the reviewer — all at once.

This doesn't scale. More agents means more terminal windows. More context means more time writing prompts. More failures means more manual restarts. You're hiring an AI engineer and giving them a human manager. The bottleneck moves from the code to the coordination.

Symphony's answer: version-control the coordination itself.

The WORKFLOW.md Primitive

The key invention in Symphony isn't the daemon or the Linear adapter. It's WORKFLOW.md.

Every repository defines its own WORKFLOW.md. This file contains two things: YAML front matter (poll intervals, concurrency limits, agent executable, timeout settings, workspace hooks) and a Markdown body (the prompt template for the coding agent, with issue variables).

---
poll_interval: 60s
workspace_root: /tmp/symphony
active_states: [In Progress, Review Requested]
terminal_states: [Done, Cancelled]
max_concurrent: 3
agent_executable: codex
agent_args: ["--model", "gpt-5"]
agent_timeout: 30m
workspace_hooks:
  setup: ./scripts/agent-setup.sh
  teardown: ./scripts/agent-teardown.sh
---

You are working on: {{ issue.title }}

## Context
{{ issue.description }}

## Blocked By
{{ issue.blocked_by }}

## Definition of Done
- Tests pass
- Types check clean
- PR description includes screenshot if UI changed
- No regressions in CI

This file lives in the repo. It's version-controlled. It gets code-reviewed like any other file. When your agent behavior needs to change — different timeout, new constraints, updated prompt — you open a PR, not a settings panel.

The Six-Layer Architecture

Symphony is more structured than it looks. Six distinct layers, each with a single responsibility:

That last layer is the one most agent setups skip. Without structured observability, you get anecdotes instead of data. "The agent seemed confused" instead of "agent failed on 4 of 7 issues in the auth module, all involving async patterns."

Issue Lifecycle: No Human in the Loop Until Review

Here's the full lifecycle from issue to merged PR — no human involved until the final step:

Linear: issue moves to "In Progress"
           ↓
Symphony polls (every 60s by default)
           ↓
Creates /workspaces/ABC-123/ (deterministic path)
           ↓
Builds prompt from issue data + WORKFLOW.md template
           ↓
Spawns Codex in app-server mode (JSON-RPC over stdio)
           ↓
Agent writes code, runs tests, opens PR, posts CI status
           ↓
Issue transitions to "Human Review"
           ↓
Engineer reviews proof of work → accept or reject

Symphony never writes to tickets or PRs directly. The coding agent does that, using the tools available in its workspace. Symphony's job is coordination — eligibility checks, concurrency limits, retries, workspace cleanup. Not code.

Proof of Work

The handoff to human review isn't just "here's a PR." Symphony's spec includes proof of work: CI status, PR review feedback, complexity analysis, and walkthrough videos.

That last item is interesting. Video walkthroughs of agent-built features, generated automatically. Until recently, this would've required a full screen recording setup. Vercel Labs released WebReel this same week — a JSON config → headless Chrome automation → MP4 pipeline with animated cursor and keystroke overlays. Symphony + WebReel closes the loop: the agent builds the feature, WebReel records the walkthrough, the engineer watches a 90-second video instead of reading a diff.

This isn't theoretical. The primitives exist. The integration is a cron job and a WORKFLOW.md hook.

Bounded Concurrency and Retry Logic

Two operational features that separate real systems from demos:

Bounded concurrency. Set max_concurrent: 3 in WORKFLOW.md and Symphony never exceeds three simultaneous agent runs regardless of how many eligible issues exist. No runaway spawning. Token costs stay predictable. Rate limits don't blow up.

Retry with exponential backoff. Transient failures — API timeouts, flaky tests, workspace setup errors — retry automatically. No human intervention needed for recoverable errors. Max retries configurable per repo. Escalate to human only when retries exhaust.

Both are table stakes for production reliability. Both are absent from most DIY agent setups.

What Symphony Deliberately Doesn't Do

As important as what it includes: Symphony has explicit non-goals. It's not a general-purpose workflow engine. It doesn't manage distributed job scheduling. It doesn't dictate how agents edit PRs or tickets (that's the agent's job). It has no built-in business logic — that lives in WORKFLOW.md.

This restraint is a feature. The more a coordination system tries to do, the more it becomes the bottleneck. Symphony coordinates. Agents implement. Issue trackers own state. Humans review.

The Harness Engineering Prerequisite

Symphony works best in codebases designed for agent editability. OpenAI calls this "harness engineering" — clear interfaces, good test coverage, predictable file structure, explicit contracts between modules.

This is worth being honest about: most codebases aren't built this way. Organic codebases have implicit conventions, tribal knowledge, and coupling that humans navigate intuitively and agents hit hard. Slapping Symphony onto a tangled repo won't produce the results the architecture promises.

The practical sequence: harness engineering first, then Symphony. This means spending time on AGENTS.md (agent-readable conventions), test coverage for critical paths, explicit API contracts, and removing magic that only works because a specific person wrote it.

It's not glamorous work. But it's the prerequisite — and it makes the codebase better for human contributors too.

Connecting to What We're Building

Right now, our agent workflow is: Connor creates a task → runs Claude Code → reviews output → merges. Symphony is what happens between "create a task" and "review output" — automated, instrumented, and version-controlled.

The near-term version of this doesn't require Symphony itself. It requires three things:

• WORKFLOW.md per repo — KaiCalls, BWK, ABP each define how their coding agent should handle issues and what proof of work looks like
• An issue queue as work queue — Linear or GitHub Issues as the source of truth, not a Slack message
• Bounded concurrency — configurable max simultaneous agents, so token costs stay predictable

The shift from "I'm going to run the agent now" to "the agent runs when an issue moves to In Progress" is mostly a mindset change. The tooling to support it — Symphony, or something equivalent built in 200 lines — exists today.

"The goal isn't faster coding. It's fewer decisions about when to start coding."

The Bigger Pattern

Symphony is a specific implementation of a broader principle: operational behavior belongs in version control.

We've learned this in infrastructure (Terraform, Kubernetes). We're learning it in AI agent behavior. The teams that treat their agent workflows as configuration to be versioned — not as prompts to be improvised — will have an advantage that compounds. When an agent run fails, they have a git diff. When a prompt needs updating, they have a PR. When something goes wrong at 3am, they have a log.

That's not magic. That's just engineering discipline applied to a new layer of the stack.