ubiquitous-invention/AGENTS.md

# AGENTS.md

Operating manual for AI coding agents (Cursor, Codex, Copilot, etc.) working in this repo. Humans should read it too. Keep it short and accurate — if you change conventions in code, update this file in the same change.

> Product: **Echodo** — a multitenant task app whose backlog is mirrored as markdown under `plans/` and synced to Cursor.
> Repo name on disk is `tasks` and the package scope is `@tasks/*` (historical, pre-rename). Everything else — the database, the deploy, the public domain — is `echodo`. If you see a `tasks` database anywhere, it's an artifact of the old name; the source of truth is `echodo`.

---

## 1. Repo layout

```
apps/
  web/             Next.js 15 (App Router, React 19) — tRPC, NextAuth, Drizzle, TipTap, Tailwind
  collab-server/   Hocuspocus (Yjs) realtime server, Redis-backed
  mcp-server/      Model Context Protocol server exposing tasks/objects to agents
packages/
  database/        Drizzle ORM schema, client, migrations, markdown-backlog importer
  shared/          Shared TS types and utils (zod schemas live here)
  ai/              AI SDK wrappers, prompts, provider config (OpenAI / Anthropic / Ollama)
config/
  CursorSync.md    Contract for app ↔ Cursor sync (read before touching sync code)
docs/
  Glossary.md      Vocabulary for plans/epics/tasks/tenants/sync
  templates/       Plan / Epic / Task markdown templates
plans/             The markdown backlog itself (see §6)
docker/            Local + Coolify compose files, Dockerfile, prod next.config
```

Workspace tooling: **pnpm 9** + **Turborepo** + **TypeScript 5.7**. Node `>=20`.

---

## 2. Commands

Run from the repo root unless noted. Always use `pnpm`, never `npm` or `yarn`.

| Task | Command |
|------|---------|
| Install | `pnpm install` |
| Dev (all apps) | `pnpm dev` |
| Dev one app | `pnpm --filter @tasks/web dev` (or `@tasks/collab-server`, `@tasks/mcp-server`) |
| Build | `pnpm build` |
| Lint | `pnpm lint` |
| Type-check | `pnpm type-check` |
| Format | `pnpm format` (Prettier) |
| Drizzle: generate migration | `pnpm db:generate` |
| Drizzle: apply migrations | `pnpm db:migrate` |
| Drizzle: push (dev only) | `pnpm db:push` |
| Drizzle Studio | `pnpm --filter @tasks/database db:studio` |
| Import `plans/` into DB | `pnpm --filter @tasks/database watch:markdown-backlog` (needs `MARKDOWN_BACKLOG_WORKSPACE_ID`) |
| Test | `pnpm test` (turbo runs vitest in every package that has a `test` script) |
| Test one package | `pnpm --filter @tasks/<name> test` |
| Test in watch mode | `pnpm --filter @tasks/<name> test:watch` |

Before opening a PR or finishing a task, run **`pnpm lint && pnpm type-check && pnpm test`** at minimum. Run `pnpm build` if you touched build config, server entry points, or cross-package exports.

If you edit anything under `apps/mcp-server/` or any library it imports, your changes won't be visible to MCP tool calls in the **current** Cursor chat — the MCP server is a long-lived stdio process per session and doesn't auto-reload. See the **MCP server lifecycle** section in [config/CursorSync.md](./config/CursorSync.md) for how to find and kill stale servers.

Tests live next to source as `*.test.ts` files. Vitest is configured per package (see `vitest.config.ts` in `packages/shared`, `packages/database`, `packages/ai`). When you add a new package that has logic worth verifying, copy one of those configs and add `test` / `test:watch` scripts to the package's `package.json`. CI gates merges on lint + type-check + test — see [.github/workflows/ci.yml](./.github/workflows/ci.yml).

---

## 3. Environment & secrets

- Local dev reads `.env` at the repo root. `.env.example` documents every variable; keep it in sync when you add a new one.
- `.env`, `*.secrets`, `*-credentials.*`, `id_rsa`, `*.key`, and `AGENT-DEPLOY.md` are gitignored. **Never** read `AGENT-DEPLOY.md` contents into a committed file, log, or PR description — it contains homelab IPs and credentials.
- Production deploys run on Coolify (CT 107) against shared Postgres/Redis on CT 102. Don't change deploy assumptions (Docker compose files, `next.config.docker.ts`) without flagging it explicitly.
- **The Postgres database name is `echodo`**, full stop — local dev, Coolify, the drizzle migration ledger, and the docker-compose `POSTGRES_DB` all need to agree. An older `tasks` database may still exist on CT 102 as a relic of the pre-rename era; treat it as a dev sandbox at best and never point Coolify at it. The 2026-06 "Authentik SSO returns `Configuration`" incident was caused by Coolify pointing at `echodo` (correct) while a stale `tasks` database had the only initialized schema.
- `NEXT_PUBLIC_*` is the only browser-exposed prefix. Never put secrets behind it.

---

## 4. Code conventions

### TypeScript
- `strict: true` is on. Don't add `// @ts-ignore` or `any` to silence errors — fix the type. If you truly need to escape, use `// @ts-expect-error <reason>`.
- ESM only (`"type": "module"` in packages). Use named exports.
- Validate every external input (HTTP body, env var, markdown frontmatter, MCP tool args) with **zod**. Shared schemas live in `packages/shared`.
- Prefer `import type { … }` for type-only imports.

### Web app (`apps/web`)
- Next.js **App Router**. Server Components by default; add `"use client"` only when you need state, refs, or browser APIs.
- Data flow is **tRPC** (`apps/web/server/`) called via `@trpc/react-query` in client components and direct procedure calls in server components / actions.
- Auth is **NextAuth v5** (`apps/web/lib/auth.ts`). Always check session in protected procedures and route handlers.
- UI: **Tailwind + Radix primitives + `cva` + `clsx` + `tailwind-merge`**. Reuse components from `components/ui/`; don't reinvent buttons, dialogs, dropdowns.
- Editor stack is **TipTap 3 + Yjs + Hocuspocus**. Document state is collaborative — don't mutate doc JSON directly when a Y.Doc is available.
- Routing groups: `(app)` is authenticated app, `(auth)` is sign-in/up. Workspace pages live under `app/(app)/[workspaceSlug]/`.

### Database (`packages/database`)
- Schema lives in `src/schema/*.ts` and is re-exported from `src/schema/index.ts`. Drizzle config points there.
- **Multitenancy is enforced by `workspace_id`** on every tenant-scoped table. Any new table that holds user data must include `workspace_id` (UUID, not null) and an index on it. Every query must filter by `workspace_id`.
- Generate migrations with `pnpm db:generate` after schema changes. Commit the generated SQL in `packages/database/migrations/`. Don't hand-edit existing migrations — write a new one.
- `db:push` is for local prototyping only. Production uses `db:migrate`.

### Collab server (`apps/collab-server`)
- Persistence is via Hocuspocus database extension into Postgres; presence/awareness via Redis. Keep auth checks in `src/index.ts` aligned with the web app's session model.

### MCP server (`apps/mcp-server`)
- Tools live in `src/tools/`, resources in `src/resources/`. Every tool must have a zod schema for arguments and must respect tenant scoping (`workspace_id`).

### Shared (`packages/shared`)
- Cross-app types and zod schemas only. No React, no Node-specific APIs, no DB imports.

### AI (`packages/ai`)
- Use the **Vercel AI SDK** (`ai`, `@ai-sdk/openai`, `@ai-sdk/anthropic`). Provider selection is driven by env (`OPENAI_BASE_URL` can route through local Ollama on CT 108).
- Keep prompts in `src/prompts/`; no inline prompt strings scattered in components.

### Style
- Prettier formats everything. Don't fight it.
- Comments explain **why**, not **what**. Don't add narration comments like `// import the module` or `// loop over items`. Don't leave breadcrumbs describing the change you just made.
- Prefer small, named functions over deeply nested callbacks.
- File names: kebab-case for routes/components, camelCase for hooks/utilities matching the symbol they export.

---

## 5. Workflow

1. **Read before writing.** Skim `docs/Glossary.md` and (when relevant) `config/CursorSync.md` and the touched package's `src/index.ts` before editing.
2. Make a plan if the task touches >2 files or crosses package boundaries. Update or add a `Task-*.md` under the right `plans/Plan-*/Epic-*/` if the work is non-trivial product change.
3. Implement, then run `pnpm lint && pnpm type-check`. Fix every error you introduced.
4. Don't commit unless the user asks. When you do commit, write a short, focused message — *why*, not a diff narration.
5. Don't push, force-push, or amend without explicit instruction.

---

## 6. The markdown backlog (`plans/`)

This tree is **the source of truth for product work**. The importer in `packages/database/src/markdown-backlog/` parses every file under `plans/` into `markdown_backlog_items`, and `cursor_sync_mappings` stores the Cursor-side ids.

Layout is strict (the parser depends on it):

```
plans/
  Plan-<slug>/
    Plan-<slug>.md
    Epic-<slug>/
      Epic-<slug>.md
      Task-<slug>.md
```

Rules:
- Slugs are lowercase-hyphenated and stable. Renaming the display title is fine; renaming a slug breaks sync — only do it deliberately.
- Every Plan/Epic/Task file must start with the YAML frontmatter from `docs/templates/`. Required fields: `kind`, `slug`, `title`, `status`, `priority`, `tenant_id`, `updated_at`. Plan/Epic/Task add their own (`plan_slug`, `epic_slug`, `cursor_*_id`).
- `status` ∈ `draft | ready | in_progress | blocked | done | cancelled`. `priority` ∈ `P0 | P1 | P2 | P3`.
- One Task per file. Keep tasks **bead-scale**: a single Cursor agent session can complete or materially advance the work.
- Don't reach across tenants — `tenant_id` scopes every record and every Cursor mapping.

When in doubt, copy from `docs/templates/` and look at `plans/Plan-multitenant-cursor-sync/` for a worked example.

---

## 7. Things to avoid

- Adding a new package manager, monorepo tool, or framework without a discussion.
- Bypassing tRPC by writing raw `fetch` calls to internal API routes.
- Querying the DB without a `workspace_id` filter on tenant-scoped tables.
- Inlining secrets, IPs, or hostnames from `AGENT-DEPLOY.md` into source or docs.
- Editing existing migrations in `packages/database/migrations/`.
- Adding files outside the directories listed in §1 without a reason.
- Generating large binary blobs, hashes, or lockfile diffs by hand.