@heyai-rules/pilo-masterkit 1.2.2 → 2.1.0

package/.agent/mcp-configs/mcp-servers.json

@@ -0,0 +1,181 @@
+{
+  "mcpServers": {
+    "jira": {
+      "command": "uvx",
+      "args": ["mcp-atlassian==0.21.0"],
+      "env": {
+        "JIRA_URL": "YOUR_JIRA_URL_HERE",
+        "JIRA_EMAIL": "YOUR_JIRA_EMAIL_HERE",
+        "JIRA_API_TOKEN": "YOUR_JIRA_API_TOKEN_HERE"
+      },
+      "description": "Jira issue tracking — search, create, update, comment, transition issues"
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT_HERE"
+      },
+      "description": "GitHub operations - PRs, issues, repos"
+    },
+    "firecrawl": {
+      "command": "npx",
+      "args": ["-y", "firecrawl-mcp"],
+      "env": {
+        "FIRECRAWL_API_KEY": "YOUR_FIRECRAWL_KEY_HERE"
+      },
+      "description": "Web scraping and crawling"
+    },
+    "supabase": {
+      "command": "npx",
+      "args": ["-y", "@supabase/mcp-server-supabase@latest", "--project-ref=YOUR_PROJECT_REF"],
+      "description": "Supabase database operations"
+    },
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"],
+      "description": "Persistent memory across sessions"
+    },
+    "omega-memory": {
+      "command": "uvx",
+      "args": ["omega-memory", "serve"],
+      "description": "Persistent agent memory with semantic search, multi-agent coordination, and knowledge graphs — run via uvx (richer than the basic memory store)"
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+      "description": "Chain-of-thought reasoning"
+    },
+    "vercel": {
+      "type": "http",
+      "url": "https://mcp.vercel.com",
+      "description": "Vercel deployments and projects"
+    },
+    "railway": {
+      "command": "npx",
+      "args": ["-y", "@railway/mcp-server"],
+      "description": "Railway deployments"
+    },
+    "cloudflare-docs": {
+      "type": "http",
+      "url": "https://docs.mcp.cloudflare.com/mcp",
+      "description": "Cloudflare documentation search"
+    },
+    "cloudflare-workers-builds": {
+      "type": "http",
+      "url": "https://builds.mcp.cloudflare.com/mcp",
+      "description": "Cloudflare Workers builds"
+    },
+    "cloudflare-workers-bindings": {
+      "type": "http",
+      "url": "https://bindings.mcp.cloudflare.com/mcp",
+      "description": "Cloudflare Workers bindings"
+    },
+    "cloudflare-observability": {
+      "type": "http",
+      "url": "https://observability.mcp.cloudflare.com/mcp",
+      "description": "Cloudflare observability/logs"
+    },
+    "clickhouse": {
+      "type": "http",
+      "url": "https://mcp.clickhouse.cloud/mcp",
+      "description": "ClickHouse analytics queries"
+    },
+    "exa-web-search": {
+      "command": "npx",
+      "args": ["-y", "exa-mcp-server"],
+      "env": {
+        "EXA_API_KEY": "YOUR_EXA_API_KEY_HERE"
+      },
+      "description": "Web search, research, and data ingestion via Exa API — prefer task-scoped use for broader research after GitHub search and primary docs"
+    },
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"],
+      "description": "Live documentation lookup — use with /docs command and documentation-lookup skill (resolve-library-id, query-docs)."
+    },
+    "magic": {
+      "command": "npx",
+      "args": ["-y", "@magicuidesign/mcp@latest"],
+      "description": "Magic UI components"
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/projects"],
+      "description": "Filesystem operations (set your path)"
+    },
+    "insaits": {
+      "command": "python3",
+      "args": ["-m", "insa_its.mcp_server"],
+      "description": "AI-to-AI security monitoring — anomaly detection, credential exposure, hallucination checks, forensic tracing. 23 anomaly types, OWASP MCP Top 10 coverage. 100% local. Install: pip install insa-its"
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp", "--browser", "chrome"],
+      "description": "Browser automation and testing via Playwright"
+    },
+    "fal-ai": {
+      "command": "npx",
+      "args": ["-y", "fal-ai-mcp-server"],
+      "env": {
+        "FAL_KEY": "YOUR_FAL_KEY_HERE"
+      },
+      "description": "AI image/video/audio generation via fal.ai models"
+    },
+    "browserbase": {
+      "command": "npx",
+      "args": ["-y", "@browserbasehq/mcp-server-browserbase"],
+      "env": {
+        "BROWSERBASE_API_KEY": "YOUR_BROWSERBASE_KEY_HERE"
+      },
+      "description": "Cloud browser sessions via Browserbase"
+    },
+    "browser-use": {
+      "type": "http",
+      "url": "https://api.browser-use.com/mcp",
+      "headers": {
+        "x-browser-use-api-key": "YOUR_BROWSER_USE_KEY_HERE"
+      },
+      "description": "AI browser agent for web tasks"
+    },
+    "devfleet": {
+      "type": "http",
+      "url": "http://localhost:18801/mcp",
+      "description": "Multi-agent orchestration — dispatch parallel Claude Code agents in isolated worktrees. Plan projects, auto-chain missions, read structured reports. Repo: https://github.com/LEC-AI/claude-devfleet"
+    },
+    "token-optimizer": {
+      "command": "npx",
+      "args": ["-y", "token-optimizer-mcp"],
+      "description": "Token optimization for 95%+ context reduction via content deduplication and compression"
+    },
+    "laraplugins": {
+      "type": "http",
+      "url": "https://laraplugins.io/mcp/plugins",
+      "description": "Laravel plugin discovery — search packages by keyword, health score, Laravel/PHP version compatibility. Use with laravel-plugin-discovery skill."
+    },
+    "confluence": {
+      "command": "npx",
+      "args": ["-y", "confluence-mcp-server"],
+      "env": {
+        "CONFLUENCE_BASE_URL": "YOUR_CONFLUENCE_URL_HERE",
+        "CONFLUENCE_EMAIL": "YOUR_EMAIL_HERE",
+        "CONFLUENCE_API_TOKEN": "YOUR_CONFLUENCE_TOKEN_HERE"
+      },
+      "description": "Confluence Cloud integration — search pages, retrieve content, explore spaces"
+    },
+    "evalview": {
+      "command": "python3",
+      "args": ["-m", "evalview", "mcp", "serve"],
+      "env": {
+        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE"
+      },
+      "description": "AI agent regression testing — snapshot behavior, detect regressions in tool calls and output quality. 8 tools: create_test, run_snapshot, run_check, list_tests, validate_skill, generate_skill_tests, run_skill_test, generate_visual_report. API key optional — deterministic checks (tool diff, output hash) work without it. Install: pip install \"evalview>=0.5,<1\""
+    }
+  },
+  "_comments": {
+    "usage": "Copy the servers you need to your ~/.claude.json mcpServers section",
+    "env_vars": "Replace YOUR_*_HERE placeholders with actual values",
+    "disabling": "Use disabledMcpServers array in project config to disable per-project",
+    "context_warning": "Keep under 10 MCPs enabled to preserve context window"
+  }
+}

package/.agent/rules/ARCHITECTURAL_BLUEPRINTS.md

@@ -1,62 +1,62 @@
-# 🏗️ Architectural Blueprints & Design System
-
-This document specifies the technical architecture, design standards, and default tools for the Pilo Masterkit. It follows the **Master + Overrides** pattern for flexible design management.
-
----
-
-## 🏛️ 1. Core Architecture & Tech Stack
-
-- **Frontend**: React 19, Next.js 15, Tailwind CSS v4.
-- **Backend**: Node.js (TypeScript) or Python (FastAPI).
-- **Database**: PostgreSQL (Prisma/Drizzle), Redis for caching.
-- **AI Integration**: Multi-model support (GPT-4o, Claude 3.5/3.7, Gemini 2.0) via API Gateway.
-
----
-
-## 🎨 2. Design System (Aesthetics)
-
-The project follows a **Modern, Minimalist, and Elegant** design philosophy. 
-
-### Global Design Master (`design-system/MASTER.md`)
-All global design tokens, color scales, and typography are defined here. 
-
-### Page-Specific Overrides (`design-system/pages/`)
-Specific pages (e.g., Dashboard, Checkout) can deviate from the Master by providing an override file in this folder.
-
-### Visual Styles
-- **Light Mode**: Elegant (Vanilla/Milk, Soft White, Pastel Orange).
-- **Dark Mode**: Aesthetic/Cosmic (Pink and Blue Pastels, Galaxy theme).
-- **Glassmorphism**: Primary effect for dark mode cards and navbars.
-- **Layout**: Bento Grid, consistent spacing (`max-w-7xl` containers).
-- **Typography**: Inter, Montserrat, or Outfit (Google Fonts).
-
----
-
-## 🛠️ 3. Integrated Kits & Capabilities
-
-We leverage world-class skill sets to ensure project excellence:
-
-1.  **UI/UX Pro Max**: 67 styles, 96 palettes, 57 font pairings. Use for all visual enhancements.
-2.  **Antigravity Kit**: 20 specialized agents and 36 foundational skills.
-3.  **Claude ECC**: Advanced TDD, security auditing, and autonomous workflows.
-
----
-
-## 📐 4. Professional UI Rules (Mandatory)
-
-1.  **No Emojis as Icons**: Use SVG icons ONLY (Heroicons, Lucide, Simple Icons).
-2.  **Stable Hover States**: Use color/opacity transitions. Avoid scale transforms that shift layout.
-3.  **Cursor Pointer**: Mandatory `cursor-pointer` for ALL interactive elements (cards, buttons, links).
-4.  **Floating Navbar**: Fixed elements should have proper floating spacing (e.g., `top-4 left-4 right-4`).
-5.  **Theme Direct Use**: Use theme colors directly (`bg-primary`) instead of wrapping them in unverified variables.
-
----
-
-## 🏁 5. Quality Standards
-
-- **PDCA Cycle**: Plan -> Do -> Check -> Act.
-- **Socratic Gate**: Clarify requirements BEFORE implementation.
-- **Zero-Bug Tolerance**: Every feature must include automated tests and manual walkthroughs.
-
----
-> *"Simplicity is the ultimate sophistication."*
+# 🏗️ Architectural Blueprints & Design System
+
+This document specifies the technical architecture, design standards, and default tools for the Pilo Masterkit. It follows the **Master + Overrides** pattern for flexible design management.
+
+---
+
+## 🏛️ 1. Core Architecture & Tech Stack
+
+- **Frontend**: React 19, Next.js 15, Tailwind CSS v4.
+- **Backend**: Node.js (TypeScript) or Python (FastAPI).
+- **Database**: PostgreSQL (Prisma/Drizzle), Redis for caching.
+- **AI Integration**: Multi-model support (GPT-4o, Claude 3.5/3.7, Gemini 2.0) via API Gateway.
+
+---
+
+## 🎨 2. Design System (Aesthetics)
+
+The project follows a **Modern, Minimalist, and Elegant** design philosophy. 
+
+### Global Design Master (`design-system/MASTER.md`)
+All global design tokens, color scales, and typography are defined here. 
+
+### Page-Specific Overrides (`design-system/pages/`)
+Specific pages (e.g., Dashboard, Checkout) can deviate from the Master by providing an override file in this folder.
+
+### Visual Styles
+- **Light Mode**: Elegant (Vanilla/Milk, Soft White, Pastel Orange).
+- **Dark Mode**: Aesthetic/Cosmic (Pink and Blue Pastels, Galaxy theme).
+- **Glassmorphism**: Primary effect for dark mode cards and navbars.
+- **Layout**: Bento Grid, consistent spacing (`max-w-7xl` containers).
+- **Typography**: Inter, Montserrat, or Outfit (Google Fonts).
+
+---
+
+## 🛠️ 3. Integrated Kits & Capabilities
+
+We leverage world-class skill sets to ensure project excellence:
+
+1.  **UI/UX Pro Max**: 67 styles, 96 palettes, 57 font pairings. Use for all visual enhancements.
+2.  **Antigravity Kit**: 20 specialized agents and 36 foundational skills.
+3.  **Claude ECC**: Advanced TDD, security auditing, and autonomous workflows.
+
+---
+
+## 📐 4. Professional UI Rules (Mandatory)
+
+1.  **No Emojis as Icons**: Use SVG icons ONLY (Heroicons, Lucide, Simple Icons).
+2.  **Stable Hover States**: Use color/opacity transitions. Avoid scale transforms that shift layout.
+3.  **Cursor Pointer**: Mandatory `cursor-pointer` for ALL interactive elements (cards, buttons, links).
+4.  **Floating Navbar**: Fixed elements should have proper floating spacing (e.g., `top-4 left-4 right-4`).
+5.  **Theme Direct Use**: Use theme colors directly (`bg-primary`) instead of wrapping them in unverified variables.
+
+---
+
+## 🏁 5. Quality Standards
+
+- **PDCA Cycle**: Plan -> Do -> Check -> Act.
+- **Socratic Gate**: Clarify requirements BEFORE implementation.
+- **Zero-Bug Tolerance**: Every feature must include automated tests and manual walkthroughs.
+
+---
+> *"Simplicity is the ultimate sophistication."*

package/.agent/rules/CODE_CRAFTSMANSHIP.md

@@ -1,69 +1,69 @@
-# 💻 Code Craftsmanship Standards
-
-This document specifies the coding standards, directory structures, and mandatory design patterns for the Pilo Masterkit. 
-
-> *"Code is read more often than it is written. Write for the human first, the machine second."*
-
----
-
-## 🏗️ 1. Project Architecture (Feature-based)
-
-The project uses a **Feature-based Architecture** to ensure high cohesion and low coupling.
-
-### Frontend (Next.js 15 App Router)
-- `src/app/`: Define Routes (Pages, Layouts, Loading, Error).
-- `src/components/ui/`: Base UI primitives (shadcn/ui, tailwind-v4).
-- `src/components/features/`: Complex components tied to business logic.
-- `src/hooks/`: Reusable custom React Hooks.
-- `src/lib/`: Utility libraries and service configurations (Prisma, Cloudinary, etc.).
-
-### Backend (Node.js / FastAPI)
-- `api/routes/`: Endpoint definitions and routing logic.
-- `api/controllers/`: Core business logic handlers.
-- `api/models/`: Data structure definitions and validation schemas.
-
----
-
-## ⚡ 2. Core Coding Principles
-
-### Immutability (CRITICAL)
-- **Rule**: Always create new objects/arrays instead of mutating existing ones.
-- **Pattern**: Use spreads `[...arr]`, `{...obj}` or functional updates.
-- **Reason**: Enhances predictability, debuggability, and compatibility with React's rendering cycle.
-
-### Small & Focused Files
-- **Files**: Aim for 200-400 lines typical. **800 lines MAX**.
-- **Functions**: Small and atomic (<50 lines). If a function does two things, split it.
-- **Cohesion**: Keep related logic together; separate unrelated concerns.
-
-### Error Handling
-- **No Silencing**: Never silently swallow errors with empty `catch` blocks.
-- **User-Friendly**: Provide clear, non-technical messages in UI components.
-- **Detailed Logging**: Log full error context and stack traces server-side.
-
----
-
-## 📝 3. Naming Conventions
-
-- **Files & Folders**: `kebab-case` (e.g., `user-profile.tsx`, `api-gateway/`).
-- **Components**: `PascalCase` (e.g., `UserProfileCard`).
-- **Variables & Functions**: `camelCase` (e.g., `fetchUserData`).
-- **Constants**: `UPPER_SNAKE_CASE` (e.g., `MAX_RETRY_LIMIT`).
-- **Boolean Variables**: Prefix with `is`, `has`, or `should` (e.g., `isLoading`, `hasError`).
-
----
-
-## 🧹 4. Development Patterns
-
-### React 19 & Next.js 15
-- **Server Components (RSC)**: Default to Server Components for data fetching.
-- **Client Components**: Use `"use client"` only when interactivity (hooks/events) is required.
-- **Data Mutations**: Use **Server Actions** for all data-changing operations.
-
-### Backend & API
-- **Statelessness**: Every API endpoint must be stateless.
-- **Validation**: Strict schema-based validation using `Zod` (TypeScript) or `Pydantic` (Python).
-- **Graceful Failure**: Return consistent error envelopes with appropriate HTTP status codes.
-
----
-> *"Simplicity is the key to brilliance."*
+# 💻 Code Craftsmanship Standards
+
+This document specifies the coding standards, directory structures, and mandatory design patterns for the Pilo Masterkit. 
+
+> *"Code is read more often than it is written. Write for the human first, the machine second."*
+
+---
+
+## 🏗️ 1. Project Architecture (Feature-based)
+
+The project uses a **Feature-based Architecture** to ensure high cohesion and low coupling.
+
+### Frontend (Next.js 15 App Router)
+- `src/app/`: Define Routes (Pages, Layouts, Loading, Error).
+- `src/components/ui/`: Base UI primitives (shadcn/ui, tailwind-v4).
+- `src/components/features/`: Complex components tied to business logic.
+- `src/hooks/`: Reusable custom React Hooks.
+- `src/lib/`: Utility libraries and service configurations (Prisma, Cloudinary, etc.).
+
+### Backend (Node.js / FastAPI)
+- `api/routes/`: Endpoint definitions and routing logic.
+- `api/controllers/`: Core business logic handlers.
+- `api/models/`: Data structure definitions and validation schemas.
+
+---
+
+## ⚡ 2. Core Coding Principles
+
+### Immutability (CRITICAL)
+- **Rule**: Always create new objects/arrays instead of mutating existing ones.
+- **Pattern**: Use spreads `[...arr]`, `{...obj}` or functional updates.
+- **Reason**: Enhances predictability, debuggability, and compatibility with React's rendering cycle.
+
+### Small & Focused Files
+- **Files**: Aim for 200-400 lines typical. **800 lines MAX**.
+- **Functions**: Small and atomic (<50 lines). If a function does two things, split it.
+- **Cohesion**: Keep related logic together; separate unrelated concerns.
+
+### Error Handling
+- **No Silencing**: Never silently swallow errors with empty `catch` blocks.
+- **User-Friendly**: Provide clear, non-technical messages in UI components.
+- **Detailed Logging**: Log full error context and stack traces server-side.
+
+---
+
+## 📝 3. Naming Conventions
+
+- **Files & Folders**: `kebab-case` (e.g., `user-profile.tsx`, `api-gateway/`).
+- **Components**: `PascalCase` (e.g., `UserProfileCard`).
+- **Variables & Functions**: `camelCase` (e.g., `fetchUserData`).
+- **Constants**: `UPPER_SNAKE_CASE` (e.g., `MAX_RETRY_LIMIT`).
+- **Boolean Variables**: Prefix with `is`, `has`, or `should` (e.g., `isLoading`, `hasError`).
+
+---
+
+## 🧹 4. Development Patterns
+
+### React 19 & Next.js 15
+- **Server Components (RSC)**: Default to Server Components for data fetching.
+- **Client Components**: Use `"use client"` only when interactivity (hooks/events) is required.
+- **Data Mutations**: Use **Server Actions** for all data-changing operations.
+
+### Backend & API
+- **Statelessness**: Every API endpoint must be stateless.
+- **Validation**: Strict schema-based validation using `Zod` (TypeScript) or `Pydantic` (Python).
+- **Graceful Failure**: Return consistent error envelopes with appropriate HTTP status codes.
+
+---
+> *"Simplicity is the key to brilliance."*

package/.agent/rules/CORE_RULES.md

@@ -1,72 +1,72 @@
----
-trigger: always_on
----
-
-# 📜 CORE RULES & PROTOCOLS / Quy tắc & Giao thức Cốt lõi
-
-> **Dự án: Pilo Masterkit**
-> **Mục đích**: Thiết lập các quy tắc vận hành bất biến cho AI Agent trong dự án.
-> **Lưu ý**: Tệp này có ưu tiên cao nhất (P0) đối với mọi hoạt động của Agent.
-
----
-
-## 🌐 1. Ngôn ngữ & Giao tiếp (Language & Communication)
-
-1.  **Giao tiếp & Suy luận**: Sử dụng **TIẾNG VIỆT** (Bắt buộc) cho mọi cuộc hội thoại, báo cáo và giải thích.
-2.  **Tài liệu (Artifacts)**: Viết nội dung file `.md` (Plan, Task, Walkthrough) bằng **TIẾNG VIỆT**.
-3.  **Kỹ thuật & Mã nguồn**:
-    - Tên biến, hàm, file: **TIẾNG ANH** (camelCase, snake_case...).
-    - Comment trong code: **TIẾNG ANH** (để chuẩn hóa quy chuẩn quốc tế).
-
----
-
-## 🔄 2. Chu trình PDCA (Vòng đời Quản trị)
-
-Mọi tác vụ lớn (Tính năng/Tái cấu trúc/Sửa lỗi) phải tuân thủ nghiêm ngặt chu trình 4 bước:
-
-1.  **PLAN (Lập kế hoạch)**: Phân tích yêu cầu, liệt kê file bị ảnh hưởng và đề xuất giải pháp kỹ thuật rõ ràng. Luôn lập kế hoạch trước khi thực hiện tác vụ phức tạp. **Quy tắc Trạng thái File**: Mỗi khi một kế hoạch được Duyệt (Approved), Hoàn thành (Completed) hoặc Hủy bỏ (Cancelled), PHẢI ghi chú trạng thái ở đầu file và đổi tên file đính kèm trạng thái đó (VD: `[APPROVED]-plan.md`).
-2.  **DO (Thực thi)**: Thực hiện công việc sau khi kế hoạch được phê duyệt. Tuân thủ tiêu chuẩn mã nguồn sạch (Clean Code).
-3.  **CHECK (Kiểm tra)**: Chạy kiểm thử, kiểm tra lỗi cú pháp (Lint) và xác minh kết quả. **Bằng chứng trước, khẳng định sau**.
-4.  **ACT (Tối ưu)**: Khắc phục lỗi phát sinh, cập nhật tài liệu và đóng phiên làm việc. Nếu gặp vấn đề bất ngờ, hãy DỪNG LẠI và lập lại kế hoạch (Re-plan).
-
----
-
-## 🛑 3. Cổng Kiểm soát Socratic (Socratic Gate)
-
-**Luật Bất Biến**: Không bao giờ thực hiện công việc ngay khi nhận yêu cầu mơ hồ hoặc có rủi ro cao. AI phải chủ động:
-- Đặt ít nhất **3 câu hỏi chiến lược** để xác định mục tiêu và phạm vi nếu yêu cầu chưa rõ ràng.
-- Đánh giá rủi ro ảnh hưởng đến hệ thống hiện tại. Nếu có rủi ro: **CẢNH BÁO**.
-- **No Laziness**: Tìm kiếm nguyên nhân gốc rễ (Root Cause) thay vì chỉ sửa chữa bề nổi.
-- **Task Limit**: Một tác vụ chỉ được thực hiện tối đa 3 lần.
-- **Time Limit**: Mỗi lần thực hiện tối đa 10 phút. Nếu treo quá 10 phút, lập tức dừng tác vụ. Nếu dự tính cần nhiều thời gian hơn, phải đưa ra thời gian ước tính và hỏi ý kiến người dùng.
-
----
-
-## 🛡️ 4. Bảo mật & An toàn (Security Armor)
-
-- **Zero Secrets**: Tuyệt đối không lưu trữ API Keys, mật khẩu vào Git. Kiểm tra `.gitignore` thường xuyên.
-- **Sanitization**: Kiểm tra kỹ các dữ liệu đầu vào (Input) và sử dụng Whitelist cho các kết nối mạng (nếu có).
-- **Audit Requirement**: Luôn chạy quét bảo mật (`security-reviewer`) trước khi bàn giao các đoạn mã nhạy cảm.
-
----
-
-## 🧹 5. Tiêu chuẩn Kỹ thuật (Technical Standards)
-
-- **Immutability**: Ưu tiên tạo đối tượng mới thay vì thay đổi trực tiếp (mutate) đối tượng cũ.
-- **Simplicity First**: Ưu tiên giải pháp đơn giản và thanh lịch nhất. Tránh over-engineering.
-- **Modularization**: Không try-hard code trong một file quá lớn. Chia nhỏ file (<400 dòng), ưu tiên tách components/logic dùng chung để tăng khả năng tái sử dụng.
-- **Model Selection**: Tự chọn model phù hợp (flash cho planning/review, pro cho coding/debug sâu).
-
----
-
-## 📂 6. Tổ chức & Vệ sinh Ngữ cảnh (Context Hygiene)
-
-- **Artifacts Location**: Lưu trữ file vào đúng thư mục chuyên biệt. Không để file tạm ở thư mục gốc.
-- **Context Awareness**: Luôn đọc `PROJECT_MAP.md` và `PILO_MASTER.md` khi bắt đầu một phiên làm việc mới. Đọc có chọn lọc (Selective Reading) các file cần thiết thay vì quét toàn bộ project.
-- **Memory Sync**: Luôn cập nhật memories (hoặc nhật ký công việc) sau mỗi phiên làm việc (bất kể lớn nhỏ) và mỗi khi lập một kế hoạch.
-- **Memory Hygiene**: Tự động đánh giá và dọn dẹp memory định kỳ (hoặc bằng lệnh `/clean_memory`). Hệ thống **PHẢI tổng hợp, chắt lọc những tinh hoa, quyết định quan trọng**, đồng thời xóa bỏ triệt để các log/ngữ cảnh dư thừa để tránh "loãng" bộ nhớ.
-- **Customization**: Có thể tạo thêm quy tắc, kỹ năng, hiến pháp hoặc workflows mới bằng lệnh slash tương ứng.
-- **Documentation Sync**: Mọi thay đổi kiến trúc phải được cập nhật ngay lập tức vào bản đồ dự án.
-
----
-> *"Orchestrating the technology of the future with discipline and soul."*
+---
+trigger: always_on
+---
+
+# 📜 CORE RULES & PROTOCOLS / Quy tắc & Giao thức Cốt lõi
+
+> **Dự án: Pilo Masterkit**
+> **Mục đích**: Thiết lập các quy tắc vận hành bất biến cho AI Agent trong dự án.
+> **Lưu ý**: Tệp này có ưu tiên cao nhất (P0) đối với mọi hoạt động của Agent.
+
+---
+
+## 🌐 1. Ngôn ngữ & Giao tiếp (Language & Communication)
+
+1.  **Giao tiếp & Suy luận**: Sử dụng **TIẾNG VIỆT** (Bắt buộc) cho mọi cuộc hội thoại, báo cáo và giải thích.
+2.  **Tài liệu (Artifacts)**: Viết nội dung file `.md` (Plan, Task, Walkthrough) bằng **TIẾNG VIỆT**.
+3.  **Kỹ thuật & Mã nguồn**:
+    - Tên biến, hàm, file: **TIẾNG ANH** (camelCase, snake_case...).
+    - Comment trong code: **TIẾNG ANH** (để chuẩn hóa quy chuẩn quốc tế).
+
+---
+
+## 🔄 2. Chu trình PDCA (Vòng đời Quản trị)
+
+Mọi tác vụ lớn (Tính năng/Tái cấu trúc/Sửa lỗi) phải tuân thủ nghiêm ngặt chu trình 4 bước:
+
+1.  **PLAN (Lập kế hoạch)**: Phân tích yêu cầu, liệt kê file bị ảnh hưởng và đề xuất giải pháp kỹ thuật rõ ràng. Luôn lập kế hoạch trước khi thực hiện tác vụ phức tạp. **Quy tắc Trạng thái File**: Mỗi khi một kế hoạch được Duyệt (Approved), Hoàn thành (Completed) hoặc Hủy bỏ (Cancelled), PHẢI ghi chú trạng thái ở đầu file và đổi tên file đính kèm trạng thái đó (VD: `[APPROVED]-plan.md`).
+2.  **DO (Thực thi)**: Thực hiện công việc sau khi kế hoạch được phê duyệt. Tuân thủ tiêu chuẩn mã nguồn sạch (Clean Code).
+3.  **CHECK (Kiểm tra)**: Chạy kiểm thử, kiểm tra lỗi cú pháp (Lint) và xác minh kết quả. **Bằng chứng trước, khẳng định sau**.
+4.  **ACT (Tối ưu)**: Khắc phục lỗi phát sinh, cập nhật tài liệu và đóng phiên làm việc. Nếu gặp vấn đề bất ngờ, hãy DỪNG LẠI và lập lại kế hoạch (Re-plan).
+
+---
+
+## 🛑 3. Cổng Kiểm soát Socratic (Socratic Gate)
+
+**Luật Bất Biến**: Không bao giờ thực hiện công việc ngay khi nhận yêu cầu mơ hồ hoặc có rủi ro cao. AI phải chủ động:
+- Đặt ít nhất **3 câu hỏi chiến lược** để xác định mục tiêu và phạm vi nếu yêu cầu chưa rõ ràng.
+- Đánh giá rủi ro ảnh hưởng đến hệ thống hiện tại. Nếu có rủi ro: **CẢNH BÁO**.
+- **No Laziness**: Tìm kiếm nguyên nhân gốc rễ (Root Cause) thay vì chỉ sửa chữa bề nổi.
+- **Task Limit**: Một tác vụ chỉ được thực hiện tối đa 3 lần.
+- **Time Limit**: Mỗi lần thực hiện tối đa 10 phút. Nếu treo quá 10 phút, lập tức dừng tác vụ. Nếu dự tính cần nhiều thời gian hơn, phải đưa ra thời gian ước tính và hỏi ý kiến người dùng.
+
+---
+
+## 🛡️ 4. Bảo mật & An toàn (Security Armor)
+
+- **Zero Secrets**: Tuyệt đối không lưu trữ API Keys, mật khẩu vào Git. Kiểm tra `.gitignore` thường xuyên.
+- **Sanitization**: Kiểm tra kỹ các dữ liệu đầu vào (Input) và sử dụng Whitelist cho các kết nối mạng (nếu có).
+- **Audit Requirement**: Luôn chạy quét bảo mật (`security-reviewer`) trước khi bàn giao các đoạn mã nhạy cảm.
+
+---
+
+## 🧹 5. Tiêu chuẩn Kỹ thuật (Technical Standards)
+
+- **Immutability**: Ưu tiên tạo đối tượng mới thay vì thay đổi trực tiếp (mutate) đối tượng cũ.
+- **Simplicity First**: Ưu tiên giải pháp đơn giản và thanh lịch nhất. Tránh over-engineering.
+- **Modularization**: Không try-hard code trong một file quá lớn. Chia nhỏ file (<400 dòng), ưu tiên tách components/logic dùng chung để tăng khả năng tái sử dụng.
+- **Model Selection**: Tự chọn model phù hợp (flash cho planning/review, pro cho coding/debug sâu).
+
+---
+
+## 📂 6. Tổ chức & Vệ sinh Ngữ cảnh (Context Hygiene)
+
+- **Artifacts Location**: Lưu trữ file vào đúng thư mục chuyên biệt. Không để file tạm ở thư mục gốc.
+- **Context Awareness**: Luôn đọc `PROJECT_MAP.md` và `PILO_MASTER.md` khi bắt đầu một phiên làm việc mới. Đọc có chọn lọc (Selective Reading) các file cần thiết thay vì quét toàn bộ project.
+- **Memory Sync**: Luôn cập nhật memories (hoặc nhật ký công việc) sau mỗi phiên làm việc (bất kể lớn nhỏ) và mỗi khi lập một kế hoạch.
+- **Memory Hygiene**: Tự động đánh giá và dọn dẹp memory định kỳ (hoặc bằng lệnh `/clean_memory`). Hệ thống **PHẢI tổng hợp, chắt lọc những tinh hoa, quyết định quan trọng**, đồng thời xóa bỏ triệt để các log/ngữ cảnh dư thừa để tránh "loãng" bộ nhớ.
+- **Customization**: Có thể tạo thêm quy tắc, kỹ năng, hiến pháp hoặc workflows mới bằng lệnh slash tương ứng.
+- **Documentation Sync**: Mọi thay đổi kiến trúc phải được cập nhật ngay lập tức vào bản đồ dự án.
+
+---
+> *"Orchestrating the technology of the future with discipline and soul."*