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

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.