Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ Please read ~/.agent-protocols/closeout/SKILL.md
Scope: current implementation task
```

For Claude Code structured-review reviewer passes, use the bundled runner:
For structured-review reviewer passes, use the bundled runner:

```bash
python structured-review/scripts/claude_structured_review.py \
Expand All @@ -89,6 +89,11 @@ python structured-review/scripts/claude_structured_review.py \
The runner loads the shared skill from this repo and target-repo overlays from
the explicit `--worktree`.

The runner drives either Claude Code or Codex as the reviewer.
`--reviewer-backend` defaults to `auto`, which picks the cross-vendor
reviewer for the detected driver (Claude Code driver -> Codex reviewer, Codex
driver -> Claude reviewer); pass `--reviewer-backend claude|codex` to pin it.

`--protocol-dir` is optional and mainly for tests or intentional alternate
checkouts; normal usage relies on the script's own `structured-review`
directory.
7 changes: 3 additions & 4 deletions closeout/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,10 +44,9 @@ This trigger list is the canonical Closeout Review trigger list. Maintain it
through structured-review skill self-evolution when protocol rules change.

When Closeout Review is triggered, use the `structured-review` protocol with
`Type: closeout-review`. For repo-backed Closeout Review, use the bundled
Claude runner when available. Default to `print-review` for durable closeout
reports or reference artifacts; use `write-commit-to-plan` only when the driver
explicitly provides a thread file with `## Review Threads`.
`Type: closeout-review`. The structured-review skill's default runner rule and
runner-mode guidance decide how the reviewer pass runs; this protocol does not
duplicate that policy.

Closeout Review checks whether the closeout evidence or report is accurate and
complete. It returns to closeout with `ready to resume closeout` or named
Expand Down
6 changes: 3 additions & 3 deletions docs/CURRENT.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Current Protocol Map

Status: active source-of-truth map
Last updated: 2026-06-06
Last updated: 2026-06-10

This file points humans and agents to the active protocol entrypoints. It does
not replace root `AGENTS.md`; agents should start there, then use this map to
Expand All @@ -19,8 +19,8 @@ avoid treating historical plans as current instructions.

- `structured-review/SKILL.md` - structured review for plans,
implementations, optional closeout evidence reviews, and review-response
passes. Repo-backed review gates default to the bundled Claude runner when
available.
passes. Repo-backed review gates default to the bundled runner when
available, with cross-vendor Claude and Codex reviewer backends.
- `closeout/SKILL.md` - final hygiene checklist and delivery handoff after
implementation, documentation, review, or phase work.
- `planning/SKILL.md` - discussion-to-plan workflow before implementation.
Expand Down
636 changes: 636 additions & 0 deletions docs/agent_plans/2026-06-10_codex_reviewer_backend_plan.md

Large diffs are not rendered by default.

2 changes: 2 additions & 0 deletions docs/agent_plans/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,3 +28,5 @@ responses, and closeout evidence for changes to this repo's protocols.
provenance hardening plan.
- `2026-06-10_scout_validation_provenance_closeout.md` - closeout report for
the Scout validation provenance work (PR #13).
- `2026-06-10_codex_reviewer_backend_plan.md` - Codex reviewer backend and
cross-vendor default runner plan.
34 changes: 28 additions & 6 deletions structured-review/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: structured-review
description: Use when a written reviewable artifact needs structured human-agent review, including plans, implementation plans, implementation reviews, optional closeout evidence reviews, and review-response passes. Defaults repo-backed review gates to the bundled Claude runner when available, with explicit reviewer/driver roles and driver-owned post-review decisions.
description: Use when a written reviewable artifact needs structured human-agent review, including plans, implementation plans, implementation reviews, optional closeout evidence reviews, and review-response passes. Defaults repo-backed review gates to the bundled runner when available, with Claude and Codex reviewer backends, explicit reviewer/driver roles, and driver-owned post-review decisions.
---

# Structured Review
Expand Down Expand Up @@ -48,26 +48,40 @@ skill manually, read these references before judging readiness.
For high-touch product UI, dashboards, charts, data review tools, and operator
consoles, also apply `references/ui-review.md`.

## Default Claude Runner Rule
## Default Runner Rule

For repo-backed Plan Review, Plan Re-review, Implementation Review, and
Implementation Re-review gates, the driver defaults to invoking the bundled
Claude runner for the reviewer pass when it is available.
runner for the reviewer pass when it is available.

`Closeout Review` is not part of this default gate list. If closeout explicitly
triggers a repo-backed Closeout Review, use the bundled runner when available;
the trigger comes from closeout, not from structured-review by default.

The runner supports two reviewer backends: `claude` (Claude Code) and `codex`
(Codex CLI). `--reviewer-backend` defaults to `auto`, which selects the
cross-vendor reviewer from the driver's environment: a Claude Code driver gets
the `codex` reviewer and a Codex driver gets the `claude` reviewer. When both
driver markers are present the runner fails and requires an explicit
`--reviewer-backend`; when neither is present it uses `claude`. Review threads
record the reviewer backend in each pass heading.

If an auto-selected backend binary is unavailable, the runner fails with an
actionable error. Substituting the same-vendor reviewer is an explicit
human/driver decision via `--reviewer-backend`, never a silent fallback.

`Default` means use the runner unless:
- the human explicitly says not to use Claude;
- the human explicitly says not to use the runner or a specific reviewer
backend;
- the review is not repo-backed;
- the runner is unavailable and the blocker is reported.

The runner is available when:
- the runner script exists in this protocol checkout or submodule;
- the target worktree is a git repository;
- Python can run the script;
- `claude` is available through the configured `--claude-bin`.
- the selected reviewer backend binary is available through the configured
`--claude-bin` or `--codex-bin`.

Do not silently substitute driver self-review, chat-only commentary, or a
manually constructed reviewer prompt for a required repo-backed review gate. If
Expand All @@ -89,6 +103,11 @@ python structured-review/scripts/claude_structured_review.py \
--topic "example plan"
```

In both modes the reviewer runs read-only and returns the review text. In
`write-commit-to-plan` the runner itself appends that text verbatim under the
thread file's `Review Threads` section and creates the `structured-review:`
commit, so the append-only thread contract holds by construction.

Use `print-review` when appending review threads would pollute a durable
reference artifact, such as a published doc, skill, protocol overlay, or other
reference file.
Expand All @@ -100,6 +119,9 @@ provides a thread file that already has a `## Review Threads` section.
The explicit runner `--mode` is the write-back authorization for that run. The
driver still owns the decision after receiving reviewer output.

Pass `--reviewer-backend claude|codex` to pin the reviewer backend; the
default `auto` selects the cross-vendor reviewer for the detected driver.

Use `--protocol-dir` only when testing or intentionally running against a
different checkout of this protocol. By default the runner uses the
`structured-review` directory that contains the script.
Expand Down Expand Up @@ -199,7 +221,7 @@ Pause and discuss with the human before editing when a reviewer finding:

After applying or rejecting reviewer feedback, the driver summary must
distinguish:
- Claude reviewer suggestions;
- reviewer suggestions, named by reviewer backend;
- driver decisions;
- human decisions;
- remaining risks;
Expand Down
Loading
Loading