agentic-dev/AGENTS.md

Agent Instructions

Monorepo Package Map

Package	Purpose
@repo/core	Clean architecture: entities, use cases, interfaces, DI
@repo/api	tRPC router definitions (calls core controllers)
@repo/api-client	Shared React Query hooks + ApiProvider
@repo/cms-core	Payload CMS config, collections, hooks, globals
@repo/cms-client	Dual-mode Payload client (local + HTTP)
@repo/ui	shadcn/ui + Atomic Design component library
@repo/eslint-config	Shared ESLint flat configs
@repo/typescript-config	Shared TypeScript configs

App	Purpose
apps/web-next	Next.js 15 reference app
apps/web-tanstack	TanStack Start reference app
apps/cms	Thin Next.js shell for Payload admin
apps/storybook	Centralized Storybook instance

Dependency Flow (one direction only)

apps/web-next, apps/web-tanstack → @repo/api-client → @repo/api → @repo/core
apps/cms → @repo/cms-core → @repo/core/application (hooks only)
@repo/core/infrastructure → @repo/cms-client (standalone)
@repo/ui (standalone)

HARD RULES — NEVER VIOLATE

• NEVER: packages/core → apps/*
• NEVER: apps/cms → packages/core/infrastructure
• NEVER: packages/cms-client → apps/cms or packages/core or packages/cms-core
• NEVER: packages/cms-core → packages/cms-client
• NEVER: core/entities → anything
• NEVER: core/application → core/infrastructure

How to Add a New Feature (end-to-end)

1. Define entity in packages/core/src/entities/models/
2. Define repository interface in packages/core/src/application/repositories/
3. Write use case in packages/core/src/application/use-cases/{domain}/
4. Write controller in packages/core/src/interface-adapters/controllers/{domain}/
5. Write infrastructure implementation in packages/core/src/infrastructure/
6. Register in DI container (packages/core/src/di/)
7. Add tRPC router in packages/api/src/router/
8. Add React Query hook in packages/api-client/src/hooks/
9. If CMS collection needed: add to packages/cms-core/src/collections/
10. Build UI component in packages/ui/src/ (classify atomic level)
11. Write Storybook story (co-located .stories.tsx)
12. Write tests (unit in packages/core/tests/, E2E in tests/e2e/)

How to Add a New UI Component

1. Classify: atom (single element), molecule (2-3 atoms), organism (complex section), template (layout)
2. Create folder: packages/ui/src/{level}/{component-name}/
3. Create: {name}.tsx, {name}.stories.tsx, index.ts
4. Story title: "{Level}/{ComponentName}" (e.g., "Atoms/Button")
5. Export from level's index.ts barrel file
6. Import rules: atoms ← nothing | molecules ← atoms | organisms ← atoms+molecules | templates ← all

How to Add a Payload CMS Collection

1. Create folder: packages/cms-core/src/collections/{name}/
2. Create: index.ts (CollectionConfig), fields.ts, optionally hooks/, access/
3. Import in packages/cms-core/src/payload.config.ts collections array
4. Export from packages/cms-core/src/index.ts
5. Hooks that contain business logic must delegate to use cases in @repo/core/application