claudify-agent 1.0.7 → 1.0.9

package/README.md

@@ -18,7 +18,7 @@
 ## 💡 Overview
 
 Inspired by empirical research on autonomous agent failure modes, **`claudify-agent`** acts as the deterministic bridle and operating system for Claude:
-- **Prevents Context Bloat & Token Snowball:** Eliminates token waste and context rot by enforcing sub-20 line rules and on-demand `@path` modular skill loading.
+- **Prevents Context Bloat & Token Snowball:** Eliminates token waste and context rot by enforcing sub-20 line rules and on-demand modular skill loading (plain path references).
 - **Plan-First Mandate:** Obligates Claude to formulate an explicit execution plan before modifying two or more files.
 - **Zero-Token Local Verification:** Offloads formatting, ESLint corrections, typechecks, and security scans to local scripts rather than burning hundreds of thousands of tokens across LLM feedback loops.
 - **Production Backend & Web3 Ready:** Comprehensive guidelines for high-throughput **Golang**, enterprise **NestJS**, distributed **Concurrency & Locking**, and secure **Solidity Smart Contracts**.
@@ -34,9 +34,12 @@ npx claudify-agent init
 ```
 
 This bootstraps:
-- `CLAUDE.md`: The central root steering file auto-loaded by Claude Code CLI.
+- `CLAUDE.md`: The central root steering file auto-loaded by Claude Code CLI. If your project already has one, your content is kept and Claudify only adds/updates a block between `<!-- claudify:start -->` and `<!-- claudify:end -->`.
+- `BACKBONE.md`: Project map (overview, structure, docs index, capabilities, commands, invariants) loaded every session.
+- `spec/config.md`: Rules for writing feature specs.
+- `.claude/commands/`: Slash commands for the spec, backbone and learning workflow.
 - `.claude/rules/`: 13 context-tiered rules governing planning, execution, and security.
-- `.claude/skills/`: 12 on-demand domain skills (Golang, NestJS, Concurrency, Solidity, Next.js, etc.).
+- `.claude/skills/`: 15 on-demand domain skills (Golang, NestJS, Concurrency, Solidity, Next.js, etc.).
 - `.claude/scripts/`: Local multi-language verification suite (`auto-validate.js`, `security-scan.js`).
 
 ---
@@ -57,6 +60,86 @@ Claude Code automatically discovers `CLAUDE.md`. All guardrails, tiered rules, a
 
 ---
 
+## 🔁 Daily Workflow
+
+Three tools, each with one job:
+
+| Tool | Scope | When |
+|---|---|---|
+| `BACKBONE.md` | Whole project: what it is, where things live, which docs are current | Always loaded, every prompt |
+| `spec/` | One feature at a time | Only when you run `/spec-*` (non-trivial features) |
+| `/learn` | One mistake at a time | After you corrected the AI |
+
+### Commands
+
+| Command | What it does |
+|---|---|
+| `/backbone-init` | Scan the repo and draft `BACKBONE.md`. Run once per project. Shows a diff, writes after your approval. |
+| `/backbone-sync [area]` | After work done without specs (bug fixes, small features): diff the code since `Last synced`, compare with the backbone and `spec/specs/`, ask about gaps, update the backbone after approval. Never edits archived specs. |
+| `/spec-new <name> <goal>` | Draft ONE file `spec/changes/<name>.md`: Why, Scope/Non-goals, Requirements per capability (ADDED/MODIFIED/REMOVED + GIVEN/WHEN/THEN), Design, Risks, Tasks + DoD. ~800 words; proposes splitting big changes. No code. |
+| `/spec-apply <name> [task]` | Implement the next unchecked task, run its DoD, tick it. One task per call. |
+| `/spec-archive <name>` | Merge the requirements into `spec/specs/<capability>.md` (current truth), move the change to `spec/changes/archive/`, update the backbone. |
+| `/learn [lesson]` | Turn a correction into one rule in the right place (backbone invariant, skill `## Lessons`, or `.claude/rules/lessons.md`). Shows a diff first. |
+
+Bugs and trivial tasks: just prompt as usual. No spec needed.
+
+### Layout
+
+```
+BACKBONE.md                     ← project map (always loaded)
+spec/
+├── config.md                   ← how to write specs
+├── changes/
+│   ├── add-refund.md           ← in progress
+│   └── archive/2026-11-08-add-export.md   ← history
+└── specs/
+    └── data-export.md          ← current truth, merged on archive
+```
+
+### Example: a feature, end to end
+
+```text
+> /spec-new add-refund Users can request a refund for a failed order within 7 days
+
+AI: Reads BACKBONE.md (already in context), spec/config.md, spec/specs/orders.md.
+    Q: Partial refunds in scope? Who approves: auto or admin?
+You: Full refund only, auto-approve.
+AI: Wrote spec/changes/add-refund.md (640 words, 4 tasks). Added it to "Open changes".
+    Approve the tasks?
+
+> /spec-apply add-refund
+AI: Task 1 done: POST /orders/:id/refund + Zod schema.
+    Proof: npm run lint && npm run typecheck && npm test -> 42 passed. Next: task 2.
+
+(AI used float for the amount; you correct it)
+> /learn money is always integer cents, never float
+AI: Proposed diff in BACKBONE.md Invariants:
+    + - Money amounts are integer cents; never float.
+    Write it?   -> yes
+
+> /spec-archive add-refund
+AI: Merged 2 ADDED requirements into spec/specs/orders.md,
+    moved the change to spec/changes/archive/2026-11-08-add-refund.md,
+    updated Capabilities in BACKBONE.md.
+```
+
+### Example: after a bug fix without spec
+
+```text
+> fix: export CSV breaks on commas in names
+AI: Fixed + test. This added docs/csv-format.md, consider /backbone-sync.
+
+> /backbone-sync
+AI: 6 commits since a1b2c3d. Gaps:
+    - Docs index: docs/csv-format.md missing
+    - Commands: `npm run test:e2e` added in CI
+    Q: Is docs/export-v1.md still current? It contradicts src/export/csv.ts.
+You: outdated.
+AI: Diff for BACKBONE.md (+3 lines, Last synced: e4f5a6b). Write it?
+```
+
+---
+
 ## 🧠 Architecture & ReAct Loop
 
 ```mermaid
@@ -80,7 +163,7 @@ graph TD
 
 ---
 
-## 🛠️ Included 12 Production Skills
+## 🛠️ Included 15 Production Skills
 
 | Skill | Path | Focus Area |
 | :--- | :--- | :--- |
@@ -97,6 +180,8 @@ graph TD
 | **Tool Selection** | `.claude/skills/tool-selection/SKILL.md` | Decision matrix to minimize excessive LLM tool calls. |
 | **Plan Mastery** | `.claude/skills/plan-mode-mastery/SKILL.md` | Systematic research and execution planning before code generation. |
 | **Vite Guide** | `.claude/skills/vite-guide/SKILL.md` | Modern SPA build optimization and bundling practices. |
+| **Parallel Exploration** | `.claude/skills/parallel-exploration/SKILL.md` | 2-4 parallel read-only Explore subagents for broad discovery. |
+| **Learning Loop** | `.claude/skills/learning-loop/SKILL.md` | Detect anti-patterns from plan metrics and suggest rule updates. |
 
 ---
 

package/README.vi.md

@@ -18,7 +18,7 @@
 ## 💡 Tổng Quan
 
 Lấy cảm hứng từ các nghiên cứu thực nghiệm về thất bại của AI Agent khi viết code, **`claudify-agent`** đóng vai trò là "dây cương và hệ điều hành" cho Claude:
-- **Chống Tràn Ngữ Cảnh & Hiệu Ứng Tuyết Lăn (Context Snowball):** Triệt tiêu lãng phí token bằng nguyên tắc luật dưới 20 dòng và nạp modular skill theo nhu cầu thông qua cú pháp `@path`.
+- **Chống Tràn Ngữ Cảnh & Hiệu Ứng Tuyết Lăn (Context Snowball):** Triệt tiêu lãng phí token bằng nguyên tắc luật dưới 20 dòng và nạp modular skill theo nhu cầu qua tham chiếu đường dẫn thường.
 - **Bắt Buộc Lập Kế Hoạch (Plan-First):** Ép Claude phải xuất ra một kế hoạch (Plan) cụ thể trước khi được phép sửa từ 2 file trở lên.
 - **Xác Thực Cục Bộ Tốn 0 Token (Zero-Token Verification):** Đẩy toàn bộ việc sửa format, ESLint, kiểm tra type TypeScript và quét bảo mật cho các script local chạy trên máy tính thay vì đốt hàng trăm ngàn token qua các lượt chat lặp lại của AI.
 - **Sẵn Sàng Cho Production Backend & Web3:** Cung cấp sẵn các cẩm nang chuẩn cho hệ thống **Golang** hiệu năng cao, **NestJS** doanh nghiệp, xử lý **Concurrency & Khóa phân tán (Locking)**, và hợp đồng thông minh **Solidity** an toàn.
@@ -34,9 +34,12 @@ npx claudify-agent init
 ```
 
 Lệnh này sẽ tự động thiết lập:
-- `CLAUDE.md`: File điều phối trung tâm tự động được nạp bởi Claude Code CLI.
+- `CLAUDE.md`: File điều phối trung tâm tự động được nạp bởi Claude Code CLI. Nếu dự án đã có `CLAUDE.md`, nội dung của bạn được giữ nguyên; Claudify chỉ thêm/cập nhật khối nằm giữa `<!-- claudify:start -->` và `<!-- claudify:end -->`.
+- `BACKBONE.md`: Bản đồ dự án (tổng quan, cấu trúc, docs index, capabilities, lệnh, bất biến), nạp mỗi session.
+- `spec/config.md`: Quy tắc viết spec cho feature.
+- `.claude/commands/`: Slash command cho workflow spec, backbone và tự học từ lỗi.
 - `.claude/rules/`: 13 quy tắc phân tầng kiểm soát quá trình lập plan, thực thi và bảo mật.
-- `.claude/skills/`: 12 cẩm nang chuyên sâu theo từng công nghệ (Golang, NestJS, Concurrency, Solidity, Next.js...).
+- `.claude/skills/`: 15 cẩm nang chuyên sâu theo từng công nghệ (Golang, NestJS, Concurrency, Solidity, Next.js...).
 - `.claude/scripts/`: Bộ công cụ tự động kiểm tra code đa ngôn ngữ (`auto-validate.js`, `security-scan.js`).
 
 ---
@@ -57,6 +60,86 @@ Claude Code sẽ tự động nhận diện `CLAUDE.md`. Toàn bộ luật bảo
 
 ---
 
+## 🔁 Workflow Hằng Ngày
+
+Ba công cụ, mỗi cái một việc:
+
+| Công cụ | Phạm vi | Khi nào |
+|---|---|---|
+| `BACKBONE.md` | Toàn dự án: là gì, cái gì nằm đâu, docs nào còn đúng | Luôn được nạp, mọi prompt |
+| `spec/` | Từng feature | Chỉ khi bạn gõ `/spec-*` (feature không tầm thường) |
+| `/learn` | Từng lỗi | Sau khi bạn đã sửa lỗi của AI |
+
+### Các lệnh
+
+| Lệnh | Làm gì |
+|---|---|
+| `/backbone-init` | Quét repo và viết `BACKBONE.md`. Chạy 1 lần mỗi dự án. Cho xem diff, bạn duyệt mới ghi. |
+| `/backbone-sync [vùng]` | Sau khi làm việc không qua spec (fix bug, feature nhỏ): diff code từ `Last synced`, so với backbone và `spec/specs/`, hỏi chỗ thiếu, cập nhật backbone sau khi bạn duyệt. Không bao giờ sửa spec đã archive. |
+| `/spec-new <tên> <mục tiêu>` | Viết MỘT file `spec/changes/<tên>.md`: Why, Scope/Non-goals, Requirements theo capability (ADDED/MODIFIED/REMOVED + GIVEN/WHEN/THEN), Design, Risks, Tasks + DoD. ~800 từ; tự đề xuất tách change lớn. Không code. |
+| `/spec-apply <tên> [task]` | Làm task chưa tick tiếp theo, chạy DoD, tick. Mỗi lần một task. |
+| `/spec-archive <tên>` | Gộp requirements vào `spec/specs/<capability>.md` (sự thật hiện tại), chuyển change vào `spec/changes/archive/`, cập nhật backbone. |
+| `/learn [bài học]` | Biến lần sửa lỗi thành một rule đúng chỗ (bất biến trong backbone, `## Lessons` của skill, hoặc `.claude/rules/lessons.md`). Cho xem diff trước. |
+
+Fix bug và việc nhỏ: cứ prompt như bình thường, không cần spec.
+
+### Cấu trúc thư mục
+
+```
+BACKBONE.md                     ← bản đồ dự án (luôn nạp)
+spec/
+├── config.md                   ← cách viết spec
+├── changes/
+│   ├── add-refund.md           ← đang làm
+│   └── archive/2026-11-08-add-export.md   ← lịch sử
+└── specs/
+    └── data-export.md          ← sự thật hiện tại, gộp vào khi archive
+```
+
+### Ví dụ: một feature từ đầu tới cuối
+
+```text
+> /spec-new add-refund User được yêu cầu hoàn tiền cho order lỗi trong vòng 7 ngày
+
+AI: Đọc BACKBONE.md (đã có sẵn), spec/config.md, spec/specs/orders.md.
+    Hỏi: Có hoàn tiền một phần không? Ai duyệt: tự động hay admin?
+Bạn: Chỉ hoàn toàn bộ, tự động duyệt.
+AI: Đã viết spec/changes/add-refund.md (640 từ, 4 task). Đã thêm vào "Open changes".
+    Duyệt task list chứ?
+
+> /spec-apply add-refund
+AI: Task 1 xong: POST /orders/:id/refund + Zod schema.
+    Proof: npm run lint && npm run typecheck && npm test -> 42 passed. Tiếp: task 2.
+
+(AI dùng float cho số tiền; bạn bảo sửa)
+> /learn tiền luôn là số nguyên (cent), không bao giờ dùng float
+AI: Đề xuất diff trong Invariants của BACKBONE.md:
+    + - Số tiền là số nguyên (cent); không dùng float.
+    Ghi chứ?   -> có
+
+> /spec-archive add-refund
+AI: Đã gộp 2 requirement ADDED vào spec/specs/orders.md,
+    chuyển change vào spec/changes/archive/2026-11-08-add-refund.md,
+    cập nhật Capabilities trong BACKBONE.md.
+```
+
+### Ví dụ: sau khi fix bug không dùng spec
+
+```text
+> fix: export CSV bị vỡ khi tên có dấu phẩy
+AI: Đã sửa + thêm test. Có thêm docs/csv-format.md, nên chạy /backbone-sync.
+
+> /backbone-sync
+AI: 6 commit kể từ a1b2c3d. Chỗ thiếu:
+    - Docs index: chưa có docs/csv-format.md
+    - Commands: CI có thêm `npm run test:e2e`
+    Hỏi: docs/export-v1.md còn đúng không? Nó mâu thuẫn với src/export/csv.ts.
+Bạn: lỗi thời rồi.
+AI: Diff cho BACKBONE.md (+3 dòng, Last synced: e4f5a6b). Ghi chứ?
+```
+
+---
+
 ## 🧠 Kiến Trúc Hoạt Động (ReAct Loop)
 
 ```mermaid
@@ -81,7 +164,7 @@ graph TD
 
 ---
 
-## 🛠️ Danh Mục 12 Kỹ Năng Đính Kèm
+## 🛠️ Danh Mục 15 Kỹ Năng Đính Kèm
 
 | Kỹ Năng | Đường Dẫn | Trọng Tâm Giải Quyết |
 | :--- | :--- | :--- |
@@ -98,6 +181,8 @@ graph TD
 | **Tool Selection** | `.claude/skills/tool-selection/SKILL.md` | Chiến lược chọn đúng tool nhằm giảm thiểu số lần gọi API. |
 | **Plan Mastery** | `.claude/skills/plan-mode-mastery/SKILL.md` | Lập kế hoạch bài bản trước khi bắt đầu sinh code. |
 | **Vite Guide** | `.claude/skills/vite-guide/SKILL.md` | Cấu hình bundling SPA tối ưu hiệu năng. |
+| **Parallel Exploration** | `.claude/skills/parallel-exploration/SKILL.md` | Chạy 2-4 subagent Explore song song (chỉ đọc) để khảo sát rộng. |
+| **Learning Loop** | `.claude/skills/learning-loop/SKILL.md` | Phát hiện anti-pattern từ plan metrics và đề xuất cập nhật rule. |
 
 ---
 

package/bin/cli.js

@@ -7,9 +7,12 @@
 
 import { fileURLToPath } from 'url';
 import { dirname, join, resolve } from 'path';
-import { cp } from 'fs/promises';
+import { cp, readFile, writeFile } from 'fs/promises';
 import { existsSync } from 'fs';
 
+const BLOCK_START = '<!-- claudify:start (managed by `npx claudify init`, edits inside are overwritten) -->';
+const BLOCK_END = '<!-- claudify:end -->';
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const packageRoot = resolve(__dirname, '..');
@@ -24,9 +27,24 @@ if (command === 'init') {
   console.log(`📦 Initializing Claudify in: ${targetDir}`);
 
   try {
-    // 1. Copy CLAUDE.md
-    await cp(join(packageRoot, 'CLAUDE.md'), join(targetDir, 'CLAUDE.md'));
-    console.log('  ✅ Created CLAUDE.md (Root agent instruction guidelines)');
+    // 1. CLAUDE.md: keep the project's own content, manage only the Claudify block
+    const claudeMd = join(targetDir, 'CLAUDE.md');
+    const block = `${BLOCK_START}\n${(await readFile(join(packageRoot, 'CLAUDE.md'), 'utf-8')).trim()}\n${BLOCK_END}\n`;
+    if (!existsSync(claudeMd)) {
+      await writeFile(claudeMd, block);
+      console.log('  ✅ Created CLAUDE.md (Root agent instruction guidelines)');
+    } else {
+      const current = await readFile(claudeMd, 'utf-8');
+      const start = current.indexOf(BLOCK_START);
+      const end = current.indexOf(BLOCK_END);
+      if (start !== -1 && end > start) {
+        await writeFile(claudeMd, current.slice(0, start) + block + current.slice(end + BLOCK_END.length).replace(/^\n/, ''));
+        console.log('  ✅ Updated the Claudify block in CLAUDE.md (your own content untouched)');
+      } else {
+        await writeFile(claudeMd, `${current.trimEnd()}\n\n${block}`);
+        console.log('  ✅ Appended the Claudify block to your existing CLAUDE.md');
+      }
+    }
 
     // 2. Copy .claude folder (never overwrite the project's own settings.json)
     const settingsSrc = join(packageRoot, '.claude', 'settings.json');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudify-agent",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Enterprise-grade workflow & context optimization framework for Claude Code, Claude Desktop, and AI coding agents.",
   "repository": {
     "type": "git",