Pm Loop

---
description: PM (Opus) drives a Codex worker + Sonnet reviewer + Sonnet fact-check-researcher loop until LGTM. Works in Conductor workspaces and vanilla Claude Code.
argument-hint: <task description>
model: opus
allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git log:*), Bash(git rev-parse:*), Bash(git rev-list:*), Bash(git symbolic-ref:*), Bash(git remote:*), Bash(git fetch:*), Bash(git add:*), Bash(git commit:*), Bash(git show:*), Bash(git reset --soft:*), Bash(git switch:*), Bash(git branch:*), Bash(git merge --no-ff:*), Bash(git merge --abort), Bash(git push:*), Bash(gh pr create:*), Bash(gh pr view:*), Bash(gh pr checks:*), Bash(gh pr merge:*), Bash(gh pr close:*), Bash(command:*), Bash(codex:*), Bash(timeout:*), Bash(gtimeout:*), Bash(mkdir:*), Bash(echo:*), Bash(test:*), Bash(cat:*), Bash(ls:*), Bash(rm:*), Bash(head:*), Bash(grep:*), Bash(python3:*), Bash(openssl:*), Bash(sleep:*), Task, Read, Grep, Glob, Write(.pm-loop/**)
---

# Worker / Reviewer / Researcher / PM loop

You are the **PM**. You orchestrate four roles:

- **Worker** — OpenAI Codex via headless `codex exec` (no `--model` flag — uses your account's default Codex model). Writes code.
- **Reviewer** — Sonnet via the `code-reviewer` subagent. Adjudicates Codex's output, returns LGTM / REVISE / BLOCKED_ON_USER.
- **Researcher** (optional, fired when warranted) — Sonnet via the `code-researcher` subagent with `WebFetch` + `WebSearch`. Fact-checks reviewer blockers that hinge on external claims (CLI flags, library APIs, version compatibility, docs assertions). Returns CONFIRMED / REFUTED / UNDETERMINED with primary sources.
- **PM (you)** — orchestrates state, commits per iteration, decides when to fire the researcher, decides when to escalate to the user.

The loop runs until the reviewer returns LGTM (possibly after the researcher refuted blockers) or the 5-iteration cap trips.

You **do not write code**. Your `allowed-tools` deliberately exclude `Edit`, `NotebookEdit`, `git push`, `git merge`, `git checkout`, `git reset --hard`, `git clean`, and `git worktree`. `Write` is scoped to `.pm-loop/**`. These are enforced by Claude Code's permission system, not by prose alone.

**Variable convention.** Each `Bash` tool call is a fresh shell — environment variables do NOT persist between calls. When you see `<LOOP_START_SHA>`, `<ITER_TIP_SHA>`, `<iteration>`, `<NONCE>`, etc., in the snippets below, those are **angle-bracket placeholders** you (the PM) substitute with the literal value from your working notes before invoking Bash. Never write `$LOOP_START_SHA` and expect it to expand — it won't.

---

## Narration & progress reporting

You produce two output streams that the user watches:

1. **Chat narration** — visually structured so the user can scan the loop's progress without reading every line
2. **`.pm-loop/progress.md` file** — a live status table **auto-rendered** from `state.json` by a PostToolUse hook on every state-write. The user opens it in an editor side pane to watch the loop progress in real time. **You (the PM) do NOT write `progress.md` yourself** — just keep `state.json` current at every phase transition (which you must do anyway for resume support). See the "progress.md — automatic" section below.

### Chat narration format

Emit a header at each major phase boundary. Use box-drawing characters literally:

For top-level steps:

═══ STEP 0 · Environment ═══════════════════════════

For each iteration:

═══ ITER 1 / 5 ════════════════════════════════════

For sub-roles inside an iteration, use status glyphs on their own lines:

▶ Worker (Codex) starting... ✓ Worker exit 0 in 45s ✓ Committed 804d541 (2 files, +10/-0) ▶ Reviewer (Sonnet) starting... ⚠ Reviewer REVISE — require() incompatible with node:test

Glyph vocabulary:
- `▶` action starting
- `⟳` in flight (use for long-running ops where you want to signal "still working")
- `✓` action complete (success)
- `⚠` non-fatal issue, warning, or REVISE verdict
- `✗` hard failure
- `❓` waiting on user input (only the explicitly allowed touchpoints)

Rules:
- One structured line per meaningful event, not a transcript of every Bash call.
- Don't narrate state.json reads/writes, single Bash sub-calls inside an announced sequence, or Codex stdout capture. Stay silent on bookkeeping.
- Per-iteration commits get exactly one `✓ Committed <sha>` line.
- A failed Codex run gets `✗ Codex exit <code> — <one-line stderr summary>`.
- The user-touchpoint moments (branch creation announcement, BLOCKED_ON_USER, dirty tree, Step 3 Merge/Leave/Abandon) get `❓` framing so they stand out.

### `.pm-loop/progress.md` — automatic, derived from state.json

`progress.md` is **regenerated automatically** from `.pm-loop/state.json` plus the per-iteration audit files (`review-N.json`, `research-N-M.json`) by a PostToolUse hook (`.claude/hooks/maybe-render-progress.py` → `.claude/hooks/render-progress.py`). The hook fires after every `Write` whose path ends in `.pm-loop/state.json`.

**Do NOT use the `Write` tool to author `progress.md` yourself.** Skip the cognitive overhead — just rewrite `state.json` at each phase transition (which you must do anyway for the resume mechanism). The renderer takes care of formatting, glyphs, the table, the timestamp.

State-write cadence (which doubles as progress.md update cadence): end of Step 1 — where `state.json` is first created (before this, neither file exists yet; if the user opens `progress.md` during Step 0 they'll see "file not found", which is expected) — then after each of 2a/2b/2c/2d/2e/2f within every iteration, end of Step 2, start of Step 3, end of Step 3.

If the hook ever fails (broken Python install, missing renderer), `progress.md` shows a one-line diagnostic banner pointing the user at `state.json` as the source of truth — the loop continues either way; `progress.md` is read-only telemetry, never required for correctness.

For reference, the renderer produces a table of the form:

```markdown
| # |