diff --git a/README.md b/README.md index b3f1df4..1934ead 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,13 @@ runs without operator access conclude unverified. Mode is auto-detected from context, or you can force it with an argument. +### Language + +The skill detects the operator's session language from recent +conversation and instructs the reviewer to respond in it. No flag, +no configuration. If you write to Claude in Russian, the reviewer's +findings come back in Russian. + ### What the reviewer can do - **Read** any file in the repository @@ -89,9 +96,24 @@ Mode is auto-detected from context, or you can force it with an argument. - **Inspect git history** — blame, log, diff The reviewer **must not** create, edit, or delete project files. The -briefing forbids it. If your host supports an enforced read-only sandbox -(Claude Code `disallowedTools`, Codex `sandbox_mode = "read-only"`), the -skill recommends applying it on top. +briefing forbids it — that's the primary control on both hosts and the +default the skill ships with. The reason for keeping it briefing-only +is that the reviewer also needs to **run things** (tests, linters, git, +MCP queries) to verify findings — hard sandboxes that block writes tend +to block exec too, which would gut the reviewer. + +If you accept that trade-off and want enforced no-write on top, both +hosts have an option: + +- **Claude Code:** define a custom subagent (e.g. + `~/.claude/agents/adversarial-reviewer.md`) with + `disallowedTools: Write, Edit` and dispatch that agent type. The + built-in `general-purpose` agent has no invocation-time + tool-restriction knob, so this path requires the custom definition. +- **Codex:** `sandbox_mode = "read-only"` applies natively, but it also + disables shell exec for the subagent — the reviewer will not be able + to run tests or commands. Use only when you specifically want a + read-only audit and are willing to give up empirical verification. ### What the lead does (and does NOT do) @@ -104,6 +126,12 @@ applied/re-scoped/rejected-with-reasoning format. number, make confident tool-mechanic claims without empirical testing, stay silent about rejections. +**Pauses the operator** only on **structural** fixes — changes to the +invocation grammar, output contract, workflow states, or the meaning of +public options. Wording and factual fixes apply silently; the operator +sees the full breakdown in the round summary. One pause per round at +most, never one per finding. + The skill explicitly invokes `superpowers:receiving-code-review` for the evaluation step (and inlines its key principles for portability). @@ -160,30 +188,35 @@ mkdir -p ~/.codex/skills ln -s "$(pwd)" ~/.codex/skills/claude-team-review ``` -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). +Codex supports intra-session continuation natively — the lead addresses +the running subagent thread by name in its next instruction and Codex's +orchestration routes the message there. The skill uses this for cheap +re-review. (As an operator, you can use the `/agent` CLI command to +inspect or switch between active threads — it's a terminal tool, not +something the lead invokes.) 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 ```bash -# Auto-detect what to review +# Auto-detect what to review (from git state + conversation context) /claude-team-review -# Review a plan +# Force a specific mode /claude-team-review plan - -# Review code changes /claude-team-review code +/claude-team-review code-vs-plan # uses the plan most recently shown in the conversation +/claude-team-review code-vs-plan path/to/plan.md # explicit plan file -# Review a specific file +# A bare file path is treated as a plan to review /claude-team-review path/to/plan.md -# Use maximum reasoning effort for the reviewer +# xhigh is an effort flag, orthogonal to mode — combine with any of the above /claude-team-review xhigh +/claude-team-review plan xhigh +/claude-team-review code-vs-plan path/to/plan.md xhigh ``` ## Files in this skill diff --git a/SKILL.md b/SKILL.md index 09c5c7e..c61d72e 100644 --- a/SKILL.md +++ b/SKILL.md @@ -145,19 +145,25 @@ prose, reasoning, descriptions, recommendations — in The verbatim reply from the reviewer is shown to the operator as-is — do not translate it back; it should already be in the operator's language. -**Tool restrictions:** the briefing's "must NOT modify files" rule is -the primary control on the read path. The built-in `general-purpose` -subagent on Claude Code has no tool-restriction knob the lead can pass -at invocation time, so the briefing rule is the only control there. If -you want enforced sandboxing on top, that requires going off the -default path: +**Tool restrictions.** The briefing's "must NOT modify files" rule is +the primary control on both hosts and the default. **Do not reach for +host-level sandboxes by reflex** — the reviewer also needs to run +things (tests, linters, git, MCP queries) to verify findings, and +hard sandboxes that block writes typically block exec too, which guts +the reviewer. + +If the operator explicitly wants enforced no-write on top and accepts +the trade-off, both hosts have an option: - **Claude Code:** define a custom subagent (e.g. `~/.claude/agents/adversarial-reviewer.md`) with frontmatter `disallowedTools: Write, Edit`, and dispatch that agent type instead - of `general-purpose`. -- **Codex:** the host's `sandbox_mode = "read-only"` applies to the - spawned subagent natively. + of `general-purpose`. The built-in `general-purpose` has no + invocation-time tool-restriction knob. +- **Codex:** `sandbox_mode = "read-only"` applies natively, **but also + disables shell exec for the subagent** — the reviewer will not be + able to run tests or commands. Use only when the operator wants a + read-only audit and is willing to give up empirical verification. ---