| name | gateway-frontend |
| description | Routes frontend TanStack/React tasks to the right skills, invariants, and reviewer. Use when modifying frontend/src/** or shared schemas backing a frontend feature. Returns the skill list to load, repo invariants to enforce, mandatory tools, and the required reviewer follow-up. |
| version | 1.0.0 |
Frontend Gateway
This skill is the portable contract for any frontend code change in this repo. Both Claude Code and other LLM tools should consume it identically.
When to use
Invoke this gateway whenever a task touches:
frontend/src/** — TanStack Router routes, React components, hooks, data fetchers, integrations, lib utilitiespackages/shared/** — DTOs, branded IDs, enums backing a frontend-only feature
Do NOT invoke for: pure backend tasks, doc-only changes, or non-source-tree edits.
Required skills (load by intent)
Pick the subset that matches the task. Loading skills you do not need wastes attention.
| Intent | Skills to load |
|---|
| New route, route loader, search params, navigation | tanstack-router-best-practices, tanstack-start-best-practices |
| Server functions, SSR, middleware, deployment | tanstack-start-best-practices |
| Data fetching, mutations, cache invalidation, server state | tanstack-query-best-practices |
| New UI component, form, dialog, table, toast | shadcn-ui |
| Theme tokens, responsive layout, design system primitives | tailwind-design-system |
When in doubt, prefer loading less. Read the skill's references/ directory only on demand.
Invariants (cite when the model asks "why")
These come from CLAUDE.md and the existing frontend codebase. Treat as hard constraints.
- Shared DTOs in
packages/shared/. Never duplicate a backend DTO inside frontend/src/. Import the shared schema and derive types via Schema.Type<typeof Foo>.
- TanStack Router file-based routing. Routes live under
frontend/src/routes/. Do not register routes manually. Re-run codegen after adding/renaming routes; do not hand-edit routeTree.gen.ts.
- TanStack Query for server state, React state for UI state. Do not mirror server data into
useState. Cache invalidation is the source of truth.
- shadcn/ui primitives over hand-rolled components. When a shadcn component covers the use case (Button, Dialog, Form, Table, etc.), use it. Customize via Tailwind classes, not via copy-paste forks.
- Tailwind v4 utility-first. No new CSS files for component styling. Design tokens go through the existing
styles.css configuration.
- No business logic in components. Components render. Hooks orchestrate.
data/ and integrations/ own API calls. Keep components testable by isolating side effects.
Mandatory tools
- Serena for symbol-level reads and edits. Use
find_symbol, replace_symbol_body, insert_after_symbol, find_referencing_symbols. Avoid full-file reads.
- GitNexus:
- Run
gitnexus_impact({target: "<symbol>", direction: "upstream"}) BEFORE modifying any exported component, hook, or function. Report the blast radius if HIGH or CRITICAL.
- Run
gitnexus_detect_changes() BEFORE declaring the task complete. Verify the change scope matches expectations.
- RTK for shell commands (auto-rewritten by the require-rtk hook).
Required follow-up
After implementation completes:
- The orchestrator MUST spawn the
frontend-reviewer agent (see .claude/agents/frontend-reviewer.md).
- The reviewer returns
VERDICT: PASS | FAIL | SKIP and writes its verdict to .data/feedback-loop.json under domain_status.frontend.reviewer_status.
- On
FAIL, fix every listed issue and re-spawn the reviewer. Do not declare the task done with a non-PASS verdict.
- The Stop hook (
feedback-loop-stop.sh) will refuse to end the session until both reviewer_status and tests_status are PASS for frontend.
Domain boundary
packages/shared/** edits initiated for a frontend feature are owned by this gateway and reviewed by frontend-reviewer. When a backend feature initiates a shared-package edit, the backend gateway owns it instead — the orchestrator decides which gateway to invoke based on the originating task, not the file path. For changes that genuinely require both lanes (e.g., adding a field that exposes through API and renders in the UI), invoke both gateways and dispatch both developer agents serially.
