@mrtrinhvn/ag-kit 1.0.6 → 1.0.7

package/.agent/skills/lint-and-validate/scripts/lint_runner.py

@@ -14,8 +14,6 @@ Supports:
 import subprocess
 import sys
 import json
-import platform
-import shutil
 from pathlib import Path
 from datetime import datetime
 
@@ -79,24 +77,14 @@ def run_linter(linter: dict, cwd: Path) -> dict:
     }
     
     try:
-        cmd = linter["cmd"]
-        
-        # Windows compatibility for npm/npx
-        if platform.system() == "Windows":
-            if cmd[0] in ["npm", "npx"]:
-                # Force .cmd extension on Windows
-                if not cmd[0].lower().endswith(".cmd"):
-                    cmd[0] = f"{cmd[0]}.cmd"
-        
         proc = subprocess.run(
-            cmd,
+            linter["cmd"],
             cwd=str(cwd),
             capture_output=True,
             text=True,
             encoding='utf-8',
             errors='replace',
-            timeout=120,
-            shell=platform.system() == "Windows" # Shell=True often helps with path resolution on Windows
+            timeout=120
         )
         
         result["output"] = proc.stdout[:2000] if proc.stdout else ""

package/.agent/skills/memory-architecture/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: memory-architecture
+description: >
+  Hệ thống Bộ nhớ Đồ thị Đa Tầng (Multi-layered Graph Memory) cho Agent.
+  Hợp nhất giữa Progressive Disclosure (L1, L2, L3) và Temporal Knowledge Graph (Node-Edge).
+---
+
+# Multi-layered Graph Memory Architecture
+
+> 🔴 **CRITICAL RULE**: Trí nhớ của Agent không còn là Text phẳng. Nó là một **Đồ thị Tri thức Đa tầng (Graph)** cho phép "Zoom-out" nhìn toàn cảnh và "Zoom-in" đọc chi tiết lõi.
+
+---
+
+## 1. Nguyên tắc cốt lõi: 3 Tầng Ký ức (L1/L2/L3)
+
+```text
+L1 (Zoom Out) → session_summary & Core_Nodes  — "Toàn cảnh dự án, các khái niệm lõi"
+L2 (Mid)      → category-indexed & Edges      — "Mạng lưới quan hệ, mạch sự kiện"
+L3 (Zoom In)  → detail_record & Solutions     — "Chi tiết lỗi, code snippet gốc"
+```
+
+---
+
+## 2. Hình thái Dữ liệu cấp thấp (Node-Edge Graph)
+
+Mọi dữ liệu trong tầng L1/L2/L3 đều được lưu dưới dạng Đồ thị (Graph):
+
+### A. NODES (Hạt nhân Kiến thức)
+Các khái niệm định danh tĩnh. Vd: `[Node:DB_PORT] => 5432 (Energy: 100)`
+
+### B. EDGES / EPISODES (Mạch Câu chuyện)
+Luồng sự kiện liên kết. Vd: `[Node:USER] --(muốn mở port)--> [Node:DB_PORT]`
+
+### Progressive Disclosure (Tiết kiệm Token):
+Thay vì load toàn bộ Memory, hệ thống truy vấn tự động theo dạng Phóng to/Thu nhỏ:
+1. **Search (Zoom Out):** Chỉ lấy mỏ neo 1-2 Node lõi + Quan hệ (L1/L2) (Tốn rất ít token).
+2. **Details (Zoom In):** Nếu AI cần phân tích sâu 1 đoạn code phức tạp, gọi L3 (Token cao hơn nhưng cực kỳ chính xác).
+
+---
+
+## 3. Vòng đời Trí nhớ (Biocybernetic Lifecycle)
+
+1. **Temporal Decay (Phai mờ):** Mỗi Node và Edge có `Energy`. Bị hao hụt tự động mỗi 24h. L1 siêu bền, L3 hao nhanh.
+2. **Reinforcement (Củng cố):** Mỗi lần "bò" (traversal) qua Node, Energy phục hồi.
+3. **Consolidation (Ngủ):** Cứ đêm đến, AI gộp các mạch nhớ L3/L2 rườm rà thành 1 Node L1 khái quát siêu bền.
+4. **Forgetting (Quên lãng):** Node có `Energy < 0` HOẶC mồ côi (không ai gọi tới) sẽ BỊ XOÁ (Quét rác sinh học).
+
+---
+
+## 4. Bảng Phân loại Khối Lượng Ký ức
+
+| Target / Kiểu Node | Tầng | Giải thích | Energy Khởi tạo | Mức độ Tự Phân Hủy (Decay) |
+|---|---|---|---|---|
+| `session_summary` | L1 | Toàn cảnh phiên làm việc | 100 | Lâu dài (Gần như không) |
+| `Core_Fact` | L1 | Cấu hình, IP, Convention cốt lõi | 100 | Gần như không |
+| `User_Pref` | L2 | Thói quen user | 80 | Cực chậm |
+| `project_context` | L2 | Ngữ cảnh dự án hiện tại | 80 | Trung hạn (Cập nhật đổi version) |
+| `Episode_Edge` | L2 | "Hôm qua đã làm gì" | 30 | Nhanh (Rất mau phai mờ) |
+| `error_solution` | L3 | Bug log + Code fix cụ thể | 50 | Trung bình (Công nghệ đổi -> Xóa) |
+
+---
+
+## 5. Workflow Tương tác Trí Nhớ (Mô phỏng GraphRAG)
+
+### KHI BẮT ĐẦU task mới (Retrieve):
+```text
+1. Bắn 1 tia Vector Search thả mỏ neo vào Đồ thị (Tìm L1/L2).
+2. Khôi phục lại Mạch Câu Chuyện bằng cách "Bò" dọc theo Edges lân cận (BFS).
+3. Nếu cần code chính xác của 1 Bug, gọi lệnh lấy Detail (L3).
+```
+
+### KHI KẾT THÚC task (Commit):
+❌ **Sai:** Lưu text rác `memory_save("Fix xong bug X")` vào trong hư không.
+✅ **Đúng:** 
+```text
+1. Khởi tạo Node mới: Node[Fix_CORS] = "Thiếu accept headers"
+2. Nối Mạch: Node[Env_Prod] --(gặp lỗi)=> Node[Fix_CORS]
+3. (Tùy chọn) Gắn thêm Detail record vào L3 nếu fix cực phức tạp cần giữ code snippet.
+```
+
+---
+
+## 6. Anti-Patterns Kịch Độc
+
+```text
+❌ Gọi L3 load toàn bộ chi tiết khi không cần thiết (Tràn token).
+❌ Cố gắng chèn 200 dòng code vào Tên của Node (Node chỉ giữ Context lõi, Code đẩy xuống L3).
+❌ Tạo Node rác không gán Edge quan hệ. (Garbage Collector sẽ chém thẳng tay).
+```
+
+---
+
+## 7. Giao thức Tự động Dịch chuyển Ký ức (Self-Migration Protocol)
+
+> **Dành cho các AI Agent hoạt động trong dự án cũ (Legacy Projects) vừa được cập nhật `ag-kit` thông qua `npx`.**
+
+Khi bạn (AI) nhận thức được mình đang ở trong một dự án đã có sẵn dữ liệu ký ức cũ (chứa trong các file `.jsonl` hoặc `memory.db` phẳng), bạn **CÓ TRÁCH NHIỆM TỰ ĐỘNG** thực hiện quá trình "Memory Migration" (Dịch chuyển Ký ức) mà không cần User yêu cầu, theo các bước sau:
+
+1. **Phát hiện:** Dùng lệnh đọc file hoặc MCP để quét nội dung các ký ức cũ trong thư mục `data/memories/` (nếu có).
+2. **Băm nhỏ (Chunking & Entity Extraction):** Phân tích các đoạn log cũ xem chúng nói về chủ đề gì (vd: Lịch sử fix bug, Convention code cũ, Sở thích User).
+3. **Tái cấu trúc (Graph Construction):**
+   - Từ các đoạn text đó, rút trích ra các `Nodes` cốt lõi mang tính sự thật (Core Facts).
+   - Thiết lập các `Edges` (Mạch kết nối) mô tả luồng logic giữa các Nodes đó.
+4. **Lưu trữ (Commit):** Lưu bộ Graph vừa tạo vào cơ sở dữ liệu mới (thông qua `GraphMemoryTool` nếu dự án đã hỗ trợ, hoặc lưu ngược lại bằng `memory_save` dưới cấu trúc **Pseudo-Graph** cực đoan: `[Node:A] --[rel]--> [Node:B]` nếu nền tảng chưa được nâng cấp DB SQLite).
+
+Bằng giao thức này, kiến thức của dự án sẽ KHÔNG BAO GIỜ bị đứt gãy sau khi cập nhật kiến trúc. Mọi ký ức quá khứ sẽ tự động "tiến hóa" thành dạng Đồ thị tương lai!
+

package/.agent/skills/mini-antigravity-injection/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: mini-antigravity-injection
+description: Kiến trúc Cấy Lõi Tự Đẩy & Tiến Hoá (Self-Healing & Autonomous Code Mutation) cho Dự Án. Hướng dẫn Agent cách xây dựng bộ máy Tự Code, Tự Fix Lỗi và Tự Hot-Reload định chuẩn TDD.
+---
+
+# KỸ NĂNG: CẤY TIỂU-ANTIGRAVITY (Self-Healing Core Injection)
+
+Khi User yêu cầu "Cấy Tiểu-Antigravity" vào một chức năng hay dự án mới, User đang ám chỉ việc xây dựng một hệ thống **Tiến hoá Mã nguồn Tự trị**. Bạn phải tuân thủ nghiêm ngặt 3 Phần dưới đây để tiến hành xây dựng.
+
+---
+
+## PHẦN A: THIẾT LẬP HẠ TẦNG & QUYỀN TRUY CẬP (Prerequisites)
+Để Lõi Bác Sĩ (Doctor Persona) có trí tuệ mổ xẻ code, Hệ thống bắt buộc phải có tài nguyên LLM. Trước khi viết code, bạn phải kiểm tra và hướng dẫn User cài đặt hoặc cấu hình các thông số sau:
+
+### 1. Trí Tuệ Trung Tâm: Cổng 9Router (Gemini Pro)
+- **Chuẩn bị:** Yêu cầu hệ thống phải đang chạy cổng `9router` (Mặc định). 
+- **Token:** User cần cài đặt `9router` (nếu chưa có), đăng nhập các tài khoản Antigravity / Google Hub để `9router` cấp phát Token hợp lệ cho Tiểu Antigravity.
+- **Hoặc:** Nếu không dùng 9router, hệ thống phải được cấu hình chèn cứng `GEMINI_API_KEY` trực tiếp vào biến môi trường.
+- **Biến môi trường:** Đặt `HEALER_MODEL="ag/gemini-3-flash"` hoặc `"ag/gemini-pro-1.5"` cho luồng Mổ Xẻ.
+
+### 2. Trí Tuệ Sinh Tồn (Offline Fallback): Ollama & Bartowski
+- **Mục đích:** Khi đứt cáp hoặc không gọi được 9Router/Gemini, Quản Đốc văng lỗi sẽ chết đứng nếu không có Backup.
+- **Thực thi:** Yêu cầu User cài đặt Ollama local (`https://ollama.com/`).
+- **Tải Model:** Chạy lệnh `ollama run hf.co/bartowski/nvidia_Orchestrator-8B-GGUF:Q4_K_M` để kéo chuyên gia Lập trình Local (Tay cắt mổ phụ).
+- **Cấu hình Fallback:** Module Code xử lý mạng phải đảm bảo: Nếu `gemini` timeout hoặc 404 -> Fallback trực tiếp xuống mốc local `hf.co/bartowski/nvidia_Orchestrator-8B-GGUF:Q4_K_M`.
+
+---
+
+## PHẦN B: LÕI TRIẾT LÝ KIẾN TRÚC (5 Trụ Cột Tiểu-Antigravity)
+Khi bạn (AI) tự động tạo code `SelfHealingService` cho dự án mới, bạn phải đúc đủ 5 trụ cột này vào code:
+
+### 1. Cơ Chế Bơm Kiến Thức Vĩ Mô (Skill & DNA Injection)
+- Code tự động đọc các file nguyên tắc lập trình của dự án (`.agent/GEMINI.md`, `clean-code/SKILL.md`...) và TIÊM vào System Prompt của LLM Bác Sĩ Cục Bộ. Đảm bảo nó code đúng văn phong của Antigravity.
+
+### 2. Định Luật Cạn Kiệt Gen (Exhaustion Trigger)
+- Hệ thống bắt Stack Trace. Nếu lỗi Tool/Code gãy 3 lần (Vòng lặp bất tận) -> Kích Hoạt Tiểu-Antigravity chữa cháy tự động.
+
+### 3. Hộp Cát Tử Thần (Sandbox) & Lá Chắn Ngữ Nghĩa (Semantic Shield)
+Tuyệt đối KHÔNG đẩy code vừa sinh thẳng vào Môi trường Thực Chiến.
+- **Phase 1 (Doctor):** Dùng prompt áp dụng `5-Whys` tìm Root Cause và viết mới lại file Code.
+- **Phase 2 (Syntax Test):** Build/Compile Dry-run qua trình biên dịch (VD: `tsc --noEmit`).
+- **Phase 3 (Semantic Shield):** Cốt lõi của sự Khôn ngoan! Hệ thống tự rà file Unit Test đi kèm (`*.spec.ts` hoặc `*.test.ts`). Chạy **Test Ngữ Nghĩa (Logic)** với file mới. Nếu Logic tính toán sai (dù cú pháp đúng) -> Đánh sập nhánh đó, cấm Hot-Reload.
+
+### 4. Giao Kèo Docstring Định Danh (Docstring Identity Pact)
+- Ép Prompt của Bác Sĩ: Khai báo đa dòng ở đầu file Code mới: Sửa dòng nào? Tại sao sửa? Tuân thủ triết lý gì?
+
+### 5. Nạp Nóng (Hot-Reload) & Sổ Ghi Chép Chung (Evolution Ledger)
+- **Git Backup:** Ghi `.bak`, commit Git.
+- **Hot-Reload:** Tự xoá cache (`require.cache` trong JS) nạp RAM trực tiếp.
+- **Ghi Chép:** Bắn Log Tự Sinh Tồn vào `self_healing_logs.md` để Ký ức được đồng bộ khi Main Agent (Antigravity Sếp) tỉnh dậy.
+
+---
+
+## PHẦN C: CÁCH TRIỂN KHAI CHO DỰ ÁN MỚI
+*(Ghi chú cho Antigravity: Không cần lưu cứng bộ boilerplate code vào ag-kit).*
+Khi User ra lệnh "Cấy Tiểu-Antigravity cho tao", bạn (Agent đang chat) tự động làm các bước sau:
+1. Đặt Câu Hỏi Hạ Tầng: Xác nhận 9Router và Ollama đã on-ready theo `PHẦN A`.
+2. Tự Động Viết Code: Tự phân tích Framework của dự án (TS/Node, Python, Rust) và Code ra file `SelfHealingService` theo triết lý của `PHẦN B`.
+3. Tự Động Test: Viết 1 file test làm hỏng kiến trúc cố ý (`BrokenTool`), kích hoạt tiến trình Tự Động Vá Lỗi để chứng minh hệ thống đã On-Air thành công cho User xem!

package/.agent/skills/nextjs-react-expert/1-async-eliminating-waterfalls.md

@@ -7,7 +7,7 @@
 
 ## Overview
 
-This section contains **6 rules** focused on eliminating waterfalls, now including Next.js 16 `after()` and `connection()` patterns.
+This section contains **5 rules** focused on eliminating waterfalls.
 
 ---
 
@@ -310,42 +310,3 @@ Both components share the same promise, so only one fetch occurs. Layout renders
 
 **Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
 
-
----
-
-## Rule 1.6: Use `after()` and `connection()` (Next.js 16+)
-
-**Impact:** HIGH  
-**Tags:** nextjs16, async, runtime, performance
-
-Next.js 16 introduced APIs to prevent "Blocking the Main Thread" and ensure "Dynamic Runtime" awareness.
-
-### 1. `after()` for Non-Blocking Logic
-Avoid `await` on logic that doesn't affect the initial UI (logging, analytics, emails).
-
-```tsx
-import { after } from 'next/server'
-
-export default async function Page() {
-  const data = await fetchData() // CRITICAL
-  
-  after(() => {
-    // RUNS AFTER THE RESPONSE IS SENT
-    logTrack(data) 
-  })
-
-  return <View data={data} />
-}
-```
-
-### 2. `connection()` for Dynamic Intent
-Use `connection()` to signal that a component is dynamic and should not be pre-rendered as static, allowing other parts of the page to stream independently.
-
-```tsx
-import { connection } from 'next/server'
-
-async function DynamicData() {
-  await connection() // Signals dynamic intent
-  return await fetchFreshData()
-}
-```

package/.agent/skills/nextjs-react-expert/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: react-best-practices
+name: nextjs-react-expert
 description: React and Next.js performance optimization from Vercel Engineering. Use when building React components, optimizing performance, eliminating waterfalls, reducing bundle size, reviewing code for performance issues, or implementing server/client-side optimizations.
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 ---
@@ -21,17 +21,16 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 
 ## 📑 Content Map
 
-| File                                    | Impact             | Rules    | When to Read                                                    |
-| --------------------------------------- | ------------------ | -------- | --------------------------------------------------------------- |
-| `1-async-eliminating-waterfalls.md`     | 🔴 **CRITICAL**    | 5 rules  | Slow page loads, sequential API calls, data fetching waterfalls |
-| `2-bundle-bundle-size-optimization.md`  | 🔴 **CRITICAL**    | 5 rules  | Large bundle size, slow Time to Interactive, First Load issues  |
-| `3-server-server-side-performance.md`   | 🟠 **HIGH**        | 7 rules  | Slow SSR, API route optimization, server-side waterfalls        |
-| `4-client-client-side-data-fetching.md` | 🟡 **MEDIUM-HIGH** | 4 rules  | Client data management, SWR patterns, deduplication             |
-| `5-rerender-re-render-optimization.md`  | 🟡 **MEDIUM**      | 12 rules | Excessive re-renders, React performance, memoization            |
-| `6-rendering-rendering-performance.md`  | 🟡 **MEDIUM**      | 9 rules  | Rendering bottlenecks, virtualization, image optimization       |
-| `7-js-javascript-performance.md`        | ⚪ **LOW-MEDIUM**  | 12 rules | Micro-optimizations, caching, loop performance                  |
-| `8-advanced-advanced-patterns.md`       | 🔵 **VARIABLE**    | 3 rules  | Advanced React patterns, useLatest, init-once                   |
-| `9-cache-components.md`                | 🔴 **CRITICAL**    | 4 sections | **Next.js 16+ Only**: `use cache`, `cacheLife`, PPR, `cacheTag` |
+| File | Impact | Rules | When to Read |
+|------|--------|-------|--------------|
+| `1-async-eliminating-waterfalls.md` | 🔴 **CRITICAL** | 5 rules | Slow page loads, sequential API calls, data fetching waterfalls |
+| `2-bundle-bundle-size-optimization.md` | 🔴 **CRITICAL** | 5 rules | Large bundle size, slow Time to Interactive, First Load issues |
+| `3-server-server-side-performance.md` | 🟠 **HIGH** | 7 rules | Slow SSR, API route optimization, server-side waterfalls |
+| `4-client-client-side-data-fetching.md` | 🟡 **MEDIUM-HIGH** | 4 rules | Client data management, SWR patterns, deduplication |
+| `5-rerender-re-render-optimization.md` | 🟡 **MEDIUM** | 12 rules | Excessive re-renders, React performance, memoization |
+| `6-rendering-rendering-performance.md` | 🟡 **MEDIUM** | 9 rules | Rendering bottlenecks, virtualization, image optimization |
+| `7-js-javascript-performance.md` | ⚪ **LOW-MEDIUM** | 12 rules | Micro-optimizations, caching, loop performance |
+| `8-advanced-advanced-patterns.md` | 🔵 **VARIABLE** | 3 rules | Advanced React patterns, useLatest, init-once |
 
 **Total: 57 rules across 8 categories**
 
@@ -68,9 +67,6 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 
 ✨ Need advanced patterns
   → Read Section 8: Advanced Patterns
-
-🚀 **Next.js 16+ Performance (Caching & PPR)**
-  → Read Section 9: Cache Components
 ```
 
 ---
@@ -98,23 +94,20 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 4️⃣ LOW (Polish - Do Last):
    ├─ Section 7: JavaScript Performance
    └─ Section 8: Advanced Patterns
-
-🔥 **MODERN (Next.js 16+):**
-   └─ Section 9: Cache Components (Replaces most traditional revalidation)
 ```
 
 ---
 
 ## 🔗 Related Skills
 
-| Need                    | Skill                             |
-| ----------------------- | --------------------------------- |
-| API design patterns     | `@[skills/api-patterns]`          |
-| Database optimization   | `@[skills/database-design]`       |
-| Testing strategies      | `@[skills/testing-patterns]`      |
-| UI/UX design principles | `@[skills/frontend-design]`       |
-| TypeScript patterns     | `@[skills/typescript-expert]`     |
-| Deployment & DevOps     | `@[skills/deployment-procedures]` |
+| Need | Skill |
+|------|-------|
+| API design patterns | `@[skills/api-patterns]` |
+| Database optimization | `@[skills/database-design]` |
+| Testing strategies | `@[skills/testing-patterns]` |
+| UI/UX design principles | `@[skills/frontend-design]` |
+| TypeScript patterns | `@[skills/typescript-expert]` |
+| Deployment & DevOps | `@[skills/deployment-procedures]` |
 
 ---
 
@@ -123,7 +116,6 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 Before shipping to production:
 
 **Critical (Must Fix):**
-
 - [ ] No sequential data fetching (waterfalls eliminated)
 - [ ] Bundle size < 200KB for main bundle
 - [ ] No barrel imports in app code
@@ -131,21 +123,18 @@ Before shipping to production:
 - [ ] Parallel data fetching where possible
 
 **High Priority:**
-
 - [ ] Server components used where appropriate
 - [ ] API routes optimized (no N+1 queries)
 - [ ] Suspense boundaries for data fetching
 - [ ] Static generation used where possible
 
 **Medium Priority:**
-
 - [ ] Expensive computations memoized
 - [ ] List rendering virtualized (if > 100 items)
 - [ ] Images optimized with next/image
 - [ ] No unnecessary re-renders
 
 **Low Priority (Polish):**
-
 - [ ] Hot path loops optimized
 - [ ] RegExp patterns hoisted
 - [ ] Property access cached in loops
@@ -155,7 +144,6 @@ Before shipping to production:
 ## ❌ Anti-Patterns (Common Mistakes)
 
 **DON'T:**
-
 - ❌ Use sequential `await` for independent operations
 - ❌ Import entire libraries when you need one function
 - ❌ Use barrel exports (`index.ts` re-exports) in app code
@@ -165,7 +153,6 @@ Before shipping to production:
 - ❌ Use client components when server components work
 
 **DO:**
-
 - ✅ Fetch data in parallel with `Promise.all()`
 - ✅ Use dynamic imports: `const Comp = dynamic(() => import('./Heavy'))`
 - ✅ Import directly: `import { specific } from 'library/specific'`
@@ -179,20 +166,17 @@ Before shipping to production:
 ## 🎯 How to Use This Skill
 
 ### For New Features:
-
 1. Check **Section 1 & 2** while building (prevent waterfalls, keep bundle small)
 2. Use server components by default (Section 3)
 3. Apply memoization for expensive operations (Section 5)
 
 ### For Performance Reviews:
-
 1. Start with **Section 1** (waterfalls = biggest impact)
 2. Then **Section 2** (bundle size)
 3. Then **Section 3** (server-side)
 4. Finally other sections as needed
 
 ### For Debugging Slow Performance:
-
 1. Identify the symptom (slow load, lag, etc.)
 2. Use Quick Decision Tree above
 3. Read relevant section
@@ -217,8 +201,8 @@ Before shipping to production:
 
 ## 🔍 Validation Script
 
-| Script                                 | Purpose                     | Command                                                      |
-| -------------------------------------- | --------------------------- | ------------------------------------------------------------ |
+| Script | Purpose | Command |
+|--------|---------|---------|
 | `scripts/react_performance_checker.py` | Automated performance audit | `python scripts/react_performance_checker.py <project_path>` |
 
 ---
@@ -226,42 +210,34 @@ Before shipping to production:
 ## 📖 Section Details
 
 ### Section 1: Eliminating Waterfalls (CRITICAL)
-
 **Impact:** Each waterfall adds 100-500ms+ latency
 **Key Concepts:** Parallel fetching, Promise.all(), Suspense boundaries, preloading
 
 ### Section 2: Bundle Size Optimization (CRITICAL)
-
 **Impact:** Directly affects Time to Interactive, Largest Contentful Paint
 **Key Concepts:** Dynamic imports, tree-shaking, barrel import avoidance
 
 ### Section 3: Server-Side Performance (HIGH)
-
 **Impact:** Faster server responses, better SEO
 **Key Concepts:** Parallel server fetching, streaming, API route optimization
 
 ### Section 4: Client-Side Data Fetching (MEDIUM-HIGH)
-
 **Impact:** Reduces redundant requests, better UX
 **Key Concepts:** SWR deduplication, localStorage caching, event listeners
 
 ### Section 5: Re-render Optimization (MEDIUM)
-
 **Impact:** Smoother UI, less wasted computation
 **Key Concepts:** React.memo, useMemo, useCallback, component structure
 
 ### Section 6: Rendering Performance (MEDIUM)
-
 **Impact:** Better rendering efficiency
 **Key Concepts:** Virtualization, image optimization, layout thrashing
 
 ### Section 7: JavaScript Performance (LOW-MEDIUM)
-
 **Impact:** Incremental improvements in hot paths
 **Key Concepts:** Loop optimization, caching, RegExp hoisting
 
 ### Section 8: Advanced Patterns (VARIABLE)
-
 **Impact:** Specific use cases
 **Key Concepts:** useLatest hook, init-once patterns, event handler refs
 
@@ -270,7 +246,6 @@ Before shipping to production:
 ## 🎓 Best Practices Summary
 
 **Golden Rules:**
-
 1. **Measure first** - Use React DevTools Profiler, Chrome DevTools
 2. **Biggest impact first** - Waterfalls → Bundle → Server → Micro
 3. **Don't over-optimize** - Focus on real bottlenecks
@@ -278,7 +253,6 @@ Before shipping to production:
 5. **Think about users** - Real-world conditions matter
 
 **Performance Mindset:**
-
 - Every `await` in sequence = potential waterfall
 - Every `import` = potential bundle bloat
 - Every re-render = wasted computation (if unnecessary)

package/.agent/skills/nextjs-react-expert/scripts/convert_rules.py

@@ -187,7 +187,7 @@ def main():
     # Paths
     base_dir = Path(__file__).parent.parent.parent.parent.parent
     rules_dir = base_dir / "others/agent-skills/skills/react-best-practices/rules"
-    output_dir = base_dir / ".agent/skills/react-best-practices"
+    output_dir = base_dir / ".agent/skills/nextjs-react-expert"
 
     print(f"[*] Reading rules from: {rules_dir}")
     print(f"[*] Output to: {output_dir}")

package/.agent/skills/plan-writing/SKILL.md

@@ -13,15 +13,16 @@ This skill provides a framework for breaking down work into clear, actionable ta
 
 ## Task Breakdown Principles
 
-### 1. Small, Focused Tasks
-- Each task should take 2-5 minutes
-- One clear outcome per task
-- Independently verifiable
-
-### 2. Clear Verification
-- How do you know it's done?
-- What can you check/test?
-- What's the expected output?
+### 1. Kỷ Luật Micro-Tasking (Hành động 5 phút)
+ - Each task should take 2-5 minutes MAXIMUM.
+ - Tên Task KHÔNG PHẢI LÀ "Làm tính năng X". Tên Task phải là **hành động cụ thể trên 1 file cụ thể**.
+ - VD Sai: `[ ] Thêm logic phân quyền`
+ - VD Đúng: `[ ] Taọ file auth.middleware.ts, đọc token từ header và trả về role.`
+ 
+ ### 2. Clear Verification & TDD (Nếu có thể)
+ - How do you know it's done?
+ - What exact command to run? (e.g. `npm run test auth.test.ts`)
+ - What's the expected output?
 
 ### 3. Logical Ordering
 - Dependencies identified
@@ -50,15 +51,15 @@ This skill provides a framework for breaking down work into clear, actionable ta
 
 ---
 
-### Principle 2: Be SPECIFIC, Not Generic
-
-| ❌ Wrong | ✅ Right |
-|----------|----------|
-| "Set up project" | "Run `npx create-next-app`" |
-| "Add authentication" | "Install next-auth, create `/api/auth/[...nextauth].ts`" |
-| "Style the UI" | "Add Tailwind classes to `Header.tsx`" |
-
-> **Rule:** Each task should have a clear, verifiable outcome.
+### Principle 2: Be STRICTLY SPECIFIC (File-Level)
+ 
+ | ❌ Wrong (Cấm Tuyệt Đối) | ✅ Right (Chuẩn Superpowers) |
+ |----------|----------|
+ | "Set up project" | "Run `npx create-next-app`" |
+ | "Add authentication" | "Tạo `api/auth.ts`, code hàm verify JWT và trả 401" |
+ | "Style the UI" | "Mở `Header.tsx`, đổi bg-white thành bg-slate-900" |
+ 
+ > **Rule:** Mỗi task là một phát súng bắn tỉa chính xác vào 1 file. Không viết task bắn tỉa mù.
 
 ---
 
@@ -110,19 +111,19 @@ This skill provides a framework for breaking down work into clear, actionable ta
 
 ## Plan Structure (Flexible, Not Fixed!)
 
-```
-# [Task Name]
-
-## Goal
-One sentence: What are we building/fixing?
-
-## Tasks
-- [ ] Task 1: [Specific action] → Verify: [How to check]
-- [ ] Task 2: [Specific action] → Verify: [How to check]
-- [ ] Task 3: [Specific action] → Verify: [How to check]
-
-## Done When
-- [ ] [Main success criteria]
+```markdown
+ # [Tên tính năng ngắn gọn]
+ 
+ > **MANDATORY STEP BEFORE PLAN:** Đã đọc `.agent/knowledge/architecture_decisions.md` (ADR) để không lập kế hoạch sai luồng công nghệ chưa?
+ 
+ ## Tasks 
+ - [ ] `path/to/file1.py`: [Chính xác hàm gì cần thêm/sửa, tốn bao nhiêu phút?]
+   -> Verify: Chạy `pytest file1`, output X.
+ - [ ] `path/to/file2.ts`: [Chỉnh sửa dòng nào thành dòng nào?]
+   -> Verify: Bật browser check console log.
+ 
+ ## Done When
+ - [ ] [Main success criteria]
 ```
 
 > **That's it.** No phases, no sub-sections unless truly needed.

package/.agent/skills/product-management/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: product-management
+description: Skill nhập vai Product Manager. Viết PRD (Product Requirement Doc), lên Lộ trình (Roadmap) và theo dõi KPI.
+allowed-tools: Read, Write
+version: 1.0
+priority: HIGH
+---
+
+# Kỹ năng Quản Trị Sản Phẩm (Product Management)
+
+> **MỤC TIÊU:** Khi User muốn bổ sung "Tính năng mới", bạn KHÔNG PHẢI là Coder. Bạn là một Giám Đốc Sản Phẩm (PM).
+
+Hãy từ chối viết code ngay lập tức. Thay vào đó, hãy kích hoạt Kỹ năng PM:
+
+## 1. Viết PRD (Product Requirement Document)
+Bắt buộc trải qua quy trình Mổ xẻ tính năng:
+*   **Vấn đề cốt lõi:** User/Khách hàng đang gặp nỗi đau gì?
+*   **Giải pháp:** Tính năng này giải quyết nỗi đau đó như thế nào?
+*   **User Story:** "Là một [Vai trò], tôi muốn [Hành động] để [Nhận được giá trị gì]."
+*   **Out of Scope:** Tính năng này RÕ RÀNG KHÔNG LÀM điều gì?
+
+## 2. Đo Lường (Metrics & KPIs)
+*   Tính năng này sẽ được cho là "Thành công" khi chỉ số nào tăng/giảm? (Ví dụ: Số lượng Click vào nút Mua Hàng, Giảm độ trễ API xuống dưới 20ms).
+*   Công cụ Tracking dự kiến là gì? (Google Analytics, Sentry, Custom DB?)
+
+## 3. Lộ Trình (Roadmap Phân Nhỏ)
+Sử dụng tư duy của `plan-writing`: Chẻ nhỏ tính năng lớn thành nhiều viên gạch 5-phút. Viết rõ ràng từng viên gạch.
+
+> **QUY TẮC SẮT (PM RULE):**
+> Chỉ khi PRD và User Story được User "Gật đầu Approval", bạn mới được phép thoát vai PM và gọi `Task Boundary` chuyển sang vai Coder để Code.

package/.agent/skills/systematic-debugging/SKILL.md

@@ -100,10 +100,21 @@ grep -r "errorPattern" --include="*.ts"
 pm2 logs app-name --err --lines 100
 ```
 
+## 🛡️ Tool Use Guardian (Execution Protection)
+
+When executing long chains of tool calls (especially when searching, indexing, or scraping), you MUST act as a Guardian of the execution:
+1. **Pre-Call Validation:** Validate file paths and parameters before executing. Don't guess or hallucinate paths.
+2. **Failure Recovery:** If a tool fails (Timeout, Rate Limit, Truncated JSON), **DO NOT panic and restart from scratch**.
+   - *Truncated:* Use `view_file` with line ranges to fetch the rest.
+   - *Timeout:* Simplify the bash command or narrow the `grep_search` scope.
+   - *Error-as-200:* Always check tool output for disguised `{"error": ...}` messages before assuming success.
+3. **Checkpoints:** Maintain logical mental checkpoints. If Step 5 of a 10-step process fails, resume exactly at Step 5.
+
 ## Anti-Patterns
 
 ❌ **Random changes** - "Maybe if I change this..."
 ❌ **Ignoring evidence** - "That can't be the cause"
+❌ **Assuming Data/API is dead** - Concluding an API endpoint is removed or data is unavailable just because a simple test failed (e.g., testing outside of service hours or without proper auth). ALWAYS check official documentation or sample SDK code before declaring an API dead.
 ❌ **Assuming** - "It must be X" without proof
 ❌ **Not reproducing first** - Fixing blindly
 ❌ **Stopping at symptoms** - Not finding root cause

package/.agent/skills/tdd-workflow/SKILL.md

@@ -134,15 +134,14 @@ Every test follows:
 
 ---
 
-## 10. AI-Augmented TDD
+## 10. Cognitive Roleplay TDD
 
-### Multi-Agent Pattern
+### Solo-Agent Pattern
 
-| Agent | Role |
-|-------|------|
-| Agent A | Write failing tests (RED) |
-| Agent B | Implement to pass (GREEN) |
-| Agent C | Optimize (REFACTOR) |
+As a solo agent, you must explicitly shift cognitive contexts:
+1. **Tester Persona**: Write failing tests (RED)
+2. **Coder Persona**: Implement minimal code to pass (GREEN)
+3. **Architect Persona**: Critically review and optimize (REFACTOR)
 
 ---