@clipboard-health/ai-rules 2.23.0 → 2.23.1

package/README.md

@@ -1,6 +1,6 @@
 # @clipboard-health/ai-rules
 
-Pre-built AI agent rules for consistent coding standards. Uses a retrieval-based approach: generates a compressed index in `AGENTS.md` pointing to individual rule files that agents read on demand.
+Pre-built AI agent rules for consistent coding standards. Uses a retrieval-based approach: generates a compressed index in `AGENTS.md` pointing to copied `.rules/` files that agents read on demand, with `.agents/` linked to package-provided agent assets.
 
 ## Table of contents
 
@@ -55,7 +55,7 @@ npm install --save-dev @clipboard-health/ai-rules
 5. Commit the generated files:
 
    ```bash
-   git add .rules/ AGENTS.md CLAUDE.md
+   git add .rules/ .agents/ AGENTS.md CLAUDE.md
    git commit -m "feat: add AI coding rules"
    ```
 
@@ -96,10 +96,10 @@ npm update @clipboard-health/ai-rules
 npm install
 
 # Review the changes
-git diff .rules/ AGENTS.md
+git diff .rules/ .agents/ AGENTS.md
 
 # Commit the updates
-git add .rules/ AGENTS.md CLAUDE.md
+git add .rules/ .agents/ AGENTS.md CLAUDE.md
 git commit -m "chore: update AI coding rules"
 ```
 
@@ -170,10 +170,10 @@ v2 replaces the monolithic `AGENTS.md` with a retrieval-based approach. Rule fil
    npm install
    ```
 
-3. Add `.rules/` to git and commit:
+3. Add `.rules/` and `.agents/` to git and commit:
 
    ```bash
-   git add .rules/ AGENTS.md CLAUDE.md
+   git add .rules/ .agents/ AGENTS.md CLAUDE.md
    git commit -m "feat!: update ai-rules to v2 retrieval-based approach"
    ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/ai-rules",
-  "version": "2.23.0",
+  "version": "2.23.1",
   "description": "Pre-built AI agent rules for consistent coding standards.",
   "keywords": [
     "ai",

package/scripts/sync.js

@@ -30,10 +30,10 @@ async function sync() {
             (0, promises_1.rm)(skillsOutput, { recursive: true, force: true }),
             (0, promises_1.rm)(libraryOutput, { recursive: true, force: true }),
         ]);
-        const [, skillsCopied, libraryCopied] = await Promise.all([
+        const [, skillsSyncResult, librarySyncResult] = await Promise.all([
             copyRuleFiles(ruleIds, rulesOutput),
-            copySkillFiles(skillsOutput),
-            copyLibraryFiles(libraryOutput),
+            syncAgentDirectory("skills", skillsOutput),
+            syncAgentDirectory("lib", libraryOutput),
             copySetupScript(),
             mergeSessionStartHook(),
         ]);
@@ -42,7 +42,10 @@ async function sync() {
         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)`);
         await appendOverlay(PATHS.projectRoot);
-        await formatOutputFiles(PATHS.projectRoot, { skillsCopied, libCopied: libraryCopied });
+        await formatOutputFiles(PATHS.projectRoot, {
+            skillsCopied: skillsSyncResult === "copied",
+            libCopied: librarySyncResult === "copied",
+        });
     }
     catch (error) {
         // Log error but exit gracefully to avoid breaking installs
@@ -120,33 +123,42 @@ async function copyRuleFiles(ruleIds, rulesOutput) {
         await (0, promises_1.cp)(node_path_1.default.join(PATHS.packageRoot, "rules", rulePath), destination);
     }));
 }
-async function copySkillFiles(skillsOutput) {
-    const skillsSource = node_path_1.default.join(PATHS.packageRoot, "skills");
+async function syncAgentDirectory(directoryName, destination) {
+    const source = await resolveAgentDirectorySource(directoryName);
+    if (!source) {
+        return "missing";
+    }
+    await (0, promises_1.mkdir)(node_path_1.default.dirname(destination), { recursive: true });
+    const relativeSource = node_path_1.default.relative(node_path_1.default.dirname(destination), source);
     try {
-        await (0, promises_1.cp)(skillsSource, skillsOutput, { recursive: true });
-        console.log(`📋 Synced skills to .agents/skills/`);
-        return true;
+        await (0, promises_1.symlink)(relativeSource, destination, "dir");
+        console.log(`📋 Linked ${directoryName} to .agents/${directoryName}/`);
+        return "linked";
     }
     catch (error) {
-        if (error.code === "ENOENT") {
-            return false;
-        }
-        throw error;
+        console.warn(`⚠️ Could not symlink ${directoryName}; copying instead: ${(0, toErrorMessage_1.toErrorMessage)(error)}`);
+        await (0, promises_1.cp)(source, destination, { recursive: true });
+        console.log(`📋 Synced ${directoryName} to .agents/${directoryName}/`);
+        return "copied";
     }
 }
-async function copyLibraryFiles(libraryOutput) {
-    const librarySource = node_path_1.default.join(PATHS.packageRoot, "lib");
-    try {
-        await (0, promises_1.cp)(librarySource, libraryOutput, { recursive: true });
-        console.log(`📋 Synced lib to .agents/lib/`);
-        return true;
+async function resolveAgentDirectorySource(directoryName) {
+    const packageSource = node_path_1.default.join(PATHS.packageRoot, directoryName);
+    const sourceTreeSource = node_path_1.default.join(PATHS.projectRoot, "plugins", "core", directoryName);
+    // This repo runs the built sync script from dist/, but checked-in links should
+    // target source assets rather than ignored build output.
+    if (isSourceBuildPackage() && (await fileExists(sourceTreeSource))) {
+        return sourceTreeSource;
     }
-    catch (error) {
-        if (error.code === "ENOENT") {
-            return false;
-        }
-        throw error;
+    if (await fileExists(packageSource)) {
+        return packageSource;
     }
+    return undefined;
+}
+function isSourceBuildPackage() {
+    return node_path_1.default
+        .normalize(PATHS.packageRoot)
+        .endsWith(node_path_1.default.normalize(node_path_1.default.join("dist", "packages", "ai-rules")));
 }
 async function copySetupScript() {
     const source = node_path_1.default.join(PATHS.packageRoot, "scripts", "setup.sh");
@@ -245,6 +257,11 @@ async function generateAgentsIndex(ruleIds) {
         "|------|------|-------------|",
         ...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) {