compose-agentsmd 3.2.6 → 3.3.0

package/README.md

@@ -32,9 +32,13 @@ compose-agentsmd
 
 The tool reads `agent-ruleset.json` from the given root directory (default: current working directory), and writes the output file specified by the ruleset. If `output` is omitted, it defaults to `AGENTS.md`.
 
+By default, compose also writes a `CLAUDE.md` companion file containing an `@...` import pointing to the primary output file. You can disable this with `claude.enabled: false` in the ruleset.
+
 The tool prepends a small "Tool Rules" block to every generated `AGENTS.md` so agents know how to regenerate or update rules.
 Each composed rule section is also prefixed with the source file path that produced it.
 
+When the output file is `AGENTS.md`, the CLI also prints a unified diff for `AGENTS.md` when it changes (and prints `AGENTS.md unchanged.` when it does not). This works even when the project is not under git. `--quiet` and `--json` suppress this output.
+
 ## Setup (init)
 
 For a project that does not have a ruleset yet, bootstrap one with `init`:
@@ -49,6 +53,7 @@ Defaults:
 - `domains`: empty
 - `extra`: empty
 - `global`: omitted (defaults to `true`)
+- `claude`: `{ "enabled": true, "output": "CLAUDE.md" }`
 - `output`: `AGENTS.md`
 
 Use `--dry-run` to preview actions, `--force` to overwrite existing files, and `--compose` to generate `AGENTS.md` immediately.
@@ -82,6 +87,11 @@ Ruleset files accept JSON with `//` or `/* */` comments.
   "domains": ["node", "unreal"],
   // Additional local rule files to append.
   "extra": ["agent-rules-local/custom.md"],
+  // Optional Claude Code companion output.
+  "claude": {
+    "enabled": true,
+    "output": "CLAUDE.md"
+  },
   // Output file name.
   "output": "AGENTS.md"
 }
@@ -93,6 +103,9 @@ Ruleset keys:
 - `global` (optional): include `rules/global` (defaults to true). Omit this unless you want to disable globals.
 - `domains` (optional): domain folders under `rules/domains/<domain>`.
 - `extra` (optional): additional local rule files to append.
+- `claude` (optional): companion settings for Claude Code.
+- `claude.enabled` (optional): enable/disable companion generation (defaults to `true`).
+- `claude.output` (optional): companion file path (defaults to `CLAUDE.md`).
 - `output` (optional): output file name (defaults to `AGENTS.md`).
 
 ### Ruleset schema validation
@@ -119,7 +132,7 @@ Remote sources are cached under `~/.agentsmd/cache/<owner>/<repo>/<ref>/`. Use `
 - `--no-domains`: initialize with no domains
 - `--no-extra`: initialize without extra rule files
 - `--no-global`: initialize without global rules
-- `--compose`: compose `AGENTS.md` after `init`
+- `--compose`: compose output file(s) after `init`
 - `--dry-run`: show init plan without writing files
 - `--yes`: skip init confirmation prompt
 - `--force`: overwrite existing files during init

package/agent-ruleset.schema.json

@@ -16,6 +16,19 @@
       "type": "string",
       "minLength": 1
     },
+    "claude": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "output": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
     "domains": {
       "type": "array",
       "items": {

package/dist/compose-agents.js

@@ -5,8 +5,10 @@ import os from "node:os";
 import { execFileSync } from "node:child_process";
 import readline from "node:readline";
 import { Ajv } from "ajv";
+import { createTwoFilesPatch } from "diff";
 const DEFAULT_RULESET_NAME = "agent-ruleset.json";
 const DEFAULT_OUTPUT = "AGENTS.md";
+const DEFAULT_CLAUDE_OUTPUT = "CLAUDE.md";
 const DEFAULT_CACHE_ROOT = path.join(os.homedir(), ".agentsmd", "cache");
 const DEFAULT_WORKSPACE_ROOT = path.join(os.homedir(), ".agentsmd", "workspace");
 const DEFAULT_INIT_SOURCE = "github:owner/repo@latest";
@@ -275,6 +277,15 @@ const readProjectRuleset = (rulesetPath) => {
     if (ruleset.output === undefined) {
         ruleset.output = DEFAULT_OUTPUT;
     }
+    if (ruleset.claude === undefined) {
+        ruleset.claude = {};
+    }
+    if (ruleset.claude.enabled === undefined) {
+        ruleset.claude.enabled = true;
+    }
+    if (ruleset.claude.output === undefined) {
+        ruleset.claude.output = DEFAULT_CLAUDE_OUTPUT;
+    }
     if (ruleset.global === undefined) {
         ruleset.global = true;
     }
@@ -515,11 +526,25 @@ const formatRuleSourcePath = (rulePath, rulesRoot, rulesetDir, source, resolvedR
     const result = normalizePath(path.relative(rulesetDir, rulePath));
     return result;
 };
+const resolveOutputPaths = (rulesetDir, projectRuleset) => {
+    const primaryOutputPath = resolveFrom(rulesetDir, projectRuleset.output ?? DEFAULT_OUTPUT);
+    const claude = projectRuleset.claude ?? {};
+    const companionEnabled = claude.enabled !== false;
+    const configuredCompanionPath = resolveFrom(rulesetDir, claude.output ?? DEFAULT_CLAUDE_OUTPUT);
+    if (!companionEnabled || path.resolve(primaryOutputPath) === path.resolve(configuredCompanionPath)) {
+        return { primaryOutputPath };
+    }
+    return { primaryOutputPath, companionOutputPath: configuredCompanionPath };
+};
+const buildClaudeCompanionContent = (primaryOutputPath, companionOutputPath) => {
+    const relativeImportPath = normalizePath(path.relative(path.dirname(companionOutputPath), primaryOutputPath));
+    return `@${relativeImportPath}\n`;
+};
 const composeRuleset = (rulesetPath, rootDir, options) => {
     const rulesetDir = path.dirname(rulesetPath);
     const projectRuleset = readProjectRuleset(rulesetPath);
-    const outputFileName = projectRuleset.output ?? DEFAULT_OUTPUT;
-    const outputPath = resolveFrom(rulesetDir, outputFileName);
+    const { primaryOutputPath, companionOutputPath } = resolveOutputPaths(rulesetDir, projectRuleset);
+    const composedOutputPath = normalizePath(path.relative(rootDir, primaryOutputPath));
     const { rulesRoot, resolvedRef } = resolveRulesRoot(rulesetDir, projectRuleset.source, options.refresh ?? false);
     const globalRoot = path.join(rulesRoot, "global");
     const domainsRoot = path.join(rulesRoot, "domains");
@@ -543,12 +568,63 @@ const composeRuleset = (rulesetPath, rootDir, options) => {
     });
     const lintHeader = "<!-- markdownlint-disable MD025 -->";
     const toolRules = normalizeTrailingWhitespace(TOOL_RULES);
-    const output = `${lintHeader}\n${[toolRules, ...parts].join("\n\n")}\n`;
+    const primaryOutputContent = `${lintHeader}\n${[toolRules, ...parts].join("\n\n")}\n`;
+    const composedFiles = [
+        {
+            absolutePath: primaryOutputPath,
+            relativePath: composedOutputPath,
+            content: primaryOutputContent
+        }
+    ];
+    if (companionOutputPath) {
+        composedFiles.push({
+            absolutePath: companionOutputPath,
+            relativePath: normalizePath(path.relative(rootDir, companionOutputPath)),
+            content: buildClaudeCompanionContent(primaryOutputPath, companionOutputPath)
+        });
+    }
+    let agentsMdDiff;
+    if (options.emitAgentsMdDiff && path.basename(primaryOutputPath) === DEFAULT_OUTPUT) {
+        const before = fs.existsSync(primaryOutputPath) ? fs.readFileSync(primaryOutputPath, "utf8") : "";
+        if (before === primaryOutputContent) {
+            agentsMdDiff = { status: "unchanged" };
+        }
+        else {
+            agentsMdDiff = {
+                status: "updated",
+                patch: createTwoFilesPatch(`a/${composedOutputPath}`, `b/${composedOutputPath}`, before, primaryOutputContent, "", "", { context: 3 })
+            };
+        }
+    }
     if (!options.dryRun) {
-        fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-        fs.writeFileSync(outputPath, output, "utf8");
+        for (const file of composedFiles) {
+            fs.mkdirSync(path.dirname(file.absolutePath), { recursive: true });
+            fs.writeFileSync(file.absolutePath, file.content, "utf8");
+        }
     }
-    return normalizePath(path.relative(rootDir, outputPath));
+    return {
+        output: composedOutputPath,
+        outputs: composedFiles.map((file) => file.relativePath),
+        agentsMdDiff
+    };
+};
+const printAgentsMdDiffIfPresent = (result) => {
+    if (!result.agentsMdDiff) {
+        return;
+    }
+    if (result.agentsMdDiff.status === "unchanged") {
+        process.stdout.write("AGENTS.md unchanged.\n");
+        return;
+    }
+    process.stdout.write("AGENTS.md updated. ACTION (agent): refresh rule recognition from the diff below.\n");
+    process.stdout.write("--- BEGIN DIFF ---\n");
+    if (result.agentsMdDiff.patch) {
+        process.stdout.write(result.agentsMdDiff.patch);
+        if (!result.agentsMdDiff.patch.endsWith("\n")) {
+            process.stdout.write("\n");
+        }
+    }
+    process.stdout.write("--- END DIFF ---\n");
 };
 const LOCAL_RULES_TEMPLATE = "# Local Rules\n\n- Add project-specific instructions here.\n";
 const buildInitRuleset = (args) => {
@@ -556,7 +632,11 @@ const buildInitRuleset = (args) => {
     const extra = normalizeListOption(args.extra, "--extra");
     const ruleset = {
         source: args.source ?? DEFAULT_INIT_SOURCE,
-        output: args.output ?? DEFAULT_OUTPUT
+        output: args.output ?? DEFAULT_OUTPUT,
+        claude: {
+            enabled: true,
+            output: DEFAULT_CLAUDE_OUTPUT
+        }
     };
     if (args.global === false) {
         ruleset.global = false;
@@ -574,6 +654,8 @@ const buildInitRuleset = (args) => {
 const formatInitRuleset = (ruleset) => {
     const domainsValue = JSON.stringify(ruleset.domains ?? []);
     const extraValue = JSON.stringify(ruleset.extra ?? []);
+    const claudeEnabled = ruleset.claude?.enabled ?? true;
+    const claudeOutput = ruleset.claude?.output ?? DEFAULT_CLAUDE_OUTPUT;
     const lines = [
         "{",
         '  // Rules source. Use github:owner/repo@ref or a local path.',
@@ -587,6 +669,11 @@ const formatInitRuleset = (ruleset) => {
         lines.push('  // Include rules/global from the source.');
         lines.push('  "global": false,');
     }
+    lines.push('  // Claude Code companion output settings.');
+    lines.push('  "claude": {');
+    lines.push(`    "enabled": ${claudeEnabled ? "true" : "false"},`);
+    lines.push(`    "output": "${claudeOutput}"`);
+    lines.push("  },");
     lines.push('  // Output file name.');
     lines.push(`  "output": "${ruleset.output ?? DEFAULT_OUTPUT}"`);
     lines.push("}");
@@ -616,7 +703,7 @@ const initProject = async (args, rootDir, rulesetName) => {
     const rulesetPath = args.ruleset ? resolveFrom(rootDir, args.ruleset) : path.join(rootDir, rulesetName);
     const rulesetDir = path.dirname(rulesetPath);
     const ruleset = buildInitRuleset(args);
-    const outputPath = resolveFrom(rulesetDir, ruleset.output ?? DEFAULT_OUTPUT);
+    const outputPaths = resolveOutputPaths(rulesetDir, ruleset);
     const plan = [];
     if (fs.existsSync(rulesetPath)) {
         if (!args.force) {
@@ -641,14 +728,20 @@ const initProject = async (args, rootDir, rulesetName) => {
         extraToWrite.push(extraPath);
     }
     if (args.compose) {
-        if (fs.existsSync(outputPath)) {
-            if (!args.force) {
-                throw new Error(`Output already exists: ${normalizePath(outputPath)} (use --force to overwrite)`);
+        const composedTargets = [outputPaths.primaryOutputPath];
+        if (outputPaths.companionOutputPath) {
+            composedTargets.push(outputPaths.companionOutputPath);
+        }
+        for (const composedTarget of composedTargets) {
+            if (fs.existsSync(composedTarget)) {
+                if (!args.force) {
+                    throw new Error(`Output already exists: ${normalizePath(composedTarget)} (use --force to overwrite)`);
+                }
+                plan.push({ action: "overwrite", path: composedTarget });
+            }
+            else {
+                plan.push({ action: "create", path: composedTarget });
             }
-            plan.push({ action: "overwrite", path: outputPath });
-        }
-        else {
-            plan.push({ action: "create", path: outputPath });
         }
     }
     if (!args.quiet && !args.json) {
@@ -678,13 +771,16 @@ const initProject = async (args, rootDir, rulesetName) => {
     }
     let composedOutput;
     if (args.compose) {
-        composedOutput = composeRuleset(rulesetPath, rootDir, { refresh: args.refresh ?? false });
+        composedOutput = composeRuleset(rulesetPath, rootDir, {
+            refresh: args.refresh ?? false,
+            emitAgentsMdDiff: !args.quiet && !args.json
+        });
     }
     if (args.json) {
         process.stdout.write(JSON.stringify({
             initialized: [normalizePath(path.relative(rootDir, rulesetPath))],
             localRules: extraToWrite.map((filePath) => normalizePath(path.relative(rootDir, filePath))),
-            composed: composedOutput ? [composedOutput] : [],
+            composed: composedOutput ? composedOutput.outputs : [],
             dryRun: false
         }, null, 2) + "\n");
     }
@@ -696,7 +792,8 @@ const initProject = async (args, rootDir, rulesetName) => {
                 .join("\n")}\n`);
         }
         if (composedOutput) {
-            process.stdout.write(`Composed AGENTS.md:\n- ${composedOutput}\n`);
+            process.stdout.write(`Composed AGENTS.md:\n${composedOutput.outputs.map((filePath) => `- ${filePath}`).join("\n")}\n`);
+            printAgentsMdDiffIfPresent(composedOutput);
         }
     }
 };
@@ -777,12 +874,17 @@ const main = async () => {
         const rulesetDir = path.dirname(rulesetPath);
         const ruleset = readProjectRuleset(rulesetPath);
         applyRulesFromWorkspace(rulesetDir, ruleset.source);
-        const output = composeRuleset(rulesetPath, rootDir, { refresh: true, dryRun: args.dryRun });
+        const output = composeRuleset(rulesetPath, rootDir, {
+            refresh: true,
+            dryRun: args.dryRun,
+            emitAgentsMdDiff: !args.quiet && !args.json
+        });
         if (args.json) {
-            process.stdout.write(JSON.stringify({ composed: [output], dryRun: !!args.dryRun }, null, 2) + "\n");
+            process.stdout.write(JSON.stringify({ composed: output.outputs, dryRun: !!args.dryRun }, null, 2) + "\n");
         }
         else if (!args.quiet) {
-            process.stdout.write(`Composed AGENTS.md:\n- ${output}\n`);
+            process.stdout.write(`Composed AGENTS.md:\n${output.outputs.map((filePath) => `- ${filePath}`).join("\n")}\n`);
+            printAgentsMdDiffIfPresent(output);
         }
         return;
     }
@@ -792,12 +894,19 @@ const main = async () => {
     }
     const outputs = rulesetFiles
         .sort()
-        .map((rulesetPath) => composeRuleset(rulesetPath, rootDir, { refresh: args.refresh, dryRun: args.dryRun }));
+        .map((rulesetPath) => composeRuleset(rulesetPath, rootDir, {
+        refresh: args.refresh,
+        dryRun: args.dryRun,
+        emitAgentsMdDiff: !args.quiet && !args.json
+    }));
     if (args.json) {
-        process.stdout.write(JSON.stringify({ composed: outputs, dryRun: !!args.dryRun }, null, 2) + "\n");
+        process.stdout.write(JSON.stringify({ composed: outputs.flatMap((result) => result.outputs), dryRun: !!args.dryRun }, null, 2) + "\n");
     }
     else if (!args.quiet) {
-        process.stdout.write(`Composed AGENTS.md:\n${outputs.map((file) => `- ${file}`).join("\n")}\n`);
+        process.stdout.write(`Composed AGENTS.md:\n${outputs.flatMap((result) => result.outputs).map((filePath) => `- ${filePath}`).join("\n")}\n`);
+        for (const result of outputs) {
+            printAgentsMdDiffIfPresent(result);
+        }
     }
 };
 const run = async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compose-agentsmd",
-  "version": "3.2.6",
+  "version": "3.3.0",
   "description": "CLI tools for composing per-project AGENTS.md files from modular rule sets",
   "license": "MIT",
   "repository": {
@@ -48,6 +48,7 @@
     "typescript": "^5.7.3"
   },
   "dependencies": {
-    "ajv": "^8.17.1"
+    "ajv": "^8.17.1",
+    "diff": "^8.0.3"
   }
 }

package/tools/usage.txt

@@ -16,7 +16,7 @@ Options:
   --no-domains         Initialize with no domains
   --no-extra           Initialize without extra rule files
   --no-global          Initialize without global rules
-  --compose            Compose AGENTS.md after init
+  --compose            Compose output file(s) after init
   --dry-run            Show init plan without writing files
   --yes                Skip init confirmation prompt
   --force              Overwrite existing files during init