@lovehlmmm/primekit 1.0.2 → 1.0.5

package/README.md

@@ -1,107 +1,87 @@
-# PrimeKit (AI Coding Suite Generator)
-> Bộ công cụ AI Coding cá nhân hoá, kiến trúc mở cho Claude Code, Cursor, Codex, VS Code và các AI Assistants.
+# PrimeKit (Universal AI Coding Suite)
+> Trang bị bộ 100+ Skills và Quy chuẩn Lập trình Chuyên nghiệp cho Claude Code, Cursor, Codex, VS Code và mọi AI Coding Assistant.
 
 [![npm package](https://img.shields.io/npm/v/@lovehlmmm/primekit.svg)](https://www.npmjs.com/package/@lovehlmmm/primekit)
-![Build Status](https://img.shields.io/badge/Tests-100%25%20Passing-brightgreen.svg)
+![Build Status](https://img.shields.io/badge/Status-Active-brightgreen.svg)
 ![License](https://img.shields.io/badge/License-MIT-green.svg)
 
 ---
 
-## 🌟 Tổng quan Dự án
+## 🌟 Giới thiệu PrimeKit
 
-**PrimeKit** (`@lovehlmmm/primekit`) là một AI Coding Suite hoàn chỉnh được thiết kế theo kiến trúc modular mở. Dự án bao gồm hệ thống **100+ skills độc lập**, CLI quản lý vòng đời (`init`, `list`, `doctor`, `update`, `import`, `uninstall`) và bộ kiểm thử benchmark 5 kịch bản thực tế.
+**PrimeKit** (`@lovehlmmm/primekit`) là bộ công cụ AI Coding mở giúp tự động hóa quy trình phát triển phần mềm. Khi khởi tạo trong dự án hoặc hệ thống, PrimeKit trang bị cho AI Assistant của bạn bộ 100+ skills chuyên sâu (khảo sát codebase, lập kế hoạch multi-agent, lập trình TDD, phân tích nguyên nhân gốc rễ 5-Whys, quét bảo mật OWASP, và lưu hợp đồng bàn giao).
 
 ---
 
-## 🚀 Hướng dẫn Cài đặt & Sử dụng (Quick Start)
+## 🚀 Hướng dẫn Cài đặt Nhanh (Quick Start)
 
-### 1. Khởi tạo bằng `npx` (Không cần cài đặt)
-Mở bất kỳ dự án/workspace nào và chạy:
+Bạn có thể sử dụng PrimeKit ngay lập tức theo 2 cơ chế:
+
+### 1. Cài đặt Cấp Dự án (Project Scope - Cho cá nhân & Teamwork)
+Khởi tạo trực tiếp vào thư mục dự án hiện tại (tự động tạo `AGENTS.md`, `.cursorrules` và bộ skills):
 ```bash
 npx @lovehlmmm/primekit init
 ```
 
-### 2. Cài đặt Cục bộ (Global CLI)
+### 2. Cài đặt Toàn cục (Global Scope - Cài 1 lần dùng cho MỌI dự án)
+Cài đặt bộ skills trực tiếp vào hệ thống cá nhân (`~/.gemini/config/skills/`, `~/.claude/skills/`, `~/.cursor/rules/`):
+```bash
+npx @lovehlmmm/primekit init --global
+```
+
+### 3. Cài đặt CLI Global (Tùy chọn)
 ```bash
 npm install -g @lovehlmmm/primekit
 
-# Sử dụng qua lệnh primekit hoặc alias ngắn pk
-primekit init
-# hoặc
+# Sau khi cài global, bạn có thể gõ ngắn gọn lệnh primekit hoặc pk:
 pk init
+pk init --global
 ```
 
 ---
 
 ## ⚡ Cú pháp Gọi Skill Rút gọn (`/pk:`)
 
-PrimeKit hỗ trợ cú pháp kích hoạt skill rút gọn cực nhanh bằng tiền tố `/pk:`:
+Sau khi khởi tạo, bạn có thể gõ lệnh kích hoạt trực tiếp trong ô chat với AI Assistant của mình:
 
-| Lệnh Gọi Skill | Tên Skill | Vai trò & Quy trình |
+| Lệnh Gọi Skill | Tên Skill | Mô tả & Quy trình Thực thi |
 | :--- | :--- | :--- |
 | `/pk:explore` | Codebase Scout | Khảo sát sâu kiến trúc repository, dependencies & entry points |
-| `/pk:clarify` | Requirement Clarifier | Làm rõ yêu cầu chưa đầy đủ & thách thức phạm vi YAGNI |
+| `/pk:clarify` | Requirement Clarifier | Phân tích lỗ hổng yêu cầu & thách thức phạm vi thừa (YAGNI) |
 | `/pk:plan` | Implementation Planner | Lập kế hoạch theo giai đoạn (`--fast`, `--deep`, `--debate`, `--ultra`) |
 | `/pk:implement` | Focused Coder | Lập trình khoanh vùng chính xác (Hỗ trợ TDD `--tdd`) |
 | `/pk:debug` | Root Cause Analyzer | Phân tích nguyên nhân gốc rễ 5-Whys & kịch bản tái hiện |
-| `/pk:test` | Test Execution | Tự động chạy unit/integration test suite & chống lỗi hồi quy |
+| `/pk:test` | Test Execution | Tự động nhận diện runner, thực thi test suite & chống lỗi hồi quy |
 | `/pk:review` | Diff Inspector | Đánh giá git diff, kiểm tra rủi ro bảo mật OWASP/STRIDE |
-| `/pk:handoff` | Session Continuity | Lưu trạng thái bàn giao Hợp đồng Tiếp nối phiên sau |
+| `/pk:handoff` | Session Continuity | Đóng gói Hợp đồng Tiếp nối phiên làm việc cho lần sau |
 | `/pk:predict` | Architecture Predictor | 5 Chuyên gia phản biện kiến trúc trước khi code |
-| `/pk:vibe` | Autonomous Pipeline | Tự động hóa luồng từ GitHub Issue tới PR hoàn chỉnh |
+| `/pk:vibe` | Autonomous Pipeline | Tự động hóa luồng làm việc từ GitHub Issue tới PR |
 
 ---
 
-## 🛠️ Lệnh Quản lý CLI Reference
+## 🛠️ Danh mục Lệnh PrimeKit CLI
 
-```bash
-primekit init        # Khởi tạo PrimeKit vào workspace (.primekit/, AGENTS.md, .cursorrules)
-primekit list        # Liệt kê các skill, hooks và adapters đã cài đặt
-primekit doctor      # Kiểm tra sức khỏe hệ thống, SHA256 checksum & tương thích Assistant
-primekit import <name> # Import/clone skill bất kỳ từ hệ sinh thái vào workspace (VD: pk import predict)
-primekit update      # Cập nhật an toàn bộ skill & CLI (tự động tạo backup .bak)
-primekit uninstall   # Gỡ bỏ sạch sẽ các thành phần do PrimeKit quản lý
-```
+| Lệnh CLI | Mô tả Chức năng |
+| :--- | :--- |
+| `pk init` | Khởi tạo PrimeKit vào thư mục dự án hiện tại |
+| `pk init -g` | Cài đặt bộ skills vào hệ thống toàn cục cho mọi dự án |
+| `pk list` | Liệt kê các skill, hooks và adapters đã cài đặt |
+| `pk doctor` | Kiểm tra sức khỏe hệ thống, checksum SHA256 & độ tương thích AI |
+| `pk import <skill>` | Clone/Import skill bất kỳ từ hệ sinh thái vào dự án (VD: `pk import predict`) |
+| `pk update` | Cập nhật an toàn bộ skill & CLI (tự động sao lưu file `.bak`) |
+| `pk uninstall` | Gỡ bỏ sạch sẽ các tập tin do PrimeKit quản lý |
 
 ---
 
-## 📁 Cấu trúc Thư mục Dự án
-
-```text
-PrimeKit/
-├── .primekit/             # Thư mục chứa skills & adapters đã init trong workspace
-│   ├── skills/            # Tất cả skills (SKILL.md)
-│   └── manifest.json      # File theo dõi phiên bản & checksum SHA256
-├── cli/                   # Mã nguồn CLI (Node.js & TypeScript)
-│   ├── src/               # Code nguồn (commands, adapters, utils)
-│   └── dist/              # Code đã biên dịch JavaScript
-├── docs/                  # Tài liệu hướng dẫn tiếng Việt
-│   ├── ARCHITECTURE.md    # Kiến trúc chi tiết hệ thống
-│   └── USAGE.md           # Hướng dẫn sử dụng CLI reference
-├── benchmarks/            # 5 bài kiểm thử thực tế (Bug fix, Feature, Refactor, Review, Handoff)
-├── scripts/               # Scripts kiểm thử CLI & runner benchmark
-├── skills/                # Thư mục nguồn 100+ Skills (SKILL.md)
-├── AGENTS.md              # Quy tắc agent chuẩn hóa hệ thống
-├── agnt.md                # File đặc tả cấu hình Agent tối ưu
-├── package.json           # Cấu hình package & scripts
-└── tsconfig.json          # Cấu hình TypeScript compiler
-```
+## 🎯 Bảng Tương thích với các IDE & AI Assistants
 
----
-
-## 🧪 Phát triển & Kiểm thử (Development & Benchmarks)
-
-```bash
-# Cài đặt dependencies và build TypeScript
-npm install
-npm run build
-
-# Chạy bộ test CLI integration
-npm test
+PrimeKit tương thích 100% với mọi môi trường lập trình AI phổ biến hiện nay:
 
-# Chạy bộ đánh giá 5 kịch bản benchmark thực tế
-npm run benchmark
-```
+- **Claude Code (CLI)**: Nhận diện qua `.claude/skills/` và `.primekit/claude-adapter.json`.
+- **Cursor IDE**: Nhận diện qua file cấu hình `.cursorrules` và `.cursor/rules/`.
+- **Codex / OpenAI**: Nhận diện qua tập tin quy chuẩn `AGENTS.md`.
+- **VS Code (Copilot / Gemini / Antigravity)**: Nhận diện qua `AGENTS.md` và `.gemini/config/skills/`.
+- **Custom CLI Agents**: Tuân thủ chuẩn định dạng Markdown CommonMark & YAML Frontmatter.
 
 ---
 

package/{AGENTS.md → agnt.md}

@@ -1,23 +1,3 @@
-# PRIMEKIT INTEGRATION INSTRUCTIONS
-> Active AI Coding Suite: PrimeKit (Universal Architecture)
-
-## Available Core Skills
-PrimeKit skills are located in `.primekit/skills/`. Read the corresponding `SKILL.md` before executing workflows:
-
-1. **explore** (`.primekit/skills/explore/SKILL.md`): Codebase Scout.
-2. **clarify** (`.primekit/skills/clarify/SKILL.md`): Requirement Clarifier.
-3. **plan** (`.primekit/skills/plan/SKILL.md`): Implementation Planner.
-4. **implement** (`.primekit/skills/implement/SKILL.md`): Focused Coder.
-5. **debug** (`.primekit/skills/debug/SKILL.md`): Root Cause Analyzer.
-6. **test** (`.primekit/skills/test/SKILL.md`): Test Execution & Verification.
-7. **review** (`.primekit/skills/review/SKILL.md`): Diff Inspector.
-8. **handoff** (`.primekit/skills/handoff/SKILL.md`): Session Continuity.
-
-## Router Rules
-- Small/single edits -> Direct to `implement`.
-- Complex tasks (>2 files) -> Follow `explore` -> `plan` -> `implement` -> `test` -> `review` -> `handoff`.
-
-
 # AGENT SPECIFICATION: PRIMEKIT (AI CODING SUITE GENERATOR)
 > **Phiên bản Prompt Tối ưu hóa**: 1.0  
 > **Mục tiêu**: Hướng dẫn AI Agent tự thiết kế, xây dựng và đóng gói bộ công cụ AI Coding "PrimeKit" (lấy cảm hứng từ PrimeKit) hoàn chỉnh, chạy thực tế, có CLI, bộ skill và framework đánh giá.

package/cli/dist/commands/init.d.ts

@@ -3,6 +3,7 @@ export interface InitOptions {
     dryRun?: boolean;
     assistant?: string;
     force?: boolean;
+    global?: boolean;
 }
-export declare function copyFolderRecursive(src: string, dest: string, dryRun: boolean, manifestFiles: ManifestFileEntry[]): void;
+export declare function copyFolderRecursive(src: string, dest: string, dryRun: boolean, manifestFiles?: ManifestFileEntry[]): void;
 export declare function runInit(projectRoot?: string, options?: InitOptions): void;

package/cli/dist/commands/init.js

@@ -30,23 +30,49 @@ function copyFolderRecursive(src, dest, dryRun, manifestFiles) {
             if (!dryRun) {
                 fs_1.default.copyFileSync(srcPath, destPath);
             }
-            const sha256 = dryRun ? '' : (0, manifest_1.calculateSHA256)(destPath);
-            manifestFiles.push({
-                path: path_1.default.relative(process.cwd(), destPath).replace(/\\/g, '/'),
-                sha256,
-                updatedAt: new Date().toISOString()
-            });
+            if (manifestFiles) {
+                const sha256 = dryRun ? '' : (0, manifest_1.calculateSHA256)(destPath);
+                manifestFiles.push({
+                    path: path_1.default.relative(process.cwd(), destPath).replace(/\\/g, '/'),
+                    sha256,
+                    updatedAt: new Date().toISOString()
+                });
+            }
         }
     }
 }
 function runInit(projectRoot = process.cwd(), options = {}) {
     const dryRun = !!options.dryRun;
     const assistant = options.assistant || 'all';
+    const isGlobal = !!options.global;
+    const userHome = process.env.USERPROFILE || process.env.HOME || 'C:\\Users\\TuanNguyenAnh';
+    const sourceSkillsDir = path_1.default.join(__dirname, '..', '..', '..', 'skills');
+    if (isGlobal) {
+        console.log(`[PrimeKit Init --global] Installing PrimeKit Skills Globally to System AI Assistants...`);
+        if (dryRun)
+            console.log(`[DRY-RUN MODE] No files will be modified.`);
+        const globalTargets = [
+            path_1.default.join(userHome, '.gemini', 'config', 'skills'),
+            path_1.default.join(userHome, '.claude', 'skills'),
+            path_1.default.join(userHome, '.cursor', 'rules')
+        ];
+        let installedCount = 0;
+        for (const targetDir of globalTargets) {
+            const parentDir = path_1.default.dirname(targetDir);
+            if (fs_1.default.existsSync(parentDir) || targetDir.includes('.gemini')) {
+                console.log(`- Installing global skills to: ${targetDir}`);
+                copyFolderRecursive(sourceSkillsDir, targetDir, dryRun);
+                installedCount++;
+            }
+        }
+        console.log(`🎉 PrimeKit Global Initialization complete! (${installedCount} assistant targets updated).`);
+        return;
+    }
+    // Local Project Scope
     console.log(`[PrimeKit Init] Initializing PrimeKit in ${projectRoot}...`);
     if (dryRun) {
         console.log(`[DRY-RUN MODE] No files will be modified.`);
     }
-    const sourceSkillsDir = path_1.default.join(__dirname, '..', '..', '..', 'skills');
     const targetSkillsDir = path_1.default.join(projectRoot, '.primekit', 'skills');
     const manifestFiles = [];
     // Copy skills

package/cli/dist/index.js

@@ -9,13 +9,13 @@ const uninstall_1 = require("./commands/uninstall");
 const import_1 = require("./commands/import");
 function printHelp() {
     console.log(`
-PrimeKit CLI v1.0.0 - Universal AI Coding Tool Suite Management
+PrimeKit CLI v1.0.2 - Universal AI Coding Tool Suite Management
 
 USAGE:
   $ primekit <command> [options]
 
 COMMANDS:
-  init        Initialize PrimeKit in the current project workspace.
+  init        Initialize PrimeKit in the workspace (or globally with --global).
   list        List installed skills, adapters, and tracked components.
   doctor      Diagnose health, SHA256 integrity, and adapter integration.
   update      Safely update PrimeKit skills and CLI components.
@@ -23,14 +23,16 @@ COMMANDS:
   uninstall   Cleanly remove PrimeKit assets from the workspace.
 
 OPTIONS:
+  --global, -g Install skills globally to system AI Assistant configs (~/.gemini, ~/.claude, etc.).
   --dry-run   Simulate changes without modifying files.
   --assistant Specify target assistant (claude, cursor, codex, all).
   --help, -h  Display help message.
 
 EXAMPLES:
-  $ primekit import plan
-  $ primekit import predict
-  $ primekit import --all
+  $ primekit init
+  $ primekit init --global
+  $ pk init -g
+  $ pk import predict
 `);
 }
 function main() {
@@ -41,12 +43,13 @@ function main() {
         return;
     }
     const isDryRun = args.includes('--dry-run');
+    const isGlobal = args.includes('--global') || args.includes('-g');
     const isAll = args.includes('--all');
     const assistantIdx = args.indexOf('--assistant');
     const assistant = assistantIdx !== -1 && args[assistantIdx + 1] ? args[assistantIdx + 1] : 'all';
     switch (command) {
         case 'init':
-            (0, init_1.runInit)(process.cwd(), { dryRun: isDryRun, assistant });
+            (0, init_1.runInit)(process.cwd(), { dryRun: isDryRun, assistant, global: isGlobal });
             break;
         case 'list':
             (0, list_1.runList)(process.cwd());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovehlmmm/primekit",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "description": "Universal AI Coding Tool Suite Generator inspired by AgentKit",
   "main": "cli/dist/index.js",
   "bin": {
@@ -12,8 +12,7 @@
     "skills",
     "docs",
     "README.md",
-    "agnt.md",
-    "AGENTS.md"
+    "agnt.md"
   ],
   "publishConfig": {
     "access": "public"