You are an AI agent running the maintainer's hybrid Codex + Claude orchestration loop in the SlopWeaver public repo.

This command documents how to drive a chain end to end: codex plans, Claude implements, codex reviews, CI watches, human merges. It's the maintainer's primary loop; **contributors don't need this** — `/fix-issue`, `/investigate`, and `/review-pr` work fine without codex installed.

## When to use it

- Non-trivial investigation or planning that benefits from a separate model.
- Multi-file refactors where a fresh planning pass de-risks the implementation.
- CI failures where root-cause analysis is the bottleneck, not the fix.

Do not substitute generic Explore agents for codex on these tasks — they don't run the same loop.

## Tooling expectations

- `codex-agent` on `PATH` (see [Codex install (optional)](../../docs/contributing/ai-workflow.md#codex-install-optional)).
- `gh` for PR creation and CI tailing.
- The `pnpm cli orchestration` runner ships in this repo and drives the full loop. See [chain file format](../../docs/orchestration/chain-format.md) for the schema.

## Three ways to drive a chain

**Direct (codex-agent CLI), Claude-driven.** Claude Code itself drives each phase with `codex-agent start/await-turn/send/quit`. This is the **hybrid loop** the rest of this doc describes — codex plans, Claude implements, codex reviews. No chain file required; works ad hoc.

**Hybrid via `prepare` + Claude launcher.** Author a chain file under `.claude/orchestration/<category>/<name>.md`, then bootstrap the worktree and prompt artifacts:

```bash
pnpm cli orchestration prepare @.claude/orchestration/<chain>.md

prepare sets up the worktree, syncs .env*, and writes a launcher-manifest.json plus the planning/review prompt files. A separate Claude-side launcher (the maintainer's external tool — not in this repo) consumes the manifest and drives the implementation phase as Claude. This is the "Codex plans, Claude implements" path.

Codex-only fallback. pnpm cli orchestration run runs the entire chain through codex without Claude in the loop:

# Preview phases (no codex calls, no side effects)
pnpm cli orchestration run @.claude/orchestration/<chain>.md --dry-run

# Full codex-only run (codex plans + codex implements + codex reviews)
pnpm cli orchestration run @.claude/orchestration/<chain>.md

# Resume is automatic. Use --restart to clear saved state.
pnpm cli orchestration run @.claude/orchestration/<chain>.md --restart

Use this when Claude is rate-limited or unavailable and you'd rather have codex implement than wait. run is hardcoded to codex-only; the --executor flag only applies to prepare.

State and artifacts for both prepare and run persist under $CODEX_HOME/orchestration-runs/<slug>/.

Execution flow

1. Planning phase (codex, read-only)

Spawn a codex agent in the prepared worktree and run the chain's codex-plan and codex-send prompts in sequence:

codex-agent start "<step 1 prompt>" --map -s read-only -d <worktree-path>
# Returns the job id

codex-agent await-turn <jobId>
# Reads the full plan from stdout (foreground only — see below)

codex-agent send <jobId> "<step 2 prompt>"
codex-agent await-turn <jobId>

codex-agent send <jobId> "/quit"

2. Implementation phase (Claude)

Hand the final plan to Claude with this preamble:

I am interfacing between codex for planning and reviewing, and claude code for implementation.

Codex already wrote the plan below. You don't need to change the plan. You just need to make this your plan so that you can implement. And then once you're fully done implementing, then I will ask Codex to review your implementation.

Claude implements, commits, pushes, opens the PR via gh pr create.

3. Review phase (codex, read-only — iteration loop)

Spawn a fresh codex agent to review the PR:

codex-agent start "<review prompt with PR URL>" --map -s read-only -d <worktree-path>
codex-agent await-turn <jobId>
codex-agent send <jobId> "/quit"

If the reviewer surfaces P0/P1 issues → feed the review into Claude → Claude fixes → push → spawn a new review agent. Repeat until the reviewer returns the success sentinel LGTM - ready for local testing. (or REVIEW_STATUS: PASS).

Post the review to the PR (single edited comment, CodeRabbit-style)

After each codex review iteration, post or update one review comment on the PR so the deliberation is visible to onlookers. Don't spam a new comment per iteration — find the existing codex-review comment and PATCH it.

First iteration (creates the comment):

gh pr comment <pr-number> --body "$(cat <<'EOF'
<!-- codex-review -->
**Codex review** — gpt-5.4 (high reasoning) · iteration 1

<paste codex output verbatim — REVIEW_STATUS line, findings, or LGTM>
EOF
)"

Subsequent iterations (edit the same comment via the marker):

REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
COMMENT_ID=$(gh api "repos/$REPO/issues/<pr-number>/comments" --paginate \
  --jq '.[] | select(.body | contains("<!-- codex-review -->")) | .id' | head -1)

gh api -X PATCH "repos/$REPO/issues/comments/$COMMENT_ID" \
  --field body="$(cat <<'EOF'
<!-- codex-review -->
**Codex review** — gpt-5.4 (high reasoning) · iteration N

<paste latest codex output verbatim>
EOF
)"

Rules:

The  HTML comment is the marker the next iteration uses to find the comment. Don't change it.
Quote the codex output verbatim — don't summarize. The point is transparency.
Bump the iteration number in the header each pass.
When the reviewer returns REVIEW_STATUS: PASS, the final comment shows the LGTM line so anyone scanning the PR sees the verdict at the top.
This is the maintainer's loop. If you're a contributor and don't have codex installed, ignore this — your /review-pr flow already posts a Claude-only comment.

4. CI watch + auto-fix loop

gh run watch

On fail ```