@clipboard-health/ai-rules 2.26.0 → 2.28.0

package/scripts/sync.js

@@ -8,6 +8,7 @@ const promises_1 = require("node:fs/promises");
 const node_path_1 = __importDefault(require("node:path"));
 const constants_1 = require("./constants");
 const execAndLog_1 = require("./execAndLog");
+const rules_1 = require("./rules");
 const toErrorMessage_1 = require("./toErrorMessage");
 const PATHS = {
     projectRoot: node_path_1.default.join(__dirname, "../../../.."),
@@ -16,8 +17,18 @@ const PATHS = {
 async function sync() {
     try {
         const parsedArguments = parseArguments();
-        const ruleIds = resolveRuleIds(parsedArguments);
-        if (ruleIds.length === 0) {
+        const allRules = await (0, rules_1.discoverRules)(node_path_1.default.join(PATHS.packageRoot, "rules"));
+        const { rules, unknownIds } = (0, rules_1.resolveRules)({
+            rules: allRules,
+            profileCategories: constants_1.PROFILES[parsedArguments.profile].include,
+            includes: parsedArguments.extraIncludes,
+            excludes: parsedArguments.excludes,
+        });
+        if (unknownIds.length > 0) {
+            console.warn(`⚠️ Ignoring unknown rules: ${unknownIds.join(", ")}`);
+            console.warn(`Available rules: ${allRules.map((rule) => rule.id).join(", ")}`);
+        }
+        if (rules.length === 0) {
             console.error("❌ Error: No rules remaining after excludes");
             process.exit(1);
         }
@@ -31,16 +42,16 @@ async function sync() {
             (0, promises_1.rm)(libraryOutput, { recursive: true, force: true }),
         ]);
         const [, skillsSyncResult, librarySyncResult] = await Promise.all([
-            copyRuleFiles(ruleIds, rulesOutput),
+            copyRuleFiles(rules, rulesOutput),
             syncAgentDirectory("skills", skillsOutput),
             syncAgentDirectory("lib", libraryOutput),
             copySetupScript(),
             mergeSessionStartHook(),
         ]);
-        const agentsContent = await generateAgentsIndex(ruleIds);
+        const agentsContent = (0, rules_1.generateAgentsIndex)(rules);
         await (0, promises_1.writeFile)(node_path_1.default.join(PATHS.projectRoot, constants_1.FILES.agents), agentsContent, "utf8");
         await (0, promises_1.writeFile)(node_path_1.default.join(PATHS.projectRoot, constants_1.FILES.claude), "@AGENTS.md\n", "utf8");
-        console.log(`✅ @clipboard-health/ai-rules synced ${parsedArguments.profile} (${ruleIds.length} rules)`);
+        console.log(`✅ @clipboard-health/ai-rules synced ${parsedArguments.profile} (${rules.length} rules)`);
         await appendOverlay(PATHS.projectRoot);
         await formatOutputFiles(PATHS.projectRoot, {
             skillsCopied: skillsSyncResult === "copied",
@@ -53,9 +64,6 @@ async function sync() {
         process.exit(0);
     }
 }
-function isRuleId(value) {
-    return value in constants_1.RULE_FILES;
-}
 function isProfileName(value) {
     return value in constants_1.PROFILES;
 }
@@ -83,11 +91,6 @@ function parseArguments() {
             console.error(`❌ Error: Unexpected argument "${argument}"`);
             printUsageAndExit();
         }
-        else if (!isRuleId(argument)) {
-            console.error(`❌ Error: Unknown rule "${argument}"`);
-            console.error(`Available rules: ${Object.keys(constants_1.RULE_FILES).join(", ")}`);
-            process.exit(1);
-        }
         else if (mode === "include") {
             extraIncludes.push(argument);
         }
@@ -106,21 +109,11 @@ function printUsageAndExit() {
     console.error(`  node sync.js common --include backend/architecture`);
     process.exit(1);
 }
-function resolveRuleIds(parsedArguments) {
-    const { profile, extraIncludes, excludes } = parsedArguments;
-    const profileRules = constants_1.PROFILES[profile].include.flatMap((category) => constants_1.CATEGORIES[category]);
-    const ruleSet = new Set([...profileRules, ...extraIncludes]);
-    for (const ruleId of excludes) {
-        ruleSet.delete(ruleId);
-    }
-    return [...ruleSet];
-}
-async function copyRuleFiles(ruleIds, rulesOutput) {
-    await Promise.all(ruleIds.map(async (ruleId) => {
-        const rulePath = (0, constants_1.toRulePath)(ruleId);
-        const destination = node_path_1.default.join(rulesOutput, rulePath);
+async function copyRuleFiles(rules, rulesOutput) {
+    await Promise.all(rules.map(async (rule) => {
+        const destination = node_path_1.default.join(rulesOutput, rule.relativePath);
         await (0, promises_1.mkdir)(node_path_1.default.dirname(destination), { recursive: true });
-        await (0, promises_1.cp)(node_path_1.default.join(PATHS.packageRoot, "rules", rulePath), destination);
+        await (0, promises_1.cp)(node_path_1.default.join(PATHS.packageRoot, "rules", rule.relativePath), destination);
     }));
 }
 async function syncAgentDirectory(directoryName, destination) {
@@ -230,40 +223,6 @@ async function mergeSessionStartHook() {
     const action = hasStale || currentCount > 1 ? "Updated" : "Added";
     console.log(`📋 ${action} SessionStart hook in .claude/settings.json`);
 }
-async function extractHeading(filePath) {
-    try {
-        const content = await (0, promises_1.readFile)(filePath, "utf8");
-        const match = /^#\s+(?<heading>.+)$/m.exec(content);
-        return match?.groups?.["heading"] ?? node_path_1.default.basename(filePath, ".md");
-    }
-    catch {
-        return node_path_1.default.basename(filePath, ".md");
-    }
-}
-async function generateAgentsIndex(ruleIds) {
-    const rows = await Promise.all(ruleIds.map(async (ruleId) => {
-        const rulePath = (0, constants_1.toRulePath)(ruleId);
-        const heading = await extractHeading(node_path_1.default.join(PATHS.packageRoot, "rules", rulePath));
-        return `| ${heading} | .rules/${rulePath} | ${constants_1.RULE_FILES[ruleId]} |`;
-    }));
-    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");
-}
 async function appendOverlay(projectRoot) {
     const overlayPath = node_path_1.default.join(projectRoot, "OVERLAY.md");
     let overlayContent;

package/rules/frontend/bottomSheets.md

@@ -1,25 +0,0 @@
-# Bottom Sheets
-
-## Closing
-
-Every bottom sheet must include a close button in the top-right corner via `BottomSheetHeader`:
-
-```typescript
-<BottomSheet
-  modalState={modalState}
-  header={<BottomSheetHeader onClose={onClose} />}
->
-```
-
-## Component Structure
-
-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>`.
-
-An exception to this rule is if the bottom sheet itself is just presentational with no data fetching/mutations. Then it can just be one .tsx file.
-
-## Button Layout
-
-Buttons inside a bottom sheet must always stack vertically (never side by side). Use `<DialogFooter orientation="vertical">` or a vertical `<Stack>`.

package/rules/frontend/businessLogicPlacement.md

@@ -1,3 +0,0 @@
-# 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/errorHandling.md

@@ -1,39 +0,0 @@
-# Error Handling
-
-## Component Level
-
-```typescript
-export function DataComponent() {
-  const { data, isLoading, isError, refetch } = useGetData();
-
-  if (isLoading) return <LoadingState />;
-  if (isError) return <ErrorState onRetry={refetch} />;
-
-  return <DataDisplay data={data} />;
-}
-```
-
-## Mutation Level
-
-```typescript
-useMutation({
-  mutationFn: createItem,
-  onSuccess: () => showSuccessToast("Created"),
-  meta: {
-    logErrorMessage: APP_EVENTS.CREATE_FAILURE,
-    userErrorMessage: "Failed to create",
-  },
-});
-```
-
-## Validation
-
-```typescript
-try {
-  const validated = formSchema.parse(formData);
-} catch (error) {
-  if (error instanceof z.ZodError) {
-    error.errors.forEach((err) => showFieldError(err.path.join("."), err.message));
-  }
-}
-```

package/rules/frontend/frontendTechnologyStack.md

@@ -1,10 +0,0 @@
-# Frontend 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

package/rules/frontend/interactiveElements.md

@@ -1,19 +0,0 @@
-# Interactive Elements
-
-Never add `onClick` to `div` or `span`. Use:
-
-- `<button>` for actions
-- `<a>` (Link) for navigation
-- MUI interactive components (`Button`, `IconButton`, `ListItemButton`)
-
-This ensures proper accessibility: focus states, keyboard navigation, ARIA roles.
-
-## Keyboard Accessibility
-
-Every interactive element must be:
-
-- Tab focusable (proper tab order)
-- Visually indicated when focused (visible focus indicator)
-- Assigned appropriate ARIA roles
-- Equipped with keyboard event handling (Enter/Space for buttons, Enter for links)
-- Styled with pointer cursor

package/rules/frontend/modalRoutes.md

@@ -1,15 +0,0 @@
-# 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.

package/skills/flaky-test-bulk-debugger/SKILL.md

@@ -1,89 +0,0 @@
----
-name: flaky-test-bulk-debugger
-description: Bulk-triage flaky test investigation tickets by clustering sightings, sharing artifacts, and delegating per-cluster diagnosis to flaky-test-debugger. Use when investigating many flaky test tickets, Linear issues tagged flaky-investigation, CI flake bursts, or repeated failures that may share a root cause.
----
-
-# Flaky Test Bulk Debugger
-
-Use this skill to investigate a queue of flaky test sightings efficiently. Its purpose is orchestration: collect tickets, build a compact manifest, cluster related failures, fetch shared artifacts once, then run `flaky-test-debugger` per cluster.
-
-Do not duplicate the detailed diagnosis workflow from `flaky-test-debugger`. When a cluster is ready for root-cause analysis, use `flaky-test-debugger` in plan mode unless the user explicitly asks to implement fixes.
-
-## Rules
-
-- Treat bulky data as external artifacts. Save full issue descriptions, CI logs, LLM reports, Playwright traces, screenshots, and telemetry extracts to files; keep only manifests and summaries in conversation context.
-- Cluster before per-test debugging. Do not read each test file independently until shared setup, CI, auth, static asset, backend, or infrastructure failures have been ruled out.
-- Prefer one implementation ticket per root cause, not one per sighting.
-- Preserve the source ticket instructions for labels, status, linked issues, PR body requirements, and close-out comments.
-- If parallel workers are available, use them per cluster with minimal context. If not, process clusters serially and keep a running manifest file.
-- Keep the coordinator responsible for queue state, deduplication, and Linear/bookkeeping; keep cluster workers responsible for evidence and diagnosis.
-
-## Phase 1: Build Queue
-
-Fetch or receive all candidate tickets. For Linear, filter by the user-provided project/status/label, commonly `Todo` plus `flaky-investigation`.
-
-For each ticket, extract one manifest row: `issueId`, `repo`, `framework`, `testFile`, `testName`, `runUrl`, `commit`, `branch`, `shard`, `timestamp`, `firstError`, `firstStackFrame`, `priorTickets`, and `sourceInstructions`. Write full raw ticket data to a local artifact file if it is large.
-
-## Phase 2: Cluster
-
-Normalize errors before grouping:
-
-- Replace random IDs, emails, names, phone numbers, shift/facility IDs, UUIDs, ObjectIds, hashes, ports, and timestamps with placeholders.
-- Collapse generated asset filenames to their logical shape, for example `main-<hash>.<hash>.js`.
-- Keep HTTP status codes, helper names, route names, endpoint paths, and lifecycle stages intact.
-
-Cluster by strongest shared evidence first:
-
-1. Same CI run, commit, timestamp window, and setup/helper stack.
-2. Same failure surface from `flaky-test-debugger`: CI/job setup, test setup/auth/data, app bootstrap/navigation, user action, backend request, post-success render, assertion/locator.
-3. Same first project stack frame or setup helper.
-4. Same endpoint/static asset/status-code pattern.
-5. Same test file or prior related tickets.
-
-Do not merge clusters only because they are in the same run. Same-run failures can still have different root causes.
-
-## Phase 3: Fetch Artifacts
-
-For each unique CI run, fetch the available reports once and store them under a predictable temporary path. For Playwright LLM reports in Clipboard repos, use the repository helper when available:
-
-```bash
-bash scripts/fetch-llm-report.sh "<github-actions-url>"
-```
-
-Record artifact paths in the manifest. Workers should receive paths and the relevant manifest rows, not the full artifact contents.
-
-## Phase 4: Diagnose Clusters
-
-For each cluster, run `flaky-test-debugger` in plan mode. If the agent supports skills, explicitly load or invoke `flaky-test-debugger`; otherwise follow its workflow manually.
-
-Use this worker prompt shape:
-
-```text
-Use flaky-test-debugger in plan mode.
-Investigate this cluster as one possible shared root cause, not as isolated tickets.
-
-Inputs: cluster summary, manifest rows, artifact/report paths, prior related tickets, and source ticket close-out instructions.
-
-Return: final failure surface, evidence artifacts, root cause diagnosis, confidence score, whether one implementation ticket covers all issues, implementation plan or no-code disposition, and exact ticket action recommendation.
-```
-
-If confidence is below 5/5, the worker must include the observability or artifact changes needed to make the next occurrence diagnosable.
-
-## Phase 5: Act
-
-Merge worker outputs into a coordinator summary:
-
-- Cluster name and issue IDs
-- Shared vs independent root cause
-- Evidence level and confidence
-- Recommended implementation ticket count
-- Tickets to mark duplicate/no-code/human-needed
-- Remaining unknowns
-
-Create or recommend implementation tickets only after clustering. Link all investigation tickets covered by the same root cause, plus prior related tickets from the source descriptions.
-
-When updating investigation tickets, comment with the implementation ticket ID or no-code disposition, link related issues as requested, and move the ticket only after the comment/link exists.
-
-## Output Format
-
-End with a compact bulk triage report containing: queue size, cluster count, unique CI runs, each cluster's issue IDs, surface, recommendation, confidence, next ticket action, artifact index, and risks such as missing evidence or likely false merges.