@axiomatic-labs/claudeflow 2.13.17 → 2.13.19

package/lib/install.js

@@ -154,7 +154,7 @@ async function run() {
       copyDirSync(srcTemplates, dstTemplates);
     }
     materializeSharedAppendPrompt(cwd);
-    materializeDefaultClaudeMd(cwd);
+    ensureDefaultClaudeMdRules(cwd);
     propagateTemplateRules(cwd, srcTemplates);
 
     // Copy template agents (only template-managed, preserve user agents)
@@ -991,17 +991,74 @@ function materializeSharedAppendPrompt(projectRoot) {
   fs.copyFileSync(templatePath, outputPath);
 }
 
-// Materialize the default CLAUDE.md only when the project has none.
-// CLAUDE.md is user-owned: customizations made by the user (or by other
-// frameworks) must survive `claudeflow update`. We therefore never
-// overwrite an existing file.
-function materializeDefaultClaudeMd(projectRoot) {
+// Inject the canonical claudeflow rules block into the project's CLAUDE.md.
+//
+// Three cases:
+//   1. CLAUDE.md absent → create with the block plus user-content section
+//   2. CLAUDE.md present, no sentinel, no opt-out → prepend the block,
+//      preserving every byte of the existing file
+//   3. CLAUDE.md present with sentinel → replace the block in place
+//      (keeps future template revisions propagating idempotently)
+//
+// User opt-out: drop the literal string `claudeflow:default-rules:opt-out`
+// anywhere in CLAUDE.md (e.g. in a comment) to skip injection forever.
+//
+// The block is wrapped in HTML comments — markdown renders them invisibly
+// but they survive editor round-trips and remain machine-detectable.
+const CLAUDE_MD_INJECT_BEGIN = '<!-- claudeflow:default-rules:start (do not edit between markers) -->';
+const CLAUDE_MD_INJECT_END = '<!-- claudeflow:default-rules:end -->';
+const CLAUDE_MD_OPT_OUT = 'claudeflow:default-rules:opt-out';
+
+function buildDefaultRulesBlock(projectRoot) {
   const templatePath = path.join(projectRoot, DEFAULT_CLAUDE_MD_TEMPLATE);
-  if (!fs.existsSync(templatePath)) return false;
+  if (!fs.existsSync(templatePath)) return null;
+  let body = fs.readFileSync(templatePath, 'utf8');
+  // Strip the leading `# CLAUDE.md` heading — when injected into an existing
+  // file the heading would conflict with the user's own H1.
+  body = body.replace(/^\s*#\s*CLAUDE\.md\s*\r?\n+/, '').trimEnd();
+  return `${CLAUDE_MD_INJECT_BEGIN}\n${body}\n${CLAUDE_MD_INJECT_END}`;
+}
+
+function ensureDefaultClaudeMdRules(projectRoot) {
+  const block = buildDefaultRulesBlock(projectRoot);
+  if (!block) return { action: 'no-template' };
+
   const outputPath = path.join(projectRoot, DEFAULT_CLAUDE_MD_OUTPUT);
-  if (fs.existsSync(outputPath)) return false;
-  fs.copyFileSync(templatePath, outputPath);
-  return true;
+
+  if (!fs.existsSync(outputPath)) {
+    fs.writeFileSync(outputPath, `${block}\n`);
+    return { action: 'created' };
+  }
+
+  const existing = fs.readFileSync(outputPath, 'utf8');
+
+  if (existing.includes(CLAUDE_MD_OPT_OUT)) {
+    return { action: 'opt-out' };
+  }
+
+  // The block always lives at the bottom. Two paths get us there:
+  //   - sentinels found at the bottom and content current → unchanged
+  //   - sentinels found anywhere else (top, middle, stale content) →
+  //     remove the old block and append a fresh one at the tail.
+  //   - sentinels absent → append for the first time.
+  const beginIdx = existing.indexOf(CLAUDE_MD_INJECT_BEGIN);
+  const endIdx = existing.indexOf(CLAUDE_MD_INJECT_END);
+  let userContent;
+  if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
+    const before = existing.slice(0, beginIdx);
+    const after = existing.slice(endIdx + CLAUDE_MD_INJECT_END.length);
+    userContent = `${before.replace(/\s+$/, '')}${after.startsWith('\n') ? '' : '\n'}${after}`.replace(/^\s+/, '').replace(/\s+$/, '');
+  } else {
+    userContent = existing.replace(/\s+$/, '');
+  }
+
+  const next = userContent.length === 0
+    ? `${block}\n`
+    : `${userContent}\n\n${block}\n`;
+
+  if (next === existing) return { action: 'unchanged' };
+  fs.writeFileSync(outputPath, next);
+  return { action: beginIdx !== -1 ? 'updated' : 'injected' };
 }
 
 function isTemplateManagedAgent(agentName) {
@@ -1036,7 +1093,11 @@ function copyDirSync(src, dst, skipNames) {
 module.exports = Object.assign(run, {
   assertRequiredTemplateRules,
   materializeSharedAppendPrompt,
-  materializeDefaultClaudeMd,
+  ensureDefaultClaudeMdRules,
+  buildDefaultRulesBlock,
+  CLAUDE_MD_INJECT_BEGIN,
+  CLAUDE_MD_INJECT_END,
+  CLAUDE_MD_OPT_OUT,
   isTemplateManagedAgent,
   listTemplateManagedAgents,
   mergeClaudeSettings,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiomatic-labs/claudeflow",
-  "version": "2.13.17",
+  "version": "2.13.19",
   "description": "Claudeflow — AI-powered development toolkit for Claude Code. Skills, agents, hooks, and quality gates that ship production apps.",
   "bin": {
     "claudeflow": "./bin/cli.js"