From 8f6fd9a5a88630c1f36dc60300e550450b06a33f Mon Sep 17 00:00:00 2001 From: satyaborg Date: Fri, 14 Aug 2026 12:12:44 +1000 Subject: [PATCH 1/3] feat: default reviews to native subagents --- CHANGELOG.md | 6 ++++ README.md | 7 ++-- skills/revloop/SKILL.md | 32 +++++++++++-------- .../revloop/references/github-publication.md | 2 +- skills/revloop/references/review-contract.md | 6 ++-- .../revloop/references/reviewer-adapters.md | 32 +++++++++++++------ skills/revloop/scripts/test-static.sh | 12 ++++++- 7 files changed, 66 insertions(+), 31 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8d3527d..9883f0b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## Unreleased + +- Use a fresh native subagent as the default reviewer. +- Keep Codex and Claude Code as explicit reviewer-provider choices. +- Allow operation without a cross-provider fallback when none is configured. + ## 0.1.0 - 2026-08-12 - Publish the initial public-beta Revloop skill. diff --git a/README.md b/README.md index 236318d..f1f46dc 100644 --- a/README.md +++ b/README.md @@ -19,15 +19,18 @@ Invoke Revloop explicitly: ```text $revloop Implement durable campaign search with pagination. +$revloop native Implement durable campaign search with pagination. $revloop claude Implement durable campaign search with pagination. $revloop specs/campaign-search.md codex ``` -Requires Codex or Claude Code, Git, an authenticated GitHub CLI, a pushable GitHub remote, network access, and an independent reviewer route. +Revloop uses a fresh native subagent by default. Pass `codex` or `claude` to explicitly request that reviewer provider. + +Requires Codex or Claude Code, Git, an authenticated GitHub CLI, a pushable GitHub remote, network access, and either a native isolated reviewer or an explicitly selected reviewer route. ## 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 the 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. diff --git a/skills/revloop/SKILL.md b/skills/revloop/SKILL.md index 65e4cf8..be678a8 100644 --- a/skills/revloop/SKILL.md +++ b/skills/revloop/SKILL.md @@ -7,7 +7,7 @@ description: Run an autonomous implementation and independent review loop that p 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. -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. 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 native isolated subagent route or an explicitly selected Codex or Claude reviewer route. +- 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. @@ -39,7 +39,7 @@ 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. +- 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. @@ -63,22 +63,26 @@ Generate a spec only when the user requests one, an interview was required, or a - 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 `native`, `codex`, or `claude` as the reviewer selector. Treat `claude code` as `claude`. +- When omitted, select `native`. +- `native` means one fresh isolated subagent in the current harness with no inherited conversation. Supply only the reviewer prompt and self-contained brief. The reviewer must not call tools, inspect the repository, edit files, or delegate. +- Treat `codex` and `claude` as explicit provider choices. When the selected provider matches the current harness, use its native isolated route. +- Stop before editing when the primary route is unavailable. For `native`, report that the current harness cannot start a fresh isolated reviewer and suggest an explicit provider selector. +- Configure another available route as fallback when possible, preferring a different provider. A fallback is optional and a valid `REJECT` is not reviewer failure. +- Reject unknown command-style arguments with: `/revloop [spec-or-stack.md] [reviewer: native|codex|claude]`. 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. +- In Codex, `/revloop` uses Codex to implement and a fresh Codex subagent to review. +- In Claude Code, `/revloop native` uses Claude Code to implement and a fresh Claude Code subagent to review. +- In Codex, `/revloop claude` explicitly uses Claude Code to review. +- In Claude Code, `/revloop codex` explicitly uses 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. +- `/revloop specs/auth-stack.md` implements the declared stack with a fresh native reviewer. ## Workflow -1. Resolve the implementer, primary reviewer, fallback reviewer, optional spec, and ordered work units. +1. Resolve the implementer, primary reviewer, optional fallback reviewer, 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. @@ -86,7 +90,7 @@ Examples: 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 start a fresh primary reviewer for that checkpoint. If it 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. diff --git a/skills/revloop/references/github-publication.md b/skills/revloop/references/github-publication.md index 95b2584..3fb0ed3 100644 --- a/skills/revloop/references/github-publication.md +++ b/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. diff --git a/skills/revloop/references/review-contract.md b/skills/revloop/references/review-contract.md index f08ced3..cd3ec83 100644 --- a/skills/revloop/references/review-contract.md +++ b/skills/revloop/references/review-contract.md @@ -162,9 +162,9 @@ Use `VERDICT: REJECT` for any failed gate, `minor fixes`, or `needs rework`. Lis - 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. +- Treat command failure, malformed output, timeout, or missing machine verdict as reviewer failure and use a configured fallback route when present. +- 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. diff --git a/skills/revloop/references/reviewer-adapters.md b/skills/revloop/references/reviewer-adapters.md index fda30ea..e480467 100644 --- a/skills/revloop/references/reviewer-adapters.md +++ b/skills/revloop/references/reviewer-adapters.md @@ -4,12 +4,28 @@ 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 the current harness native subagent route by default. +- Treat `codex` and `claude` as explicit provider selections. When the selected provider matches the current harness, use its native route. +- Use the CLI mappings below only for an explicitly selected external provider or a configured cross-provider fallback. +- Prefer a different provider for the fallback. Continue without a fallback when no second route is available. - Do not retry the same failed reviewer automatically. +## Native reviewer + +Treat the ability to start one fresh isolated subagent as the native preflight. Stop before editing when `native` is selected and that capability is unavailable. + +Send only the reviewer prompt and self-contained brief. The reviewer must not call tools, inspect the repository, edit files, or delegate. Never fork or inherit the implementation conversation. + +In Codex, spawn one native isolated agent. 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 one non-forked subagent through the Claude Code `Agent` tool. Do not use `/subtask`, `context: fork`, or any route that inherits conversation history. + +Use the subagent's final response as the reviewer result. Never resume or reuse the reviewer after it returns. + +## External routes + +In Codex, use the non-interactive Claude CLI for an explicit Claude route or configured Claude fallback. In Claude Code, use an ephemeral Codex CLI process for an explicit Codex route or configured Codex fallback. In another shell-capable client, use the matching explicit CLI route below. + ## Claude preflight Run once before committing: @@ -32,9 +48,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 +62,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" - diff --git a/skills/revloop/scripts/test-static.sh b/skills/revloop/scripts/test-static.sh index 4680a55..613730c 100755 --- a/skills/revloop/scripts/test-static.sh +++ b/skills/revloop/scripts/test-static.sh @@ -11,6 +11,7 @@ GITHUB_FILE="$SKILL_DIR/references/github-publication.md" ADAPTERS_FILE="$SKILL_DIR/references/reviewer-adapters.md" STACK_FILE="$SKILL_DIR/references/stacked-pull-requests.md" LIVE_FILE="$SCRIPT_DIR/test-live.sh" +README_FILE="$SKILL_DIR/../../README.md" fail() { printf 'not ok - %s\n' "$1" >&2 @@ -44,7 +45,7 @@ require_text_count() { [ "$actual" = "$expected" ] || fail "expected $expected occurrence(s), found $actual in $file: $needle" } -for file in "$SKILL_FILE" "$OPENAI_FILE" "$REVIEW_FILE" "$GITHUB_FILE" "$ADAPTERS_FILE" "$STACK_FILE" "$LIVE_FILE"; do +for file in "$SKILL_FILE" "$OPENAI_FILE" "$REVIEW_FILE" "$GITHUB_FILE" "$ADAPTERS_FILE" "$STACK_FILE" "$LIVE_FILE" "$README_FILE"; do require_file "$file" done @@ -65,6 +66,9 @@ require_file_text "$SKILL_FILE" "record it as \`accepted_head\`" require_file_text "$SKILL_FILE" 'Any later worktree change, commit, push, or pull-request head change invalidates acceptance' require_file_text "$SKILL_FILE" 'Pending, failing, unavailable, or stale-head checks are not green.' require_file_text "$SKILL_FILE" 'Never claim completion after reviewer failure, malformed output, or a missing machine verdict.' +require_file_text "$SKILL_FILE" "Accept \`native\`, \`codex\`, or \`claude\` as the reviewer selector." +require_file_text "$SKILL_FILE" "When omitted, select \`native\`." +reject_file_text "$SKILL_FILE" 'When omitted, select the other harness' require_file_text "$OPENAI_FILE" 'allow_implicit_invocation: false' require_file_text "$OPENAI_FILE" "Use \$revloop" @@ -88,9 +92,15 @@ reject_file_text "$GITHUB_FILE" '## Revloop' require_file_text "$ADAPTERS_FILE" '--permission-mode dontAsk' require_file_text "$ADAPTERS_FILE" '--skip-git-repo-check' require_file_text "$ADAPTERS_FILE" 'read-only' +require_file_text "$ADAPTERS_FILE" 'Use the current harness native subagent route by default.' +require_file_text "$ADAPTERS_FILE" "\`fork_turns\` to \`none\`" +require_file_text "$ADAPTERS_FILE" "Claude Code \`Agent\` tool" reject_file_text "$ADAPTERS_FILE" '--dangerously-skip-permissions' reject_file_text "$ADAPTERS_FILE" '--dangerously-bypass-approvals-and-sandbox' +require_file_text "$README_FILE" "\$revloop native" +require_file_text "$README_FILE" 'uses a fresh native subagent by default' + require_file_text "$STACK_FILE" 'Never rebase or force-push a published stack branch.' require_file_text "$STACK_FILE" 'Mark accepted, unchanged pull requests ready from bottom to top.' From 4f767dfdef31ee6156aba25b790cb1c8d21af981 Mon Sep 17 00:00:00 2001 From: satyaborg Date: Sun, 16 Aug 2026 16:40:50 +1000 Subject: [PATCH 2/3] feat: consolidate subagent reviews --- CHANGELOG.md | 7 ++-- README.md | 12 +++--- skills/revloop/SKILL.md | 39 +++++++++---------- .../revloop/references/github-publication.md | 2 +- skills/revloop/references/review-contract.md | 15 ++++++- .../revloop/references/reviewer-adapters.md | 24 ++++++------ skills/revloop/scripts/test-static.sh | 15 ++++--- 7 files changed, 67 insertions(+), 47 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9883f0b..edb61e8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,9 +2,10 @@ ## Unreleased -- Use a fresh native subagent as the default reviewer. -- Keep Codex and Claude Code as explicit reviewer-provider choices. -- Allow operation without a cross-provider fallback when none is configured. +- 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 diff --git a/README.md b/README.md index f1f46dc..9b51b65 100644 --- a/README.md +++ b/README.md @@ -19,18 +19,18 @@ Invoke Revloop explicitly: ```text $revloop Implement durable campaign search with pagination. -$revloop native 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 ``` -Revloop uses a fresh native subagent by default. Pass `codex` or `claude` to explicitly request that reviewer provider. +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 a native isolated reviewer or an explicitly selected reviewer route. +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 and any configured 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. diff --git a/skills/revloop/SKILL.md b/skills/revloop/SKILL.md index be678a8..f8f8b80 100644 --- a/skills/revloop/SKILL.md +++ b/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 a configured fallback reviewer when one is available. +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,7 +16,7 @@ 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 either a fresh native isolated subagent route or an explicitly selected Codex or Claude reviewer route. +- 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,7 +38,7 @@ 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. +- 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. @@ -62,27 +62,26 @@ 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 `native`, `codex`, or `claude` as the reviewer selector. Treat `claude code` as `claude`. -- When omitted, select `native`. -- `native` means one fresh isolated subagent in the current harness with no inherited conversation. Supply only the reviewer prompt and self-contained brief. The reviewer must not call tools, inspect the repository, edit files, or delegate. -- Treat `codex` and `claude` as explicit provider choices. When the selected provider matches the current harness, use its native isolated route. -- Stop before editing when the primary route is unavailable. For `native`, report that the current harness cannot start a fresh isolated reviewer and suggest an explicit provider selector. -- Configure another available route as fallback when possible, preferring a different provider. A fallback is optional and a valid `REJECT` is not reviewer failure. -- Reject unknown command-style arguments with: `/revloop [spec-or-stack.md] [reviewer: native|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` uses Codex to implement and a fresh Codex subagent to review. -- In Claude Code, `/revloop native` uses Claude Code to implement and a fresh Claude Code subagent to review. -- In Codex, `/revloop claude` explicitly uses Claude Code to review. -- In Claude Code, `/revloop codex` explicitly uses 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 a fresh native reviewer. +- 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, optional 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. @@ -90,7 +89,7 @@ Examples: 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 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. +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. diff --git a/skills/revloop/references/github-publication.md b/skills/revloop/references/github-publication.md index 3fb0ed3..433909d 100644 --- a/skills/revloop/references/github-publication.md +++ b/skills/revloop/references/github-publication.md @@ -169,7 +169,7 @@ Omit Open findings when there are none. Include optional confirmed behavior only
Run details -- 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} diff --git a/skills/revloop/references/review-contract.md b/skills/revloop/references/review-contract.md index cd3ec83..985bf96 100644 --- a/skills/revloop/references/review-contract.md +++ b/skills/revloop/references/review-contract.md @@ -157,12 +157,25 @@ 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 a configured fallback route when present. +- 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. diff --git a/skills/revloop/references/reviewer-adapters.md b/skills/revloop/references/reviewer-adapters.md index e480467..ae6f907 100644 --- a/skills/revloop/references/reviewer-adapters.md +++ b/skills/revloop/references/reviewer-adapters.md @@ -4,27 +4,29 @@ Use a fresh independent reviewer for every checkpoint. Keep reviewers read-only, ## Route selection -- Use the current harness native subagent route by default. -- Treat `codex` and `claude` as explicit provider selections. When the selected provider matches the current harness, use its native route. -- Use the CLI mappings below only for an explicitly selected external provider or a configured cross-provider fallback. -- Prefer a different provider for the fallback. Continue without a fallback when no second route is available. +- 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. -## Native reviewer +## Subagent reviewers -Treat the ability to start one fresh isolated subagent as the native preflight. Stop before editing when `native` is selected and that capability is unavailable. +Treat the ability to start at least one fresh isolated subagent as the `subagents` preflight. Stop before editing when this capability is unavailable. -Send only the reviewer prompt and self-contained brief. The reviewer must not call tools, inspect the repository, edit files, or delegate. Never fork or inherit the implementation conversation. +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. -In Codex, spawn one native isolated agent. When the tool is named `spawn_agent`, set `fork_turns` to `none`. Do not launch nested `codex exec` from an app-hosted Codex session. +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 Claude Code, invoke one non-forked subagent through the Claude Code `Agent` tool. Do not use `/subtask`, `context: fork`, or any route that inherits conversation history. +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. -Use the subagent's final response as the reviewer result. Never resume or reuse the reviewer after it returns. +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 an explicit Claude route or configured Claude fallback. In Claude Code, use an ephemeral Codex CLI process for an explicit Codex route or configured Codex fallback. In another shell-capable client, use the matching explicit CLI route below. +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 diff --git a/skills/revloop/scripts/test-static.sh b/skills/revloop/scripts/test-static.sh index 613730c..caea741 100755 --- a/skills/revloop/scripts/test-static.sh +++ b/skills/revloop/scripts/test-static.sh @@ -66,8 +66,9 @@ require_file_text "$SKILL_FILE" "record it as \`accepted_head\`" require_file_text "$SKILL_FILE" 'Any later worktree change, commit, push, or pull-request head change invalidates acceptance' require_file_text "$SKILL_FILE" 'Pending, failing, unavailable, or stale-head checks are not green.' require_file_text "$SKILL_FILE" 'Never claim completion after reviewer failure, malformed output, or a missing machine verdict.' -require_file_text "$SKILL_FILE" "Accept \`native\`, \`codex\`, or \`claude\` as the reviewer selector." -require_file_text "$SKILL_FILE" "When omitted, select \`native\`." +require_file_text "$SKILL_FILE" "Accept \`subagents\` or \`other\` as the review mode." +require_file_text "$SKILL_FILE" "When omitted, select \`subagents\`." +require_file_text "$SKILL_FILE" 'launch up to three reviewers and consolidate their results' reject_file_text "$SKILL_FILE" 'When omitted, select the other harness' require_file_text "$OPENAI_FILE" 'allow_implicit_invocation: false' require_file_text "$OPENAI_FILE" "Use \$revloop" @@ -76,6 +77,8 @@ require_file_text "$REVIEW_FILE" 'Specification gate: PASS' require_file_text "$REVIEW_FILE" 'Engineering gate: PASS' require_file_text "$REVIEW_FILE" "Record that SHA as \`accepted_head\`." require_file_text "$REVIEW_FILE" 'invalidates the accepted verdict' +require_file_text "$REVIEW_FILE" 'Set the consolidated verdict to `ACCEPT` only when every valid result is `ACCEPT`.' +require_file_text "$REVIEW_FILE" 'Treat the route as unavailable only when no reviewer returns a valid result.' for check in 'Correctness' 'Test quality' 'Maintainability' 'Architecture boundaries' 'Simplicity' 'Security' 'Operational safety'; do require_file_text "$REVIEW_FILE" "- $check: " done @@ -92,14 +95,16 @@ reject_file_text "$GITHUB_FILE" '## Revloop' require_file_text "$ADAPTERS_FILE" '--permission-mode dontAsk' require_file_text "$ADAPTERS_FILE" '--skip-git-repo-check' require_file_text "$ADAPTERS_FILE" 'read-only' -require_file_text "$ADAPTERS_FILE" 'Use the current harness native subagent route by default.' +require_file_text "$ADAPTERS_FILE" 'Use same-harness subagents by default.' +require_file_text "$ADAPTERS_FILE" 'Launch three reviewers concurrently when capacity permits.' require_file_text "$ADAPTERS_FILE" "\`fork_turns\` to \`none\`" require_file_text "$ADAPTERS_FILE" "Claude Code \`Agent\` tool" reject_file_text "$ADAPTERS_FILE" '--dangerously-skip-permissions' reject_file_text "$ADAPTERS_FILE" '--dangerously-bypass-approvals-and-sandbox' -require_file_text "$README_FILE" "\$revloop native" -require_file_text "$README_FILE" 'uses a fresh native subagent by default' +require_file_text "$README_FILE" "\$revloop subagents" +require_file_text "$README_FILE" "\$revloop other" +require_file_text "$README_FILE" 'uses up to three fresh same-harness subagents by default' require_file_text "$STACK_FILE" 'Never rebase or force-push a published stack branch.' require_file_text "$STACK_FILE" 'Mark accepted, unchanged pull requests ready from bottom to top.' From b49a440c2aea38ad3e96b52acbc196f15aee4f8e Mon Sep 17 00:00:00 2001 From: satyaborg Date: Sun, 16 Aug 2026 16:42:14 +1000 Subject: [PATCH 3/3] fix: satisfy shellcheck for review mode assertion --- skills/revloop/scripts/test-static.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/revloop/scripts/test-static.sh b/skills/revloop/scripts/test-static.sh index caea741..aa6e0f3 100755 --- a/skills/revloop/scripts/test-static.sh +++ b/skills/revloop/scripts/test-static.sh @@ -77,7 +77,7 @@ require_file_text "$REVIEW_FILE" 'Specification gate: PASS' require_file_text "$REVIEW_FILE" 'Engineering gate: PASS' require_file_text "$REVIEW_FILE" "Record that SHA as \`accepted_head\`." require_file_text "$REVIEW_FILE" 'invalidates the accepted verdict' -require_file_text "$REVIEW_FILE" 'Set the consolidated verdict to `ACCEPT` only when every valid result is `ACCEPT`.' +require_file_text "$REVIEW_FILE" "Set the consolidated verdict to \`ACCEPT\` only when every valid result is \`ACCEPT\`." require_file_text "$REVIEW_FILE" 'Treat the route as unavailable only when no reviewer returns a valid result.' for check in 'Correctness' 'Test quality' 'Maintainability' 'Architecture boundaries' 'Simplicity' 'Security' 'Operational safety'; do require_file_text "$REVIEW_FILE" "- $check: "