Templates & playbooks

# AGENTS.md — Next.js 14 App Router

## Stack
- Next.js 14 (App Router), React 18, TypeScript
- Data: React Server Components + Server Actions

## Conventions
- "use client" only at the leaf that needs interactivity.
- Server Components are the default; never import server-only
  modules (fs, db) into a client component.
- Routes live under app/<feature>/page.tsx (route) or
  app/<feature>/layout.tsx (shared shell).

## Data fetching
- Fetch in Server Components with async/await.
- Mutate via Server Actions; keep forms progressively enhanced.

## Gotchas
- Do not import "@/lib/server" from a "use client" file.
- Environment keys: NEXT_PUBLIC_* are client-visible.

# CLAUDE.md — FastAPI service

## Stack
- Python 3.12, FastAPI, SQLAlchemy 2.0 (async), Pydantic v2

## Rules
- All DB access is async (asyncpg); never call blocking IO in a
  request handler without to_thread.
- Define request/response schemas as Pydantic models in api/schemas/.
- Share dependencies (auth, db session) via FastAPI Depends.

## Testing
- pytest + httpx.AsyncClient; tests under tests/ mirror app/ layout.
- Use the dependency_overrides registry to swap the DB for a fixture.

## Notes
- Run migrations with `alembic upgrade head`, never edit the DB directly.

# AGENTS.md — Rust CLI (clap)

## Layout
- src/main.rs: arg parsing + wiring only.
- src/commands/: one module per subcommand.
- src/lib.rs: pure logic, fully unit-tested.

## Error handling
- Define domain errors with thiserror.
- Propagate with anyhow in main; map to exit codes at the boundary.

## Build & release
- cargo build --release; binaries in target/release/.
- CI cross-compiles via cargo-zigbuild for linux/macos/windows.
- Version is sourced from Cargo.toml, not hard-coded.

// Cursor Rules — Go gRPC service

- Accept ctx context.Context as the FIRST argument of every
  exported function; never store it in a struct.
- protoc output (*.pb.go, *_grpc.pb.go) is generated; do NOT edit.
  Regenerate with `make proto` after changing .proto files.
- Packages: internal/ for unexported code, api/ for the gRPC
  surface, pkg/ only for truly reusable helpers.
- Errors: wrap with fmt.Errorf("...: %w", err); surface gRPC
  status codes via status.Errorf.
- Run `golangci-lint run` before every commit.

<!-- Copilot Instructions — React Native (Expo) -->

- Use Platform.select() for platform-specific behavior; keep the
  shared component the default and branch only when necessary.
- Native modules live under /modules; never import 'react-native'
  internals directly.
- Styling: StyleSheet.create with design tokens from theme.ts.
  Do not use inline pixel values outside the token system.
- Navigation: React Navigation v7; screen params are typed.
- Avoid nativewind/tailwind mixing with StyleSheet in the same file.

# AGENTS.md — Turborepo monorepo (pnpm)

## Packages
- apps/web: Next.js consumer app.
- packages/ui: shared React components (no business logic).
- packages/core: framework-agnostic domain logic.

## Rules
- Import shared code via workspace protocol: "@repo/ui".
- Never reach into another package's src/ directly.
- Run tasks through turbo: `pnpm turbo build --filter=web`.

## Pipelines
- build dependsOn ^build; test/test dependOn build.
- Cache is content-addressed; don't disable it for CI speed wins.

# AGENTS.md — Java Spring Boot service

## Stack
- Java 21, Spring Boot 3.2, Maven, JPA/Hibernate, PostgreSQL

## Package layout
- controller/: HTTP adapters, request/response DTOs only.
- service/: business logic; never expose repositories here.
- domain/: entities, value objects, and repository interfaces.
- infrastructure/: JPA implementations, config, and clients.

## Rules
- Use constructor injection; avoid field injection.
- Return ResponseEntity<T> from controllers; keep HTTP concerns out of services.
- Use Bean Validation on DTOs, never on entities.
- Run tests with `./mvnw test`; integration tests end in *IT.java.

// Cursor Rules — Vanilla HTML/CSS/JS

- Prefer semantic HTML over div soup; use <template> for repeated
  markup.
- CSS lives next to its component (component.css) or in a shared
  styles/ folder. No inline styles.
- JS is modular: one file per component, imported as ES modules.
- Select elements with data-* attributes, not CSS classes meant
  for styling.
- Keep DOM reads/writes batched; never read layout inside a loop.
- Accessibility: every interactive element must be focusable and
  have an aria-label when the label isn't visible.

# AGENTS.md — Node.js + Express backend

## Stack
- Node.js 20 LTS, Express 4, esm module system

## Structure
- routes/: route definitions only, no business logic.
- controllers/: thin HTTP layer that calls services.
- services/: pure async business logic, fully unit-tested.
- middleware/: reusable Express middleware (auth, validation, errors).

## Rules
- Always pass errors to next(err); never swallow async errors.
- Validate request bodies with zod or joi before controllers.
- Environment config lives in config/ and is read once at startup.
- Use npm scripts (start, test, lint); pin Node version in .nvmrc.

# CLAUDE.md — PHP web application

## Stack
- PHP 8.3, Composer (PSR-4), Apache/nginx, MariaDB, PDO

## Layout
- public/: entry point (index.php) and static assets only.
- src/: application code (Controllers, Services, Models).
- config/: environment and service configuration.
- templates/: view templates; escape every output with htmlspecialchars.

## Rules
- Use Composer autoloading; no manual requires.
- All database access goes through PDO with prepared statements.
- Never commit vendor/ or .env; keep secrets outside document root.
- Routing is centralized in public/index.php or a dedicated router.

# AGENTS.md — Markdown documentation repo

## Flavor
- GitHub Flavored Markdown with YAML frontmatter.
- frontmatter keys: title, description, order, tags, status.

## File layout
- docs/: user-facing guides organized by product area.
- api/: OpenAPI-generated reference (do not edit by hand).
- assets/: images and diagrams referenced with relative paths.

## Rules
- One sentence per line for easier diff reviews.
- Use semantic line breaks; no hard wraps in the middle of a sentence.
- Status values are: draft | review | published | deprecated.
- Images must include alt text and be under 500 KB.

// Cursor Rules — TypeScript project

- Enable strict, noImplicitAny, exactOptionalPropertyTypes and
  noUncheckedIndexedAccess in tsconfig.json.
- Prefer interfaces for object shapes; use type for unions and
  mapped types.
- Export public APIs with explicit return types so tsc errors
  surface where consumers see them.
- Avoid `any`; use `unknown` with runtime validation at system
  boundaries.
- Keep types co-located with the code they describe; shared types
  live in src/types.ts with a barrel export.
- Run `tsc --noEmit` and the test suite before every PR.

# CLAUDE.md — PHP CLI tool

## Stack
- PHP 8.3 CLI, Symfony Console 7, Composer, PSR-4 autoloading

## Layout
- bin/: executable entry script (e.g., bin/myapp).
- src/Command/: one Symfony Console command per class.
- src/Service/: reusable business logic with no CLI coupling.

## Rules
- Return proper exit codes: 0 success, 1 general error, 2 usage
  error; avoid arbitrary magic numbers.
- Read stdin with stream_get_contents(STDIN); never assume argv
  is the only input source.
- Output must be testable: inject a SymfonyStyle or OutputInterface.
- Register the command class in bin/myapp and add it to composer.json
  bin array.