nextjs-loop-engineering-starter AGENTS.md

AGENTS.md — Project Instructions for AI Agents

How to Start a Loop

See README.md → "Developing with the Loop" for the Report/Build mode commands. Skills live in .claude/skills/<name>/SKILL.md.

Project Purpose

A task management web application built with Next.js and developed through loop engineering. Treat this as a real product codebase: the backlog in BACKLOG.md defines what to build next, and every change goes through the verifier pipeline. Whatever the product owner puts in BACKLOG.md is the product — build that.

Stack

Next.js 15 (App Router) · React 19 · TypeScript (strict)
Tailwind CSS 4 + shadcn/ui conventions (components.json is configured)
SQLite + Drizzle ORM (zero external services)
Vitest (unit) · Playwright (e2e, deterministic config)

Commands

pnpm db:reset         # push schema + deterministic seed — run once after clone
pnpm e2e              # Playwright e2e (starts its own server, reseeds DB)
pnpm verify           # THE verification pipeline — same as CI
pnpm snap [routes]    # screenshot pages for visual inspection (dev server must run)

Code Rules

TypeScript

• strict: true and noUncheckedIndexedAccess: true — never use any (the verifier rejects diffs containing any)
• Validate every external input (form data, search params) with Zod

Next.js

• Server Components by default — add "use client" only where the component needs state, effects, or event handlers
• Mutations go through Server Actions in actions.ts files colocated with the route (see src/app/tasks/actions.ts for the reference pattern: auth check → Zod parse → ownership check → mutate → revalidatePath)
• Every route with async data gets loading.tsx and error.tsx (see src/app/tasks/ for the reference implementation)
• Auth: call getCurrentUser() from @/lib/auth in server code. Never edit src/lib/auth.ts — it is denylisted.

Database (Drizzle + SQLite)

• Schema: src/db/schema.ts. Always query through db from @/db/client
• Schema change flow: edit schema → pnpm db:push locally → note in the PR that a migration is needed. Schema changes always need human review
• Deletes are soft (deletedAt) — follow the pattern in tasks
• Never edit src/db/seed.ts randomness rules: seeds stay deterministic (fixed IDs, fixed dates), e2e depends on it