@xaviele/ag-kit 1.0.0 → 1.2.0

package/README.md

@@ -1,20 +1,107 @@
-# @xaviele/ag-kit
+# @xaviele/ag-kit (Antigravity Agent Kit)
 
-Antigravity Agent Kit - CLI tự động thêm bộ não AI với 45 kĩ năng vào dự án.
+🌎 **[English](#english-version) | 🇻🇳 [Tiếng Việt](#phiên-bản-tiếng-việt)**
 
-## Cài đặt
+---
 
-Sử dụng trực tiếp qua npx:
+## <a name="english-version"></a> 🇬🇧 English Version
+
+🚀 **Antigravity Agent Kit** is a powerful CLI utility that injects an advanced AI Agent workspace into any of your projects. Packed with **45 specialized skills**, **12 automated workflows**, and smart project configurations.
+
+### 📦 Quick Install
+
+Run directly via `npx` in your target project root folder to install the AI system:
 
 ```bash
 npx @xaviele/ag-kit init
 ```
 
-Hoặc force ghi đè nếu muốn update/làm sạch cái cũ:
+### 🎯 Specialized Commands
+
+| Command | Functionality | Description |
+|---------|---------------|-------------|
+| `init` | Core setup | Automatically generates the `.agent/` directory with the full core system. Use the `--force` flag to overwrite/reset. |
+| `add <skill>` | Add single skill | Swiftly inject any missing individual skill into an installed project (E.g.: `npx @xaviele/ag-kit add clean-code`). |
+| `update` | Safe Sync | Downloads the latest core Skills from the Master Repo but **STRICTLY PRESERVES** your current configurations (Rules, Architecture). |
+
+### 🛠️ What's inside the AI Brain?
+
+After installation, your `.agent` directory serves as the control center guiding the behavior of your AI Programming Assistants (Claude, Cursor, Gemini)... with 3 main architectural blocks:
+
+#### 1. 🧠 Skills (45 Skills)
+The Kit comes pre-loaded with numerous deep-expertise skills, acting as instruction manuals helping the AI behave like an expert Senior Engineer.
+*   **Frontend & Web:** React patterns, Tailwind v4, Mobile Design, Web Testing (Playwright), Waterfall fetching optimization.
+*   **System & Backend:** Database architecture logic, REST & GraphQL API design, Server Management, Deployment strategies.
+*   **Security & Metrics:** Standardized Clean Code, Vulnerability scanning, Red-team tactics, Core Web Vitals 2025.
+*   **Super Apps:** Blazing-fast Zalo Mini App capabilities, premium ZaUI interfaces, UI/UX Pro Max standards.
+
+#### 2. 🔄 Automated Workflows (12 Workflows)
+Slash-command shortcuts (like `/slash-commands`) standardizing your development lifecycle. For example:
+*   `/brainstorm`: Forces the AI to think and solve edge cases thoroughly before rushing into code.
+*   `/plan`: Demands the AI write an Implementation Plan File for components so you can approve it before execution.
+*   `/ui-ux-pro-max`: A specialized process preventing the AI from using outdated libraries, forcing Glassmorphism and smooth Gradient designs.
+*   `/test`: Automatically scours the Source Code to attach AAA-standard Unit/E2E tests.
+
+#### 3. 🛡️ Rules & Architecture
+The area establishing boundaries for the Assistant:
+*   `rules/`: Contains rules specific to you or your organization. (E.g., "Always explain in English," "Do not use Moment.js").
+*   `ARCHITECTURE.md` / `mcp_config.json`: Documentation noting your unique system architecture (The AI ecosystem scans these first to grasp the current Codebase context).
+
+### 🚀 Use Cases
+1. **Super App Initialization (e.g., Zalo Mini App):** Setup an empty project, install the Kit, and chat: *"Use `/ui-ux-pro-max` to design the Index screen"* -> The AI immediately complies with flat Mobile design standards and exact Styles.
+2. **Code & Architecture Review:** Use the `/orchestrate` workflow, and the AI will summon various Virtual Engineers (Frontend Specialist, Backend Architect, Security Auditor) to jointly review your repository's security.
+3. **Legacy Code Revival:** Drop the Kit into dusty code and chat: *"Clean up trash variables based on `clean-code` and `react-best-practices`"* -> The AI systematically refactors each file.
+
+---
+
+## <a name="phiên-bản-tiếng-việt"></a> 🇻🇳 Phiên bản Tiếng Việt
+
+🚀 **Antigravity Agent Kit** là một tiện ích dòng lệnh CLI mạnh mẽ giúp tự động cấy ghép Không gian làm việc Trợ lý AI nâng cao vào bất kỳ dự án nào của bạn. Gói bao gồm **45 kỹ năng chuyên môn**, **12 quy trình luồng làm việc tự động**, và các cấu hình dự án thông minh.
+
+### 📦 Cài đặt thao tác nhanh
+
+Chỉ cần chạy trực tiếp bằng lệnh `npx` ở thư mục gốc của dự án bạn muốn cài đặt hệ thống AI:
+
 ```bash
-npx @xaviele/ag-kit init --force
+npx @xaviele/ag-kit init
 ```
 
-## Tính năng
+### 🎯 Các lệnh Chuyên biệt
+
+| Lệnh | Tính năng | Mô tả chi tiết |
+|------|-----------|----------------|
+| `init` | Khởi tạo toàn bộ lõi | Tự động sinh mục `.agent/` với toàn bộ hệ thống gốc. Dùng cờ `--force` để cài đè (Reset). |
+| `add <skill>` | Thêm 1 kỹ năng lẻ | Bổ sung siêu tốc bất kỳ kỹ năng nào bị thiếu vào dự án đã cài đặt (VD: `npx @xaviele/ag-kit add clean-code`). |
+| `update` | Cập nhật đồng bộ | Tải các Kỹ năng gốc mới nhất từ Master Repo nhưng **BẢO TOÀN TUYỆT ĐỐI** các cài đặt (Rules, Cấu hình) của bạn hiện tại. |
+
+### 🛠️ Cấu trúc "Bộ não AI" có gì?
+
+Sau khi cài đặt xong, thư mục `.agent` của bạn sẽ đóng vai trò điều hướng mọi hành vi của Trợ lý lập trình AI (Claude, Cursor, Gemini)... với 3 khối kiến trúc chính:
+
+#### 1. 🧠 Kỹ năng (45 Skills)
+Bộ Kit chứa sẵn vô số kỹ năng chuyên môn sâu, đóng vai trò như cẩm nang hướng dẫn AI làm việc chuẩn xác như một kỹ sư chuyên nghiệp (Senior Engineer).
+*   **Frontend & Web:** Kỹ năng viết React, Tailwind v4, Mobile Design, Web Testing (Playwright), Tối ưu hoá Waterfall fetching.
+*   **Hệ thống & Backend:** Thiết kế kiến trúc Database logic, REST & GraphQL API, Quản lý Server, Mẹo Deploy an toàn.
+*   **Bảo mật & Tối ưu:** Clean Code quy chuẩn quốc tế, Rà quét lỗ hổng rủi ro (Vulnerability scanner), Chiến thuật Red-team, Đo tốc độ web 2025.
+*   **Siêu Ứng dụng (Super Apps):** Kỹ năng code Zalo Mini App thần tốc, giao diện ZaUI cao cấp, UI/UX Pro Max.
+
+#### 2. 🔄 Luồng làm việc tự động (12 Workflows)
+Các phím tắt quy trình (kiểu `/slash-commands`) chuẩn hóa vòng đời phát triển dự án. Chẳng hạn:
+*   `/brainstorm`: Ép AI động não, rào trước đón sau giải quyết triệt để edge-cases trước khi hùng hục lao vào code.
+*   `/plan`: Yêu cầu AI viết Kế hoạch triển khai (Implementation Plan) thật kĩ để bạn Phê duyệt trước khi tiến hành viết Code.
+*   `/ui-ux-pro-max`: Quy trình chuyên biệt ép AI không được dùng Bootstrap cũ rích mà phải thiết kế giao diện Glassmorphism, Gradient bóng mượt.
+*   `/test`: Tự động lùng sục Source Code và đính kèm Unit test chuẩn mô hình cốt lõi.
+
+#### 3. 🛡️ Quy tắc (Rules) & Cấu hình (Architecture)
+Khu vực thiết lập giới hạn và điều luật ranh giới cho Trợ lý:
+*   `rules/`: Chứa các quy định riêng theo văn hóa tổ chức của bạn. Định dạng file markdown cực kì cơ bản. Ví dụ: "Luôn luôn trả lời Tiếng Việt", "Nghiêm cấm dùng thư viện Moment.js", v.v.
+*   `ARCHITECTURE.md` / `mcp_config.json`: Tài liệu ghi chú kiến trúc hệ thống riêng biệt của bạn (Hệ sinh thái AI sẽ scan các file này đầu tiên để móc nối bối cảnh làm việc hiện tại).
+
+### 🚀 Các Trường hợp sử dụng tiêu biểu
+
+1. **Khởi động Nhanh Siêu ứng dụng (VD: Zalo Mini App Taisun):** Bạn tạo dự án trống, cài Gói Kit này bằng lệnh init, sau đó chat với AI: *"Hãy dùng lệnh `/ui-ux-pro-max` và thiết kế màn hình Check-in"* -> AI lập tức tuân thủ quy chuẩn thiết kế Mobile phẳng, áp dụng Style chuẩn xác và giao diện hút mắt.
+2. **Review Code & Kiến trúc Hệ thống:** Dùng quy trình `/orchestrate` (Điều phối), AI sẽ tự gọi ra Hội Đồng Kỹ sư ảo (Frontend Specialist, Backend Architect, Security Auditor) luân lưu code và dò lổ hổng bảo mật trang Repo cho bạn.
+3. **Tái sinh mã nguồn cũ rích:** Thả bộ Kit vào đống code đã bám bụi, gõ vào luồng chat: *"Hãy dọn dẹp các biến rác theo chuẩn skill `clean-code` và `react-best-practices`"* -> AI tự thực thi cải tạo và refactor tối ưu theo chuẩn quốc tế 2025 từng đoạn code một.
 
-- Tự động copy toàn bộ kiến trúc agents, workflows và skills template vào thư mục `.agent` của bạn (Bao gồm các kĩ năng Backend, API, Frontend, AI Prompting...).
+## ⚖️ License
+MIT © Xavie Le

package/bin/cli.js

@@ -10,51 +10,144 @@ const packageJson = require('../package.json');
 
 program
   .name('ag-kit')
-  .description('Trình khởi tạo Antigravity Agent Kit cho dự án của bạn')
+  .description('Trình khởi tạo Antigravity Agent Kit (Antigravity Agent Kit Initializer)')
   .version(packageJson.version);
 
 program
   .command('init')
-  .description('Khởi tạo thư mục .agent vào dự án hiện hành')
-  .option('-f, --force', 'Ghi đè nếu thư mục .agent đã tồn tại')
+  .description('Khởi tạo thư mục bộ não AI (Initialize the AI Brain directory)')
+  .option('-f, --force', 'Ghi đè/Làm mới nếu đã tồn tại (Overwrite/Clean if exists)')
   .action(async (options) => {
     const targetDir = path.join(process.cwd(), '.agent');
     const sourceDir = path.join(__dirname, '..', 'template', '.agent');
 
-    console.log(chalk.cyan(`\n✨ Khởi động tiến trình cài đặt @xaviele/ag-kit\n`));
+    console.log(chalk.cyan(`\n✨ Khởi động tiến trình cài đặt | Starting initialization for @xaviele/ag-kit\n`));
 
     // Check if source exists
     if (!fs.existsSync(sourceDir)) {
-      console.log(chalk.red(`❌ Lỗi: Không tìm thấy thư mục template tại ${sourceDir}`));
+      console.log(chalk.red(`❌ Lỗi | Error: Không tìm thấy thư viện mẫu tại | Source template not found at ${sourceDir}`));
       process.exit(1);
     }
 
     // Check if target exists
     if (fs.existsSync(targetDir) && !options.force) {
-      console.log(chalk.yellow(`⚠️ Thư mục .agent đã tồn tại trong dự án này.`));
-      console.log(`Hãy sử dụng flag ${chalk.green('--force')} nếu bạn muốn ghi đè.\n`);
+      console.log(chalk.yellow(`⚠️ Cảnh báo | Warning: Thư mục .agent đã tồn tại ở đây (The .agent folder already exists here).`));
+      console.log(`Hãy chạy kèm cờ ${chalk.green('--force')} nếu bạn muốn ghi đè đè code cũ (Use the ${chalk.green('--force')} flag to overwrite).\n`);
       process.exit(1);
     }
 
-    const spinner = ora('Đang sao chép các kỹ năng và cấu hình Agent (45 Skills, 12 Workflows)...').start();
+    const spinner = ora('Đang sao chép các kỹ năng | Copying skills & workflows (45 Skills, 12 Workflows)...').start();
 
     try {
       if (options.force && fs.existsSync(targetDir)) {
-        spinner.text = 'Đang dọn dẹp thư mục .agent cũ...';
+        spinner.text = 'Đang dọn dẹp hệ thống cũ | Cleaning up old workspace...';
         await fs.remove(targetDir);
       }
       
-      spinner.text = 'Đang tiến hành clone Data sang .agent...';
+      spinner.text = 'Đang tiến hành nhân bản dữ liệu | Cloning data...';
       await fs.copy(sourceDir, targetDir);
       
-      spinner.succeed(chalk.green('Thành công! Toàn bộ hệ thống Antigravity Agent Kit (.agent) đã được cài đặt.'));
+      spinner.succeed(chalk.green('Thành công! Toàn bộ hệ thống Antigravity Agent Kit (.agent) đã được cài đặt | Success! System workspace installed.'));
       
-      console.log(`\n${chalk.white.bold('Tiếp theo bạn có thể:')}`);
-      console.log(`👉 Chạy ${chalk.cyan('npx @xaviele/ag-kit update')} (Tính năng sắp ra mắt)`);
-      console.log(`👉 Cấu hình thêm Rule tùy chỉnh ở ${chalk.yellow('.agent/rules/')}\n`);
+      console.log(`\n${chalk.white.bold('Tiếp theo bạn có thể | Next steps:')}`);
+      console.log(`👉 Chạy lệnh ${chalk.cyan('npx @xaviele/ag-kit update')} (Tính năng sắp ra mắt | Coming soon)`);
+      console.log(`👉 Cấu hình Rule ở hộp thoại ${chalk.yellow('.agent/rules/')} (Config custom rules)\n`);
       
     } catch (err) {
-      spinner.fail(chalk.red('Quá trình sao chép thất bại!'));
+      spinner.fail(chalk.red('Quá trình sao chép thất bại! | Installation failed!'));
+      console.error(err);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('add <skillName>')
+  .description('Thêm một kỹ năng lẻ vào dự án (Add a single skill into project)')
+  .action(async (skillName) => {
+    const targetBaseDir = path.join(process.cwd(), '.agent');
+    const targetSkillDir = path.join(targetBaseDir, 'skills', skillName);
+    const sourceSkillDir = path.join(__dirname, '..', 'template', '.agent', 'skills', skillName);
+
+    console.log(chalk.cyan(`\n✨ Đang tải nhánh kỹ năng | Downloading skill branch [${skillName}] bằng hệ thống @xaviele/ag-kit\n`));
+
+    // LỰA CHỌN 2: Ép buộc phải có thư mục hệ thống trước
+    if (!fs.existsSync(targetBaseDir)) {
+      console.log(chalk.red(`❌ TỪ CHỐI | ACCESS DENIED: Dự án của bạn chưa thiết lập cấu trúc lõi (Core workflow not initialized).`));
+      console.log(`💡 Vui lòng tạo nền tảng móng trước bằng lệnh (Please initialize first using): ${chalk.green('npx @xaviele/ag-kit init')}\n`);
+      process.exit(1);
+    }
+
+    // Kiểm tra kỹ năng có tồn tại trong template kho hay không?
+    if (!fs.existsSync(sourceSkillDir)) {
+      console.log(chalk.red(`❌ Lỗi 404 | Error 404: Không tìm thấy kỹ năng (Skill not found) '${skillName}'.`));
+      process.exit(1);
+    }
+
+    // Kiểm tra tránh ghi đè lỗi lầm vào Source đã có
+    if (fs.existsSync(targetSkillDir)) {
+      console.log(chalk.yellow(`⚠️ Báo động | Alert: Kỹ năng (Skill) '${skillName}' đã tồn tại! Từ chối ghi đè để bảo vệ Code (Skipped to protect code).`));
+      process.exit(1);
+    }
+
+    const spinner = ora(`Đang giải nén mã nguồn kỹ năng | Extracting skill data ${skillName}...`).start();
+
+    try {
+      await fs.copy(sourceSkillDir, targetSkillDir);
+      spinner.succeed(chalk.green(`Tuyệt vời! Kỹ năng | Awesome! Skill '${skillName}' đã trang bị thành công (installed successfully).`));
+      console.log(`👉 Cài tại thư mục (Installed at): ${chalk.cyan('.agent/skills/' + skillName)}\n`);
+    } catch (err) {
+      spinner.fail(chalk.red(`Lỗi giải nén kỹ năng! | Extraction failed for ${skillName}!`));
+      console.error(err);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('update')
+  .description('Đồng bộ bộ Kỹ năng gốc từ hệ thống (Sync core skills from the system registry)')
+  .action(async () => {
+    const targetBaseDir = path.join(process.cwd(), '.agent');
+    const sourceDir = path.join(__dirname, '..', 'template', '.agent');
+
+    console.log(chalk.cyan(`\n✨ Đang khởi chạy tính năng UPDATE đồng bộ từ @xaviele/ag-kit\n`));
+
+    // Yêu cầu phải có .agent
+    if (!fs.existsSync(targetBaseDir)) {
+      console.log(chalk.red(`❌ LỖI ĐỒNG BỘ | UPDATE FAILED: Dự án của bạn chưa từng được thiết lập móng .agent lõi.`));
+      console.log(`💡 Vui lòng dùng lệnh: ${chalk.green('npx @xaviele/ag-kit init')} trước tiên.\n`);
+      process.exit(1);
+    }
+
+    const spinner = ora('Phân tích cập nhật, tạo khiên bảo vệ Cấu hình dự án (User Rules / Configs)...').start();
+
+    // Thuật toán màng lọc (Immunity Shield)
+    const filterSync = (src, dest) => {
+      const srcName = path.basename(src);
+      // Danh sách các Item bất khả xâm phạm nếu đã tồn tại đẻ bảo vệ Config của Khách Hàng
+      const protectedItems = [
+        'rules', 
+        'scratch', 
+        'ARCHITECTURE.md', 
+        'mcp_config.json', 
+        '.system_generated'
+      ];
+      
+      // Nếu folder/file thuộc diện bảo vệ và ĐÃ TỒN TẠI ở máy khách -> BLOCK Không cho đè
+      if (protectedItems.includes(srcName) && fs.existsSync(dest)) {
+        return false;
+      }
+      return true; // Mọi thứ khác như skills/, workflows/ được cấp phép update đè
+    };
+
+    try {
+      await fs.copy(sourceDir, targetBaseDir, {
+        overwrite: true,
+        filter: filterSync
+      });
+      spinner.succeed(chalk.green(`Tuyệt vời! Toàn bộ 45 Skills và 12 Workflows đã được Cập Nhập (Sync) mới nhất.`));
+      console.log(`👉 Các hệ thống cá nhân hóa (ARCHITECTURE.md, mcp_config.json, rules) được bảo toàn tuyệt đối 100%.\n`);
+    } catch (err) {
+      spinner.fail(chalk.red(`Đồng bộ thất bại! | Sync failed!`));
       console.error(err);
       process.exit(1);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xaviele/ag-kit",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Antigravity Agent Kit - CLI tool to install intelligent agent workspaces",
   "bin": {
     "xaviele-ag-kit": "./bin/cli.js",