WORKFLOW.md Front Matter Configuration Options in OpenAI Symphony

The WORKFLOW.md file in openai/symphony uses YAML front matter to configure six top-level orchestration parameters—tracker, polling, workspace, hooks, agent, and codex—that govern Linear integration, workspace lifecycle, agent concurrency, and LLM execution sandboxing.

The WORKFLOW.md file located in the repository’s elixir/ directory defines the runtime behavior of Symphony’s automated workflow agents. Its YAML front matter block, delimited by --- markers at the top of the file, supplies the complete configuration for how the orchestration system connects to issue trackers, manages temporary workspaces, and executes AI-powered tasks.

Tracker Integration Settings

The tracker key configures the connection to your issue tracking system and maps ticket states to the agent’s internal workflow logic. According to the source code in elixir/WORKFLOW.md, this section supports the following sub-keys:

• kind – Specifies the issue tracking system (e.g., linear).
• project_slug – The unique identifier for the Linear project (e.g., "symphony-0c79b11b75ea").
• active_states – Array of ticket states considered "in progress" (e.g., Todo, In Progress, Merging, Rework).
• terminal_states – Array of states that signal workflow completion (e.g., Closed, Cancelled, Canceled, Duplicate, Done).

tracker:
  kind: linear
  project_slug: "symphony-0c79b11b75ea"
  active_states:
    - Todo
    - In Progress
    - Merging
    - Rework
  terminal_states:
    - Closed
    - Cancelled
    - Canceled
    - Duplicate
    - Done

Polling Frequency and Workspace Paths

The polling and workspace keys control the operational tempo and file system layout of the orchestration system.

polling accepts:

• interval_ms – The frequency in milliseconds that the agent polls the tracker for updates (default: 5000).

workspace accepts:

• root – The base directory where per-ticket workspaces are materialized (e.g., ~/code/symphony-workspaces).

polling:
  interval_ms: 5000
workspace:
  root: ~/code/symphony-workspaces

Lifecycle Hooks for Workspace Management

The hooks key defines shell scripts executed at specific points in the workspace lifecycle, allowing custom setup and teardown procedures.

• after_create – Executed immediately after a new workspace directory is instantiated. Typically used for cloning repositories and installing dependencies.
• before_remove – Executed before a workspace is torn down, useful for cleanup tasks or final state persistence.

hooks:
  after_create: |
    git clone --depth 1 https://github.com/openai/symphony .
    if command -v mise >/dev/null 2>&1; then
      cd elixir && mise trust && mise exec -- mix deps.get
    fi
  before_remove: |
    cd elixir && mise exec -- mix workspace.before_remove

Agent Concurrency and Turn Limits

The agent key imposes resource guardrails on the orchestration system to prevent runaway processes and manage server load.

• max_concurrent_agents – Hard ceiling on simultaneous agent processes (default: 10).
• max_turns – Per-agent limit on interaction turns before forced termination (default: 20).

agent:
  max_concurrent_agents: 10
  max_turns: 20

Codex LLM and Sandboxing Configuration

The codex key configures the underlying LLM-powered executor, including model selection, sandboxing policies, and approval behaviors.

• command – The base shell command used to launch the Codex AI worker, including model specifications and configuration overrides.
• approval_policy – Controls auto-approval privileges (never in the default configuration).
• thread_sandbox – Sandboxing mode for the entire conversation thread (workspace-write).
• turn_sandbox_policy.type – Sandboxing mode for individual turns (workspaceWrite).

codex:
  command: codex --config shell_environment_policy.inherit=all --config 'model="gpt-5.5"' --config model_reasoning_effort=xhigh app-server
  approval_policy: never
  thread_sandbox: workspace-write
  turn_sandbox_policy:
    type: workspaceWrite

Practical Configuration Examples

When customizing a Symphony deployment, you can override specific front matter values while preserving the rest of the configuration structure.

Reducing API load by extending the polling interval:

polling:
  interval_ms: 10000

Directing agents to a different Linear project:

tracker:
  kind: linear
  project_slug: "my-custom-project"

Adding automated linting to the workspace creation hook:

hooks:
  after_create: |
    git clone --depth 1 https://github.com/openai/symphony .
    cd elixir && mix deps.get
    mix compile
    mix credo --strict

Increasing parallel throughput for high-volume environments:

agent:
  max_concurrent_agents: 25
  max_turns: 20

Switching to a newer model while preserving sandboxing:

codex:
  command: codex --config shell_environment_policy.inherit=all --config 'model="gpt-6.0"' --config model_reasoning_effort=high app-server
  approval_policy: never
  thread_sandbox: workspace-write
  turn_sandbox_policy:
    type: workspaceWrite

Summary

• The WORKFLOW.md front matter in openai/symphony uses six top-level YAML keys to configure the entire orchestration system.
• tracker maps Linear states to active and terminal workflow phases.
• polling and workspace control operational timing and directory structure.
• hooks enable custom setup via after_create and cleanup via before_remove shell scripts.
• agent enforces concurrency limits (max_concurrent_agents) and interaction caps (max_turns).
• codex configures the LLM executor, including sandbox policies (thread_sandbox, turn_sandbox_policy) and approval controls.

Frequently Asked Questions

What happens if I omit the terminal_states list in the tracker configuration?

The workflow agent will not recognize which Linear ticket states indicate completed work, potentially causing agents to continue processing tickets that should be ignored. Always define terminal_states to include values like Closed, Done, or Cancelled according to your Linear workflow.

Can I use environment variables in the workspace.root path?

The front matter is parsed as static YAML, so you should use shell expansion in your deployment scripts rather than environment variables directly in the YAML value. Write the absolute path (e.g., ~/code/symphony-workspaces) and ensure the directory exists before the agent starts.

How do I prevent the Codex agent from auto-approving dangerous operations?

Set codex.approval_policy to never as shown in the default configuration. This forces the system to require explicit human approval for all actions, regardless of the sandbox settings. The thread_sandbox and turn_sandbox_policy provide additional filesystem isolation but do not replace approval controls.

What is the difference between thread_sandbox and turn_sandbox_policy?

thread_sandbox applies to the entire conversation thread (the complete lifecycle of a single ticket’s agent), while turn_sandbox_policy governs individual interaction turns within that thread. In the default WORKFLOW.md, both are set to workspace-write, allowing write access to the ticket-specific workspace directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}