diff --git a/EXPERIMENT.md b/EXPERIMENT.md index d7df4cb..660657f 100644 --- a/EXPERIMENT.md +++ b/EXPERIMENT.md @@ -1,5 +1,14 @@ # Эксперимент: как две модели ревьюят один и тот же план +> **Note (2026-05-15):** This write-up predates the cross-platform +> redesign of `claude-team-review`. It refers to artifacts that no +> longer exist in their original form — specifically `adversarial- +> reviewer.md` (a Claude Code agent definition that has been replaced +> by `reviewer-prompt.md`, a host-agnostic briefing template). The +> historical descriptions below are preserved as-is for the experiment +> record; for the current skill structure, see `SKILL.md` and +> `reviewer-prompt.md`. + Opus и GPT-5.4 получили одинаковый план и одинаковую adversarial установку. Нашли разные проблемы. Этот документ — полный ход эксперимента: от наивного запуска до контролируемого сравнения. diff --git a/README.md b/README.md index cda31c6..b3f1df4 100644 --- a/README.md +++ b/README.md @@ -62,8 +62,10 @@ the same host as the lead. ``` The lead tries to **continue the same reviewer** for re-review when the -host supports it (cheaper — context is preserved). When continuation is -unavailable (Codex, or Claude Code without Agent Teams), or when the +host supports it (cheaper — context is preserved). Codex supports +intra-session continuation natively; Claude Code requires Agent Teams +(`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`) for the `SendMessage`-based +continuation path. When continuation is unavailable, or when the previous reviewer is no longer reachable, the lead asks the operator before spawning a fresh subagent — full project re-read is expensive, and the operator may prefer to conclude the review unverified. Headless @@ -129,8 +131,9 @@ ln -s "$(pwd)" ~/.claude/skills/claude-team-review Claude Code watches `~/.claude/skills/` for changes and will pick the skill up without a restart. -**Optional — enable Agent Teams for cheaper re-review** (continuation -between rounds instead of fresh-spawn). Add to your Claude Code settings: +**Recommended — enable Agent Teams** for cheaper re-review. Continuation +across rounds uses `SendMessage`, which is gated on Agent Teams. Add to +your Claude Code settings: ```json { @@ -140,9 +143,11 @@ between rounds instead of fresh-spawn). Add to your Claude Code settings: } ``` -The skill works fine without Agent Teams — it falls back to a fresh -subagent each round, with the previous-rounds context block packed into -the briefing. +Without Agent Teams, the Task-tool spawn is one-shot — every Round 2+ +re-review goes through the operator-gated fresh-spawn path (the operator +decides between spawning a fresh subagent that re-reads the project, or +concluding the review unverified). Headless runs without an operator +conclude as `NOT VERIFIED`. ### Codex @@ -155,11 +160,12 @@ mkdir -p ~/.codex/skills ln -s "$(pwd)" ~/.codex/skills/claude-team-review ``` -Codex spawns subagents without context continuation across spawns. The -skill treats every re-review on Codex as an operator-gated decision — -the lead asks whether to spawn a fresh subagent (full project re-read, -expensive) or conclude without verification. Continuation can be added -later if Codex grows that feature. +Codex supports intra-session continuation natively — the lead can send +follow-up instructions to a running subagent thread (use `/agent` to +switch between active threads). The skill uses this for cheap re-review. +When the previous subagent thread is no longer active, Round 2+ goes +through the operator-gated fresh-spawn path (operator decides: spawn +fresh with a full project re-read, or conclude unverified). ## Usage diff --git a/SKILL.md b/SKILL.md index 4a7dfef..466b564 100644 --- a/SKILL.md +++ b/SKILL.md @@ -63,11 +63,18 @@ message "Plan mode is active" → mode = `plan`, skip git. pass it the briefing assembled from `reviewer-prompt.md`. - **Claude Code:** Task tool with `general-purpose` type, OR — if Agent - Teams is enabled — spawn a teammate. Teammates support continuation - between rounds, which makes re-review cheaper. Both work; pick what's - available. + Teams is enabled — spawn a teammate. Note: **only Agent Teams supports + continuation between rounds** (via `SendMessage`, which is gated on + `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). Without Agent Teams, the + Task tool spawn is one-shot — Round 2+ has to go through the operator- + gated fresh-spawn path in Step 6. - **Codex:** native subagent spawn (host orchestrates spawn/wait/consolidate). -- **Other hosts:** equivalent subagent mechanism. + Codex supports intra-session continuation — the lead can send follow-up + instructions to a running subagent thread, and `/agent` switches between + active threads. +- **Other hosts:** equivalent subagent mechanism. The skill works as long + as the host can spawn a subagent and (optionally) route follow-up + messages to it. The reviewer is a full agent session — it explores the repo, runs git commands, and reads files on its own. **Do not pre-collect diffs or file @@ -120,9 +127,10 @@ This step exists because the reviewer may be technically wrong — and applying its findings blindly causes real damage (large structural edits based on cited issues that turn out to be feature requests, not bugs). -**REQUIRED SUB-SKILL:** Use `superpowers:receiving-code-review` if it's -available on the host. The key principles are inlined below for portability; -the full skill has more depth. +**Use `superpowers:receiving-code-review` when available** — it has the +full discipline for this step. The key principles are inlined below as +the always-available fallback (so the matrix step works on any host, +even where Superpowers is not installed). ### Build the evaluation matrix @@ -269,11 +277,20 @@ digraph re_review { } ``` +**Continuation support, by host (verify against current docs before +relying on this):** + +| Host | Continuation | Mechanism | +|---|---|---| +| Claude Code + Agent Teams (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`) | yes | `SendMessage` to the teammate inbox | +| Claude Code without Agent Teams | **no** — Task spawn is one-shot | — | +| Codex | yes — intra-session | follow-up message to a running thread; `/agent` to switch | + Two routes lead to the "ask operator" step: -- The host has no continuation mechanism (e.g. Codex) — every round - after Round 1 lands here +- The host has no continuation mechanism for our use case (Claude Code + without Agent Teams) — every round after Round 1 lands here - The host has continuation but the previous reviewer is no longer - reachable (process ended, inbox dead) + reachable (process ended, thread closed, inbox dead) **Detecting a dead reviewer (continuation-supporting hosts).** When the send call returns only a routing acknowledgment (e.g. `{"success": true, @@ -282,6 +299,16 @@ the reviewer process has ended; the message went to a dead inbox. Do not wait. Treat the reviewer as unreachable, fall through to the operator question. +**Detecting an operator.** Treat the run as **interactive** (operator +available) only if both conditions hold: + +1. The current conversation has a direct human message — not just an + automated trigger, hook, scheduled run, or CI invocation +2. The host exposes a user-facing channel to surface the question + +When in doubt, default to **presenting the choice** — pausing once is +cheaper than concluding unverified by mistake. + **Asking the operator.** Present the choice plainly: ```