claudify-agent 1.0.1 → 1.0.3

package/CLAUDE.md

@@ -35,6 +35,7 @@ After modifying code, execute local verification based on project stack:
 - **Next.js:** @.claude/skills/nextjs-guide/SKILL.md
 - **React:** @.claude/skills/react-guide/SKILL.md
 - **Python:** @.claude/skills/python-guide/SKILL.md
+- **Security (OWASP):** @.claude/skills/security-guide/SKILL.md
 - **Vite:** @.claude/skills/vite-guide/SKILL.md
 - **MCP Mastery:** @.claude/skills/mcp-mastery/SKILL.md
 - **Tool Selection:** @.claude/skills/tool-selection/SKILL.md

package/README.md

@@ -1,66 +1,105 @@
-# ⚡ claudify-agent
+<p align="center">
+  <h1 align="center">⚡ claudify-agent</h1>
+  <p align="center">
+    <strong>Enterprise-grade workflow & context optimization framework for Claude Code, Claude Desktop, and autonomous AI coding agents.</strong>
+  </p>
+  <p align="center">
+    <a href="https://www.npmjs.com/package/claudify-agent"><img src="https://img.shields.io/npm/v/claudify-agent.svg" alt="NPM Version" /></a>
+    <a href="https://www.npmjs.com/package/claudify-agent"><img src="https://img.shields.io/npm/dm/claudify-agent.svg" alt="NPM Downloads" /></a>
+    <a href="https://github.com/mytoandeptrai/claudify-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" /></a>
+  </p>
+  <p align="center">
+    English | <a href="README.vi.md">Tiếng Việt</a>
+  </p>
+</p>
 
-> **Enterprise-grade workflow & context optimization framework for Claude Code, Claude Desktop, and autonomous AI coding agents.**
+---
+
+## 💡 Overview
 
-Inspired by research-backed agent instruction patterns, **claudify-agent** acts as the deterministic bridle and operating system for Claude: preventing context bloat, eliminating repetitive LLM token waste through zero-token local hooks, and enforcing systematic plan-first development.
+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.
+- **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**.
 
 ---
 
-## 🚀 Quick Install via NPX
+## 📦 Quick Start
 
-Không cần cài đặt rườm rà. Tại bất kỳ dự án mới hoặc có sẵn nào của bạn, chỉ cần mở terminal và chạy:
+Initialize `claudify-agent` into any existing repository or new project with a single command:
 
 ```bash
 npx claudify-agent init
 ```
 
-Lệnh này sẽ tự động khởi tạo:
-- `CLAUDE.md`: File điều phối trung tâm tự động nạp bởi Claude Code CLI.
-- `.claude/skills/`: Kho 12 cẩm nang chuyên sâu (Golang, NestJS, Concurrency/Locking, Solidity, Next.js, React...).
-- `.claude/rules/`: 13 bộ luật tối ưu phân tầng ngữ cảnh (< 20 dòng/rule).
-- `.claude/scripts/`: Hệ thống tự kiểm tra cú pháp, typecheck, và bảo mật tốn 0 token.
+This bootstraps:
+- `CLAUDE.md`: The central root steering file auto-loaded by Claude Code CLI.
+- `.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/scripts/`: Local multi-language verification suite (`auto-validate.js`, `security-scan.js`).
 
 ---
 
-## 📖 Hướng Dẫn Sử Dụng Chi Tiết (How to Use)
+## 🚀 How to Use
 
-### Cách 1: Dùng với Claude Code CLI (Khuyên Dùng Nhất 🚀)
-
-Sau khi chạy `npx claudify-agent init`, chỉ cần mở terminal và gõ:
+### 1. With Claude Code CLI (Recommended)
+After running `npx claudify-agent init`, open your terminal in the project root and launch Claude:
 ```bash
 claude
 ```
-👉 Claude Code CLI sẽ tự động phát hiện và tuân thủ toàn bộ quy tắc trong `CLAUDE.md`:
-- Tự động lập **Plan Mode** trước khi sửa từ 2 file trở lên.
-- Tự động tra cứu kỹ năng chuyên biệt khi đụng tới backend Go, NestJS, hoặc Smart Contract.
-- Tự chạy kiểm tra local sau khi code xong.
+Claude Code automatically discovers `CLAUDE.md`. All guardrails, tiered rules, and verification loops run seamlessly in the background.
 
-### Cách 2: Dùng với Claude Desktop / Claude Projects
+### 2. With Claude Desktop / Claude Projects
+1. Open **Claude Desktop** and create a new **Project** pointing to your workspace.
+2. Copy the content of [`CLAUDE.md`](CLAUDE.md) into the **Custom Instructions** box.
+3. Attach the `.claude/` directory to Project Knowledge for on-demand skill retrieval.
 
-1. Mở **Claude Desktop** $\rightarrow$ Tạo **Project** mới trỏ vào thư mục code.
-2. Dán nội dung của [CLAUDE.md](CLAUDE.md) vào ô **Custom Instructions**.
-3. Thêm thư mục `.claude/` vào Project Files để Claude tra cứu khi cần.
+---
+
+## 🧠 Architecture & ReAct Loop
+
+```mermaid
+graph TD
+    User["Developer Prompt"] --> Claude["Claude Code CLI"]
+    Claude --> RootCheck["CLAUDE.md<br>(Sub-20 Line Minimalist Guardrails)"]
+    RootCheck --> PlanCheck{"Modifying >= 2 Files?"}
+    PlanCheck -- "Yes" --> Plan["1. Produce Concise Plan<br>& Await Confirmation"]
+    PlanCheck -- "No" --> Execute["2. Targeted Execution"]
+    Plan --> Execute
+    Execute --> LocalChecks{"3. Local Verification Loop<br>(Zero Tokens Spent)"}
+    LocalChecks -->|"Format / Syntax"| ESLint["Local ESLint auto-fix"]
+    LocalChecks -->|"Type Safety"| TSC["Local tsc --noEmit"]
+    LocalChecks -->|"Go / Solidity"| Compiler["go vet / forge test"]
+    LocalChecks -->|"Security"| SecScan["Local Secret Scan"]
+    ESLint --> Done["✅ Clean, Verified Output"]
+    TSC --> Done
+    Compiler --> Done
+    SecScan --> Done
+```
 
 ---
 
-## 🛠️ Kho Kỹ Năng Đầy Đủ (Included 12 Skills)
+## 🛠️ Included 12 Production Skills
 
-| Kỹ Năng | Đường dẫn | Trọng tâm giải quyết |
+| Skill | Path | Focus Area |
 | :--- | :--- | :--- |
-| **Backend Concurrency** | `.claude/skills/backend-concurrency/SKILL.md` | Chống Race conditions, Distributed Lock (Redis), Deadlock, Idempotency. |
-| **Golang Backend** | `.claude/skills/golang-guide/SKILL.md` | Standard layout (`cmd/`, `internal/`), Worker Pool, Safe Goroutines, Context. |
-| **NestJS Enterprise** | `.claude/skills/nestjs-guide/SKILL.md` | Module boundaries, TypeORM Transaction QueryRunner, DTO Validation. |
-| **Solidity (Smart Contracts)** | `.claude/skills/solidity-guide/SKILL.md` | Mẫu CEI, ReentrancyGuard, tối ưu Gas EVM, Foundry/Hardhat tests. |
-| **Next.js Guide** | `.claude/skills/nextjs-guide/SKILL.md` | App Router, Server Components & Server Actions. |
+| **Backend Concurrency** | `.claude/skills/backend-concurrency/SKILL.md` | Race conditions, Distributed Redis Lock, Deadlocks, Idempotency. |
+| **Golang Backend** | `.claude/skills/golang-guide/SKILL.md` | Standard project layout, Worker Pools, Concurrency safety, Context. |
+| **NestJS Enterprise** | `.claude/skills/nestjs-guide/SKILL.md` | Clean module boundaries, TypeORM QueryRunner transactions, DTO safety. |
+| **Solidity Smart Contracts** | `.claude/skills/solidity-guide/SKILL.md` | CEI pattern, ReentrancyGuard, EVM gas optimization, Foundry tests. |
+| **Next.js Guide** | `.claude/skills/nextjs-guide/SKILL.md` | App Router, React Server Components (RSC), and Server Actions. |
 | **React Guide** | `.claude/skills/react-guide/SKILL.md` | Single Source of Truth, render optimization & Custom Hooks. |
 | **Python Guide** | `.claude/skills/python-guide/SKILL.md` | FastAPI, Django, Type hints & Pydantic. |
-| **MCP Mastery** | `.claude/skills/mcp-mastery/SKILL.md` | Kết nối và sử dụng các Model Context Protocol servers. |
-| **Debug Optimizer** | `.claude/skills/debug-optimizer/SKILL.md` | Quy trình truy tìm nguyên nhân gốc rễ (Root Cause) 4 bước. |
-| **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 có hệ thống trước khi gõ code. |
-| **Vite Guide** | `.claude/skills/vite-guide/SKILL.md` | Cấu hình bundling SPA tối ưu hiệu năng. |
+| **MCP Mastery** | `.claude/skills/mcp-mastery/SKILL.md` | Model Context Protocol configuration and tool calling patterns. |
+| **Debug Optimizer** | `.claude/skills/debug-optimizer/SKILL.md` | 4-step systematic root-cause debugging protocol. |
+| **Security Guide** | `.claude/skills/security-guide/SKILL.md` | OWASP Top 10: secrets, injection, auth checks, input validation. |
+| **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. |
 
 ---
 
 ## 📄 License
-MIT © [mytoandeptrai](https://github.com/mytoandeptrai)
+
+MIT © [jacob-tech](https://github.com/mytoandeptrai)

package/README.vi.md

@@ -0,0 +1,106 @@
+<p align="center">
+  <h1 align="center">⚡ claudify-agent</h1>
+  <p align="center">
+    <strong>Framework tối ưu hóa ngữ cảnh và quy trình làm việc chuẩn doanh nghiệp cho Claude Code, Claude Desktop và các AI Coding Agent tự chủ.</strong>
+  </p>
+  <p align="center">
+    <a href="https://www.npmjs.com/package/claudify-agent"><img src="https://img.shields.io/npm/v/claudify-agent.svg" alt="NPM Version" /></a>
+    <a href="https://www.npmjs.com/package/claudify-agent"><img src="https://img.shields.io/npm/dm/claudify-agent.svg" alt="NPM Downloads" /></a>
+    <a href="https://github.com/mytoandeptrai/claudify-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License" /></a>
+  </p>
+  <p align="center">
+    <a href="README.md">English</a> | Tiếng Việt
+  </p>
+</p>
+
+---
+
+## 💡 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`.
+- **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.
+
+---
+
+## 📦 Khởi Tạo Nhanh (Quick Start)
+
+Khởi tạo `claudify-agent` vào bất kỳ dự án mới hoặc có sẵn nào chỉ bằng 1 dòng lệnh duy nhất:
+
+```bash
+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/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/scripts/`: Bộ công cụ tự động kiểm tra code đa ngôn ngữ (`auto-validate.js`, `security-scan.js`).
+
+---
+
+## 🚀 Hướng Dẫn Sử Dụng
+
+### 1. Dùng với Claude Code CLI (Khuyên dùng nhất)
+Sau khi chạy `npx claudify-agent init`, mở terminal tại thư mục dự án và gõ:
+```bash
+claude
+```
+Claude Code sẽ tự động nhận diện `CLAUDE.md`. Toàn bộ luật bảo vệ, phân tầng ngữ cảnh và chuỗi kiểm tra tự động sẽ chạy ngầm mà không cần cấu hình thêm.
+
+### 2. Dùng với Claude Desktop / Claude Projects
+1. Mở **Claude Desktop** $\rightarrow$ Tạo một **Project** trỏ vào thư mục code của bạn.
+2. Sao chép toàn bộ nội dung file [`CLAUDE.md`](CLAUDE.md) dán vào ô **Custom Instructions**.
+3. Đính kèm thư mục `.claude/` vào Project Files để Claude tra cứu kỹ năng khi cần.
+
+---
+
+## 🧠 Kiến Trúc Hoạt Động (ReAct Loop)
+
+```mermaid
+graph TD
+    User["Developer Prompt"] --> Claude["Claude Code CLI"]
+    Claude --> RootCheck["CLAUDE.md<br>(Sub-20 Line Minimalist Guardrails)"]
+    PlanCheck{"Sửa >= 2 Files?"}
+    RootCheck --> PlanCheck
+    PlanCheck -- "Có" --> Plan["1. Lập Plan Chi Tiết<br>& Chờ Duyệt"]
+    PlanCheck -- "Không" --> Execute["2. Thực Thi Targeted Code"]
+    Plan --> Execute
+    Execute --> LocalChecks{"3. Chuỗi Kiểm Tra Local<br>(Tốn 0 LLM Token)"}
+    LocalChecks -->|"Format / Cú pháp"| ESLint["Tự chạy ESLint fix"]
+    LocalChecks -->|"Type Safety"| TSC["Tự chạy tsc --noEmit"]
+    LocalChecks -->|"Go / Solidity"| Compiler["go vet / forge test"]
+    LocalChecks -->|"Bảo mật"| SecScan["Quét rò rỉ Secret"]
+    ESLint --> Done["✅ Code Sạch & Đã Kiểm Thử"]
+    TSC --> Done
+    Compiler --> Done
+    SecScan --> Done
+```
+
+---
+
+## 🛠️ Danh Mục 12 Kỹ Năng Đính Kèm
+
+| Kỹ Năng | Đường Dẫn | Trọng Tâm Giải Quyết |
+| :--- | :--- | :--- |
+| **Backend Concurrency** | `.claude/skills/backend-concurrency/SKILL.md` | Xử lý Race conditions, Redis Distributed Lock, Deadlocks, Idempotency. |
+| **Golang Backend** | `.claude/skills/golang-guide/SKILL.md` | Standard layout (`cmd/`, `internal/`), Worker Pool, Safe Goroutines, Context. |
+| **NestJS Enterprise** | `.claude/skills/nestjs-guide/SKILL.md` | Module boundaries, TypeORM Transaction QueryRunner, DTO Validation. |
+| **Solidity Smart Contracts** | `.claude/skills/solidity-guide/SKILL.md` | Mô hình CEI, ReentrancyGuard, tối ưu Gas EVM, Foundry/Hardhat tests. |
+| **Next.js Guide** | `.claude/skills/nextjs-guide/SKILL.md` | App Router, Server Components (RSC), và Server Actions. |
+| **React Guide** | `.claude/skills/react-guide/SKILL.md` | Single Source of Truth, tối ưu Render & Custom Hooks. |
+| **Python Guide** | `.claude/skills/python-guide/SKILL.md` | FastAPI, Django, Type hints & Pydantic. |
+| **MCP Mastery** | `.claude/skills/mcp-mastery/SKILL.md` | Cấu hình và gọi các Model Context Protocol servers. |
+| **Debug Optimizer** | `.claude/skills/debug-optimizer/SKILL.md` | Quy trình truy tìm nguyên nhân gốc rễ (Root Cause) 4 bước. |
+| **Security Guide** | `.claude/skills/security-guide/SKILL.md` | OWASP Top 10: quản lý secrets, chống injection, phân quyền, validate input. |
+| **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. |
+
+---
+
+## 📄 Bản Quyền
+
+Phát hành dưới giấy phép MIT © [jacob-tech](https://github.com/mytoandeptrai)

package/bin/cli.js

@@ -7,7 +7,7 @@
 
 import { fileURLToPath } from 'url';
 import { dirname, join, resolve } from 'path';
-import { cp, access } from 'fs/promises';
+import { cp } from 'fs/promises';
 import { existsSync } from 'fs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -28,9 +28,18 @@ if (command === 'init') {
     await cp(join(packageRoot, 'CLAUDE.md'), join(targetDir, 'CLAUDE.md'));
     console.log('  ✅ Created CLAUDE.md (Root agent instruction guidelines)');
 
-    // 2. Copy .claude folder
-    await cp(join(packageRoot, '.claude'), join(targetDir, '.claude'), { recursive: true });
-    console.log('  ✅ Created .claude/ (Skills and automated verification scripts)');
+    // 2. Copy .claude folder (never overwrite the project's own settings.json)
+    const settingsSrc = join(packageRoot, '.claude', 'settings.json');
+    const settingsDest = join(targetDir, '.claude', 'settings.json');
+    const keepSettings = existsSync(settingsDest);
+    await cp(join(packageRoot, '.claude'), join(targetDir, '.claude'), {
+      recursive: true,
+      filter: (src) => !(keepSettings && src === settingsSrc),
+    });
+    console.log('  ✅ Created .claude/ (Skills, rules and Claude Code hooks)');
+    if (keepSettings) {
+      console.log(`  ⚠️  Kept your existing .claude/settings.json — merge the "hooks" block from ${settingsSrc} manually.`);
+    }
 
     console.log('\n🎉 Successfully initialized Claudify!');
     console.log('👉 Next Steps:');

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "claudify-agent",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Enterprise-grade workflow & context optimization framework for Claude Code, Claude Desktop, and AI coding agents.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mytoandeptrai/claudify-agent.git"
+  },
   "type": "module",
   "main": "bin/cli.js",
   "bin": {
@@ -42,5 +46,13 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.6.6",
+    "eslint": "^10.14.0",
+    "globals": "^17.14.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.72.1"
   }
 }

package/.claude/skills/debug-optimizer.md

@@ -1,12 +0,0 @@
-# Root Cause Debugging & Troubleshooting
-
-## 4-Step Systematic Debugging Protocol
-1. **Reproduce & Isolate:** Recreate the exact failure case with minimal reproduction code or single targeted test.
-2. **Inspect & Trace:** Check actual runtime logs, stack traces, and variable states instead of guessing.
-3. **Hypothesize & Form Minimal Fix:** Identify the root mechanism causing the breakdown. Form the smallest possible diff that completely fixes the issue.
-4. **Regression Prevention:** Add a targeted regression test confirming the bug is dead and adjacent modules remain intact.
-
-## Anti-Patterns
-- ❌ Do NOT randomly wrap code in `try-catch` blocks without handling or logging errors.
-- ❌ Do NOT suppress TypeScript compiler errors with `@ts-ignore` or `as any`.
-- ❌ Do NOT write sprawling test fixtures when a focused unit test suffices.

package/.claude/skills/nextjs.md

@@ -1,13 +0,0 @@
-# Next.js 14+ / App Router Mastery Skill
-
-## Core Principles
-1. **Server Components by Default:** Keep components as React Server Components (RSC) unless interactivity (hooks, state, browser events) is strictly required.
-2. **Client Components Boundary:** Push `'use client'` to the leaf nodes of the component tree to maximize server-side performance.
-3. **Data Fetching:** Fetch data directly inside Server Components using async/await. Avoid `useEffect` for data loading.
-4. **Server Actions:** Use Server Actions for mutations. Always validate incoming inputs with Zod before database operations.
-5. **Route Handlers:** Place API endpoints in `app/api/[route]/route.ts`. Return typed `NextResponse.json(...)`.
-
-## Anti-Patterns to Avoid
-- ❌ Do NOT add `'use client'` to top-level page components (`page.tsx`) just to use a small client button.
-- ❌ Do NOT leak secrets or database queries into Client Components.
-- ❌ Do NOT use `router.refresh()` in loops.

package/.claude/skills/react.md

@@ -1,12 +0,0 @@
-# React & State Management Mastery
-
-## Architecture Rules
-1. **Single Source of Truth:** Keep state as close to where it is consumed as possible.
-2. **State Elevation:** Only elevate state to global store (Zustand, Context) when shared across distant siblings.
-3. **Pure Components:** Keep rendering pure. Side effects belong strictly in `useEffect` or event handlers.
-4. **Custom Hooks:** Extract reusable component logic and state handling into `use[Feature]` custom hooks.
-
-## Performance Checklist
-- Memoize expensive calculations with `useMemo`.
-- Avoid premature optimization; profile render frequency before adding `useCallback` everywhere.
-- Always provide stable, unique `key` props (never use array index for dynamic/reorderable lists).