@lovehlmmm/primekit 1.0.4 → 1.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/AGENTS.md +18 -0
  2. package/README.md +126 -62
  3. package/{agnt.md → docs/AGENT_SPEC.md} +6 -5
  4. package/package.json +2 -2
  5. package/skills/ak/SKILL.md +1 -1
package/AGENTS.md ADDED
@@ -0,0 +1,18 @@
1
+ # PRIMEKIT INTEGRATION INSTRUCTIONS
2
+ > Active AI Coding Suite: PrimeKit (Universal Architecture)
3
+
4
+ ## Available Core Skills
5
+ PrimeKit skills are located in `.primekit/skills/`. Read the corresponding `SKILL.md` before executing workflows:
6
+
7
+ 1. **explore** (`.primekit/skills/explore/SKILL.md`): Codebase Scout.
8
+ 2. **clarify** (`.primekit/skills/clarify/SKILL.md`): Requirement Clarifier.
9
+ 3. **plan** (`.primekit/skills/plan/SKILL.md`): Implementation Planner.
10
+ 4. **implement** (`.primekit/skills/implement/SKILL.md`): Focused Coder.
11
+ 5. **debug** (`.primekit/skills/debug/SKILL.md`): Root Cause Analyzer.
12
+ 6. **test** (`.primekit/skills/test/SKILL.md`): Test Execution & Verification.
13
+ 7. **review** (`.primekit/skills/review/SKILL.md`): Diff Inspector.
14
+ 8. **handoff** (`.primekit/skills/handoff/SKILL.md`): Session Continuity.
15
+
16
+ ## Router Rules
17
+ - Small/single edits -> Direct to `implement`.
18
+ - Complex tasks (>2 files) -> Follow `explore` -> `plan` -> `implement` -> `test` -> `review` -> `handoff`.
package/README.md CHANGED
@@ -1,107 +1,171 @@
1
- # PrimeKit (AI Coding Suite Generator)
2
- > 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.
1
+ # PrimeKit (Universal AI Coding Suite)
2
+ > Equip 100+ Professional Agentic Skills & Coding Standards for Claude Code, Cursor, Codex, VS Code, and any AI Coding Assistant.
3
3
 
4
4
  [![npm package](https://img.shields.io/npm/v/@lovehlmmm/primekit.svg)](https://www.npmjs.com/package/@lovehlmmm/primekit)
5
- ![Build Status](https://img.shields.io/badge/Tests-100%25%20Passing-brightgreen.svg)
5
+ ![Build Status](https://img.shields.io/badge/Status-Active-brightgreen.svg)
6
6
  ![License](https://img.shields.io/badge/License-MIT-green.svg)
7
7
 
8
8
  ---
9
9
 
10
- ## 🌟 Tổng quan Dự án
10
+ 🌐 **Language / Ngôn ngữ**: [English](#english) | [Tiếng Việt](#tiếng-việt)
11
11
 
12
- **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ế.
12
+ ---
13
+
14
+ <a name="english"></a>
15
+ ## 🌟 About PrimeKit (English)
16
+
17
+ **PrimeKit** (`@lovehlmmm/primekit`) is an open-source AI Coding toolkit designed to automate and elevate software development workflows. When initialized in a project or system-wide, PrimeKit equips your AI Coding Assistants with 100+ specialized agentic skills (codebase scouting, multi-agent planning, TDD implementation, 5-Whys root-cause debugging, OWASP security auditing, and session continuity handoffs).
18
+
19
+ ---
20
+
21
+ ## 🚀 Quick Start
22
+
23
+ Initialize PrimeKit using one of two modes:
24
+
25
+ ### 1. Project Scope (For Individual & Team Repositories)
26
+ Initialize directly in your current project root (automatically generates `AGENTS.md`, `.cursorrules`, and `.primekit/skills`):
27
+ ```bash
28
+ npx @lovehlmmm/primekit init
29
+ ```
30
+
31
+ ### 2. Global Scope (One-time Setup for ALL Projects)
32
+ Install skills directly into your system user directory (`~/.gemini/config/skills/`, `~/.claude/skills/`, `~/.cursor/rules/`):
33
+ ```bash
34
+ npx @lovehlmmm/primekit init --global
35
+ ```
36
+
37
+ ### 3. Global CLI Installation (Optional)
38
+ ```bash
39
+ npm install -g @lovehlmmm/primekit
40
+
41
+ # Use short commands primekit or pk anywhere:
42
+ pk init
43
+ pk init --global
44
+ ```
45
+
46
+ ---
47
+
48
+ ## ⚡ Skill Invocation (`/pk:`)
49
+
50
+ After initialization, invoke skills directly in your AI Assistant chat:
51
+
52
+ | Command | Skill Name | Description & Execution Workflow |
53
+ | :--- | :--- | :--- |
54
+ | `/pk:explore` | Codebase Scout | Deep architectural scouting, dependencies, and entry-point discovery |
55
+ | `/pk:clarify` | Requirement Clarifier | Scope gap analysis & YAGNI over-engineering elimination |
56
+ | `/pk:plan` | Implementation Planner | Multi-phase planning (`--fast`, `--deep`, `--debate`, `--ultra`) |
57
+ | `/pk:implement` | Focused Coder | Surgical code modifications with TDD support (`--tdd`) |
58
+ | `/pk:debug` | Root Cause Analyzer | 5-Whys root cause analysis & reproduction scenarios |
59
+ | `/pk:test` | Test Execution | Auto-detect test runner, execute test suite & prevent regressions |
60
+ | `/pk:review` | Diff Inspector | Git diff inspection with OWASP/STRIDE security threat modeling |
61
+ | `/pk:handoff` | Session Continuity | Package state continuation contracts for future sessions |
62
+ | `/pk:predict` | Architecture Predictor | 5-persona adversarial panel debate before coding |
63
+ | `/pk:vibe` | Autonomous Pipeline | End-to-end pipeline from GitHub Issue to pull request |
13
64
 
14
65
  ---
15
66
 
16
- ## 🚀 Hướng dẫn Cài đặt & Sử dụng (Quick Start)
67
+ ## 🛠️ PrimeKit CLI Commands
17
68
 
18
- ### 1. Khởi tạo bằng `npx` (Không cần cài đặt)
19
- Mở bất kỳ dự án/workspace nào và chạy:
69
+ | CLI Command | Description |
70
+ | :--- | :--- |
71
+ | `pk init` | Initialize PrimeKit in the current project root |
72
+ | `pk init -g` | Install PrimeKit skills globally for all local projects |
73
+ | `pk list` | List installed skills, hooks, and assistant adapters |
74
+ | `pk doctor` | Run health checks, SHA256 checksum verification & assistant compatibility |
75
+ | `pk import <skill>` | Import/clone any skill from the ecosystem (e.g., `pk import predict`) |
76
+ | `pk update` | Safely update skills & CLI (auto-backs up custom files as `.bak`) |
77
+ | `pk uninstall` | Cleanly remove files managed by PrimeKit |
78
+
79
+ ---
80
+
81
+ ## 🎯 Compatibility Matrix
82
+
83
+ PrimeKit is 100% compatible with popular AI Coding environments:
84
+
85
+ - **Claude Code (CLI)**: Detected via `.claude/skills/` and `.primekit/claude-adapter.json`.
86
+ - **Cursor IDE**: Detected via `.cursorrules` and `.cursor/rules/`.
87
+ - **Codex / OpenAI**: Detected via standard `AGENTS.md` instructions.
88
+ - **VS Code (Copilot / Gemini / Antigravity)**: Detected via `AGENTS.md` and `.gemini/config/skills/`.
89
+ - **Custom CLI Agents**: Standard CommonMark & YAML frontmatter compliant.
90
+
91
+ ---
92
+
93
+ <a name="tiếng-việt"></a>
94
+ ## 🌟 Giới thiệu PrimeKit (Tiếng Việt)
95
+
96
+ **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).
97
+
98
+ ---
99
+
100
+ ## 🚀 Hướng dẫn Cài đặt Nhanh (Quick Start)
101
+
102
+ Bạn có thể sử dụng PrimeKit ngay lập tức theo 2 cơ chế:
103
+
104
+ ### 1. Cài đặt Cấp Dự án (Project Scope - Cho cá nhân & Teamwork)
105
+ 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):
20
106
  ```bash
21
107
  npx @lovehlmmm/primekit init
22
108
  ```
23
109
 
24
- ### 2. Cài đặt Cục bộ (Global CLI)
110
+ ### 2. Cài đặt Toàn cục (Global Scope - Cài 1 lần dùng cho MỌI dự án)
111
+ Cài đặt bộ skills trực tiếp vào hệ thống cá nhân (`~/.gemini/config/skills/`, `~/.claude/skills/`, `~/.cursor/rules/`):
112
+ ```bash
113
+ npx @lovehlmmm/primekit init --global
114
+ ```
115
+
116
+ ### 3. Cài đặt CLI Global (Tùy chọn)
25
117
  ```bash
26
118
  npm install -g @lovehlmmm/primekit
27
119
 
28
- # Sử dụng qua lệnh primekit hoặc alias ngắn pk
29
- primekit init
30
- # hoặc
120
+ # Sau khi cài global, bạn có thể gõ ngắn gọn lệnh primekit hoặc pk:
31
121
  pk init
122
+ pk init --global
32
123
  ```
33
124
 
34
125
  ---
35
126
 
36
127
  ## ⚡ Cú pháp Gọi Skill Rút gọn (`/pk:`)
37
128
 
38
- PrimeKit hỗ trợ cú pháp kích hoạt skill rút gọn cực nhanh bằng tiền tố `/pk:`:
129
+ 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:
39
130
 
40
- | Lệnh Gọi Skill | Tên Skill | Vai trò & Quy trình |
131
+ | Lệnh Gọi Skill | Tên Skill | Mô tả & Quy trình Thực thi |
41
132
  | :--- | :--- | :--- |
42
133
  | `/pk:explore` | Codebase Scout | Khảo sát sâu kiến trúc repository, dependencies & entry points |
43
- | `/pk:clarify` | Requirement Clarifier | Làm rõ yêu cầu chưa đầy đủ & thách thức phạm vi YAGNI |
134
+ | `/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) |
44
135
  | `/pk:plan` | Implementation Planner | Lập kế hoạch theo giai đoạn (`--fast`, `--deep`, `--debate`, `--ultra`) |
45
136
  | `/pk:implement` | Focused Coder | Lập trình khoanh vùng chính xác (Hỗ trợ TDD `--tdd`) |
46
137
  | `/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 |
47
- | `/pk:test` | Test Execution | Tự động chạy unit/integration test suite & chống lỗi hồi quy |
138
+ | `/pk:test` | Test Execution | Tự động nhận diện runner, thực thi test suite & chống lỗi hồi quy |
48
139
  | `/pk:review` | Diff Inspector | Đánh giá git diff, kiểm tra rủi ro bảo mật OWASP/STRIDE |
49
- | `/pk:handoff` | Session Continuity | Lưu trạng thái bàn giao Hợp đồng Tiếp nối phiên sau |
140
+ | `/pk:handoff` | Session Continuity | Đóng gói Hợp đồng Tiếp nối phiên làm việc cho lần sau |
50
141
  | `/pk:predict` | Architecture Predictor | 5 Chuyên gia phản biện kiến trúc trước khi code |
51
- | `/pk:vibe` | Autonomous Pipeline | Tự động hóa luồng từ GitHub Issue tới PR hoàn chỉnh |
142
+ | `/pk:vibe` | Autonomous Pipeline | Tự động hóa luồng làm việc từ GitHub Issue tới PR |
52
143
 
53
144
  ---
54
145
 
55
- ## 🛠️ Lệnh Quản lý CLI Reference
146
+ ## 🛠️ Danh mục Lệnh PrimeKit CLI
56
147
 
57
- ```bash
58
- primekit init # Khởi tạo PrimeKit vào workspace (.primekit/, AGENTS.md, .cursorrules)
59
- primekit list # Liệt kê các skill, hooks và adapters đã cài đặt
60
- primekit doctor # Kiểm tra sức khỏe hệ thống, SHA256 checksum & tương thích Assistant
61
- primekit import <name> # Import/clone skill bất kỳ từ hệ sinh thái vào workspace (VD: pk import predict)
62
- primekit update # Cập nhật an toàn bộ skill & CLI (tự động tạo backup .bak)
63
- primekit uninstall # Gỡ bỏ sạch sẽ các thành phần do PrimeKit quản lý
64
- ```
148
+ | Lệnh CLI | Mô tả Chức năng |
149
+ | :--- | :--- |
150
+ | `pk init` | Khởi tạo PrimeKit vào thư mục dự án hiện tại |
151
+ | `pk init -g` | Cài đặt bộ skills vào hệ thống toàn cục cho mọi dự án |
152
+ | `pk list` | Liệt kê các skill, hooks và adapters đã cài đặt |
153
+ | `pk doctor` | Kiểm tra sức khỏe hệ thống, checksum SHA256 & độ tương thích AI |
154
+ | `pk import <skill>` | Clone/Import skill bất kỳ từ hệ sinh thái vào dự án (VD: `pk import predict`) |
155
+ | `pk update` | Cập nhật an toàn bộ skill & CLI (tự động sao lưu file `.bak`) |
156
+ | `pk uninstall` | Gỡ bỏ sạch sẽ các tập tin do PrimeKit quản lý |
65
157
 
66
158
  ---
67
159
 
68
- ## 📁 Cấu trúc Thư mục Dự án
69
-
70
- ```text
71
- PrimeKit/
72
- ├── .primekit/ # Thư mục chứa skills & adapters đã init trong workspace
73
- │ ├── skills/ # Tất cả skills (SKILL.md)
74
- │ └── manifest.json # File theo dõi phiên bản & checksum SHA256
75
- ├── cli/ # Mã nguồn CLI (Node.js & TypeScript)
76
- │ ├── src/ # Code nguồn (commands, adapters, utils)
77
- │ └── dist/ # Code đã biên dịch JavaScript
78
- ├── docs/ # Tài liệu hướng dẫn tiếng Việt
79
- │ ├── ARCHITECTURE.md # Kiến trúc chi tiết hệ thống
80
- │ └── USAGE.md # Hướng dẫn sử dụng CLI reference
81
- ├── benchmarks/ # 5 bài kiểm thử thực tế (Bug fix, Feature, Refactor, Review, Handoff)
82
- ├── scripts/ # Scripts kiểm thử CLI & runner benchmark
83
- ├── skills/ # Thư mục nguồn 100+ Skills (SKILL.md)
84
- ├── AGENTS.md # Quy tắc agent chuẩn hóa hệ thống
85
- ├── agnt.md # File đặc tả cấu hình Agent tối ưu
86
- ├── package.json # Cấu hình package & scripts
87
- └── tsconfig.json # Cấu hình TypeScript compiler
88
- ```
160
+ ## 🎯 Bảng Tương thích với các IDE & AI Assistants
89
161
 
90
- ---
91
-
92
- ## 🧪 Phát triển & Kiểm thử (Development & Benchmarks)
93
-
94
- ```bash
95
- # Cài đặt dependencies và build TypeScript
96
- npm install
97
- npm run build
98
-
99
- # Chạy bộ test CLI integration
100
- npm test
162
+ 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:
101
163
 
102
- # Chạy bộ đánh giá 5 kịch bản benchmark thực tế
103
- npm run benchmark
104
- ```
164
+ - **Claude Code (CLI)**: Nhận diện qua `.claude/skills/` và `.primekit/claude-adapter.json`.
165
+ - **Cursor IDE**: Nhận diện qua file cấu hình `.cursorrules` và `.cursor/rules/`.
166
+ - **Codex / OpenAI**: Nhận diện qua tập tin quy chuẩn `AGENTS.md`.
167
+ - **VS Code (Copilot / Gemini / Antigravity)**: Nhận diện qua `AGENTS.md` và `.gemini/config/skills/`.
168
+ - **Custom CLI Agents**: Tuân thủ chuẩn định dạng Markdown CommonMark & YAML Frontmatter.
105
169
 
106
170
  ---
107
171
 
package/{agnt.md → docs/AGENT_SPEC.md} RENAMED
@@ -91,7 +91,7 @@ Mỗi skill được đóng gói độc lập với file hướng dẫn (`SKILL.
91
91
 
92
92
  ---
93
93
 
94
- ### BƯỚC 4: LẬP TRÌNH CLI VÀ QUẢN LÝ VÒNG ĐỜI (CLI MANAGEMENT)
94
+ ## 🛠️ BƯỚC 4: LẬP TRÌNH CLI VÀ QUẢN LÝ VÒNG ĐỜI (CLI MANAGEMENT)
95
95
 
96
96
  Xây dựng một ứng dụng CLI nhẹ (Node.js/TypeScript hoặc Python) quản lý gói `PrimeKit`:
97
97
 
@@ -113,7 +113,7 @@ primekit uninstall # Gỡ bỏ sạch sẽ các thành phần do PrimeKit tạo
113
113
 
114
114
  ---
115
115
 
116
- ### BƯỚC 5: ĐÁNH GIÁ THỰC TẾ & BENCHMARK (EMPIRICAL EVALUATION)
116
+ ## 🧪 BƯỚC 5: ĐÁNH GIÁ THỰC TẾ & BENCHMARK (EMPIRICAL EVALUATION)
117
117
 
118
118
  Tạo thư mục `benchmarks/` chứa 5 bài kiểm thử có thể tái lập:
119
119
  1. **Bug Fix**: Tái hiện 1 lỗi cụ thể ➔ sửa lỗi ➔ pass test.
@@ -124,7 +124,7 @@ Tạo thư mục `benchmarks/` chứa 5 bài kiểm thử có thể tái lập:
124
124
 
125
125
  ---
126
126
 
127
- ### BƯỚC 6: BÀN GIAO SẢN PHẨM (FINAL DELIVERABLES)
127
+ ## 📦 BƯỚC 6: BÀN GIAO SẢN PHẨM (FINAL DELIVERABLES)
128
128
 
129
129
  Mã nguồn dự án phải sẵn sàng để nghiệm thu với cấu trúc thư mục tối thiểu:
130
130
 
@@ -138,8 +138,9 @@ PrimeKit/
138
138
  │ └── dist/index.js
139
139
  ├── docs/ # Tài liệu tiếng Việt
140
140
  │ ├── ARCHITECTURE.md # Kiến trúc chi tiết
141
- │ └── USAGE.md # Hướng dẫn sử dụng & CLI reference
141
+ │ ├── USAGE.md # Hướng dẫn sử dụng & CLI reference
142
+ │ └── AGENT_SPEC.md # File đặc tả cấu hình Agent này
142
143
  ├── benchmarks/ # 5 bài kiểm thử thực tế
143
144
  ├── README.md # Tổng quan dự án & Getting Started
144
- └── agnt.md # File đặc tả cấu hình Agent này
145
+ └── AGENTS.md # File quy tắc & điều hướng AI Assistant
145
146
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lovehlmmm/primekit",
3
- "version": "1.0.4",
3
+ "version": "1.0.7",
4
4
  "description": "Universal AI Coding Tool Suite Generator inspired by AgentKit",
5
5
  "main": "cli/dist/index.js",
6
6
  "bin": {
@@ -12,7 +12,7 @@
12
12
  "skills",
13
13
  "docs",
14
14
  "README.md",
15
- "agnt.md"
15
+ "AGENTS.md"
16
16
  ],
17
17
  "publishConfig": {
18
18
  "access": "public"
package/skills/ak/SKILL.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: pk:primekit
2
+ name: pk:ak
3
3
  description: "Operate the primekit control-plane CLI itself — the PrimeKit binary that installs, inspects, updates, recovers, and removes kits and their skills. Use when the next action is invoking an primekit subcommand (init, kit, skills, plan, journal, doctor, recover, self-update, login), deciding between read-only inspection and lifecycle mutation, disambiguating project vs global scope, or interpreting primekit --json output. Not for authoring skills (use pk:skill-creator) or routing generic work (use pk:primekit)."
4
4
  user-invocable: true
5
5
  when_to_use: "Invoke when the next action is running an primekit subcommand or interpreting its output. Do not invoke for skill authoring (pk:skill-creator), plan writing (pk:plan), journal writing (pk:journal), generic task routing (pk:primekit), or kit-specific workflows already covered by their own skills."