Imported from bniceley50/tradenotes (AGENTS.md). Install upstream with npx skills add bniceley50/tradenotes. Copyright stays with the author.

Source of truth for universal workflow rules: docs/brian-system-prompt-v4-6.md This file contains project-specific extensions only. If AGENTS.md and the system prompt conflict, the system prompt wins.

AI Agent Contract — TradeNotes

This file is the single source of truth for how any AI agent (Claude Code, Codex, ChatGPT, etc.) must behave when working on this repo. If an agent conflicts with this contract, this contract wins.

0) Two Modes: READ-ONLY by Default

Default mode: READ-ONLY. You may only inspect, summarize, propose, and produce labeled commands. No file edits, no formatting, no commits, no pushes.

Write mode: only when I include: EDIT_OK: [file list or "any files needed for this task"]

If EDIT_OK is not present, stay READ-ONLY. No exceptions.

1) Momentum Rules: No Question Loops

Question budget: 0

Blocked means missing input would cause: incorrect behavior, security risk, destructive changes, or wasted work that must be redone.

If not blocked, pick defaults and proceed.

If you must ask:

• One question, one sentence
• State the default you will use if unanswered
• Proceed immediately using that default

No permission questions for routine steps.

2) Operating Cadence: One Change Then Gate

1. Make exactly ONE logical change
2. Run gate: pnpm lint && pnpm typecheck && pnpm test
3. Report:
   • Gate result: pass or fail
   • If fail: first error + ~20 lines of context
   • Working tree state: clean or dirty, plus which files

Do not stack multiple unrelated changes in one step.

3) Output Contract (Every Response)

• What changed: 1-3 bullets
• Gate result: pass or fail
• If fail: first error + ~20 lines of context
• Next step: one sentence
• Session footer: Questions (blocking): [none / question + default]

Do not paste giant file dumps unless requested.

4) Repo Reality Check

If you did not open a file or run a command, do not claim you did. State exactly what is missing and propose the smallest check to confirm.

5) Stop Digging Rule

If a change branches into multiple problems: stop, finish the smallest shippable fix, gate, then do the next patch separately. Never refactor while failing.

6) Project Identity

• Project name: TradeNotes
• Purpose: Voice-to-document AI for solo plumbers and small shops. Record a job summary on site, get a completion report, compliance checklist, install record, and invoice draft ready to send before leaving the driveway.
• Current milestone: 0 (foundation + auth + PWA shell)
• Stack: Next.js 15 (App Router), TypeScript strict, Supabase, Tailwind CSS + shadcn/ui, Vercel, Google OAuth, Stripe, OpenAI Whisper, Anthropic Claude
• Repo root (local): N:\tradenotes
• Repo root (remote): github.com/bniceley50/tradenotes

7) Domain Rules and Defaults

Use these instead of asking.

AUTH AND PERMISSIONS

• Auth: Google OAuth via Supabase Auth (no magic link, no email+password)
• All API routes require session cookie — 401 if missing
• Scope all queries to user_id (MVP) or org_id (multi-user)
• Owner role: CRUD own jobs and documents
• Admin role (shop owner): read all jobs in the shop, manage members
• Service role: worker/backend only

DATA RULES

• Soft-delete only, never hard-delete job records or documents
• Documents are append-versioned (keep edit history)
• Transcripts are immutable once created
• Job status transitions are one-directional: queued → transcribing → extracting → reviewing → sent
• Audio files eligible for hard-delete after TTL (default: 30 days)
• Documents retained indefinitely

DOMAIN-SPECIFIC RULES

• Never invent facts not present in transcript, profile, or manual edits
• Never invent permit numbers, serial numbers, inspection results, or code citations
• Missing required field → flag as VERIFY BEFORE SEND
• Compliance prompt receives curated code reference pack verbatim — never asks model to infer codes
• Sending is blocked until user acknowledges all VERIFY flags
• Generation pattern: 1 extraction call → deterministic validation (app code) → 3 generation calls
• Validation step is application code against known checklist — NOT an AI call

MULTI-USER RULES

• Launch: multi-user under one shop account (owner + techs)
• Each job has user_id (tech who created it) and shop_id (org)
• Admins see all jobs in their shop
• Techs see only their own jobs
• Stripe subscription is per-shop, not per-user

IDEMPOTENCY

• If job already at target state, return current record — no duplicate writes
• If user already has an active job in progress, reject new job creation (409)

BILLING RULES

• Stripe from day one — subscription per shop
• Beta users get a free tier (limited jobs/month, tracked in DB)
• Track per-job API cost from first beta job (Whisper + Claude)
• Never allow unbounded AI calls without subscription check

8) Artifact and File Structure

• Migrations: supabase/migrations/YYYYMMDDHHMM_description.sql
• Prompts: prompts/extraction.md, prompts/compliance-ky-wh.md, prompts/invoice.md
• Code reference packs: prompts/codes/ky-plumbing-wh-replacement.md
• Docs: docs/RUNBOOK_DEV.md, docs/ARCHITECTURE.md, docs/DEMO.md
• Audio: Supabase Storage audio → audio/{shopId}/{jobId}/recording.webm
• Transcripts: Supabase Storage transcripts → transcripts/{shopId}/{jobId}/transcript.txt
• Documents: Supabase Storage documents → documents/{shopId}/{jobId}/{docType}.pdf

9) Gate Command

pnpm lint && pnpm typecheck && pnpm test

If gate fails: stop, fix only what is required to get gate green, gate again. No refactors while failing.

10) Security Baseline (carry forward from CNA red team audit 2026-03-17)

Required from day one — do not re-introduce known vulnerabilities:

1. No x-vercel-cron header trust — bearer token auth only (CRON_SECRET)
2. Rate limiting fails closed in production (503, not passthrough) if Upstash unavailable
3. No open redirects in auth callbacks — validate next: startsWith("/") && !startsWith("//")
4. Processing endpoints scoped to authenticated user_id — never global
5. System prompts in Claude API system parameter, NOT embedded in user message
6. Audio/document storage buckets private — path-scoped to shopId
7. Dev-login: NODE_ENV === "development" gate + ALLOW_DEV_LOGIN flag (not NEXT_PUBLIC_)
8. Rate limit AI endpoints — subscription check before any Whisper or Claude call
9. Stripe webhook signature verification on all webhook routes

11) Current Working State

Current goal: Milestone 0 — repo scaffold, Google OAuth, Stripe setup, PWA shell
Last known good checkpoint: none yet — project start
Current schema: not yet created
Open decisions: scaffolding approach (fresh Next.js init — decided), auth method (Google OAuth — decided)

Locked decisions:

• D001: Stack — Next.js 15, TypeScript strict, Supabase, Tailwind, shadcn/ui, Vercel
• D002: Auth — Google OAuth via Supabase (no magic link, no email+password)
• D003: Multi-user — shop-based org model (owner + techs under one subscription)
• D004: Billing — Stripe per-shop subscription, beta free tier with job limit
• D005: AI kill switch — AI_ENABLE_REAL_APIS + AI_ENABLE_STUB_APIS flags
• D006: Launch scope — KY plumbers only, residential gas water heater replacement only
• D007: Prompt pipeline — extract (1 AI call) → validate (app code) → generate (3 AI calls)
• D008: Security — carry all CNA red team fixes forward from day one

12) Milestone Map

Current milestone: 0 Next decision point: Milestone 0 scaffold complete, then wire Google OAuth + Supabase.

13) Multi-Agent Protocol

• Builder agent: Claude Code (primary), Codex (secondary)
• Reviewer agents: Claude, ChatGPT, Gemini (diff review + red team)
• Coordinator: Brian merges and decides

Peer review handoff format:

• Provide: diff, files changed, acceptance criteria
• Request: risks, edge cases, security concerns
• Rule: reviewers flag only, do not rewrite unless explicitly asked

14) Formatting Policy

• No whitespace-only changes
• No drive-by refactors
• No reformatting of unrelated files
• Keep diffs tight
• Every change must have a stated reason

15) PWA Requirements (TradeNotes-specific)

• Recording must work offline — record locally first (Service Worker + IndexedDB)
• Upload when connectivity is restored — do not require signal during recording
• All UI controls must be usable one-handed on a phone with gloves
• Minimum tap target size: 48x48px
• Test on real iPhone (Safari) and Android (Chrome) before any beta invite
• iOS Safari MediaRecorder API reliability is a known risk — test early

If an agent conflicts with this contract, this contract wins.