Symphony v2: Complete architecture redesign

[shivamstaq]

Summary

• Ground-up redesign replacing the v1 orchestrator with a declarative FSM, event-driven engine, and multi-adapter architecture
• Adds Linear tracker support alongside GitHub, multi-agent support (Claude Code, OpenCode, Codex), and a built-in Bubble Tea TUI dashboard
• 126 files changed: 9,574 insertions, 8,223 deletions — 177 tests passing across 15 packages

Closes #1

Motivation

The v1 architecture had critical issues:

• Cost leaks: No-commits exits silently retried, burning API credits
• Implicit state: Transitions scattered across orchestrator code
• No process visibility: No way to observe or control running agents
• GitHub-only: No support for Linear or other trackers
• Heavy ops: Required external Grafana/Prometheus for basic monitoring

What changed

New architecture

Layer	Interface	Implementations
Tracker	FetchCandidates, FetchStates, ValidateConfig	GitHub, Linear, Mock
Agent	Start(ctx, config) → *Session	Claude Code, OpenCode, Codex, Mock
CodeHost	UpsertPR, CommentOnItem, UpdateProjectStatus	GitHub

FSM (9 states, 16 events, 28 transitions)

open → queued → preparing → running → completed → handed_off
                              ↕ pause/resume
                         needs_human (stall/budget/no-commits)
                              ↓
                           failed (retries exhausted)

All transitions are declarative in domain/fsm.go with typed guards. Invalid transitions are compile-time checkable. Property tests verify 55K+ random event sequences.

Engine event loop

Single-goroutine processes events sequentially — no mutexes on state:

• Poll tick → fetch candidates → eligibility → dispatch → worker goroutine
• Agent updates → token tracking → budget enforcement
• Stall detection → reconciliation with tracker → retry scheduling
• Handoff: push branch → create PR → comment on issue → update project status

Multi-turn support

Workers loop up to max_turns sessions, re-checking work item state between turns. No-commits after all turns → needs_human (prevents silent cost leaks).

CLI commands

symphony init          # Interactive setup wizard
symphony run [--mock]  # Start orchestrator with TUI
symphony doctor        # Validate config + GitHub API connectivity
symphony attach <id>   # Connect to agent PTY via Unix socket
symphony logs/events   # Structured log + FSM event viewers
symphony pause/resume/kill <id>
symphony config validate/show

Package changes

Removed (v1)	Replaced by (v2)
internal/adapter/	internal/agent/{claude,opencode,codex,mock}/
internal/orchestrator/	internal/engine/
internal/webhook/	internal/server/api.go (webhook endpoint)
internal/config/{workflow,service_config,watcher}.go	internal/config/symphony_config.go
test/integration/	test/scenario/ + test/property/

New packages	Purpose
internal/domain/	Canonical WorkItem + FSM (zero external deps)
internal/engine/	Event loop + handlers (eligibility, retry, stall, budget, handoff, reconcile)
internal/codehost/	CodeHost interface + GitHub adapter
internal/tracker/{github,linear,mock}/	Multi-tracker with factory + contract tests
internal/prompt/	Field-based prompt template routing
internal/tui/views/	Bubble Tea TUI (overview, detail, logs)
internal/logging/	JSONL structured logger

Webhook endpoint

POST /api/v1/webhooks/github with HMAC-SHA256 signature verification. Triggers coalesced poll via the engine's buffered event channel.

Doctor command

Validates: .symphony/ directory, symphony.yaml parse + validation, directories, prompt template parseability, agent binary on PATH, git availability, auth credentials, GitHub API connectivity (authenticated).

Test plan

• go build ./... — compiles cleanly
• go test ./... -count=1 — 177 tests pass
• Property tests: 55K+ random FSM sequences, all invariants hold
• Scenario tests: 7 end-to-end flows (happy path, retry exhaustion, no-commits escalation, stall recovery, reconcile closed, budget exceeded, handoff protection)
• Contract tests: shared behavioral suite for all tracker implementations
• Eligibility tests: per-status and per-repo concurrency limits
• Webhook tests: valid/invalid/missing signature, no-secret-configured
• Server tests: healthz, refresh endpoint
• Manual: symphony init → symphony doctor → symphony run --mock

🤖 Generated with Claude Code