@dtd-dev/agent-kb 0.1.0 → 0.1.2

package/README.md

@@ -36,7 +36,9 @@ Không cài global, không cần clone. Zero-dependency nên `npx` chạy tức
 | `help` | Trợ giúp |
 
 Chạy tương tác sẽ hỏi: **tên dự án, backend, database, frontend, CI/CD, lệnh deploy, tool phụ**
-(Enter để giữ gợi ý). agent-kb **tự đọc `package.json`/`go.mod`/… để gợi ý stack & database sẵn**.
+(Enter để giữ gợi ý). agent-kb **tự đọc `package.json`/`go.mod`/… để gợi ý stack & database sẵn**
+— quét cả **thư mục con tới 3 cấp** nên hỗ trợ **monorepo** (vd `apps/web`, `services/api`). Nếu
+không thấy manifest nào, nó **báo rõ** và để bạn nhập tay (hoặc dùng cờ `--backend/--frontend/--database`).
 Các phần còn lại (cache, state, UI lib, container, URL môi trường, rollback…) là placeholder
 `<!-- vd: ... -->` trong file để bạn điền tay sau.
 
@@ -86,20 +88,39 @@ tiêu đề đã điền tên feature — khỏi copy thư mục `feature-a/` (v
 - `.ai/core/*` là Tier 1 (luôn load, giữ nhỏ). Mọi thứ khác load theo task qua router trong `AGENTS.md`.
 - Không nhân bản rule sang nhiều file → tránh lệch và tốn token.
 
-## Tự publish lên npm (tuỳ chọn)
-1. `name` trong `package.json` đã đặt là `@dtd-dev/agent-kb` (đổi scope nếu cần).
-2. `npm login`
-3. `npm publish --access public`
-Sau đó cả team dùng: `npx @dtd-dev/agent-kb`.
+## Bản đồ file: cái nào core, cái nào cá nhân hoá, cái nào nhờ AI điền
 
-Hoặc dùng local không cần publish:
-```bash
-npm pack            # tạo file .tgz
-# rồi ở dự án khác: npx /duong/dan/dtd-dev-agent-kb-0.1.0.tgz init
-```
+Sau khi `init`, mỗi file rơi vào **một** trong 3 nhóm. Cột "Ai điền" cho biết bạn phải tự làm hay nhờ AI/CLI:
+
+| File / Thư mục | Nhóm | Ai điền | Ghi chú |
+|---|---|---|---|
+| `AGENTS.md` (router + quy tắc), `CLAUDE.md`/`GEMINI.md`/`copilot-instructions.md` | 🟦 **Core** | CLI | Khung dùng lại mọi dự án. Phần trong block `BEGIN/END agent-kb` do CLI quản — đừng sửa tay (chạy lại `init` sẽ ghi đè block). |
+| `.ai/README.md` (index Tier 0) | 🟦 **Core** | — | Bản đồ "task → file". Giữ nguyên. |
+| `.ai/workflows/*` (create-feature, fix-bug, code-review, release, learn, incident-response) | 🟦 **Core** | — | Phương pháp luận, dùng lại như nhau giữa các dự án. |
+| `.ai/agents/*` (reviewer, tester, bug-fixer, feature-builder) | 🟦 **Core** | — | Nguồn chân lý của sub-agent; CLI tự emit sang `.claude/agents/`. |
+| `.ai/core/tech-stack.md` | 🟩 **AI điền** | CLI + AI | CLI điền `{{...}}` từ nhận diện stack; AI bổ sung các chỗ `<!-- vd: ... -->` (cache, state, UI lib…) sau khi đọc code. |
+| `.ai/core/coding-standards.md`, `.ai/core/glossary.md` | 🟩 **AI điền** | AI | Nhờ AI đọc codebase rồi viết. |
+| `.ai/architecture.md` | 🟩 **AI điền** | AI | AI suy ra từ cấu trúc dự án. |
+| `.ai/examples/*` | 🟩 **AI điền** | AI | Sinh từ code thật của bạn (thay ví dụ mẫu). |
+| `.ai/skills/devops/*` (deployment, docker, github-actions), `.ai/skills/frontend/react.md`, `ui-guideline.md` | 🟩 **AI điền** | AI | Skill generic — AI viết theo stack thực tế. `deployment.md` có `{{DEPLOY_CMD}}` do CLI điền. |
+| `.ai/memory/*` (common-bugs, lessons-learned, troubleshooting) | 🟩 **AI điền** | AI (dần dần) | Tích luỹ qua workflow `learn.md` mỗi khi rút kinh nghiệm. |
+| `.ai/product/*` (vision, business-rules, domain-model) | 🟥 **Cá nhân hoá** | Người (+AI hỗ trợ) | **Nội dung shipped là MẪU CarePay** — bắt buộc thay bằng nghiệp vụ công ty bạn. Giữ cách đánh số (BR-001…). |
+| `.ai/skills/backend/carepay-*`, `.ai/skills/frontend/carepay-firebase.md` | 🟥 **Cá nhân hoá** | Người | Skill nghiệp vụ mẫu — xoá hoặc thay bằng skill dự án bạn. |
+| `.ai/decisions/ADR-00x-*` | 🟥 **Cá nhân hoá** | Người | Mẫu — thay bằng quyết định thật; tạo mới: `agent-kb adr <tiêu đề>`. |
+| `.ai/specs/feature-a/*` | 🟥 **Cá nhân hoá** | Người | Spec mẫu — tạo spec thật: `agent-kb feature <tên>`. |
+
+> 🟦 **Core** = giữ nguyên, dùng lại mọi dự án.  🟩 **AI điền** = nhờ AI đọc code rồi viết.  🟥 **Cá nhân hoá** = nội dung nghiệp vụ riêng, bạn (hoặc AI có ngữ cảnh công ty) phải thay.
+
+### AI đọc file nào mỗi lần chạy?
+- **Luôn (mọi session)**: `CLAUDE.md` → import `AGENTS.md` (router + Tier 1). Tier 1 = `.ai/core/tech-stack.md` + `coding-standards.md` + `glossary.md`. Giữ 3 file này thật ngắn (< ~500 token/file) vì đây là phần tốn token cố định.
+- **Theo task (Tier 2, on-demand)**: AI tra bảng router trong `AGENTS.md` / `.ai/README.md` rồi chỉ mở file khớp task — vd fix bug → `workflows/fix-bug.md` + `memory/common-bugs.md`; hiểu nghiệp vụ → `product/business-rules.md` + `product/domain-model.md`. **Không** nuốt cả `.ai/`.
 
-## Cập nhật template về sau
-Sửa các file trong `template/` của package này → bump version → publish lại.
-Mọi dự án init sau đó nhận bản mới. (Dự án cũ chạy lại `agent-kb init` để vá phần thiếu.)
+Gợi ý onboard dự án mới: điền 🟩 (nhờ AI) trước → thay 🟥 (nghiệp vụ) → chạy `agent-kb doctor` để chốt.
+
+**Prompt 1-câu để Agent tự điền các file 🟩** (dán vào Claude Code/Cursor… ở thư mục gốc dự án):
+
+```
+Đọc codebase của dự án này rồi điền chính xác CHỈ các file nhóm 🟩 trong .ai/ (core/tech-stack.md ở các chỗ <!-- vd: ... -->, core/coding-standards.md, core/glossary.md, architecture.md, examples/*, skills/devops/* và skills/frontend/react.md + ui-guideline.md) bằng dữ kiện có thật trong code — giữ mỗi file core/* dưới ~500 token, KHÔNG đụng file 🟥 nghiệp vụ (product/*, skills/backend/carepay-*, carepay-firebase, decisions/, specs/), KHÔNG sửa trong block BEGIN/END agent-kb — xong chạy `agent-kb doctor` và sửa tới khi sạch cảnh báo.
+```
 
 MIT

package/bin/cli.js

@@ -167,38 +167,86 @@ function substituteTokens(values) {
   }
 }
 
-// Đọc dự án để gợi ý stack — chỉ đọc file, không đổi gì.
-function detectStack() {
-  const out = { backend: null, frontend: null, database: null, cicd: null, stacks: [] };
-  const addStack = (s) => {
-    if (!out.stacks.includes(s)) out.stacks.push(s);
+// Thư mục rác/sinh ra — không quét để khỏi nhận diện nhầm & cho nhanh.
+const IGNORE_DIRS = new Set([
+  "node_modules", ".git", ".ai", ".claude", "dist", "build", "out",
+  ".next", ".nuxt", "coverage", "vendor", "target", ".gradle", ".venv", "venv", "__pycache__",
+]);
+const MANIFEST_NAMES = [
+  "package.json", "go.mod", "requirements.txt", "pyproject.toml", "Pipfile",
+  "pom.xml", "build.gradle", "build.gradle.kts", "Cargo.toml", "composer.json",
+];
+
+// Tìm các thư mục có manifest, quét tối đa maxDepth cấp từ root (bỏ thư mục rác/dotdir).
+function findProjectRoots(root, maxDepth) {
+  const roots = [];
+  const walk = (dir, depth) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    if (entries.some((e) => e.isFile() && MANIFEST_NAMES.includes(e.name))) roots.push(dir);
+    if (depth >= maxDepth) return;
+    for (const e of entries) {
+      if (e.isDirectory() && !e.name.startsWith(".") && !IGNORE_DIRS.has(e.name)) {
+        walk(path.join(dir, e.name), depth + 1);
+      }
+    }
   };
+  walk(root, 0);
+  return roots;
+}
 
-  const pkg = readJSONSafe(path.join(CWD, "package.json"));
+// Nhận diện stack trong MỘT thư mục, gộp vào `out` (chỉ điền chỗ còn trống → root thắng subfolder).
+function detectInDir(dir, out, addStack) {
+  const exists = (f) => fs.existsSync(path.join(dir, f));
+  const pkg = readJSONSafe(path.join(dir, "package.json"));
   if (pkg) {
     const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
     const has = (n) => Object.prototype.hasOwnProperty.call(deps, n);
-    if (has("next")) { out.frontend = "Next.js + React"; addStack("react"); }
-    else if (has("react")) { out.frontend = "React" + (has("vite") ? " + Vite" : ""); addStack("react"); }
-    else if (has("vue")) out.frontend = "Vue";
-    else if (has("svelte") || has("@sveltejs/kit")) out.frontend = "Svelte";
-
-    if (has("@nestjs/core")) { out.backend = "Node.js + NestJS"; addStack("node"); }
-    else if (has("express")) { out.backend = "Node.js + Express"; addStack("node"); }
-    else if (has("fastify")) { out.backend = "Node.js + Fastify"; addStack("node"); }
-    else if (!out.frontend) { out.backend = "Node.js"; addStack("node"); }
-
-    if (has("pg") || has("postgres") || has("postgresql")) out.database = "PostgreSQL";
-    else if (has("mysql") || has("mysql2")) out.database = "MySQL";
-    else if (has("mongoose") || has("mongodb")) out.database = "MongoDB";
-    else if (has("firebase") || has("firebase-admin")) out.database = "Firebase/Firestore";
-    if (has("redis") || has("ioredis")) out.database = out.database ? out.database + " + Redis" : "Redis";
-  }
-  if (hasFile("go.mod")) { out.backend = out.backend || "Go"; addStack("go"); }
-  if (hasFile("requirements.txt") || hasFile("pyproject.toml") || hasFile("Pipfile")) { out.backend = out.backend || "Python"; addStack("python"); }
-  if (hasFile("pom.xml") || hasFile("build.gradle") || hasFile("build.gradle.kts")) { out.backend = out.backend || "Java"; addStack("java"); }
-  if (hasFile("Cargo.toml")) { out.backend = out.backend || "Rust"; addStack("rust"); }
-  if (hasFile("composer.json")) { out.backend = out.backend || "PHP"; addStack("php"); }
+    let fe = null, be = null;
+    if (has("next")) { fe = "Next.js + React"; addStack("react"); }
+    else if (has("react")) { fe = "React" + (has("vite") ? " + Vite" : ""); addStack("react"); }
+    else if (has("vue")) fe = "Vue";
+    else if (has("svelte") || has("@sveltejs/kit")) fe = "Svelte";
+
+    if (has("@nestjs/core")) { be = "Node.js + NestJS"; addStack("node"); }
+    else if (has("express")) { be = "Node.js + Express"; addStack("node"); }
+    else if (has("fastify")) { be = "Node.js + Fastify"; addStack("node"); }
+    else if (!fe) { out._node = true; addStack("node"); } // Node "trơn": ưu tiên thấp nhất, quyết ở cuối
+
+    if (fe && !out.frontend) out.frontend = fe;
+    if (be && !out.backend) out.backend = be;
+
+    if (!out.database) {
+      if (has("pg") || has("postgres") || has("postgresql")) out.database = "PostgreSQL";
+      else if (has("mysql") || has("mysql2")) out.database = "MySQL";
+      else if (has("mongoose") || has("mongodb")) out.database = "MongoDB";
+      else if (has("firebase") || has("firebase-admin")) out.database = "Firebase/Firestore";
+    }
+    if ((has("redis") || has("ioredis")) && !(out.database || "").includes("Redis")) {
+      out.database = out.database ? out.database + " + Redis" : "Redis";
+    }
+  }
+  if (exists("go.mod")) { out.backend = out.backend || "Go"; addStack("go"); }
+  if (exists("requirements.txt") || exists("pyproject.toml") || exists("Pipfile")) { out.backend = out.backend || "Python"; addStack("python"); }
+  if (exists("pom.xml") || exists("build.gradle") || exists("build.gradle.kts")) { out.backend = out.backend || "Java"; addStack("java"); }
+  if (exists("Cargo.toml")) { out.backend = out.backend || "Rust"; addStack("rust"); }
+  if (exists("composer.json")) { out.backend = out.backend || "PHP"; addStack("php"); }
+}
+
+// Đọc dự án để gợi ý stack — chỉ đọc file, không đổi gì. Quét cả thư mục con (monorepo).
+function detectStack() {
+  const out = { backend: null, frontend: null, database: null, cicd: null, stacks: [], roots: [], _node: false };
+  const addStack = (s) => {
+    if (!out.stacks.includes(s)) out.stacks.push(s);
+  };
+
+  // Root (CWD) trước, rồi tới subfolder nông→sâu, để stack của thư mục gốc được ưu tiên.
+  const roots = findProjectRoots(CWD, 3).sort((a, b) => a.length - b.length);
+  for (const dir of roots) {
+    detectInDir(dir, out, addStack);
+    out.roots.push(path.relative(CWD, dir) || ".");
+  }
+  if (!out.backend && out._node) out.backend = "Node.js"; // fallback Node sau khi đã xét hết
 
   if (fs.existsSync(path.join(CWD, ".github", "workflows"))) out.cicd = "GitHub Actions";
   else if (hasFile(".gitlab-ci.yml")) out.cicd = "GitLab CI";
@@ -223,6 +271,8 @@ function availableStacks() {
 }
 
 // Emit sub-agent: copy .ai/agents/*.md (nguồn chân lý) -> .claude/agents/ cho Claude Code đọc.
+// .claude/agents/ là bản emit PHÁI SINH — luôn ghi đè theo nguồn (không tôn trọng --force/skip),
+// nếu không sửa .ai/agents/ rồi chạy lại init sẽ không đồng bộ.
 function emitAgents(stats) {
   const src = path.join(CWD, ".ai", "agents");
   if (!fs.existsSync(src)) return 0;
@@ -230,7 +280,17 @@ function emitAgents(stats) {
   let n = 0;
   for (const f of fs.readdirSync(src)) {
     if (!f.endsWith(".md")) continue;
-    copyRecursive(path.join(src, f), path.join(dest, f), stats);
+    const to = path.join(dest, f);
+    const rel = path.relative(CWD, to);
+    const content = fs.readFileSync(path.join(src, f), "utf8");
+    const existed = fs.existsSync(to);
+    if (existed && fs.readFileSync(to, "utf8") === content) {
+      n++;
+      continue; // đã trùng nguồn → không ghi, không báo
+    }
+    fs.mkdirSync(dest, { recursive: true });
+    fs.writeFileSync(to, content);
+    (existed ? stats.synced : stats.written).push(rel);
     n++;
   }
   return n;
@@ -259,6 +319,14 @@ async function init() {
 
   if (det.backend || det.frontend || det.cicd) {
     console.log(`\nℹ  Nhận diện stack: ${[det.backend, det.frontend, det.database, det.cicd].filter(Boolean).join(" · ") || "—"}`);
+    if (det.roots.length > 1 || (det.roots.length === 1 && det.roots[0] !== ".")) {
+      console.log(`   (manifest tại: ${det.roots.join(", ")})`);
+    }
+  } else {
+    console.log("\n⚠  Không tự nhận diện được stack — không thấy manifest");
+    console.log("   (package.json / go.mod / requirements.txt / pyproject.toml / pom.xml / Cargo.toml / composer.json)");
+    console.log("   trong thư mục này hay các thư mục con (quét tối đa 3 cấp).");
+    console.log("   → Chạy ở đúng thư mục gốc dự án, hoặc nhập tay / dùng cờ --backend --frontend --database.");
   }
 
   if (!YES) {
@@ -279,7 +347,7 @@ async function init() {
     rl.close();
   }
 
-  const stats = { written: [], skipped: [], merged: [] };
+  const stats = { written: [], skipped: [], merged: [], synced: [] };
   for (const [from, to] of MAP) {
     copyRecursive(path.join(TEMPLATE_DIR, from), path.join(CWD, to), stats);
   }
@@ -309,7 +377,10 @@ async function init() {
   }
   if (tools.length) console.log(`🔌 Tool đã bật: ${tools.join(", ")}`);
   if (stacks.length) console.log(`📦 Gói stack: ${stacks.join(", ")} → .ai/skills/stacks/`);
-  if (agentsCount) console.log(`🤖 Sub-agents: ${agentsCount} → .claude/agents/ (nguồn: .ai/agents/)`);
+  if (agentsCount) {
+    const note = stats.synced.length ? ` (${stats.synced.length} đồng bộ lại từ nguồn)` : "";
+    console.log(`🤖 Sub-agents: ${agentsCount} → .claude/agents/ (nguồn: .ai/agents/)${note}`);
+  }
   if (stats.skipped.length) {
     console.log(`↷ Bỏ qua ${stats.skipped.length} file đã tồn tại (dùng --force để ghi đè).`);
   }
@@ -496,13 +567,19 @@ function doctor() {
     if (fs.existsSync(path.join(CWD, dest))) oks.push(`${dest} (${t})`);
   }
 
-  // Sub-agents: mỗi .ai/agents/*.md cần có bản emit ở .claude/agents/
+  // Sub-agents: mỗi .ai/agents/*.md cần có bản emit ở .claude/agents/ KHỚP nội dung nguồn.
   const aiAgents = path.join(CWD, ".ai", "agents");
   if (fs.existsSync(aiAgents)) {
     for (const f of fs.readdirSync(aiAgents)) {
       if (!f.endsWith(".md")) continue;
-      if (fs.existsSync(path.join(CWD, ".claude", "agents", f))) oks.push(`.claude/agents/${f}`);
-      else warnings.push(`Agent .ai/agents/${f} chưa emit sang .claude/agents/ (chạy lại agent-kb init)`);
+      const emit = path.join(CWD, ".claude", "agents", f);
+      if (!fs.existsSync(emit)) {
+        warnings.push(`Agent .ai/agents/${f} chưa emit sang .claude/agents/ (chạy lại agent-kb init)`);
+      } else if (fs.readFileSync(path.join(aiAgents, f), "utf8") !== fs.readFileSync(emit, "utf8")) {
+        warnings.push(`.claude/agents/${f} lệch với nguồn .ai/agents/${f} (chạy lại agent-kb init để đồng bộ)`);
+      } else {
+        oks.push(`.claude/agents/${f}`);
+      }
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtd-dev/agent-kb",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Bộ agent skill chuẩn hoá cho doanh nghiệp: scaffold knowledge base .ai/ tiết kiệm token, tăng độ chính xác khi viết code, và cá nhân hoá theo nghiệp vụ công ty để tái dùng cho nhiều dự án cùng nghiệp vụ (AGENTS.md, CLAUDE.md, GEMINI.md, Copilot).",
   "bin": {
     "agent-kb": "bin/cli.js"