Skip to main content

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 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: 
---
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: 
uv run python plugins/symphony/scripts/symphony_service.py ./WORKFLOW.md --dry-run-config

​
Validation

uv run pytest plugins/symphony/tests