@heyai-rules/pilo-masterkit 1.2.2

package/.agent/rules/CODE_CRAFTSMANSHIP.md

@@ -0,0 +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."*

package/.agent/rules/CORE_RULES.md

@@ -0,0 +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."*

package/.agent/rules/PROJECT_MAP.md

@@ -0,0 +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."*

package/.agent/rules/QUALITY_ASSURANCE.md

@@ -0,0 +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."*

package/.agent/rules/SECURITY_ARMOR.md

@@ -0,0 +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."*

package/.agent/rules/VERSION_ORCHESTRATION.md

@@ -0,0 +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."*

package/.agent/rules/WORKFLOW_ORCHESTRATION.md

@@ -0,0 +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."*

package/.agent/scripts/auto_preview.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+Auto Preview - Antigravity Kit
+==============================
+Manages (start/stop/status) the local development server for previewing the application.
+
+Usage:
+    python .agent/scripts/auto_preview.py start [port]
+    python .agent/scripts/auto_preview.py stop
+    python .agent/scripts/auto_preview.py status
+"""
+
+import os
+import sys
+import time
+import json
+import signal
+import argparse
+import subprocess
+from pathlib import Path
+
+AGENT_DIR = Path(".agent")
+PID_FILE = AGENT_DIR / "preview.pid"
+LOG_FILE = AGENT_DIR / "preview.log"
+
+def get_project_root():
+    return Path(".").resolve()
+
+def is_running(pid):
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError:
+        return False
+
+def get_start_command(root):
+    pkg_file = root / "package.json"
+    if not pkg_file.exists():
+        return None
+    
+    with open(pkg_file, 'r') as f:
+        data = json.load(f)
+    
+    scripts = data.get("scripts", {})
+    if "dev" in scripts:
+        return ["npm", "run", "dev"]
+    elif "start" in scripts:
+        return ["npm", "start"]
+    return None
+
+def start_server(port=3000):
+    if PID_FILE.exists():
+        try:
+            pid = int(PID_FILE.read_text().strip())
+            if is_running(pid):
+                print(f"⚠️  Preview already running (PID: {pid})")
+                return
+        except:
+            pass # Invalid PID file
+
+    root = get_project_root()
+    cmd = get_start_command(root)
+    
+    if not cmd:
+        print("❌ No 'dev' or 'start' script found in package.json")
+        sys.exit(1)
+    
+    # Add port env var if needed (simple heuristic)
+    env = os.environ.copy()
+    env["PORT"] = str(port)
+    
+    print(f"🚀 Starting preview on port {port}...")
+    
+    with open(LOG_FILE, "w") as log:
+        process = subprocess.Popen(
+            cmd,
+            cwd=str(root),
+            stdout=log,
+            stderr=log,
+            env=env,
+            shell=True # Required for npm on windows often, or consistent path handling
+        )
+    
+    PID_FILE.write_text(str(process.pid))
+    print(f"✅ Preview started! (PID: {process.pid})")
+    print(f"   Logs: {LOG_FILE}")
+    print(f"   URL: http://localhost:{port}")
+
+def stop_server():
+    if not PID_FILE.exists():
+        print("ℹ️  No preview server found.")
+        return
+
+    try:
+        pid = int(PID_FILE.read_text().strip())
+        if is_running(pid):
+            # Try gentle kill first
+            os.kill(pid, signal.SIGTERM) if sys.platform != 'win32' else subprocess.call(['taskkill', '/F', '/T', '/PID', str(pid)])
+            print(f"🛑 Preview stopped (PID: {pid})")
+        else:
+            print("ℹ️  Process was not running.")
+    except Exception as e:
+        print(f"❌ Error stopping server: {e}")
+    finally:
+        if PID_FILE.exists():
+            PID_FILE.unlink()
+
+def status_server():
+    running = False
+    pid = None
+    url = "Unknown"
+    
+    if PID_FILE.exists():
+        try:
+            pid = int(PID_FILE.read_text().strip())
+            if is_running(pid):
+                running = True
+                # Heuristic for URL, strictly we should save it
+                url = "http://localhost:3000" 
+        except:
+            pass
+            
+    print("\n=== Preview Status ===")
+    if running:
+        print(f"✅ Status: Running")
+        print(f"🔢 PID: {pid}")
+        print(f"🌐 URL: {url} (Likely)")
+        print(f"📝 Logs: {LOG_FILE}")
+    else:
+        print("⚪ Status: Stopped")
+    print("===================\n")
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("action", choices=["start", "stop", "status"])
+    parser.add_argument("port", nargs="?", default="3000")
+    
+    args = parser.parse_args()
+    
+    if args.action == "start":
+        start_server(int(args.port))
+    elif args.action == "stop":
+        stop_server()
+    elif args.action == "status":
+        status_server()
+
+if __name__ == "__main__":
+    main()