feat(review): default to consolidated subagent reviews

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+- Add `subagents` and `other` review modes.
+- Default to up to three isolated same-harness subagents and consolidate their structured results.
+- Keep the original cross-harness reviewer behavior behind explicit `other` mode.
+- Allow operation without a fallback when the unselected mode is unavailable.
+
 ## 0.1.0 - 2026-08-12
 
 - Publish the initial public-beta Revloop skill.

README.md

@@ -19,15 +19,18 @@ Invoke Revloop explicitly:
 
 ```text
 $revloop Implement durable campaign search with pagination.
-$revloop claude Implement durable campaign search with pagination.
-$revloop specs/campaign-search.md codex
+$revloop subagents Implement durable campaign search with pagination.
+$revloop other Implement durable campaign search with pagination.
+$revloop specs/campaign-search.md other
 ```
 
-Requires Codex or Claude Code, Git, an authenticated GitHub CLI, a pushable GitHub remote, network access, and an independent reviewer route.
+Revloop uses up to three fresh same-harness subagents by default and consolidates their results into one structured review. Pass `other` to use Claude Code from Codex or Codex from Claude Code, matching the original cross-harness behavior.
+
+Requires Codex or Claude Code, Git, an authenticated GitHub CLI, a pushable GitHub remote, network access, and either isolated same-harness subagents or the other agent harness.
 
 ## Safety
 
-Revloop modifies files, commits and pushes code, manages draft pull requests and comments, and sends a review brief to the selected reviewer or fallback. The brief contains the request, repository instructions, committed diff, surrounding code, verification evidence, and prior findings.
+Revloop modifies files, commits and pushes code, manages draft pull requests and comments, and sends a review brief to each selected reviewer and any configured fallback. The brief contains the request, repository instructions, committed diff, surrounding code, verification evidence, and prior findings.
 
 Do not use Revloop on material you cannot send to the configured reviewer providers. GitHub artifacts use neutral labels and do not expose the workflow name.
 

skills/revloop/SKILL.md

@@ -5,9 +5,9 @@ description: Run an autonomous implementation and independent review loop that p
 
 # Revloop
 
-Implement in the current coding-agent session. Run only independent review in a fresh isolated context. Continue from discovery through final verification without handing orchestration back to the user.
+Implement in the current coding-agent session. Run independent review through either fresh same-harness subagents or the other agent harness. Continue from discovery through final verification without handing orchestration back to the user.
 
-Revloop is explicitly invoked because it has consequential side effects. It creates branches and commits, pushes code, opens or updates GitHub pull requests and comments, and transmits a self-contained review brief to the selected reviewer. The brief includes the request, repository instructions, committed diff, and verification evidence. A failed primary route sends the same brief to the fallback reviewer.
+Revloop is explicitly invoked because it has consequential side effects. It creates branches and commits, pushes code, opens or updates GitHub pull requests and comments, and transmits a self-contained review brief to the selected reviewer instances. The brief includes the request, repository instructions, committed diff, and verification evidence. A failed primary route sends the same brief to a configured fallback reviewer when one is available.
 
 ## Compatibility
 
@@ -16,8 +16,8 @@ Require all of the following:
 - A Git repository with a pushable GitHub remote.
 - GitHub CLI authenticated with permission to push branches and manage pull requests.
 - Shell access, Git, `gh`, and network access.
-- Codex or Claude Code as the implementer, plus an independent Codex or Claude reviewer route.
-- Permission to transmit the review brief to the selected reviewer provider and fallback.
+- Codex or Claude Code as the implementer, plus either a fresh isolated subagent route in that harness or the other agent harness.
+- Permission to transmit the review brief to the selected reviewer provider and any configured fallback.
 
 Stop before editing when any requirement is unavailable. Do not silently downgrade to a local-only workflow.
 
@@ -38,8 +38,8 @@ Explicit invocation authorizes the implementer to:
 
 - Inspect, edit, test, commit, and push task-owned repository changes.
 - Create or update dedicated draft pull requests and their living status comments.
-- Start the selected reviewer and transmit the review brief.
-- Silently use the declared fallback reviewer when the primary route fails.
+- Start the selected reviewer route and transmit the review brief.
+- Silently use a configured fallback reviewer when the primary route fails.
 - Continue through valid review findings and final verification.
 
 Never ask for confirmation between ordinary implementation, review, or stack layers. Stop only for a material ambiguity that cannot be resolved from available evidence, an unsafe collision with pre-existing work, or an external system failure after documented recovery is exhausted.
@@ -62,31 +62,34 @@ Generate a spec only when the user requests one, an interview was required, or a
 ## Invocation contract
 
 - Treat the current harness as the implementer. An argument never selects the implementer.
-- Accept at most one Markdown path and one reviewer selector in either order.
-- Accept `codex` or `claude` as the reviewer selector. Treat `claude code` as `claude`.
-- When omitted, select the other harness: Claude when Codex implements, or Codex when Claude implements.
-- Stop when the selected reviewer is the same context as the implementer and no fresh isolated route exists.
-- Set the other available route as fallback. A valid `REJECT` is not reviewer failure.
-- Reject unknown command-style arguments with: `/revloop [spec-or-stack.md] [reviewer: codex|claude]`.
+- Accept at most one Markdown path and one review mode in either order.
+- Accept `subagents` or `other` as the review mode.
+- When omitted, select `subagents`.
+- `subagents` launches up to three fresh isolated reviewers in the current harness and consolidates their valid results into one structured review.
+- `other` selects Claude Code when Codex implements, or Codex when Claude Code implements, using the existing external reviewer adapter.
+- Stop before editing when the primary mode is unavailable. For `subagents`, report that the current harness cannot start a fresh isolated reviewer and suggest `other`.
+- Configure the other mode as fallback when available and permitted. A fallback is optional and a valid `REJECT` is not reviewer failure.
+- Reject unknown command-style arguments with: `/revloop [spec-or-stack.md] [reviewer: subagents|other]`.
 
 Examples:
 
-- In Codex, `/revloop claude` uses Codex to implement and Claude Code to review.
-- In Claude Code, `/revloop codex` uses Claude Code to implement and Codex to review.
-- `/revloop specs/auth.md claude` implements one supplied spec with Claude reviewing.
-- `/revloop specs/auth-stack.md` implements the declared stack with the other harness reviewing.
+- In Codex, `/revloop` uses Codex to implement and up to three fresh Codex subagents to review.
+- In Claude Code, `/revloop subagents` uses Claude Code to implement and up to three fresh Claude Code subagents to review.
+- In Codex, `/revloop other` uses Claude Code to review.
+- In Claude Code, `/revloop specs/auth.md other` implements the supplied spec with Codex reviewing.
+- `/revloop specs/auth-stack.md` implements the declared stack with same-harness subagent reviews.
 
 ## Workflow
 
-1. Resolve the implementer, primary reviewer, fallback reviewer, optional spec, and ordered work units.
+1. Resolve the implementer, primary review mode, optional fallback mode, optional spec, and ordered work units.
 2. Run the readiness gate and freeze the acceptance contract defined in the review contract.
 3. Record `git status --short`, `git rev-parse HEAD`, the default branch, and remote. Preserve all pre-existing changes.
 4. Pass reviewer and GitHub publication preflights before editing.
 5. For each work unit, create or resolve its task branch from the accepted parent checkpoint. Add or update the smallest stable proof test first when practical and confirm it fails for the expected reason.
 6. Implement the active unit. Run its relevant tests, lint, type checks, build, coverage, and every acceptance proof. Record unavailable verification honestly.
 7. Stage only task-owned files and create one conventional commit for the verified checkpoint.
 8. Push the checkpoint, create or resolve its draft pull request, and immediately set its living status to `Review pending`.
-9. Record the exact pushed checkpoint as `reviewed_head`, then start a fresh primary reviewer for that checkpoint. If it fails, invoke the fallback with the same brief without asking the user.
+9. Record the exact pushed checkpoint as `reviewed_head`, then run the primary review mode for that checkpoint. In `subagents` mode, launch up to three reviewers and consolidate their results using the review contract. If the primary mode fails and a fallback is configured, invoke the fallback with the same brief without asking the user. If no fallback is configured, publish `Review unavailable` and stop.
 10. Publish both gate results and the new history row before validating or fixing findings.
 11. Independently validate every finding. Fix only valid findings in the earliest work unit that owns the defect, verify again, and create a separate `fix:` commit.
 12. Push the fix, return every affected comment to `Review pending`, propagate changed parents through published descendants without rewriting history, and re-review every affected unit.

skills/revloop/references/github-publication.md

@@ -95,7 +95,7 @@ Use these states:
 
 - `Review pending`: a checkpoint was pushed but has not completed review.
 - `Changes required`: the current checkpoint has concrete findings.
-- `Review unavailable`: both reviewer routes failed.
+- `Review unavailable`: the primary reviewer failed and no configured fallback produced a valid result.
 - `Final verification`: the checkpoint was accepted and final checks are running.
 - `Ready for human review`: the accepted checkpoint equals the remote head and required checks passed.
 
@@ -169,7 +169,7 @@ Omit Open findings when there are none. Include optional confirmed behavior only
 <details>
 <summary>Run details</summary>
 
-- Reviewer: {reviewer and fallback use when applicable}
+- Reviewer: {review mode, valid/failed/malformed subagent counts when applicable, and fallback use when applicable}
 - Review: {scope, files changed, and diff statistics}
 - Checkpoint: {full commit SHA}
 - Verification: {commands and results}

skills/revloop/references/review-contract.md

@@ -157,14 +157,27 @@ Use `VERDICT: ACCEPT` only when the specification gate is `PASS`, the engineerin
 
 Use `VERDICT: REJECT` for any failed gate, `minor fixes`, or `needs rework`. List findings worse first: P0 cannot ship, P1 is a substantive defect, P2 is lower risk, and at most one P3 may cover a cosmetic issue.
 
+## Consolidate subagent results
+
+In `subagents` mode, validate each returned result against the required format, then produce exactly one normalized review in that same format.
+
+- Wait for every launched reviewer before consolidating.
+- Use every valid result. Record failed or malformed reviewer counts, but do not treat them as findings.
+- Treat the route as unavailable only when no reviewer returns a valid result.
+- Set the consolidated verdict to `ACCEPT` only when every valid result is `ACCEPT`. Any valid `REJECT` makes the consolidated verdict `REJECT`.
+- Set each consolidated gate to `PASS` only when every valid result passes that gate.
+- Merge and deduplicate findings without discarding a substantive disagreement. Keep the highest severity and the most concrete evidence and fix.
+- Do not independently dismiss findings during consolidation. Validate them in the normal finding-validation step after publishing the consolidated result.
+- Do not publish individual reviewer transcripts. Identify the result as a consolidated subagent review and record the valid, failed, and malformed reviewer counts.
+
 ## Process the result
 
 - Bind a valid `ACCEPT` only to the exact pushed checkpoint SHA named in the brief. Record that SHA as `accepted_head`.
 - Any later worktree change, commit, push, or pull-request head change invalidates the accepted verdict and requires verification plus a fresh review of the new head.
 - Treat an otherwise valid `ACCEPT` with a missing gate, missing engineering row, failed obligation, unjustified `N/A`, concrete finding, or non-ship verdict as `REJECT`.
-- Treat command failure, malformed output, timeout, or missing machine verdict as reviewer failure and use the fallback route.
-- Publish `Review unavailable` only after both reviewer routes fail.
+- For a single external reviewer, treat command failure, malformed output, timeout, or missing machine verdict as reviewer failure. For subagents, treat the route as failed only when no valid result remains after consolidation. Use a configured fallback route when the primary route fails.
+- Publish `Review unavailable` only after the primary and every configured fallback route fail, or immediately when the primary fails and no fallback is configured.
 - Publish normalized gate results, findings, checkpoint evidence, and a history row before changing code or stopping.
 - Validate every finding independently before fixing it.
 - Include rejected findings and the evidence against them in the next brief.
-- If a reviewer repeats a demonstrably invalid finding, use the fallback as a fresh adjudicator with stronger evidence.
+- If a reviewer repeats a demonstrably invalid finding, use a configured fallback as a fresh adjudicator with stronger evidence. When no fallback is configured, publish the unresolved result and stop.

skills/revloop/references/reviewer-adapters.md

@@ -4,12 +4,30 @@ Use a fresh independent reviewer for every checkpoint. Keep reviewers read-only,
 
 ## Route selection
 
-- In Codex, prefer a fresh native isolated agent for a Codex route. Do not launch nested `codex exec` from an app-hosted Codex session.
-- In Claude Code, use the non-interactive Claude CLI for a Claude route.
-- In another shell-capable client, use the explicit CLI mappings below.
-- A fallback may use the implementer's product only as a fresh context with no inherited conversation and no further delegation.
+- Use same-harness subagents by default.
+- Treat `other` as an explicit selection of Claude Code from Codex or Codex from Claude Code.
+- Use the CLI mappings below only for `other` mode or a configured cross-harness fallback.
+- Prefer the unselected mode as fallback. Continue without a fallback when it is unavailable or not permitted.
 - Do not retry the same failed reviewer automatically.
 
+## Subagent reviewers
+
+Treat the ability to start at least one fresh isolated subagent as the `subagents` preflight. Stop before editing when this capability is unavailable.
+
+Launch three reviewers concurrently when capacity permits. Otherwise launch the maximum available, never exceeding three and never launching zero. Do not start extra serial reviewers merely to reach three.
+
+Send each reviewer only the same reviewer prompt and self-contained brief. A reviewer must not call tools, inspect the repository, edit files, or delegate. Never fork or inherit the implementation conversation.
+
+In Codex, spawn the reviewers as native isolated agents. When the tool is named `spawn_agent`, set `fork_turns` to `none`. Do not launch nested `codex exec` from an app-hosted Codex session.
+
+In Claude Code, invoke non-forked subagents through the Claude Code `Agent` tool. Do not use `/subtask`, `context: fork`, or any route that inherits conversation history.
+
+Wait for every launched reviewer. Use each final response as one reviewer result, then consolidate valid results using [review-contract.md](review-contract.md). Never resume or reuse a reviewer after it returns.
+
+## External routes
+
+In Codex, use the non-interactive Claude CLI for `other` mode or a configured Claude fallback. In Claude Code, use an ephemeral Codex CLI process for `other` mode or a configured Codex fallback. In another shell-capable client, use the matching CLI route below.
+
 ## Claude preflight
 
 Run once before committing:
@@ -32,9 +50,7 @@ Read review text from the final JSON result record's `result` field. Remove the
 
 ## Codex preflight
 
-When native isolated agents are available, treat that capability as the preflight.
-
-Otherwise, run Codex from a fresh empty temporary directory:
+For an external Codex route, run Codex from a fresh empty temporary directory:
 
 ```sh
 REVIEWER_WORKDIR="$(mktemp -d)"
@@ -48,9 +64,7 @@ Continue only when the command succeeds and the final response contains `REVIEWE
 
 ## Codex review
 
-In app-hosted Codex, spawn one fresh native agent with no inherited conversation. When the tool is named `spawn_agent`, set `fork_turns` to `none`. Send only the reviewer prompt and self-contained brief. The reviewer must not call tools, inspect the repository, edit files, or delegate.
-
-When native isolation is unavailable, pass the brief through stdin to a fresh ephemeral process in an empty directory:
+Pass the brief through stdin to a fresh ephemeral process in an empty directory:
 
 ```sh
 codex exec --ignore-user-config --skip-git-repo-check -s read-only --ephemeral -c approval_policy=never -c agents.enabled=false -C "$REVIEWER_WORKDIR" -