@clipboard-health/ai-rules 2.26.0 → 2.27.0

package/rules/datamodeling/dbtYamlDocumentation.md

@@ -1,3 +1,7 @@
+---
+description: "Writing dbt YAML documentation and schema files"
+---
+
 # .yaml documentation rules
 
 - The YAML should include the following sections: `version`, `models`, and `columns`.

package/rules/frontend/{fileOrganization.md → architecture.md}

@@ -1,4 +1,21 @@
-# File Organization
+---
+description: "Frontend architecture: technology stack, file organization, where business logic lives"
+---
+
+# Frontend Architecture
+
+## Technology Stack
+
+- **React** with TypeScript (strict mode)
+- **MUI** for UI components
+- **React Query** (@tanstack/react-query) for data fetching
+- **Zod** for runtime validation
+- **Vitest** + **@testing-library/react** for testing
+- **MSW** for API mocking
+- **Playwright** for E2E tests
+- **constate** for shared state
+
+## File Organization
 
 Organize frontend code by concept/feature (e.g., `Shifts/`, `Invites/`), not by type (e.g., `components/`, `hooks/`).
 
@@ -18,3 +35,7 @@ FeatureName/
 ├── paths.ts                # Route constants
 └── types.ts                # Shared types
 ```
+
+## Business Logic Placement
+
+Flag business logic in frontend code that should be a backend API call instead. Frontend/backend divergence causes bugs.

package/rules/frontend/customHooks.md

@@ -1,3 +1,7 @@
+---
+description: "Creating React custom hooks: naming, shared state with constate"
+---
+
 # Custom Hooks
 
 ## Naming
@@ -6,18 +10,6 @@
 - Data: `useGet*`, `use*Data`
 - Actions: `useSubmit*`, `useCreate*`
 
-## Structure
-
-```typescript
-export function useFeature(params: Params, options: Options = {}) {
-  const query = useQuery(...);
-  const computed = useMemo(() => transform(query.data), [query.data]);
-  const handleAction = useCallback(async () => { ... }, []);
-
-  return { data: computed, isLoading: query.isLoading, handleAction };
-}
-```
-
 ## Shared State with Constate
 
 ```typescript

package/rules/frontend/dataFetching.md

@@ -1,10 +1,14 @@
+---
+description: "Implementing data fetching and error handling: React Query, API calls, caching, parsedApi"
+---
+
 # Data Fetching
 
 ## Core Rules
 
 1. Use React Query for all API calls
 2. Define Zod schemas for all request/response types
-3. Use `enabled` option for conditional fetching
+3. Use the `enabled` option for conditional fetching: `{ enabled: isDefined(dependencyData?.id) }`
 4. Use `invalidateQueries` (not `refetch`) for disabled queries
 
 ## Hook Pattern
@@ -36,7 +40,21 @@ export function useGetFeature(id: string, options = {}) {
 
 - Log errors via `meta.logErrorMessage` using centralized event constants
 - Display user-facing errors via `meta.userErrorMessage`
-- Do not use the deprecated `onError` callback for useQuery queries , use the `meta` pattern to handle errors. This rule doesn't apply to useMutation, using onError for useMutation is a valid pattern
+- Do not use the deprecated `onError` callback for useQuery queries — use the `meta` pattern. `onError` remains valid for useMutation.
+
+```typescript
+useMutation({
+  mutationFn: createItem,
+  onSuccess: () => {
+    showSuccessToast("Created");
+    queryClient.invalidateQueries(["items"]);
+  },
+  meta: {
+    logErrorMessage: APP_EVENTS.CREATE_FAILURE,
+    userErrorMessage: "Failed to create",
+  },
+});
+```
 
 ## Query Keys
 
@@ -47,23 +65,14 @@ queryKey: ["users", userId];
 queryKey: ["users", userId, "posts"];
 ```
 
-## Conditional Fetching
+## `parsedApi.ts` vs `api.ts`
 
-```typescript
-const { data } = useGetFeature({ id: dependencyData?.id }, { enabled: isDefined(dependencyData?.id) });
-```
+Frontend repos have two API layers:
 
-## Mutations
+- **`api.ts`** (legacy) — does not parse responses through Zod schemas. Inferred types say `Date` for `dateTimeSchema()` fields but the runtime value is still a string. Zod transforms (`.transform()`, `dateTimeSchema()`, enum fallbacks) produce **incorrect types at runtime**.
+- **`parsedApi.ts`** — parses both inputs (`z.input`) and outputs (`z.output`) through schemas. Types match runtime values.
 
-```typescript
-export function useCreateItem() {
-  const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: (data: CreateItemRequest) => api.post("/items", data),
-    onSuccess: () => queryClient.invalidateQueries(["items"]),
-  });
-}
-```
+Use `parsedApi.ts` for all new API calls. However, `parsedApi.ts` means invalid contract schemas will fail at runtime — ensure contracts are forwards-compatible. Do not use `parsedApi.ts` if the contract contains bare `z.enum()` values that the backend may extend, as new enum values will cause parse failures on old clients. Migrate bare `z.enum()` to `requiredEnumWithFallback`/`optionalEnumWithFallback` first.
 
 ## Test Utilities
 

package/rules/frontend/e2eTesting.md

@@ -1,3 +1,7 @@
+---
+description: "Writing E2E tests with Playwright"
+---
+
 # E2E Testing (Playwright)
 
 ## Core Rules
@@ -5,15 +9,7 @@
 - Test critical user flows only—not exhaustive scenarios; when in doubt, write a component test instead
 - Each test sets up its own data (no shared state between tests)
 - Mock feature flags and third-party services
-- Use user-centric locators (role, label, text)—avoid CSS selectors
-
-## Locator Priority
-
-1. `page.getByRole()`
-2. `page.getByLabel()`
-3. `page.getByPlaceholder()`
-4. `page.getByText()`
-5. `page.getByTestId()` (last resort)
+- Use user-centric locators in priority order: `getByRole`, `getByLabel`, `getByPlaceholder`, `getByText`; use `getByTestId` only as a last resort—avoid CSS/XPath selectors
 
 ## Assertions
 
@@ -38,4 +34,3 @@ Before adding an E2E test:
 - Hard-coded timeouts (`page.waitForTimeout`)
 - Testing loading states (non-deterministic)
 - Shared data between tests
-- CSS/XPath selectors

package/rules/frontend/reactComponents.md

@@ -1,37 +1,8 @@
-# React Components
-
-## Type vs Interface
-
-```typescript
-// Use interface for: props, object shapes, extensible types
-interface UserCardProps {
-  user: User;
-  onSelect: (id: string) => void;
-}
-```
-
-## Structure Order
-
-```typescript
-export function Component({ userId, onUpdate }: Props) {
-  // 1. Hooks
-  const { data, isLoading } = useGetUser(userId);
-  const [isEditing, setIsEditing] = useState(false);
-
-  // 2. Derived state (no useMemo for cheap operations)
-  const displayName = formatName(data);
-
-  // 3. Event handlers
-  const handleSave = useCallback(async () => { ... }, [deps]);
-
-  // 4. Early returns for loading/error/empty
-  if (isLoading) return <Loading />;
-  if (!data) return <NotFound />;
+---
+description: "Building UI components: structure, composition, modals, bottom sheets, interactive elements, a11y, Storybook"
+---
 
-  // 5. Main render
-  return <Card>...</Card>;
-}
-```
+# React Components
 
 ## Naming Conventions
 
@@ -60,15 +31,6 @@ interface Props {
 }
 ```
 
-## Navigation & Layout
-
-- Show bottom navigation on all top-level tabs/pages; hide it on nested or drilled-in views
-- Use `Title` with correct heading levels (`h1`-`h6`) and maintain a structured `h1`→`h2`→`h3` hierarchy per page
-
-## Storybook
-
-Register every new or updated shared UI component in Storybook before merging; include a `Default` story first with all relevant props exposed via controls.
-
 ## Inline JSX and Handlers
 
 ```typescript
@@ -87,6 +49,50 @@ const handleSave = useCallback(async () => { ... }, [deps]);
 return <MemoizedChild onSave={handleSave} />;
 ```
 
+## Interactive Elements
+
+Never add `onClick` to `div` or `span` — it breaks focus states, keyboard navigation, and ARIA roles. Use:
+
+- `<button>` for actions
+- `<a>` (Link) for navigation
+- MUI interactive components (`Button`, `IconButton`, `ListItemButton`)
+
+Every interactive element must be tab focusable with a visible focus indicator and keyboard event handling.
+
+## Navigation & Layout
+
+- Show bottom navigation on all top-level tabs/pages; hide it on nested or drilled-in views
+- Use `Title` with correct heading levels (`h1`-`h6`) and maintain a structured `h1`→`h2`→`h3` hierarchy per page
+
+## Modal Routes
+
+Modal visibility is driven by URL, not local state:
+
+```typescript
+<ModalRoute
+  path={`${basePath}/confirm`}
+  closeModalPath={basePath}
+  render={({ modalState }) => (
+    <ConfirmDialog modalState={modalState} />
+  )}
+/>
+```
+
+Use `history.replace` (not `push`) when navigating between modals to avoid awkward back-button behavior.
+
+## Bottom Sheets
+
+- Every bottom sheet must include a close button in the top-right corner via `BottomSheetHeader`: `<BottomSheet modalState={modalState} header={<BottomSheetHeader onClose={onClose} />}>`
+- Buttons inside a bottom sheet must always stack vertically (never side by side). Use `<DialogFooter orientation="vertical">` or a vertical `<Stack>`.
+- Split each bottom sheet into two components for Storybook testability:
+  - **`SomethingBottomSheet`** — connected component that owns data fetching, analytics, and state; renders `<BottomSheet>` and delegates content to the presentational component.
+  - **`SomethingBottomSheetContent`** — pure presentational component that accepts only primitive/callback props; has a `.stories.tsx` file. The stories file should render a button that opens the content in a `<BottomSheet>`.
+  - Exception: a bottom sheet that is purely presentational with no data fetching/mutations can be one `.tsx` file.
+
+## Storybook
+
+Register every new or updated shared UI component in Storybook before merging; include a `Default` story first with all relevant props exposed via controls.
+
 ## Component Reuse
 
 Before creating a new component, search for existing ones in this order:

package/rules/frontend/styling.md

@@ -1,3 +1,7 @@
+---
+description: "Styling components with MUI sx prop: theme tokens, spacing, no CSS/SCSS"
+---
+
 # Styling
 
 ## Core Rules
@@ -40,13 +44,3 @@ Use `rem` for fonts/heights (scales with user zoom), spacing indices for padding
 
 - ✅ Use full names: `padding`, `paddingX`, `marginY`
 - ❌ Avoid abbreviations: `p`, `px`, `my`
-
-## Pseudo-classes
-
-```typescript
-<Box sx={(theme) => ({
-  "&:hover": { backgroundColor: theme.palette.primary.dark },
-  "&:disabled": { opacity: 0.5 },
-  "& .MuiTypography-root": { color: theme.palette.text.secondary },
-})} />
-```

package/rules/frontend/testing.md

@@ -1,3 +1,7 @@
+---
+description: "Writing frontend tests: React Testing Library, component tests"
+---
+
 # Testing
 
 ## Philosophy
@@ -6,38 +10,9 @@ Focus on integration tests—test how components work together as users experien
 
 **Priority:** Static (TS/ESLint) → Integration → Unit (pure utilities only) → E2E (critical flows only)
 
-## Test Structure
-
-```typescript
-describe("ComponentName", () => {
-  it("should [behavior] when [condition]", async () => {
-    const user = userEvent.setup();
-    render(<Component />);
-
-    await user.click(screen.getByRole("button", { name: "Submit" }));
-
-    await waitFor(() => {
-      expect(screen.getByText("Success")).toBeInTheDocument();
-    });
-  });
-});
-```
-
-## Query Priority
+## Queries
 
-1. `getByRole` (best for accessibility)
-2. `getByLabelText` (form fields)
-3. `getByText` (non-interactive content)
-4. `getByTestId` (last resort only)
-
-```typescript
-// ✅ Prefer
-screen.getByRole("button", { name: /submit/i });
-screen.getByLabelText("Email");
-
-// ❌ Avoid
-screen.getByTestId("submit-button");
-```
+Prefer user-centric queries in priority order: `getByRole`, `getByLabelText`, `getByText`; use `getByTestId` only as a last resort.
 
 ## MSW Handlers
 
@@ -50,7 +25,3 @@ export const createUserHandler = (userData: User) => rest.get("/api/user", (req,
 // Usage
 mockServer.use(createUserHandler(customData));
 ```
-
-## What to Test
-
-✅ Test: user interactions, all states (loading/success/error), integration between components

package/scripts/constants.js

@@ -3,8 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PROFILES = exports.CATEGORIES = exports.RULE_FILES = exports.FILES = exports.PATHS = void 0;
-exports.toRulePath = toRulePath;
+exports.PROFILES = exports.FILES = exports.PATHS = void 0;
 const node_path_1 = __importDefault(require("node:path"));
 const PACKAGE_ROOT = node_path_1.default.join(__dirname, "..");
 exports.PATHS = {
@@ -15,83 +14,6 @@ exports.FILES = {
     agents: "AGENTS.md",
     claude: "CLAUDE.md",
 };
-exports.RULE_FILES = {
-    "common/configuration": "Adding config, secrets, or third-party dependencies: SSM, LaunchDarkly, DB, NPM packages",
-    "common/coreLibraries": "Adding dependencies, implementing functionality, or debugging errors involving a @clipboard-health/* library",
-    "common/featureFlags": "Creating or managing feature flags: naming, lifecycle, SDK usage, Zod schemas",
-    "common/gitWorkflow": "Writing commit messages, PR titles, or reviewing pull requests",
-    "common/loggingObservability": "Adding logging, metrics, monitoring, or observability: levels, context, PII, Datadog",
-    "common/testing": "Writing unit tests: conventions, naming, structure",
-    "common/typeScript": "Writing ANY TypeScript code",
-    "backend/architecture": "Structuring NestJS modules, services, repos: three-tier, microservices, ts-rest contracts",
-    "backend/asyncMessaging": "Working with queues, async messaging, or background jobs",
-    "backend/mongodb": "Working with MongoDB/Mongoose: schemas, indexes, queries, transactions, migrations",
-    "backend/notifications": "Implementing notifications via Knock: push notifications, deep links, workflow design",
-    "backend/postgres": "Working with Postgres: column types, schema changes, query patterns, Prisma TypedSQL",
-    "backend/restApiDesign": "Designing REST APIs: JSON:API, auth, validation, pagination, ts-rest contracts, DTOs",
-    "backend/infrastructure": "Provisioning infrastructure: Terraform, Docker, ECS, DNS",
-    "backend/serviceTests": "Writing service tests: test data, background jobs, bug handling, migrations",
-    "frontend/businessLogicPlacement": "Implementing or reviewing business logic: flag logic that should live on the backend",
-    "frontend/customHooks": "Creating React custom hooks: naming, structure, shared state with constate",
-    "frontend/dataFetching": "Implementing data fetching: React Query, API calls, caching",
-    "frontend/e2eTesting": "Writing E2E tests with Playwright",
-    "frontend/errorHandling": "Handling errors in React: component, mutation (meta pattern), Zod validation",
-    "frontend/fileOrganization": "Organizing files and folders in a frontend project",
-    "frontend/frontendTechnologyStack": "Choosing frontend libraries, frameworks, or tools",
-    "frontend/interactiveElements": "Adding interactive elements: semantic HTML, a11y, keyboard accessibility",
-    "frontend/modalRoutes": "Implementing modals or route-based dialogs",
-    "frontend/reactComponents": "Writing React components: structure, composition, navigation, Storybook, inline JSX",
-    "frontend/styling": "Styling components with MUI sx prop: theme tokens, spacing, no CSS/SCSS",
-    "frontend/testing": "Writing frontend tests: React Testing Library, component tests",
-    "datamodeling/analytics": "Querying analytics data: dbt-mcp, Snowflake, source columns, output formatting",
-    "datamodeling/castingDbtStagingModels": "Casting data types in dbt staging models",
-    "datamodeling/dbtModelDevelopment": "Developing dbt models: naming, structure, testing",
-    "datamodeling/dbtYamlDocumentation": "Writing dbt YAML documentation and schema files",
-};
-function toRulePath(ruleId) {
-    return `${ruleId}.md`;
-}
-exports.CATEGORIES = {
-    common: [
-        "common/configuration",
-        "common/coreLibraries",
-        "common/featureFlags",
-        "common/gitWorkflow",
-        "common/loggingObservability",
-        "common/testing",
-        "common/typeScript",
-    ],
-    backend: [
-        "backend/architecture",
-        "backend/asyncMessaging",
-        "backend/infrastructure",
-        "backend/mongodb",
-        "backend/notifications",
-        "backend/postgres",
-        "backend/restApiDesign",
-        "backend/serviceTests",
-    ],
-    frontend: [
-        "frontend/businessLogicPlacement",
-        "frontend/customHooks",
-        "frontend/dataFetching",
-        "frontend/e2eTesting",
-        "frontend/errorHandling",
-        "frontend/fileOrganization",
-        "frontend/frontendTechnologyStack",
-        "frontend/interactiveElements",
-        "frontend/modalRoutes",
-        "frontend/reactComponents",
-        "frontend/styling",
-        "frontend/testing",
-    ],
-    datamodeling: [
-        "datamodeling/analytics",
-        "datamodeling/castingDbtStagingModels",
-        "datamodeling/dbtModelDevelopment",
-        "datamodeling/dbtYamlDocumentation",
-    ],
-};
 exports.PROFILES = {
     common: { include: ["common"] },
     frontend: { include: ["common", "frontend"] },

package/scripts/rules.js

@@ -0,0 +1,126 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRuleFile = parseRuleFile;
+exports.discoverRules = discoverRules;
+exports.resolveRules = resolveRules;
+exports.generateAgentsIndex = generateAgentsIndex;
+exports.generateReadmeRulesSection = generateReadmeRulesSection;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const FRONTMATTER_PATTERN = /^---\r?\n(?<frontmatter>[\s\S]*?)\r?\n---/;
+const DESCRIPTION_PATTERN = /^description:\s*(?<description>.+)$/m;
+const HEADING_PATTERN = /^#\s+(?<heading>.+)$/m;
+/**
+ * Parses a rule file's frontmatter `description` (the "When to Read" text) and its H1 heading.
+ * The frontmatter is the single source of truth for rule metadata; throws when it's missing so
+ * tests catch unregistered descriptions before publishing.
+ */
+function parseRuleFile(params) {
+    const { content, filePath } = params;
+    const frontmatter = FRONTMATTER_PATTERN.exec(content)?.groups?.["frontmatter"];
+    const rawDescription = frontmatter
+        ? DESCRIPTION_PATTERN.exec(frontmatter)?.groups?.["description"]
+        : undefined;
+    if (!rawDescription) {
+        throw new Error(`Rule file ${filePath} is missing a frontmatter 'description'`);
+    }
+    const description = stripQuotes(rawDescription.trim());
+    const heading = HEADING_PATTERN.exec(content)?.groups?.["heading"] ?? node_path_1.default.basename(filePath, ".md");
+    return { description, heading };
+}
+function stripQuotes(value) {
+    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+/**
+ * Discovers rules from the rules directory: each `<category>/<name>.md` file is a rule with id
+ * `<category>/<name>`. Categories are the directory names; no separate registration required.
+ */
+async function discoverRules(rulesRoot) {
+    const entries = await (0, promises_1.readdir)(rulesRoot, { withFileTypes: true });
+    const categories = entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .toSorted();
+    const rules = await Promise.all(categories.map(async (category) => {
+        const fileNames = await (0, promises_1.readdir)(node_path_1.default.join(rulesRoot, category));
+        const files = fileNames.filter((file) => file.endsWith(".md")).toSorted();
+        return await Promise.all(files.map(async (file) => {
+            const relativePath = node_path_1.default.join(category, file);
+            const content = await (0, promises_1.readFile)(node_path_1.default.join(rulesRoot, relativePath), "utf8");
+            const { description, heading } = parseRuleFile({ content, filePath: relativePath });
+            return {
+                category,
+                description,
+                heading,
+                id: `${category}/${node_path_1.default.basename(file, ".md")}`,
+                relativePath,
+            };
+        }));
+    }));
+    return rules.flat();
+}
+/**
+ * Resolves the rules to sync: profile categories expanded in order, plus includes, minus
+ * excludes. Unknown ids are reported (not fatal) so a stale `--include`/`--exclude` in a consuming
+ * repo degrades gracefully instead of breaking installs.
+ */
+function resolveRules(params) {
+    const { excludes, includes, profileCategories, rules } = params;
+    const rulesById = new Map(rules.map((rule) => [rule.id, rule]));
+    const unknownIds = [...includes, ...excludes].filter((id) => !rulesById.has(id));
+    const ruleIds = new Set([
+        ...profileCategories.flatMap((category) => rules.filter((rule) => rule.category === category).map((rule) => rule.id)),
+        ...includes.filter((id) => rulesById.has(id)),
+    ]);
+    for (const id of excludes) {
+        ruleIds.delete(id);
+    }
+    return {
+        rules: [...ruleIds].map((id) => rulesById.get(id)).filter((rule) => rule !== undefined),
+        unknownIds,
+    };
+}
+function generateAgentsIndex(rules) {
+    const rows = rules.map((rule) => `| ${rule.heading} | .rules/${toPosixPath(rule.relativePath)} | ${rule.description} |`);
+    return [
+        "<!-- Generated by @clipboard-health/ai-rules -->",
+        "",
+        "# Coding Rules",
+        "",
+        "IMPORTANT: You MUST read the relevant rule files below before writing or reviewing code.",
+        "",
+        "| Rule | File | When to Read |",
+        "|------|------|-------------|",
+        ...rows,
+        "",
+        "## Agent Skills",
+        "",
+        "Agent skills are linked from `node_modules/@clipboard-health/ai-rules` into `.agents/`.",
+        "If a referenced skill is missing or unreadable, run `npm ci` from the repository root and retry.",
+        "",
+    ].join("\n");
+}
+/**
+ * Generates the README "Available Rules" tables from rule frontmatter. A test asserts the README
+ * contains this exact content; run scripts/populateReadme.ts after changing rules.
+ */
+function generateReadmeRulesSection(rules) {
+    const uniqueCategories = [...new Set(rules.map((rule) => rule.category))];
+    const categories = uniqueCategories.toSorted();
+    const sections = categories.map((category) => {
+        const rows = rules
+            .filter((rule) => rule.category === category)
+            .map((rule) => `| \`${rule.id}\` | ${rule.description} |`);
+        return [`### ${category}`, "", "| Rule ID | When to Read |", "| --- | --- |", ...rows].join("\n");
+    });
+    return sections.join("\n\n");
+}
+function toPosixPath(filePath) {
+    return filePath.split(node_path_1.default.sep).join("/");
+}