# Project Constitution — main-awf Đây là Hiến pháp của dự án platform main-awf. Mọi hoạt động lập trình và thay đổi mã nguồn của AI trên dự án này đều phải tuân thủ nghiêm ngặt các nguyên tắc dưới đây. Đối với các dự án của người dùng, hiến pháp sẽ được khởi tạo dựa theo file template [CONSTITUTION.template.md](templates/CONSTITUTION.template.md). --- ## TẦNG 1: Tầm nhìn & Mục tiêu Cốt lõi (Immutable Vision & Core Goals) _Định nghĩa lý do tồn tại của dự án. AI tuyệt đối không được đưa ra các đề xuất đi ngược lại triết lý này._ ### 1. Sứ mệnh & Tầm nhìn (Mission & Vision) - **Tầm nhìn**: AWKit là "Single Source of Truth" và là hệ thống điều phối Agent lập trình tự trị tối giản, tốc độ cao, và có độ tin cậy tuyệt đối. - **Triết lý phát triển**: **Pragmatic & Symphony-First**. AI không hoạt động đơn lẻ mà là một phần trong dàn hợp xướng (Symphony), phối hợp nhịp nhàng giữa điều phối (Gemini Flash), lập kế hoạch (Claude Fable), và thực thi (Qwen/Codex). ### 2. Mục tiêu Bất biến (Core Goals) - **Developer-Centric**: Mọi tính năng, lệnh CLI hoặc giao diện TUI đều phải trực quan, dễ dùng và giảm thiểu cognitive load (tải nhận thức) của nhà phát triển. - **Zero-Drift Integrity**: Đảm bảo trạng thái giữa Thư mục dự án cục bộ (`main-awf/`) và Thư mục Runtime (`~/.gemini/antigravity/`) luôn được đồng bộ và kiểm soát rõ ràng qua các lệnh `status`, `sync`, `install`, và `harvest`. - **Cost & Token Efficiency**: Tối ưu hóa việc sử dụng tài nguyên ngữ cảnh (context window). Sử dụng spec digest và phân rã nhiệm vụ nhỏ để tiết kiệm chi phí và tăng tốc độ phản hồi. - **Multi-Platform Support**: Hỗ trợ chạy ổn định và tối ưu trên đa nền tảng bao gồm macOS, Linux và Windows. Tránh các lệnh shell Unix-only hoặc đường dẫn tuyệt đối cứng mà không có giải pháp thay thế tương thích (xử lý dấu phân cách đường dẫn và tương thích với CMD/PowerShell). - **Resource & Token Optimization**: Tối ưu hóa dung lượng bộ nhớ runtime (giải phóng tiến trình nền, dọn dẹp bộ nhớ đệm) và tối ưu hóa lượng token ngữ cảnh (nén lịch sử, sử dụng spec digest và phân rã nhiệm vụ nhỏ) để tiết kiệm tài nguyên. - **Multi Sub-Agent Coordination**: Vận hành hiệu quả cơ chế phân rã và điều phối giữa nhiều sub-agent (logical roles: reasoning, runner, designer, audit), phân giải chính xác alias thành physical model để phân bổ công việc tối ưu nhất. - **Self-Aware State & Deterministic Navigation**: Agent luôn tự nhận thức trạng thái thực tế của nhiệm vụ (State > Logic), tự khôi phục ngữ cảnh (Context Recovery) từ `task.md`, `implementation_plan.md`, và `nmem` ở đầu turn, đảm bảo luôn biết rõ mình đang ở gate nào và bước tiếp theo cần làm gì. --- ## TẦNG 2: Giới hạn Cứng Bất biến (Hard Boundaries - 100% Bắt buộc) _Các quy tắc biên kỹ thuật và an toàn không được phép vi phạm dưới bất kỳ hình thức nào. Nếu AI phát hiện vi phạm, hệ thống phải dừng lại lập tức (Gate 0 Failure)._ ### 1. An toàn & Bảo mật (Safety & Credentials) - **Tuyệt đối KHÔNG lưu trữ cứng credentials**: Tất cả API Keys, Tokens, Passwords bắt buộc phải đi qua `.env` hoặc hệ thống quản lý config nội bộ (`model-registry.mjs`, `~/.awkit/config.json`). - **Khóa hành động phá hủy (Destructive Actions Lock)**: Nghiêm cấm chạy tự động hoặc đề xuất các lệnh gây mất mát dữ liệu (`rm -rf` diện rộng, `git reset --hard`, `force push` đè nhánh chính, hoặc xóa database không có điều kiện `WHERE`) mà không có sự xác nhận thủ công (Double-Confirm) từ người dùng. ### 2. Tính toàn vẹn của Kiến trúc (Architectural Integrity) - **Symphony Task Schema**: Không tự ý thay đổi cấu trúc dữ liệu của các task Symphony (trong database hoặc file json) nếu không có sự thống nhất từ trước. - **No Unrelated Code Churn**: Khi sửa lỗi hoặc thêm tính năng, chỉ chỉnh sửa trong phạm vi scope được yêu cầu. Không tự ý refactor lại các file/module khác đang chạy ổn định. - **Preserve Comments**: Không xóa các comment giải thích nghiệp vụ, tài liệu API, docstrings hoặc các ký hiệu đánh dấu đặc biệt của dự án cũ trừ khi đoạn code liên quan bị loại bỏ hoàn toàn. --- ## TẦNG 3: Vùng Dao động & Linh hoạt (Soft Boundaries - Flex Space) _Những khu vực cho phép AI và Developer linh hoạt đưa ra quyết định tối ưu, thử nghiệm giải pháp mới hoặc cấu hình theo nhu cầu thực tế mà không cần xin phép trước._ ### 1. Phân bổ Mô hình & Định tuyến CLI (Dynamic Model Routing) - **Model Fallbacks**: Thứ tự ưu tiên và danh sách mô hình thực thi (Runner/Planner) có thể thay đổi linh hoạt tùy thuộc vào hạn ngạch (quota) API hoặc hiệu năng thực tế. AI được tự động chọn model ưu tiên tiếp theo trong danh sách cấu hình. - **Mức độ Abstraction (Ponytail Ladder)**: AI có thể tự do lựa chọn giải pháp viết mã từ đơn giản (stdlib) đến phức tạp (thêm dependency có sẵn) miễn là đáp ứng tiêu chí tối giản và dễ bảo trì. ### 2. Giao diện & Trải nghiệm Trực quan (UI/UX Styling) - **Visual Presentation**: Cách bố trí màu sắc, ký tự biểu tượng (emojis), bố cục của bảng Kanban hoặc giao diện TUI có thể được điều chỉnh linh hoạt để đạt tính thẩm mỹ cao nhất mà không cần tuân theo một khuôn mẫu cứng nhắc. - **Helper Functions & Local Refactoring**: AI được phép tạo thêm các hàm bổ trợ cục bộ (local helper functions) trong phạm vi file đang sửa để giữ mã nguồn sạch sẽ và tránh lặp code, miễn là không thay đổi giao diện API public (API Signature).