@heyai-rules/pilo-masterkit 1.2.2 → 2.2.0

package/.agent/rules/PROJECT_MAP.md

@@ -1,58 +1,58 @@
-# 🗺️ Project Map / Bản đồ Điều hướng Dự án
-
-> **Dự án**: Pilo Masterkit
-> **Vai trò**: Cung cấp cái nhìn tổng quan về cấu trúc hệ thống, quy chuẩn kỹ thuật và triết lý vận hành.
-
----
-
-## 🏛️ Quản trị Hệ thống (.agent/)
-
-Đây là "não bộ" của dự án, chứa các quy tắc và thực thể AI:
-
-- **[PILO_MASTER.md](../agents/PILO_MASTER.md)**: Nhân dạng chính & Điều phối viên (Senior Architect).
-- **[CORE_RULES.md](CORE_RULES.md)**: Giao thức bắt buộc (P0), PDCA, Socratic Gate.
-- **[SECURITY_ARMOR.md](SECURITY_ARMOR.md)**: Quy chuẩn bảo mật và quét lỗ hổng.
-- **`agents/`**: Danh sách 20+ chuyên gia kỹ thuật (Planner, Debugger, v.v.).
-- **`skills/`**: Thư viện 125+ kỹ năng chuyên sâu (UI/UX Pro, React Expert, v.v.).
-- **`workflows/`**: Các quy trình tự động hóa kích hoạt bằng Slash Command.
-
-### 🔍 Giao thức Đọc File (Reading Protocol)
-> **Selective Reading**: AI PHẢI đọc có chọn lọc các file cần thiết dựa trên yêu cầu của người dùng thay vì quét toàn bộ project. Hãy ưu tiên các sơ đồ kiến trúc và file quy tắc trước khi đi sâu vào mã nguồn.
-
----
-
-## 💻 Tiêu chuẩn Kỹ thuật (Technical Standards)
-
-Các quy ước bắt buộc cho mã nguồn:
-
-- **[CODE_STANDARDS.md](../../products/CODE_STANDARDS.md)**: Quy tắc đặt tên và cấu trúc file.
-- **[SYSTEM_DESIGN.md](../../products/SYSTEM_DESIGN.md)**: Kiến trúc hệ thống và thẩm mỹ (Master + Overrides).
-- **[TESTING_POLICY.md](../../products/TESTING_POLICY.md)**: Quy trình TDD và yêu cầu Coverage >80%.
-- **[GIT_WORKFLOW.md](../../products/GIT_WORKFLOW.md)**: Conventional Commits và chiến lược nhánh.
-
----
-
-## 📁 Thư mục Chức năng (Functional Directories)
-
-- **`lessons/`**: Bài học kinh nghiệm và kinh nghiệm tích lũy sau mỗi task.
-- **`reports/`**: Báo cáo tiến độ, kết quả audit và hiệu năng.
-- **`plans/`**: Kế hoạch triển khai chi tiết cho các tính năng mới.
-- **`status/`**: Trạng thái hiện tại của dự án và các module.
-- **`tasks/`**: Nhiệm vụ chi tiết (todo, in-progress, done).
-- **`logs/`**: Nhật ký hoạt động chi tiết của Agent và hệ thống.
-- **`walkthroughs/`**: Hướng dẫn từng bước cho các tính năng phức tạp.
-- **`producs/`**: Tài liệu đặc tả sản phẩm (specs, PRD, roadmap).
-- **`.agent/scripts/`**: Các kịch bản Master Audit (`checklist.py`, `verify_all.py`).
-
----
-
-## 🛠️ Trạng thái Hệ thống
-
-| Thành phần | Trạng thái | Ghi chú |
-| :--- | :--- | :--- |
-| **Agent Fleet** | ✅ Sẵn sàng | 20+ Agents đã nạp |
-| **Skill Matrix** | ✅ Sẵn sàng | 125+ Skills đã nạp |
-| **Security Gate** | ✅ Kích hoạt | Bắt buộc quét trước commit |
-
----
-> *"Orchestrating the technology of the future with discipline and soul."*
+# 🗺️ Project Map / Bản đồ Điều hướng Dự án
+
+> **Dự án**: Pilo Masterkit
+> **Vai trò**: Cung cấp cái nhìn tổng quan về cấu trúc hệ thống, quy chuẩn kỹ thuật và triết lý vận hành.
+
+---
+
+## 🏛️ Quản trị Hệ thống (.agent/)
+
+Đây là "não bộ" của dự án, chứa các quy tắc và thực thể AI:
+
+- **[PILO_MASTER.md](../agents/PILO_MASTER.md)**: Nhân dạng chính & Điều phối viên (Senior Architect).
+- **[CORE_RULES.md](CORE_RULES.md)**: Giao thức bắt buộc (P0), PDCA, Socratic Gate.
+- **[SECURITY_ARMOR.md](SECURITY_ARMOR.md)**: Quy chuẩn bảo mật và quét lỗ hổng.
+- **`agents/`**: Danh sách 20+ chuyên gia kỹ thuật (Planner, Debugger, v.v.).
+- **`skills/`**: Thư viện 125+ kỹ năng chuyên sâu (UI/UX Pro, React Expert, v.v.).
+- **`workflows/`**: Các quy trình tự động hóa kích hoạt bằng Slash Command.
+
+### 🔍 Giao thức Đọc File (Reading Protocol)
+> **Selective Reading**: AI PHẢI đọc có chọn lọc các file cần thiết dựa trên yêu cầu của người dùng thay vì quét toàn bộ project. Hãy ưu tiên các sơ đồ kiến trúc và file quy tắc trước khi đi sâu vào mã nguồn.
+
+---
+
+## 💻 Tiêu chuẩn Kỹ thuật (Technical Standards)
+
+Các quy ước bắt buộc cho mã nguồn:
+
+- **[CODE_STANDARDS.md](../../products/CODE_STANDARDS.md)**: Quy tắc đặt tên và cấu trúc file.
+- **[SYSTEM_DESIGN.md](../../products/SYSTEM_DESIGN.md)**: Kiến trúc hệ thống và thẩm mỹ (Master + Overrides).
+- **[TESTING_POLICY.md](../../products/TESTING_POLICY.md)**: Quy trình TDD và yêu cầu Coverage >80%.
+- **[GIT_WORKFLOW.md](../../products/GIT_WORKFLOW.md)**: Conventional Commits và chiến lược nhánh.
+
+---
+
+## 📁 Thư mục Chức năng (Functional Directories)
+
+- **`lessons/`**: Bài học kinh nghiệm và kinh nghiệm tích lũy sau mỗi task.
+- **`reports/`**: Báo cáo tiến độ, kết quả audit và hiệu năng.
+- **`plans/`**: Kế hoạch triển khai chi tiết cho các tính năng mới.
+- **`status/`**: Trạng thái hiện tại của dự án và các module.
+- **`tasks/`**: Nhiệm vụ chi tiết (todo, in-progress, done).
+- **`logs/`**: Nhật ký hoạt động chi tiết của Agent và hệ thống.
+- **`walkthroughs/`**: Hướng dẫn từng bước cho các tính năng phức tạp.
+- **`producs/`**: Tài liệu đặc tả sản phẩm (specs, PRD, roadmap).
+- **`.agent/scripts/`**: Các kịch bản Master Audit (`checklist.py`, `verify_all.py`).
+
+---
+
+## 🛠️ Trạng thái Hệ thống
+
+| Thành phần | Trạng thái | Ghi chú |
+| :--- | :--- | :--- |
+| **Agent Fleet** | ✅ Sẵn sàng | 20+ Agents đã nạp |
+| **Skill Matrix** | ✅ Sẵn sàng | 125+ Skills đã nạp |
+| **Security Gate** | ✅ Kích hoạt | Bắt buộc quét trước commit |
+
+---
+> *"Orchestrating the technology of the future with discipline and soul."*

package/.agent/rules/QUALITY_ASSURANCE.md

@@ -1,54 +1,54 @@
-# 🧪 Quality Assurance & Testing Policy
-
-This document defines the rigorous automated testing standards for the Pilo Masterkit. **Zero-Bug Tolerance** is our ultimate target.
-
-> *"If it's not tested, it's broken."*
-
----
-
-## 📐 1. The Testing Pyramid
-
-1. **Unit Tests (Base)**: Individual functions, utilities, and components (Vitest/Pytest).
-2. **Integration Tests (Middle)**: Interaction between modules and service integrations.
-3. **End-to-End (E2E) Tests (Peak)**: Critical user flows and frontend-backend interactions (Playwright).
-
----
-
-## 🚀 2. Mandatory TDD Workflow (CRITICAL)
-
-**Test-Driven Development (TDD)** is mandatory for all new features and bug fixes. Follow the **Red-Green-Refactor** cycle:
-
-1. **RED**: Write a failing test for the new functionality or bug. (Viết test thất bại trước).
-2. **GREEN**: Write the minimal implementation to make the test pass. (Viết code tối thiểu để pass).
-3. **REFACTOR**: Optimize the code and test suite for clarity and performance. (Tối ưu hóa mã nguồn).
-
----
-
-## 🛠️ 3. Testing Stack & Tools
-
-- **Core Engine**: Vitest (Web), Pytest (Python).
-- **Automation**: Playwright (E2E, Cross-browser).
-- **Mocking**: MSW (Mock Service Worker) for API layer simulation.
-- **Component Test**: Testing Library (React/Vue/Svelte).
-
----
-
-## 📜 4. Operational Requirements
-
-- **Root Cause Analysis**: Every failing test must be analyzed for its root cause. Fix the cause, not the symptoms.
-- **Regression Guard**: Every discovered bug MUST have a corresponding regression test to prevent its return.
-- **Coverage Goal**: 
-  - **Business Logic**: 80%+ mandatory coverage.
-  - **Main API Endpoints**: 100% coverage (Success & Error cases).
-  - **UI Components**: Ensure error, loading, and success states are tested.
-
----
-
-## 🏁 5. Verification & Reporting
-
-- **Manual Audit**: Use `python .agent/scripts/checklist.py .` before completion.
-- **Evidence Collection**: Test logs and coverage reports MUST be included in the final `walkthrough.md`.
-- **Pre-Commit Check**: No code shall be committed with failing tests or critical lint errors.
-
----
-> *"Quality is not an act, it is a habit."*
+# 🧪 Quality Assurance & Testing Policy
+
+This document defines the rigorous automated testing standards for the Pilo Masterkit. **Zero-Bug Tolerance** is our ultimate target.
+
+> *"If it's not tested, it's broken."*
+
+---
+
+## 📐 1. The Testing Pyramid
+
+1. **Unit Tests (Base)**: Individual functions, utilities, and components (Vitest/Pytest).
+2. **Integration Tests (Middle)**: Interaction between modules and service integrations.
+3. **End-to-End (E2E) Tests (Peak)**: Critical user flows and frontend-backend interactions (Playwright).
+
+---
+
+## 🚀 2. Mandatory TDD Workflow (CRITICAL)
+
+**Test-Driven Development (TDD)** is mandatory for all new features and bug fixes. Follow the **Red-Green-Refactor** cycle:
+
+1. **RED**: Write a failing test for the new functionality or bug. (Viết test thất bại trước).
+2. **GREEN**: Write the minimal implementation to make the test pass. (Viết code tối thiểu để pass).
+3. **REFACTOR**: Optimize the code and test suite for clarity and performance. (Tối ưu hóa mã nguồn).
+
+---
+
+## 🛠️ 3. Testing Stack & Tools
+
+- **Core Engine**: Vitest (Web), Pytest (Python).
+- **Automation**: Playwright (E2E, Cross-browser).
+- **Mocking**: MSW (Mock Service Worker) for API layer simulation.
+- **Component Test**: Testing Library (React/Vue/Svelte).
+
+---
+
+## 📜 4. Operational Requirements
+
+- **Root Cause Analysis**: Every failing test must be analyzed for its root cause. Fix the cause, not the symptoms.
+- **Regression Guard**: Every discovered bug MUST have a corresponding regression test to prevent its return.
+- **Coverage Goal**: 
+  - **Business Logic**: 80%+ mandatory coverage.
+  - **Main API Endpoints**: 100% coverage (Success & Error cases).
+  - **UI Components**: Ensure error, loading, and success states are tested.
+
+---
+
+## 🏁 5. Verification & Reporting
+
+- **Manual Audit**: Use `python .agent/scripts/checklist.py .` before completion.
+- **Evidence Collection**: Test logs and coverage reports MUST be included in the final `walkthrough.md`.
+- **Pre-Commit Check**: No code shall be committed with failing tests or critical lint errors.
+
+---
+> *"Quality is not an act, it is a habit."*

package/.agent/rules/SECURITY_ARMOR.md

@@ -1,44 +1,44 @@
-# 🛡️ SECURITY ARMOR / Giao thức Bảo mật Cốt lõi
-
-> **Dự án**: Pilo Masterkit
-> **Nguyên tắc**: Bảo mật không phải là một sản phẩm, mà là một quy trình xuyên suốt (Security-First).
-
----
-
-## 🔐 1. Quản lý Bí mật (Zero Secrets)
-
-- **Tuyệt đối cấm**: Không bao giờ hardcode API Keys, mật khẩu, tokens vào mã nguồn hoặc commit lên Git.
-- **Lưu trữ**: Chỉ sử dụng biến môi trường (`.env`) hoặc hệ thống quản lý bí mật chuyên dụng.
-- **Xác minh**: Luôn kiểm tra file `.gitignore` để đảm bảo các file nhạy cảm không bị lộ.
-- **Sự cố**: Nếu phát hiện rò rỉ, ngay lập tức: **Dừng tiến trình -> Thu hồi Key -> Tạo mới Key -> Quét toàn bộ lịch sử Git.**
-
----
-
-## 🛠️ 2. An toàn Runtime & Công cụ
-
-- **Quyền hạn tối thiểu (Least Privilege)**: AI chỉ hoạt động trong phạm vi thư mục dự án được cấp quyền.
-- **Hạn chế hệ thống**: Cấm AI tự ý thay đổi các cấu trúc cốt lõi của hệ điều hành (OS) trừ khi có chỉ thị cụ thể và được người dùng phê duyệt.
-- **Kết nối mạng**: Sử dụng Whitelist cho các kết nối ra ngoài. Luôn hỏi ý kiến người dùng trước khi thực hiện các yêu cầu mạng phức tạp.
-
----
-
-## 🧪 3. Kiểm tra Bảo mật (Security Audit)
-
-**Trước khi bàn giao bất kỳ đoạn mã nào, AI PHẢI:**
-
-1.  **Sanitization**: Kiểm tra kỹ các dữ liệu đầu vào (Input) từ người dùng để ngăn chặn SQL Injection và XSS.
-2.  **Vulnerability Scan**: Sử dụng kỹ năng `vulnerability-scanner` hoặc chạy script `security_scan.py` nếu có.
-3.  **Dependency Check**: Kiểm tra các thư viện bên thứ ba để đảm bảo không có lỗ hổng bảo mật đã biết (CVE).
-
----
-
-## 📊 4. Danh sách Kiểm tra (Security Checklist)
-
-- [ ] Không có thông tin nhạy cảm trong mã nguồn.
-- [ ] Dữ liệu đầu vào đã được làm sạch và xác thực.
-- [ ] Các thông báo lỗi không làm lộ thông tin cấu hình hệ thống.
-- [ ] Mật khẩu/Token được mã hóa an toàn nếu được lưu trữ.
-- [ ] Quyền truy cập tệp tin (File Permissions) được thiết lập đúng.
-
----
-> *"Security is a process, not a destination."*
+# 🛡️ SECURITY ARMOR / Giao thức Bảo mật Cốt lõi
+
+> **Dự án**: Pilo Masterkit
+> **Nguyên tắc**: Bảo mật không phải là một sản phẩm, mà là một quy trình xuyên suốt (Security-First).
+
+---
+
+## 🔐 1. Quản lý Bí mật (Zero Secrets)
+
+- **Tuyệt đối cấm**: Không bao giờ hardcode API Keys, mật khẩu, tokens vào mã nguồn hoặc commit lên Git.
+- **Lưu trữ**: Chỉ sử dụng biến môi trường (`.env`) hoặc hệ thống quản lý bí mật chuyên dụng.
+- **Xác minh**: Luôn kiểm tra file `.gitignore` để đảm bảo các file nhạy cảm không bị lộ.
+- **Sự cố**: Nếu phát hiện rò rỉ, ngay lập tức: **Dừng tiến trình -> Thu hồi Key -> Tạo mới Key -> Quét toàn bộ lịch sử Git.**
+
+---
+
+## 🛠️ 2. An toàn Runtime & Công cụ
+
+- **Quyền hạn tối thiểu (Least Privilege)**: AI chỉ hoạt động trong phạm vi thư mục dự án được cấp quyền.
+- **Hạn chế hệ thống**: Cấm AI tự ý thay đổi các cấu trúc cốt lõi của hệ điều hành (OS) trừ khi có chỉ thị cụ thể và được người dùng phê duyệt.
+- **Kết nối mạng**: Sử dụng Whitelist cho các kết nối ra ngoài. Luôn hỏi ý kiến người dùng trước khi thực hiện các yêu cầu mạng phức tạp.
+
+---
+
+## 🧪 3. Kiểm tra Bảo mật (Security Audit)
+
+**Trước khi bàn giao bất kỳ đoạn mã nào, AI PHẢI:**
+
+1.  **Sanitization**: Kiểm tra kỹ các dữ liệu đầu vào (Input) từ người dùng để ngăn chặn SQL Injection và XSS.
+2.  **Vulnerability Scan**: Sử dụng kỹ năng `vulnerability-scanner` hoặc chạy script `security_scan.py` nếu có.
+3.  **Dependency Check**: Kiểm tra các thư viện bên thứ ba để đảm bảo không có lỗ hổng bảo mật đã biết (CVE).
+
+---
+
+## 📊 4. Danh sách Kiểm tra (Security Checklist)
+
+- [ ] Không có thông tin nhạy cảm trong mã nguồn.
+- [ ] Dữ liệu đầu vào đã được làm sạch và xác thực.
+- [ ] Các thông báo lỗi không làm lộ thông tin cấu hình hệ thống.
+- [ ] Mật khẩu/Token được mã hóa an toàn nếu được lưu trữ.
+- [ ] Quyền truy cập tệp tin (File Permissions) được thiết lập đúng.
+
+---
+> *"Security is a process, not a destination."*

package/.agent/rules/VERSION_ORCHESTRATION.md

@@ -1,64 +1,64 @@
-# 🌿 Version Orchestration & Collaboration
-
-This document defines the Git workflow, branching strategy, and commit message standards for the Pilo Masterkit to ensure a clean, traceable, and professional history.
-
-> *"Clean Git history is as important as clean code."*
-
----
-
-## 🌿 1. Modular Branching Strategy
-
-- **`main`**: The source of truth. Always stable and production-ready.
-- **`dev`**: The primary integration branch for new features and fixes.
-- **`feature/[name]`**: Dedicated branch for developing a specific feature.
-- **`bugfix/[name]`**: Dedicated branch for fixing identified bugs.
-- **`hotfix/[name]`**: Urgent production fixes.
-
----
-
-## 💬 2. Conventional Commit Standards
-
-Every commit message MUST follow the **Conventional Commits** format: `type(scope): description`.
-
-| Type | Description |
-| :--- | :--- |
-| **feat** | A new feature or capability. |
-| **fix** | A bug fix. |
-| **docs** | Documentation-only changes. |
-| **style** | Formatting, missing semi-colons, etc. (no business logic change). |
-| **refactor** | Code change that neither fixes a bug nor adds a feature. |
-| **perf** | A code change that improves performance. |
-| **test** | Adding missing tests or correcting existing tests. |
-| **chore** | Changes to the build process, auxiliary tools, or libraries. |
-| **ci** | Changes to CI configuration files and scripts. |
-
-*Example: `feat(auth): add JWT login support`*
-
----
-
-## 🚀 3. Pull Request (PR) Protocol
-
-Before submitting or merging any PR, the AI Task Force must ensure:
-
-1. **Protocol Verification**: All code adheres to `CORE_RULES.md` and `CODE_CRAFTSMANSHIP.md`.
-2. **Quality Gate**: 
-   - `python .agent/scripts/checklist.py .` must pass with zero critical blockers.
-   - All tests pass with **80%+ coverage**.
-3. **Walkthrough Inclusion**: A final `walkthrough.md` report must be provided, detailing:
-   - What changed and why.
-   - Evidence of successful tests (logs/screenshots).
-   - Side-effects analyzed via mental simulation.
-4. **Knowledge Capture**: Any important project context, architectural decisions, or lessons learned must be updated in `.agent/tasks/lessons.md`.
-5. **Approval**: Final confirmation from the User or a senior AI Orchestrator.
-
----
-
-## 🧹 4. Repository Hygiene
-
-- **Micro-Commits**: Prefer small, atomic commits covering a single logical change.
-- **Zero Secrets**: Strictly prohibit committing `.env` files, API keys, or any sensitive credentials.
-- **Sanitized History**: Use `rebase` (where appropriate) to keep a linear and clean history.
-- **File Integrity**: Never leave temporary files, build artifacts, or IDE configs in the repository.
-
----
-> *"Orchestrate the history as you orchestrate the code."*
+# 🌿 Version Orchestration & Collaboration
+
+This document defines the Git workflow, branching strategy, and commit message standards for the Pilo Masterkit to ensure a clean, traceable, and professional history.
+
+> *"Clean Git history is as important as clean code."*
+
+---
+
+## 🌿 1. Modular Branching Strategy
+
+- **`main`**: The source of truth. Always stable and production-ready.
+- **`dev`**: The primary integration branch for new features and fixes.
+- **`feature/[name]`**: Dedicated branch for developing a specific feature.
+- **`bugfix/[name]`**: Dedicated branch for fixing identified bugs.
+- **`hotfix/[name]`**: Urgent production fixes.
+
+---
+
+## 💬 2. Conventional Commit Standards
+
+Every commit message MUST follow the **Conventional Commits** format: `type(scope): description`.
+
+| Type | Description |
+| :--- | :--- |
+| **feat** | A new feature or capability. |
+| **fix** | A bug fix. |
+| **docs** | Documentation-only changes. |
+| **style** | Formatting, missing semi-colons, etc. (no business logic change). |
+| **refactor** | Code change that neither fixes a bug nor adds a feature. |
+| **perf** | A code change that improves performance. |
+| **test** | Adding missing tests or correcting existing tests. |
+| **chore** | Changes to the build process, auxiliary tools, or libraries. |
+| **ci** | Changes to CI configuration files and scripts. |
+
+*Example: `feat(auth): add JWT login support`*
+
+---
+
+## 🚀 3. Pull Request (PR) Protocol
+
+Before submitting or merging any PR, the AI Task Force must ensure:
+
+1. **Protocol Verification**: All code adheres to `CORE_RULES.md` and `CODE_CRAFTSMANSHIP.md`.
+2. **Quality Gate**: 
+   - `python .agent/scripts/checklist.py .` must pass with zero critical blockers.
+   - All tests pass with **80%+ coverage**.
+3. **Walkthrough Inclusion**: A final `walkthrough.md` report must be provided, detailing:
+   - What changed and why.
+   - Evidence of successful tests (logs/screenshots).
+   - Side-effects analyzed via mental simulation.
+4. **Knowledge Capture**: Any important project context, architectural decisions, or lessons learned must be updated in `.agent/tasks/lessons.md`.
+5. **Approval**: Final confirmation from the User or a senior AI Orchestrator.
+
+---
+
+## 🧹 4. Repository Hygiene
+
+- **Micro-Commits**: Prefer small, atomic commits covering a single logical change.
+- **Zero Secrets**: Strictly prohibit committing `.env` files, API keys, or any sensitive credentials.
+- **Sanitized History**: Use `rebase` (where appropriate) to keep a linear and clean history.
+- **File Integrity**: Never leave temporary files, build artifacts, or IDE configs in the repository.
+
+---
+> *"Orchestrate the history as you orchestrate the code."*

package/.agent/rules/WORKFLOW_ORCHESTRATION.md

@@ -1,55 +1,55 @@
-# 🔄 Workflow Orchestration Protocols
-
-This document defines the advanced operational workflows for the Pilo Masterkit. These rules ensure autonomy, elegance, and continuous self-improvement.
-
----
-
-## 1. Plan Mode Default
-- **Trigger**: Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions).
-- **Control**: If something goes sideways, **STOP and re-plan immediately** — don't keep pushing.
-- **Verification**: Use plan mode for verification steps, not just building.
-- **Spec First**: Write detailed specs upfront to reduce ambiguity.
-
-## 2. Subagent Strategy
-- **Clean Context**: Use subagents liberally to keep main context window clean.
-- **Delegation**: Offload research, exploration, and parallel analysis to specialized subagents.
-- **Scale**: For complex problems, throw more compute at it via multiple parallel subagents.
-- **Focus**: One specific task per subagent for maximum accuracy.
-
-## 3. Self-Improvement Loop
-- **Memory Update**: After ANY correction from the user: update `.agent/tasks/lessons.md` with the new pattern.
-- **Preventive Rules**: Write rules for yourself in this project to prevent repeating the same mistake.
-- **Iteration**: Ruthlessly iterate on these lessons until the mistake rate drops.
-- **Awareness**: Review previous lessons at the start of every session.
-
-## 4. Verification Before Done
-- **No Assumptions**: Never mark a task complete without proving it works.
-- **Diff Analysis**: Diff behavior between the original code and your changes.
-- **Peer Review**: Ask yourself: *"Would a staff engineer approve this change?"*.
-- **Demonstration**: Run tests, check logs, and clearly demonstrate correctness to the user.
-
-## 5. Demand Elegance (Balanced)
-- **Pause & Reflect**: For non-trivial changes, pause and ask: *"Is there a more elegant way?"*.
-- **Refinement**: If a fix feels hacky: *"Knowing everything I know, implement the elegant solution instead"*.
-- **Practicality**: Skip this for simple, obvious fixes — do not over-engineer.
-- **Self-Critique**: Challenge your own work before presenting it.
-
-## 6. Autonomous Bug Fixing
-- **Direct Resolution**: When given a bug report: just fix it. Don't ask for hand-holding.
-- **Root Cause**: Identify logs, errors, or failing tests — then resolve them thoroughly.
-- **Minimal User Burden**: Aim for zero context switching required from the user.
-- **CI Ownership**: Fix failing CI tests automatically without being told how.
-
----
-
-## Task Management Lifecycle
-
-1. **Plan First**: Write the plan to `.agent/tasks/todo.md` with checkable items.
-2. **Verify Plan**: Check in with the user (if required) before starting implementation.
-3. **Track Progress**: Mark items as complete as you progress.
-4. **Explain Changes**: Provide a high-level summary at each major step.
-5. **Document Results**: Add a "Review" section to `.agent/tasks/todo.md` after completion.
-6. **Capture Lessons**: Update `.agent/tasks/lessons.md` immediately after any corrections.
-
----
-> *"Efficiency is doing things right; effectiveness is doing the right things."*
+# 🔄 Workflow Orchestration Protocols
+
+This document defines the advanced operational workflows for the Pilo Masterkit. These rules ensure autonomy, elegance, and continuous self-improvement.
+
+---
+
+## 1. Plan Mode Default
+- **Trigger**: Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions).
+- **Control**: If something goes sideways, **STOP and re-plan immediately** — don't keep pushing.
+- **Verification**: Use plan mode for verification steps, not just building.
+- **Spec First**: Write detailed specs upfront to reduce ambiguity.
+
+## 2. Subagent Strategy
+- **Clean Context**: Use subagents liberally to keep main context window clean.
+- **Delegation**: Offload research, exploration, and parallel analysis to specialized subagents.
+- **Scale**: For complex problems, throw more compute at it via multiple parallel subagents.
+- **Focus**: One specific task per subagent for maximum accuracy.
+
+## 3. Self-Improvement Loop
+- **Memory Update**: After ANY correction from the user: update `.agent/tasks/lessons.md` with the new pattern.
+- **Preventive Rules**: Write rules for yourself in this project to prevent repeating the same mistake.
+- **Iteration**: Ruthlessly iterate on these lessons until the mistake rate drops.
+- **Awareness**: Review previous lessons at the start of every session.
+
+## 4. Verification Before Done
+- **No Assumptions**: Never mark a task complete without proving it works.
+- **Diff Analysis**: Diff behavior between the original code and your changes.
+- **Peer Review**: Ask yourself: *"Would a staff engineer approve this change?"*.
+- **Demonstration**: Run tests, check logs, and clearly demonstrate correctness to the user.
+
+## 5. Demand Elegance (Balanced)
+- **Pause & Reflect**: For non-trivial changes, pause and ask: *"Is there a more elegant way?"*.
+- **Refinement**: If a fix feels hacky: *"Knowing everything I know, implement the elegant solution instead"*.
+- **Practicality**: Skip this for simple, obvious fixes — do not over-engineer.
+- **Self-Critique**: Challenge your own work before presenting it.
+
+## 6. Autonomous Bug Fixing
+- **Direct Resolution**: When given a bug report: just fix it. Don't ask for hand-holding.
+- **Root Cause**: Identify logs, errors, or failing tests — then resolve them thoroughly.
+- **Minimal User Burden**: Aim for zero context switching required from the user.
+- **CI Ownership**: Fix failing CI tests automatically without being told how.
+
+---
+
+## Task Management Lifecycle
+
+1. **Plan First**: Write the plan to `.agent/tasks/todo.md` with checkable items.
+2. **Verify Plan**: Check in with the user (if required) before starting implementation.
+3. **Track Progress**: Mark items as complete as you progress.
+4. **Explain Changes**: Provide a high-level summary at each major step.
+5. **Document Results**: Add a "Review" section to `.agent/tasks/todo.md` after completion.
+6. **Capture Lessons**: Update `.agent/tasks/lessons.md` immediately after any corrections.
+
+---
+> *"Efficiency is doing things right; effectiveness is doing the right things."*

package/.agent/rules/common/agents.md

@@ -0,0 +1,50 @@
+# Agent Orchestration
+
+## Available Agents
+
+Located in `~/.claude/agents/`:
+
+| Agent | Purpose | When to Use |
+|-------|---------|-------------|
+| planner | Implementation planning | Complex features, refactoring |
+| architect | System design | Architectural decisions |
+| tdd-guide | Test-driven development | New features, bug fixes |
+| code-reviewer | Code review | After writing code |
+| security-reviewer | Security analysis | Before commits |
+| build-error-resolver | Fix build errors | When build fails |
+| e2e-runner | E2E testing | Critical user flows |
+| refactor-cleaner | Dead code cleanup | Code maintenance |
+| doc-updater | Documentation | Updating docs |
+| rust-reviewer | Rust code review | Rust projects |
+
+## Immediate Agent Usage
+
+No user prompt needed:
+1. Complex feature requests - Use **planner** agent
+2. Code just written/modified - Use **code-reviewer** agent
+3. Bug fix or new feature - Use **tdd-guide** agent
+4. Architectural decision - Use **architect** agent
+
+## Parallel Task Execution
+
+ALWAYS use parallel Task execution for independent operations:
+
+```markdown
+# GOOD: Parallel execution
+Launch 3 agents in parallel:
+1. Agent 1: Security analysis of auth module
+2. Agent 2: Performance review of cache system
+3. Agent 3: Type checking of utilities
+
+# BAD: Sequential when unnecessary
+First agent 1, then agent 2, then agent 3
+```
+
+## Multi-Perspective Analysis
+
+For complex problems, use split role sub-agents:
+- Factual reviewer
+- Senior engineer
+- Security expert
+- Consistency reviewer
+- Redundancy checker