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 onraxol-payments -- ACP job sessions used by the paused-run resume flowagent-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
- Blocking on human input inline -- return
{:pause, reason, token} and let a
surface/Resumer resume; don't sleep the runner.
- Bad WORKFLOW.md --
WorkflowStore falls back to the last-known-good config and
records last_error/1; check it after edits.
- Assuming production-ready -- v0.1 pre-alpha; pin versions and expect churn.
1---2name: raxol-symphony3description: 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).4---56# Raxol Symphony Skill78`raxol_symphony` (v0.1, pre-alpha) is an OTP port of OpenAI's Symphony: an orchestrator9that turns tracker work into autonomous coding-agent runs. Each issue gets an isolated10workspace, runs an agent until a workflow-defined handoff state, and surfaces evidence11(CI, PR comments, asciinema walkthrough) so engineers manage outcomes, not prompts.1213Config is a `WORKFLOW.md` (YAML front-matter + a Liquid prompt template), hot-reloaded on14change. Pre-alpha: APIs may shift.1516## What You Get1718- Orchestrator loop: poll tracker -> isolate workspace -> run runner -> collect evidence19- Runners: RaxolAgent (primary), Codex (JSON-RPC parity), AgentSession, Review, Noop20- Trackers: Linear (GraphQL), GitHub (state labels), Memory (tests)21- WORKFLOW.md hot-reload + a workflow graph adapter (saga-style)22- Evidence framework: CI, PR comments, complexity (cloc), asciinema recordings23- Six surfaces + a first-class paused-run substrate (pause/resume across surfaces)2425## Quickstart2627```elixir28{:ok, _pid} = Raxol.Symphony.start_link(workflow_path: "WORKFLOW.md")29```3031```markdown32<!-- WORKFLOW.md -->33---34tracker:35 kind: linear36 project_slug: demo37 api_key: $LINEAR_API_KEY38 active_states: ["Todo", "In Progress"]39 terminal_states: ["Done", "Cancelled"]40runner:41 kind: raxol_agent42 agent:43 backend: anthropic44 model: claude-sonnet-4-645 max_turns: 2046---47You are working on issue {{ issue.identifier }}: {{ issue.title }}.48```4950## See also5152- `raxol` -- core agent/TUI framework Symphony runs agents on53- `raxol-payments` -- ACP job sessions used by the paused-run resume flow54- `agent-designer` -- general multi-agent orchestration patterns (non-Symphony)55- `prd-to-plan` / `qa` -- feeding a tracker with well-formed issues5657## Reading Guide5859| Task | File |60| ----------------------------------------- | -------------------------- |61| Orchestrator, trackers, runners, config | `orchestrator.md` |62| WORKFLOW.md, graph adapter, evidence | `workflows-evidence.md` |63| Surfaces + pause/resume + sandboxes | `surfaces-pause.md` |6465## Key Conventions6667- One workspace per issue; `PathSafety` sanitizes identifiers and asserts paths stay68 inside the workspace root. Never run an agent outside its workspace.69- A runner returns `:ok` (retry-continue), `{:error, reason}` (backoff retry), or70 `{:pause, reason, token}` (park in the orchestrator's paused map).71- The Review runner's `Contract` deliberately carries no workspace reference -- reviewer72 isolation is an invariant.7374## Common Pitfalls75761. **Blocking on human input inline** -- return `{:pause, reason, token}` and let a77 surface/`Resumer` resume; don't sleep the runner.782. **Bad WORKFLOW.md** -- `WorkflowStore` falls back to the last-known-good config and79 records `last_error/1`; check it after edits.803. **Assuming production-ready** -- v0.1 pre-alpha; pin versions and expect churn.
DROOdotFOO