Skip to content

AGENTS.md

Latest commit

 

History

History
62 lines (51 loc) · 2.92 KB

AGENTS.md

File metadata and controls

62 lines (51 loc) · 2.92 KB
Raw

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 and CONTRIBUTING.md. This file is the short version.

Commands

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.