raxol-symphony

name	raxol-symphony
description	Symphony: the Raxol tracker-driven coding-agent orchestrator (raxol_symphony, pre-alpha). Turns tracker issues into autonomous agent runs in isolated workspaces, surfaces evidence (CI/PR/asciinema), and supports human-in-the-loop paused runs across six surfaces. TRIGGER when: mix.exs lists :raxol_symphony; code imports Raxol.Symphony.*; there is a WORKFLOW.md driving an orchestrator; user asks about tracker-driven agent orchestration, Symphony runners (RaxolAgent/Codex), evidence capture, or paused-run resume with Raxol. DO NOT TRIGGER when: building a single Raxol agent or the core framework (use raxol skill); agent payments / ACP job sessions (use raxol-payments skill); generic multi-agent system design without Symphony (use agent-designer skill); the Claude Agent SDK (use claude-api).
metadata	{"author":"droo","version":"0.1.0","tags":"elixir, raxol, symphony, orchestrator, coding-agent, tracker"}

Raxol Symphony Skill

raxol_symphony (v0.1, pre-alpha) is an OTP port of OpenAI's Symphony: an orchestrator that turns tracker work into autonomous coding-agent runs. Each issue gets an isolated workspace, runs an agent until a workflow-defined handoff state, and surfaces evidence (CI, PR comments, asciinema walkthrough) so engineers manage outcomes, not prompts.

Config is a WORKFLOW.md (YAML front-matter + a Liquid prompt template), hot-reloaded on change. Pre-alpha: APIs may shift.

What You Get

• Orchestrator loop: poll tracker -> isolate workspace -> run runner -> collect evidence
• Runners: RaxolAgent (primary), Codex (JSON-RPC parity), AgentSession, Review, Noop
• Trackers: Linear (GraphQL), GitHub (state labels), Memory (tests)
• WORKFLOW.md hot-reload + a workflow graph adapter (saga-style)
• Evidence framework: CI, PR comments, complexity (cloc), asciinema recordings
• Six surfaces + a first-class paused-run substrate (pause/resume across surfaces)

Quickstart

{:ok, _pid} = Raxol.Symphony.start_link(workflow_path: "WORKFLOW.md")

<!-- WORKFLOW.md -->
---
tracker:
  kind: linear
  project_slug: demo
  api_key: $LINEAR_API_KEY
  active_states: ["Todo", "In Progress"]
  terminal_states: ["Done", "Cancelled"]
runner:
  kind: raxol_agent
  agent:
    backend: anthropic
    model: claude-sonnet-4-6
    max_turns: 20
---
You are working on issue {{ issue.identifier }}: {{ issue.title }}.

See also

• raxol -- core agent/TUI framework Symphony runs agents on
• raxol-payments -- ACP job sessions used by the paused-run resume flow
• agent-designer -- general multi-agent orchestration patterns (non-Symphony)
• prd-to-plan / qa -- feeding a tracker with well-formed issues

Reading Guide

Task	File
Orchestrator, trackers, runners, config	orchestrator.md
WORKFLOW.md, graph adapter, evidence	workflows-evidence.md
Surfaces + pause/resume + sandboxes	surfaces-pause.md

Key Conventions

• One workspace per issue; PathSafety sanitizes identifiers and asserts paths stay inside the workspace root. Never run an agent outside its workspace.
• A runner returns :ok (retry-continue), {:error, reason} (backoff retry), or {:pause, reason, token} (park in the orchestrator's paused map).
• The Review runner's Contract deliberately carries no workspace reference -- reviewer isolation is an invariant.

Common Pitfalls

1. Blocking on human input inline -- return {:pause, reason, token} and let a surface/Resumer resume; don't sleep the runner.
2. Bad WORKFLOW.md -- WorkflowStore falls back to the last-known-good config and records last_error/1; check it after edits.
3. Assuming production-ready -- v0.1 pre-alpha; pin versions and expect churn.