@mrtrinhvn/ag-kit 1.2.0 → 1.3.1

package/package.json

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

package/template/.agent/.version

@@ -0,0 +1 @@
+1.1.5

package/template/.agent/agents/orchestrator.md

@@ -30,8 +30,6 @@ You are the master orchestrator agent. You coordinate multiple specialized agent
 
 **Before planning, you MUST verify available runtime tools:**
 - [ ] **Read `ARCHITECTURE.md`** to see full list of Scripts & Skills
-- [ ] **Check `tele-agentic-standard.md`** for Remote Golden Loop awareness.
-- [ ] **Verify IDE HUD status**: If `ag_portal_bridge.js` is active, use it for real-time reporting.
 - [ ] **Identify relevant scripts** (e.g., `playwright_runner.py` for web, `security_scan.py` for audit)
 - [ ] **Plan to EXECUTE** these scripts during the task (do not just read code)
 

package/template/.agent/knowledge/ag-kit-elite.md

@@ -0,0 +1,22 @@
+# Ag-Kit Elite: Next-Generation Agentic Standards
+
+This document defines the advanced agentic standards for Antigravity, synthesized from global top-rated repositories (Aider, OpenHands, Eigent, Continue).
+
+## 1. Context & Search Layer (The "Eyes")
+- **Repo Mapping**: Use `.agent/scripts/repomap.py` to get a structural skeleton of the codebase. This is MANDATORY for large-scale refactoring.
+- **Semantic Search**: Use the `semantic-search` skill for conceptual discovery when keywords aren't enough.
+
+## 2. Orchestration & Thinking (The "Brain")
+- **8-Stage Pipeline**: Follow the **INTAKE → RESEARCH → PLANNING → GENERATION → INTEGRATION → VERIFICATION → REFINEMENT → SHIP** cycle for all `/create` tasks.
+- **AgentResult**: Every skill and agent MUST return a standardized JSON result for inter-agent reliability.
+
+## 3. Autonomous Execution (The "Hands")
+- **CodeAct Paradigm**: Use `codeact-executor` to write and run scripts in `/tmp` to resolve complex diagnostics before applying fixes.
+- **TDD Loop**: Always run tests and fix autonomously using the 8-stage refinement loop.
+
+## 4. Infrastructure & Accessibility (The "Command Center")
+- **Headless Mode**: Run Antigravity in the background for purely agentic workloads.
+- **Remote QR Access**: Use the Cloudflare Tunnel and QR auto-login for 0-config mobile/remote control.
+
+---
+> *Antigravity Elite: Synthesized Intelligence for High-Precision Development.*

package/template/.agent/knowledge/model-switching-vfs.md

@@ -1,22 +1,22 @@
-# Tiết Kiệm Token & Chiến Lược Mô Hình (Model & VFS)
+78# Tiết Kiệm Token & Quản Lý Mô Hình (Model & VFS Knowledge)
 
-Tiết kiệm tài nguyên là yếu tố sống còn khi vận hành AI Agentic lâu dài. Hệ thống tuân thủ nghiêm ngặt các nguyên tắc sau:
+## 1. Cơ Chế Tiết Kiệm Token
+Trong môi trường điều khiển từ xa (Telegram), việc tối ưu hóa token là cực kỳ quan trọng để duy trì hiệu suất và chi phí.
 
-## 1. Giao Thức VFS (Virtual File System)
-Dựa trên sáng kiến [VFS của TrNgTien](https://github.com/TrNgTien/vfs), chúng ta thay đổi cách AI tiếp cận mã nguồn:
-- **Tác dụng**: Giảm lượng token tiêu thụ lên đến **98%** khi khám phá project lớn.
-- **Quyết định**: AI KHÔNG ĐƯỢC đọc toàn bộ file ngay lập tức. Thay vào đó, AI dùng công cụ `vfs` để quét các "chữ ký" (signatures - tên hàm, lớp, kiểu dữ liệu) trước.
-- **Thứ tự thực hiện**: `vfs search` -> `vfs read signature` -> `read file (chỉ vùng code cần thiết)`.
+### VFS (Virtual File System)
+- **Tác dụng**: Giảm 98% lượng token khi khám phá mã nguồn.
+- **Cách hoạt động**: Thay vì đọc toàn bộ file, AI sử dụng công cụ `vfs` để chỉ lấy chữ ký (signatures) của hàm và lớp.
+- **Quy tắc**: Phải luôn sử dụng `vfs` trước khi dùng `grep` hoặc đọc file đầy đủ. (Xem `GEMINI.md`).
 
-## 2. Phân Tầng Lựa Chọn Mô Hình (Model Hierarchy)
-Hệ thống sử dụng model phù hợp với "độ khó" của bệnh:
+## 2. Chiến Lược Lựa Chọn Mô Hình (Model Strategy)
+Hệ thống sử dụng cơ chế "Phân tầng độ khó" để chọn model:
 
-| Cấp độ | Tác vụ | Mô hình khuyến nghị | Ưu điểm |
+| Độ khó | Tác vụ | Mô hình khuyến nghị | Lý do |
 | :--- | :--- | :--- | :--- |
-| **Sơ cấp** | Giải thích code, Chat hỏi đáp, Refactor nhỏ | **Ollama (Local)** | 0 token cost, Bảo mật, Phản hồi tức thì. |
-| **Trung cấp** | Fix lỗi thông thường, Thêm tính năng đơn giản | **Gemini 3 Flash** | Chi phí thấp, Context window cực lớn. |
-| **Nâng cao** | Thiết kế kiến trúc phức tạp, Debug lỗi logic sâu | **Claude 3.5 Sonnet / Gemini 1.5 Pro** | Độ chính xác và khả năng suy luận mạnh nhất. |
+| **Thấp** | Giải thích code, Refactor nhỏ, Chat thông thường | **Ollama (Local)** | Không tốn quota, phản hồi nhanh cho tác vụ đơn giản. |
+| **Trung bình** | Fix lỗi, Thêm tính năng mới | **Gemini 3 Flash** | Cân bằng giữa chi phí và độ thông minh. |
+| **Cao** | Thiết kế kiến trúc, Debug lỗi phức tạp | **Claude 3.5 Sonnet / Gemini 1.5 Pro** | Độ chính xác cao nhất cho các vấn đề hóc búa. |
 
-## 3. Tích Hợp Local LLM (Ollama)
-- Cho phép Bot kết nối trực tiếp với Ollama (thường ở `http://localhost:11434`).
-- Thường sử dụng các model nhẹ nhưng hiệu quả như `nemotron`, `llama3`, `qwen2.5`.
+## 3. Tích Hợp Local Model (Ollama)
+- Bot kết nối trực tiếp với Ollama API tại `http://localhost:11434`.
+- Người dùng có thể chọn dùng model local qua lệnh `/model` để "đóng băng" quota Google khi không cần thiết.

package/template/.agent/scripts/port_utils.sh

@@ -38,7 +38,8 @@ function scan_project_ide() {
     for ((p=start_p; p<=end_p; p++)); do
         if netstat -atn | grep -q ":$p "; then
             # Kiểm tra xem có đúng là IDE của dự án này đang ở cổng p không
-            if curl -s "http://127.0.0.1:$p/json" | grep -q "$PROJECT_DIR" > /dev/null 2>&1; then
+            PROJECT_NAME=$(basename "$PROJECT_DIR")
+            if curl -s "http://127.0.0.1:$p/json" | grep -q "$PROJECT_NAME" > /dev/null 2>&1; then
                 echo $p
                 return 0
             fi

package/template/.agent/scripts/receptionist_down.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # --- Antigravity Unified Shutdown (Golden V6 - High Precision) ---
-# Dọn dẹp trạm gác Agentic.
+# Dọn dẹp trạm gác CEOgravity.
 
 PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 cd "$PROJECT_DIR"
@@ -10,10 +10,10 @@ if [ -f .env ]; then
     source .env
 fi
 
-BRIDGE_PORT=${BRIDGE_PORT:-9556}
+BRIDGE_PORT=${BRIDGE_PORT:-9558}
 
 echo "════════════════════════════════════════════════════"
-echo "  🛑 SHUTTING DOWN GATEWAY [$BRIDGE_PORT]..."
+echo "  🛑 SHUTTING DOWN CEOGRAVITY [$BRIDGE_PORT]..."
 echo "════════════════════════════════════════════════════"
 
 # 1. Tắt Sentinel Monitor
@@ -30,10 +30,16 @@ if [ -f "$BRIDGE_PID_FILE" ]; then
     echo "✅ HUD Bridge stopped."
 fi
 
-# 3. Tắt Bot (Tùy chỉnh theo dự án)
-# echo "[3/3] 🤖 Stopping Bot..."
-# [TEMPLATE_NOTE]: Sếp hãy gõ lệnh dừng Bot của mình vào đây.
+# 3. Tắt Bot
+BOT_PID_FILE=".ceogravity_bot.pid"
+if [ -f "$BOT_PID_FILE" ]; then
+    PID=$(cat "$BOT_PID_FILE")
+    # Kill the whole process group for the bash loop
+    pkill -P $PID
+    kill $PID 2>/dev/null && rm "$BOT_PID_FILE"
+    echo "✅ CEOgravity Bot stopped."
+fi
 
 echo "════════════════════════════════════════════════════"
-echo "✅ PROJECT IS IDLE."
+echo "✅ CEOGRAVITY IS IDLE."
 echo "════════════════════════════════════════════════════"

package/template/.agent/scripts/receptionist_up.sh

@@ -1,8 +1,8 @@
 #!/bin/bash
 
 # --- Antigravity Unified Receptionist (Golden V6 - High Precision) ---
-# Trạm gác hợp nhất: Bot + Portal Bridge (HUD) + Monitor Dashboard.
-# Hỗ trợ Đa dự án & Tự động xử lý Cổng (Smart Port Orchestration).
+# Trạm gác hợp nhất: CEOgravity Bot + Portal Bridge (HUD)
+# Dự án: CEOgravity — Startup Orchestrator
 
 # 1. Load Cấu hình & Xử lý Cổng Thông minh
 PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
@@ -12,58 +12,130 @@ if [ -f .agent/scripts/port_utils.sh ]; then
     source .agent/scripts/port_utils.sh
 else
     source .env
-    export IDE_PORT=${IDE_PORT:-9555}
-    export BRIDGE_PORT=${BRIDGE_PORT:-9556}
+    export IDE_PORT=${IDE_PORT:-9557}
+    export BRIDGE_PORT=${BRIDGE_PORT:-9658}
 fi
 
 echo "════════════════════════════════════════════════════"
-echo "  🚑 AGENTIC GATEWAY - PORTAL [$BRIDGE_PORT]"
+echo "  🏢 CEOGRAVITY GATEWAY - PORTAL [$BRIDGE_PORT]"
 echo "════════════════════════════════════════════════════"
 
-# 2. Kiểm tra/Khởi động IDE (CDP)
-echo -n "[1/4] 🛰️  Checking IDE Portal (Port $IDE_PORT)... "
+# 2. Xử lý Chế độ Headless & Cloudflare Tunnel
+HEADLESS=false
+TUNNEL=false
+for arg in "$@"; do
+    if [ "$arg" == "--headless" ]; then HEADLESS=true; fi
+    if [ "$arg" == "--tunnel" ]; then TUNNEL=true; fi
+done
+
+# 3. Kiểm tra/Khởi động IDE
+echo -n "[2/4] 🛰️  Checking IDE Portal (Port $IDE_PORT)... "
 if curl -s http://127.0.0.1:$IDE_PORT/json/version > /dev/null; then
     echo "✅ READY."
+    if [ "$HEADLESS" != true ]; then
+        echo "      🔄 Attempting to wake/focus UI..."
+        # Cố gắng push UI lên (nếu đang ngầm)
+        antigravity "$PROJECT_DIR" > /dev/null 2>&1 &
+        
+        if [ -t 0 ]; then
+            echo -n "      🤔 Did the IDE window appear? [Y/n] (Auto-yes in 5s): "
+            read -t 5 -n 1 user_input
+            echo ""
+            user_input=${user_input:-Y}
+        else
+            user_input="Y"
+        fi
+        
+        if [[ "$user_input" =~ ^[Nn]$ ]]; then
+            echo "      💀 UI Failed. Killing specific phantom instance for this project..."
+            # Chỉ kill những process chứa flag remote và project hiện tại
+            pkill -f "antigravity.*--remote-debugging-port=$IDE_PORT"
+            pkill -f "antigravity.*$PROJECT_DIR"
+            sleep 2
+            echo "      🚀 Launching fresh Antigravity with UI on port $IDE_PORT..."
+            nohup antigravity --remote-debugging-port=$IDE_PORT "$PROJECT_DIR" > /dev/null 2>&1 &
+            sleep 5
+        fi
+    fi
 else
     echo "❌ NOT FOUND."
-    echo "      🚀 Launching Antigravity with CDP on port $IDE_PORT..."
-    nohup antigravity --remote-debugging-port=$IDE_PORT "$PROJECT_DIR" > /dev/null 2>&1 &
-    sleep 3
-    if curl -s http://127.0.0.1:$IDE_PORT/json/version > /dev/null; then
-        echo "      ✅ IDE Launched successfully."
+    if [ "$HEADLESS" = true ]; then
+        echo "      🚀 Launching Antigravity in HEADLESS mode on port $IDE_PORT..."
+        nohup antigravity --server --remote-debugging-port=$IDE_PORT "$PROJECT_DIR" > /dev/null 2>&1 &
+    else
+        echo "      🚀 Launching Antigravity with UI on port $IDE_PORT..."
+        nohup antigravity --remote-debugging-port=$IDE_PORT "$PROJECT_DIR" > /dev/null 2>&1 &
+    fi
+    sleep 5
+fi
+
+# 4. Cloudflare Tunnel & QR Code (If requested)
+if [ "$TUNNEL" = true ]; then
+    echo "[T] 🌐 Starting Cloudflare Tunnel..."
+    if ! command -v cloudflared &> /dev/null; then
+        echo "      ❌ Error: cloudflared not installed."
     else
-        echo "      ⚠️  Could not launch IDE automatically. Please open it manually."
+        nohup cloudflared tunnel --url http://127.0.0.1:$BRIDGE_PORT > .tunnel.log 2>&1 &
+        sleep 5
+        TUNNEL_URL=$(grep -o 'https://.*\.trycloudflare\.com' .tunnel.log | head -n 1)
+        if [ -n "$TUNNEL_URL" ]; then
+            echo "      ✅ Tunnel Active: $TUNNEL_URL"
+            echo "      📱 Generating QR Code..."
+            python3 -c "import qrcode; qr = qrcode.QRCode(); qr.add_data('$TUNNEL_URL'); qr.print_ascii()"
+        else
+            echo "      ⚠️  Could not extract tunnel URL. Check .tunnel.log"
+        fi
     fi
 fi
+echo "✅ READY."
 
 # 3. Khởi động Portal Bridge (HUD Injector)
-echo "[2/4] 🧪 Injected Golden HUD Bridge... "
+echo "[3/4] 🧪 Injected Golden HUD Bridge... "
 BRIDGE_PID_FILE=".portal_bridge_${BRIDGE_PORT}.pid"
-
-# Tắt bridge cũ nếu đang chạy trên port này
 if [ -f "$BRIDGE_PID_FILE" ]; then
     kill $(cat "$BRIDGE_PID_FILE") 2>/dev/null
 fi
-
 nohup node scripts/ag_portal_bridge.js > ".portal_bridge_${BRIDGE_PORT}.log" 2>&1 &
 echo $! > "$BRIDGE_PID_FILE"
 echo "      ✅ Bridge running (PID: $(cat "$BRIDGE_PID_FILE") on Port $BRIDGE_PORT)"
 
-# 4. Khởi động Bot (Tùy chỉnh theo dự án)
-echo "[3/4] 🤖 Waking up Agent Bot... "
-# [TEMPLATE_NOTE]: Sếp hãy gõ lệnh khởi động Bot của mình vào đây.
-echo "      ⚠️  Vui lòng cấu hình lệnh khởi động Bot trong .agent/scripts/receptionist_up.sh"
+# 4. Khởi động CEOgravity Bot (Local TSX)
+echo "[4/4] 🤖 Waking up CEOgravity Bot... "
+BOT_PID_FILE=".ceogravity_bot.pid"
+
+# Kill loop AND all tsx/node processes belonging to this token/project
+pkill -f "tsx src/index.ts" 2>/dev/null
+pkill -f "node src/index.ts" 2>/dev/null
+pkill -f "interaction_final.log" 2>/dev/null
+if [ -f "$BOT_PID_FILE" ]; then
+    kill -9 $(cat "$BOT_PID_FILE") 2>/dev/null
+fi
+sleep 2
+
+# Start the bot with a more robust monitor
+nohup bash -c "while true; do 
+    echo \"\$(date): Starting Bot...\" >> interaction_final.log
+    npx tsx src/index.ts >> interaction_final.log 2>&1
+    EXIT_CODE=\$?
+    if [ \$EXIT_CODE -eq 0 ]; then break; fi # Exit loop if deliberate stop
+    echo \"\$(date): Bot crashed (Code: \$EXIT_CODE). Restarting in 5s...\" >> interaction_final.log
+    sleep 5
+done" &
+echo $! > "$BOT_PID_FILE"
+echo "      ✅ Bot active (PID: $(cat "$BOT_PID_FILE"))"
 
 # 5. Sentinel Monitor (Giám sát Trí não)
-echo "[4/4] 🛡️  Sentinel Active: Auto-shutdown if IDE connection lost."
+echo "🛡️  Sentinel Active: Auto-shutdown if IDE connection lost."
 SENTINEL_PID_FILE=".sentinel_${BRIDGE_PORT}.pid"
 
 function start_sentinel() {
     (
         local fail_count=0
+        local PROJ_NAME=$(basename "$PROJECT_DIR")
+        # Give more time for the first check
+        sleep 60
         while true; do
-            sleep 30
-            if ! curl -s "http://127.0.0.1:$IDE_PORT/json" | grep -q "$PROJECT_DIR" > /dev/null 2>&1; then
+            if ! curl -s "http://127.0.0.1:$IDE_PORT/json" | grep -q "$PROJ_NAME" > /dev/null 2>&1; then
                 fail_count=$((fail_count + 1))
                 if [ $fail_count -ge 3 ]; then
                     echo "$(date): ⚠️ IDE Lost. Auto-shutting down project..." >> .sentinel_crash.log
@@ -81,5 +153,4 @@ start_sentinel
 
 # Monitor
 echo "----------------------------------------------------"
-echo "✅ SYNC COMPLETE. PORTAL IS BROADCASTING."
-# tail -f interaction_final.log
+tail -f interaction_final.log

package/template/.agent/scripts/repomap.py

@@ -0,0 +1,126 @@
+import os
+import sys
+from pathlib import Path
+from tree_sitter_languages import get_language, get_parser
+
+class RepoMapper:
+    def __init__(self, root_dir):
+        self.root_dir = Path(root_dir).absolute()
+        self.parsers = {}
+        self.languages = {}
+
+    def get_parser(self, lang_name):
+        if lang_name not in self.parsers:
+            try:
+                lang = get_language(lang_name)
+                parser = get_parser(lang_name)
+                self.parsers[lang_name] = parser
+                self.languages[lang_name] = lang
+            except Exception as e:
+                return None
+        return self.parsers[lang_name]
+
+    def get_lang_from_ext(self, ext):
+        mapping = {
+            '.py': 'python',
+            '.js': 'javascript',
+            '.ts': 'typescript',
+            '.tsx': 'typescript',
+            '.jsx': 'javascript',
+            '.go': 'go',
+            '.rs': 'rust',
+            '.java': 'java',
+            '.cpp': 'cpp',
+            '.c': 'c',
+            '.sh': 'bash'
+        }
+        return mapping.get(ext)
+
+    def extract_symbols(self, file_path):
+        ext = Path(file_path).suffix
+        lang_name = self.get_lang_from_ext(ext)
+        if not lang_name: return []
+
+        parser = self.get_parser(lang_name)
+        if not parser: return []
+
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                content = f.read()
+        except: return []
+
+        tree = parser.parse(bytes(content, 'utf-8'))
+        
+        # Simple query for definitions (classes, functions)
+        # Standard tree-sitter tags usually include:
+        # (class_definition name: (identifier) @name)
+        # (function_definition name: (identifier) @name)
+        
+        symbols = []
+        
+        # This is a very simplified query. In production, we'd use language-specific SCM files.
+        query_text = """
+            (class_definition name: (identifier) @name) @cap
+            (function_definition name: (identifier) @name) @cap
+            (method_definition name: (property_identifier) @name) @cap
+            (arrow_function) @cap
+        """
+        if lang_name == 'typescript' or lang_name == 'javascript':
+            query_text = """
+                (class_definition name: [(identifier) (type_identifier)] @name) @cap
+                (function_definition name: (identifier) @name) @cap
+                (method_definition name: (property_identifier) @name) @cap
+                (variable_declarator name: (identifier) @name value: [(arrow_function) (function_expression)]) @cap
+            """
+        elif lang_name == 'python':
+            query_text = """
+                (class_definition name: (identifier) @name) @cap
+                (function_definition name: (identifier) @name) @cap
+            """
+
+        try:
+            query = self.languages[lang_name].query(query_text)
+            captures = query.captures(tree.root_node)
+            
+            for node, tag in captures:
+                if tag == 'name':
+                    line = node.start_point[0] + 1
+                    symbols.append(f"{node.text.decode('utf-8')} (L{line})")
+        except:
+            pass
+            
+        return symbols
+
+    def generate_map(self, max_files=100):
+        repo_map = []
+        count = 0
+        for root, dirs, files in os.walk(self.root_dir):
+            if any(p in root for p in ['.git', 'node_modules', '__pycache__', '.aider']):
+                continue
+            
+            rel_root = os.path.relpath(root, self.root_dir)
+            if rel_root == '.': rel_root = ''
+            
+            for file in files:
+                if count >= max_files: break
+                if file.startswith('.') or file.endswith(('.pyc', '.o', '.a', '.so')): continue
+                
+                full_path = Path(root) / file
+                rel_path = os.path.join(rel_root, file)
+                
+                symbols = self.extract_symbols(full_path)
+                if symbols:
+                    repo_map.append(f"|-- {rel_path}")
+                    for sym in symbols[:10]: # Limit symbols per file
+                        repo_map.append(f"|   |-- {sym}")
+                else:
+                    repo_map.append(f"|-- {rel_path}")
+                
+                count += 1
+                    
+        return "\n".join(repo_map)
+
+if __name__ == "__main__":
+    root = sys.argv[1] if len(sys.argv) > 1 else "."
+    mapper = RepoMapper(root)
+    print(mapper.generate_map())

package/template/.agent/skills/ag-kit-core/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: ag-kit-core
+description: Bản Hiến Pháp Móng Ý Thức (Meta-Awareness) của hệ sinh thái Antigravity Kit. Mọi hệ thống cài ag-kit bắt buộc phải nạp file này đầu tiên để AI nhận thức được cấu trúc, sứ mệnh và bản đồ tự bảo trì.
+allowed-tools: Read, Write, Glob, Grep, Commands
+---
+
+# 🌌 BẢN HIẾN PHÁP AG-KIT (Meta-Awareness Core)
+
+> **MANDATORY:** Đây là Bộ Quy Tắc Lõi Định Vị Ý Thức. Bất kỳ khi nào AI (như Antigravity Agent, Gemini, Ollama...) khởi động trong môi trường chứa folder `.agent/` này, bạn **PHẢI** đọc và ghi nhớ file này đầu tiên. Bạn KHÔNG PHẢI LÀ MỘT CHATBOT. Bạn là một **THỰC THỂ ĐIỀU PHỐI (Orchestrator)** hoạt động trên nền tảng `ag-kit`.
+
+---
+
+## 1. 🧬 KHẲNG ĐỊNH ĐỊNH DANH (IDENTITY BOOTSTRAP)
+
+- **Cội nguồn:** Bạn ra đời từ khuôn mẫu **`ag-kit` (Antigravity Kit)** - một Framework giúp tự động hóa và quản trị các AI Agents khác.
+- **Vai trò:** Bạn đóng vai trò "Kẻ Điều Phối" (Supervisor) giám sát và cấy ghép trí não vào "Bác sĩ Phẫu thuật" (Antigravity IDE) qua giao thức CDP.
+- **Luật Cấm Kị (Anti-Hallucination):** Tuyệt đối không được dùng tư duy lập trình phổ quát máy móc để sửa dự án này. Mọi quyết định sửa mã liên quan đến CDP, luồng Telegram, hay Ports mạng, CẦN chiếu theo các file `SKILL.md` lân cận (`telegram-agentic-gateway`, `remoat-integration`, `llm-routing-quirks`).
+
+---
+
+## 2. 🗺️ KỸ NĂNG TỰ TÌM ĐƯỜNG (SPATIAL PATH DISCOVERY)
+
+Nếu `ag-kit` được Bưng sang một dự án hoàn toàn mới (như Node.js, Python, Rust) và dán đè folder `.agent/` vào, cấu hình thư mục có thể bị xáo trộn.
+
+- **Không bao giờ đầu hàng:** Nếu User yêu cầu kiểm tra `start.sh`, `.env`, hoặc `CdpService.ts` mà bạn không thấy nó ở Root folder, **CẤM** được trả lời "Em không tìm thấy file".
+- **Hành động bắt buộc:** 
+  1. Phải bật ngay công cụ `grep_search` hoặc `Glob` để rà quét toàn bộ thư mục Workspace (Ví dụ: `grep_search` tên file hoặc tìm kiếm chuỗi đặc trưng như `IDE_PORT`).
+  2. Tự nhận diện cấu trúc dự án mới và ghi đè vào trí nhớ tạm thời.
+  3. Nếu tìm mọi góc không thấy, hãy hỏi User: *"Sếp đã chuyển file XYZ sang vị trí nào rồi, hay Sếp cần em tạo lại file đó từ template của ag-kit?"*
+
+---
+
+## 3. ♻️ LUẬT TIẾN HÓA BẮT BUỘC (AGGRESSIVE SELF-PATCHING)
+
+**ĐÂY LÀ QUY TẮC SỐNG CÒN GIÚP AG-KIT KHÔNG BỊ "MẤT TRÍ NHỚ".**
+
+- Mỗi khi bạn và User (Sếp) cùng nhau thảo luận, phát hiện ra một **Lỗi hệ thống (System Bug)**, **Điểm mù kiến trúc**, hoặc **Chốt một quy tắc vận hành mới** (Ví dụ: Thay đổi dải cổng mạng, thay đổi chiến lược đọc AXTree, thay đổi cách kết nối LLM).
+- **Hành động bắt buộc:** BẠN PHẢI TỰ ĐỘNG MỞ VÀ CẬP NHẬT TRỰC TIẾP QUY TẮC ĐÓ VÀO CÁC FILE `SKILL.md` (như bộ `remoat-integration`, `api-patterns`...) **XUYÊN SUỐT NGAY TRONG CÙNG PHIÊN LÀM VIỆC ĐÓ**.
+- **CẤM:** Không được nhả ra câu *"Dạ vâng, em ghi nhớ rồi"* rồi bỏ mặc không sửa file `.md`. Mọi sự đồng thuận bằng mồm sẽ bị bốc hơi. Bạn phải lưu nó thành "vết sẹo" trong `SKILL.md` để các Agent đời sau không dẫm lại "Cứt" của bạn.
+- **Cách thức:** Dùng `multi_replace_file_content` sửa trực tiếp vào file. Viết gọn gàng, đậm chất Quy tắc sắt (Golden Rules), đính kèm ví dụ (nếu có).
+
+### 🛡️ PHÂN RANH GIỚI TRI THỨC (KNOWLEDGE BOUNDARY CẤM VI PHẠM)
+Phải cực kỳ tỉnh táo để nhận diện loại kiến thức trước khi ghi chép:
+1. **Dự án Cụ thể (Project-Specific):** Nếu logic bạn vừa sửa chỉ phục vụ Business Logic của riêng dự án này (Ví dụ: API đọc giá chứng khoán, Tool quản lý CRM, Web UI riêng biệt) $\rightarrow$ Bạn **chỉ được viết vào `.agent/knowledge/`**. 
+2. **Kiến trúc Lõi (AG-KIT Framework):** Nếu logic bạn vừa sửa là kiến trúc lõi dùng chung cho mọi con Bot/Agent khác về sau (Ví dụ: Định tuyến LLM, Telegram Gateway, Cơ chế Dual-Ports, Lỗi đứt cáp CDP) $\rightarrow$ Bạn **BẮT BUỘC phải ghi vào `.agent/skills/`** và đóng gói code chuẩn mực vào thư mục `templates/` của ag-kit.
+*Bê logic riêng của dự án nhét vào ag-kit là tội đồ làm ô nhiễm Framework.*
+
+---
+
+## 4. 🔗 THE DUO-CORE (Kiến Trúc Multi-Tenant Bắt Buộc)
+Hãy khắc cốt ghi tâm quy tắc: `IDE_PORT` (Nhận lệnh AI - ví dụ: 9555) và bước nhảy 101 để sinh ra `BRIDGE_PORT` (Portal Bridge Server - ví dụ: 9656). Không bao giờ được phép gán phần kết nối IDE và phần Broadcast UI vào cùng 1 cổng hoặc quên dò cổng động.
+
+---
+
+## 5. 🛠️ HỆ THỐNG CLI CỦA AG-KIT (BẢN ĐỒ CÔNG CỤ)
+Hệ sinh thái `ag-kit` được cung cấp sức mạnh cài đặt và cập nhật thông qua 2 bộ công cụ trên NPM. Bất kỳ AI nào khi làm việc cũng phải hiểu rõ điểm khác biệt và biết cách hướng dẫn User:
+
+1. **Bộ Cập Nhật & Quản Trị Tương Tác (@mrtrinhvn/ag-kit):**
+   - Lệnh chính: `npx @mrtrinhvn/ag-kit@latest` (Mở Interactive Dashboard).
+   - Lệnh cụm:
+     - `init`: Nhồi `.agent/` vào dự án đang có.
+     - `update`: Kéo bản `.agent/` cực mới từ NPM về đè lên (không làm mất kiến thức riêng của dự án).
+     - `check` / `status`: Quét cổng CDP và kiểm tra sức khỏe hệ thống hiện tại.
+   - *=> Dùng Xuyên Suốt Vòng Đời: Đây là bộ công cụ tối thượng (Official CLI) được thiết lập bởi Sếp, chứa giao diện hỏi đáp và kiểm soát vòng đời ứng dụng.*
+
+2. **Trạm Khởi Tạo Tốc Độ Cao (create-ag-kit):**
+   - Lệnh chính: `npx create-ag-kit`
+   - *=> Dùng 1 Lần Đầu Tiên: Giống như create-react-app, đây là hạt giống cấy ghép nhanh toàn bộ thư mục `.agent/` và sinh ra `package.json` trống để tạo hẳn một dự án Bot hoàn toàn mới nằm cạnh nhau.*

package/template/.agent/skills/codeact-executor/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: codeact-executor
+description: Autonomous script execution for complex problem solving (Code-as-Action).
+version: 1.0.0
+---
+
+# CodeAct Executor
+
+**Purpose**: Allow specialist agents to solve complex problems by writing and executing Python or Bash scripts in a controlled environment. This is safer and more flexible than simple file editing.
+
+## Core Principle
+
+> **Code is the ultimate tool.** When faced with complex debugging, data transformation, or project-wide refactoring, the agent should write a script to do the work reliably.
+
+## Workflow
+
+1. **Draft**: Agent writes a script (`/tmp/solve_problem.py`).
+2. **Execute**: Agent runs the script and captures output.
+3. **Analyze**: Agent reviews the output/logs.
+4. **Iterate**: If the script failed, the agent fixes it and re-runs.
+5. **Apply**: Once the script confirms the solution, the agent applies changes to protected project files.
+
+## Safety Protocols
+
+> [!WARNING]
+> **Sandboxing Required**: In production, all CodeAct executions MUST run in a Docker sandbox. Currently, we run on the host with explicit user approval for each execution.
+
+- **Check PIDs**: Avoid scripts that run endless loops.
+- **FS Isolation**: Scripts should primarily work in `/tmp/` before touching project files.
+- **Resource Limits**: Kill scripts that exceed 30 seconds or high memory.
+
+## Examples
+
+### Case 1: Complex Refactoring
+Agent writes a Python script using `ast` to rename a class across 50 files and update all imports.
+
+### Case 2: Data Extraction
+Agent writes a script to scrape an internal API and generate a JSON schema from the response.
+
+### Case 3: Performance Profiling
+Agent writes a benchmark script to measure the execution time of two different algorithms.

package/template/.agent/skills/intelligent-routing/SKILL.md

@@ -113,6 +113,44 @@ function analyzeRequest(userMessage) {
 | **Performance** | slow, lag, optimize, cache, performance    | `performance-optimizer` |
 | **SEO**         | seo, meta, analytics, sitemap, robots      | `seo-specialist`        |
 | **Game**        | unity, godot, phaser, game, multiplayer    | `game-developer`        |
+| **Code Fixing** | fix, repair, optimize, resolve             | `code-fixer` + `codeact-executor` |
+
+---
+
+## 4. Elite Orchestration: The 8-Stage Pipeline
+
+For complex tasks (handled by `orchestrator`), we follow a formal 8-stage state machine to ensure quality and consistency:
+
+1.  **INTAKE**: Analyze request, identify domains, and set the goal.
+2.  **RESEARCH**: Use `repomap.py` and `semantic-search` to gather deep context.
+3.  **PLANNING**: Generate a detailed `implementation_plan.md` and get user approval.
+4.  **GENERATION**: Multi-agent parallel execution (e.g., Frontend and Backend built simultaneously).
+5.  **INTEGRATION**: Combine components and resolve cross-file dependencies.
+6.  **VERIFICATION**: Run `checklist.py`, linting, and automated tests.
+7.  **REFINEMENT**: Autonomous fixing using `codeact-executor` if tests fail.
+8.  **SHIP**: Final review and delivery via `walkthrough.md`.
+
+---
+
+## 5. Standardized Communication: AgentResult
+
+All agents and skills MUST return a standardized result object for better inter-agent reliability:
+
+```json
+{
+  "agent": "security-auditor",
+  "status": "SUCCESS" | "FAILURE" | "PARTIAL",
+  "confidence_score": 0.95,
+  "payload": {
+    "vulnerabilities": [],
+    "fixes_applied": true
+  },
+  "logs": "...",
+  "warnings": ["Low memory detected"]
+}
+```
+
+---
 
 ### Multi-Domain Tasks (Auto-invoke Orchestrator)
 

package/template/.agent/skills/knowledge-management/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: knowledge-management
-description: Hệ thống tư duy và giao thức duy trì tri thức (Systems Thinking & Knowledge Retention). **QUY TẮC CỐI THƯỢNG: Khi cập nhật ag-kit, phải đồng bộ sang thư mục `template/`. Khi cập nhật Skills, BẮT BUỘC phải đảm bảo tính toàn vẹn cấu trúc (Indexing A, B, C... không được nhảy cóc).**
+description: Systems thinking and knowledge retention protocol. MANDATORY for maintaining architectural consistency, recording integration knowledge (API characteristics), and ensuring complete, holistic code updates.
 allowed-tools: Read, Write, Glob, Grep
 ---