ai-developer-skill-os 1.3.1 → 1.4.1

package/README.md

@@ -35,10 +35,12 @@ Mở terminal tại thư mục gốc dự án của bạn và chạy:
 ```bash
 npx ai-developer-skill-os init
 ```
-*Lệnh này sẽ tự động tải và khởi tạo thư mục ẩn `.qk-ai-skill-os/` chứa toàn bộ kỹ năng vào dự án của bạn.*
+Hệ thống sẽ cung cấp cho bạn 2 tuỳ chọn cực kỳ linh hoạt:
+- **(1) Local:** Cài vào thư mục ẩn `.qk-ai-skill-os/` ngay trong dự án. (Phù hợp khi làm việc nhóm, commit lên Git để ai cũng xài được).
+- **(2) Global:** Cài thẳng vào ổ đĩa máy tính (Home Directory). Từ đó trở đi, bạn mở **BẤT KỲ DỰ ÁN NÀO** cũng sẽ tự động gọi được 23 kỹ năng mà không cần tải lại file! (Rất tuyệt vời cho cá nhân sử dụng).
 
 ### Cách 2: Sử dụng Git Submodule
-Nếu bạn không dùng Node.js, bạn có thể nhúng trực tiếp qua Git:
+Nếu bạn không dùng Node.js, bạn có thể nhúng trực tiếp qua Git (Chỉ hỗ trợ dạng Local):
 ```bash
 git submodule add https://github.com/phamquangkhanh2999/ai-developer-skill-os.git .qk-ai-skill-os
 ```
@@ -107,6 +109,28 @@ Dưới đây là các ví dụ cụ thể để bạn copy - paste và trải n
 
 ---
 
+## 💡 Mẹo & Workflow Thực Chiến (Best Practices)
+
+Để khai thác tối đa sức mạnh của 23 kỹ năng, bí quyết là **kết hợp (chaining) nhiều skill** lại với nhau trong cùng một luồng công việc. Dưới đây là các Workflow kinh điển:
+
+### 🌟 1. Workflow Bắt đầu một New Chat (Bắt buộc)
+Khi mở một New Chat, AI hoàn toàn chưa biết gì về dự án. Đừng bắt nó code ngay!
+* **Bước 1:** `> Dùng ./qk-context-manager để đọc cấu trúc toàn bộ dự án này.`
+* **Bước 2:** `> Dùng ./qk-agent-orchestrator để phân tích yêu cầu sau đây và lên kế hoạch: [Yêu cầu của bạn]`
+
+### 🌟 2. Workflow Làm tính năng mới (VD: Tích hợp API)
+Muốn tạo một màn hình hiển thị danh sách từ API trả về? Hãy gõ:
+* `> Hãy dùng ./qk-api-integration để tạo file gọi API fetch danh sách Users.`
+* `> Tiếp theo dùng ./qk-state-management để lưu data này vào Zustand/Redux.`
+* `> Cuối cùng dùng ./qk-ui-builder để vẽ màn hình Table hiển thị data đó.`
+
+### 🌟 3. Workflow Chống "Phá Code" (Safe Refactor)
+Trước khi đổi một cấu trúc lớn, hãy bắt AI dò mìn:
+* `> Hãy chạy ./qk-project-audit để dò xem việc đổi tên biến X có ảnh hưởng đến các component khác không.`
+* `> OK, giờ hãy dùng ./qk-refactor để sửa lại một cách an toàn.`
+
+---
+
 ## 💎 Danh sách 23+ Kỹ Năng Độc Quyền
 
 | Phân hệ | Kỹ năng tiêu biểu | Chức năng chính |

package/bin/install.js

@@ -3,9 +3,9 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
+const os = require('os');
 
 const sourceDir = path.join(__dirname, '..');
-let targetDir = path.join(process.cwd(), '.qk-ai-skill-os');
 
 function copyRecursiveSync(src, dest) {
   const exists = fs.existsSync(src);
@@ -24,17 +24,6 @@ function copyRecursiveSync(src, dest) {
   }
 }
 
-const systemPrompt = `[Role]
-You are an elite AI Software Engineer. You must strictly follow the rules in this project.
-Vui lòng tìm đọc danh sách kỹ năng tại file \`./.qk-ai-skill-os/skills.json\`.
-
-[Trigger Mechanism]
-Bất cứ khi nào người dùng gõ lệnh bắt đầu bằng \`./qk-[tên-skill]\`, bạn BẮT BUỘC phải đọc file \`SKILL.md\` tương ứng trong thư mục \`./.qk-ai-skill-os/skills/...\` trước khi làm bất cứ việc gì. Đừng bao giờ đoán mò.
-
-[Command Arguments]
-Người dùng có thể truyền thêm tham số vào lệnh (ví dụ: \`./qk-ui-builder --fw=react --css=tailwind\`). 
-Nếu người dùng sử dụng tham số (argument), bạn BẮT BUỘC phải tuân thủ tuyệt đối các công nghệ/yêu cầu được chỉ định trong tham số đó thay vì dùng mặc định.`;
-
 const rl = readline.createInterface({
   input: process.stdin,
   output: process.stdout
@@ -42,94 +31,137 @@ const rl = readline.createInterface({
 
 console.log('🚀 Đang chuẩn bị cài đặt AI Developer Skill OS...\n');
 
-const questionText = `Vui lòng chọn IDE/AI Assistant bạn đang sử dụng để tự động cấu hình (Auto-Generate Config):
+const questionIde = `Vui lòng chọn IDE/AI Assistant bạn đang sử dụng:
 (1) Cursor
 (2) Windsurf
 (3) Cline / Roo Code
 (4) Antigravity / Gemini
 (5) Codex
 (6) Kilo Code
-(0) Bỏ qua (Không tạo file config)
+(0) Bỏ qua (Không tạo config tự động)
 
 Nhập số (0-6): `;
 
-rl.question(questionText, (answer) => {
-  let isGemini = false;
-  let ruleFile = null;
-
-  switch(answer.trim()) {
-    case '1': ruleFile = '.cursorrules'; break;
-    case '2': ruleFile = '.windsurfrules'; break;
-    case '3': ruleFile = '.clinerules'; break;
-    case '4': 
-      isGemini = true; 
-      targetDir = path.join(process.cwd(), '.agents', 'skills');
-      ruleFile = path.join('.agents', 'AGENTS.md');
-      break;
-    case '5': ruleFile = '.codexrules'; break;
-    case '6': ruleFile = '.kilorules'; break;
-    case '0': 
-    default:
-      console.log('👉 Bỏ qua bước tạo file cấu hình tự động.');
-      break;
-  }
+const questionScope = `
+Bạn muốn cài đặt bộ kỹ năng ở đâu?
+(1) Local  (Gắn vào dự án hiện tại - Phù hợp làm việc nhóm)
+(2) Global (Cài vào máy tính dùng chung cho mọi dự án - Dành cho cá nhân)
 
-  if (isGemini) {
-    console.log('\n⚙️ Chế độ: Gemini / Antigravity IDE (Cài vào thư mục .agents/)');
-  } else {
-    console.log('\n⚙️ Chế độ: Mặc định (Cài vào thư mục .qk-ai-skill-os/)');
+Nhập số (1-2): `;
+
+rl.question(questionIde, (answerIde) => {
+  let isGemini = false;
+  let ruleFileName = null;
+  const ideCode = answerIde.trim();
+
+  switch(ideCode) {
+    case '1': ruleFileName = '.cursorrules'; break;
+    case '2': ruleFileName = '.windsurfrules'; break;
+    case '3': ruleFileName = '.clinerules'; break;
+    case '4': isGemini = true; break;
+    case '5': ruleFileName = '.codexrules'; break;
+    case '6': ruleFileName = '.kilorules'; break;
+    case '0': default: break;
   }
 
-  try {
-    if (!fs.existsSync(targetDir)) {
-      fs.mkdirSync(targetDir, { recursive: true });
+  rl.question(questionScope, (answerScope) => {
+    const isGlobal = answerScope.trim() === '2';
+    
+    let targetDir = '';
+    let ruleFilePath = null;
+    let baseFolderForPrompt = '';
+    const homeDir = os.homedir();
+    const cwd = process.cwd();
+
+    if (isGemini) {
+      if (isGlobal) {
+        targetDir = path.join(homeDir, '.gemini', 'config');
+        ruleFilePath = path.join(targetDir, 'AGENTS.md');
+        baseFolderForPrompt = path.join(targetDir, 'skills').replace(/\\/g, '/');
+      } else {
+        targetDir = path.join(cwd, '.agents');
+        ruleFilePath = path.join(cwd, '.agents', 'AGENTS.md');
+        baseFolderForPrompt = '.agents/skills';
+      }
+    } else {
+      if (isGlobal) {
+        targetDir = path.join(homeDir, '.qk-ai-skill-os');
+        baseFolderForPrompt = targetDir.replace(/\\/g, '/');
+      } else {
+        targetDir = path.join(cwd, '.qk-ai-skill-os');
+        baseFolderForPrompt = './.qk-ai-skill-os';
+      }
+      if (ruleFileName) {
+        ruleFilePath = path.join(cwd, ruleFileName);
+      }
     }
 
-    const filesAndFolders = [
-      'skills', 
-      '_template', 
-      'docs', 
-      'skills.json', 
-      'README.md', 
-      'CHANGELOG.md', 
-      'LICENSE'
-    ];
-
-    filesAndFolders.forEach(item => {
-      const src = path.join(sourceDir, item);
-      let dest = path.join(targetDir, item);
-      
-      if (fs.existsSync(src)) {
-        copyRecursiveSync(src, dest);
+    const systemPrompt = `[Role]
+You are an elite AI Software Engineer. You must strictly follow the rules in this project.
+Vui lòng tìm đọc danh sách kỹ năng tại file \`${baseFolderForPrompt}/skills.json\`.
+
+[Trigger Mechanism]
+Bất cứ khi nào người dùng gõ lệnh bắt đầu bằng \`./qk-[tên-skill]\`, bạn BẮT BUỘC phải đọc file \`SKILL.md\` tương ứng trong thư mục \`${baseFolderForPrompt}/...\` (hoặc dùng tool view_file để đọc file đó) trước khi làm bất cứ việc gì. Đừng bao giờ đoán mò.
+
+[Command Arguments]
+Người dùng có thể truyền thêm tham số vào lệnh (ví dụ: \`./qk-ui-builder --fw=react --css=tailwind\`). 
+Nếu người dùng sử dụng tham số (argument), bạn BẮT BUỘC phải tuân thủ tuyệt đối các công nghệ/yêu cầu được chỉ định trong tham số đó thay vì dùng mặc định.`;
+
+    try {
+      if (!fs.existsSync(targetDir)) {
+        fs.mkdirSync(targetDir, { recursive: true });
       }
-    });
 
-    if (ruleFile) {
-        const fullRulePath = path.join(process.cwd(), ruleFile);
-        const ruleDir = path.dirname(fullRulePath);
-        if (ruleDir !== process.cwd() && !fs.existsSync(ruleDir)) {
-            fs.mkdirSync(ruleDir, { recursive: true });
-        }
-        
-        let writeContent = systemPrompt;
-        if (isGemini) {
-            writeContent = `\n<RULE[ai_skill_os]>\n---\ntrigger: always_on\n---\n${systemPrompt}\n</RULE[ai_skill_os]>\n`;
-        }
+      const filesAndFolders = [
+        'skills', '_template', 'docs', 'skills.json', 'README.md', 'CHANGELOG.md', 'LICENSE'
+      ];
 
-        if (fs.existsSync(fullRulePath)) {
-            fs.appendFileSync(fullRulePath, "\n\n" + writeContent);
-            console.log(`✅ Đã GHI THÊM cấu hình tự động vào file: ${ruleFile}`);
-        } else {
-            fs.writeFileSync(fullRulePath, writeContent);
-            console.log(`✅ Đã TẠO MỚI file cấu hình: ${ruleFile}`);
+      // Nếu là Gemini Global, chỉ cần copy skills và skills.json để tránh rác
+      if (isGemini && isGlobal) {
+        if (fs.existsSync(path.join(sourceDir, 'skills'))) {
+            copyRecursiveSync(path.join(sourceDir, 'skills'), path.join(targetDir, 'skills'));
         }
-    }
+      } else {
+        filesAndFolders.forEach(item => {
+            const src = path.join(sourceDir, item);
+            let dest = path.join(targetDir, item);
+            if (fs.existsSync(src)) {
+                copyRecursiveSync(src, dest);
+            }
+        });
+      }
 
-    console.log(`✅ Đã cài đặt thư viện thành công vào thư mục: ${targetDir.replace(process.cwd(), '.')}`);
-    console.log('\n💡 Hãy tận hưởng trải nghiệm Auto-Config và Command Arguments (VD: ./qk-ui-builder --fw=react)!');
-  } catch (error) {
-    console.error('❌ Có lỗi xảy ra trong quá trình cài đặt:', error.message);
-  } finally {
-    rl.close();
-  }
+      if (ruleFilePath) {
+          const ruleDir = path.dirname(ruleFilePath);
+          if (ruleDir !== cwd && !fs.existsSync(ruleDir)) {
+              fs.mkdirSync(ruleDir, { recursive: true });
+          }
+          
+          let writeContent = systemPrompt;
+          if (isGemini) {
+              writeContent = `\n<RULE[ai_skill_os]>\n---\ntrigger: always_on\n---\n${systemPrompt}\n</RULE[ai_skill_os]>\n`;
+          }
+
+          if (fs.existsSync(ruleFilePath)) {
+              fs.appendFileSync(ruleFilePath, "\n\n" + writeContent);
+              console.log(`✅ Đã GHI THÊM cấu hình tự động vào file: ${ruleFilePath}`);
+          } else {
+              fs.writeFileSync(ruleFilePath, writeContent);
+              console.log(`✅ Đã TẠO MỚI file cấu hình: ${ruleFilePath}`);
+          }
+      }
+
+      console.log(`\n🎉 HOÀN TẤT! Dữ liệu kỹ năng đã được lưu tại: ${targetDir}`);
+      if (isGlobal && !isGemini) {
+        console.log(`💡 Lưu ý: Kỹ năng đã được cài ở cấp độ máy tính (Global). File cấu hình cục bộ (${ruleFileName}) ở dự án này đang trỏ thẳng về thư mục Global đó.`);
+      } else if (isGlobal && isGemini) {
+        console.log(`💡 Lưu ý: Antigravity đã được cài Global. Từ nay bạn mở BẤT KỲ DỰ ÁN NÀO trên máy tính này, Antigravity cũng sẽ tự động có đủ 23 kỹ năng mà không cần cài lại!`);
+      }
+
+    } catch (error) {
+      console.error('❌ Có lỗi xảy ra trong quá trình cài đặt:', error.message);
+    } finally {
+      rl.close();
+    }
+  });
 });

package/docs/HUONG_DAN_SU_DUNG.md

@@ -27,24 +27,21 @@ Bộ Skin này rất linh hoạt và được phân phối qua NPM để bạn c
 Mở terminal tại gốc dự án của bạn và chạy lệnh cài đặt tương ứng với công cụ AI bạn đang dùng:
 
 ### Dành cho Gemini IDE / Antigravity
-Các công cụ này đọc cấu hình từ thư mục `.agents/skills/`. Bạn chỉ cần thêm cờ `--gemini` khi chạy cài đặt:
-```bash
-npx ai-developer-skill-os init --gemini
-```
-*Lệnh này sẽ tự tạo thư mục `.agents/skills/` và tải toàn bộ bộ kỹ năng vào đó.*
+### 1. Cài đặt (Installation)
+> Khuyên dùng cách cài đặt qua NPM để luôn nhận được cấu trúc mới nhất và tận dụng tính năng Auto-Config.
 
-### Dành cho Cursor / Windsurf / Claude Code / Kilo Code
-Các công cụ này linh hoạt hơn, bạn cài đặt mặc định:
+Mở terminal tại thư mục gốc dự án của bạn và chạy lệnh sau:
 ```bash
 npx ai-developer-skill-os init
 ```
-*Lệnh này sẽ tạo thư mục `.qk-ai-skill-os/` ở gốc dự án.*
-
----
+Quá trình cài đặt sẽ hỏi bạn 2 câu quan trọng:
 
-## 3. Cấu hình cho IDE / AI Agent
+**Câu 1: Bạn đang dùng IDE nào?**
+Hệ thống sẽ tự động tạo file cấu hình tương ứng (ví dụ `.cursorrules`, `.windsurfrules`, `.clinerules`) và bơm sẵn System Prompt vào để AI tự nhận diện các skill.
 
-Sau khi thư mục kỹ năng đã xuất hiện trong dự án của bạn, hãy cấu hình để AI biết cách sử dụng nó.
+**Câu 2: Phạm vi cài đặt?**
+- **(1) Local:** Cài vào thư mục ẩn `.qk-ai-skill-os/` (hoặc `.agents/` cho Gemini) ngay trong dự án. Rất phù hợp nếu dự án có nhiều người làm chung, bạn có thể commit thư mục này lên Git để ai cũng có skill.
+- **(2) Global:** Cài thẳng vào ổ đĩa máy tính (Home Directory). Nếu bạn code một mình, hãy chọn tuỳ chọn này! Nó giúp bạn tiết kiệm dung lượng, và chỉ cần cài 1 lần là BẤT KỲ DỰ ÁN NÀO bạn mở lên, AI cũng tự động có đủ 23 kỹ năng (Đặc biệt siêu mượt với Antigravity/Gemini). nó.
 
 ### Cho Gemini IDE / Antigravity
 **Không cần cấu hình gì thêm!** Gemini/Antigravity sẽ tự động nhận diện các file trong `.agents/skills/` và sẵn sàng làm việc ngay.
@@ -117,3 +114,27 @@ Dưới đây là các câu lệnh (prompt) mẫu cực kỳ hiệu quả mà b
 
 ### 🎯 Ví dụ 6: Database & Backend
 > **`./qk-database-engineer`** Hãy viết cho tôi schema Prisma cho bảng Product và User có quan hệ 1-N. Làm theo đúng chuẩn kiến trúc trong skill.
+
+---
+
+## 6. 💡 Mẹo & Workflow Thực Chiến (Best Practices)
+
+Để khai thác tối đa sức mạnh của 23 kỹ năng, bí quyết là **kết hợp (chaining) nhiều skill** lại với nhau trong cùng một luồng công việc.
+
+### 🌟 Workflow Bắt đầu một New Chat (Bắt buộc)
+Khi mở một New Chat, AI hoàn toàn chưa biết gì về dự án. Đừng bắt nó code ngay!
+* **Bước 1:** `> Dùng ./qk-context-manager để đọc cấu trúc toàn bộ dự án này.`
+* **Bước 2:** `> Dùng ./qk-agent-orchestrator để phân tích yêu cầu sau đây và lên kế hoạch: [Yêu cầu của bạn]`
+
+### 🌟 Workflow Làm tính năng mới (VD: Tích hợp API)
+Muốn tạo một màn hình hiển thị danh sách từ API trả về? Hãy gõ 1 lượt các lệnh:
+* `> Hãy dùng ./qk-api-integration để tạo file gọi API fetch danh sách Users.`
+* `> Tiếp theo dùng ./qk-state-management để lưu data này vào Zustand/Redux.`
+* `> Cuối cùng dùng ./qk-ui-builder để vẽ màn hình Table hiển thị data đó.`
+
+### 🌟 Workflow Chống "Phá Code" (Safe Refactor)
+Trước khi đổi một cấu trúc lớn, hãy bắt AI dò mìn:
+* `> Hãy chạy ./qk-project-audit để dò xem việc đổi tên biến X có ảnh hưởng đến các component khác không.`
+* `> OK, giờ hãy dùng ./qk-refactor để sửa lại một cách an toàn.`
+
+👉 Chúc bạn tận hưởng cảm giác code như một Tech Lead thực thụ!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-developer-skill-os",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "description": "Multi-agent skill package cho AI coding agents (Claude, Cursor, Windsurf, Antigravity) với 23 skills chuyên nghiệp.",
   "main": "bin/install.js",
   "bin": {