# Claude Code Setup (KADi backend-nextjs) This document is the durable reference for the KADi Claude Code reviewer suite. It explains what is shipped under `.claude/` and how it relates to the human-review guidelines in `AGENTS.md` and the operational repo context in `CLAUDE.md`. The authoritative content for each component lives in the `.claude/` files themselves. This document summarises and indexes; it does not duplicate the internal checklists. ## How this fits with `CLAUDE.md` and `AGENTS.md` - `CLAUDE.md` is the always-loaded operating context for Claude Code in this repository: tech stack, repository conventions, naming, the Claude Code Setup registry (this same set of subagents, skills, and hooks), and project-specific operating rules. - `AGENTS.md` is the human-review guideline document: review principles, the P0 / P1 / P2 severity framing, the `AGENTS.md` Responsibility boundaries section, and diff-scoping guidance for human reviewers. - This file (`docs/foundation/claude-code-setup.md`) is the foundation reference that an engineer reads to understand what each Claude Code artefact is and how it is meant to be used. New repo members read this when onboarding. The three documents do not contradict. If a contradiction is observed, the source files under `.claude/` are authoritative. ## Reviewer suite overview The reviewer suite has four artefact families: 1. **Subagents** under `.claude/agents/`: read-only review subagents. Each has its own deterministic checklist. 2. **Slash skills** under `.claude/skills/`: user-invocable skills (`/review`, `/check`, `/check-full`). 3. **Auto-loaded skills** under `.claude/skills/`: reference content that injects automatically when working in matching `paths:` zones (`architecture-rails`, `supabase-migration-review`, `service-role-audit`). 4. **Hooks** under `.claude/hooks/`: shell scripts wired into `PreToolUse` events via `.claude/settings.json`. ## Subagents (`.claude/agents/`) Subagents run on a diff. They are read-only by allowlist (`tools: Read, Grep, Glob, Bash` with no `Edit` or `Write`). Each has its own subagent-scoped `PreToolUse:Bash` hook that calls `block-destructive-bash.sh` for defense-in-depth. ### `architecture-reviewer` Reviews diffs against the import-boundary rules in `docs/foundation/architecture-rails.md`, ADR-010 (product core vs customer adapter), and ADR-015 (architecture boundary enforcement). Reports violations by severity. Authoritative file: `.claude/agents/architecture-reviewer.md`. ### `security-reviewer` Reviews diffs against the security baseline (ADR-017), CSP enforcement (ADR-018), no-customer-exception (ADR-020), the service-role intent register, and the RLS audit. Anchors on five named trust boundaries (browser/server, app/db, core/customer, server/logs, server/outbound). Never prints real secret values; uses the placeholder `` in findings. Authoritative file: `.claude/agents/security-reviewer.md`. ### `code-quality-reviewer` Reviews diffs for TypeScript correctness, error-handling discipline, React / Next.js patterns, and test patterns. Anchors on a 7-point Quality Bar grounded in `tsconfig.json` (`strict: true`), `eslint.config.mjs` (no-console error in product zones), and `AGENTS.md`. Hands off architectural-boundary findings to `architecture-reviewer` and security findings to `security-reviewer` rather than duplicating them. Authoritative file: `.claude/agents/code-quality-reviewer.md`. ## Slash skills (`.claude/skills/`, manual via `/name`) Slash skills are user-invocable skills. `/review` is intended for explicit review orchestration. `/check` and `/check-full` support fast or full validation requests. ### `/review` Project reviewer-suite orchestrator. Dispatches `architecture-reviewer`, `security-reviewer`, and `code-quality-reviewer` in parallel against the same diff and synthesizes their findings into one severity-ordered report. Sets `disable-model-invocation: true` so it runs only on explicit user invocation. Argument-handling validates an optional base ref via a regex text-check plus `git rev-parse --verify --end-of-options` before passing to subagents. Authoritative file: `.claude/skills/review/SKILL.md`. **Known limitation.** On machines with a personal skill named `/review` at `~/.claude/skills/review/`, Claude Code may resolve `Skill(skill="review")` to the personal-level skill instead of this repository's project-level skill. To use the repository-level `/review`, rename or remove the personal-level shadow. Workaround: invoke the reviewer subagents directly with `@architecture-reviewer`, `@security-reviewer`, and `@code-quality-reviewer`. ### `/check` Fast project-health check. Runs `npm run typecheck` and `npm run lint` and emits a single PASS / FAIL summary with error counts and the first five file-and-line references on failure. Auto-routable for casual `is this clean?` requests. Authoritative file: `.claude/skills/check/SKILL.md`. ### `/check-full` Full project-health check. Runs `npm run typecheck`, `npm run lint`, and `npm run check:portability` (the composite of profiles, forbidden-strings, boundaries, openapi, csp, and secrets). Auto-routable for explicit full-validation requests. Authoritative file: `.claude/skills/check-full/SKILL.md`. ## Auto-loaded skills (`.claude/skills/`, scoped via `paths:`) Auto-loaded skills inject reference content when the user opens a file matching the skill's `paths:` patterns. They have `user-invocable: false` and do not run commands. ### `architecture-rails` Auto-loaded for boundary zones: `lib/customers/**`, `lib/*/index.ts` barrels, `app/api/v1/**`, `openapi/v1/**`, `eslint.config.mjs`, `config/profiles/**`. Provides compact import-boundary guidance and pointers to the rails doc, ADR-010, and ADR-015. Authoritative file: `.claude/skills/architecture-rails/SKILL.md`. ### `supabase-migration-review` Auto-loaded for Supabase-sensitive zones: `supabase/bootstrap/supabase-schema.sql`, `supabase/migrations/supabase-migration-*.sql`, `supabase-audit-*.sql`, `lib/supabase/**`, `docs/foundation/rls-*.md`, `docs/foundation/service-role-intent-register.md`. Provides migration-safety guidance, RLS coverage rules, lax-policy and duplicate-policy-set smells (per the RLS audit), and service-role boundary rules. Authoritative file: `.claude/skills/supabase-migration-review/SKILL.md`. ### `service-role-audit` Auto-loaded for `createAdminClient` register zones: `lib/supabase/admin.ts`, `lib/supabase/privileged-env.ts`, `docs/foundation/service-role-intent-register.md`, `app/api/admin/**`, `app/api/demo/**`. Provides the 4-tier risk legend (Critical / High / Medium / Low), the 7-column register-row format, and the six cross-cutting recommendations from the register. Authoritative file: `.claude/skills/service-role-audit/SKILL.md`. ## Hooks (`.claude/hooks/`) Hooks are shell scripts wired into `PreToolUse` events via `.claude/settings.json`. ### `check-gstack.sh` Wired to `PreToolUse: Skill`. Guards skill invocation behavior and allows repo-local skills listed in the script's `REPO_LOCAL_SKILLS` array. Authoritative file: `.claude/hooks/check-gstack.sh`. ### `warn-sensitive-paths.sh` Wired to `PreToolUse: Edit|Write`. Warns before edits to sensitive paths. Authoritative file: `.claude/hooks/warn-sensitive-paths.sh`. ### `block-destructive-bash.sh` Wired to `PreToolUse: Bash`. Blocks destructive Bash patterns configured in `.claude/settings.json`. Each reviewer subagent and the `/review` orchestrator additionally wires this hook in their own frontmatter for defense-in-depth. Authoritative file: `.claude/hooks/block-destructive-bash.sh`. ## Verification baseline The Claude Code Setup is correct when: - Each subagent file under `.claude/agents/` matches the names listed above. - Each skill directory under `.claude/skills/` matches the names listed above. - Each hook script under `.claude/hooks/` matches the names listed above. - `.claude/hooks/check-gstack.sh` `REPO_LOCAL_SKILLS` contains the six repo-local skill names. - `.claude/settings.json` wires the three hooks to their declared `PreToolUse` matchers. - `CLAUDE.md` Claude Code Setup registry section reflects the same set. - `AGENTS.md` Responsibility boundaries section delegates to this file. ## Pointers - `AGENTS.md`: human-review guidelines and severity framing. - `CLAUDE.md`: always-loaded repo operating context. - `.claude/agents/`: subagent definitions. - `.claude/skills/`: slash skill and auto-loaded skill definitions. - `.claude/hooks/`: hook scripts. - `.claude/settings.json`: hook wiring and repository-level Claude Code settings. - `docs/foundation/architecture-rails.md`: import-boundary rails (referenced by `architecture-reviewer` and `architecture-rails` skill). - `docs/foundation/service-role-intent-register.md`: createAdminClient call-site register (referenced by `security-reviewer`, `supabase-migration-review`, and `service-role-audit`). - `docs/foundation/rls-audit-2026-04-21.md`: RLS audit snapshot (referenced by `security-reviewer` and `supabase-migration-review`). - `docs/adr/`: ADRs cited above (010, 015, 017, 018, 020).