> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qredence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# symphony plugin

> Reference Symphony service that polls Linear issues, creates per-issue workspaces, and runs Codex app-server sessions governed by a repository WORKFLOW.md file.

**Symphony** is a reference Symphony service packaged as a dual Claude/Codex plugin. It continuously polls Linear issues, creates deterministic per-issue workspaces, and runs Codex app-server sessions inside those workspaces. Runtime behavior is owned by a repository `WORKFLOW.md` file with YAML front matter and a strict Liquid prompt body.

The implementation follows the OpenAI Symphony draft v1 service spec. It is a trusted-environment harness by default: workspace path containment and hook timeouts are enforced, while Codex approval and sandbox settings are passed through from `WORKFLOW.md`.

If `workspace.root` is omitted, the service defaults to `/symphony_workspaces`. If `WORKFLOW.md` becomes unreadable or invalid during runtime, Symphony keeps the last known good config for reconciliation, blocks new dispatches, and resumes dispatch once the workflow file is fixed.

This baseline intentionally stops short of the optional HTTP dashboard / API and SSH worker extensions. The Linear runtime path is still first-class: operators should use the Linear plugin / app for issue and project work, and Codex sessions launched by Symphony can use the bundled `linear_graphql` tool for scoped in-thread Linear GraphQL access.

## Files

* `scripts/symphony_service.py` — Python reference service and CLI.
* `skills/symphony/SKILL.md` — operator workflow for authoring and running Symphony.
* `references/workflow-example.md` — starter `WORKFLOW.md`.
* `references/implementation-notes.md` — conformance notes and safety posture.

## Quick start

Before you create or validate a repository-owned `WORKFLOW.md`, settle two required inputs:

1. **Confirm the Linear auth connection** Symphony should use at runtime. Symphony does not infer this from hidden plugin state — the chosen auth must resolve through `tracker.api_key`, typically via `LINEAR_API_KEY`.
2. **Choose the Linear project** for this repo. Use the Linear plugin / app to find or confirm the project, then write that repo-to-project mapping into `tracker.project_slug`.

Then create the workflow:

```yaml theme={null}
---
tracker:
  kind: linear
  endpoint: https://api.linear.app/graphql
  project_slug: qredence-plugins
  api_key: $LINEAR_API_KEY
polling:
  interval_ms: 30000
hooks:
  after_create: |
    git clone https://github.com/Qredence/qredence-plugins.git .
  before_run: |
    uv sync --frozen --dev
  after_run: |
    git status --short --branch
agent:
  max_concurrent_agents: 1
  max_turns: 20
  max_retry_backoff_ms: 300000
codex:
  command: codex app-server
  approval_policy: on-request
  thread_sandbox: workspace-write
  turn_sandbox_policy:
    type: workspaceWrite
---
```

Validate a config without dispatching:

```bash theme={null}
uv run python plugins/symphony/scripts/symphony_service.py ./WORKFLOW.md --dry-run-config
```

## Validation

```bash theme={null}
uv run pytest plugins/symphony/tests
```