@vuau/agent-memory 0.5.5 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @vuau/agent-memory
 
-Structured AI memory for codebases. Works with GitHub Copilot, Cursor, Windsurf, and any AI coding assistant that reads markdown files.
+Structured AI memory for codebases. Works with GitHub Copilot, Cursor, Windsurf, Claude Code, OpenCode, and any AI coding assistant that reads markdown files.
 
 **[Tiếng Việt →](./README.vi.md)**
 
@@ -18,7 +18,8 @@ npx @vuau/agent-memory init
 
 ```
 / (Project Root)
-├── AGENTS.md                    # Fixed router (managed by package)
+├── AGENTS.md                    # Copilot, Cursor, Windsurf, OpenCode …
+├── CLAUDE.md                    # Claude Code (symlink → AGENTS.md on macOS/Linux)
 └── .agents/
     ├── CUSTOM.md                # Project-specific rules & spec mapping
     ├── MEMORY.md                # Long-term memory (decisions, patterns)
@@ -29,15 +30,15 @@ npx @vuau/agent-memory init
 ## How It Works
 
 1. **You run `init`** → Creates the structure. `AGENTS.md` points to `.agents/CUSTOM.md`.
-2. **Agent reads rules** → Follows the priority: CUSTOM.md > AGENTS.md > spec files.
+2. **Agent reads rules** → Follows the priority: CUSTOM.md > AGENTS/CLAUDE.md > spec files.
 3. **Agent works** → Updates MEMORY.md for decisions and TASKS.md for progress.
-4. **Update package** → Run `agent-memory update` to get the latest `AGENTS.md` router without losing your custom rules.
+4. **Update package** → Run `agent-memory update` to get the latest router files without losing your custom rules.
 
 ## CLI Commands
 
 ```bash
 npx @vuau/agent-memory init      # Scaffold .agents/ structure
-npx @vuau/agent-memory update    # Update AGENTS.md router to latest version
+npx @vuau/agent-memory update    # Update router files (AGENTS.md, CLAUDE.md) to latest version
 npx @vuau/agent-memory doctor    # Validate structure integrity
 npx @vuau/agent-memory help      # Show help
 ```
@@ -46,8 +47,12 @@ npx @vuau/agent-memory help      # Show help
 
 ### The Router Split
 
-- **AGENTS.md**: Core router managed by the package. Do not edit this file directly as it may be overwritten.
-- **.agents/CUSTOM.md**: Your project's home for custom rules, architectural decisions, and documentation mapping.
+- **`AGENTS.md`** — For GitHub Copilot, Cursor, Windsurf, OpenCode, and general AI coding assistants.
+  Read by: Copilot (`.github/copilot-instructions.md` instructions point here), Cursor (`@AGENTS.md`), Windsurf (`.windsurfrules` references).
+- **`CLAUDE.md`** — For Claude Code exclusively.
+  On macOS/Linux it's a **symlink to `AGENTS.md`** so content is always in sync.
+  On Windows it's a **hook file** that tells Claude Code to read `AGENTS.md`.
+- **`.agents/CUSTOM.md`** — Your project's home for custom rules, architectural decisions, and documentation mapping.
 
 ### Memory Files
 

package/README.vi.md

@@ -1,6 +1,6 @@
 # @vuau/agent-memory
 
-Bộ nhớ AI có cấu trúc cho các codebase. Hoạt động với GitHub Copilot, Cursor, Windsurf, và bất kỳ AI coding assistant nào đọc markdown files.
+Bộ nhớ AI có cấu trúc cho các codebase. Hoạt động với GitHub Copilot, Cursor, Windsurf, Claude Code, OpenCode, và bất kỳ AI coding assistant nào đọc markdown files.
 
 **[English →](./README.md)**
 
@@ -18,7 +18,8 @@ npx @vuau/agent-memory init
 
 ```
 / (Project Root)
-├── AGENTS.md                    # Router cố định (quản lý bởi package)
+├── AGENTS.md                    # Copilot, Cursor, Windsurf, OpenCode …
+├── CLAUDE.md                    # Claude Code (symlink → AGENTS.md trên macOS/Linux)
 └── .agents/
     ├── CUSTOM.md                # Rules riêng của project & mapping tài liệu
     ├── MEMORY.md                # Bộ nhớ dài hạn (quyết định, patterns)
@@ -29,15 +30,15 @@ npx @vuau/agent-memory init
 ## Cách hoạt động
 
 1. **Bạn chạy `init`** → Tạo cấu trúc thư mục. `AGENTS.md` sẽ trỏ đến `.agents/CUSTOM.md`.
-2. **Agent đọc rules** → Tuân theo ưu tiên: CUSTOM.md > AGENTS.md > spec files.
+2. **Agent đọc rules** → Tuân theo ưu tiên: CUSTOM.md > AGENTS/CLAUDE.md > spec files.
 3. **Agent làm việc** → Cập nhật MEMORY.md cho các quyết định và TASKS.md cho tiến độ công việc.
-4. **Cập nhật package** → Chạy `agent-memory update` để nhận router `AGENTS.md` mới nhất mà không mất các rules tùy chỉnh của bạn.
+4. **Cập nhật package** → Chạy `agent-memory update` để nhận các router files mới nhất mà không mất rules tùy chỉnh của bạn.
 
 ## Các lệnh CLI
 
 ```bash
 npx @vuau/agent-memory init      # Khởi tạo cấu trúc .agents/
-npx @vuau/agent-memory update    # Cập nhật router AGENTS.md lên bản mới nhất
+npx @vuau/agent-memory update    # Cập nhật router files (AGENTS.md, CLAUDE.md) lên bản mới nhất
 npx @vuau/agent-memory doctor    # Kiểm tra tính toàn vẹn của cấu trúc
 npx @vuau/agent-memory help      # Hiện trợ giúp
 ```
@@ -46,8 +47,12 @@ npx @vuau/agent-memory help      # Hiện trợ giúp
 
 ### Phân tách Router
 
-- **AGENTS.md**: Router cốt lõi được quản lý bởi thư viện. Không sửa file này trực tiếp vì nó có thể bị ghi đè khi update.
-- **.agents/CUSTOM.md**: Nơi dành riêng cho dự án của bạn để viết custom rules, quyết định kiến trúc và mapping tài liệu.
+- **`AGENTS.md`** — Dành cho GitHub Copilot, Cursor, Windsurf, OpenCode, và các AI coding assistants thông thường.
+  Cách đọc: Copilot (chỉ định trong `.github/copilot-instructions.md`), Cursor (`@AGENTS.md`), Windsurf (tham chiếu trong `.windsurfrules`).
+- **`CLAUDE.md`** — Riêng cho Claude Code.
+  Trên macOS/Linux: **symlink đến `AGENTS.md`** để luôn đồng bộ.
+  Trên Windows: **hook file** yêu cầu Claude Code đọc `AGENTS.md`.
+- **`.agents/CUSTOM.md`** — Nơi dành riêng cho dự án của bạn để viết custom rules, quyết định kiến trúc và mapping tài liệu.
 
 ### Các file bộ nhớ
 

package/dist/bin/cli.js

@@ -5,9 +5,10 @@ import { existsSync as existsSync3 } from "fs";
 import { join as join3 } from "path";
 
 // src/scaffold.ts
-import { existsSync, mkdirSync, writeFileSync, readFileSync } from "fs";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, symlinkSync, lstatSync, unlinkSync } from "fs";
 import { join, resolve, dirname } from "path";
 import { fileURLToPath } from "url";
+import { platform } from "os";
 
 // src/types.ts
 var AGENTS_DIR = ".agents";
@@ -17,6 +18,7 @@ var MEMORY_DETAIL_FILE = ".agents/MEMORY-DETAIL.md";
 var TASKS_FILE = ".agents/TASKS.md";
 var CUSTOM_FILE = ".agents/CUSTOM.md";
 var AGENTS_MD = "AGENTS.md";
+var CLAUDE_MD = "CLAUDE.md";
 
 // src/scaffold.ts
 function getTemplatesDir() {
@@ -93,6 +95,7 @@ function scaffold(projectDir, options = {}) {
     result,
     force
   );
+  writeClaudeMd(projectDir, vars, result, force);
   return result;
 }
 function writeFileIfNeeded(targetPath, content, displayName, result, force) {
@@ -114,26 +117,67 @@ function guessProjectName(dir) {
   }
   return dir.split("/").pop() || "Project";
 }
+var IS_WIN = platform() === "win32";
+function writeClaudeMd(projectDir, vars, result, force) {
+  const targetPath = join(projectDir, CLAUDE_MD);
+  if (IS_WIN) {
+    writeFileIfNeeded(
+      targetPath,
+      applyVars(readTemplate("CLAUDE.md"), vars),
+      CLAUDE_MD,
+      result,
+      force
+    );
+    return;
+  }
+  const linkTarget = AGENTS_MD;
+  if (existsSync(targetPath)) {
+    if (!force) {
+      result.skipped.push(CLAUDE_MD);
+      return;
+    }
+    unlinkSync(targetPath);
+  }
+  try {
+    symlinkSync(linkTarget, targetPath);
+    result.created.push(`${CLAUDE_MD} \u2192 ${AGENTS_MD}`);
+  } catch (err) {
+    writeFileSync(targetPath, applyVars(readTemplate("CLAUDE.md"), vars));
+    result.created.push(`${CLAUDE_MD} (symlink failed, wrote file)`);
+  }
+}
 function updateRouter(projectDir) {
-  const targetPath = join(projectDir, AGENTS_MD);
-  if (!existsSync(targetPath)) return false;
   const projectName = guessProjectName(projectDir);
   const vars = { PROJECT_NAME: projectName };
-  let content = applyVars(readTemplate("AGENTS.md"), vars);
-  const customPath = join(projectDir, CUSTOM_FILE);
-  if (existsSync(customPath)) {
-    const customContent = readFileSync(customPath, "utf-8").trim();
-    if (customContent) {
-      content += `
-
----
-<!-- BEGIN CUSTOM RULES (inlined from .agents/CUSTOM.md) -->
-${customContent}
-<!-- END CUSTOM RULES -->
-`;
+  const agentsPath = join(projectDir, AGENTS_MD);
+  if (!existsSync(agentsPath)) return false;
+  writeFileSync(agentsPath, applyVars(readTemplate("AGENTS.md"), vars));
+  const claudePath = join(projectDir, CLAUDE_MD);
+  if (IS_WIN) {
+    writeFileSync(claudePath, applyVars(readTemplate("CLAUDE.md"), vars));
+  } else {
+    let needsRecreate = false;
+    if (!existsSync(claudePath)) {
+      needsRecreate = true;
+    } else {
+      try {
+        const stat = lstatSync(claudePath);
+        if (!stat.isSymbolicLink()) {
+          needsRecreate = true;
+        }
+      } catch {
+        needsRecreate = true;
+      }
+    }
+    if (needsRecreate) {
+      try {
+        if (existsSync(claudePath)) unlinkSync(claudePath);
+        symlinkSync(AGENTS_MD, claudePath);
+      } catch {
+        writeFileSync(claudePath, applyVars(readTemplate("CLAUDE.md"), vars));
+      }
     }
   }
-  writeFileSync(targetPath, content);
   const managedSpecs = [
     { target: `${SPEC_DIR}/coding-principles.md`, template: "spec/coding-principles.md" }
   ];
@@ -147,12 +191,14 @@ ${customContent}
 }
 
 // src/doctor.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync2, lstatSync as lstatSync2 } from "fs";
 import { join as join2 } from "path";
+import { platform as platform2 } from "os";
 function doctor(projectDir) {
   const issues = [];
   const required = [
-    { file: AGENTS_MD, desc: "Root router file" },
+    { file: AGENTS_MD, desc: "Root router file (OpenCode)" },
+    { file: CLAUDE_MD, desc: "Root router file (Claude Code)" },
     { file: CUSTOM_FILE, desc: "Project specific rules" },
     { file: MEMORY_FILE, desc: "Long-term memory" },
     { file: TASKS_FILE, desc: "Working memory" },
@@ -169,22 +215,37 @@ function doctor(projectDir) {
       issues.push({ level: "error", file: dir, message: "Directory missing" });
     }
   }
-  const agentsPath = join2(projectDir, AGENTS_MD);
-  if (existsSync2(agentsPath)) {
-    const content = readFileSync2(agentsPath, "utf-8");
-    if (!content.includes(".agents/")) {
-      issues.push({
-        level: "warning",
-        file: AGENTS_MD,
-        message: "No references to .agents/ \u2014 agents may not find memory files"
-      });
-    }
-    if (content.split("\n").length > 150) {
-      issues.push({
-        level: "warning",
-        file: AGENTS_MD,
-        message: "Over 150 lines \u2014 consider keeping it concise as a router"
-      });
+  const routerFiles = [AGENTS_MD, CLAUDE_MD];
+  for (const rf of routerFiles) {
+    const rfPath = join2(projectDir, rf);
+    if (existsSync2(rfPath)) {
+      if (rf === CLAUDE_MD && platform2() !== "win32") {
+        try {
+          if (!lstatSync2(rfPath).isSymbolicLink()) {
+            issues.push({
+              level: "warning",
+              file: CLAUDE_MD,
+              message: "Plain file \u2014 should be a symlink to AGENTS.md. Run 'agent-memory update' to fix"
+            });
+          }
+        } catch {
+        }
+      }
+      const content = readFileSync2(rfPath, "utf-8");
+      if (!content.includes(".agents/")) {
+        issues.push({
+          level: "warning",
+          file: rf,
+          message: "No references to .agents/ \u2014 agents may not find memory files"
+        });
+      }
+      if (content.split("\n").length > 150) {
+        issues.push({
+          level: "warning",
+          file: rf,
+          message: "Over 150 lines \u2014 consider keeping it concise as a router"
+        });
+      }
     }
   }
   const memoryPath = join2(projectDir, MEMORY_FILE);
@@ -209,8 +270,8 @@ function printUsage() {
 @vuau/agent-memory \u2014 Structured AI memory for codebases
 
 Usage:
-  agent-memory init [options]    Scaffold .agents/ structure and AGENTS.md
-  agent-memory update            Update AGENTS.md router to latest version
+  agent-memory init [options]    Scaffold .agents/ structure, AGENTS.md and CLAUDE.md
+  agent-memory update            Update router files to latest version
   agent-memory doctor            Validate .agents/ structure
   agent-memory help              Show this help
 
@@ -252,7 +313,7 @@ Initializing agent memory in ${cwd}...
     }
   }
   console.log("\nNext steps:");
-  console.log("  1. Edit AGENTS.md \u2014 add project-specific rules");
+  console.log("  1. Edit AGENTS.md (OpenCode) / CLAUDE.md (Claude Code) with project-specific rules");
   console.log("  2. Add spec files to .agents/spec/ for detailed documentation");
   console.log("  3. Agent will read rules and write to .agents/MEMORY.md automatically");
   console.log("");
@@ -265,14 +326,14 @@ async function runUpdate() {
     process.exit(1);
   }
   console.log(`
-Updating ${AGENTS_MD} in ${cwd}...
+Updating ${AGENTS_MD} / ${CLAUDE_MD} in ${cwd}...
 `);
   const updated = updateRouter(cwd);
   if (updated) {
-    console.log(`  \u2713 ${AGENTS_MD} updated to the latest template.`);
+    console.log(`  \u2713 ${AGENTS_MD} and ${CLAUDE_MD} updated to the latest template.`);
     console.log(`  (Note: Your custom rules in .agents/CUSTOM.md were not affected)`);
   } else {
-    console.error("\u2717 Failed to update AGENTS.md");
+    console.error("\u2717 Failed to update router files");
     process.exit(1);
   }
   console.log("");

package/dist/index.js

@@ -1,7 +1,8 @@
 // src/scaffold.ts
-import { existsSync, mkdirSync, writeFileSync, readFileSync } from "fs";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, symlinkSync, lstatSync, unlinkSync } from "fs";
 import { join, resolve, dirname } from "path";
 import { fileURLToPath } from "url";
+import { platform } from "os";
 
 // src/types.ts
 var AGENTS_DIR = ".agents";
@@ -11,6 +12,7 @@ var MEMORY_DETAIL_FILE = ".agents/MEMORY-DETAIL.md";
 var TASKS_FILE = ".agents/TASKS.md";
 var CUSTOM_FILE = ".agents/CUSTOM.md";
 var AGENTS_MD = "AGENTS.md";
+var CLAUDE_MD = "CLAUDE.md";
 
 // src/scaffold.ts
 function getTemplatesDir() {
@@ -87,6 +89,7 @@ function scaffold(projectDir, options = {}) {
     result,
     force
   );
+  writeClaudeMd(projectDir, vars, result, force);
   return result;
 }
 function writeFileIfNeeded(targetPath, content, displayName, result, force) {
@@ -108,26 +111,67 @@ function guessProjectName(dir) {
   }
   return dir.split("/").pop() || "Project";
 }
+var IS_WIN = platform() === "win32";
+function writeClaudeMd(projectDir, vars, result, force) {
+  const targetPath = join(projectDir, CLAUDE_MD);
+  if (IS_WIN) {
+    writeFileIfNeeded(
+      targetPath,
+      applyVars(readTemplate("CLAUDE.md"), vars),
+      CLAUDE_MD,
+      result,
+      force
+    );
+    return;
+  }
+  const linkTarget = AGENTS_MD;
+  if (existsSync(targetPath)) {
+    if (!force) {
+      result.skipped.push(CLAUDE_MD);
+      return;
+    }
+    unlinkSync(targetPath);
+  }
+  try {
+    symlinkSync(linkTarget, targetPath);
+    result.created.push(`${CLAUDE_MD} \u2192 ${AGENTS_MD}`);
+  } catch (err) {
+    writeFileSync(targetPath, applyVars(readTemplate("CLAUDE.md"), vars));
+    result.created.push(`${CLAUDE_MD} (symlink failed, wrote file)`);
+  }
+}
 function updateRouter(projectDir) {
-  const targetPath = join(projectDir, AGENTS_MD);
-  if (!existsSync(targetPath)) return false;
   const projectName = guessProjectName(projectDir);
   const vars = { PROJECT_NAME: projectName };
-  let content = applyVars(readTemplate("AGENTS.md"), vars);
-  const customPath = join(projectDir, CUSTOM_FILE);
-  if (existsSync(customPath)) {
-    const customContent = readFileSync(customPath, "utf-8").trim();
-    if (customContent) {
-      content += `
-
----
-<!-- BEGIN CUSTOM RULES (inlined from .agents/CUSTOM.md) -->
-${customContent}
-<!-- END CUSTOM RULES -->
-`;
+  const agentsPath = join(projectDir, AGENTS_MD);
+  if (!existsSync(agentsPath)) return false;
+  writeFileSync(agentsPath, applyVars(readTemplate("AGENTS.md"), vars));
+  const claudePath = join(projectDir, CLAUDE_MD);
+  if (IS_WIN) {
+    writeFileSync(claudePath, applyVars(readTemplate("CLAUDE.md"), vars));
+  } else {
+    let needsRecreate = false;
+    if (!existsSync(claudePath)) {
+      needsRecreate = true;
+    } else {
+      try {
+        const stat = lstatSync(claudePath);
+        if (!stat.isSymbolicLink()) {
+          needsRecreate = true;
+        }
+      } catch {
+        needsRecreate = true;
+      }
+    }
+    if (needsRecreate) {
+      try {
+        if (existsSync(claudePath)) unlinkSync(claudePath);
+        symlinkSync(AGENTS_MD, claudePath);
+      } catch {
+        writeFileSync(claudePath, applyVars(readTemplate("CLAUDE.md"), vars));
+      }
     }
   }
-  writeFileSync(targetPath, content);
   const managedSpecs = [
     { target: `${SPEC_DIR}/coding-principles.md`, template: "spec/coding-principles.md" }
   ];
@@ -141,12 +185,14 @@ ${customContent}
 }
 
 // src/doctor.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync2, lstatSync as lstatSync2 } from "fs";
 import { join as join2 } from "path";
+import { platform as platform2 } from "os";
 function doctor(projectDir) {
   const issues = [];
   const required = [
-    { file: AGENTS_MD, desc: "Root router file" },
+    { file: AGENTS_MD, desc: "Root router file (OpenCode)" },
+    { file: CLAUDE_MD, desc: "Root router file (Claude Code)" },
     { file: CUSTOM_FILE, desc: "Project specific rules" },
     { file: MEMORY_FILE, desc: "Long-term memory" },
     { file: TASKS_FILE, desc: "Working memory" },
@@ -163,22 +209,37 @@ function doctor(projectDir) {
       issues.push({ level: "error", file: dir, message: "Directory missing" });
     }
   }
-  const agentsPath = join2(projectDir, AGENTS_MD);
-  if (existsSync2(agentsPath)) {
-    const content = readFileSync2(agentsPath, "utf-8");
-    if (!content.includes(".agents/")) {
-      issues.push({
-        level: "warning",
-        file: AGENTS_MD,
-        message: "No references to .agents/ \u2014 agents may not find memory files"
-      });
-    }
-    if (content.split("\n").length > 150) {
-      issues.push({
-        level: "warning",
-        file: AGENTS_MD,
-        message: "Over 150 lines \u2014 consider keeping it concise as a router"
-      });
+  const routerFiles = [AGENTS_MD, CLAUDE_MD];
+  for (const rf of routerFiles) {
+    const rfPath = join2(projectDir, rf);
+    if (existsSync2(rfPath)) {
+      if (rf === CLAUDE_MD && platform2() !== "win32") {
+        try {
+          if (!lstatSync2(rfPath).isSymbolicLink()) {
+            issues.push({
+              level: "warning",
+              file: CLAUDE_MD,
+              message: "Plain file \u2014 should be a symlink to AGENTS.md. Run 'agent-memory update' to fix"
+            });
+          }
+        } catch {
+        }
+      }
+      const content = readFileSync2(rfPath, "utf-8");
+      if (!content.includes(".agents/")) {
+        issues.push({
+          level: "warning",
+          file: rf,
+          message: "No references to .agents/ \u2014 agents may not find memory files"
+        });
+      }
+      if (content.split("\n").length > 150) {
+        issues.push({
+          level: "warning",
+          file: rf,
+          message: "Over 150 lines \u2014 consider keeping it concise as a router"
+        });
+      }
     }
   }
   const memoryPath = join2(projectDir, MEMORY_FILE);
@@ -197,6 +258,7 @@ function doctor(projectDir) {
 export {
   AGENTS_DIR,
   AGENTS_MD,
+  CLAUDE_MD,
   CUSTOM_FILE,
   MEMORY_DETAIL_FILE,
   MEMORY_FILE,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vuau/agent-memory",
-  "version": "0.5.5",
-  "description": "Structured AI memory for codebases — scaffolding CLI for OpenCode, Copilot, Cursor, Windsurf",
+  "version": "0.6.0",
+  "description": "Structured AI memory for codebases — scaffolding CLI for OpenCode, Copilot, Cursor, Windsurf, Claude Code",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {

package/templates/AGENTS.md

@@ -1,11 +1,14 @@
 # {{PROJECT_NAME}} - AGENTS
 
-Router file for AI agents.
+Router file for AI coding assistants: OpenCode, GitHub Copilot, Cursor, Windsurf, and others.
 
 > **Note**: This file is automatically managed by `@vuau/agent-memory`.
 > Do not add project-specific rules here, as they may be overwritten by `agent-memory update`.
 >
 > 👉 **For project-specific rules, context, and document mapping, see `.agents/CUSTOM.md`**
+>
+> 💡 **Claude Code users**: Install `@vuau/agent-memory` and run `init` to auto-generate `CLAUDE.md` —
+>   a companion file that references this `AGENTS.md` so you get the same rules.
 
 ## Priority
 1. User request first.

package/templates/CLAUDE.md

@@ -0,0 +1,14 @@
+# {{PROJECT_NAME}} - CLAUDE.md
+
+Router file for Claude Code.
+
+> **Note**: This file is auto-generated by `@vuau/agent-memory`.
+> Do not edit directly.
+>
+> 👉 **All project rules live in `AGENTS.md`** — you MUST read that file for context and instructions.
+
+## Rules
+
+All project rules, memory protocol, and response style are defined in **[AGENTS.md](./AGENTS.md)**.
+
+Read `AGENTS.md` before making any changes.