Conductor

Conductor is an Elixir/OTP implementation scaffold for the Symphony Service Specification in SPEC.md. The service is intended to poll Linear, create isolated per-issue workspaces, and run Codex app-server sessions against those workspaces.

This repository is set up for agent-first development:

• AGENTS.md is the short entry map for Codex and other coding agents.
• docs/ is the versioned system of record for product, architecture, quality, security, and execution plans.
• WORKFLOW.md is the repository-owned runtime contract for Symphony-style unattended issue work.
• make all is the local quality gate used by humans and agents.

Current State

The repository now includes the core Symphony runtime plus three optional extensions:

• workflow front-matter parsing, typed config, dynamic reload checks, and strict prompt rendering;
• Linear issue reads and normalization;
• sanitized per-issue workspaces with lifecycle hooks;
• Codex app-server launch over JSON-RPC stdio from the issue workspace;
• an OTP orchestrator for polling, bounded dispatch, retries, reconciliation, and snapshots;
• a loopback Phoenix LiveView dashboard and JSON API when server.port or CLI --port is set;
• a linear_graphql Codex client-side tool when Linear auth is configured;
• SSH stdio worker execution when worker.ssh_hosts is configured.

The real external integration profile is still environment-dependent future validation.

Prerequisites

• Elixir 1.19.x with Erlang/OTP 28.
• Optional: mise can install the pinned toolchain from mise.toml.

Setup

mix setup
mix test

make all is the full quality gate. It currently fails at the coverage step until the test baseline is raised to the configured 95% threshold.

Development Commands

mix format
mix test
mix coverage
mix specs.check
mix repo_knowledge.check
mix credo.check
mix dialyzer.check
make coverage
make all

mix coverage runs mix test --cover, writes the built-in HTML report to cover/, and enforces at least 95% total coverage.

Run

mix escript.build
./conductor ./WORKFLOW.md

If no workflow path is passed, the CLI defaults to ./WORKFLOW.md.

Enable the optional HTTP dashboard/API with either workflow server.port or a CLI override:

./conductor --port 4000 ./WORKFLOW.md

Repository Map

• SPEC.md: authoritative service behavior contract.
• ARCHITECTURE.md: implementation architecture and module boundaries.
• WORKFLOW.md: default Linear/Codex workflow configuration and prompt.
• docs/product-specs/: product-level behavior and acceptance references.
• docs/design-docs/: design decisions and agent-first principles.
• docs/exec-plans/: active plans, completed plans, and known technical debt.
• docs/QUALITY_SCORE.md: quality grades and next improvement targets.
• docs/SECURITY.md: trust boundary and hardening posture.