AGENTS.md git:20260728.85b66abA

Immutable. This exact content never changes and is served at /api/v1/blob/f633c750b3499a8f.

# AGENTS.md

Piyaz is an agentic workspace for project management, where people and coding
agents work on the same project. It runs as an MCP server
(`app/api/mcp/route.ts`, nine ref-first tools) with a Next.js web app on top, storing
a project as a graph of tasks, dependency edges, decisions, and execution records.

Full contributor guidance is in [CLAUDE.md](CLAUDE.md) and
[CONTRIBUTING.md](CONTRIBUTING.md). This file is the short version.

## Commands

```sh
bun install
bun run dev          # next dev
bun run lint         # eslint, the linter
bun run typecheck    # tsc --noEmit
bun run format       # biome, the formatter only
bun test             # full suite; use `bun run test` so the test DB starts
bun test tests/api/task.test.ts   # one file, once the test DB is up
```

CI gates in order: `bun audit`, `format:check`, `lint`, `typecheck`, a `db:generate`
diff check, `test`, `check:plugins`.

## Layout

- `app/` routes, RSCs, and UI; route handlers under `app/api/**`
- `lib/actions/` server actions, the auth-checked mutation entry points
- `lib/data/` all RLS-scoped DB access, one module per aggregate; the only layer
  that touches `withUserContext`
- `lib/db/` Drizzle client, driver selection, RLS helpers
- `lib/auth/` better-auth wiring, sessions, MCP token verification
- `lib/mcp/` tool registration and schemas; `lib/graph/tools/` one handler module
  per tool; `lib/context/_core/` the context lenses tasks are read through
- `plugins/` vendor plugins for Claude Code, Codex, Cursor, and Antigravity

## Rules worth knowing before you edit

- **Row-level security is the tenant boundary.** Never call `db.select`, `db.query.*`,
  `db.transaction()`, or `.batch()` directly. Go through `withUserContext(userId, tx)`
  or `withUserContextRead` from `@/lib/db/rls`. ESLint rejects the alternatives with
  the reason inline.
- **Two build targets from one codebase**: self-host Node and Cloudflare Workers.
  Runtime-specific modules come in `.node.ts` / `.workers.ts` pairs; the bare module
  re-exports the Node variant and `next.config.ts` swaps it for Workers builds.
  Editing one variant usually means editing its sibling, because typecheck only sees
  `.node`.
- **`public` schema belongs to Drizzle** (`lib/db/schema.ts` + `bun run db:generate`);
  the `piyaz_auth` schema, roles, grants, and RLS policies are hand-written SQL under
  `docker/`. Migrations are roll-forward only; `db:push` is for throwaway test DBs.
- **Generated files.** `plugins/claude-code/` is canonical; run `bun run sync:plugins`
  after editing shared skills. The MCP tool docs are generated by
  `scripts/generate-docs.ts` into a separate repo. Do not hand-edit either output.
- **This repository is public.** No real project data, ids, emails, or tokens in
  commits, comments, or PR text.

## Commits

Conventional Commits, imperative, lowercase, under 72 characters, signed. Squash merge
only. Versions and `CHANGELOG.md` are managed by release-please; do not bump them by
hand.