AGENTS.md template

Copy# AGENTS.md - Design Consistency Standards
 
Copy this section into the project's existing `AGENTS.md`.
 
## Install Strongtie Components
 
Resolve component delivery before writing UI code:
 
- ✅ If `@strongtie/design-system` is installed, reuse package subpath imports.
- ⏭ If Simpson Azure Artifacts authentication is available, run `npm install @strongtie/design-system sonner` and follow https://design.strongtie.io/getting-started/installation.
- ⚠ If feed credentials are unavailable, configure the public registry and run `npx shadcn@latest add @strongtie/<component>`. Follow https://design.strongtie.io/getting-started/strongtie-registry.
- ❌ If neither path is configured, stop and report the missing installation precondition.
 
Rules:
 
- Import maintained primitives from `@strongtie/design-system/<component>`.
- Do not edit, patch, or copy package source from `node_modules`.
- Compose product behavior in application-owned feature components.
- Use `@/components/ui/*` only when the project explicitly uses the public registry path.
- Keep secrets out of the project `.npmrc`; store Azure credentials in `~/.npmrc`.
 
```tsx
import { Button } from "@strongtie/design-system/button"
import {
  Card,
  CardContent,
  CardHeader,
  CardTitle,
} from "@strongtie/design-system/card"
```
 
## React Compiler Optimization
 
This project uses React Compiler (`babel-plugin-react-compiler`).
 
Do not add `useMemo()`, `useCallback()`, or `React.memo()` without a measured need. Use standard hooks and `React.lazy()` for code splitting.
 
## State Management
 
Choose state by ownership:
 
1. Server data from an API → **TanStack Query**
2. Component-local UI state → **useState**
3. Session-level shared state → **React Context**
4. Complex computed or cross-component state → **Zustand**
 
Do not store API responses in `useState`, duplicate query cache in local state, or create Context for one component.
 
## Form Implementation
 
| Condition | Solution |
| --- | --- |
| 1-3 fields and no validation | `useState` |
| 4+ fields or validation rules | React Hook Form + Zod |
 
For a complex form:
 
1. Create the schema in `schemas/<feature>-schema.ts`.
2. Use `zodResolver` with React Hook Form.
3. Import `FormField`, `FormItem`, `FormControl`, and `FormMessage` from `@strongtie/design-system/form`.
4. Import controls such as `Input` and `Button` from their Strongtie package subpaths.
 
## TanStack Query
 
- Reuse the query-key factory in `hooks/query-keys.ts`.
- Create custom hooks for queries instead of calling `useQuery` in view components.
- Implement optimistic updates with rollback for suitable mutations.
- Render loading, error, and empty states.
 
## Error Handling
 
| Error type | Handler |
| --- | --- |
| React component crash | Error Boundary |
| Expected API error | Query error state and toast |
| Validation error | Form field message |
| Network error | Actionable toast |
 
Map API error codes to user-facing messages in `lib/error-messages.ts`. Never display a raw API error to a user.
 
## Accessibility
 
- Give every icon-only button an accessible name.
- Associate every form control with a visible label.
- Use meaningful alternative text, or `alt=""` for decorative media.
- Preserve keyboard access and visible focus states.
- Never use color as the only state indicator.
 
```tsx
<Button aria-label="Delete project" size="icon" variant="ghost">
  <Trash2 aria-hidden="true" className="size-4" />
</Button>
```
 
## Loading and Empty States
 
- Use Skeleton when the content layout is predictable.
- Use Spinner for action-triggered or blocking work.
- Always provide loading, error with retry, and empty with call-to-action states.
 
## Component Checklist
 
- [ ] Uses a named export
- [ ] Marks props `readonly`
- [ ] Defines subcomponents at module scope
- [ ] Handles loading, error, and empty states
- [ ] Gives icon buttons accessible names
- [ ] Associates form inputs with labels
- [ ] Uses Strongtie package primitives where applicable
- [ ] Does not edit or duplicate package source
- [ ] Uses `cn()` for conditional classes
- [ ] Uses `@/` aliases for application-owned modules
 
## Git Workflow
 
- Work on a `feature/*` or `hotfix/*` branch, never directly on `main`.
- Use lowercase, hyphenated branch descriptions.
- Write focused Conventional Commits.
- Run the project's typecheck, tests, lint, and build before requesting review.
 
## AI Agent Skills
 
Available Strongtie skills:
 
- `strongtie-component` - Component creation
- `strongtie-test` - Test generation
- `strongtie-docs` - Documentation
- `strongtie-react-practices` - React best practices
- `strongtie-style-consistency` - Linting and formatting