feat: Symphony handoff target — emit WORKFLOW.md aligned with OpenAI's spec

[mabry1985]

Summary

Adds a third handoff target alongside filesystem and linear: Symphony, the OpenAI open-source orchestration spec released April 2026. Symphony turns project work into autonomous coding-agent runs by polling an issue tracker and dispatching Codex sessions into isolated per-issue workspaces.

The architecture: our system becomes the planning + outcomes layer; Symphony becomes the execution layer; Linear (or a future filesystem-tracker extension) is the wire between them. This is slice 1 of a 3-slice plan toward a full project management app — see docs/explanation/symphony-alignment.md for the full roadmap.

What this PR ships

• server/src/handoff/symphony.ts — spec-compliant WORKFLOW.md renderer. YAML front matter with tracker / polling / workspace / hooks / agent / codex blocks per Symphony spec §5.3. Liquid prompt template embedding our standing decisions, scope, and per-issue instructions that point the agent at the repo's dr/ context.
• dr_export_symphony MCP tool — writes WORKFLOW.md, optionally pushes tasks to Linear first (so the WORKFLOW.md can target the resulting Linear project), finalizes handoff with target='symphony'.
• Orchestrator integration — wires Symphony as the preferred option in the handoff phase when LINEAR_API_KEY is set. Falls back to Linear-only or filesystem when the user declines. CLI flow stays backward-compatible when LINEAR_API_KEY is absent.
• HandoffRecordSchema gains target='symphony' and a workflow_path field.
• Tests — 11 new (5 unit + 6 flow). Total now 100 tests (83 unit + 17 flow).
• Docs — docs/how-to/handoff-to-symphony.md, docs/explanation/symphony-alignment.md (the 3-slice roadmap), updates to research-notes.md, mcp-tools.md, README.md, and the docs index.

The 3-slice roadmap (sequenced, only slice 1 in this PR)

1. Symphony handoff target — this PR. Smallest delta, biggest near-term leverage.
2. Filesystem tracker extension — propose to Symphony upstream. Lets Symphony poll our dr/tasks/ directly instead of going through Linear. No external system required.
3. Status surface — consume Symphony's GET /api/v1/state and render running/retrying/done state alongside decisions and outcomes in our dr/index.html. Closes the operator loop.

What this delivers operationally

• Single tool finalizes planning → execution handoff.
• Prompt template tells the agent to (a) resolve the Symphony issue to the underlying dr/tasks/ task, (b) load decision_refs from dr/decisions/, (c) honor depends_on, (d) implement, (e) satisfy acceptance_criteria, (f) test, (g) open a PR. Explicit guard rails: don't modify dr/decisions/, don't mark partial work as done, don't leave the workspace.
• Handoff record captures workflow_path so downstream tooling knows where the live WORKFLOW.md sits.

Test plan

• npx tsc --noEmit — clean
• npm run test:unit — 83 tests pass (was 77; +6 new in unit-symphony)
• npm run test:flow — 17 tests pass (was 11; +6 new in flow-symphony)
• npm run build — both bundles build
• CI passes
• Manual smoke test against a real Symphony installation (deferred; flow tests cover the WORKFLOW.md generation deterministically)

Files

• server/src/handoff/symphony.ts — new renderer module
• server/src/tools/handoff.ts — dr_export_symphony tool registration
• server/src/cli/orchestrator.ts — Symphony as third handoff option
• server/src/schemas/index.ts — HandoffRecordSchema extended
• docs/how-to/handoff-to-symphony.md, docs/explanation/symphony-alignment.md — new
• docs/explanation/research-notes.md, docs/reference/mcp-tools.md, docs/README.md, README.md — updates

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added Symphony orchestration support for handing off planning pipelines.
  • CLI now supports exporting workflows with automatic WORKFLOW.md generation.
  • Optional Linear integration for synchronizing tasks during handoff.
  • Three invocation paths available: CLI, MCP tool, and standalone workflow.

• Documentation

  • Added comprehensive guides for Symphony integration and workflow export procedures.
  • Documented configuration options, alignment strategy, and integration patterns.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 83283474-d7de-4d1d-8960-f9ca87d224a6

📥 Commits

Reviewing files that changed from the base of the PR and between 1687b08 and 31d8444.

⛔ Files ignored due to path filters (1)

• README.md is excluded by !*.md

📒 Files selected for processing (11)

• docs/README.md
• docs/explanation/research-notes.md
• docs/explanation/symphony-alignment.md
• docs/how-to/handoff-to-symphony.md
• docs/reference/mcp-tools.md
• server/src/cli/orchestrator.ts
• server/src/handoff/symphony.ts
• server/src/schemas/index.ts
• server/src/tools/handoff.ts
• server/tests/flow-symphony.test.ts
• server/tests/unit-symphony.test.ts

---

Walkthrough

This PR introduces Symphony orchestration integration by adding a dr_export_symphony tool that emits Symphony-compatible WORKFLOW.md files with YAML configuration and Liquid-templated prompts, integrated into the CLI handoff flow, with schema updates to track workflow paths and comprehensive test coverage.

Changes

Symphony handoff workflow

Layer / File(s)	Summary
Handoff record schema with Symphony support server/src/schemas/index.ts	HandoffRecordSchema expands target enum to include "symphony" and adds optional workflow_path field to record the emitted WORKFLOW.md location.
Symphony workflow rendering and templating server/src/handoff/symphony.ts	New module exports renderSymphonyWorkflow and SymphonyWorkflowInputs interface. Renders YAML front matter with tracker, polling, workspace, agent, and codex configuration sections, then generates Liquid-templated Markdown prompt including project context, accepted decisions, per-issue workflow instructions, and outcome recording guidance.
dr_export_symphony tool implementation server/src/tools/handoff.ts	New dr_export_symphony tool validates project state, optionally pushes tasks to Linear, computes tracker project slug with multiple fallbacks, renders and writes WORKFLOW.md to resolved path, logs export events, and finalizes handoff with target='symphony' including workflow path and Linear identifiers.
CLI handoff target selection with Symphony server/src/cli/orchestrator.ts	advanceHandoff now supports three targets. When LINEAR_API_KEY is available, prompts user to select Symphony (with optional Linear pre-push) or Linear-only; otherwise defaults to filesystem. Symphony path optionally requests Linear team ID, calls dr_export_symphony, and logs results.
Unit tests for renderSymphonyWorkflow server/tests/unit-symphony.test.ts	Tests YAML front matter sections with defaults and overrides, validates prompt body includes project scope, accepted-only decisions, Liquid variables, and outcome notes. Covers edge cases: zero accepted decisions and missing tracker configuration.
Integration tests for dr_export_symphony flow server/tests/flow-symphony.test.ts	End-to-end tests: validates rejection when project not in handing-off, generates WORKFLOW.md at project root with correct event emission, honors explicit workflow_path, propagates config overrides, reuses existing Linear handoff slug, and fails appropriately when linear_team_id is set without LINEAR_API_KEY.
User documentation and guides docs/README.md, docs/explanation/research-notes.md, docs/explanation/symphony-alignment.md, docs/how-to/handoff-to-symphony.md, docs/reference/mcp-tools.md	Adds index entries, research notes on Symphony alignment (April 2026), explanation of ecosystem positioning and three-slice roadmap, how-to guide covering invocation paths and post-export wiring, and MCP tool reference for dr_export_symphony parameters and return shape.

🎯 3 (Moderate) | ⏱️ ~25 minutes

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/symphony-handoff

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}