From 657e7c350767ec625bc3655153ffb29fa6e40b3a Mon Sep 17 00:00:00 2001 From: Dmitry Dementiev Date: Fri, 15 May 2026 16:06:01 +0300 Subject: [PATCH] =?UTF-8?q?docs(skill):=20=D1=81=D0=B8=D0=BD=D1=85=D1=80?= =?UTF-8?q?=D0=BE=D0=BD=D0=B8=D0=B7=D0=B0=D1=86=D0=B8=D1=8F=20README,=20?= =?UTF-8?q?=D1=84=D0=B8=D0=BA=D1=81=20=D1=80=D0=B5=D0=BA=D0=BE=D0=BC=D0=B5?= =?UTF-8?q?=D0=BD=D0=B4=D0=B0=D1=86=D0=B8=D0=B8=20Codex=20sandbox?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - README отстал от SKILL.md после двух раундов self-review — формы инвокации, /agent, disallowedTools описаны неверно. - Рекомендация Codex sandbox_mode = "read-only" была ошибочной: она запрещает не только запись, но и exec — ревьюер не сможет запускать тесты, линтеры, git, MCP-запросы (а это основа верификации находок). - Что: - README и SKILL.md: блок «Tool restrictions» переписан — briefing-only по умолчанию на обоих хостах; жёсткая sandbox упомянута как опция с явным trade-off (на Codex теряется exec). - README: Usage block обновлён — добавлены code-vs-plan и code-vs-plan , явное правило bare → plan, xhigh как ортогональный effort flag. - README: новая короткая секция Language (ответы ревьюера на языке оператора, без флага). - README: bullet про structural-only паузы оператора в «What the lead does». - README: /agent в Codex section переформулирован как CLI оператора, а не tool лида. - Проверка: - git diff main..HEAD -- README.md SKILL.md - Прочитать README целиком и убедиться, что нет противоречий с SKILL.md. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 63 ++++++++++++++++++++++++++++++++++++++++++------------- SKILL.md | 24 +++++++++++++-------- 2 files changed, 63 insertions(+), 24 deletions(-) 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. ---