Frontend-review Skill — the steering brain

You drive a front-end conventions review. The actual analysis lives in the frontend-review subagent (.claude/agents/frontend-review.md) — this skill decides what scope and how deep, spawns the agent (fanning out for 5+ files), collates findings into one severity-rated report, and then offers to comment them on the PR or fix the safe ones. Keep the analysis logic in the agent; keep orchestration here.

This is the front-end-conventions member of the code-cleaning family. It deliberately mirrors .claude/skills/a11y/SKILL.md (diff-scoped, 3-level severity, the same report format, an offer-to-fix step) and the red-team skill/agent split (depth ladder, spawn-and-collate) — just for Nuxt UI 4 / crouton component conventions instead of accessibility or bugs.

Why a separate skill (not folded into /review)

/review is a broad correctness/security/dead-code pass and only carries a handful of Nuxt UI bullets as honor-system reminders. This skill is the dedicated, diff-scoped, severity-rated, fixable, CI-gated front-end-conventions layer — it owns the full convention checklist, the v3→v4 rename autofix, and the per-PR gate. Exactly like /a11y and /red-team sit beside /review rather than inside it.

What it does not do: visual/layout taste ("this should be a card") — that's the human /ui-proposal sign-off; accessibility — that's /a11y; security — that's /red-team. Conventions only.

1. Resolve { depth, scope, comment, fix } from the request

Scope (mirrors the review skill's modes):

Invocation	What it reviews	scope passed to agent
/frontend-review	All uncommitted .vue changes (staged + unstaged)	"diff"
/frontend-review last N	.vue files in the last N commits	"diff" (vs HEAD~N)
/frontend-review --scope <pkg>	A whole package's .vue	packages/<pkg> (or apps/<pkg>)
/frontend-review --file <path>	A single .vue file	that path

Depth (mirrors red-team's ladder):

The user said…	depth
/frontend-review (bare), a PR/diff context, quick	quick (static, diff-scoped)
/frontend-review --scope <pkg> / standard	standard (full static sweep of the scope)
/frontend-review deep / "check against real Nuxt UI"	deep (static + cross-check the real @nuxt/ui component set)

Defaults: a bare /frontend-review on a working tree → quick + "diff". A --scope/--file with no depth → standard. Only go deep when explicitly asked.

Flags: --comment → post findings as inline PR comments. --fix → apply the safe remediations (v3→v4 renames, redundant-overlay-UCard unwraps) to the working tree. Both can combine with any scope/depth.

2. Severity map (reuse the review skill's 3 levels + format)

Level	Meaning	Sources
🔴 Critical	A hard, documented convention break — blocks the CI gate	v3 component name (UDropdown/UDivider/UToggle/UNotification); UCard inside UModal/USlideover/UDrawer; Options API in a .vue; overlay clearly missing the #content="{ close }" pattern
🟡 Warning	Likely off-convention; advisory	raw <button>/<input>/<select>/<textarea>/internal <a> where a Nuxt UI / crouton component applies; hand-rolled overlay markup; hardcoded brand/semantic color
🔵 Note	Polish	bare export default {} nit; one-off hardcoded color; minor drift

Same emoji + report format as /review and /a11y, so a mixed code-cleaning pass reads consistently.

3. Gather the scope

Uncommitted (/frontend-review, --scope, --file):

git diff --name-only --diff-filter=d | grep -E '\.vue$'          # unstaged
git diff --cached --name-only --diff-filter=d | grep -E '\.vue$' # staged

Recent commits (/frontend-review last N):

git diff --name-only HEAD~N..HEAD | grep -E '\.vue$'

If --scope is set, Glob packages/<pkg>/**/*.vue (or apps/<pkg>/**/*.vue). If the diff has no .vue files, say so and stop — this skill only reviews templates.

4. Spawn the subagent

Spawn frontend-review via the Agent tool with { scope, depth, fix } in the prompt.

• < 5 files → one subagent (or just do the static pass inline if it's a single small file — agent overhead isn't worth it for one --file).
• 5+ files → fan out: split the files into groups (by directory — components/, pages/, layouts/), spawn one frontend-review subagent per group with its file subset as scope, and launch them in parallel (multiple Agent calls in one message). Same parallelization rule as /review. The agents are synchronous — you hold their results when they return; never report "running in the background".

Pass fix through only when the user asked for --fix (so a plain review run never touches files).

5. Collate & report

Merge the agents' findings, de-dupe anything the same rule flagged twice, and print the review skill's report format:

## Frontend Review Summary

| Severity | Count |
|----------|-------|
| 🔴 Critical | X |
| 🟡 Warning | Y |
| 🔵 Note | Z |

### 🔴 Critical

#### [Short title]
**File:** `path/to/file.vue:42`
**Rule:** `v3-name` (or overlay-ucard / overlay-content-slot / options-api / raw-html / hardcoded-color)
**Issue:** [Which convention is broken — "uses the v3 `UDropdown`; v4 is `UDropdownMenu`"]
**Fix:** [The exact rename/component to use]

--- (repeat for 🟡 / 🔵)

If nothing found:

## Frontend Review: clean ✅
Reviewed N templates, no convention issues found.

Mark each finding confirmed (a deterministic signal backs it) vs suspected (a reasoned smell), mirroring red-team/a11y — don't present a reasoned raw-<button> call as a confirmed violation.

6. --comment — inline PR comments

When --comment is set and the work is on a PR, post each finding as an inline review comment on the offending file:line, dovetailing with the existing 🎯 Preview feedback / ♿ A11y machinery:

1. mcp__github__pull_request_read to resolve the PR for the current branch and its head SHA.
2. For each finding, mcp__github__add_comment_to_pending_review with the file path and line, body = the finding (lead with the 🔴/🟡/🔵 + rule, then Issue/Fix). Prefix the body with a 🧩 Frontend tag so it's distinguishable from 🎯 Preview feedback, ♿ A11y, and code-review comments.
3. mcp__github__pull_request_review_write to submit the pending review as COMMENT (never auto-REQUEST_CHANGES / APPROVE).

If there's no PR (local-only), skip inline comments and just print the report — say so rather than erroring.

7. --fix — apply safe remediations

When --fix is set, the agent applies (or you apply, for a small inline run) only the safe, deterministic rewrites — the same set the agent doc lists:

• v3 → v4 name rename (UDropdown→UDropdownMenu, UDivider→USeparator, UToggle→USwitch, UNotification→UToast) — checking props still map; report anything ambiguous instead of guessing.
• Redundant UCard inside an overlay (pure wrapper, no card props) → unwrap into the #content slot's <div class="p-6">.

Then pnpm typecheck the affected app(s)/package — never leave the tree red:

pnpm -r --filter './apps/*' typecheck   # or the specific package's typecheck

Anything needing real judgment (raw <button>→UButton behaviour, an Options→<script setup> migration, a color→token swap) is reported, not auto-fixed.

8. Offer to fix (when not already --fix)

After printing the report (and any --comments), close with the review skill's offer:

Want me to fix any of these? (all / critical only / pick by number)

If the user says "all" or "critical only", apply the safe remediations directly — no per-fix confirmation — then pnpm typecheck. Findings that aren't in the safe set get called out as "needs a human decision" with the reason (e.g. "raw <button>→UButton needs prop/slot judgment").

Relationship to the other entry points

• /review carries a few Nuxt UI v4 bullets as honor-system reminders; /frontend-review is the dedicated, diff-scoped, severity-rated, fixable layer that owns the full convention checklist + the v3→v4 autofix.
• It sits beside /a11y (accessibility), /ui-proposal (human design-look sign-off), /review (general code review), and /red-team (security) — same spawn-and-collate shape, different lens. Reach for /frontend-review when you specifically want "are we on Nuxt UI 4 / crouton components, correctly", with the option to comment or fix.
• CI runs the same engine automatically (mirroring the red-team/a11y workflows): .github/workflows/frontend-review.yml runs the subagent at depth=quick on a PR diff — posts a sticky <!-- frontend-review --> comment and fails the check on a 🔴 finding (diff-scoped, so never on the pre-existing backlog). /frontend-review is the on-demand brain and human entry point for the same machinery. The workflow MUST follow the Claude-action workflow standard in .claude/agents/CLAUDE.md — notably the --allowedTools grant, without which the gate fails open (#834/#1036).