superreview

name	superreview
description	Generates a project-tailored deep-review skill (review+standards merged). Triggers: superreview, generate review skill

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.

Super Review Generator (brewcode:superreview)

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) modeled exactly on the canonical finagra shape: deterministic MODE resolution -> ANNOUNCE -> route changed files to project domain-owner agents -> reference (not restate) the project's .codex/rules + convention files -> ONE targeted parallel fan-out -> per-finding adversarial VALIDATION gate -> ONE merged P0-P3 report at .codex/reports/{TIMESTAMP}_superreview/REPORT.md, READ-ONLY (recommends /simplify, never edits).

Like skill-creator / task-board-init: a multi-step analysis that deploys a working artifact into ANY repo. 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.

---

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

Reconcile rule: the finagra shape is the canonical structure; standards-review + the review template supply the per-stack checks, the reuse matrix, and the report scaffolding that get baked INTO that shape.

---

Execution

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 finagra-shape emitted SKILL.md (with {PLACEHOLDER} slots)
   • references/agent-prompt.md — domain-owner agent prompt contract (emitted verbatim, scalar-substituted)
   • 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. Prefer grepai_search first for code exploration; fall back to Bash search (grep->ugrep / find->bfs on macOS CC).

EXECUTE using shell (project scan):

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	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
DB / test stack	testcontainers, JPA/JOOQ, pytest, jest, etc.	folded into the per-stack reference note

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:

• Which agent is the architecture arbiter / Phase-3 validator when several plausible reviewer/architect agents exist.
• The domain-owner mapping when an agent's owned path group is unclear.
• Whether to include a general second-pass agent mapping (built-in general-purpose) when no project reviewer exists.
• Confirm the dominant stack when the repo is genuinely multi-stack.

Weave the <fine-tune-prompt> argument into the emitted Focus ordering: if the user said "focus on X / weight Y higher", reorder/emphasize the emitted FOCUS_TABLE accordingly (e.g. push security to P0-always, or raise reuse to rank 1). Record the emphasis in FOCUS_EMPHASIS.

Phase 2 — Resolve placeholders + emit (scalar substitution)

Export the SCALAR placeholder values, then run the emit step (mirrors setup.sh copy_review_skill() — sed with a control-char separator; values MUST be single-line):

export PROJECT_NAME="<repo name>"
export STACK_LABEL="<Java/Kotlin | Node/TypeScript | Python | Go>"
export STACK_REF="<python.md | java-kotlin.md | typescript-react.md | go.md>"
export SOURCE_GLOB="<*.py | *.java | *.ts | *.go ...>"
export PATHSPEC_GLOBS="<'*.py' 'requirements*.txt' 'pyproject.toml' 'Dockerfile*' 'docker-compose.yml' '.github/workflows/*.yml'>"
export ARBITER_AGENT="<project architect agent | general-purpose>"
export VALIDATOR_AGENT="<project arbiter agent | general-purpose>"

EXECUTE using shell:

bash "<skill-directory>/scripts/generate.sh" emit && echo "✅ emit" || echo "❌ emit FAILED"

STOP if ❌ — verify <skill-directory>/references/SKILL.md.template exists and the target .codex/ is writable.

This writes <target>/.codex/skills/superreview/SKILL.md (scalars substituted), copies agent-prompt.md + report-template.md (scalar-substituted), and copies the chosen ${STACK_REF} into the emitted references/.

Phase 3 — Adapt the BLOCK placeholders (AI Edit)

Multi-row tables cannot go through sed (newlines). Using the Edit tool, replace each block placeholder in the EMITTED <target>/.codex/skills/superreview/SKILL.md with a table you build from Phase 1 analysis:

Block placeholder	Replace with
{DOMAIN_AGENTS_TABLE}	one row per project agent: | <agent> | Domain owner — <path glob>: <responsibility> | (built-in Explore as graceful fallback row)
{GENERAL_AGENTS_TABLE}	the {0,1,2} cross-cutting agents: <reviewer> (quality/correctness 2nd pass) + <ARBITER_AGENT> (boundary/architecture arbiter + Phase-3 validator), each with an "include WHEN" rule
{RULE_POINTER_TABLE}	one row per real .codex/rules/*.md + .codex/convention/*.md: | <file> | <one-line gist> | — REFERENCE, never restate
{RULE_PREFLIGHT_LIST}	the bash `for f in ...; do [ -f "$f" ]
{FILE_GROUP_MAP}	one row per source group: | <group> | <path pattern> | <subagent_type> | mapping each group to its domain owner; tests group -> the test agent (with test-bloat audit); build group -> the CI/build agent
{FOCUS_TABLE}	the ranked focus ordering (default: 1 correctness, 2 architecture/boundary, 3 reuse, 4 version pins, 5 business-reqs), REORDERED per the <fine-tune-prompt>
{FOCUS_EMPHASIS}	one-line note capturing the fine-tune-prompt emphasis (or "default ordering" if none)
{SIMPLIFY_AGENTS}	comma list of the domain-owner agents the fix-session should delegate to

Keep every emitted row pointing at a REAL agent (.codex/agents/ or built-in Explore/Plan/general-purpose) and a REAL rule file. Do NOT invent agents or rules. Built-in Explore is the only allowed fallback for an unavailable domain agent.

Phase 4 — Validate (NO {PLACEHOLDER} may remain)

EXECUTE using shell:

bash "<skill-directory>/scripts/generate.sh" validate && echo "✅ validate" || echo "❌ validate FAILED"

STOP if ❌ — the script lists any unresolved setup-time {PLACEHOLDER} left in the emitted SKILL.md / references (runtime tokens like {MODE}, {COUNT}, {FILE_LIST} are allow-listed and expected to remain). Go back to Phase 3 and Edit the leftovers, then re-run validate.

Phase 5 — Report

Print the generation summary:

superreview generated -> <target>/.codex/skills/superreview/

Stack:      {STACK_LABEL}  (reference: {STACK_REF})
Domain agents wired: {N}  ({list})
General agents: {reviewer?}, {ARBITER_AGENT} (arbiter + validator)
Rule pointers: {N} files referenced (not restated)
File groups:   {N}  ({group->agent})
Focus:         {resolved ordering — fine-tune: <emphasis>}

Files written:
- .codex/skills/superreview/SKILL.md
- .codex/skills/superreview/references/agent-prompt.md
- .codex/skills/superreview/references/report-template.md
- .codex/skills/superreview/references/{STACK_REF}

Run it:  /superreview "<focus>" [scope]   (in the target project)

---

How the emitted skill behaves (what you are generating)

Recap of the canonical shape the emitted SKILL.md implements (full text in references/SKILL.md.template):

Phase	Behavior
Mode detection	Deterministic FULL_PROJECT | EXPLICIT | UNCOMMITTED | LAST_COMMITS, COMPUTED not guessed; then ANNOUNCE mode+branch+scope+count+focus BEFORE any review
Routing	Group changed files by path; enable ONLY non-empty groups; route each to its domain-owner agent; add {0,1,2} general agents by judgement
Fan-out	ONE parallel message with the selected agents (find phase); each returns the shared JSON finding contract; search-first before flagging reuse/duplication
Validation	ONE arbiter agent reverse-validates EVERY candidate (adversarial, per-finding gate), merges + de-dups + prioritizes P0-P3
Report	ONE merged report at .codex/reports/{TIMESTAMP}_superreview/REPORT.md, sorted P0->P3; READ-ONLY; recommends /simplify + a Manager-mode fix session; never edits code

---

Configuration

Setting	Default	Description
Emit target	<cwd>/.codex/skills/superreview/	Where the generated skill is written
Emit templates	<skill-directory>/references/	Source templates for the generation
Generation script	<skill-directory>/scripts/generate.sh	scan | emit | validate
Stack reference	one of python.md | java-kotlin.md | typescript-react.md | go.md	Emitted per the dominant detected stack
Block placeholders	AI-filled (Edit)	Tables that cannot go through sed; validated post-emit

---

Error Handling

Condition	Action
No .codex/agents/ in target	Emit with built-in general-purpose + Explore only; warn the user the routing is generic
No .codex/rules//.codex/convention/	Emit a minimal rule-pointer table (AGENTS.md only); WARN; the emitted skill degrades gracefully (preflight WARN)
Unknown / unsupported stack	Emit with the closest per-stack ref + project rules only; warn
Multi-stack repo	Pick dominant stack for STACK_REF; note secondaries in the agent/group tables
Unresolved {PLACEHOLDER} after Phase 3	validate fails listing them; fix via Edit, re-run validate
Target .codex/ not writable	STOP — ask the user to run from the repo root

---

References

• references/SKILL.md.template — the finagra-shape emitted SKILL.md (placeholder slots).
• references/agent-prompt.md — domain-owner agent prompt contract (emitted).
• references/report-template.md — emitted merged-report layout.
• references/{python,java-kotlin,typescript-react,go}.md — per-stack reference docs (one is emitted).
• scripts/generate.sh — scan / emit / validate.