open-software-network / repo-delegate

Repo delegate

Hand a well-scoped implementation task to another harness and get a
report back. Same structure as repo-review: one prompt template
([PROMPT.md](PROMPT.md)), one runner script per harness, a template for
adding more. The delegate edits files and runs checks; **the caller reviews
the diff and commits** — delegates never touch git state.

When

• A fix round produced precise per-finding prescriptions (repo-review loop).
• Bulk implementation against a written contract (repo-build-pr delegation).
• A second, independent implementation attempt from a different model family.

Not for: architecture, contracts, go/no-go calls — those stay with the
orchestrating model (see repo-build-pr's model orchestration rules).

How

1. Write the task brief to a file. Like a contract: exact scope and file
   ownership, the interface to build against, repo conventions to follow, and
   an instruction to report deviations instead of improvising. If the brief
   would be longer than the diff, don't delegate. For a defect fix, make the
   gate fail first: encode the bug as a failing regression check (test or
   fixture assertion) before dispatch and say so in the brief — the
   delegate's "gate passed" is then proof the defect died, not a claim.

   State invariants, not failure-path branches. A brief that dictates what
   to do when something goes wrong ships the orchestrator's unexamined premise
   straight into the code, and the delegate will implement it faithfully. Say
   "never type into an unintended app"; do not say "on timeout post the
   keystroke anyway so text is not lost". Before writing any "or else X is
   lost" rationale, verify X can actually be lost. In PR #676 it could not —
   the transcript was already on the clipboard and in history — so the brief's
   own safety clause recreated the exact bug the PR existed to fix, and only a
   cross-harness adversarial run caught it.

   Mutation-check any fixture the delegate authored. A test written by the
   same agent that wrote the fix can pass for reasons unrelated to the fix.
   Revert the fix, confirm the test goes red, restore. PR #676: a delegate's
   "notice does not fire" test asserted the absence of a label in a state where
   an unrelated guard already prevented it — green with the fix removed. PR #677
   is the harder version: a delegate rewrote an existing test so its own
   regression would pass.

2. Fill and dispatch (-t is the brief file; gate defaults to
   pnpm check && pnpm typecheck && pnpm test):

    scripts/run-codex.sh  -t <brief.md> [-C <worktree>] [-g "<gate>"] [-c "<extra constraints>"] [-o <out>] \
                          [-m <model>] [-e <effort>] [-S <tier>]
    scripts/run-claude.sh -t <brief.md> [same flags, minus -S; -m takes
                          sonnet|opus|haiku (default opus), -e takes
                          low|medium|high|xhigh|max (default medium — the
                          brief carries the hard thinking; bump for subtle
                          defect fixes)]

   Codex model/effort/speed (defaults come from ~/.codex/config.toml;
   only pass a flag when the user asked for something specific):

   Allowed models (for now): gpt-5.6-sol (config default; main work),
   gpt-5.6-terra (quick review/feedback passes), gpt-5.6-luna (cheap fast
   bulk; not a primary pick) — the script rejects anything else.

   User says	Flag
   "sol" / "terra" / "luna"	-m gpt-5.6-sol / -m gpt-5.6-terra / -m gpt-5.6-luna
   "think hard"	-e high
   "max effort"	-e xhigh (rarely needed — high covers almost everything)
   "quick pass" / "low effort"	-e low (or minimal/none)
   "fast"	-S fast (bills ~2.5x credits — see below)
   "standard speed"	-S standard (the script's default)

   Effort is none|minimal|low|medium|high|xhigh (validated client-side; the
   API only rejects a bad value after the session has started). Calibration:
   medium is the workhorse, high for genuinely hard briefs, xhigh almost
   never — 5.6 at medium/high already runs long and completes tasks
   end-to-end.

   Speed maps to Codex's service_tier config: fast = priority, standard =
   default — the only two tiers the gpt-5.6 models advertise; anything else
   is silently dropped by Codex, so the script fails closed on other values.
   The script defaults to standard, overriding the user config's
   priority: fast bills ~2.5x credits, and 5.6's long autonomous runs make
   the burn unpredictable. Delegations are background work; only pass
   -S fast when the user explicitly asks.

   After the run the script prints the Codex session id; follow up in the
   same session with codex exec resume <id> "<prompt>". Sessions cannot be
   named at dispatch (/rename is TUI-only as of codex 0.144) — the id is
   the handle. Resume only for short follow-ups: gpt-5.6 input past ~272k
   tokens bills 2x, so a fresh scoped brief beats resuming a long session.

   --dry-run on either prints the filled prompt. run-codex.sh uses
   codex exec -s workspace-write (OS sandbox caps writes to the worktree);
   run-claude.sh uses headless claude -p --permission-mode acceptEdits
   with exactly the standard gate commands allowlisted (a custom -g gate
   outside that set fails closed — extend the allowlist in the script
   deliberately, never to bare pnpm:*/cargo:*, which would reopen
   pnpm exec git / pnpm dlx / cargo run). Claude-side enforcement is
   policy-level, and the delegate reads the whole repo — instruction-like
   text anywhere in it is injection surface, so only dispatch onto checkouts
   you trust. Both runners fail loudly if the delegate moved HEAD.

3. Verify, never trust. Read the diff, re-run the gate yourself, route
   defects back with evidence (a new brief referencing the old one), then
   commit.

Gotchas

• Delegate from a clean tracked tree (the runners enforce it; untracked
  files fail closed unless --allow-untracked) — a dirty base means the
  delegate can clobber uncommitted work without diff evidence.

• Ignored local files (.env, build outputs, scratch dirs) stay writable by
  the delegate — inherent to a writable worktree, and the standard flow
  copies .env in deliberately. Keep unrecoverable local state out of
  delegated worktrees; re-copy .env from the main checkout if damaged.

• Fresh worktrees need pnpm install --frozen-lockfile before the gate can
  pass; say so in the brief or run it first.

• codex exec is synchronous — no job babysitting. If dispatching many
  briefs, run them as background shell tasks and read the -o files.

• The delegate reports what it claims it did; the diff is the truth.

Extending

Add scripts/run-<harness>.sh per
[scripts/HARNESS-TEMPLATE.md](scripts/HARNESS-TEMPLATE.md): same CLI, prompt
from fill-prompt.sh, write access confined to the worktree, no git
mutations, uniform report output.