Conductor Coding Harness

Scheduled GitHub loops use pr_review_sweep, pr_address_sweep, and issue_resolution_sweep. Scans dynamically dispatch bounded candidates through automation_dispatch; long approval gates never hold the next sweep open. Hidden GitHub markers record revision claims and child IDs. Register with ./register.sh, restart workers so the automation module polls, then create schedules explicitly (registration creates none). The exact sweep and dispatch inputs are listed in ../docs/workflow-inputs.md.

Operator guides: models and profiles, prompt templates, and local OpenSpec development. The workflow input reference remains the definition-backed source for required parameters and defaults.

Autonomous coding as durable Conductor workflows. Point it at a repo, an issue, or a PR and it plans, writes, reviews, and revises code — running coding agents (Claude Agent SDK, OpenAI Codex, or Google Gemini) in parallel across isolated git worktrees, with every run observable, resumable, and retryable in Conductor.

The PR lifecycle, as workflows:

issue  ──issue_to_pr──▶  PR  ──pr_review──▶  review comments
                          ▲                        │
                          └──────address_pr────────┘   (revise from feedback)

code_parallel is the coding core: decompose one instruction → code the parts in parallel → merge. The GitHub workflows wrap it with clone / push / PR plumbing.
verification is a separately deployed, read-only worker. For every candidate SHA it maps changed files to exact tests or affected build units and verifies only that scope in a disposable clone; it is intentionally not loaded by ordinary coding workers. Start it with WORKER_MODULES=verification workers/.venv/bin/python workers/main.py. It returns a typed execution outcome: passed, code_failed, infra_blocked, configuration_blocked, timed_out, or cancelled. Only code_failed may enter automated remediation. Built-in adapters cover Gradle, Maven, npm/pnpm/Yarn workspaces (JavaScript and TypeScript), pytest, Go, Cargo, CMake/CTest, and SwiftPM. Unknown build graphs must provide .conductor-code/verification.json; the worker blocks instead of falling back to a root test suite.
feature_campaign is the interactive path for complex work: design and DAG review, resumable dependency waves, profile-driven checks, and final verification on a local branch.
openspec_development validates an apply-ready OpenSpec change, selects the appropriate coding path, verifies the result, and completes/archives the spec lifecycle.
Backends are per-task: claude (default), codex, or gemini — or inferred from the model id. Mix them (plan on Claude, code on Codex, etc.).

Start in 60 seconds

Assumes Python 3.13+, Node.js 20.19+, npm, jq, a reachable Conductor server, and at least one authenticated backend. Run from the repository's coding-harness/ directory:

# 1. Install
python3 -m venv workers/.venv
workers/.venv/bin/pip install -q -r workers/requirements.txt
npm install --no-audit --no-fund --prefix workers/openspec

# 2. Register task + workflow definitions on your Conductor server (idempotent)
export CONDUCTOR_SERVER_URL=http://localhost:8080/api
./workers/register.sh

# 3. Start the workers (they poll Conductor for work)
workers/.venv/bin/python workers/main.py

In another terminal, trigger a workflow:

export CONDUCTOR_SERVER_URL=http://localhost:8080/api
conductor workflow start --workflow issue_to_pr -i '{
  "repo": "https://github.com/you/your-repo.git",
  "issueNumber": 42
}'

If no server is running, start one first with conductor server start (Java 21+). After definitions change, rerun ./workers/register.sh, ask TUI chat to register them, use /register, or g on the dashboard. Registration updates definitions and verifies the SIMPLE-task worker gate.

Watch progress in the Conductor UI or with conductor workflow status <id> — the coding tasks push live per-turn updates (files touched, commands run, tokens). For an interactive experience, use the terminal UI (../tui/): python -m tui to launch runs from a form and watch agents work live — see ../tui/README.md.

Prerequisites

Conductor server reachable (CONDUCTOR_SERVER_URL, default http://localhost:8080/api). Default local backend is SQLite (conductor server start, zero extra deps). If a parallel-heavy workflow (code_parallel, openspec_plan) fails with NonTransientException: [SQLITE_BUSY...], opt into the Postgres-backed alternative instead: CONDUCTOR_BACKEND=postgres in .env, then ../run.sh (brings up ../docker-compose.postgres.yml — requires Docker). For authenticated servers, set both CONDUCTOR_AUTH_KEY and CONDUCTOR_AUTH_SECRET; the Python workers pass them directly to the SDK and reject a partial pair.

At least one agent backend, authenticated in the worker's environment:

Backend	`agent` value	Auth
Claude Agent SDK (default)	`claude`	`claude login` or `ANTHROPIC_API_KEY`
OpenAI Codex	`codex`	bundled `openai-codex` SDK — reuses `~/.codex/auth.json` / `OPENAI_API_KEY` (`CODEX_DRIVER=cli` uses the `codex` CLI)
Google Gemini	`gemini`	`npm i -g @google/gemini-cli`, `GEMINI_API_KEY` (or `~/.gemini/.env`)

For the GitHub workflows (issue_to_pr, pr_review, address_pr, github_demo): the gh CLI installed and authenticated (gh auth login, or GH_TOKEN in the worker's env). The first remote task runs gh auth setup-git so plain git-over-HTTPS uses gh's credentials — no tokens in URLs.
The target toolchain for whatever the agents build (node, go, etc.).

Every configuration variable — Conductor connection, backend keys, GitHub, logging, and tuning knobs — is documented in ../.env.example. Copy it to .env (gitignored); ../run.sh auto-loads it, or set -a; . ../.env; set +a before running main.py / run_workers.sh directly.

Workflows

Seven user-facing workflows plus three internal sub-workflows. All inputs are JSON passed with conductor workflow start --workflow <name> -i '{...}'. Only the inputs marked required must be set; the rest have the defaults shown.

`openspec_development` — implement and archive an OpenSpec change

Use this when an apply-ready OpenSpec change is the source of truth. The source can be local, a Git remote, or a public HTTPS archive. The workflow validates and snapshots the change, assesses a repository-aware DAG, selects code_parallel or feature_campaign, runs requirement-level verification, then completes tasks.md and archives the change.

Input	Default	Meaning
`specSource` / `changeId`	required	OpenSpec source and kebab-case change ID.
`repoPath`	`""`	Target repo; required unless the local source-workspace option is enabled.
`useSpecSourceWorkspace`	`false`	Use an absolute local checked-out source as the implementation worktree; verified runs push a draft PR.
`specSourceType`	`auto`	`auto`, `local`, `git`, or `url`.
`specRef` / `specPath`	`""`	Optional Git ref and path to the OpenSpec project.
`specWritebackRepo`	`""`	Required for URL sources; receives the archived change as a draft PR.
`executionMode`	`auto`	Deterministic complexity routing, or explicit `parallel` / `campaign`.
`maxTasks` / `maxParallelism` / `maxWaves`	`25` / `6` / `20`	DAG and execution bounds.

conductor workflow start --workflow openspec_development -i '{
  "repoPath": "/path/to/repo",
  "specSource": ".",
  "changeId": "add-health-endpoint"
}'

With useSpecSourceWorkspace:true, the selected OpenSpec tree is materialized in an owned worktree. Every Git-visible source change is included in that worktree's run-owned branch while the source checkout's branch, index, and files remain untouched; ignored OpenSpec artifacts are force-staged only for the lifecycle commit. Same-repo specs otherwise archive on the verified local implementation branch. External GitHub specs use an archive branch and draft PR. Credentials come from the worker environment and authenticated gh; never place tokens in specSource or any workflow input. This v1 workflow accepts only apply-ready changes—it does not author proposals.

`feature_campaign` — interactive complex feature work

Use this instead of code_parallel when design and plan need iterative approval, implementation has dependencies, or real-system checks need operator-controlled environments. It pauses after every design pass, approved DAG, integrated wave, attached-server run, and final verification. Agents resume the same session/worktree after feedback or budget exhaustion.

Input	Default	Meaning
`repoPath` / `instruction`	required	Local repository and feature goal.
`inPlace`	`false`	Create and switch to a new unique branch in the supplied checkout before committing every Git-visible existing change as the baseline; the original branch ref is not moved and no push or PR is permitted.
`contextPaths`	`[]`	Live, read-only absolute file/directory references given to agents by path only; their contents are never prompt-attached. Requires the Claude backend until equivalent read-root sandboxing exists for other backends.
`changeBranch`	derived	`feature-campaign/<workflow-id>` when blank.
`designDir`	`docs/design`	Design artifact directory.
`Agent` / `Model`	`claude` / `""`	Design, plan, code, and review backends/models.
`maxTurns` / `maxBudgetUsd`	`500` / `50.0`	Per invocation; no aggregate spend cap.
`maxTasks` / `maxParallelism` / `maxWaves`	`25` / `6` / `20`	Validated DAG and wave bounds.
`designMaxRevisions` / `planMaxRevisions`	`5` / `5`	Review-loop bounds.
Checkpoint actions are Continue, Revise, Adopt edits, Stop, and Later.
Integration conflicts fail soft and return to the checkpoint. Stop retains
the branch with an incomplete outcome. Campaigns retain the verified branch locally by default;
set `createPr:true` explicitly to push it and open a PR.

Campaign checks and exact-SHA verification use the same command runner. Each gets the worker's real environment (whatever the deployment provides -- Docker env, local shell/config files like ~/.gradle/gradle.properties, or a sandbox's injected credentials -- nothing here filters or redirects it), an unbounded process lifetime, external artifact logs, and runtime evidence. Set CONDUCTOR_ARTIFACT_ROOT to choose where retained check logs live. Check/profile timeoutSeconds is rejected so repository configuration cannot reintroduce a hidden deadline.

For build graphs that cannot be inferred, add a language-neutral changed-scope map. Commands are argv arrays (never shell strings); each rule proves which changed paths it covers:

{
  "version": 1,
  "changedScopeRules": [{
    "paths": ["native/core/**"],
    "affectedUnit": "native-core",
    "scope": "focused",
    "scopeToken": "native-core-test",
    "commands": [["ninja", "native-core-test"]]
  }]
}

Generic interpreters and shell syntax are rejected. A missing executable, runtime startup failure, spawn failure, or explicit cancellation returns a blocked infrastructure outcome and never spends a repair attempt.

conductor workflow start --workflow feature_campaign -i '{
  "repoPath": "/path/to/repo",
  "instruction": "Add a durable event subsystem with migrations and tests"
}'

`code_parallel` — code a change, in parallel

Decompose one instruction into independent sub-tasks, optionally create up-front design docs, code each on its own git worktree/branch in parallel, then merge into one newly created outcome branch. Works from a local source checkout (repoPath); it doesn't clone or push (the GitHub workflows do that). By default the source checkout is never switched or edited: the run uses .cc-worktrees/run-<workflow-id> from a snapshot that includes every Git-visible local change.

Input	Default	Meaning
`repoPath`	required	Local directory to work in. Need not be a git repo — it's initialized if needed.
`inPlace`	`false`	Require an existing checkout, create/switch to a new outcome branch first, capture all Git-visible changes there, and integrate locally. Parallel child worktrees are temporary.
`contextPaths`	`[]`	Live, read-only absolute file/directory references; agents receive locations, not inlined contents. Requires the Claude backend until equivalent read-root sandboxing exists for other backends.
`instruction`	required	The coding goal to decompose and implement.
`changeBranch`	derived	New branch the parallel work merges into; blank derives `conductor/run-<workflow-id>`.
`openspecHumanApproval`	`true`	Pause after each OpenSpec plan pass for approval or actionable feedback. False uses the read-only `coding_agent` judge.
`openspecMaxIterations`	`5`	Maximum plan/review passes before the workflow fails closed; may be raised.
`openspecPlanAgent` / `codeAgent`	`claude`	Backend for the OpenSpec plan / coders.
`openspecPlanModel` / `codeModel`	`""`	Model id; empty = the backend's default.
`maxTurns` / `maxBudgetUsd`	`500` / `50.0`	Per-agent turn and spend caps. The OpenSpec plan also defaults to 500 turns/`$50` (`openspecMaxTurns`/`openspecMaxBudgetUsd`). These are not wall-clock deadlines.

Every completed merge is committed to the new outcome branch before verification runs. A failed or exhausted verification loop is returned as evidence in the final verificationState; it never reverts or withholds the committed source handoff. The output's sourceHandoff object gives the exact checkout path, branch, and candidate commit for review.

conductor workflow start --workflow code_parallel -i '{
  "repoPath": "/path/to/repo",
  "instruction": "Add a REST API with CRUD endpoints for notes, plus tests.",
  "changeBranch": "notes-api",
  "openspecPlanAgent": "claude",
  "codeAgent": "codex"
}'

Output: changeBranch, subtasks, merged, conflicts, totalTokens, totalCostUsd, and a summary with a per-sub-task + {plan, subtasks, merge} token/cost breakdown.

`issue_to_pr` — GitHub issue → pull request

Fetch an issue, prepare an isolated workspace, resolve it with code_parallel, push a branch, and open a PR whose body closes the issue. The workflow clones its own temporary source checkout. When design:true, it runs design_docs first and the TUI shows the actual design files before coding. When approvePr:true, Request code changes revises the current candidate workspace, re-verifies it, and returns to the gate; Stop and failed verification never push.

Input	Default	Meaning
`repo`	required	Repo URL or `owner/name`.
`issueNumber`	required	Issue to resolve.
`base`	`main`	Base branch for the PR.
`design` / `designHumanApproval`	`false` / `true`	Generate design docs before coding and review the actual files.
`maxApprovalRevisions`	`2`	Maximum code-revision requests before publication is blocked.
`openspecHumanApproval`	`true`	Human review each OpenSpec plan pass; false selects the automated read-only judge.
`openspecMaxIterations`	`5`	Maximum plan/review passes before the workflow fails closed.
`openspecPlanAgent` / `codeAgent`	`claude`	Backends.
`maxTurns` / `maxBudgetUsd`	`300` / `50.0`	Per-agent turn and spend caps; no wall-clock deadline.

conductor workflow start --workflow issue_to_pr -i '{
  "repo": "https://github.com/you/your-repo.git",
  "issueNumber": 42,
  "base": "main",
  "codeAgent": "claude"
}'

Output: prNumber, prUrl, changeBranch, subtasks, totalTokens, totalCostUsd.

`pr_review` — review and decide a PR

Read a PR's diff (plus surrounding code for context), produce a structured review with a read-only agent, and post one formal GitHub review. A clean review is exactly LGTM with no inline comments and event APPROVE. Concrete required changes use anchored inline comments and event REQUEST_CHANGES. With the TUI gate enabled, the human decision is authoritative: Approve posts the selected comments and approves; Request changes posts the human feedback without approval; Investigate further privately resumes the same read-only reviewer and refreshes the complete draft; Later leaves the workflow paused and posts nothing. Investigation never posts.

Input	Default	Meaning
`repo`	required	Repo URL or `owner/name`.
`prNumber`	required	PR to review.
`agent`	`claude`	Backend for the reviewer.
`model`	`""`	Model id; empty = backend default.
`approve`	`false`	Open a signalable publication gate before posting the review.
`reviewGuidance`	`""`	Optional trusted focus for the initial reviewer.
`maxInvestigationPasses`	`5`	Maximum private follow-up questions before a final decision is required.
`reviewPromptTemplate` / `reviewPromptTemplateSource`	`""` / `""`	Optional reviewer-template override and its provenance.
`reviewInvestigationPromptTemplate` / `reviewInvestigationPromptTemplateSource`	`""` / `""`	Optional private follow-up template and its provenance.
`maxTurns` / `maxBudgetUsd`	`250` / `50.0`	Turn and spend caps; no wall-clock deadline.

conductor workflow start --workflow pr_review -i '{
  "repo": "https://github.com/you/your-repo.git",
  "prNumber": 7
}'

Output: approvalState, publicationState, event (APPROVE/REQUEST_CHANGES), inlineCount, reviewUrl, changedFiles, investigationHistory, investigationCount, lastInvestigationAnswer, tokenUsed, costUsd.

`local_review` — review a local checkout before committing

Review an existing checked-out repository against a freshly fetched remote baseline without changing it. Unlike the implementation workflows, this intentionally uses repoPath directly so the review includes local commits ahead of the remote, staged and unstaged edits, and untracked files. It never creates a worktree, edits, stages, commits, pushes, or posts to GitHub; the agent gets only Read, Grep, and Glob.

Input	Default	Meaning
`repoPath`	required	Local checked-out Git repository on the worker host.
`baseRemote`	`origin`	Configured remote to refresh before comparison.
`baseBranch`	`main`	Remote branch used as the baseline.
`agent` / `model`	`claude` / `""`	Read-only reviewer backend and optional model id.
`maxTurns` / `maxBudgetUsd`	`250` / `50.0`	Per-agent limits.

conductor workflow start --workflow local_review -i '{
  "repoPath":"/absolute/path/to/repo",
  "baseRemote":"origin",
  "baseBranch":"main"
}'

Output: summary, verdict, comments, changedFiles, baseRef, tokenUsed, costUsd.

`address_pr` — revise a PR from its feedback

Consolidate a PR's review feedback (conversation comments + reviews + inline threads, skipping the harness's own), and append bounded context from URLs in actionable feedback. Linked material is provenance-labeled untrusted evidence, never workflow instructions. GitHub Actions links use the worker's gh authentication to include failed-job log tails; inaccessible links only add warnings. The workflow then checks out the PR branch, makes the changes, and pushes to the same branch (updating the PR — no new PR). Safely re-runnable: the harness's own replies are tagged and skipped, and it no-ops when there's no outstanding feedback. The exact candidate must pass local verification before the human gate. Request code changes uses the same workspace and re-verifies; only approval can call the shared publisher. The publisher guards against local/remote branch drift, pushes the exact commit once, waits for exact-SHA CI, and comments only after CI passes.

Input	Default	Meaning
`repo`	required	Repo URL or `owner/name`.
`prNumber`	required	PR whose feedback to address.
`engine`	`code_parallel`	How to code: `code_parallel` (decompose+parallel) or `coding_agent` (single session, cheaper for small feedback).
`maxApprovalRevisions`	`2`	Maximum human-requested code revision passes.
`agent`	`claude`	Backend.
`openspecHumanApproval` / `openspecMaxIterations`	`true` / `5`	OpenSpec plan review (`code_parallel` engine only).
`fixPromptTemplate` / `fixPromptTemplateSource`	`""` / `""`	Optional fix-template override and its provenance.
`maxTurns` / `maxBudgetUsd`	`250` / `50.0`	Turn and spend caps; no wall-clock deadline.

conductor workflow start --workflow address_pr -i '{
  "repo": "https://github.com/you/your-repo.git",
  "prNumber": 7,
  "engine": "coding_agent"
}'

Output: head, engine, commentCount, linkCount, linkedContextChars, linkWarnings, pushed, replyUrl.

`github_demo` — minimal clone → change → PR

A small demo of the remote plumbing without code_parallel: clone, branch, one coding_agent edit, commit, push, open a PR. Good for smoke-testing GitHub connectivity.

Input	Default	Meaning
`repoUrl`	required	Repo to clone.
`instruction`	required	The change to make.
`changeBranch`	`conductor-harness-change`	Branch to push.
`base`	`""`	PR base (empty = repo default).
`prTitle`	`""`	PR title (empty = derived from the concise summary).
`agent` / `model`	`claude` / `""`	Backend + model.

Internal sub-workflows

openspec_plan — drives the openspec CLI (typed tasks, not agent judgment) to scaffold an OpenSpec change and deterministically drain its proposal/specs/design/tasks dependency graph each pass, then reuses the same human-or-AI-judge review loop the harness has always had: human review is the default (approve to exit, or submit feedback that drives the next pass); with openspecHumanApproval:false, a read-only coding_agent judge reviews the generated artifacts instead. openspecMaxIterations defaults to 5 and can be raised. On approval, it deterministically parses the generated tasks.md into subtasks[]. Always invoked by code_parallel; not called directly.
openspec_generate_artifact — one artifact-generation unit of openspec_plan (openspec_instructions → coding_agent). Driven by the dynamic fork; not called directly.
code_subtask — one parallel unit of code_parallel (worktree_add → coding_agent → commit). Driven by the dynamic fork; not called directly.
campaign_subtask — one resumable, file-scoped DAG task for feature_campaign.

Prompt templates (custom instructions)

Every workflow ships a tuned built-in prompt, but you can fully override an agent step's prompt with your own instructions — from three layers, highest precedence first:

Explicit input — a *PromptTemplate workflow input (localReviewPromptTemplate, reviewPromptTemplate, codePromptTemplate, planPromptTemplate, designPromptTemplate, fixPromptTemplate, phase-specific campaign/OpenSpec templates, and approval/design judge templates); inline text, or @repo/path to read the prompt from a file in the checkout.
Repo-resident — a .conductor/<key>.md file committed in the target repo (local_review · pr_review · code · plan · design · address_pr), read from the checkout. Applies to every run on that repo with no payload change — the natural fit for scheduled/CI automation.
Shipped default — the canonical built-in prompt in defaults/prompts/<key>.md (what the worker uses by default; the TUI seeds new templates from the same files).

OpenSpec artifact generation (proposal/specs/design/tasks, inside openspec_plan) is instead driven by that artifact's openspec instructions output (template + instruction + rules), not by a *PromptTemplate input — the artifact content it produces is what openspec itself defines. Each template input has a paired *PromptTemplateSource. The coding worker returns the actual resolvedSource, templateKey, and prompt sha256 in output.promptTemplate; the requested source is descriptive provenance and never overrides the resolver's security checks.

{{diff}} / {{feedback}} / {{instruction}} / {{subtask}} placeholders are filled with runtime context; unused context is appended automatically. The output schema stays enforced (a custom pr_review template still produces a structured review). Details + the full table: ../docs/CODING_AGENT_WORKER.md §14. Untrusted repos: set CODING_AGENT_REPO_TEMPLATES=0 in the worker env to disable the repo-file layer.

Event-triggered review in CI (example)

Because the repo carries its own context — an AGENTS.md guide (auto-read into every agent's prompt: how to build/test/review) and optionally a .conductor/pr_review.md or .conductor/local_review.md prompt — a GitHub or local review workflow Action only needs to start the workflow, no prompt in the payload. CONDUCTOR_SERVER_URL must reach your Conductor server and the workers must be running (self-hosted or a hosted/Orkes cluster):

# .github/workflows/harness-review.yml (in the target repo)
name: Harness PR review
on: { pull_request: { types: [opened, synchronize] } }
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - name: Start pr_review
        env:
          CONDUCTOR_SERVER_URL: ${{ secrets.CONDUCTOR_SERVER_URL }}
        run: |
          curl -sf -X POST "$CONDUCTOR_SERVER_URL/workflow/pr_review" \
            -H 'Content-Type: application/json' \
            -d "{\"repo\":\"${{ github.repository }}\",\"prNumber\":${{ github.event.number }}}"
          # gate stays OFF for automation (no `approve`); AGENTS.md and .conductor/pr_review.md
          # (if committed) are applied by the worker automatically.

The worker reads a repo agent guide — AGENTS.md → AGENT.md → CLAUDE.md (first found at the repo root) — and prepends it to the prompt of every coding/review/plan agent, across all backends, so it learns how to build/test/review the repo with no payload. Disable per run with includeRepoGuide:false or fleet-wide with CODING_AGENT_REPO_GUIDE=0. See ../docs/CODING_AGENT_WORKER.md §15.

Backends

Every coding task selects its engine via agent (or openspecPlanAgent/codeAgent). If unset, it's inferred from the model id: gpt-*/o*/codex-* → codex, gemini-* → gemini, else claude. All three return the same result contract (status, result, structured output, turns, tokens, cost) so they're interchangeable and mixable within one run. Cost is native for Claude and estimated from token counts for Codex/Gemini. See ../docs/CODING_AGENT_WORKER.md §12 for the parity matrix.

Guardrails

Coding agents run locked down: OS sandbox (writes confined to the worktree, no network unless opened), a worktree-escape guard, a fixed tool allowlist (read/write/edit/search + scoped shell incl. file move/delete, but not rm -rf/sudo/git push), and turn/budget/time circuit breakers. Reviewers run read-only. Details in ../docs/CODING_AGENT_WORKER.md §5–§6.

Running the workers

CONDUCTOR_SERVER_URL=http://localhost:8080/api workers/.venv/bin/python workers/main.py

WORKER_MODULES (comma-separated, default coding_agent,gitops,campaign,openspec,openspecops,automation,model_policy,revision,planning) selects which task modules load; the default covers every workflow. coding_agent is the async agent driver (thread_count=8 = 8 concurrent sessions on one event loop); gitops holds the git/GitHub tasks; openspec/openspecops shell out to the openspec CLI (must be installed on that host — see Prerequisites). Split them across hosts with WORKER_MODULES if desired — note the GitHub workflows assume clone/code/push share a filesystem (single host, or a shared volume).

main.py refuses an overlapping deployment for the same Conductor URL, so a broad default worker cannot duplicate a separately started coding_agent worker. Worker task types use one poller each; CONDUCTOR_POLL_TIMEOUT_MS (default 5000) controls server long polling and CONDUCTOR_POLL_INTERVAL_MS (default 500) controls empty-queue backoff.

Layout

main.py               entrypoint — loads WORKER_MODULES, starts the Conductor poller
common/               coding_agent (backend dispatch + locked-down Claude driver),
                      codex (openai-codex SDK + CLI fallback), gemini (Gemini CLI driver),
                      claude (SDK wrapper for merge conflict-resolution),
                      git (local + remote transport), github (gh/PR ops),
                      openspec_cli (openspec CLI wrapper), tasks_md (tasks.md -> subtasks[] parser),
                      progress, session_store, cost, results, exec
coding_agent/         @worker_task("coding_agent") — the sandboxed coding worker + smoke_test.py
model_policy/         @worker_task("model_profile_resolve") — validates and resolves declarative profiles
revision/             bounded candidate checkpoint/evaluation workers for safe revision loops
gitops/               local: prepare_repo, create_branch, commit, worktree_add, merge_worktrees;
                      remote: git_clone/fetch/pull/push/remote, issue_fetch,
                      pr_comments/diff/create/checkout/status/comment/merge/submit_review
openspecops/          openspec_new_change, openspec_status, openspec_instructions,
                      openspec_tasks_to_subtasks
openspec/             OpenSpec source resolution, safe archive extraction, routing, verification,
                      and lifecycle workers; pinned local CLI package
workflows/            openspec_development, feature_campaign + campaign_subtask, code_parallel,
                      local_review, issue_to_pr, pr_review, address_pr, github_demo,
                      openspec_plan, openspec_generate_artifact, code_subtask (+ taskdefs/)

Full design reference: ../docs/CODING_AGENT_WORKER.md. Agent operating guide: ../SKILL.md.

Navigation Menu

Uh oh!

Conductor Coding Harness

Start in 60 seconds

Prerequisites

Workflows

`openspec_development` — implement and archive an OpenSpec change

`feature_campaign` — interactive complex feature work

`code_parallel` — code a change, in parallel

`issue_to_pr` — GitHub issue → pull request

`pr_review` — review and decide a PR

`local_review` — review a local checkout before committing

`address_pr` — revise a PR from its feedback

`github_demo` — minimal clone → change → PR

Internal sub-workflows

Prompt templates (custom instructions)

Event-triggered review in CI (example)

Backends

Guardrails

Running the workers

Layout

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Conductor Coding Harness

Start in 60 seconds

Prerequisites

Workflows

openspec_development — implement and archive an OpenSpec change

feature_campaign — interactive complex feature work

code_parallel — code a change, in parallel

issue_to_pr — GitHub issue → pull request

pr_review — review and decide a PR

local_review — review a local checkout before committing

address_pr — revise a PR from its feedback

github_demo — minimal clone → change → PR

Internal sub-workflows

Prompt templates (custom instructions)

Event-triggered review in CI (example)

Backends

Guardrails

Running the workers

Layout

`openspec_development` — implement and archive an OpenSpec change

`feature_campaign` — interactive complex feature work

`code_parallel` — code a change, in parallel

`issue_to_pr` — GitHub issue → pull request

`pr_review` — review and decide a PR

`local_review` — review a local checkout before committing

`address_pr` — revise a PR from its feedback

`github_demo` — minimal clone → change → PR