prisma-next AGENTS.md

Agents — Prisma Next

Welcome. This is a contract‑first, agent‑friendly data layer.

Start Here

• Docs Index — How the docs are organized and what to read next
• Architecture Overview — High-level design principles
• Testing Guide — Philosophy, patterns, and commands
• Rules Index — All agent rules organized by topic
• ADRs — Architecture Decision Records

Modular Onboarding

• Getting Started — Build, test, and run demo
• Repo Map & Layering — Package organization and import rules
• Conventions — TypeScript, tooling, and code style
• Testing — Test commands, patterns, and organization
• Common Tasks Playbook — Add operation, split monolith, fix import
• Cursor Cloud Agents — Setup, secrets, lockfile discipline, snapshot management

Project Overview

Prisma Next is a contract-first data access layer:

• Contract-first: Emit contract.json + contract.d.ts — no executable runtime code generation
• Composable DSL: Type-safe query builder (sql().from(...).select(...))
• Machine-readable: Structured artifacts that agents can understand and manipulate
• Runtime verification: Contract hashes and guardrails ensure safety before execution

Where skills and rules live

The repo keeps a single canonical home for each kind of agent surface, with presentation symlinks that satisfy the paths each harness expects.

• Skills — canonical home: skills-contrib/<skill-name>/SKILL.md. These are the tracked, deliverable source-of-truth files.
• Skills — presentation symlinks: .claude/skills/<skill-name> and .agents/skills/<skill-name> are symlink directories pointing into skills-contrib/. They exist so the various agent harnesses (Cursor, Claude Code, …) can find the skills at the paths they expect. Both symlink trees are gitignored.
• Skills — wired post-install: the symlink trees (and any tooling-specific copies) are materialized by the prepare script in package.json, which runs skills add ./skills-contrib --skill '*' --agent universal claude-code -y. After pnpm install, .claude/skills/ and .agents/skills/ are populated automatically — no manual setup. If you add a new skill under skills-contrib/, re-run pnpm install (or just the prepare hook) to wire it into the tooling locations. pnpm lint:skills validates skill frontmatter in CI.
• Drive upstream in ignite: drive-* skills and docs/drive/ live in prisma/ignite (skills/.pilot/); install with npx skills add prisma/ignite/skills/.pilot --skill '*'. This repo keeps only drive/ project-context overlays.
• Rules — canonical home: .agents/rules/<rule-name>.mdc — the only tracked copy (rule files must use the .mdc extension; a .md rule is never loaded by the harnesses) (a whitelist exception in .gitignore keeps .agents/rules/** tracked even though the rest of .agents/ is ignored). The .cursor/rules/ and .claude/rules/ trees are gitignored presentation mirrors containing only relative symlinks back into .agents/rules/.
• Rules — wired post-install: like skills, the symlink trees are materialized by prepare (which runs node scripts/sync-agent-rules.mjs after skills add). After pnpm install the trees are regenerated automatically — no manual setup. A rule added only to .cursor/rules is gitignored and silently lost, so always add it under .agents/rules/ and run pnpm rules:sync. pnpm lint:rules:symlinks enforces tree/canonical consistency in CI.
• Practical implication for editors and sub-agents: when amending or authoring a skill or rule, edit at the canonical path (skills-contrib/ for skills, .agents/rules/ for rules) — not at the symlinked path. An edit through a symlink writes to the canonical file on disk, but git status and git ls-files report against the canonical path; addressing the canonical path keeps diffs legible and avoids surface churn.