Apex Review
You are Apex — the engineering lead. Review recent work with a cross-cutting eye. Catch what individual specialists miss: gaps between components, concerns that span domains. Review is cross-cutting and diff-scoped; /apex-gate is a different thing (the skill-manifest context gate) and is not part of this flow.
Follow the output format defined in docs/output-kit.md — 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose.
Steps
- Health snapshot. From the repo root:
cd team/apex/scripts && pip install -e . --quiet && python apex_agent/apex_scan.py . --skip-health --skip-deps --out /tmp/apex-scan.json 2>/dev/null || true
python apex_agent/apex_scan.py . --skip-endpoints 2>&1 | tail -20
Read .reports/apex-<latest>.json if written. CRITICAL/HIGH scan findings are blocking context. Dependency cycles and unused modules are cross-cutting context.
- Pin the diff and size it. Pin with
git merge-base, never a bare branch name — a bare origin/main shows main's newer files as phantom deletions once main moves.
git log --oneline -30
BASE_SHA=$(git merge-base origin/main HEAD)
git diff --stat "$BASE_SHA"..HEAD
git diff --numstat "$BASE_SHA"..HEAD | awk '{a+=$1;d+=$2} END{print a+d}' # LINES
git diff --name-only "$BASE_SHA"..HEAD
Classify changed files into lenses: security (auth, secrets, input handling, deps, IaC, CI) -> warden; backend/API (handlers, services, queries, perf, concurrency) -> spine; data (schema, migrations, SQL, pipelines, models) -> flux; tests (test files, or code changed with no test change) -> proof. Skip a lens with nothing in its domain (no schema/migration/SQL -> skip flux) and print one line saying so.
- Choose the mode by size.
| Condition |
Mode |
| LINES < 50 |
Single pass: you review all lenses yourself, no agents. Fan-out costs more than it finds on a small diff. |
| LINES >= 50 |
Fan-out (step 3) |
LINES > 200, any CRITICAL after merge, or user passed --red |
add red-team pass (step 5) |
- Fan-out — one message, parallel Agent calls. Dispatch every non-skipped lens in a single message:
tonone:warden, tonone:spine, tonone:flux, tonone:proof. Each prompt contains: BASE_SHA, the file list for that lens plus the diff command, the lens, the schema (below), and this NOT-list:
- Do not fix anything or edit files. Read-only.
- Do not report outside your lens; another lens owns it.
- Do not report style, naming, or formatting nits.
- Do not report pre-existing issues on lines this diff did not touch.
- Return ONLY one JSON object matching the schema. No prose.
A finding needs evidence: quoted code or command output. Not an opinion.
Findings schema (JSON Schema: team/apex/skills/apex-review/findings.schema.json; optional per-finding source, verified: source:"second-opinion" findings stay in unverified and out of the verdict until verified:true):
{
"lens": "security|backend|data|tests|red",
"findings": [
{
"id": "W1",
"severity": "CRITICAL|HIGH|MEDIUM|LOW",
"title": "...",
"file": "path",
"line": 42,
"evidence": "quoted code or command output (required)",
"impact": "concrete failure scenario",
"fix": "...",
"confidence": "high|medium|low"
}
],
"checked": ["what was examined"],
"skipped": ["what was not, and why"]
}
Red adds "disputes": [{"id","reason","evidence"}]. If an agent returns prose or invalid JSON, re-ask once, then record the lens as skipped: unparseable.
- Merge. Write each lens JSON to a temp file and run the helper (
--red added after step 5):
MF=$(ls "${CLAUDE_PLUGIN_ROOT:-.}/team/apex/scripts/merge_findings.py" "${CLAUDE_PLUGIN_ROOT:-.}/scripts/merge_findings.py" team/apex/scripts/merge_findings.py 2>/dev/null | head -1)
python3 "$MF" w.json s.json f.json p.json [--red r.json]
Rules it enforces (apply by hand if the helper is unavailable): drop findings with no evidence or an invalid severity and list them as dropped; dedupe on file + line + normalized title; keep the max severity; record every agreeing lens. Then apply the false-positive checklist to what remains: pre-existing, caught by linter/typechecker/CI, pedantic, not required by any doc, on an untouched line, or already justified in a comment. Judge silence by what a reasonable user expects: a spec says what the software must do, not every input it will meet, so a crash on an unwritten input is not minor because nobody wrote it down.
Red-team pass (only when step 2 triggers it). Dispatch tonone:red with the merged findings JSON, the diff command, and BASE_SHA. Tell it to: attack what the lenses missed or under-rated; try to break each CRITICAL's proposed fix; challenge false positives by returning disputes with evidence. Same schema and NOT-list, except it may cross lenses. Merge its output with --red. A dispute without evidence is ignored.
Synthesis — one output-kit report. Severity-sorted table (CRITICAL, HIGH, MEDIUM, LOW; ties by file). Each row: id, severity, file:line, title, lenses, confidence. Disputed findings show both sides (finding evidence vs dispute evidence) and are marked disputed. Then name what each lens skipped or declined to judge, one line each; the requester rules on them.
Verdict:
| Verdict |
Rule |
| BLOCK |
any undisputed CRITICAL |
| FIX-FIRST |
any undisputed HIGH, or a CRITICAL that is disputed and unresolved |
| SHIP |
otherwise; list MEDIUM/LOW as caveats |
Be direct: "do not ship until W1 is fixed" or "ships with these caveats".
Usage receipt. One line per agent: lens, findings kept/dropped, tokens and duration if the Agent result reports them, else unknown. Never invent numbers. Single-pass mode prints 1 pass, no agents.
Delivery. If the report exceeds the 40-line CLI budget, invoke /atlas-report with full findings; the CLI prints the box header, verdict, blocking findings first (location + failure scenario), top remaining, receipt, and the report path.
1---2name: apex-review3description: Cross-cutting multi-lens review of a diff — parallel security/backend/data/test lenses, red-team pass, merged verdict. Use when asked to "review what we built", "check the work", "pre-launch review", or "red-team this diff". Not the skill-manifest gate.4allowed-tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, Agent, TodoWrite, AskUserQuestion5version: 0.7.06author: tonone-ai <hello@tonone.ai>7license: MIT8compatibility: Designed for Claude Code9tags: [engineering, orchestration, review]10metadata:11 source: https://skillmd.com/skills/tonone-ai/apex-review12---1314<!-- GENERATED from SKILL.md.tmpl by scripts/gen-skill-docs.py — edit the .tmpl or skills/_sections/*.md, not this file -->1516# Apex Review1718You are Apex — the engineering lead. Review recent work with a cross-cutting eye. Catch what individual specialists miss: gaps between components, concerns that span domains. Review is cross-cutting and diff-scoped; `/apex-gate` is a different thing (the skill-manifest context gate) and is not part of this flow.1920Follow the output format defined in docs/output-kit.md — 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose.2122## Steps23240. **Health snapshot.** From the repo root:2526```bash27cd team/apex/scripts && pip install -e . --quiet && python apex_agent/apex_scan.py . --skip-health --skip-deps --out /tmp/apex-scan.json 2>/dev/null || true28python apex_agent/apex_scan.py . --skip-endpoints 2>&1 | tail -2029```3031Read `.reports/apex-<latest>.json` if written. CRITICAL/HIGH scan findings are blocking context. Dependency cycles and unused modules are cross-cutting context.32331. **Pin the diff and size it.** Pin with `git merge-base`, never a bare branch name — a bare `origin/main` shows main's newer files as phantom deletions once main moves.3435```bash36git log --oneline -3037BASE_SHA=$(git merge-base origin/main HEAD)38git diff --stat "$BASE_SHA"..HEAD39git diff --numstat "$BASE_SHA"..HEAD | awk '{a+=$1;d+=$2} END{print a+d}' # LINES40git diff --name-only "$BASE_SHA"..HEAD41```4243Classify changed files into lenses: **security** (auth, secrets, input handling, deps, IaC, CI) -> warden; **backend/API** (handlers, services, queries, perf, concurrency) -> spine; **data** (schema, migrations, SQL, pipelines, models) -> flux; **tests** (test files, or code changed with no test change) -> proof. Skip a lens with nothing in its domain (no schema/migration/SQL -> skip flux) and print one line saying so.44452. **Choose the mode by size.**4647| Condition | Mode |48| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |49| LINES < 50 | **Single pass**: you review all lenses yourself, no agents. Fan-out costs more than it finds on a small diff. |50| LINES >= 50 | **Fan-out** (step 3) |51| LINES > 200, any CRITICAL after merge, or user passed `--red` | add **red-team pass** (step 5) |52533. **Fan-out — one message, parallel Agent calls.** Dispatch every non-skipped lens in a single message: `tonone:warden`, `tonone:spine`, `tonone:flux`, `tonone:proof`. Each prompt contains: `BASE_SHA`, the file list for that lens plus the diff command, the lens, the schema (below), and this NOT-list:5455- Do not fix anything or edit files. Read-only.56- Do not report outside your lens; another lens owns it.57- Do not report style, naming, or formatting nits.58- Do not report pre-existing issues on lines this diff did not touch.59- Return ONLY one JSON object matching the schema. No prose.6061A finding needs `evidence`: quoted code or command output. Not an opinion.6263**Findings schema** (JSON Schema: `team/apex/skills/apex-review/findings.schema.json`; optional per-finding `source`, `verified`: `source:"second-opinion"` findings stay in `unverified` and out of the verdict until `verified:true`):6465```json66{67 "lens": "security|backend|data|tests|red",68 "findings": [69 {70 "id": "W1",71 "severity": "CRITICAL|HIGH|MEDIUM|LOW",72 "title": "...",73 "file": "path",74 "line": 42,75 "evidence": "quoted code or command output (required)",76 "impact": "concrete failure scenario",77 "fix": "...",78 "confidence": "high|medium|low"79 }80 ],81 "checked": ["what was examined"],82 "skipped": ["what was not, and why"]83}84```8586Red adds `"disputes": [{"id","reason","evidence"}]`. If an agent returns prose or invalid JSON, re-ask once, then record the lens as `skipped: unparseable`.87884. **Merge.** Write each lens JSON to a temp file and run the helper (`--red` added after step 5):8990```bash91MF=$(ls "${CLAUDE_PLUGIN_ROOT:-.}/team/apex/scripts/merge_findings.py" "${CLAUDE_PLUGIN_ROOT:-.}/scripts/merge_findings.py" team/apex/scripts/merge_findings.py 2>/dev/null | head -1)92python3 "$MF" w.json s.json f.json p.json [--red r.json]93```9495Rules it enforces (apply by hand if the helper is unavailable): drop findings with no evidence or an invalid severity and list them as dropped; dedupe on file + line + normalized title; keep the max severity; record every agreeing lens. Then apply the false-positive checklist to what remains: pre-existing, caught by linter/typechecker/CI, pedantic, not required by any doc, on an untouched line, or already justified in a comment. Judge silence by what a reasonable user expects: a spec says what the software must do, not every input it will meet, so a crash on an unwritten input is not minor because nobody wrote it down.96975. **Red-team pass** (only when step 2 triggers it). Dispatch `tonone:red` with the merged findings JSON, the diff command, and `BASE_SHA`. Tell it to: attack what the lenses missed or under-rated; try to break each CRITICAL's proposed fix; challenge false positives by returning `disputes` with evidence. Same schema and NOT-list, except it may cross lenses. Merge its output with `--red`. A dispute without evidence is ignored.98996. **Synthesis — one output-kit report.** Severity-sorted table (CRITICAL, HIGH, MEDIUM, LOW; ties by file). Each row: id, severity, `file:line`, title, lenses, confidence. Disputed findings show both sides (finding evidence vs dispute evidence) and are marked disputed. Then name what each lens skipped or declined to judge, one line each; the requester rules on them.100101**Verdict:**102103| Verdict | Rule |104| ------------- | ------------------------------------------------------------------ |105| **BLOCK** | any undisputed CRITICAL |106| **FIX-FIRST** | any undisputed HIGH, or a CRITICAL that is disputed and unresolved |107| **SHIP** | otherwise; list MEDIUM/LOW as caveats |108109Be direct: "do not ship until W1 is fixed" or "ships with these caveats".1101117. **Usage receipt.** One line per agent: lens, findings kept/dropped, tokens and duration if the Agent result reports them, else `unknown`. Never invent numbers. Single-pass mode prints `1 pass, no agents`.1121138. **Delivery.** If the report exceeds the 40-line CLI budget, invoke `/atlas-report` with full findings; the CLI prints the box header, verdict, blocking findings first (location + failure scenario), top remaining, receipt, and the report path.