Skip to content

A full-featured CRM built with React, shadcn/ui, and Supabase.

Still rewritting skills like Addy Osmani conventions

Jerome435904885ca2
diff --git a/.claude/skills/adr-writing/SKILL.md b/.claude/skills/adr-writing/SKILL.md
index 59276f78..bbee2f7d 100644
--- a/.claude/skills/adr-writing/SKILL.md
+++ b/.claude/skills/adr-writing/SKILL.md
@@ -77,3 +77,19 @@ Reviewers see the ADR alongside the implementation.
```
Keep it short. An ADR longer than 25 lines is a sign that the decision either belongs in code comments or is actually several decisions that should be split.
+
+## Red Flags
+
+- An ADR written for a naming, file-placement, or pure-style choice (no ADR is the default).
+- A monotonic `ADR-NNN-…` filename instead of the `ADR-<SESSION_SHORT_ID>-<TASK-XXX>-<slug>` namespace parallel workers collide on the same number.
+- An ADR file written outside the worktree, or committed separately from the code it describes.
+- `Alternatives considered` invented after the fact instead of `- _Not captured at decision time._`.
+- An ADR past 25 lines likely belongs in code comments or is several decisions.
+
+## Verification
+
+- [ ] The change is a genuine structural decision (new pattern, dependency, convention departure, non-obvious schema) otherwise no ADR.
+- [ ] Filename is `<WORKTREE_PATH>/adr/ADR-<SESSION_SHORT_ID>-<TASK-XXX>-<slug>.md`.
+- [ ] Exactly one source-code reference comment points at the ADR.
+- [ ] ADR + reference comment are in the same commit as the code, with the `docs(TASK-XXX):` subject.
+- [ ] Body follows the template and is ≤ 25 lines.
diff --git a/.claude/skills/backend-dev/SKILL.md b/.claude/skills/backend-dev/SKILL.md
index f0346353..b6cbf684 100644
--- a/.claude/skills/backend-dev/SKILL.md
+++ b/.claude/skills/backend-dev/SKILL.md
@@ -3,7 +3,22 @@ name: backend-dev
description: Coding practices for backend development in Atomic CRM. Use when deciding whether backend logic is needed, or when creating/modifying database migrations, views, triggers, RLS policies, edge functions, or custom dataProvider methods that call Supabase APIs.
---
-There is no custom backend server. All server-side logic uses Supabase: PostgreSQL (tables, views, triggers, RLS), Auth API, Storage, and Edge Functions.
+# Backend Development
+
+Reference for backend conventions. There is no custom backend server all
+server-side logic uses Supabase: PostgreSQL (tables, views, triggers, RLS),
+Auth API, Storage, and Edge Functions. Read the relevant section before writing backend code, then check the Red Flags and Verification list.
+
+## When to Use
+
+- Deciding *whether* a change needs backend logic at all (default: prefer the frontend).
+- Creating or modifying database views, triggers, or RLS policies.
+- Writing or changing a Supabase edge function, or a custom dataProvider method that calls Supabase.
+
+For the SQL migration mechanics themselves, see `Skill({skill: "writing-migrations"})`.
+For the frontend side of a dataProvider method, see `Skill({skill: "frontend-dev"})`.
+
+## Deciding where logic belongs
Prefer frontend-only solutions via custom dataProvider methods calling the PostgREST API.
@@ -12,14 +27,35 @@ When backend logic is needed:
- **Aggregation/read optimization**: Create a database view (`CREATE OR REPLACE VIEW` in a new migration). PostgREST exposes views like tables. When underlying table columns change, update the `contacts_summary` and `companies_summary` views too.
- **Complex mutations** (multi-table writes): Create a Supabase edge function in Deno. Stored procedures via RPC are less preferred (code lives in migrations, harder to maintain). On the frontend, expose the edge function as a custom dataProvider method (using `httpClient(`${supabaseUrl}/functions/v1/<name>`)`) and call it via react-query. (e.g. `salesCreate()` → `/functions/v1/users`, `mergeContacts()` → `/functions/v1/merge_contacts`)
-Edge function conventions:
+## Edge function conventions
+
- Shared utils in `supabase/functions/_shared/` — reuse `authentication.ts`, `supabaseAdmin.ts`, `cors.ts`, `utils.ts`
- Follow the middleware chain pattern: CORS preflight → `authenticate()` → handler
- `verify_jwt = false` in config.toml, so JWT validation is manual via `authenticate()`
-Other conventions:
+## Other conventions
+
- New tables need RLS policies and the auto-set `sales_id` trigger (see migration `20260108160722`)
-RLS enforcement pitfalls (security-critical):
+## RLS enforcement pitfalls (security-critical)
+
- A trigger/function that **counts rows to enforce a limit** (capacity, quota, balance, subscription depletion) must be `SECURITY DEFINER` with a fixed `search_path`, or delegate to one. A `SECURITY INVOKER` count runs under the caller's RLS, sees only the rows that caller may read, under-counts, and the limit silently never fires (e.g. `session_booked_count` is DEFINER for exactly this reason).
- A `WITH CHECK` clause must constrain **every column a non-admin may set**, not just ownership. `with check (contact_id = current_user_contact())` alone lets the caller forge any other column (`status`, `type`, amounts, flags) via PostgREST — privilege escalation / payment bypass. Whitelist allowed values in the policy, a trigger, or a `CHECK` constraint; never trust a client-chosen `status`/`type`.
+
+## Red Flags
+
+- Reaching for an edge function or RPC where a custom dataProvider method against PostgREST would do.
+- Adding a column to a table that feeds `contacts_summary`/`companies_summary` without updating the view.
+- A new table without RLS policies or the `sales_id` trigger.
+- A row-counting limit enforced by a `SECURITY INVOKER` function it under-counts and never fires.
+- A `WITH CHECK` that constrains only ownership while leaving `status`/`type`/amounts client-settable.
+- An edge function handler that runs before `authenticate()` in the middleware chain.
+
+## Verification
+
+- [ ] The logic genuinely needs the backend no frontend-only path was available.
+- [ ] New/changed views keep `contacts_summary` and `companies_summary` in sync.
+- [ ] New tables have RLS policies and the `sales_id` trigger.
+- [ ] Any limit-enforcing count runs `SECURITY DEFINER` with a fixed `search_path`.
+- [ ] Every column a non-admin can set is constrained by policy, trigger, or `CHECK`.
+- [ ] Edge functions follow CORS → `authenticate()` → handler.
diff --git a/.claude/skills/delete-initial-resource/SKILL.md b/.claude/skills/delete-initial-resource/SKILL.md
index 4b4a30fb..eb8da7a3 100644
--- a/.claude/skills/delete-initial-resource/SKILL.md
+++ b/.claude/skills/delete-initial-resource/SKILL.md
@@ -5,7 +5,16 @@ description: Remove one or more of the initial CRM resources (contacts, companie
# delete-initial-resource
-Removes one or more of the five initial Atomic CRM resources (`contacts`, `companies`, `deals`, `tags`, `tasks`) and every reference to them. **Irreversible — confirm the target(s) with the user first; rely on git to recover.**
+## Overview
+
+Removes one or more of the five initial Atomic CRM resources (`contacts`, `companies`, `deals`, `tags`, `tasks`) and every reference to them. **Irreversible confirm the target(s) with the user first; rely on git to recover.** Exit criterion: `make typecheck && make lint` is clean and no live reference to the deleted resource(s) survives in `src/` or `supabase/`.
+
+## When to Use
+
+- The user asks to delete, remove, or strip out one or several built-in CRM resources.
+- Not for *custom* entities added during setup only the five built-ins above.
+
+For the backend migration mechanics, see `Skill({skill: "backend-dev"})` and `Skill({skill: "writing-migrations"})`.
## Steps
@@ -53,7 +62,26 @@ See the `backend-dev` skill for the migration workflow. In `supabase/schemas/`:
- **Orphan check:** deleting triggers can orphan helpers — but verify shared callers first (`get_domain_favicon` survives a `companies` delete because contact avatars also call it).
- **Edge functions** are separate and easy to miss: `merge_contacts/`, `_shared/db.ts` (Kysely types), `postmark/` (inbound email), and `mcp/` (an AI subsystem whose depth varies per resource). When a surviving function loses a capability, **flag it to the user**.
-## Verify
+## Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I deleted the folder, the resource is gone." | A resource is also fields on other records, `nb_<resource>` aggregates, shared subsystems, config props, dataProvider methods, and SQL — the folder is the easy part. |
+| "A `\b<resource>\b` grep came back clean, so it's clean." | `nb_<resource>` and denormalized `company_name` are invisible to that grep (`_` is a word char). Grep them separately. |
+| "I'll remove the i18n key from English only." | The French catalog is type-checked against English — a one-sided removal is a `tsc` error. Remove from both or neither. |
+| "The script edits the dependent files for me." | The script only deletes folders and prints the list. Editing every dependent file is your job. |
+| "Typecheck passes, so the deletion is complete." | `tsc` misses broken views/functions/grants. Reset the DB and grep for live references too. |
+
+## Red Flags
+
+- Editing files inside `supabase/migrations/` (never — they are append-only history).
+- A one-sided i18n key removal (English without French, or vice versa).
+- Relying on a single `\b<resource>\b` grep and skipping `nb_<resource>` / `company_name`.
+- Deleting a shared SQL helper or edge-function capability without checking surviving callers.
+- Deleting several resources but half-applying each file's "narrow the union" note.
+- Skipping the `db reset` check when Supabase is running.
+
+## Verification
```bash
make typecheck && make lint
@@ -61,6 +89,13 @@ make typecheck && make lint
Resolve whatever `tsc` surfaces (the dependent-file list is a guide, not a guarantee). Then `grep -rniE "\b<resource>\b"` over `src/`+`supabase/`, plus **separate** greps for `nb_<resource>`, `company_name`, and config-prop names (`<resource>Types`, `companySectors`, `currency`). Watch for benign/substring false positives (each resource file lists its own); never edit `supabase/migrations/`.
+- [ ] `make typecheck && make lint` is clean.
+- [ ] `\b<resource>\b`, `nb_<resource>`, `company_name`, and config-prop greps return only benign matches.
+- [ ] i18n keys removed from both catalogs, or neither.
+- [ ] Backend: table/view/policies/grants/sequences and any function references handled in `supabase/schemas/` (not `migrations/`).
+- [ ] If Supabase is running, `npx supabase db reset --local` replays cleanly.
+- [ ] Any lost edge-function capability flagged to the user.
+
**i18n is all-or-nothing:** `frenchCrmMessages.ts` is type-checked against the type derived from `englishCrmMessages.ts`, so remove a key from **both** catalogs or **neither** (a one-sided removal is a `tsc` error). Dead `resources.<x>.*` keys are harmless — flag rather than force. `frenchCrmMessages.ts` uses literal `…` escapes; if an exact-string `Edit` fails on a block spanning one, fall back to `sed -i '<from>,<to>d'`.
If Supabase is running, `npx supabase db reset --local` replays the chain + `seed.sql` and catches a broken view/function/grant `db diff` misses (benign `index "…_pkey" does not exist` NOTICEs expected). On Node 22 (see `.nvmrc`), `make test` (vitest) is also available.
diff --git a/.claude/skills/playwright-testing/SKILL.md b/.claude/skills/playwright-testing/SKILL.md
index a8552ede..3cde6957 100644
--- a/.claude/skills/playwright-testing/SKILL.md
+++ b/.claude/skills/playwright-testing/SKILL.md
@@ -5,7 +5,16 @@ description: Playwright E2E testing patterns — web-first assertions, user-visi
# Playwright E2E Testing
-Browser-based end-to-end testing with auto-waiting, cross-browser support, and reliable locators.
+Reference for the assertion, locator, and structure patterns used inside an e2e spec. Browser-based end-to-end testing with auto-waiting, cross-browser support, and reliable locators.
+
+## When to Use
+
+- Writing or reviewing the body of a Playwright e2e spec.
+- Setting up browser testing for the app (config, fixtures, auth, parallelism).
+- Migrating tests from Cypress or Selenium.
+
+For *whether* a change requires an e2e test and *where* the spec goes, see
+`Skill({skill: "e2e-conventions"})`.
---
@@ -442,7 +451,16 @@ Run `npx playwright test --update-snapshots` to generate baseline images. Snapsh
---
-## Checklist
+## Red Flags
+
+- `page.$()` / `page.textContent()` / `isVisible()` checks instead of web-first assertions.
+- CSS or XPath selectors where a `getByRole`/`getByLabel`/`getByText` locator exists.
+- Any `waitForTimeout()`, or `waitForSelector()` before a locator action.
+- `waitForResponse()` set up *after* the action that triggers the call.
+- Login flow repeated per test instead of `storageState` or a fixture.
+- `test.only` left in code, or `fullyParallel` disabled without a shared-state reason.
+
+## Verification
- [ ] Web-first assertions (`expect(locator).toBeVisible()`) — never `page.$()` or `page.textContent()`
- [ ] User-visible locators (`getByRole`, `getByLabel`, `getByText`) over CSS selectors
diff --git a/.claude/skills/setup-interview/SKILL.md b/.claude/skills/setup-interview/SKILL.md
index 0c7874e6..c4c42256 100644
--- a/.claude/skills/setup-interview/SKILL.md
+++ b/.claude/skills/setup-interview/SKILL.md
@@ -3,12 +3,19 @@ name: setup-interview
description: Domain-by-domain interview to produce $CLAUDE_PROJECT_DIR/docs/project-context.json. Invoked once by the orchestrator; the orchestrator then conducts all turns directly using Read/Write/Edit — no agent dispatching.
---
-## Purpose
+## Overview
+
+A domain-by-domain interview that produces `$CLAUDE_PROJECT_DIR/docs/project-context.json`. You drive it one user turn at a time, persisting after each domain, until the user confirms — exit criterion: a `validated: true` JSON committed and the `VALIDATED` token emitted.
**Scope constraint**: during SETUP-INTERVIEW, your Write / Edit tools are
restricted to `$CLAUDE_PROJECT_DIR/docs/project-context.json` only. Never touch `$CLAUDE_PROJECT_DIR/src/` or
any other path.
+## When to Use
+
+- Invoked once by the orchestrator at the start of project setup; the orchestrator then conducts every turn directly.
+- Resuming an interrupted interview (`validated: false`) or updating an existing config (`validated: true`).
+
---
## FIRST ACTION — startup detection
@@ -269,3 +276,25 @@ Every orchestrator turn during SETUP-INTERVIEW ends with **exactly one** of:
The `tickets` array is populated later by `planner` in SETUP_MODE — leave it
empty here.
+
+---
+
+## Red Flags
+
+- Asking more than one domain in a single turn, or skipping the per-domain confirmation.
+- Writing or editing any path other than `docs/project-context.json`.
+- Setting `validated: true` before the consistency checks pass.
+- Mentioning entities, tables, components, or other technical terms to the user (use plain-language feature names).
+- An entity resembling a built-in (`contact`/`company`/`deal`/`tag`/`task`/`note`) marked `"type": "create"` instead of `"extend"`.
+- A service-role key or secret stored in a client-side variable.
+- Emitting anything other than exactly one output contract (plain-text question / `VALIDATED` / `FAILED:`) per turn.
+
+## Verification
+
+Before emitting `VALIDATED`:
+
+- [ ] All 8 applicable domains are `"done"` (domain 8 skipped when `MODE=demo`).
+- [ ] All consistency checks pass (no duplicate fields, pipeline entities exist, every role has a permission, built-ins use `"extend"`, no client-side secrets).
+- [ ] The `cleanup` derivation was presented in plain language and confirmed (or skipped silently when nothing qualified).
+- [ ] The user gave an affirmative final confirmation.
+- [ ] `validated: true` written, JSON committed, and `VALIDATED` is the only output (no trailing text).
diff --git a/.claude/skills/shadcn-customization/SKILL.md b/.claude/skills/shadcn-customization/SKILL.md
index d3c841b5..b9ae3d76 100644
--- a/.claude/skills/shadcn-customization/SKILL.md
+++ b/.claude/skills/shadcn-customization/SKILL.md
@@ -5,7 +5,15 @@ description: Shadcn/ui theming and component customization — CSS variables, OK
# Customization & Theming
-Components reference semantic CSS variable tokens. Change the variables to change every component.
+Reference for theming and component customization. Components reference semantic CSS variable tokens change the variables to change every component. Read the relevant section, then check the Red Flags and Verification list.
+
+## When to Use
+
+- Changing colors, theme, dark mode, or border radius.
+- Adding a custom color token or a new component variant.
+- Customizing or wrapping a shadcn/ui component.
+
+For component *architecture* and where to import from, see `Skill({skill: "frontend-dev"})`.
---
@@ -169,3 +177,22 @@ npx shadcn@latest add button --diff
npx shadcn@latest add button --dry-run # see all affected files
npx shadcn@latest add button --diff button.tsx # diff for a specific file
```
+
+---
+
+## Red Flags
+
+- A hardcoded hex/rgb color in a component instead of a semantic token (`bg-primary`, `text-muted-foreground`).
+- A new CSS file created for custom colors instead of adding them to the global CSS file.
+- A custom color used without registering it under `@theme inline` for Tailwind v4.
+- Editing component source for a one-off when a `variant` or `className` would do.
+- Palette changes wired anywhere but the `lightTheme`/`darkTheme` props on `<CRM>`.
+- A token defined in `:root` but not in `.dark` (or vice versa) — one mode is left broken.
+
+## Verification
+
+- [ ] Colors use semantic tokens, never hardcoded values.
+- [ ] Custom colors live in the global CSS file and are registered under `@theme inline`.
+- [ ] Every new token is defined in both `:root` and `.dark`.
+- [ ] Customization uses the lowest-effort approach that works (variant → `className` → new variant → wrapper).
+- [ ] Palette changes go through `lightTheme`/`darkTheme` on `<CRM>`.
diff --git a/.claude/skills/update-branding/SKILL.md b/.claude/skills/update-branding/SKILL.md
index 63963e52..aad42198 100644
--- a/.claude/skills/update-branding/SKILL.md
+++ b/.claude/skills/update-branding/SKILL.md
@@ -5,7 +5,17 @@ description: Rebrand Atomic CRM — change the application logo (the wordmark in
# update-branding
-Changes the CRM **logo** and/or **title**. The logo shows in **two themes** across **five screens** (desktop + mobile header, login, signup, confirmation) and the title is hardcoded in **three** places — a naive single-file edit leaves one stale. The steps below catch all of them.
+## Overview
+
+Changes the CRM **logo** and/or **title**. The logo shows in **two themes** across **five screens** (desktop + mobile header, login, signup, confirmation) and the title is hardcoded in **three** places a naive single-file edit leaves one stale. The steps below catch all of them.
+Exit criterion: the logo renders correctly in both themes across all five screens, and the title is consistent in the header, browser tab, and PWA name.
+
+## When to Use
+
+- The user wants to change, swap, or rebrand the CRM logo and/or title/name.
+- Optionally, when they also ask to update the favicon or PWA app icons.
+
+Not for theme colors or component styling see `Skill({skill: "shadcn-customization"})`.
## Logo: two asset families
@@ -37,10 +47,33 @@ Confirm which the user means — most requests mean only #1.
Consumers (no edits if you keep the config keys): `layout/Header.tsx` + `dashboard/MobileDashboard.tsx` render both variants (CSS-toggled, `h-6`); `login/{LoginPage,SignupPage,ConfirmationRequired}.tsx` render **only** `darkModeLogo`.
-## Verify
+## Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I changed the logo file, that's the whole job." | The logo shows in two themes across five screens and the title lives in three files. One edit leaves a stale variant. |
+| "My code change has no visual effect, so it didn't apply." | The `/settings` store shadows `defaultConfiguration.ts` per browser. Clear the `CRM.app.configuration` localStorage key. |
+| "One image is fine for both themes." | The auth pages always use the dark-mode key; a single asset reads wrong on one background. Warn or derive the second variant. |
+| "I'll regenerate a couple of favicon sizes." | The PWA set is 34 PNGs. Regenerate every size from one source or ask for the set don't hand-edit a few. |
+
+## Red Flags
+
+- Editing only one of the two logo asset keys, or swapping the light/dark files.
+- Changing the title in `defaultConfiguration.ts` but not `index.html` and `manifest.json`.
+- A code change with no visible effect, with the `CRM.app.configuration` store left uncleared.
+- Hand-editing a subset of favicon/PWA sizes instead of regenerating the full set.
+- Touching the docs-site logo (`doc/`) when it wasn't requested.
+
+## Verification
`make typecheck` catches only config-key typos. Then `make start` and check: header in **both themes**, **desktop + mobile**; the **login/signup** pages (dark bg); and if the title changed, the header `<h1>`, browser tab, and PWA name. A logo wrong in exactly one theme means both keys point at one asset, or the light/dark files are swapped.
+- [ ] Both logo variants point at the correct light/dark assets (named by display mode, not color).
+- [ ] Logo renders in both themes, desktop + mobile, and on login/signup/confirmation.
+- [ ] If the name changed, the title is updated in `defaultConfiguration.ts`, `index.html`, and `manifest.json`.
+- [ ] If no visual effect appears, the `CRM.app.configuration` localStorage key was cleared.
+- [ ] Favicon/PWA icons regenerated as a full set only if explicitly requested.
+
## Favicon & app icons (optional)
Only if asked. Referenced by `index.html` + `public/manifest.json`: `public/favicon.ico` and `public/appIcon/*.png` (34 sizes incl. `maskable_icon*`). Regenerate **every** size from one square source (`sharp` / `pwa-asset-generator`) or ask the user for the set — don't hand-edit a few. Confirm scope first; `theme_color`/`background_color` in `manifest.json` may also need updating.
diff --git a/.claude/skills/worktree-detection/SKILL.md b/.claude/skills/worktree-detection/SKILL.md
index 8f8271a8..a330d713 100644
--- a/.claude/skills/worktree-detection/SKILL.md
+++ b/.claude/skills/worktree-detection/SKILL.md
@@ -3,6 +3,16 @@ name: worktree-detection
description: How to find a Git worktree by task number without hardcoding paths. Use in hooks or scripts that need to locate a specific task's worktree.
---
+# Worktree Detection
+
+Reference snippet for locating a task's Git worktree from its task number,
+without hardcoding paths.
+
+## When to Use
+
+- Inside a hook or script that must act on a specific task's worktree.
+- Any time you'd otherwise hardcode a `/tmp/...` worktree path.
+
## Pattern
```bash
@@ -30,4 +40,15 @@ fi
TASK_NUM=$(echo "$TASK_OWNER $TASK_SUBJECT" | grep -oP 'TASK-\d+' | head -1)
```
-Works whether the task number appears in the owner field or the subject line.
\ No newline at end of file
+Works whether the task number appears in the owner field or the subject line.
+
+## Red Flags
+
+- A hardcoded `/tmp/...` worktree path instead of querying `git worktree list`.
+- Assuming a directory layout rather than reading Git's registry.
+- Treating a missing worktree as an error instead of skipping cleanly (`exit 0`).
+
+## Verification
+
+- [ ] Worktree resolved via `git worktree list --porcelain`, never a hardcoded path.
+- [ ] A missing/absent worktree is handled (skip, don't crash).