symphony-linear-starter

# Symphony + Linear Starter

> An installable agent skill that gives Codex and Claude Code the ability to orchestrate autonomous AI worker teams using OpenAI Symphony for dispatch and Linear for issue tracking.

## What this is

A skill you install into an AI coding agent (Codex or Claude Code) to unlock multi-agent orchestration. Once installed, your agent can plan work as Linear issues, dispatch parallel workers through Symphony, review their output at an operator gate, and promote learnings into durable guidance that makes each wave better than the last.

## Who this is for

Developers and operators who want to run autonomous AI agent teams against real codebases. You bring the repo and the Linear project. The skill provides the orchestration protocol: issue contracts, worker dispatch, validation gates, recovery playbooks, and a self-improving runbook loop.

## Key concepts

- **Orchestrator**: Your Codex or Claude Code agent. Plans issues, dispatches workers, reviews output, promotes learnings.
- **Symphony**: OpenAI's open-source runtime for dispatching isolated workers via git worktrees.
- **Linear**: Issue tracker that holds the plan — issues, state transitions, dependencies, acceptance criteria.
- **Workers**: Autonomous agents (1-3 per wave) that each execute one bounded issue, validate, and move to In Review.
- **Self-improving loop**: RUNBOOK.md + LEARNINGS.md capture what worked and what didn't. Stable lessons get promoted into AGENTS.md, the issue template, and workflow defaults.
- **Convergence spine (`goal_state.py`)**: The judgment that bounds unattended autonomy. It reads live Linear state plus a budget ledger and returns one verdict (continue, done, or stuck) under hard caps on laps, dispatched workers, planner depth, and wall-clock time. A stuck verdict escalates to a human.
- **Autonomous goal loop (optional)**: Three layers that pursue a goal across many waves. A brain (the orchestrator lap), a merge-trigger Action (the clock), and a planner lane that shapes the next wave's issues. All three consult the convergence spine.

## Default workflow

Plan → Dispatch → Execute → Review → Improve → Done

Default first-run concurrency: 1 worker. Review gate: In Review. No auto-merge in the default workflow. An optional single-writer Release Manager lane can queue `release:ready` PRs through GitHub Merge Queue / `gh pr merge --auto` after a dry run.

An optional autonomous goal loop (`bootstrap.py --with-goal-loop`) decides the next wave from a goal and runs across many waves, bounded by `goal_state.py`'s convergence verdict and hard budget caps (max laps, dispatched, planner depth, wall-clock). Default posture is gated, with the orchestrator owning each merge. It flips to auto (the release lane) or a per-label mix.

## Repo structure

- `skills/symphony-linear-orchestrator/SKILL.md` — main skill definition
- `skills/symphony-linear-orchestrator/references/` — operating model, Linear issue contract, workflow spec, onboarding guide, recovery playbook, self-improvement loop, autonomous goal loop, planner lane, example prompts
- `skills/symphony-linear-orchestrator/scripts/doctor.py` — check local toolchain readiness
- `skills/symphony-linear-orchestrator/scripts/bootstrap.py` — render workflow, runbook, learnings, and issue templates into a target repo
- `skills/symphony-linear-orchestrator/scripts/issue_schema.py` — render or normalize canonical Linear issue bodies
- `skills/symphony-linear-orchestrator/scripts/release_manager.py` — optional single-writer merge/deploy queue runner
- `skills/symphony-linear-orchestrator/scripts/preflight.py` — validate a repo is ready for Symphony
- `skills/symphony-linear-orchestrator/scripts/goal_state.py` — convergence and budget spine for the optional autonomous goal loop
- `skills/symphony-linear-orchestrator/assets/templates/` — workflow, runbook, learnings, issue, guidance, brief, release-manager, goal-loop, and planner templates
- `skills/symphony-linear-orchestrator/agents/openai.yaml` — Codex agent configuration

## Install

```bash
npx skills add jvogan/symphony-linear-starter
```

Or copy `skills/symphony-linear-orchestrator/` into your Codex skills directory or reference `SKILL.md` from Claude Code.

## License

MIT