@dtd-dev/agent-kb 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# agent-kb
+
+Scaffold một **AI knowledge base tiết kiệm token** (`.ai/`) + cấu hình agent đa-tool
+(`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`) vào bất kỳ dự án nào,
+chỉ bằng một lệnh.
+
+## Dùng nhanh
+
+```bash
+# Trong thư mục gốc repo:
+npx @dtd-dev/agent-kb            # tương tác: hỏi tên dự án + stack
+npx @dtd-dev/agent-kb init -y    # dùng mặc định, không hỏi
+```
+
+Không cài global, không cần clone. Zero-dependency nên `npx` chạy tức thì.
+
+## Lệnh & cờ
+
+| Lệnh | Tác dụng |
+|---|---|
+| `agent-kb` / `agent-kb init` | Khởi tạo (tương tác nếu chạy trong terminal); tự nhận diện stack |
+| `agent-kb feature <tên>` | Tạo nhanh `.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 <area>/<tên>` | Tạo skill mới trong `.ai/skills/<area>/` |
+| `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 → dùng cho CI/hook) |
+| `agent-kb import` | Gom rule cũ (`.cursorrules`, `CLAUDE.md`…) vào `AGENTS.md` |
+| `agent-kb mcp add <name> -c <cmd> [-a a,b]` | Thêm MCP server vào `.mcp.json` |
+| `agent-kb hook install` | Cài git pre-commit hook chạy `doctor` |
+| `-y`, `--yes` | Bỏ qua câu hỏi, dùng mặc định + stack tự nhận diện |
+| `-f`, `--force` | Ghi đè file đã tồn tại (mặc định KHÔNG ghi đè) |
+| `--name/--backend/--frontend/--database/--cicd/--deploy` | Điền sẵn từng phần, bỏ qua câu hỏi |
+| `--tools <list\|all>` | Bật tool phụ: `cursor,windsurf,cline,zed,aider` (file trỏ về AGENTS.md) |
+| `--stack <list>` | Kéo gói chuẩn: `go,node,python,react,java,rust,php` |
+| `--hook` | Cài luôn git pre-commit hook khi init |
+| `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**.
+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.
+
+Mặc định emit `AGENTS.md` + `CLAUDE.md` + `GEMINI.md` + `.github/copilot-instructions.md`. Thêm
+`--tools` để phủ Cursor/Windsurf/Cline/Zed/Aider — tất cả chỉ là file nhỏ **trỏ về `AGENTS.md`**.
+
+## Sub-agents của dự án
+Định nghĩa sub-agent (dùng chung cho team) ở `.ai/agents/*.md` — **nguồn chân lý**, được emit sang
+`.claude/agents/` cho Claude Code đọc. `init` ship sẵn 4 agent gắn workflow: `reviewer`, `tester`,
+`bug-fixer`, `feature-builder` (mỗi agent tự trỏ về `.ai/workflows`/`skills` tương ứng → mang đúng
+quy ước nghiệp vụ dự án).
+
+```bash
+agent-kb agent security-reviewer \
+  --desc "Soát lỗ hổng bảo mật theo chuẩn dự án" \
+  --tools "Read,Grep,Bash" --model sonnet
+```
+
+Sửa ở `.ai/agents/` rồi chạy lại `agent-kb init` để đồng bộ. Tool khác (Cursor/Codex/Gemini/Copilot)
+chưa có sub-agent dạng file nên hiện chỉ emit cho Claude Code.
+
+Ví dụ scriptable (CI, không treo vì tự nhận diện không phải terminal):
+
+```bash
+npx @dtd-dev/agent-kb init --name CarePay \
+  --backend "Go 1.22 + Chi" \
+  --frontend "React 18 + Vite + Firebase" \
+  --database "Firestore" \
+  --cicd "GitHub Actions" \
+  --deploy "firebase deploy --only functions,hosting"
+```
+
+## Tạo spec cho feature mới
+```bash
+npx @dtd-dev/agent-kb feature checkout      # tạo .ai/specs/checkout/ (4 file khung trống)
+```
+Sinh sẵn `requirements.md` / `design.md` / `api.md` / `test-cases.md` với khung trống,
+tiêu đề đã điền tên feature — khỏi copy thư mục `feature-a/` (ví dụ mẫu) bằng tay.
+
+## An toàn khi chạy lại
+- **File `.ai/*`**: mặc định **không ghi đè** — chạy lại chỉ bổ sung file còn thiếu, không đụng nội dung bạn đã điền.
+- **File agent-config** (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`): nếu đã tồn tại, nội dung agent-kb được **chèn/cập nhật trong block** `<!-- BEGIN agent-kb -->` … `<!-- END agent-kb -->` — phần ngoài block của bạn giữ nguyên, chạy lại không nhân đôi.
+- Muốn reset về template thì thêm `--force`.
+
+## Triết lý
+- `AGENTS.md` là **nguồn chân lý** duy nhất; `CLAUDE.md`/`GEMINI.md`/Copilot chỉ trỏ về nó.
+- `.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`.
+
+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
+```
+
+## 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.)
+
+MIT