@mrtrinhvn/ag-kit 1.0.6 → 1.0.8

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)
 
 ---
 

package/.agent/workflows/orchestrate.md

@@ -63,11 +63,11 @@ $ARGUMENTS
 ```
 After PLAN.md is complete, ASK:
 
-"✅ Plan created: docs/PLAN.md
+"✅ Plan oluşturuldu: docs/PLAN.md
 
-Do you approve? (Y/N)
-- Y: Start implementation
-- N: I'll revise the plan"
+Onaylıyor musunuz? (Y/N)
+- Y: Implementation başlatılır
+- N: Planı düzeltirim"
 ```
 
 > 🔴 **DO NOT proceed to Phase 2 without explicit user approval!**
@@ -160,8 +160,8 @@ When invoking ANY subagent, you MUST include:
 Use the project-planner agent to create PLAN.md:
 
 **CONTEXT:**
-- User Request: "A social platform for students, using mock data"
-- Decisions: Tech=Vue 3, Layout=Grid Widgets, Auth=Mock, Design=Youthful & dynamic
+- User Request: "Öğrenciler için sosyal platform, mock data ile"
+- Decisions: Tech=Vue 3, Layout=Grid Widget, Auth=Mock, Design=Genç Dinamik
 - Previous Work: Orchestrator asked 6 questions, user chose all options
 - Current Plan: playful-roaming-dream.md exists in workspace with initial structure
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrtrinhvn/ag-kit",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Antigravity Kit Base Framework - Generic Agentic AI Programming Core",
   "main": "index.js",
   "bin": {

package/template/.agent/skills/llm-routing-quirks/SKILL.md

@@ -0,0 +1,41 @@
+---
+description: "Kinh nghiệm xương máu khi định tuyến LLM: 9Router (Gemini) vs Ollama (Bartowski/Reasoning)"
+skills: ["clean-code"]
+---
+
+# LLM Routing Quirks (Kinh Nghiệm Phẫu Thuật Não LLM)
+
+Tài liệu này lưu trữ những **chú ý sinh tử (quirks)** khi gọi các model LLM khác nhau trong kiến trúc Antigravity Orchestrator. Nó được đúc kết từ quá trình cày cuốc miệt mài vá lỗi của Quản Đốc AI và Sếp.
+
+Nếu bạn đang viết Agent hoặc Script gọi LLM, **BẮT BUỘC ĐỌC** để tránh hệ thống bị đơ, văng lỗi JSON hoặc model bị "ngu" đi.
+
+---
+
+## 1. 9Router & Gemini (Cloud Models - API tương thích OpenAI)
+
+**Mô hình áp dụng:** `ag/gemini-3-flash`, `ag/gemini-pro-1.5`, v.v.
+
+### Các Quy tắc Vàng:
+1. **JSON Format:** ĐƯỢC PHÉP (và nên) sử dụng `response_format: { type: 'json_object' }` để ép model trả về cục JSON chuẩn chỉ. Gemini xử lý JSON format tự nhiên rất tốt.
+2. **Stream Override (Lỗi SSE):** Mặc dù truyền `stream: false`, 9Router đôi khi BỊ LỖI và vẫn trả về luồng Server-Sent Events (SSE) (các dòng `data: {...}\n\ndata: [DONE]`). 
+   👉 **Cách Fix:** Code call API (`axios.post`) phải luôn chuẩn bị sẵn tinh thần parse cả 2 trường hợp: JSON Object bình thường VÀ Chuỗi SSE gộp lại. (Xem hàm `OrchestratorBrain.callAI`).
+3. **Timeout Threshold:** Bắt buộc đặt `timeout` cao (ví dụ: `120000ms` - 2 phút). Đừng set quá thấp (30s), vì proxy API Cloud thường xuyên bị trễ nhịp do routing.
+
+---
+
+## 2. Ollama & Bartowski (Local Reasoning Models - Chạy Offline)
+
+**Mô hình áp dụng:** `hf.co/bartowski/nvidia_Orchestrator-8B-GGUF:Q4_K_M`, `DeepSeek-R1`, các model có thẻ `<think>`.
+
+### Các Quy tắc Vàng (SINH TỬ):
+1. **🔥 TUYỆT ĐỐI KHÔNG DÙNG TÍNH NĂNG ÉP JSON:** KHÔNG BAO GIỜ truyền `format: "json"` vào request của Ollama đối với các Reasoning Models!
+   - **Vì sao?** Các reasoning models cần viết tư duy vào thẻ `<think>...</think>` trước khi ra kết quả. Việc ép JSON sẽ làm hệ thống của Ollama cắt gọt thẻ suy nghĩ của nó, khiến model bị "ngăn não", sinh ra ảo giác (hallucination), trả về rác (token rác) hoặc phá hỏng format JSON cuối cùng.
+2. **Xử lý Thẻ `<think>` Thủ Công:** Khi model trả về chuỗi text, ta phải chủ động dùng Regex để bóc mảng `<think>...</think>` ra rồi mới quăng phần còn lại vào `JSON.parse()`.
+   - Code mài giũa: `str.replace(/<think>[\s\S]*?<\/think>/g, '').trim()`
+3. **Mở Hộp Sọ (Context Window - `num_ctx`):** Mặc định Ollama cấp `num_ctx` rất bé (2048 token) để tiết kiệm VRAM. Với các Task Orchestration quăng cả lịch sử chat và code, **BẮT BUỘC** phải truyền `"options": { "num_ctx": 4096 }` (hoặc 8192) vào `axios.post`. Nếu không, Ollama sẽ ngắt đuôi JSON làm sập hệ thống.
+4. **Tên Model Mặc Định:** Chú ý khi tải model HuggingFace từ Ollama (ví dụ `ollama run hf.co/bartowski/...`), Ollama sẽ giữ NGHIÊM NGẶT toàn bộ đường dẫn làm `ID Model`. Luôn truyền full tên vào trường `model` (ví dụ `model: "hf.co/bartowski/nvidia_Orchestrator-8B-GGUF:Q4_K_M"`).
+
+---
+
+## 3. Khuyến nghị Tự Chữa Lành (Mini-Antigravity Check)
+Bất cứ khi nào gọi API nội bộ (để tự sửa mã) và nhận cảnh báo `SKIP Lỗi LLM` (tức 9Router bị câm), hệ thống không được gọi lại chính thằng sụp mạng, mà phải rẽ nhánh BẮN THẲNG LỆNH GỌI OLLAMA LOCALLY (tắt bypass Router) để bảo tồn mạng sống.

package/template/.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!