development-loop.md

Development Loop Runbook

This runbook defines the supervised long-running Conductor workflow. It adapts the mac mini supervisor collaboration pattern to Conductor's local-first protocol: files and commits carry state, Codex App supervises and integrates, Codex CLI implements bounded milestones, and Claude Code is used only as an independent milestone review gate.

This is not a daemon, hosted service, scheduler, or automatic agent executor. It does not change conductor CLI runtime behavior.

Role Split

Role	Owner	Responsibilities	Must not do
Supervisor	Codex App	Select the approved milestone, prepare the worker prompt, review the worker commit, run independent verification, decide integration readiness, and create the review gate commit.	Blindly continue without a launchable task, skip verification, push, or treat worker output as self-approved.
Implementation worker	Codex CLI	Work in an isolated worktree, follow AGENTS.md, implement exactly one bounded milestone, run required verification, update project records, create one implementation commit, and stop.	Edit main, expand scope, push, merge, invoke Claude Code for implementation, or continue into the next milestone.
Review gate	Claude Code	Review the just-completed milestone after the implementation commit and report Accepted or Rejected with findings, verification evidence, and residual risk.	Implement the milestone, repair issues directly, merge, push, or become the default worker.
Human	User	Approve scope changes, destructive actions, push, sensitive-file handling, and any unclear direction.	Be bypassed by automation for stop-gate decisions.

AGENTS.md is the canonical Codex CLI instruction file. Tool-specific projections such as CLAUDE.md are compatibility views, not competing sources of truth.

Claude Code review gates should use Sonnet by default to conserve quota unless the user explicitly asks for a stronger model. If Claude Code is unavailable, quota-blocked, or otherwise cannot run, Codex App may use a supervisor-only fallback review gate only when the user has allowed that fallback. The fallback must record independent verification, code-quality review findings, residual risk, and the Claude availability blocker in DEVLOG.md and HANDOFF.md.

Pre-Launch Sanity Checks

Before Codex App launches a Codex CLI milestone worker, confirm:

1. git status --short --branch is understood and any dirty state has an explicit policy.
2. The selected task in BACKLOG.md has Goal, Constraints, and Validation sections.
3. The selected SOP in .conductor/sops/ is readable and its hard gates are understood.
4. HANDOFF.md, CONTEXT.md, BACKLOG.md, DEVLOG.md, .conductor/config.yaml, and the relevant plan or runbook have been read.
5. The worktree path and branch are outside main and are not already in use.
6. The milestone has one clear deliverable and one verification set.
7. The prompt explicitly says: no push, no merge to main, no hosted service, no daemon, no background executor.
8. Sensitive-file patterns from .conductor/config.yaml are treated as hard gates.

If any check fails, stop and resolve it before launching the worker.

Milestone Flow

1. Codex App selects one approved milestone from BACKLOG.md and writes a bounded /goal prompt with target, constraints, validation, and completion criteria.
2. Codex CLI creates or enters the requested isolated worktree and branch from current local main.
3. Codex CLI reads AGENTS.md plus the required Conductor files and selected SOP.
4. Codex CLI implements only the milestone scope.
5. Codex CLI updates DEVLOG.md and HANDOFF.md; it updates BACKLOG.md only when the milestone explicitly requires metadata changes.
6. Codex CLI runs all required verification commands.
7. Codex CLI creates exactly one implementation commit and stops.
8. Codex App reviews the implementation commit, reruns verification independently, and records findings.
9. Claude Code performs the review-only gate against the implementation commit, normally with --model sonnet.
10. If Claude Code is unavailable and supervisor fallback is allowed, Codex App performs and records the fallback review gate instead of waiting indefinitely.
11. Codex App either rejects for worker fixes or creates a separate review gate commit that records review/integration state.
12. Codex App integrates locally only after the review gate or approved fallback gate passes. Push still requires explicit user confirmation.

The implementation commit and review gate commit are separate on purpose: one records the worker's deliverable; the other records supervisor review, independent verification, and review-gate outcome.

Prompt Generator

conductor supervisor prompt prepares the bounded Codex CLI worker prompt from the next launchable BACKLOG.md task. It is print-only: it does not launch Codex CLI, Claude Code, Orbit, an adapter, a daemon, or any background process.

Example:

.venv/bin/conductor supervisor prompt \
  --project . \
  --worktree /Users/caoyuqi/projects/conductor-worktrees/task-0023-supervisor-prompt \
  --branch codex/task-0023-supervisor-prompt

The generated prompt includes the selected task's goal, constraints, validation contract, SOP, worktree path, branch, stop conditions, and one-commit requirement. The prompt preserves the push gate and destructive-operation gate: the worker must not push, merge to main, run destructive git operations, touch secrets, execute Orbit launch commands, start daemons, auto-launch background agents, or continue into another task.

Use --task TASK-#### to select a specific launchable BACKLOG task instead of the next task by priority and creation date. Use --review-artifact PATH only when an explicit Claude Code review-only gate artifact is useful:

.venv/bin/conductor supervisor prompt \
  --project . \
  --task TASK-0023 \
  --worktree /Users/caoyuqi/projects/conductor-worktrees/task-0023-supervisor-prompt \
  --branch codex/task-0023-supervisor-prompt \
  --review-artifact docs/reviews/TASK-0023-claude-review.md

The review artifact is a static Markdown checklist for Claude Code review-only output. Creating it does not invoke Claude Code and does not imply review acceptance.

Version Goal Loop

The supervised loop is responsible for a version goal, not only for a single task. A version goal is active when HANDOFF.md, BACKLOG.md, CHANGELOG.md, or the roadmap names an unfinished release target such as v1.0.

When the current BACKLOG.md has a launchable task, the heartbeat must continue in auto-continue mode. When it has no launchable task but the version goal is still open, the heartbeat must not treat the loop as obsolete. It must do one of the following:

1. monitor an active worker if present, and do not launch another worker.
2. if no worker is active, launch one existing launchable task if present; otherwise analyze HANDOFF.md, BACKLOG.md, DEVLOG.md, platform progress, and git state.
3. if a clear safe local green/yellow action is now launchable, create or dispatch exactly one concrete task before doing anything else.
4. if no safe local action is launchable, create one non-authorizing red-surface decision/approval packet task and stop there.
5. stop only for project-direction change or hard red-surface action requirements.
6. do not create filler tasks.

A heartbeat automation may be active or standby:

• Active means a worker is running or a launchable task exists. The heartbeat should wake frequently enough to review worker progress, normally every 5 minutes.
• Standby means no launchable task exists but the version goal is not closed. The heartbeat should remain alive, usually at a lower frequency, and should not delete itself.
• Closed means the version goal is complete, verification passes, records are updated, and any remaining action is an explicit human gate such as push or publish. The heartbeat may pause only after writing the closure state to HANDOFF.md.

Empty queue is a state, not a success condition. A version is complete only when the documented release gate says it is complete.

Five-Step Automation Loop Contract

Recurring heartbeat automation follows the tracked TASK-0176 contract in docs/archive/plans/2026-06-08-task-0176-five-step-automation-loop.md. The contract keeps each heartbeat bounded to a cheap state snapshot, exact classification, at most one five-step micro-plan with Goal/Constraints/Validation, exactly one bounded unit, and verification/record/notification discipline.

The heartbeat must not create filler from time passing. If no concrete allowed candidate exists, it returns DONT_NOTIFY with a concise quiet status.

The worker evidence hierarchy is part of the same contract. Stale tmux capture-pane output, previous task completion output, and the generic Codex prompt are context only; they are not standalone active/completed worker evidence and are not by itself evidence of an active or completed worker. Active/completed worker classification requires current pane/process state plus current run, backlog, commit, or task-specific evidence. Use old conductor-worker scrollback only as supporting context after that current evidence is present.

Continuation Policy

The supervisor and any non-discussion automation node classify the next step before launching work. The classification is recorded in HANDOFF.md whenever the loop stops, changes pace, or seeds a new task.

The default project policy is standing auto-run inside the current approved version goal. Once a version goal, roadmap slice, or bounded task range has been approved, the supervisor should continue through safe local work without asking at every task boundary. The stop condition is the risk surface, not the mere fact that a new task begins.

Mode	When it applies	Allowed next action
auto-continue	A launchable BACKLOG task exists, all dependencies are done, the task has Goal/Constraints/Validation, the SOP is readable, the next step is within existing approved direction, and no L2 or hard gate is present.	Launch one bounded Codex CLI worker prompt for that task in the reusable conductor-worker tmux session.
auto-planning	No launchable task exists, or the next task is blocked, but the safe next action is documentation, planning, backlog grooming, or task splitting within the current roadmap/ADR direction.	Create or launch exactly one bounded docs/planning task that makes future work launchable or records the exact blocker. Do not implement runtime behavior.
supervisor-recorded-continue	A task is high-risk only because it touches runtime-adjacent metadata, but its contract is strictly local, non-executing, read-only, and explicitly forbids writes, leases, subprocesses, network/hosted access, credentials, push, workflow/dependency changes, destructive actions, and runtime expansion.	Record the exact allowed scope and denied surfaces in DEVLOG.md and HANDOFF.md, then launch one bounded Codex CLI worker prompt. Do not continue into mutation, lease, execution, daemon, or writer tasks.
conservative-bounded-authorization	The user has approved continuing in an area they may not fully understand, but only by the smallest reversible capability slice to the next checkpoint. The task may write local metadata only when disabled by default, append-only, project-local, redacted, and explicitly non-executing.	Record the capability card, denied surfaces, verification plan, and rollback in DEVLOG.md and HANDOFF.md, then launch one bounded Codex CLI worker prompt. Stop before consumption, lease, execution, daemon/background, network, credential, push, workflow/dependency, destructive, or public surfaces.
standby	The only remaining action is push, publish, release, public PR creation, external account approval, or another explicit human/external decision.	Keep recovery records current and wait. Do not create filler commits or bypass the manual gate.
hard-stop	The next action would cross a forbidden surface, change project direction, expand scope, or lacks a clear task contract.	Stop, update HANDOFF.md with the exact reason, and request supervisor or human direction.

auto-planning is not permission to implement the blocked thing. It is only permission to clarify the queue, split work, update runbooks, write specs, or record why no task is launchable. A blocked runtime placeholder is therefore a hard stop for implementation, but it may be followed by an auto-planning task when the existing ADRs and roadmap already make the safe planning action clear.

Any non-authorizing red-surface decision packet is a valid auto-planning end state only once it is explicitly recorded and no longer blocks the queue with filler tasks.

Standing Auto-Run Policy

Use this policy to avoid unnecessary blocking during long-running supervised development.

Green actions are allowed to continue automatically when they remain inside the approved version goal and the selected task contract:

• read-only inspection, local research, docs, ADRs, specs, backlog grooming, task splitting, and runbook updates;
• tests, fixtures, schema or read-model changes, preview-only CLIs, and read-only dashboard or report views;
• non-executing local readers, verifiers, and projections that only parse or summarize inert project-local metadata, and whose tests prove they do not write records, acquire leases, launch subprocesses, call networks, handle credentials, push, edit workflows, install dependencies, perform destructive operations, or expand runtime behavior;
• creating or reusing an isolated worktree/branch for one bounded task;
• sending one bounded /goal to the reusable Codex CLI worker window;
• supervisor review, deterministic verification, Claude Code Sonnet review-only gate, and Codex App fallback review when fallback is already allowed and recorded;
• local fast-forward integration after verification and review pass;
• updating BACKLOG.md, DEVLOG.md, HANDOFF.md, and local review artifacts;
• local commits for implementation, review-fix, integration records, and documentation.

Yellow actions may continue with supervisor judgment, but must be recorded in DEVLOG.md and HANDOFF.md:

• Claude Code unavailable, quota-blocked, or ambiguous, with Codex App fallback review;
• small review-fix work on the same task branch;
• local demo or smoke-test execution that does not launch agents or cross network, credential, push, destructive, or runtime boundaries;
• narrowing or rewording a task contract without changing product direction;
• unblocking a task whose old blocker was conservative but whose current contract is strictly non-executing, read-only, local, and covered by accepted docs/schema gates; this must be recorded as supervisor-recorded-continue before launch;
• localhost-only read-only preview work that does not add daemon, LAN/mobile, authentication, edit, launch, push, approval, or execution behavior.

Red actions always require explicit human approval in the current task or a recorded standing policy:

• push, publish, release, tag, public pull request creation, or hosted account mutation;
• destructive git or filesystem operations, branch reset, history rewrite, deleting data, or cleaning worktrees;
• secrets, credentials, private data, production data, OAuth, provider API calls, browser profiles, or credential-path handling;
• dependency changes, workflow changes, broad architecture changes, or cross-project rewrites;
• runtime execution, foreground runner execution, live adapter execution, queue mutation, queue writers, lease acquisition, queue execution, daemon/background agents, launch controls, approval writers, or run-record writers;
• LAN/mobile/hosted access, marketplace install/update, plugin runtime, or third-party code execution;
• unclear scope where a wrong assumption could expose data, mutate remote state, or create expensive recovery work.

Hard-stop surfaces include runtime execution, daemon behavior, queue mutation, queue writers, lease acquisition, queue execution, live adapter execution, hosted APIs, credential handling, plugin runtime, marketplace install/update, mobile/LAN behavior, push, publish, release, public pull request creation, destructive operations, workflow changes, dependency changes, secrets or sensitive-file handling, unclear scope, and project-direction changes. These surfaces require an explicit approved task and the relevant ADR/spec gates before any worker may proceed.

Reading and projecting inert queue metadata is not queue execution, lease acquisition, daemon behavior, or runtime execution when the selected task explicitly forbids writes, leases, subprocess launches, adapters, hosted or network calls, credentials, push, workflow/dependency changes, destructive actions, and runtime expansion. Such work may proceed under supervisor-recorded-continue after the supervisor records the exact scope.

Writing inert local queue metadata is a higher-risk capability slice, but it is still not queue execution when the selected task is disabled by default, append-only, project-local, redacted, non-executing, and explicitly forbids leases, queue consumption, subprocess launches, adapters, hosted or network calls, credentials, push, workflow/dependency changes, destructive actions, and runtime expansion. Such work may proceed only under conservative-bounded-authorization after the supervisor records a capability card that states what is added, what can go wrong, how to roll back, and where the next red boundary is.

Continuation mode does not override the one-milestone rule. Even in auto-continue, Codex CLI receives one bounded /goal, creates one implementation commit, and stops for Codex App supervisor review.

Decision Ledger

Every milestone that changes project state must append a DEVLOG.md entry with:

• actor and role split;
• implementation commit or pending when the entry is included in the commit itself;
• summary of changed files;
• verification commands and observed results;
• decisions made and alternatives rejected;
• blockers or residual risk;
• whether Claude Code review gate is pending, accepted, or rejected.

Do not rewrite past entries. Corrections are new entries that reference the old one.

Review Gates

Codex App review checks:

• scope matches the selected task and SOP;
• no unrelated files changed;
• no sensitive files or workflows changed without approval;
• validation output is real and current;
• local-first boundaries are preserved;
• HANDOFF.md is sufficient for recovery.

Claude Code review-only gate checks the implementation commit after Codex App review. The expected output is:

Gate: Accepted | Rejected
Commit: <sha>
Findings:
- <severity> <file:line> <issue>
Verification reviewed:
- <command> - <result>
Residual risk:
- <risk or none>

If Claude Code rejects the milestone, Codex App decides whether to send a bounded fix prompt back to Codex CLI or stop for human direction. Claude Code must not apply the fix itself.

If Claude Code cannot run, the supervisor fallback gate checks the same implementation commit and must explicitly state:

Gate: Accepted by Codex App fallback | Rejected by Codex App fallback
Commit: <sha>
Claude availability:
- <quota/tool/auth/session blocker>
Supervisor review:
- <code-quality findings or none>
Verification:
- <command> - <observed result>
Residual risk:
- <risk or none>

Fallback acceptance is not the same as a Claude Code acceptance. It is allowed only when the user has approved supervisor fallback and deterministic verification is current.

Cross-Milestone Regression Review

Before integrating a milestone that follows another recently completed milestone, Codex App reviews for regressions across the last local milestones:

git log --oneline -10
git diff --stat main..HEAD
git diff --check
.venv/bin/python -m pytest -q
.venv/bin/conductor verify .
.venv/bin/conductor verify --json . | .venv/bin/python -m json.tool

When the milestone is documentation-only, the full pytest and verify commands still run because the file protocol is itself product behavior. If failures appear, treat them as a stop gate unless clearly pre-existing and documented in HANDOFF.md.

Escalation Levels

Level	Trigger	Action
L0 worker fix	Local lint, formatting, doc mismatch, or missing handoff detail inside approved scope.	Codex CLI fixes within the same milestone branch and amends only if the supervisor explicitly asks.
L1 supervisor decision	Ambiguous interpretation, conflicting docs, or review finding with multiple valid fixes.	Codex App decides or asks the user; record the decision in DEVLOG.md.
L2 human approval	Push, merge to public branch, destructive git operation, sensitive-file change, hosted service, daemon, or scope expansion.	Stop until the user approves explicitly.
L3 blocked handoff	Repeated verification failure, missing task contract, unavailable required tool, or unclear recovery state.	Update HANDOFF.md with blocker and next diagnostic step, then stop.

Notification Rules

Notify the supervisor in the milestone report when:

• an implementation commit is ready for review;
• verification failed or was skipped;
• a stop gate was hit;
• a sensitive-file pattern matched;
• BACKLOG.md, DEVLOG.md, or HANDOFF.md changed;
• Claude Code review gate or Codex App fallback gate is needed, accepted, rejected, or unavailable.

Do not use notifications to request push. Push is always a separate explicit user decision.

GitHub Activity Policy

Conductor keeps GitHub activity through reviewed milestone pushes, not through unreviewed commit spam.

The allowed flow is:

1. Codex CLI completes one bounded milestone in an isolated worktree and creates an implementation commit.
2. Codex App reviews the commit, reruns verification, and records the integration state.
3. Claude Code performs the review-only gate when the milestone requires it, normally with --model sonnet; if Claude Code is unavailable and supervisor fallback is allowed, Codex App records the fallback gate instead.
4. Codex App fast-forwards local main only after the milestone is accepted by the review gate or approved fallback gate.
5. Push is a separate gate. The supervisor may prepare the exact push command and evidence, but must not run git push unless the user has explicitly approved pushing.

If the user grants an explicit standing push policy, record the policy in HANDOFF.md and DEVLOG.md before using it. Without that record, every push remains manual approval.

Daily GitHub activity is a publishing policy, not an implementation policy. If no milestone is ready, do not create empty commits just to keep a streak. If a milestone is ready and push approval is present, push the reviewed commits for that milestone.

Use conductor checkpoint github . to prepare local evidence before a push decision. The assistant is read-only: it reports verification commands, sensitive-file and workflow-review state, git ahead/behind/dirty state, project health, activity policy, approval policy, and the recommended manual push command. It must not be treated as approval, and it must not run git push, hosted API calls, tags, releases, pull requests, daemons, or destructive git operations.

Stop Gates

Stop before doing any of the following:

• pushing to any remote;
• merging to main without current supervisor verification and a passed review gate, or merging work that is outside the approved task contract;
• editing Orbit vault files unless the task explicitly approves it;
• modifying sensitive files or GitHub workflows without explicit approval;
• implementing runtime execution, foreground execution, live adapter execution, daemon behavior, queue execution, hosted APIs, credential handling, plugin runtime, marketplace install/update, mobile/LAN behavior, push controls, approval controls, destructive actions, workflow changes, dependency changes, secret handling, hosted services, background schedulers, or automatic executors unless the selected task explicitly authorizes that exact surface and all required ADR/spec gates are accepted;
• invoking Claude Code as implementation worker;
• continuing from one milestone into another before the current milestone has an implementation commit, supervisor verification, and a review gate result;
• changing the task contract without supervisor approval;
• changing project direction without human approval;
• proceeding with missing validation or failing verification;
• guessing after three failed attempts at the same blocker.

Recovery And Handoff

At every stop point, HANDOFF.md must let a new agent resume without conversation history. Include:

• current branch and worktree path;
• active task and status;
• last implementation commit;
• verification commands and results;
• changed files;
• blockers and exact next step;
• whether review gates are pending.

Recovery starts with:

git status --short --untracked-files=all
git log --oneline -5
sed -n '1,220p' HANDOFF.md
sed -n '1,260p' BACKLOG.md
sed -n '1,220p' DEVLOG.md

If task.md or an equivalent milestone-local plan exists, read it before editing. Resume from file state and commits, not from memory.

Required Verification Commands

Every milestone worker must run the commands specified by the task. For this repository, the default supervised-loop gate is:

.venv/bin/python -m pytest -q
.venv/bin/conductor verify .
.venv/bin/conductor verify --json . | .venv/bin/python -m json.tool
git diff --check
git status --short --branch

Codex App reruns the same commands during supervisor review. Claude Code review gate cites the evidence but remains review-only.