Template

Files

Danijel Martinek ef2b8e300e docs(plan-9): doc-pass slice 1 — CLAUDE.md, core-shared AGENTS, architecture, plan-8 annotations

First slice of the combined Plan 8 + Plan 9 doc-update pass:
- CLAUDE.md Key Conventions: append schema-in-use-case, presenter,
  controller unknown input, feature-scoped tRPC error mapping, public
  surface split (./ui)
- packages/core-shared/AGENTS.md: document defineErrorMiddleware export
  + t re-export from trpc/init
- docs/superpowers/plans/2026-05-05-plan-8-*.md and matching spec:
  one-line note that some controller/router patterns shifted in Plan 9;
  link to the Plan 9 refactor log
- docs/architecture/overview.md: data-flow box now shows xProcedure +
  xInputSchema + xOutputSchema.parse + presenter + middleware lanes;
  three explanatory paragraphs added (schemas, presenter, error mapping)
- docs/architecture/dependency-flow.md: app-side ./ui subpath note,
  allowed/disallowed examples updated for Plan 9 paths

Remaining doc-pass items (root AGENTS.md, per-feature AGENTS.md ×5,
core-testing AGENTS.md, adding-a-feature.md, tdd-workflow.md,
testing-strategy.md, vertical-feature-spec.md) follow in subsequent
commits — to be dispatched in parallel.

2026-05-06 16:43:13 +02:00

2.0 KiB

Raw Blame History

AGENTS.md — core-shared

Generic, reusable primitives with zero business knowledge. This package is the foundation for all other packages and exports utilities, Payload field/hook definitions, and tRPC initialization.

Responsibilities

Generic primitives — environment helpers, date utilities, type guards
Payload utilities — field definitions (slug, SEO), blocks (CTA), access controls (is-admin), hooks (slugify, publish timestamp)
tRPC platform — initTRPC.create(), shared context factory, procedure builders
No business domain knowledge — no awareness of articles, users, media, or any feature

Must NOT import

Any feature package (@repo/auth, @repo/blog, etc.)
Any app package
Framework-specific code (Next.js, TanStack React Query)

Public exports

From package.json:

. — all utilities, Payload exports, tRPC init
./payload — Payload field/hook/block utilities only
./trpc/init — tRPC initTRPC instance + builders. Plan 9: also exports t (the raw initTRPC.create({...}) instance) so feature packages can build their own procedures via t.procedure.use(...)
./trpc/context — tRPC context factory only
./trpc/define-error-middleware — Plan 9: factory that builds a tRPC middleware translating domain errors to TRPCError. Takes ReadonlyArray<readonly [ErrorCtor, TRPC_ERROR_CODE_KEY]> tuples; uses instanceof discrimination; preserves the original error as .cause. Owned by features: each feature passes its own constructors in via integrations/api/procedures.ts. core-shared never enumerates feature-specific error classes — this stays boundary-clean

Test conventions

Tests colocated: src/lib/slug-field.ts → src/lib/slug-field.test.ts
Vitest environment: node
Alias: @/ resolves to src/
Run: pnpm test --filter @repo/core-shared

Covered areas:

Slug field generation + validation
Payload hooks (publish-at timestamp, slugify-if-missing)
Access control helpers

2.0 KiB Raw Blame History