@dtd-dev/agent-kb 0.1.0

package/bin/cli.js

@@ -0,0 +1,653 @@
+#!/usr/bin/env node
+"use strict";
+
+/*
+ * agent-kb — scaffold a token-efficient .ai/ knowledge base + cross-tool agent config.
+ * Zero dependencies (uses only Node built-ins) so `npx` runs instantly.
+ *
+ * Lệnh chính:
+ *   agent-kb [init]            khởi tạo KB + agent config (tương tác / -y)
+ *   agent-kb feature <tên>     tạo .ai/specs/<tên>/ từ khung trống
+ *   agent-kb adr <tiêu đề>     tạo ADR mới (tự đánh số)
+ *   agent-kb skill <a>/<tên>   tạo skill mới từ khung
+ *   agent-kb doctor            kiểm tra & audit KB (read-only)
+ *   agent-kb import            gom config rule cũ vào AGENTS.md
+ *   agent-kb mcp add <name>    thêm MCP server vào .mcp.json
+ *   agent-kb hook install      cài git pre-commit hook chạy doctor
+ */
+
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+
+const TEMPLATE_DIR = path.join(__dirname, "..", "template");
+const CWD = process.cwd();
+
+// .ai/ copy nguyên cây (skip file đã có); các file agent-config xử lý riêng qua mergeOrCreate.
+const MAP = [["ai", ".ai"]];
+
+// File agent-config lõi: nếu đã tồn tại thì CHÈN block agent-kb (không bỏ qua, không đụng phần ngoài block).
+const AGENT_FILES = [
+  ["AGENTS.md", "AGENTS.md"],
+  ["CLAUDE.md", "CLAUDE.md"],
+  ["GEMINI.md", "GEMINI.md"],
+  [path.join("github", "copilot-instructions.md"), path.join(".github", "copilot-instructions.md")],
+];
+
+// Tool tuỳ chọn: file trỏ về AGENTS.md (dùng chung 1 nội dung pointer).
+const OPTIONAL_TOOLS = {
+  cursor: ".cursorrules",
+  windsurf: ".windsurfrules",
+  cline: ".clinerules",
+  zed: ".rules",
+  aider: "CONVENTIONS.md",
+};
+const POINTER_SRC = path.join(TEMPLATE_DIR, "tools", "pointer.md");
+
+const BEGIN = "<!-- BEGIN agent-kb -->";
+const END = "<!-- END agent-kb -->";
+
+const args = process.argv.slice(2);
+const cmd = args[0] && !args[0].startsWith("-") ? args[0] : "init";
+const FORCE = args.includes("--force") || args.includes("-f");
+const HOOK = args.includes("--hook");
+
+function flag(name) {
+  const i = args.indexOf(name);
+  return i !== -1 && args[i + 1] ? args[i + 1] : null;
+}
+const FLAG_NAME = flag("--name");
+const FLAG_BACKEND = flag("--backend");
+const FLAG_FRONTEND = flag("--frontend");
+const FLAG_DATABASE = flag("--database");
+const FLAG_CICD = flag("--cicd");
+const FLAG_DEPLOY = flag("--deploy");
+const FLAG_TOOLS = flag("--tools");
+const FLAG_STACK = flag("--stack");
+const FLAG_DESC = flag("--desc");
+const FLAG_MODEL = flag("--model");
+
+// -y, hoặc không phải terminal (pipe/CI): dùng mặc định thay vì treo chờ nhập.
+const YES = args.includes("--yes") || args.includes("-y") || !process.stdin.isTTY;
+
+// ---------- helpers ----------
+function ask(rl, q, def) {
+  return new Promise((res) => {
+    rl.question(`${q}${def ? ` (${def})` : ""}: `, (a) => res(a.trim() || def || ""));
+  });
+}
+
+function readJSONSafe(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function hasFile(rel) {
+  return fs.existsSync(path.join(CWD, rel));
+}
+
+function slugify(s) {
+  return (
+    String(s)
+      .trim()
+      .replace(/\s+/g, "-")
+      .replace(/[\/\\]/g, "-")
+      .replace(/^\.+/, "")
+      .replace(/-+/g, "-")
+      .replace(/^-|-$/g, "")
+      .toLowerCase() || "untitled"
+  );
+}
+
+function copyRecursive(src, dest, stats) {
+  const s = fs.statSync(src);
+  if (s.isDirectory()) {
+    if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dest, entry), stats);
+    }
+  } else {
+    if (fs.existsSync(dest) && !FORCE) {
+      stats.skipped.push(path.relative(CWD, dest));
+      return;
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+    stats.written.push(path.relative(CWD, dest));
+  }
+}
+
+// Chèn nội dung template vào file đích dưới dạng block có mốc (idempotent).
+//  - chưa có file        -> tạo file = block
+//  - có file, chưa block  -> append block vào cuối (giữ nguyên nội dung cũ)
+//  - có file, có block    -> thay đúng vùng BEGIN..END
+//  - --force              -> ghi đè cả file bằng block
+function mergeOrCreate(src, dest, stats) {
+  const inner = fs.readFileSync(src, "utf8").trim();
+  const block = `${BEGIN}\n${inner}\n${END}\n`;
+  const rel = path.relative(CWD, dest);
+
+  if (!fs.existsSync(dest) || FORCE) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, block);
+    stats.written.push(rel);
+    return;
+  }
+
+  const current = fs.readFileSync(dest, "utf8");
+  const re = new RegExp(`${BEGIN}[\\s\\S]*?${END}\\n?`);
+  if (re.test(current)) {
+    fs.writeFileSync(dest, current.replace(re, block)); // cập nhật block cũ
+  } else {
+    fs.writeFileSync(dest, current.replace(/\s*$/, "\n\n") + block); // chèn vào cuối
+  }
+  stats.merged.push(rel);
+}
+
+function substituteTokens(values) {
+  const targets = [
+    path.join(CWD, ".ai", "core", "tech-stack.md"),
+    path.join(CWD, ".ai", "skills", "devops", "deployment.md"),
+    path.join(CWD, "AGENTS.md"),
+  ];
+  for (const file of targets) {
+    if (!fs.existsSync(file)) continue;
+    let txt = fs.readFileSync(file, "utf8");
+    txt = txt
+      .replace(/\{\{PROJECT_NAME\}\}/g, values.name)
+      .replace(/\{\{BACKEND\}\}/g, values.backend)
+      .replace(/\{\{FRONTEND\}\}/g, values.frontend)
+      .replace(/\{\{DATABASE\}\}/g, values.database)
+      .replace(/\{\{CICD\}\}/g, values.cicd)
+      .replace(/\{\{DEPLOY_CMD\}\}/g, values.deploy);
+    fs.writeFileSync(file, txt);
+  }
+}
+
+// Đọ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);
+  };
+
+  const pkg = readJSONSafe(path.join(CWD, "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"); }
+
+  if (fs.existsSync(path.join(CWD, ".github", "workflows"))) out.cicd = "GitHub Actions";
+  else if (hasFile(".gitlab-ci.yml")) out.cicd = "GitLab CI";
+  else if (hasFile("Jenkinsfile")) out.cicd = "Jenkins";
+  return out;
+}
+
+function selectedTools(spec) {
+  if (!spec) return [];
+  const all = Object.keys(OPTIONAL_TOOLS);
+  if (spec.trim().toLowerCase() === "all") return all;
+  return spec
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter((t) => all.includes(t));
+}
+
+function availableStacks() {
+  const dir = path.join(TEMPLATE_DIR, "_stacks");
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => f.endsWith(".md")).map((f) => f.replace(/\.md$/, ""));
+}
+
+// Emit sub-agent: copy .ai/agents/*.md (nguồn chân lý) -> .claude/agents/ cho Claude Code đọc.
+function emitAgents(stats) {
+  const src = path.join(CWD, ".ai", "agents");
+  if (!fs.existsSync(src)) return 0;
+  const dest = path.join(CWD, ".claude", "agents");
+  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);
+    n++;
+  }
+  return n;
+}
+
+// ---------- commands ----------
+async function init() {
+  if (!fs.existsSync(TEMPLATE_DIR)) {
+    console.error("✗ Không tìm thấy thư mục template trong package.");
+    process.exit(1);
+  }
+
+  const det = detectStack();
+  const pick = (flagV, detV, placeholder) => (flagV ? "Stack: " + flagV : detV ? "Stack: " + detV : placeholder);
+
+  let values = {
+    name: FLAG_NAME || path.basename(CWD),
+    backend: pick(FLAG_BACKEND, det.backend, "Ngôn ngữ + framework: <!-- vd: Node.js 20 + NestJS 10 -->"),
+    frontend: pick(FLAG_FRONTEND, det.frontend, "Framework: <!-- vd: React 18 + Vite -->"),
+    database: FLAG_DATABASE || det.database || "<!-- vd: PostgreSQL 15 -->",
+    cicd: FLAG_CICD || det.cicd || "<!-- vd: GitHub Actions -->",
+    deploy: FLAG_DEPLOY || "<!-- vd: ./scripts/deploy.sh <env> -->",
+  };
+  let toolsSpec = FLAG_TOOLS || "";
+  let stackSpec = FLAG_STACK || "";
+
+  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 (!YES) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    console.log("\n⚙  Khởi tạo AI knowledge base (.ai/) — Enter để giữ mặc định/gợi ý\n");
+    values.name = await ask(rl, "Tên dự án", values.name);
+    const be = await ask(rl, "Backend stack", det.backend || "");
+    const db = await ask(rl, "Database", det.database || "");
+    const fe = await ask(rl, "Frontend stack", det.frontend || "");
+    const cicd = await ask(rl, "CI/CD", det.cicd || "");
+    const deploy = await ask(rl, "Lệnh deploy", "");
+    if (be) values.backend = "Stack: " + be;
+    if (db) values.database = db;
+    if (fe) values.frontend = "Stack: " + fe;
+    if (cicd) values.cicd = cicd;
+    if (deploy) values.deploy = deploy;
+    if (!toolsSpec) toolsSpec = await ask(rl, "Thêm tool khác (cursor,windsurf,cline,zed,aider / all / Enter=bỏ)", "");
+    rl.close();
+  }
+
+  const stats = { written: [], skipped: [], merged: [] };
+  for (const [from, to] of MAP) {
+    copyRecursive(path.join(TEMPLATE_DIR, from), path.join(CWD, to), stats);
+  }
+  for (const [from, to] of AGENT_FILES) {
+    mergeOrCreate(path.join(TEMPLATE_DIR, from), path.join(CWD, to), stats);
+  }
+  const tools = selectedTools(toolsSpec);
+  for (const t of tools) {
+    mergeOrCreate(POINTER_SRC, path.join(CWD, OPTIONAL_TOOLS[t]), stats);
+  }
+
+  // Gói chuẩn theo stack: từ --stack hoặc tự nhận diện.
+  const stacks = (stackSpec ? stackSpec.split(",").map((s) => s.trim().toLowerCase()) : det.stacks).filter((s) =>
+    availableStacks().includes(s)
+  );
+  for (const s of stacks) {
+    copyRecursive(path.join(TEMPLATE_DIR, "_stacks", s + ".md"), path.join(CWD, ".ai", "skills", "stacks", s + ".md"), stats);
+  }
+
+  const agentsCount = emitAgents(stats);
+  substituteTokens(values);
+  if (HOOK) installHook(true);
+
+  console.log(`\n✓ Đã tạo ${stats.written.length} file vào ${CWD}`);
+  if (stats.merged.length) {
+    console.log(`✎ Chèn/cập nhật ${stats.merged.length} file agent-config (block <!-- BEGIN/END agent-kb -->): ${stats.merged.join(", ")}`);
+  }
+  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 (stats.skipped.length) {
+    console.log(`↷ Bỏ qua ${stats.skipped.length} file đã tồn tại (dùng --force để ghi đè).`);
+  }
+  console.log("\nBước tiếp:");
+  console.log("  1. Điền .ai/core/*  (tech-stack, coding-standards, glossary)");
+  console.log("  2. Tạo spec feature mới: agent-kb feature <tên>");
+  console.log("  3. Kiểm tra bất cứ lúc nào: agent-kb doctor");
+  console.log("  4. AGENTS.md là nguồn chân lý — các file khác đã trỏ về nó.\n");
+}
+
+function feature() {
+  const raw = args.slice(1).find((a) => a && !a.startsWith("-"));
+  if (!raw) {
+    console.error("✗ Thiếu tên feature. Dùng: agent-kb feature <tên>");
+    process.exit(1);
+  }
+  const skeleton = path.join(TEMPLATE_DIR, "_feature-skeleton");
+  if (!fs.existsSync(skeleton)) {
+    console.error("✗ Không tìm thấy khung feature (_feature-skeleton) trong package.");
+    process.exit(1);
+  }
+  const specsDir = path.join(CWD, ".ai", "specs");
+  if (!fs.existsSync(specsDir)) {
+    console.error("✗ Chưa thấy .ai/specs — chạy `agent-kb init` trước.");
+    process.exit(1);
+  }
+
+  const name = raw.trim();
+  const slug = name.replace(/\s+/g, "-").replace(/[\/\\]/g, "-").replace(/^\.+/, "");
+  const dest = path.join(specsDir, slug);
+  if (fs.existsSync(dest) && !FORCE) {
+    console.error(`✗ .ai/specs/${slug}/ đã tồn tại (dùng --force để ghi đè).`);
+    process.exit(1);
+  }
+
+  const stats = { written: [], skipped: [], merged: [] };
+  copyRecursive(skeleton, dest, stats);
+  for (const f of fs.readdirSync(dest)) {
+    const file = path.join(dest, f);
+    const txt = fs.readFileSync(file, "utf8").replace(/\{\{FEATURE_NAME\}\}/g, name);
+    fs.writeFileSync(file, txt);
+  }
+
+  console.log(`\n✓ Đã tạo .ai/specs/${slug}/ (${stats.written.length} file)`);
+  console.log("  Điền requirements.md trước; quy trình: .ai/workflows/create-feature.md\n");
+}
+
+function adr() {
+  const raw = args.slice(1).find((a) => a && !a.startsWith("-"));
+  if (!raw) {
+    console.error("✗ Thiếu tiêu đề. Dùng: agent-kb adr <tiêu đề>");
+    process.exit(1);
+  }
+  const dir = path.join(CWD, ".ai", "decisions");
+  if (!fs.existsSync(dir)) {
+    console.error("✗ Chưa thấy .ai/decisions — chạy `agent-kb init` trước.");
+    process.exit(1);
+  }
+  const skel = path.join(TEMPLATE_DIR, "_adr-skeleton.md");
+  let max = 0;
+  for (const f of fs.readdirSync(dir)) {
+    const m = f.match(/^ADR-(\d+)/i);
+    if (m) max = Math.max(max, parseInt(m[1], 10));
+  }
+  const num = String(max + 1).padStart(3, "0");
+  const title = raw.trim();
+  const dest = path.join(dir, `ADR-${num}-${slugify(title)}.md`);
+  if (fs.existsSync(dest) && !FORCE) {
+    console.error(`✗ ${path.relative(CWD, dest)} đã tồn tại (dùng --force).`);
+    process.exit(1);
+  }
+  const txt = fs.readFileSync(skel, "utf8").replace(/\{\{ADR_NUM\}\}/g, num).replace(/\{\{ADR_TITLE\}\}/g, title);
+  fs.writeFileSync(dest, txt);
+  console.log(`✓ Đã tạo ${path.relative(CWD, dest)}`);
+}
+
+function skill() {
+  const raw = args.slice(1).find((a) => a && !a.startsWith("-"));
+  if (!raw) {
+    console.error("✗ Thiếu tên. Dùng: agent-kb skill <area>/<tên>  (vd: backend/payment)");
+    process.exit(1);
+  }
+  const skillsDir = path.join(CWD, ".ai", "skills");
+  if (!fs.existsSync(skillsDir)) {
+    console.error("✗ Chưa thấy .ai/skills — chạy `agent-kb init` trước.");
+    process.exit(1);
+  }
+  const skel = path.join(TEMPLATE_DIR, "_skill-skeleton.md");
+  const parts = raw.trim().split("/").map((s) => s.trim()).filter(Boolean);
+  const nameRaw = parts.pop();
+  const areaParts = parts.map(slugify);
+  const destDir = areaParts.length ? path.join(skillsDir, ...areaParts) : skillsDir;
+  fs.mkdirSync(destDir, { recursive: true });
+  const dest = path.join(destDir, slugify(nameRaw) + ".md");
+  if (fs.existsSync(dest) && !FORCE) {
+    console.error(`✗ ${path.relative(CWD, dest)} đã tồn tại (dùng --force).`);
+    process.exit(1);
+  }
+  const txt = fs.readFileSync(skel, "utf8").replace(/\{\{SKILL_NAME\}\}/g, nameRaw);
+  fs.writeFileSync(dest, txt);
+  console.log(`✓ Đã tạo ${path.relative(CWD, dest)}`);
+}
+
+async function agentCmd() {
+  const raw = args.slice(1).find((a) => a && !a.startsWith("-"));
+  if (!raw) {
+    console.error("✗ Thiếu tên. Dùng: agent-kb agent <tên> [--desc ..] [--tools ..] [--model ..]");
+    process.exit(1);
+  }
+  if (!fs.existsSync(path.join(CWD, ".ai"))) {
+    console.error("✗ Chưa thấy .ai — chạy `agent-kb init` trước.");
+    process.exit(1);
+  }
+  const skel = path.join(TEMPLATE_DIR, "_agent-skeleton.md");
+  const agentsDir = path.join(CWD, ".ai", "agents");
+  const name = slugify(raw);
+  const dest = path.join(agentsDir, name + ".md");
+  if (fs.existsSync(dest) && !FORCE) {
+    console.error(`✗ .ai/agents/${name}.md đã tồn tại (dùng --force).`);
+    process.exit(1);
+  }
+
+  let desc = FLAG_DESC || "";
+  let tools = FLAG_TOOLS || "";
+  let model = FLAG_MODEL || "";
+  if (!YES && !FLAG_DESC) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    desc = await ask(rl, "Mô tả (khi nào dùng agent này)", desc);
+    tools = await ask(rl, "Tools", tools || "Read, Grep, Glob, Bash");
+    model = await ask(rl, "Model (Enter = kế thừa)", model);
+    rl.close();
+  }
+  if (!desc) desc = "<!-- mô tả khi nào dùng agent này -->";
+  if (!tools) tools = "Read, Grep, Glob, Bash";
+
+  let txt = fs
+    .readFileSync(skel, "utf8")
+    .replace(/\{\{AGENT_NAME\}\}/g, name)
+    .replace(/\{\{AGENT_DESC\}\}/g, desc)
+    .replace(/\{\{AGENT_TOOLS\}\}/g, tools);
+  if (model) txt = txt.replace(/^(tools: .*)$/m, `$1\nmodel: ${model}`);
+
+  fs.mkdirSync(agentsDir, { recursive: true });
+  fs.writeFileSync(dest, txt);
+  const emitDir = path.join(CWD, ".claude", "agents");
+  fs.mkdirSync(emitDir, { recursive: true });
+  fs.copyFileSync(dest, path.join(emitDir, name + ".md"));
+
+  console.log(`✓ Đã tạo .ai/agents/${name}.md → emit .claude/agents/${name}.md`);
+  console.log("  Nguồn chân lý là .ai/agents/; sửa ở đó rồi chạy lại `agent-kb init` để đồng bộ.");
+}
+
+function doctor() {
+  if (!fs.existsSync(path.join(CWD, ".ai"))) {
+    console.error("✗ Chưa có .ai/ — chạy `agent-kb init` trước.");
+    process.exit(1);
+  }
+  const oks = [];
+  const warnings = [];
+  const problems = [];
+
+  const need = (rel) => {
+    if (fs.existsSync(path.join(CWD, rel))) oks.push(rel);
+    else problems.push(`Thiếu ${rel}`);
+  };
+  ["AGENTS.md", ".ai/core/tech-stack.md", ".ai/core/coding-standards.md", ".ai/core/glossary.md"].forEach(need);
+
+  for (const f of ["AGENTS.md", ".ai/core/tech-stack.md", ".ai/skills/devops/deployment.md"]) {
+    const p = path.join(CWD, f);
+    if (fs.existsSync(p) && /\{\{[A-Z_]+\}\}/.test(fs.readFileSync(p, "utf8"))) {
+      warnings.push(`${f} còn token {{...}} chưa thay (chạy lại init --force hoặc điền tay)`);
+    }
+  }
+
+  const ag = path.join(CWD, "AGENTS.md");
+  if (fs.existsSync(ag)) {
+    const n = (fs.readFileSync(ag, "utf8").match(new RegExp(BEGIN, "g")) || []).length;
+    if (n === 0) warnings.push("AGENTS.md không có block agent-kb");
+    else if (n > 1) problems.push(`AGENTS.md có ${n} block agent-kb (trùng) — nên chỉ còn 1`);
+  }
+
+  // Tool đang bật nhưng pointer thiếu (chỉ cảnh báo những tool đã có file)
+  for (const [t, dest] of Object.entries(OPTIONAL_TOOLS)) {
+    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/
+  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)`);
+    }
+  }
+
+  oks.forEach((o) => console.log("  ✓ " + o));
+  warnings.forEach((w) => console.log("  ⚠ " + w));
+  problems.forEach((p) => console.error("  ✗ " + p));
+
+  if (problems.length) {
+    console.error(`\n✗ doctor: ${problems.length} lỗi, ${warnings.length} cảnh báo.`);
+    process.exit(1);
+  }
+  console.log(`\n✓ doctor: OK${warnings.length ? ` (${warnings.length} cảnh báo)` : ""}.`);
+}
+
+function stripBlocks(txt) {
+  return txt.replace(new RegExp(`${BEGIN}[\\s\\S]*?${END}\\n?`, "g"), "").trim();
+}
+
+function importCmd() {
+  const ag = path.join(CWD, "AGENTS.md");
+  if (!fs.existsSync(ag)) {
+    console.error("✗ Chưa có AGENTS.md — chạy `agent-kb init` trước.");
+    process.exit(1);
+  }
+  const sources = [".cursorrules", ".clinerules", ".windsurfrules", ".rules", "CONVENTIONS.md", "CLAUDE.md", "GEMINI.md", path.join(".github", "copilot-instructions.md")];
+  let agText = fs.readFileSync(ag, "utf8");
+  const added = [];
+  for (const src of sources) {
+    const p = path.join(CWD, src);
+    if (!fs.existsSync(p) || path.resolve(p) === path.resolve(ag)) continue;
+    const content = stripBlocks(fs.readFileSync(p, "utf8"));
+    if (!content) continue; // chỉ là block agent-kb → bỏ
+    const marker = `<!-- IMPORTED:${src} -->`;
+    if (agText.includes(marker)) continue; // đã import trước đó
+    agText = agText.replace(/\s*$/, "\n\n") + `## Nội dung import từ \`${src}\`\n${marker}\n${content}\n`;
+    added.push(src);
+  }
+  if (!added.length) {
+    console.log("Không có nội dung mới để import (các file rule khác đều trống hoặc đã import).");
+    return;
+  }
+  fs.writeFileSync(ag, agText);
+  console.log(`✓ Đã import vào AGENTS.md từ: ${added.join(", ")}`);
+  console.log("  Hãy rà soát, gộp vào router/Tier-1 cho gọn, rồi xoá file gốc nếu muốn.");
+}
+
+function mcp() {
+  if (args[1] !== "add") {
+    console.error("Dùng: agent-kb mcp add <name> -c <command> [-a arg1,arg2]");
+    process.exit(1);
+  }
+  const name = args.slice(2).find((a) => a && !a.startsWith("-"));
+  const command = flag("-c") || flag("--command");
+  const argsCsv = flag("-a") || flag("--args");
+  if (!name || !command) {
+    console.error("✗ Thiếu name hoặc command. Vd: agent-kb mcp add github -c npx -a @org/mcp,serve");
+    process.exit(1);
+  }
+  const p = path.join(CWD, ".mcp.json");
+  const json = readJSONSafe(p) || { mcpServers: {} };
+  if (!json.mcpServers) json.mcpServers = {};
+  if (json.mcpServers[name] && !FORCE) {
+    console.error(`✗ MCP server '${name}' đã có trong .mcp.json (dùng --force để ghi đè).`);
+    process.exit(1);
+  }
+  json.mcpServers[name] = { command, args: argsCsv ? argsCsv.split(",").map((s) => s.trim()) : [] };
+  fs.writeFileSync(p, JSON.stringify(json, null, 2) + "\n");
+  console.log(`✓ Đã thêm MCP server '${name}' vào .mcp.json`);
+}
+
+function installHook(fromInit) {
+  const gitDir = path.join(CWD, ".git");
+  if (!fs.existsSync(gitDir)) {
+    if (fromInit) {
+      console.log("↷ Bỏ qua --hook: thư mục không phải git repo.");
+      return;
+    }
+    console.error("✗ Không phải git repo (.git không tồn tại).");
+    process.exit(1);
+  }
+  const hooksDir = path.join(gitDir, "hooks");
+  fs.mkdirSync(hooksDir, { recursive: true });
+  const dest = path.join(hooksDir, "pre-commit");
+  const line = "npx --yes @dtd-dev/agent-kb doctor || { echo 'agent-kb doctor báo lỗi (commit với --no-verify để bỏ qua)'; exit 1; }";
+  if (fs.existsSync(dest)) {
+    const cur = fs.readFileSync(dest, "utf8");
+    if (cur.includes("agent-kb doctor")) {
+      console.log("Hook đã có sẵn.");
+      return;
+    }
+    fs.writeFileSync(dest, cur.replace(/\s*$/, "\n") + `\n# agent-kb\n${line}\n`);
+  } else {
+    fs.writeFileSync(dest, `#!/bin/sh\n# agent-kb pre-commit\n${line}\n`);
+  }
+  fs.chmodSync(dest, 0o755);
+  console.log("✓ Đã cài git pre-commit hook (chạy agent-kb doctor).");
+}
+
+function help() {
+  console.log(`agent-kb — scaffold .ai/ knowledge base + agent config (đa tool, tiết kiệm token)
+
+Lệnh:
+  agent-kb [init]          Khởi tạo (tương tác; -y để dùng mặc định, -f để ghi đè)
+  agent-kb feature <tên>   Tạo .ai/specs/<tên>/ từ khung trống
+  agent-kb adr <tiêu đề>   Tạo ADR mới trong .ai/decisions/ (tự đánh số)
+  agent-kb skill <a>/<tên> Tạo skill mới trong .ai/skills/<a>/
+  agent-kb agent <tên>     Tạo sub-agent (.ai/agents/ → emit .claude/agents/)
+  agent-kb doctor          Kiểm tra & audit KB (thoát mã ≠0 nếu có lỗi)
+  agent-kb import          Gom nội dung rule cũ (.cursorrules, CLAUDE.md...) vào AGENTS.md
+  agent-kb mcp add <name>  Thêm MCP server vào .mcp.json (-c command [-a args])
+  agent-kb hook install    Cài git pre-commit hook chạy doctor
+  agent-kb help            Hiện trợ giúp
+
+Cờ cho init:
+  --name <tên>        Tên dự án            --database <db>    Database
+  --backend <stack>   Backend              --cicd <ci>        CI/CD
+  --frontend <stack>  Frontend             --deploy <lệnh>    Lệnh deploy
+  --tools <list|all>  Bật tool: cursor,windsurf,cline,zed,aider
+  --stack <list>      Gói chuẩn stack: ${availableStacks().join(",") || "(none)"}
+  --hook              Cài luôn git pre-commit hook
+  -y, --yes           Không hỏi (tự nhận diện stack)   -f, --force  Ghi đè
+
+Cờ cho 'agent':
+  --desc <mô tả>      Khi nào dùng agent     --tools <list>   Tools (vd "Read,Grep,Bash")
+  --model <model>     Model (Enter = kế thừa)
+`);
+}
+
+(async () => {
+  try {
+    if (cmd === "help" || args.includes("-h") || args.includes("--help")) return help();
+    if (cmd === "init") return await init();
+    if (cmd === "feature") return feature();
+    if (cmd === "adr") return adr();
+    if (cmd === "skill") return skill();
+    if (cmd === "agent") return await agentCmd();
+    if (cmd === "doctor") return doctor();
+    if (cmd === "import") return importCmd();
+    if (cmd === "mcp") return mcp();
+    if (cmd === "hook") return installHook(false);
+    console.error(`Lệnh không rõ: ${cmd}\n`);
+    help();
+    process.exit(1);
+  } catch (e) {
+    console.error("✗ Lỗi:", e.message);
+    process.exit(1);
+  }
+})();

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@dtd-dev/agent-kb",
+  "version": "0.1.0",
+  "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"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "agent-skills",
+    "agents",
+    "knowledge-base",
+    "token-efficient",
+    "code-accuracy",
+    "enterprise",
+    "business-domain",
+    "scaffold",
+    "monorepo",
+    "claude",
+    "cursor",
+    "copilot",
+    "gemini",
+    "agents.md"
+  ],
+  "license": "MIT"
+}