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)

No testing by yourself — All testing is done by the team.
No assumptions about code or domain logic — Always confirm and be sure before making changes.
No running scripts — Do not run build, dev, test, or migrate scripts unless explicitly approved.
No touching migration files — Do not mess with the migrations sql dir, as those are generated manually via drizzle orm
Log meaningful changes — After completing any meaningful change or activity, append a numbered entry to memory.log.md summarizing what was done. This keeps context across sessions.

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().

3.3 KiB Raw Blame History