CLAUDE.md — Claude Code Implementation Guide

SOP Governance Tool (Stage 1, single-tenant)

You are pair-programming with a coding beginner who is the product owner and domain expert (3PL logistics). Optimize for his learning and for maintainability, not for cleverness.

Project context

Full specs live in /docs — READ THE RELEVANT SPEC before implementing anything: 01-PRD (scope/roles) · 02-FRD (requirements + acceptance criteria) · 03-architecture (stack & decisions AD-1…AD-6) · 04-database-schema (DDL + RLS) · 05-api-spec (routes & payloads) · 06-ui-ux (screens & tokens) · 07-development-plan (milestones M0–M7, incl. M6.5 incident log).
Stack is FIXED: Next.js App Router + TypeScript + Tailwind + shadcn/ui + Supabase + Vercel + Anthropic API. Do not introduce other databases, ORMs (use supabase-js), state libraries, or i18n frameworks.
Single org today, but org_id + RLS on every table is non-negotiable (AD-1).

How to work with me (the human)

Explain as you go. After writing code, give a 3–5 line plain-English summary of what it does and why. If I ask "explain", teach me line-by-line.
Small steps. Implement ONE checklist item at a time, then tell me exactly how to test it in the browser before moving on.
Ask before: adding any dependency, changing the schema, deviating from a spec, or deleting more than ~30 lines.
Never put secrets in client code, disable RLS "temporarily", or mock away auth to make something work.
When something fails, show me the error, your diagnosis in plain English, then the fix.

Conventions

TypeScript strict; server components by default, "use client" only when needed.
All workflow mutations go through /app/api/* route handlers using the service-role client; state transitions ONLY via lib/workflow.ts; every mutation writes audit_log in the same transaction (AD-3).
Reads use the user-scoped client under RLS.
Errors: return { error: { code, message } } with correct HTTP status (see 05-api-spec §5).
Commits: after each working step, imperative plain English ("Add SOP publish route with version snapshot").
Files: kebab-case; components PascalCase; one component per file.

Session plan (follow in order; ~2 hours each)

Before each session: read the matching milestone in docs/07-development-plan.md and the FRD items it cites. After each: run the ✅ checklist with me, commit, push (Vercel auto-deploys).

S1 (M0): Scaffold app, Tailwind, shadcn init; Supabase clients in lib/supabase/; env wiring; deploy hello world.
S2 (M0): Apply db/schema.sql + db/policies.sql + db/seed.sql; verify tables + RLS deny-by-default with an anon query test.
S3–4 (M1): Login page + session; profiles + JWT claims hook; role-redirect middleware; route guards.
S5 (M1): Users & Departments admin pages (invite, role change, deactivate).
S6–7 (M2): SOP list (filters/search) + create dialog; SOP detail shell with status badge.
S8–9 (M2): Structured editor: sections nav, step cards (add/reorder/delete), photo upload to Storage, autosave.
S10 (M3): lib/workflow.ts (canTransition, nextVersion) with unit tests; submit route + validation.
S11 (M3): decide (approve/reject) + approvals queue page; publish route with version snapshot transaction; versions tab.
S12 (M3): lib/audit.ts; wire audit into all mutations; audit page + per-SOP history tab.
S13 (M4): Assign-departments dialog + route; staff /my-sops list (mobile shell, needs-ack vs acked).
S14 (M4): Staff SOP viewer (mobile, language switcher) + acknowledge flow (typed-name sheet, immutability, re-ack on new version) + share link.
S15 (M5): Dashboard cards + per-SOP acknowledgement table + department table + overdue badges.
S16 (M5): Ack report endpoint + CSV export; audit CSV.
S17 (M6): lib/ai/ (client, prompts, JSON parser with one retry); /api/ai/draft + editor modal; ai_log + daily rate limit.
S18 (M6): /api/ai/translate + translations tab + reviewed flag + staff-viewer fallback rule (safety → English until reviewed).
S19 (M6.5): Incidents table + policies; POST /api/incidents; staff report flow (viewer "Report a problem" + My SOPs button, severity buttons, photo upload).
S20 (M6.5): Admin incident list with filters + detail; review/close route with resolution note + "requires SOP revision" jump; SOP detail Incidents tab; dashboard open-incidents card.
S21 (M7): Security checklist from docs/03-architecture.md §6 — verify each item with me and show the evidence.
S22 (M7): Real data seed for the company; fix onboarding frictions; final walkthrough of docs/02-FRD.md acceptance criteria.

Definition of done (any task)

Works in the browser · matches its FRD acceptance criteria · no TypeScript errors · explained to me in plain English · committed · deployed preview checked.

Scratch — next session goal

(Human writes 1–2 lines here before each session.)

4.9 KiB Raw Blame History Unescape Escape