docs(skill): синхронизация README, фикс рекомендации Codex sandbox

- Зачем:
  - 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 <plan-path>, явное правило bare <file-path> → 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) <noreply@anthropic.com>
This commit is contained in:
2026-05-15 16:06:01 +03:00
co-authored by Claude Opus 4.7
parent a9f8d032f3
commit 657e7c3507
2 changed files with 63 additions and 24 deletions
+48 -15
View File
@@ -81,6 +81,13 @@ runs without operator access conclude unverified.
Mode is auto-detected from context, or you can force it with an argument. 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 ### What the reviewer can do
- **Read** any file in the repository - **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 - **Inspect git history** — blame, log, diff
The reviewer **must not** create, edit, or delete project files. The The reviewer **must not** create, edit, or delete project files. The
briefing forbids it. If your host supports an enforced read-only sandbox briefing forbids it — that's the primary control on both hosts and the
(Claude Code `disallowedTools`, Codex `sandbox_mode = "read-only"`), the default the skill ships with. The reason for keeping it briefing-only
skill recommends applying it on top. 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) ### 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, number, make confident tool-mechanic claims without empirical testing,
stay silent about rejections. 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 The skill explicitly invokes `superpowers:receiving-code-review` for the
evaluation step (and inlines its key principles for portability). 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 ln -s "$(pwd)" ~/.codex/skills/claude-team-review
``` ```
Codex supports intra-session continuation natively — the lead can send Codex supports intra-session continuation natively — the lead addresses
follow-up instructions to a running subagent thread (use `/agent` to the running subagent thread by name in its next instruction and Codex's
switch between active threads). The skill uses this for cheap re-review. orchestration routes the message there. The skill uses this for cheap
When the previous subagent thread is no longer active, Round 2+ goes re-review. (As an operator, you can use the `/agent` CLI command to
through the operator-gated fresh-spawn path (operator decides: spawn inspect or switch between active threads — it's a terminal tool, not
fresh with a full project re-read, or conclude unverified). 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 ## Usage
```bash ```bash
# Auto-detect what to review # Auto-detect what to review (from git state + conversation context)
/claude-team-review /claude-team-review
# Review a plan # Force a specific mode
/claude-team-review plan /claude-team-review plan
# Review code changes
/claude-team-review code /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 /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 xhigh
/claude-team-review plan xhigh
/claude-team-review code-vs-plan path/to/plan.md xhigh
``` ```
## Files in this skill ## Files in this skill
+15 -9
View File
@@ -145,19 +145,25 @@ prose, reasoning, descriptions, recommendations — in
The verbatim reply from the reviewer is shown to the operator as-is — do 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. not translate it back; it should already be in the operator's language.
**Tool restrictions:** the briefing's "must NOT modify files" rule is **Tool restrictions.** The briefing's "must NOT modify files" rule is
the primary control on the read path. The built-in `general-purpose` the primary control on both hosts and the default. **Do not reach for
subagent on Claude Code has no tool-restriction knob the lead can pass host-level sandboxes by reflex** — the reviewer also needs to run
at invocation time, so the briefing rule is the only control there. If things (tests, linters, git, MCP queries) to verify findings, and
you want enforced sandboxing on top, that requires going off the hard sandboxes that block writes typically block exec too, which guts
default path: 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 Code:** define a custom subagent (e.g.
`~/.claude/agents/adversarial-reviewer.md`) with frontmatter `~/.claude/agents/adversarial-reviewer.md`) with frontmatter
`disallowedTools: Write, Edit`, and dispatch that agent type instead `disallowedTools: Write, Edit`, and dispatch that agent type instead
of `general-purpose`. of `general-purpose`. The built-in `general-purpose` has no
- **Codex:** the host's `sandbox_mode = "read-only"` applies to the invocation-time tool-restriction knob.
spawned subagent natively. - **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.
--- ---