update review-loop skill

Author: hiyuki

.agents/skills/review-loop/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: review-loop
 description: Use this skill whenever the user asks for a review loop, self-review workflow, planner/reviewer/coder/code-reviewer collaboration, plan-before-code process, multi-round agent review, or a stable subagent workflow that must produce a plan, wait for user confirmation, implement code, review the diff, and preserve revision records. This skill requires real subagent support and must not fall back to single-agent roleplay.
-protocolVersion: 1.0.0
+protocolVersion: 2.0.0
 ---
 
 # Review Loop
@@ -11,7 +11,10 @@ Use this skill to run a two-phase workflow:
 1. Plan loop: `planner` writes or revises `plan.md`; `plan-reviewer` reviews it.
 2. Code loop: after user confirmation, `coder` implements the confirmed plan; `code-reviewer` reviews the resulting diff.
 
-The workflow requires real subagents. If the current environment cannot create real subagents, stop and tell the user that `review-loop` cannot run in this session.
+The workflow requires real planner and coder subagents. If the current
+environment cannot create them, stop and tell the user that `review-loop`
+cannot run in this session. Codex and Claude Code reviewers run as standalone
+CLI processes instead of custom subagents.
 
 ## Required Setup
 
@@ -21,23 +24,50 @@ Before doing task work:
 2. Read `references/codex.md` or `references/claude-code.md` when that platform applies.
 3. Create a task id.
 4. Run `scripts/init-workspace.js` to create `.agent-workflows/review-loop/<task-id>/`.
-5. Run `scripts/prepare-agent-roles.js` to prepare real subagent roles.
+5. Run `scripts/prepare-agent-roles.js` to prepare the platform's real subagent roles.
 6. Run `scripts/validate-state.js` before advancing.
 
 Default `maxRounds` is `3`. If the user specifies a maximum loop count, pass it to `init-workspace.js`.
 
 ## Hard Rules
 
 - Do not implement code until the plan loop has ended and the user explicitly confirms the plan.
-- Do not let reviewer roles modify `plan.md` or source files; reviewers write JSON review files only.
-- Use `scripts/validate-review-json.js` after every reviewer output.
+- Do not let reviewer roles modify repository files. Reviewers return one strict
+  JSON object; the orchestrator persists and validates it with
+  `scripts/persist-review-json.js`.
+- Start every reviewer in a fresh context that does not inherit planner/coder conversation history.
+- On Codex or Claude Code, enter the reviewing phase, then run
+  `scripts/run-reviewer.js`. It starts a new read-only CLI process with
+  state-derived paths, binds every initial input to a SHA-256 digest, writes an
+  immutable `runtime/reviewer-runs/*` artifact, validates the strict JSON
+  result, and persists the canonical review. Code reviews also bind the
+  validated Git snapshot tree. Reviewing-phase advancement fails when any
+  bound input, snapshot, or run artifact changes. Confirmation gates check only
+  `plan.md` or the Git tree, so later task-workspace patch, scope, review, and
+  log edits do not block normal work by themselves. Do not invoke
+  `scripts/persist-review-json.js` directly on either platform.
+- Use `scripts/validate-review-json.js` for later read-only revalidation.
 - Use `scripts/snapshot-diff.js` after every code loop implementation round.
+- `coder-complete` reconstructs the current Git tree, path partitions, and
+  patches; rerun `snapshot-diff.js` if any code changes after snapshotting.
+- Once the current code reviewer-run artifact exists, do not replace its bound
+  snapshot even when canonical review persistence has not completed.
 - Use `scripts/advance-state.js` for every state transition; never hand-edit `state.json`.
 - Stop a loop when the reviewer returns `approved` or when the loop reaches `state.json.maxRounds`.
 - When a loop stops because `maxRounds` is reached, summarize remaining findings and ask the user whether to continue, accept, or revise.
+- If reviewed plan/code changes while waiting at a confirmation gate, prefer a
+  new review round. Override only after the user's current message explicitly
+  accepts the changed content; pass `--accept-changed-inputs true` with a
+  non-empty `--override-reason`. The transition records the accepted drift in
+  `state.json.confirmationOverrides`.
+- Increase `maxRounds` only from that `max_rounds_reached` confirmation gate;
+  rejecting at that gate cannot resume drafting until the limit is increased,
+  after a current user message explicitly supplies a higher limit. Pass
+  `--user-confirmed true`; never reuse an earlier general instruction to bypass
+  the configured limit.
 - Preserve every round's revision record in `plan.md`.
 
-## Subagent Roles
+## Workflow Roles
 
 The four required roles are:
 
@@ -46,7 +76,10 @@ The four required roles are:
 - `coder`
 - `code-reviewer`
 
-Use the templates under `templates/roles/` to prepare role definitions. If project-level roles already exist, reuse them. If not, ask whether to create temporary roles under the task workspace or persist roles to the project agent config.
+Use the templates under `templates/roles/` as role definitions. On Codex and
+Claude Code, only `planner` and `coder` are custom subagents;
+`plan-reviewer` and `code-reviewer` templates are consumed by
+`run-reviewer.js`. Do not create reviewer agent definitions.
 
 ## User Confirmation Gates
 

.agents/skills/review-loop/jest.config.json

@@ -0,0 +1,8 @@
+{
+  "rootDir": ".",
+  "testEnvironment": "node",
+  "testMatch": ["<rootDir>/scripts/__tests__/**/*.spec.js"],
+  "passWithNoTests": false,
+  "watchman": false,
+  "testTimeout": 10000
+}

.agents/skills/review-loop/references/claude-code.md

@@ -1,51 +1,109 @@
 # Claude Code Integration
 
-Claude Code support requires real subagents. Do not run this workflow as single-agent roleplay.
+Claude Code support uses real planner/coder subagents and standalone reviewer
+CLI processes. Do not run planner or coder as single-agent roleplay.
 
 ## Role Discovery
 
 Check project agents first:
 
 ```text
 .claude/agents/planner.md
-.claude/agents/plan-reviewer.md
 .claude/agents/coder.md
-.claude/agents/code-reviewer.md
 ```
 
-If all four exist, reuse them.
+If both exist, reuse them. Reviewer instructions remain under
+`templates/roles/` and are consumed by `run-reviewer.js`; do not create Claude
+Code reviewer agents.
 
-If any are missing, ask the user to choose:
+If either planner/coder role is missing, ask the user to choose:
 
 - temporary roles under `.agent-workflows/review-loop/<task-id>/runtime/roles/`
 - persistent project agents under `.claude/agents/`
 
-Use `scripts/prepare-agent-roles.js` for either path.
+Use `scripts/prepare-agent-roles.js` for either path. `auto` mode compares only
+the planner and coder project roles with their generated definitions.
+
+## Agent Format
+
+Claude Code custom agents are Markdown files with YAML frontmatter:
+
+```yaml
+---
+name: planner
+description: Planner for review-loop workflows.
+---
+```
+
+Planner and coder inherit the parent model, effort, tools, and permission mode.
 
 ## Temporary Roles
 
-Temporary roles are copied from `templates/roles/` to:
+Temporary planner/coder roles are copied from `templates/roles/` to:
 
 ```text
 .agent-workflows/review-loop/<task-id>/runtime/roles/
 ```
 
-They are valid only for the current task.
+They are valid only for the current task. Claude Code automatically discovers
+named agents only from its configured agent locations. Use temporary
+definitions only when the host can register them for the current session.
+Otherwise choose project roles.
 
 ## Persistent Roles
 
-Persistent roles are copied from `templates/roles/` to:
+Persistent planner/coder roles are copied to:
 
 ```text
 .claude/agents/
 ```
 
-This requires explicit user confirmation because it modifies project-level agent configuration.
+This requires explicit user confirmation because it modifies project-level
+agent configuration. Reload manually created agent files with `/agents` or
+restart the session before invoking them.
+
+## Starting Roles
+
+Start planner and coder as new named subagent invocations when required by the
+state machine. Reviewers are started only through:
+
+```bash
+node .agents/skills/review-loop/scripts/run-reviewer.js \
+  --task-id <task-id> \
+  --kind plan|code \
+  --round N
+```
+
+For plan review, the script starts a new `claude -p` process with a paths-only
+review prompt. For code review, it starts a new `claude -p` process whose user
+message invokes `/code-review high` against the cumulative round patch. The
+native skill may use its own internal reviewer agents; the workflow does not
+create or resume an outer reviewer subagent.
+
+Both commands pin `model = opus`, `effort = high`,
+`permission-mode = plan`, deny direct edit tools, omit `--fix`, and set
+`--no-session-persistence`. They request `--output-format json` with
+`--json-schema`; the runner extracts `structured_output`, validates it, writes
+the immutable reviewer-run artifact, and persists the canonical review. Every
+initial input is bound to a SHA-256 digest. Code reviews additionally bind and
+revalidate the snapshot tree and patches before launch, after completion, and
+during later state validation.
+
+The runner derives `model = opus`, `reasoningEffort = high`, read-only mode, and
+the plan/code-specific source from the command and overwrites
+`evidence.reviewerConfig`; reviewer self-reporting is not trusted.
+
+The fresh CLI process does not inherit the planner/coder conversation. It still
+loads repository-visible Claude Code configuration and can inspect files in the
+working tree. This is conversation isolation, not repository-read isolation.
+
+Do not invoke `persist-review-json.js` directly for Claude Code reviews.
 
 ## Failure
 
-If Claude Code cannot create real subagents in the current session, stop the workflow and tell the user:
+If Claude Code cannot create real planner/coder subagents in the current
+session, stop the workflow and tell the user:
 
 ```text
-review-loop requires real subagent support. Current Claude Code session cannot create subagents, so the workflow cannot continue.
+review-loop requires real planner/coder subagent support. Current Claude Code session cannot create subagents, so the workflow cannot continue.
 ```

.agents/skills/review-loop/references/codex.md

@@ -1,26 +1,27 @@
 # Codex Integration
 
-Codex support requires real subagents. Do not run this workflow as single-agent roleplay.
+Codex support uses real planner/coder subagents and standalone ephemeral
+`codex exec review` processes with JSON Schema output. Do not run planner or
+coder as single-agent roleplay.
 
 ## Role Discovery
 
 Check project custom agents first:
 
 ```text
 .codex/agents/planner.toml
-.codex/agents/plan-reviewer.toml
 .codex/agents/coder.toml
-.codex/agents/code-reviewer.toml
 ```
 
-If all four exist, reuse them.
+If both exist, reuse them. Reviewer instructions remain under
+`templates/roles/` and are read by `run-reviewer.js`; do not create reviewer
+agent TOMLs.
 
-If any are missing, ask the user to choose:
-
-- temporary roles under `.agent-workflows/review-loop/<task-id>/runtime/roles/`
-- persistent project custom agents under `.codex/agents/`
-
-Use `scripts/prepare-agent-roles.js` for either path.
+If any are missing or stale, ask the user for permission to create or refresh
+the project custom agents under `.codex/agents/`, then run
+`scripts/prepare-agent-roles.js --mode project`. Codex discovers custom agents
+only from its personal or project agent directories, so task-workspace
+temporary roles are not supported.
 
 ## Persistent Agent Format
 
@@ -37,7 +38,9 @@ Do not implement code.
 
 ## Starting Roles
 
-Codex does not spawn subagents without an explicit request. After roles are prepared, the orchestrator must explicitly start the four role subagents as the state machine requires.
+Codex does not spawn subagents without an explicit request. After roles are
+prepared, the orchestrator must explicitly start planner and coder as the state
+machine requires. Reviewers are started only through `scripts/run-reviewer.js`.
 
 For each role, include:
 
@@ -48,10 +51,43 @@ For each role, include:
 - required output path
 - instruction to return a concise summary to the orchestrator
 
+After `planner-complete` or `coder-complete`, run the state-derived reviewer:
+
+```bash
+node .agents/skills/review-loop/scripts/run-reviewer.js \
+  --task-id <task-id> \
+  --kind plan|code \
+  --round N
+```
+
+The script launches a new CLI process rather than resuming or forking the parent
+conversation. It passes only fixed instructions plus state-derived repository
+paths, records a SHA-256 digest for every initial input, explicitly selects a
+read-only sandbox, validates the returned strict JSON, and writes both the
+immutable run record and canonical review artifact. Code review runs also bind
+the validated snapshot tree and fail if the worktree or patches drift.
+Do not invoke `persist-review-json.js` directly for Codex reviews.
+
+This isolates conversation history, not repository visibility. The reviewer can
+read any file visible inside the repository's read-only sandbox.
+
+`run-reviewer.js` pins `model = "gpt-5.6"`, uses
+`--ephemeral --output-schema schemas/review.schema.json`,
+`model_reasoning_effort = "high"`, and `sandbox_mode = "read-only"` on the
+command line. Each review records those settings and
+`source = "codex-exec-review-command"` in `evidence.reviewerConfig`. The runner
+derives and overwrites this configuration from the actual command; reviewer
+self-reporting is not trusted as audit evidence.
+
+In `auto` mode, `prepare-agent-roles.js` compares the planner and coder project
+roles with their current templates. A mismatch returns `stale_roles`; refresh
+project roles explicitly before spawning planner or coder.
+
 ## Failure
 
-If Codex cannot create real subagents in the current session, stop the workflow and tell the user:
+If Codex cannot create real planner/coder subagents in the current session,
+stop the workflow and tell the user:
 
 ```text
-review-loop requires real subagent support. Current Codex session cannot create subagents, so the workflow cannot continue.
+review-loop requires real planner/coder subagent support. Current Codex session cannot create subagents, so the workflow cannot continue.
 ```