Skip to main content

next-frontend-quality-loop

Why It Exists​

.omc/plans/quality-loop-skills.md (local research artifact, not tracked in this repo) records the actual origin: this skill is not a from-scratch design, it's a genericization of arcos-web's Angular/.NET quality-loop-frontend/quality-loop-backend pair toward this repo's Next.js/React/Hono/kubb/Supabase stack. The plan is explicit that this had to be additive — a separately-named skill that leaves the existing global frontend-quality-loop (which already auto-detects Next/React/Angular from package.json) untouched, rather than forking or replacing it.

The plan drafted this skill under the name frontend-quality-loop-next; the introducing commit (b56785a, git log --follow -- skills/next-frontend-quality-loop) shipped it as next-frontend-quality-loop instead. That rename tracks a real design reversal, not just cosmetics: the plan's "Decision 2" left an open question for its own follow-up — mirror the existing global skill's always-loop-and-fix default, or keep arcos-web's original read-only-by-default shape with an explicit --fix flag. SKILL.md's own text resolves that question in favor of the cautious option, and states why: "on a stack with generated code (Kubb hooks), snapshot-based env plumbing, and convention-bound Playwright specs, an unattended fix pass is more likely to fight the generator than help. Look first; edit on request."

The plan's "Decision 3" — reuse, don't duplicate — is the other load-bearing choice visible in the shipped skill. Every lens that maps onto another next-starters skill's already-documented rules is written as a citation back to that skill instead of a re-derived checklist: contract defers to kubb-react-query invariant 8, env defers to runtime-env-config invariants 1/3/4, playwright-conventions defers to the four playwright-* skills, and ai-slop defers entirely to ai-slop-cleaner. The plan names the risk this creates directly — a hard dependency on six other skills being installed — and the mitigation baked into SKILL.md: log SKIPPED — <dependency> not detected rather than failing when one isn't present.

What It Does​

next-frontend-quality-loop reads package.json (plus tsconfig.json, next.config.*, tailwind.config.*, and any kubb.config.ts) to detect which of this stack's signals are present, then runs the applicable lenses concurrently over the target: the eight general lenses shared with the base skill's philosophy (a11y, perf, types, patterns, state, styling, tables, e2e) plus four stack-specific ones (contract, env, playwright-conventions, ai-slop). Each lens loads the portable skill that actually owns its rules instead of restating them inline.

By default it only reports — a severity-ranked, deduped findings table scoped to the git diff against trunk, zero edits. --fix opts into a bounded auto-fix loop that applies fixes for CRITICAL/HIGH findings, re-grades, and exits after two consecutive clean rounds (or max_rounds, whichever comes first); --critic layers an independent reviewer pass over whatever --fix applied, and is a no-op without --fix since a report-only run produces no diff to review.

How To Use It​

Triggers on grading frontend code in the Next.js/React/TypeScript family this repo's starters ship — App Router apps, a Kubb-generated React Query data layer, the runtime @cogs/config env layer, Supabase, and the four Playwright testid/attribute conventions. It only fires when package.json shows next or react plus at least one of @cogs/config, a kubb.config.ts, or @supabase/supabase-js — otherwise it hands off to the general-purpose frontend-quality-loop skill instead of grading a stack it has no lenses for.

skills add git@github.com:catesandrew/next-starters.git --skill skills/next-frontend-quality-loop -g
npm install @next-starters/skill-next-frontend-quality-loop
/plugin marketplace add catesandrew/next-starters
/plugin install next-frontend-quality-loop@next-starters

Gotchas & Invariants​

  • Report-only is the default. --fix is opt-in and only ever applies to CRITICAL/HIGH findings — medium severity is reported and left alone, because chasing every low-severity note to zero is how a fix loop never terminates.
  • Exit condition for --fix is "0 CRITICAL/HIGH for two consecutive rounds," not "0 total findings." Stop at max_rounds even if not clean, and report the remainder honestly.
  • --critic without --fix is a documented no-op: report mode produces no diff, so there's nothing for an independent reviewer pass to look at.
  • A fix that regresses typecheck or tests gets reverted and downgraded to a reported finding immediately — the loop never retries a fix that just broke something.
  • The playwright-conventions lens only fires when spec/page-object files are in scope, and it defers to all four sibling conventions rather than re-deriving any of them: playwright-testid-catalog (the id registry and mirror), playwright-testid-attributes (which attributes a component must expose, and from which render-driving variable), playwright-attribute-waits (the shared readiness helper and epoch fencing), and playwright-page-objects (selector priority, verify* methods, one file per route). It does add one rule of its own that none of the four owns — raw process.env reads inside a spec — asserted locally rather than cited.
  • contract, env, and ai-slop lenses only run when their stack flag is detected (kubb-react-query, runtime-env-config, and "UI files in scope," respectively) — running contract with no kubb.config.ts on disk produces confident nonsense, per SKILL.md's own "Common Mistakes" list.
  • Diff-scoping intersects the trunk diff with the target path and adds untracked files back in, since a fresh file has no diff against trunk and would otherwise be silently skipped. An empty resulting diff stops the run immediately rather than widening to the whole tree.
  • next-backend-quality-loop — the backend-side sibling grader, covering the Hono/Drizzle/Zod/kubb/Supabase API stack instead of the frontend.

Sourced from: skills/next-frontend-quality-loop/metadata.json, skills/next-frontend-quality-loop/SKILL.md, .omc/plans/quality-loop-skills.md (local research artifact, not tracked in this repo), git log --follow -- skills/next-frontend-quality-loop (commit b56785a)