Skip to content

AGENTS.md

Latest commit

 

History

History
30 lines (28 loc) · 5.67 KB

AGENTS.md

File metadata and controls

30 lines (28 loc) · 5.67 KB
Raw
  • Workspace tasks MUST use package.json scripts; add a script when a missing workflow is repeatable like the existing commands, not ad hoc commands.
  • CI package path filters, matrix package ids, and root scripts test:* in .github/workflows/ci.yml and root package.json MUST stay synchronized when a workspace package is added, renamed, or moved; the store filter sync rule lives in packages/trueforge-core/src/agent-session/store/AGENTS.md.
  • Release wiring MUST keep dist-free host development, pnpm smoke, and packed CJS/ESM consumers of @truefoundry/trueforge-core and @truefoundry/trueforge-sdk working without changes. Workspace loaders opt into SDK/core src/ via the trueforge-dev export condition (never "development"); the SDK's trueforge-dev branch MUST keep types on its generated .d.ts (emitted by root sdk:types) because generated source is not exactOptionalPropertyTypes-clean.
  • PRs that change published-package code (packages/trueforge-core, packages/trueforge, packages/trueforge-ui, packages/trueforge-sdk) or packages/frontend (ships inside @truefoundry/trueforge) MUST include a new .changeset/*.md file (pnpm changeset). Docs, CI/workflows, charts, and docker-compose changes do not. SDK regeneration already adds @truefoundry/trueforge-sdk via pnpm changeset:sdk-regen.
  • Shared Postgres/Redis settings in docker-compose.yml and docker-compose.dev.yml (image versions, health checks, env_file) MUST stay synchronized; intentional differences (app services, data paths, project name, host ports, in-network POSTGRES_HOST / REDIS_URL) MUST stay explicit. packages/trueforge/.env is the host-dev + secrets source; docker-compose.yml may read it but MUST override container connectivity so host-dev localhost values are not used inside the smoke-test stack.
  • Changes to types or schemas MUST keep packages/trueforge-core, packages/frontend, packages/trueforge, and patches synchronized; they MUST NOT update only one affected layer.
  • TypeScript code MUST NOT use assertion escapes such as as T, as unknown as T, non-null !, or as never to silence type errors; implementations MUST use sound contracts, guards, or corrected types.
  • When catching an error and throwing another, the new error MUST set { cause: caught } so the original failure is preserved for logs and debugging.
  • Every type, schema, helper, and contract MUST have one canonical owner; code MUST NOT introduce duplicate definitions or forwarding shims that hide ownership.
  • AgentUIServer / server-port types (AgentChatServer, AgentBuilderServer, catalog ports, session/turn DTOs, stream events) MUST be defined only in @truefoundry/assistant-ui-runtime (src/server/types.ts / events.ts). @truefoundry/trueforge-ui MUST re-export them from src/server/types.ts (pass-through aliases only) and MUST NOT add hand-written parallel definitions of those ports/DTOs.
  • Runtime types backed by Zod schemas MUST be derived with named z.infer<typeof Schema> aliases; code MUST NOT duplicate those schemas as hand-written interfaces or indirect utility-type chains.
  • Modules MUST use static import and import type; they MUST NOT use require(), require.resolve(), or lint suppressions to bypass import checks.
  • A change that makes code unused MUST remove that dead code in the same change; it MUST NOT leave stale exports, files, documentation, duplicates, or “just in case” shims.
  • Every nested AGENTS.md MUST have a sibling CLAUDE.md containing only @AGENTS.md, so Cursor and Claude Code load the same scoped rules.
  • OpenAPI specs under .github/fern/openapi/openapi.json and docs/openapi.json are autogenerated in CI and MUST NOT be edited manually (both copies MUST stay identical)
  • Code under packages/trueforge-sdk and python/trueforge_sdk is autogenerated in CI and MUST NOT be edited manually
  • Tests MUST live under a package-top-level test or tests directory that mirrors the src layout; they MUST NOT be inlined under src.
  • Functions with more than one parameter of the same type MUST take a single options object (e.g. f({ a, b }: { a: string; b: string })); they MUST NOT use multiple positional parameters of that repeated type (e.g. f(a: string, b: string)).
  • Zod unions MUST use z.discriminatedUnion whenever every member carries a shared literal discriminator field; z.union is only permitted when no such common discriminator exists.
  • HTTP/OpenAPI wire shapes (path params, query params, request/response JSON fields) and database identifiers (table/column names, persisted jsonb document keys) MUST use snake_case.
  • Server code MUST NOT read environment variables via process.env directly; all env reads MUST go through packages/trueforge/src/config.ts, unless there is a documented special requirement (for example bootstrap before config is loaded).
  • UI styles MUST use rem for lengths (not px); assume 1rem = 16px. Prefer Tailwind spacing/type scale utilities when they fit. Exceptions: 0px in calc()/env() fallbacks, existing media-query breakpoints, and canvas/measurement APIs that require CSS pixels.

Code comments

  • Comments MUST explain intent, trade-offs, or constraints and remain brief; they MUST NOT restate the code, include issue-tracker IDs, or use {@link …} / deep cross-links.
  • Do NOT add file-level banners that enumerate implementations, backends, or call graphs; put a one-line note on the symbol that needs it, or omit.
  • Comments MUST NOT leak internal wiring into public or shared surfaces.
  • OpenAPI / route description and .describe(…) strings MUST stay under 50 words and describe the caller-visible contract only — not backend routing or storage.
  • TODOs stay to one short line when needed.