miles-mechanical-web

Design-token and theming conventions for the Starter — semantic CSS variables in theme.css, Tailwind v4 @theme registration in globals.css, dark mode, and the Figma token-sync flow. Use when extracting repeated design values, adding/editing tokens, theming, or syncing tokens from Figma.

API service layer with ky/apiClient and Next.js API routes with Zod validation. Use when creating services, API endpoints, or HTTP calls.

Project file organization, naming conventions, and import patterns. Use when creating new files, organizing code, or deciding where to place modules.

Conventions when no auth provider is bundled. Use when adding authentication or guarding routes.

React component patterns — server vs client components, styling with cn(), props interfaces. Use when creating UI or shared components.

Use before writing or referencing any stack library — fetches version-accurate docs via the context7 MCP server so call signatures, hooks, and APIs match what is installed. Invoke on first usage of any non-none slot library, on any non-trivial Next.js API, or when uncertain whether an API is current.

TanStack Query patterns for data fetching — useQuery, useMutation, query keys, cache invalidation. Use when fetching server data or creating data hooks.

Error boundary usage, API error toast patterns, and error propagation. Use when implementing error states, handling API failures, or wrapping components with error boundaries.

Form patterns with React Hook Form + Zod validation + zodResolver. Use when building forms with validation.

next-intl i18n conventions for the Starter — locale routing, message catalogs, typed translation helpers, locale-switcher, and proxy locale detection. Use when adding or translating pages, adding message keys, or touching anything under src/i18n.

Package migration guide — swap procedures for HTTP client, state management, data fetching, URL state, and forms. Use when evaluating or replacing a core package. Currently selected packages are recorded in docs/PACKAGES.md.

Next.js 16 proxy (middleware) patterns — route protection, auth checks, redirects. Use when implementing request interception or route guards.

Next.js App Router patterns — route groups, layouts, metadata, and loading/error route files. Use when creating route structure and page-level routing artifacts.

Use when reviewing route handlers, server actions, middleware, auth flows, file uploads, redirects, or any code that crosses a user-input trust boundary — walks OWASP Top 10 for this specific stack.

AI SEO + GEO for the Starter — config-driven metadata, canonical/hreflang, JSON-LD, robots/sitemap/llms.txt, and the AI-crawler policy. Use when adding pages, registering public routes, or touching anything under src/app, src/lib/seo, or the SEO config.

Use when adding a new skill to this project, editing an existing skill, or extracting reusable patterns from AGENTS.md into a dedicated skill file.

Use when a new skill is added or an existing skill behaves incorrectly — turns a skill into behaviour-verifying scenarios via a structured interview protocol.

Use after editing a skill or when asked to test a skill — executes scenarios from skill-test-designer against the current agent context and reports pass/fail.

State management decision tree — Zustand for client UI, nuqs for URL state, useState for local. Use when managing client-side state.

Vitest + Testing Library patterns for unit tests, Playwright for integration/e2e tests. Use when writing tests or adding test coverage.

Schema definition, parsing, and inference patterns using Zod.