diff --git a/AGENTS.md b/AGENTS.md index c5cb9d0..a326d72 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -352,6 +352,24 @@ Actual function names: `bindProductionAuth`, `bindProductionBlog`, `bindProducti --- +### Cross-feature events and background jobs (Plan 10, ADR-015) + +Three rules: + +- **E0:** Events are for cross-feature decoupling. In-feature reactions are direct use-case calls — do not use the bus. +- **E1:** Event contracts are exported from the publisher's root; handlers are private to the consumer's bind-* files (never re-exported, ESLint-enforced). +- **J0:** Jobs are for *deferred* work, not abstraction. Synchronous code stays synchronous. + +`@repo/core-events` provides `IEventBus` (`InMemoryEventBus` for dev/test, `PayloadJobsEventBus` for prod). `@repo/core-shared/jobs` provides `IJobQueue` (`InMemoryJobQueue` / `PayloadJobQueue`). Both are swapped by `bindAll()` using the same `USE_DEV_SEED` / `NODE_ENV` rules as repositories. + +Per-feature folders (all optional): `events/.event.ts`, `events/handlers/on--.handler.ts`, `jobs/.job.ts`, `integrations/cms/jobs/.task.ts`. + +Use the generators: `pnpm turbo gen event {publish|consume}`, `pnpm turbo gen job`. They insert at six fixed `// ` anchor comments present in every feature. + +See `docs/guides/events-and-jobs.md` and `docs/decisions/adr-015-events-and-jobs.md`. + +--- + ## Instrumentation conventions **Symbols (in `core-shared/instrumentation/symbols.ts`):** @@ -446,6 +464,7 @@ Feature packages MUST NOT `import "@sentry/*"`. Allowlist: - **Dependency Flow** — `docs/architecture/dependency-flow.md` — allowed directions and composition pattern - **Scaffolding a Feature** — `docs/guides/scaffolding-a-feature.md` — `turbo gen feature` reference (fast path) - **Adding a Feature Guide** — `docs/guides/adding-a-feature.md` — step-by-step new feature walkthrough (manual path) +- **Events and Jobs Guide** — `docs/guides/events-and-jobs.md` — publish, consume, schedule background work - **Testing Strategy** — `docs/guides/testing-strategy.md` — test placement, Vitest per-package, Playwright e2e - **TDD Workflow** — `docs/guides/tdd-workflow.md` — red-green-refactor cycle, mocking decision tree, coverage targets