Loop Orchestrator

Loop Orchestrator

Run a repeatable doer -> judge -> auditor loop with explicit artifact handoff.

Workflow

1) Define one task and one run

• Require a stable task ID (for example TASK-0042) and a concise task statement.
• Create a run directory under .orchestrator/runs/.
• Keep all loop evidence in the run directory.

2) Create separated worktrees

Run:

bash <path-to-skill>/scripts/mk_worktrees.sh --repo <repo> --run-dir <run-dir> --base-ref <ref>

• Keep doer worktree writable.
• Keep judge worktree read-only by default.
• Reuse judge worktree for auditor execution.

3) Run doer

Run codex exec in the doer worktree and require:

• handoff.json
• patch.diff

4) Apply patch and run judge

• Apply patch.diff to judge worktree.
• Run judge in read-only mode.
• Require verdict.json.

5) Run auditor gate (default)

• Run auditor in read-only mode after judge pass.
• Require audit.json with gate status pass|fail|needs-human.
• Map gate status to loop outcome:
  • pass -> final pass
  • fail -> final reject with feedback
  • needs-human -> final needs-human

Disable auditor stage only when explicitly needed:

bash <path-to-skill>/scripts/run_loop.sh ... --skip-audit

6) Iterate with feedback

• Feed judge/auditor required changes back to doer on the next round.
• Cap iterations with --max-rounds.
• Persist summary.json with judge and audit outcomes.
• Keep requirement-ID traceability across artifacts (requirements_touched -> requirements_checked|requirements_missing).

Quick Start

bash <path-to-skill>/scripts/run_loop.sh \
  --repo /path/to/repo \
  --task-id TASK-0042 \
  --task "Implement password reset endpoint and tests" \
  --judge-eval "pytest -q" \
  --audit-eval "pip-audit" \
  --max-rounds 2

Inspect run artifacts:

• rounds/round-*/handoff.json
• rounds/round-*/patch.diff
• rounds/round-*/verdict.json
• rounds/round-*/audit.json
• summary.json

Non-Negotiables

• Keep role separation strict.
• Exchange machine-readable artifacts only.
• Preserve traceability from task to evidence.

Resources

scripts/

• scripts/mk_worktrees.sh: create doer/judge worktrees with judge read-only by default.
• scripts/run_loop.sh: orchestrate doer, judge, and optional auditor rounds.

references/

• references/artifacts.md: artifact contracts for handoff, verdict, audit, and summary.
• references/prompt-templates.md: default prompts and override pattern.