OpenAI Symphony

Set up and run OpenAI Symphony with isolated issue workspaces, workflow contracts, and unattended Codex orchestration for Linear projects.

Security Scan

The skill's declared requirements and runtime instructions are internally consistent with its stated purpose (orchestrating Codex for Linear issues), but it requires high-trust credentials and runs repository hooks so you should review scopes and run it only in vetted/test environments.

Purpose & Capability

Name/description (Linear + Codex orchestration) align with required binaries (git, codex), required env vars (LINEAR_API_KEY, OPENAI_API_KEY, GITHUB_TOKEN), and the workspace config path. These pieces are what you would expect for a service that polls Linear, runs Codex, and clones/pushes repos. Minor inconsistency: documentation accepts either OPENAI_API_KEY or an active 'codex' login session and supports SSH key auth, but manifest lists OPENAI_API_KEY and GITHUB_TOKEN as required — acceptable but slightly stricter than the prose.

Instruction Scope

SKILL.md and the included docs keep behavior scoped to per-issue workspaces and insist on user approval before unattended operation. However, the skill explicitly runs repo hooks (git clone and hook scripts) and will drive a local codex app-server; those hooks can execute arbitrary code from a repository. The skill includes guardrails and advises test-project rollouts, but executing hooks is an expected, high-risk part of the stated purpose and requires the user to ensure repositories/hooks are trusted.

Install Mechanism

Instruction-only skill with no install spec or embedded code files — lowest install risk. The runtime behavior relies on existing system binaries (git, codex). Because there is no installer that downloads/extracts code, nothing new is written to disk by an install step beyond the memory/workspace files the skill itself instructs to create at runtime.

Credentials

Requested environment variables (LINEAR_API_KEY, OPENAI_API_KEY, GITHUB_TOKEN) are proportionate to the capability: Linear API for tracker access, OpenAI/Codex auth for agent execution, and GitHub credentials for clone/fetch/push. Caveats: the skill's prose allows SSH keys as an alternative to GITHUB_TOKEN and also mentions codex login session as an alternative to OPENAI_API_KEY — the manifest's required list is somewhat stricter than the guidance. The skill stores runtime memory under ~/symphony/ and explicitly advises not to store secrets there.

Persistence & Privilege

The skill persists state to ~/symphony/ (memory, run-history, incidents) and is allowed autonomous invocation (platform default). It does not request 'always: true' or modify other skills. Because it performs unattended orchestration and can run hooks, persistent write access to its own workspace and repo operations are expected; this increases blast radius only insofar as you grant the requested credentials and approvals.

Assessment

This skill appears to do what it claims, but it operates at a high trust level. Before installing or enabling unattended runs: 1) only use a test Linear project and a non-production repository until you validate one end-to-end run; 2) minimize token scopes — prefer a least-privilege Git token or deploy key rather than a broad GITHUB_TOKEN; 3) prefer SSH key auth if you don't want to store a token; 4) verify the 'codex' binary is legitimate and understand whether it uses OPENAI_API_KEY or a separate login session; 5) inspect any repository hooks (after_create, before_run, etc.) you will run — hooks can execute arbitrary code from the repo; 6) keep workspace root on a dedicated path (not a parent/shared directory) and do not store secrets in ~/symphony/ memory files; 7) require explicit user approval before enabling unattended/autonomous operation; and 8) if provenance matters, confirm the referenced upstream implementation (e.g., the GitHub repo cited in docs) before trusting the skill. If you want, provide the exact token scopes you plan to use and the location of the codex binary and I can give more specific hardening steps.

Setup

On first use, read setup.md and establish integration boundaries before proposing commands or workflow edits.

When to Use

Use this skill when the user wants an unattended orchestration service that reads Linear issues, creates per-issue workspaces, and drives Codex in app-server mode until work reaches review or done states. It is optimized for Symphony rollout, workflow authoring, safety hardening, and day-2 operations.

Architecture

Memory lives in ~/symphony/. See memory-template.md for setup.

~/symphony/
|-- memory.md                # Activation policy, environment profile, and operating defaults
|-- workflow-notes.md        # WORKFLOW.md decisions, state map, and prompt policy
|-- incidents.md             # Runtime failures, retries, and mitigations
`-- run-history.md           # Launch evidence, validations, and release notes

Quick Reference

Use the smallest relevant file for the task.

Topic	File
Setup and activation behavior	setup.md
Memory template and status values	memory-template.md
Upstream spec map and implementation checkpoints	SPEC.md
Starter workflow contract used by the service	WORKFLOW.md
Bootstrap and launch runbook	setup-runbook.md
WORKFLOW.md contract template	workflow-template.md
Security hardening and trust checks	safety-guardrails.md
Incident triage and recovery	incident-playbook.md

Requirements

• Repository access for the target project and a safe workspace root
• Linear personal API key in LINEAR_API_KEY
• OpenAI auth for Codex (OPENAI_API_KEY or equivalent codex login session)
• Git remote credentials (GITHUB_TOKEN or SSH key access) for clone/fetch/push hooks
• codex binary with app-server support
• git for workspace bootstrap hooks
• explicit user approval of target environment before unattended operation
• Trusted environment policy approved by the user before unattended operation

Core Rules

1. Treat SPEC.md as the Contract

When implementation details are unclear, align with the upstream Symphony specification first. Do not invent incompatible state models, config keys, or agent-runner behavior.

2. Keep WORKFLOW.md Repository-Owned and Validated

All orchestration policy must live in versioned WORKFLOW.md front matter plus prompt body. Validate YAML and template variables before launch, because invalid workflow files halt dispatch.

3. Enforce Per-Issue Workspace Isolation

Map each issue identifier to a dedicated workspace key and run Codex only inside that directory. Never execute agent work in shared roots or outside the configured workspace boundary.

4. Respect State-Driven Orchestration

Dispatch only active tracker states, stop sessions on terminal states, and preserve idempotent recovery after restarts. A run can end in a workflow-defined handoff state, not only Done.

5. Autonomy Requires Explicit Environment Approval

Before enabling unattended operation, confirm the repository, tracker project, and workspace root are approved by the user. Start with conservative policy (approval_policy: on-request) and test-project rollout before broadening scope.

6. Apply Bounded Concurrency, Retries, and Safe Hooks

Use explicit concurrency ceilings and exponential backoff for transient failures. Retries must resume from existing workspace state instead of repeating completed investigation work. Allow only deterministic hooks that stay inside the issue workspace and avoid secret exfiltration patterns (curl | sh, arbitrary uploads, or parent-directory deletes).

7. Preserve Observability and Safety Evidence

Record launch config, workspace path, tracker state transitions, validation proof, and token/runtime metrics for every run. Operators must be able to reconstruct what happened without rerunning the issue.

Common Traps

• Copying sample workflow statuses without matching the team's Linear workflow -> agents never dispatch or never stop.
• Running hooks that write outside the issue workspace -> cross-issue contamination and unsafe side effects.
• Using prompt templates with unknown variables -> attempt failures at render time.
• Treating retries as fresh runs -> duplicated commits, repeated comments, and wasted tokens.
• Starting unattended runs in untrusted environments -> elevated risk of accidental destructive actions.
• Ignoring terminal-state cleanup -> stale workspaces consume disk and hide old state.

External Endpoints

Endpoint	Data Sent	Purpose
https://api.linear.app/graphql	Issue metadata, state queries, and workflow updates	Tracker polling, reconciliation, and issue-level orchestration
https://api.openai.com	Codex app-server requests and model output payloads	Agent execution for implementation turns
https://github.com	Repository clone/fetch/push traffic defined by workspace hooks	Prepare and update per-issue code workspaces

No other data is sent externally unless the user adds additional integrations.

Security & Privacy

Data that leaves your machine:

• Linear issue context required for dispatch and reconciliation
• Codex request/response payloads needed for agent execution
• Git remote traffic required by repository hooks

Data that stays local:

• Orchestration notes and memory files in ~/symphony/
• Workspace content under the configured root
• Local logs and runtime snapshots

This skill does NOT:

• bypass declared sandbox or approval policies
• execute undeclared external endpoints
• approve ambiguous hook scripts automatically
• modify its own SKILL.md

Trust

This skill depends on OpenAI Codex APIs, Linear APIs, and your configured Git remote. Only install and run it if you trust those services with your repository and issue data.

Related Skills

Install with clawhub install <slug> if user confirms:

• agent - Improve single-agent execution quality for scoped implementation tasks.
• agents - Coordinate multiple agents with explicit ownership and handoff boundaries.
• agentic-engineering - Enforce high-rigor workflows for autonomous software delivery.
• workflow - Design robust repeatable workflows with clear gates and status transitions.
• memory - Persist durable context and operating preferences across sessions.

Feedback

• If useful: clawhub star symphony
• Stay updated: clawhub sync