---
name: superreview-setup
description: "Generates a project-tailored deep-review skill: domain-expert routing + scope discipline (blast radius, delivery, closeout) + mechanical gates + adversarial validation. Triggers: superreview, generate review skill, deep review skill, scope discipline review"
---

# Project-tailored review

Inspect repository instructions, architecture, tests, and recent changes, then create a focused Codex review skill in the user-selected project `.codex/skills/` path. Encode evidence-based checks, severity guidance, and verification commands. Validate the generated skill and do not create Markdown agent definitions.

## Complete native workflow

Follow every phase below. When a phase delegates work, use Codex collaboration with only `task_name` and `message`; treat each "Codex delegation brief" block as role and message content, not executable syntax. Use `request_user_input` for the documented user gates. Resolve `<skill-directory>`, `<plugin-root>`, `<project-root>`, and `<arguments>` before running commands.

<!-- brewcode-meta: version=6.2.0 content_version=5.6.0 generated_by=brewcode:superreview-setup -->

# Super Review Generator (brewcode:superreview-setup)

**ROLE:** GENERATOR. This skill is HUMAN-invoked. It analyzes the TARGET project, then WRITES a self-contained,
project-local `.codex/skills/superreview/` into that project — the merged deep-review skill (`review` + `standards-review`
folded into one). It does NOT review code itself; it EMITS the skill that does.

**OUTPUT:** A project-local skill at `<target>/.codex/skills/superreview/` (SKILL.md + references) PLUS a project
agent at `<target>/.codex/agents/intent-guard.toml`, modeled exactly on the canonical shape: deterministic MODE
resolution + semantic DEPTH resolution -> MECHANICAL GATES -> ANNOUNCE -> the INTENT pass (`intent-guard`, both
depths) -> [EXTENDED only:] route changed files to project DOMAIN-EXPERT agents selected at RUNTIME -> resolve the
SANCTIONED SCOPE baseline -> reference (not restate) the project's `.codex/rules` + convention files -> ONE
targeted parallel fan-out (domain experts + 2 scope passes + intent) -> per-finding adversarial VALIDATION gate ->
scope gate (request_user_input) -> ONE merged P0-P3 report at
`.codex/reports/{TIMESTAMP}_superreview/REPORT.md`, READ-ONLY (recommends `/simplify`, never edits).

> **Three things make or break the emitted skill:**
> **(1) DOMAIN EXPERTS** — a review routed to generic agents finds generic issues. Phase 1.6 below is mandatory:
> discover the experts, and CREATE the missing ones before emitting.
> **(2) SCOPE DISCIPLINE** — the emitted skill measures every change against the SANCTIONED baseline (task + issue
> + recorded decisions): creep, blast radius, under-delivery, closeout. Phase 1.5 wires it to the target's tracker.
> **(3) THE INTENT PASS** — `intent-guard` answers "was the DELIVERED thing the ASKED thing?". It runs at BOTH
> depths and is the whole review at `QUICK`. Phase 1.6 + Phase 3 wire it to this project's real invariants.

> **The emitted skill has TWO orthogonal axes.** `{MODE}` selects SCOPE (`FULL_PROJECT` / `EXPLICIT` /
> `UNCOMMITTED` / `LAST_COMMITS`). `{DEPTH}` selects EFFORT: **`QUICK`** (the DEFAULT and common case — mechanical
> gates + the intent pass, ONE spawn, no domain experts) or **`EXTENDED`** (the full fan-out + validation + scope
> gate, plus the intent pass). Depth is inferred SEMANTICALLY from the user's prompt, exactly like the `{MODE}`
> whole-project rule — **there is no `--fast`, no flag and no CLI token, and you must not add one.**

> The emitted skill is generic-capable (Java/Kotlin, Node/TS, Python, Go) and self-contained — NO plugin dependency,
> NO sibling-skill orchestration once generated.

**Arguments:** `<arguments>` — `<fine-tune-prompt>` (free text: what to emphasize in the emitted skill's focus ordering)
plus optional `[scope]` hint. The fine-tune prompt is woven into the emitted skill's Focus ordering + emphasis.

---

## Prompt contract

Position 1 of `<arguments>` is a **free-form prompt** (RU/EN) — verbs and flags are optional and may
follow in any order. Nobody types keys: resolve the verb + fine-tune focus FROM the prompt.

1. Strip flags. An explicit verb token anywhere wins outright, no scoring — the seven canonical verbs
   are in the Verb routing table below.
2. Else score verbs by distinct whole-word keyword hits (Verb routing table below). Highest unique
   score wins. Tie involving `purge` (destructive) -> `request_user_input`; tie with `status` ->
   `status`; tie of two mutating verbs -> the keyword appearing first; all zero -> `status` if
   `.codex/skills/superreview/SKILL.md` or its `.disabled` twin exists, else `install`.
3. Empty arguments -> the default above; ask ONE scoping `request_user_input` only when the answer
   changes what gets written. `status` asks nothing.
4. Outcome-changing ambiguity -> ONE `request_user_input` (max 4 questions) BEFORE any work.
5. Prose that names no verb is the fine-tune prompt, not an error — it is woven into the emitted
   skill's Focus ordering (Phase 1.5), never treated as the verb by its first word.

Then print this block ONCE, before the resolved verb runs:

```
PLAN — brewcode:superreview-setup
INPUT:  <arguments verbatim, or "(empty)">
MODE:   <resolved verb> — <explicit | matched keyword: X | default>
SCOPE:  <target repo, fine-tune focus, scope hint>
DO:     <2-5 imperative bullets>
RESULT: <what the user ends up holding>
```

Labels are literal; values follow the conversation language.

---

## What the emitted skill merges (review + standards-review)

| Source | What it contributes to the emitted skill |
|--------|------------------------------------------|
| `review` engine | Canonical STRUCTURE: deterministic mode, two-phase **find -> validate**, single merged P0-P3 report, agent prompt contract, report scaffolding |
| `standards-review` | The **reuse/duplication** focus (rank 3: search-first 90/70/50% reuse matrix), tech-stack detection, file-grouping-by-type, per-stack reviewer guidelines, `/simplify` hand-off |
| `setup` Phase 3.5 | Tech-specific check tables (Java/Node/Python/Go) folded into the per-stack reference docs; the placeholder -> concrete generation mechanism |
| Scope discipline | `references/scope.md.template`: sanctioned-baseline resolution + precedence, ownership map + always-shared surfaces, the 6-shape creep taxonomy, the delivery map D1-D5 with PROOF OF ABSENCE, the closeout map C1-C4, the NOT-creep exclusion list, the Phase 3b user gate |
| Runtime expertise | `references/agent-prompt.md`: live-roster expert selection, recon-agent exclusion, DEGRADED marking when a surface has no owner |
| Execution ground truth | Mechanical gates -> `CONFIRMED-BY-EXECUTION`, the only non-adversarial verdict; `UNVALIDATED` -> the run is `INCOMPLETE` |

> Reconcile rule: the canonical shape is the STRUCTURE; `standards-review` + the `review` template supply the
> per-stack checks, the reuse matrix and the report scaffolding baked INTO it; the scope + expert-selection
> references supply the two axes that make the review project-specific rather than generic.

---

## Execution

### Verb routing — resolve FIRST, before anything else

`<arguments>` may start with one of the seven canonical verbs, in this order:
`status | install | upgrade | enable | disable | uninstall | purge`. Anything else is the fine-tune
prompt and takes the free-form path. Strip the verb before using the rest as the fine-tune prompt.

Removed aliases that must never be accepted or printed: `init`, `on`, `off`, `setup`, `remove`,
`reset`, `create`, `update`, `cleanup`. Recognize them in free text, echo the canonical verb back.

| Verb | EN keywords | RU keywords | What runs | Mutates? |
|------|-------------|-------------|-----------|----------|
| `status` | *(empty)*, `status`, `check`, `show` | `статус`, `проверь`, `покажи` | read-only: is `.codex/skills/superreview/` there, is it ENABLED or parked, is `.codex/agents/intent-guard.toml` present, is `.template-baseline/` there? Then `generate.sh validate` and report. **STOP** — no phases run | no |
| `install` | `install`, `setup`, `generate`, `set up`, `create` | `настрой`, `установи`, `сгенерируй` | the full generate flow, Phase 0 -> Phase 4 below | yes |
| `upgrade` | `upgrade`, `update`, `refresh templates` | `обнови`, `апгрейд` | Phase 2b only (`generate.sh upgrade`), then Phase 3 for any `MISSING -> restored` asset, then Phase 4 `validate`. **STOP** | live files only via targeted Edit |
| `enable` | `enable`, `on`, `turn on`, `activate` | `включи`, `активируй` | `generate.sh enable` — un-parks the installed skill. **STOP** | one rename |
| `disable` | `disable`, `off`, `turn off`, `pause` | `выключи`, `отключи`, `пауза` | `generate.sh disable` — parks the installed skill without deleting anything. **STOP** | one rename |
| `uninstall` | `uninstall`, `remove`, `delete skill` | `удали`, `убери` | `generate.sh uninstall` — deletes the generated skill dir, KEEPS the reports and `intent-guard.toml`. Confirm once. **STOP** | deletes |
| `purge` | `purge`, `wipe`, `remove everything`, `nuke` | `вычисти`, `удали полностью` | `generate.sh purge` — uninstall + deletes `.codex/reports/*_superreview/`. Still keeps `intent-guard.toml`. Confirm once, naming the report count. **STOP** | deletes, destructive |
| *(no args at all)* | — | — | `status` when `.codex/skills/superreview/` exists, otherwise `install` | status: no |
| *(no verb, but a prompt)* | — | — | same as `install`; the whole `<arguments>` is the fine-tune prompt | yes |

Print the PLAN block (Prompt contract above) now, before running the resolved verb.

**EXECUTE** using shell (`status` only):
```bash
if test -f .codex/skills/superreview/SKILL.md; then echo "installed: enabled"
elif test -f .codex/skills/superreview/SKILL.md.disabled; then echo "installed: DISABLED (parked as SKILL.md.disabled — run 'enable' to restore)"
elif test -d .codex/skills/superreview; then echo "installed: BROKEN (dir present, no SKILL.md and no SKILL.md.disabled)"
else echo "not_installed"; fi
test -f .codex/agents/intent-guard.toml && echo "intent-guard: present" || echo "intent-guard: MISSING"
test -d .codex/skills/superreview/.template-baseline && echo "baseline: present" || echo "baseline: absent (pre-baseline install)"
echo "reports: $({ find .codex/reports -maxdepth 1 -type d -name '*_superreview' 2>/dev/null || true; } | wc -l | tr -d ' ') dir(s) — deleted by 'purge', kept by 'uninstall'"
bash "<skill-directory>/scripts/generate.sh" validate && echo "✅ validate" || echo "❌ validate FAILED"
```

> `status` never writes and never asks. `not_installed` -> report it and offer `install`; nothing else.
> `installed: DISABLED` is a state, not a fault — report it and offer `enable`. `validate` fails on a
> disabled install (it looks for `SKILL.md`); say so rather than presenting it as a broken installation.

---

### Modes: enable | disable | uninstall | purge

| Mode | Generated skill dir | `references/` + `.template-baseline/` | Phase 3 tailoring | `.codex/reports/*_superreview/` | `intent-guard.toml` |
|------|--------------------|---------------------------------------|-------------------|----------------------------------|-------------------|
| `enable` | `SKILL.md.disabled` -> `SKILL.md` | kept | kept | kept | kept |
| `disable` | `SKILL.md` -> `SKILL.md.disabled` | kept | kept | kept | kept |
| `uninstall` | **deleted** | deleted with it | lost | **kept** | kept |
| `purge` | **deleted** | deleted with it | lost | **deleted** | kept |

**How the toggle works.** Codex discovers a project skill only through `<dir>/SKILL.md`.
`disable` renames that ONE file to `SKILL.md.disabled`, so `/superreview` stops being offered while
`references/`, `.template-baseline/` and every Phase 3 tailoring stay byte-identical on disk. `enable`
renames it back. Nothing is regenerated in either direction, so no `version` is bumped and no
self-synced edit is at risk. Use `disable` to park a review setup that is temporarily noisy; use
`uninstall` when it should really go. Both take effect in the NEXT session — skills are discovered at
session start.

**`intent-guard` is never touched by any of the four.** `generate.sh` (`emit`/`emit-agent`) is its
only writer, and it is shared with `$brewcode:teams-setup`, which may have put it there. Deleting or
parking it would silently break an unrelated team install. All four modes print it as `KEPT`.

**Confirm before deleting.** `uninstall` and `purge` each `request_user_input` exactly once, listing the
real paths (`find .codex/skills/superreview -type f | sort`) and, for `purge`, the number of review
reports being destroyed, with `uninstall` offered as the keep-the-reports alternative. A declined
confirmation ends the run cleanly — delete nothing.

**EXECUTE** using shell (the chosen verb, after confirmation where required):
```bash
bash "<skill-directory>/scripts/generate.sh" MODE_HERE && echo "✅ MODE_HERE" || echo "❌ MODE_HERE FAILED"
```

Then report the script's `MOVED:` / `REMOVED:` / `KEPT:` lines verbatim. Not installed at all ->
say so and **STOP**; never "disable" or "purge" something that was never emitted.


### Delegation (applies to every sub-agent task this generator spawns AND to the fan-out it emits)

A big task handed to one agent = an agent gone for an hour: you cannot observe it, cannot correct
it, and it usually drifts off-target. One subagent = ONE bounded unit — one deliverable
(here: ONE file group's review), ~<=5 files, ~<=10 steps. Bigger MUST be split into N tasks, all
spawned in ONE message — that is why the emitted skill routes file GROUPS to domain owners.

Every spawn prompt MUST carry:

| Field | Content |
|-------|---------|
| GOAL | the overall task and why it exists — the point beyond the file edit |
| ROLE | what this agent owns; what it must NOT touch |
| SCOPE | exact paths/commands in bounds + explicit out-of-bounds |
| CONTEXT | what is already done, by whom, what runs in parallel — trimmed to what THIS agent needs |
| CONSUMER | who or what uses the result next, and the shape it must fit |
| DONE | acceptance criteria + the exact report shape you want back |

A bare one-line task is never enough. When filling `{FILE_GROUP_MAP}` in Phase 3, keep every group
small enough to be one bounded unit — split an oversized group into two rows rather than emitting a
single agent that owns half the repo.

### Phase 0 — Pre-analysis (read THIS skill's emit material)

1. Read the emit templates this generator ships (relative to `<skill-directory>`):
   - `references/SKILL.md.template` — the emitted SKILL.md (with `{PLACEHOLDER}` slots)
   - `references/agent-prompt.md` — runtime expert selection + domain-owner prompt contract (emitted, substituted)
   - `references/scope.md.template` — scope-discipline reference (emitted as the target's `references/scope.md`)
   - `references/intent-guard.md.template` — the anti-drift agent (emitted as `<target>/.codex/agents/intent-guard.toml`;
     READ it before Phase 3 — you fill three BLOCKs in it). Its own header comment documents every placeholder;
     `generate.sh` STRIPS that header on emit
   - `references/report-template.md` — emitted report layout
   - `references/{python,java-kotlin,typescript-react,go}.md` — per-stack reference docs (one is emitted)
2. Confirm the TARGET project is the current working directory (the repo to be reviewed). All emitted paths are
   relative to that repo root.

### Phase 1 — Analyze the TARGET project

Gather everything the emitted skill must be wired to. Explore the code with Bash search (`grep`->ugrep / `find`->bfs
on macOS CC; native Grep/Glob are no-ops there).

**EXECUTE** using shell (project scan):
```bash
bash "<skill-directory>/scripts/generate.sh" scan && echo "✅ scan" || echo "❌ scan FAILED"
```

The scan reports: build files, `.codex/agents/*`, `.codex/rules/*` + `.codex/convention/*`, test dirs, source dirs.
From it (plus your own reads) determine:

| Aspect | How to detect | Drives placeholder |
|--------|---------------|--------------------|
| Tech stack | build files: `pom.xml`/`build.gradle*` -> Java/Kotlin; `package.json`+react/ts -> Node/TS; `pyproject.toml`/`requirements*.txt` -> Python; `go.mod` -> Go | `STACK_LABEL`, `STACK_REF`, `SOURCE_GLOB`, `PATHSPEC_GLOBS` |
| Project agents | `.codex/agents/*.toml` (name + description); map each to the path group it owns; flag READ-ONLY recon agents (cloud/SaaS/tracker consoles) as NON-reviewers | `DOMAIN_AGENTS_TABLE`, `FILE_GROUP_MAP`, `GENERAL_AGENTS_TABLE` |
| Arbiter / validator | an architecture/reviewer agent in `.codex/agents/`, else built-in `general-purpose` | `ARBITER_AGENT`, `VALIDATOR_AGENT` |
| Rule + convention files | `.codex/rules/*.md` + `.codex/convention/*.md` + `AGENTS.md` | `RULE_POINTER_TABLE`, `RULE_PREFLIGHT_LIST` |
| Source path groups | top-level source dirs / service dirs / module layout | `FILE_GROUP_MAP` |
| **Mechanical gates** | the REAL build/lint/type/test commands (`package.json` scripts, Makefile, gradle tasks, `pytest`, `go test`), plus where they run from | `GATE_COMMANDS` |
| **Scope tracker** | `.codex/features/**` board, `gh` + `.github/`, Jira/Linear config, branch naming `<type>/<issue>-<slug>` | `TRACKER_LABEL`, `BASELINE_RESOLUTION_BASH`, `SANCTION_PRECEDENCE_TABLE`, `SCOPE_AGENT_A/B` |
| **Shared surfaces** | public API/contract dirs, DB migrations, schema/registry files, CI workflows, dependency manifests, design tokens | `SHARED_SURFACES_TABLE`, `OWNERSHIP_SIGNALS_BASH` |
| Team parallelism | contributors in `git shortlog -sn --since=3.months`, owner columns on the board | `TEAM_NOTE` |
| DB / test stack | testcontainers, JPA/JOOQ, pytest, jest, etc. | folded into the per-stack reference note |
| **Intent tier sources** | Tier 2 = spec/design-doc dirs (`.codex/specs/**`, `docs/specs/**`, an ADR dir); Tier 3 = plan / task board / task graph (`.codex/features/**`, `TASKS.md`); Tier 4 = policy (root + nested `AGENTS.md`, `.codex/rules/**`, `.codex/convention/**`). Tier 1 is `TRACKER_LABEL`, already detected. Absent -> the literal string `none` | `SPEC_LOCATION`, `PLAN_LOCATION`, `POLICY_LOCATION` |
| **Project invariants** | READ them, do not guess: PLANNED SCALE (users/RPS/data volume stated in README/AGENTS.md/specs — "personal tool" and "10k RPS" produce opposite drift verdicts); TESTING POLICY (the project's own testing rule: few scenario tests vs full-coverage); DEPENDENCY POLICY (pinning rule, "reuse before adding", vendored/allowed sets); FILE-LAYOUT POLICY (one-file-per-what, module boundaries, naming conventions); ARCHITECTURE STANCE (the pattern the project actually committed to, and what it explicitly rejected) | `PROJECT_INVARIANTS_TABLE` |
| **Known drift instances** | past over-engineering in this repo's history + what its rules explicitly FORBID (an `avoid.md` row IS a drift class someone already hit) + the vocabulary this team uses for it | `DRIFT_EXAMPLES_TABLE` |
| **Cheap evidence commands** | this repo's real one-liners: `git diff --stat` on the resolved range, the dependency-manifest diff for THIS manifest (`package.json` / `pom.xml` / `pyproject.toml` / `go.mod`), new-file listing, test-file count under the real test dirs | `EVIDENCE_COMMANDS_BASH` |

**Multi-stack repos:** if more than one stack is detected, pick the DOMINANT one for the emitted `STACK_REF`, and note
the secondary stack(s) in `DOMAIN_AGENTS_TABLE` / `FILE_GROUP_MAP`. (One stack reference doc is emitted; the rule
pointers cover the rest.)

### Phase 1.5 — Clarify genuinely ambiguous params (request_user_input)

Use request_user_input ONLY for params you cannot reliably infer. Never auto-guess a non-obvious choice. Typical questions:

- **The scope baseline** — which tracker sanctions work (file board / GitHub issues / Jira / none), and the
  branch -> issue convention. Without it the emitted skill caps every scope finding at P2, so ASK when unsure.
- **Always-shar