@dtd-dev/agent-kb 0.1.1 → 0.1.2

package/README.md

@@ -88,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

@@ -271,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;
@@ -278,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;
@@ -335,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);
   }
@@ -365,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 đè).`);
   }
@@ -552,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.1",
+  "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"