agentic-dev/packages/core/AGENTS.md

@repo/core — Clean Architecture Core

Business logic package. All use cases, entities, interfaces, and DI live here.

Layers (dependencies point inward only)

entities/          → NOTHING (innermost, zero deps)
application/       → entities/ only
interface-adapters/→ application/, entities/
infrastructure/    → application/, entities/, @repo/cms-client, external libs
di/                → all internal layers

Import Rules

Layer	Can import from	NEVER import from
entities/	NOTHING	Everything else
application/	entities/ only	infrastructure/, interface-adapters/
interface-adapters/	application/, entities/	infrastructure/
infrastructure/	application/, entities/, @repo/cms-client	interface-adapters/, apps/*
di/	All internal layers	apps/*

DI Resolution Table

Symbol	Interface	Production	Mock
IUsersRepository	IUsersRepository	PayloadUsersRepository (Plan 3)	MockUsersRepository
IArticlesRepository	IArticlesRepository	PayloadArticlesRepository (Plan 3)	MockArticlesRepository
IAuthenticationService	IAuthenticationService	BetterAuthService (future)	MockAuthenticationService
ITelemetryService	ITelemetryService	OTelSentryService (future)	MockTelemetryService

Naming Conventions

• Models: {name}.ts with Zod schema + type export
• Errors: {domain}.ts with Error subclasses
• Interfaces: {name}.repository.interface.ts or {name}.service.interface.ts
• Use cases: {verb}-{noun}.use-case.ts
• Controllers: {noun}.controller.ts
• Infra: {provider}-{name}.repository.ts or mock-{name}.repository.ts
• DI modules: {domain}.module.ts

Running Tests

cd packages/core && pnpm vitest run