qiming/qiming-xagi-frontend-templates/packages/react-vite/AGENTS.md

React Vite Template — Agent Contract

Goal

Use this template with deterministic rules so AI agents can deliver features quickly with minimal guessing.

Command Contract

Use pnpm only.

pnpm dev         # Start dev server
pnpm build       # Build production assets
pnpm type-check  # TypeScript check (tsc --noEmit)
pnpm lint        # ESLint
pnpm check       # Required gate: type-check + lint

Task Entry (always follow)

1. Confirm target template and feature goal in one sentence.
2. Locate the matching module area (pages, components, lib, router).
3. Reuse existing patterns from src/examples and src/components/ui.
4. Implement with framework-native style (React function components + hooks).
5. Run pnpm check before finalizing.

Isomorphic Structure Mapping

Use these module locations in this React template:

Concern	React location
Route pages	src/pages/*.tsx
Shared components	src/components/**
API client	src/lib/api.ts
Service helpers	src/lib/services.ts
Utilities	src/lib/utils.ts
Router registry	src/router/index.tsx
Examples entry page	src/pages/ExamplesPage.tsx
Examples route	/#/examples

Minimal Delivery Paths

New page (5 steps)

1. Create src/pages/<FeatureName>.tsx.
2. Add route in src/router/index.tsx with path + element.
3. Use existing UI primitives from src/components/ui.
4. If data is required, call service functions via src/lib/services.ts.
5. Run pnpm check.

New component (4 steps)

1. Create component under src/components/ (or src/components/ui/ for primitives).
2. Type all props and callbacks explicitly.
3. Keep styling Tailwind-first and merge classes via cn when needed.
4. Run pnpm check.

New API flow (4 steps)

1. Define/extend endpoint calls in src/lib/api.ts or service module.
2. Add typed service wrapper in src/lib/services.ts.
3. Consume via page/component using useApi style pattern.
4. Run pnpm check.

Allowed Changes

• src/pages/**, src/components/**, src/lib/**, src/router/**
• Template docs (AGENTS.md, README.md)
• Template-local config required for feature delivery

Forbidden Changes

• Do not copy src/examples/* into production files verbatim.
• Do not change package manager (pnpm is mandatory).
• Do not add parallel agent rule docs (this file is the single source).
• Do not introduce framework-mixed patterns (keep React idioms only).

Pre-submit Checklist

1. pnpm check passes in this template.
2. If template metadata/version changed, validate related metadata files before release.
3. New route/page/API follows the mapping table and naming conventions.
4. src/examples remains reference-only.