illusory-iotam/AGENTS.md

AGENTS.md

This document defines the laws, principles, and rule sets that govern this codebase. Any agent or developer making changes has to adhere to these rules.

Before starting off — Read the README.md file to understand the project's goals and objectives.

---

Agent Rules (Override Everything)

1. No testing by yourself — All testing is done by the team.
2. No assumptions about code or domain logic — Always confirm and be sure before making changes.
3. No running scripts — Do not run build, dev, test, or migrate scripts unless explicitly approved.
4. No touching migration files — Do not mess with the migrations sql dir, as those are generated manually via drizzle orm

More rules are only to be added by the human, in case such a suggestion becomes viable.

---

1. Stack

• Monorepo: Turborepo + pnpm
• Language: TypeScript everywhere, Node >= 24
• Apps: @apps/main (SvelteKit), @apps/front (Hono), @apps/orchestrator (Hono)
• Packages: @pkg/logic, @pkg/db, @pkg/logger, @pkg/result, @pkg/keystore, @pkg/settings
• DB: PostgreSQL via Drizzle ORM; Redis (Valkey) via @pkg/keystore

---

2. Logic Package Conventions

All domain logic lives in @pkg/logic under packages/logic/domains/<domain>/ with four files: data.ts, repository.ts, controller.ts, errors.ts. Mirror this exactly when adding a domain.

Path aliases (logic package only):

• @/* → ./* · @domains/* → ./domains/* · @core/* → ./core/*

FlowExecCtx (fctx) — passed into every domain operation for tracing:

type FlowExecCtx = { flowId: string; userId?: string; sessionId?: string; };

---

3. Error Handling

• Use neverthrow (ResultAsync, okAsync, errAsync) for all fallible async logic.
• @pkg/result's Result type is legacy — do not reach for it primarily.
• Use ERROR_CODES from @pkg/result for all error codes.
• Use getError() from @pkg/logger when converting thrown errors into Err objects at boundaries.
• Use domain-specific error constructors from errors.ts — never ad-hoc error objects.
• Always check result.isOk() / result.isErr() before accessing result.value.

---

4. Main App Conventions (apps/main)

• Feature code lives in src/lib/domains/<domain>/ — view model, components, remote functions.
• VM pattern: *.vm.svelte.ts classes own all reactive state and async flows for a screen. Pages are thin — they just mount the VM.
• Remote functions: *.remote.ts per domain. Naming: *SQ for queries, *SC for commands.
• Auth context and fctx are built inside remote functions from event.locals via $lib/core/server.utils.

---

5. Observability Convention

When adding any new operation in a repository or controller, wrap it with traceResultAsync from @pkg/logic/core/observability.ts. Keep span names descriptive and consistent (e.g. "user.getUserInfo"). Do not add ad-hoc spans.

---

6. Validation

• Valibot for all schemas. Types via v.InferOutput<typeof Schema>.
• Domain data types defined in data.ts. Remote function inputs validated via Valibot schemas passed to query() / command().