git:20260730.da338fd to git:20260803.4dcf273

---

name: next-react-workbench

description: Router--Next + React. Picks implement + verify skills. Triggers--routes, shell, server/client, forms, loading, theme, UI polish.

---

# Next React Workbench

Use this as the specialist entry point for real Next.js and React app work.

This skill narrows the broad web/UI stack into a repeatable chain for:

- Next.js App Router work

- React component refactors

- route and app-shell UI improvements

- forms, async states, auth surfaces, and loading/error flows

- final browser verification after implementation

Primary downstream skills to leverage through the skill chain:

- `$vercel:nextjs`

- `$vercel:react-best-practices`

- `$build-web-apps:frontend-app-builder`

- `$vercel:agent-browser`

- `$dogfood`

- `$playwright-interactive`

- `$browser-workbench`

## Read These References As Needed

- [references/routing-matrix.md](references/routing-matrix.md)

- [references/next-app-router.md](references/next-app-router.md)

- [references/react-surface-refactors.md](references/react-surface-refactors.md)

Use the helper scripts when routing is unclear:

- `scripts/detect-next-surface.py`

- `scripts/print-next-workbench-prompts.py`

## First Step

Before choosing a path:

1. Confirm the repo has a Next/React web surface.

2. Detect whether the task is implementation, refactor, or verification-heavy.

3. Detect whether the surface is route-level, component-level, or shared app-shell.

4. Route to the smallest chain that can finish the work.

## Routing Rules

### Path: Route or App-Shell Work

Use this chain when the task touches a page, layout, shell, navigation, settings surface, dashboard surface, or route-specific form:

- `$vercel:nextjs`

- `$vercel:react-best-practices`

- `$vercel:agent-browser`

- `$playwright-interactive`

- `$browser-workbench`

#### Core Plugins

- `$vercel` and `$build-web-apps` plugins, `$sentry` where relevant.

Add `$build-web-apps:frontend-app-builder` first if the user wants visual uplift, stronger hierarchy, or better aesthetics.

State `Path: next-route`.

### Path: React Surface Refactor

Use this chain when the task is mostly component architecture, prop cleanup, state flow cleanup, or composition quality:

- `$vercel:react-best-practices`

- `$browser-workbench` if the result needs runtime verification

State `Path: react-surface`.

### Path: UI Polish

Use this chain when the task is mostly presentation, theming, spacing, hierarchy, visual coherence, or interaction polish:

- `$build-web-apps:frontend-app-builder`

- `$vercel:nextjs`

- `$browser-workbench`

State `Path: ui-polish`.

### Path: Post-Change Audit

After meaningful React changes, run `react-doctor` when practical.

State `Path: react-doctor`.

- Next App Router web runtime under `apps/web`

- shadcn local component source under `apps/web/components.json`

- Clerk auth in the web app

In other repos, generalize from those patterns rather than assuming the same paths exist.

## Anti-Patterns

- Do not start with low-level browser skills when the task is mostly implementation or refactor planning.

- Do not duplicate browser setup or auth bootstrap here; route setup to `browser-workbench-setup`.

- Do not treat every React task as a design task; only pull in `frontend-design` when visual quality is actually central.

- Do not use this skill for Expo/mobile runtime work.

## Prompting Guidance

- `Use $next-react-workbench to fix this Next route, improve the loading and error states, and verify the result in the browser.`

- `Use $next-react-workbench to refactor this React surface for cleaner composition and better runtime behavior.`

- `Use $next-react-workbench to polish this page's hierarchy, spacing, theme, and interaction quality, then run browser verification.`