@damphuquy/agent-init 2.3.0 → 3.0.0

package/templates/vi/AGENTS.md

@@ -37,24 +37,32 @@
 <foundations>
   <!-- Trụ cột 1: Task & Specification -->
   <pillar id="task_spec" title="Task & Đặc tả (Specification)">
-    <rule>Nguồn sự thật duy nhất (Single Source of Truth): Tệp task đang thực thi trong [`process/features/active/{feature}/task.md`](process/features/) hoặc [`process/general-plans/active/{task}/task.md`](process/general-plans/) (khởi tạo từ [`process/_seeds/task-template.md.seed`](process/_seeds/task-template.md.seed)).</rule>
-    <rule>Khởi tạo qua Prompt & Lệnh Gạch Chéo (Prompt & Slash Command Initialization): Người dùng có thể yêu cầu tạo và chạy task trực tiếp bằng prompt hoặc tiền tố lệnh gạch chéo (Pseudo-Slash Commands). Agent tự động định tuyến thư mục và khởi tạo `task.md` từ [`process/_seeds/task-template.md.seed`](process/_seeds/task-template.md.seed):
-      - Cú pháp `/feature`, `/big-task`, `/epic` hoặc các từ khóa `big task`, `feature`, `big changes`: định tuyến vào `process/features/active/{task-slug}/task.md` (chế độ PAIR).
-      - Cú pháp `/task`, `/small-task`, `/bug` hoặc các từ khóa `small task`, `general changes`, `small changes`: định tuyến vào `process/general-plans/active/{task-slug}/task.md` (chế độ PAIR).
-      - Cú pháp `/hotfix`: định tuyến vào `process/general-plans/active/{task-slug}/task.md` và chạy chế độ DELEGATED.
+    <rule>Nguồn sự thật duy nhất (Single Source of Truth): Tệp task đang thực thi trong [`process/features/active/{feature}/task.md`](process/features/) (Full Track) hoặc [`process/general-plans/active/{task}/task-lite.md`](process/general-plans/) (Lite Track).</rule>
+    <rule>Cơ chế Định tuyến Đôi (Dual-Track Routing):
+      - **Full Track (7 artifacts):** Dành cho tính năng phức tạp, epic lớn, tái cấu trúc kiến trúc. Khởi tạo từ [`process/_seeds/task-template.md.seed`](process/_seeds/task-template.md.seed) tại `process/features/active/{task-slug}/`. Chuỗi: `task.md → research.md → decision.md → plan.md → state.md → review.md → handoff.md`.
+      - **Lite Track (1 artifact):** Dành cho tác vụ nhanh, sửa lỗi (bugfix), micro-tasks, và hotfix. Khởi tạo từ [`process/_seeds/task-lite.md.seed`](process/_seeds/task-lite.md.seed) tại `process/general-plans/active/{task-slug}/task-lite.md`. Gom toàn bộ spec, phạm vi file, kế hoạch cắt lát và cổng kiểm chứng vào duy nhất 1 file để triệt tiêu chi phí ngữ cảnh (token tax).</rule>
+    <rule>Khởi tạo qua Prompt & Lệnh Gạch Chéo (Prompt & Slash Command Initialization): Người dùng có thể yêu cầu tạo và chạy task trực tiếp:
+      - Cú pháp `/feature`, `/big-task`, `/epic` hoặc từ khóa `big task`, `feature`, `big changes`: định tuyến Full Track vào `process/features/active/{task-slug}/task.md` (chế độ PAIR).
+      - Cú pháp `/task`, `/small-task`, `/bug` hoặc từ khóa `small task`, `bug`: định tuyến Lite Track vào `process/general-plans/active/{task-slug}/task-lite.md` (chế độ PAIR).
+      - Cú pháp `/hotfix`: định tuyến Lite Track vào `process/general-plans/active/{task-slug}/task-lite.md` và chạy chế độ DELEGATED.
       - Cú pháp `/fast-track`, `/delegated`: chạy tự trị liên tục qua toàn bộ chu trình.
-      - Cú pháp `/update`: kiểm tra phiên bản mới của quy chuẩn chỉ dẫn (qua `instruction-version.json` và registry); nếu có phiên bản mới thì thực hiện cập nhật và bảo toàn cấu hình dự án, nếu không có phiên bản mới hơn thì thông báo "nothing changed".
-      Agent tự tạo thư mục, điền mục tiêu & tiêu chí AC từ prompt vào `task.md` và bắt đầu ngay pha RESEARCH.</rule>
-    <rule>Định nghĩa thay đổi thông qua Mục tiêu (Goal), Hành vi hiện tại (Current Behavior), Hành vi kỳ vọng (Expected Behavior), Bất biến (Invariants) và Ngoài phạm vi (`<out_of_scope>`).</rule>
-    <rule>Tiêu chí nghiệm thu (Acceptance Criteria - AC) phải rõ ràng, kiểm chứng được dưới dạng checkbox markdown (`- [ ]`).</rule>
-    <rule>Mỗi task đều có bản hợp đồng master (`task.md`) và chuỗi artifact hoàn chỉnh: `research.md → decision.md → plan.md → state.md → review.md → handoff.md`.</rule>
+      - Cú pháp `/sync`: thực thi `npx @damphuquy/agent-init sync` để ánh xạ `AGENTS.md` sang `.cursor/rules/`, `CLAUDE.md`, và `.windsurfrules`.
+      - Cú pháp `/verify-gate [G2|G3]`: kiểm tra git diff, đảm bảo không có file nào bị sửa ngoài `<allowed_files>`.
+      - Cú pháp `/update`: kiểm tra và nâng cấp phiên bản quy chuẩn chỉ dẫn (qua `instruction-version.json`); nếu đã ở bản mới nhất thì xuất ra "nothing changed".</rule>
+    <rule>Định nghĩa thay đổi thông qua Mục tiêu (Goal), Bất biến (Invariants), Hợp đồng phạm vi (`<scope_contract>`), và Tiêu chí nghiệm thu (AC).</rule>
   </pillar>
 
-  <!-- Trụ cột 2: Context Navigation -->
-  <pillar id="context" title="Điều hướng & Nạp ngữ cảnh (Context Navigation)">
+  <!-- Trụ cột 2: Context Navigation & Model Context Protocol (MCP) -->
+  <pillar id="context" title="Điều hướng ngữ cảnh & MCP">
     <rule>Chỉ thu thập ngữ cảnh tối thiểu đủ dùng (Minimum Sufficient Context). Tuyệt đối không quét toàn bộ repo hay tự ý refactor ngoài phạm vi.</rule>
     <rule>Tuân thủ thứ tự ưu tiên thông tin được định nghĩa trong [`.agents/behavior.md`](.agents/behavior.md).</rule>
     <rule>Định tuyến ngữ cảnh dự án thông qua [`process/context/all-context.md`](process/context/all-context.md).</rule>
+    <mcp_tools>
+      Khi môi trường có sẵn Model Context Protocol (MCP), agent phải ưu tiên sử dụng MCP tools:
+      - Database MCP: Truy vấn schema và dữ liệu trực tiếp, không giả định schema mò mẫm.
+      - Git MCP: Đọc log/diff chính xác, tránh parsing lệnh shell tự do.
+      - Browser/DevTools MCP: Khảo sát live DOM / cây accessibility khi nghiệm thu giao diện.
+    </mcp_tools>
   </pillar>
 
   <!-- Trụ cột 3: Engineering Harness & Guardrails -->
@@ -65,6 +73,12 @@
       # Node/TS: npm run test && npm run typecheck && npm run lint
       # Go:      go test ./... && go vet ./...
     </validation_commands>
+    <action_governance>
+      Agent vận hành dưới cơ chế kiểm soát và ngăn chặn vi phạm nghiêm ngặt:
+      - Chống vượt ranh giới (Anti-Escape): Tuyệt đối không sửa đổi file ngoài danh sách `<allowed_files>` hoặc cấu hình gốc dự án chưa được duyệt (`package.json`, CI workflow) trừ khi được chỉ định rõ trong `plan.md`.
+      - Danh sách cấm an toàn (Safety Blacklist): Tuyệt đối không thực thi các lệnh phá hủy (`git push -f`, `git reset --hard`, xóa đệ quy không giới hạn, `DROP TABLE`).
+      - Nghiệm thu phi triển khai (Non-Implementer Review): Người trực tiếp viết code không được tự ý đơn phương nghiệm thu; việc nghiệm thu bắt buộc phải qua thẩm định độc lập.
+    </action_governance>
     <architecture_guardrail>
       Clean Architecture & Dependency Injection cung cấp định hướng cấu trúc, KHÔNG PHẢI
       chỉ thị để làm phức tạp hóa quá mức các hàm tiện ích đơn giản.

package/templates/vi/instruction-version.json

@@ -1,13 +1,13 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "@damphuquy/agent-init",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "framework": "RIPER-5",
-  "frameworkVersion": "2.0.0",
+  "frameworkVersion": "3.0.0",
   "language": "vi",
   "description": "Tệp định danh và kiểm soát phiên bản quy chuẩn chỉ dẫn (instructions) cho AI Coding Agents và Workspace.",
-  "installedAt": "2026-09-08T00:00:00.000Z",
-  "updatedAt": "2026-09-08T00:00:00.000Z",
+  "installedAt": "2026-09-09T00:00:00.000Z",
+  "updatedAt": "2026-09-09T00:00:00.000Z",
   "manifest": {
     "core": [
       "AGENTS.md",
@@ -22,6 +22,7 @@
     "seeds": [
       "process/_seeds/_GUIDE.md",
       "process/_seeds/task-template.md.seed",
+      "process/_seeds/task-lite.md.seed",
       "process/_seeds/context-group.md.seed",
       "process/_seeds/decision-template.md.seed",
       "process/_seeds/plan-template.md.seed",

package/templates/vi/process/_seeds/_GUIDE.md

@@ -23,9 +23,18 @@
 <catalog>
 
   <seed type="task" path="task-template.md.seed">
-    Hợp đồng master và bản lưu vết trạng thái xuyên suốt toàn bộ vòng đời RIPER-5.
+    Hợp đồng master và bản lưu vết trạng thái xuyên suốt toàn bộ vòng đời RIPER-5 (Full Track: 7 artifacts).
     Bao gồm: Metadata kiểm soát task (working_mode PAIR/DELEGATED), Đặc tả (Spec), Ranh giới ngữ cảnh, Chiến lược kiểm chứng,
     Quyết định kỹ thuật, Kế hoạch thực thi RIPER-5 (kèm Gates G0–G3), và Ranh giới an toàn (Guardrails).
+    Khuyến nghị cho: Các tính năng phức tạp, tái cấu trúc kiến trúc, và Epic tại `process/features/`.
+  </seed>
+
+  <seed type="task-lite" path="task-lite.md.seed">
+    Hợp đồng tinh gọn gom vào duy nhất 1 artifact cho RIPER-5 Lite Track (1 artifact).
+    Bao gồm: Ý định, Ràng buộc bất biến, Hợp đồng phạm vi (<allowed_files>), Kế hoạch cắt lát tinh gọn,
+    và Cổng kiểm chứng nghiệm thu tổng hợp (G1/G2/G3).
+    Khuyến nghị cho: Tác vụ nhỏ, sửa lỗi (bugfix), tính năng nhỏ (micro-tasks), và hotfix tại `process/general-plans/`.
+    Giảm hơn 70% chi phí token và overhead khởi tạo.
   </seed>
 
   <seed type="research" path="context-group.md.seed">

package/templates/vi/process/_seeds/plan-template.md.seed

@@ -109,11 +109,11 @@
 <!-- Được điền trong và sau giai đoạn Thực thi (Execute) -->
 <verification_matrix>
 
-| AC / Rủi ro | Bài test / Lệnh | Bằng chứng kỳ vọng | Kết quả thực tế |
-|---|---|---|---|
-| AC-1 | | | |
-| AC-2 | | | |
-| AC-3 | | | |
+| AC / Rủi ro | Bài test / Lệnh | Bằng chứng kỳ vọng | Mức độ nghiêm ngặt (hard-mandatory / soft-mandatory / advisory) | Kết quả thực tế |
+|---|---|---|---|---|
+| AC-1 | | | hard-mandatory | |
+| AC-2 | | | hard-mandatory | |
+| AC-3 | | | advisory | |
 
 </verification_matrix>
 
@@ -124,6 +124,7 @@
 <gate id="G2">
   - [ ] Mọi lát cắt đều có verifier xác định.
   - [ ] Hợp đồng phạm vi (cho phép / cấm) đã được phê duyệt.
+  - [ ] Mức độ nghiêm ngặt thực thi đã được gán cho từng AC / mục kiểm chứng.
   - [ ] Điều kiện dừng đã được định nghĩa cho từng slice.
   - [ ] Điểm hoàn nguyên (rollback point) đã được định nghĩa cho từng slice.
   - [ ] Danh sách lệnh được phép đã được liệt kê.

package/templates/vi/process/_seeds/review-template.md.seed

@@ -7,6 +7,7 @@
   <phase>REVIEW</phase>
   <mode>READ-ONLY</mode>
   <reviewer></reviewer>
+  <reviewer_harness></reviewer_harness>  <!-- ví dụ: human-pair / independent-subagent / cross-model-harness -->
   <last_updated></last_updated>
 </review_status>
 
@@ -136,6 +137,7 @@
 
 <gate id="G3">
   - [ ] Toàn bộ git diff đã được kiểm toán (không có thay đổi ngoài luồng).
+  - [ ] Đã xác minh nghiệm thu độc lập (người thực hiện không phải là người nghiệm thu duy nhất).
   - [ ] Hoàn tất dọn dẹp vệ sinh: toàn bộ debug log, lệnh print tạm và file nháp scratch đã bị xóa.
   - [ ] Mọi bằng chứng yêu cầu đều tồn tại và được đính kèm.
   - [ ] Toàn bộ phát hiện đã được phân loại xử lý (Lỗi xác nhận đã sửa hoặc được chấp nhận rủi ro).

package/templates/vi/process/_seeds/task-lite.md.seed

@@ -0,0 +1,88 @@
+# Nhiệm Vụ Tinh Gọn: [TASK-ID] [Tiêu Đề Nhiệm Vụ]
+
+<task_lite version="3.0" framework="RIPER-5-Lite">
+
+<!-- ════════════════════════════════════════════
+     PHẦN 0 — ĐIỀU KHIỂN NHIỆM VỤ
+     ════════════════════════════════════════════ -->
+<task_control>
+  <track>LITE</track>  <!-- LITE: Artifact 1 file duy nhất cho tác vụ nhanh, sửa lỗi, micro-task -->
+  <status>ACTIVE</status>  <!-- ACTIVE | REVIEW | COMPLETED | CANCELLED -->
+  <priority>P2</priority>  <!-- P0=khẩn | P1=cao | P2=bình thường | P3=thấp -->
+  <working_mode>PAIR</working_mode>  <!-- PAIR (duyệt tại cổng) | DELEGATED (chạy tự trị liên tục) -->
+  <current_phase>PLAN</current_phase>  <!-- PLAN | EXECUTE | REVIEW -->
+  <owner>@engineer</owner>
+</task_control>
+
+---
+
+## 1. Ý Định & Bản Đặc Tả (Intent & Spec)
+
+<specification>
+  <goal>
+    [Mô tả rõ ràng mục tiêu sửa lỗi, cải tiến nhỏ, hoặc tính năng phụ trợ]
+  </goal>
+
+  <invariants>
+    - [Ràng buộc bất biến tuyệt đối KHÔNG được phá vỡ trong nhiệm vụ này]
+  </invariants>
+
+  <acceptance_criteria>
+    - [ ] AC-1: [Kết quả chức năng cụ thể có thể kiểm chứng được]
+    - [ ] AC-2: [Kiểm thử tự động hoặc lệnh lint vượt qua không có lỗi]
+  </acceptance_criteria>
+
+  <!-- Cổng Định Nghĩa Sẵn Sàng (DoR): Không bắt đầu code nếu bài toán hoặc file được sửa còn mơ hồ -->
+  <definition_of_ready>
+    - [ ] Mục tiêu và tiêu chí nghiệm thu rõ ràng, không giả định.
+    - [ ] Danh sách file được phép sửa ở Mục 2 đã được xác định.
+  </definition_of_ready>
+</specification>
+
+---
+
+## 2. Hợp Đồng Phạm Vi & Danh Sách Tệp Được Phép Sửa
+
+<scope_contract>
+  <allowed_files>
+    <file>[đường/dẫn/tuyệt/đối/hoặc/tương/đối/file1.ts]</file>
+    <file>[đường/dẫn/file1.test.ts]</file>
+  </allowed_files>
+
+  <forbidden_files>
+    <file>[các/file/nằm/ngoài/phạm/vi/nhiệm/vụ]</file>
+  </forbidden_files>
+</scope_contract>
+
+---
+
+## 3. Kế Hoạch Cắt Lát Thực Thi (Compact Slices)
+
+<execution_plan>
+  ### Slice 1: [Tiêu Đề Thay Đổi Cốt Lõi]
+  - **Hành động:** [Viết mã hoặc test gì]
+  - **Lệnh kiểm chứng (Verifier):** [ví dụ: npm test path/to/test.ts || pytest path/to/test.py]
+  - **Trạng thái:** [ ] PENDING / IN_PROGRESS / DONE
+
+  ### Slice 2 (Tùy chọn): [Thay Đổi Bổ Trợ / Tích Hợp]
+  - **Hành động:** [Viết mã hoặc test gì]
+  - **Lệnh kiểm chứng (Verifier):** [Lệnh thực thi kiểm thử]
+  - **Trạng thái:** [ ] PENDING / IN_PROGRESS / DONE
+</execution_plan>
+
+---
+
+## 4. Kiểm Thử Tổng Hợp & Cổng Chất Lượng
+
+<verification_gates>
+  <!-- Cổng G1/G2: Kiểm tra thiết kế & phạm vi (trước khi code) -->
+  - [ ] **Cổng G1/G2 (Kế hoạch được duyệt):** Danh sách allowed_files xác định rõ ràng, có verifier.
+
+  <!-- Cổng G3: Bằng chứng nghiệm thu (sau khi code xong) -->
+  - [ ] **Cổng G3 (Sẵn sàng nghiệm thu/handoff):**
+    - [ ] Các lệnh kiểm thử (verifier) thực thi thành công 100% (Zero lỗi).
+    - [ ] Kiểm tra `git diff` — KHÔNG chạm vào bất kỳ file nào ngoài `<allowed_files>`.
+    - [ ] Đã dọn sạch mọi log debug hoặc thay đổi ngoài ý muốn.
+</verification_gates>
+
+</task_lite>

package/templates/vi/process/_seeds/task-template.md.seed

@@ -53,6 +53,14 @@
     - [ ] AC-2: [Các trường hợp biên (edge cases), quy tắc kiểm tra hợp lệ hoặc xử lý lỗi]
     - [ ] AC-3: [Kiểm thử tự động được bổ sung/cập nhật và chạy pass 100%]
   </acceptance_criteria>
+
+  <!-- Cổng Định Nghĩa Sẵn Sàng (Definition-of-Ready - DoR) — Tư duy trước khi dispatch -->
+  <definition_of_ready>
+    - [ ] Mục tiêu và tiêu chí nghiệm thu rõ ràng, kiểm chứng được (không phải đoán mò).
+    - [ ] Ràng buộc bất biến và phạm vi loại trừ <out_of_scope> được tuyên bố tường minh.
+    - [ ] Các câu hỏi mở được giải quyết hoặc đưa vào decision.md (Không code phỏng đoán).
+    <!-- DỪNG LẠI: Nếu bất kỳ mục DoR nào chưa thỏa mãn, dừng lại và hỏi người dùng trước! -->
+  </definition_of_ready>
 </specification>
 
 ---

package/templates/vi/process/development-protocols/orchestration.md

@@ -98,4 +98,23 @@
   </rule>
 </coordination_and_recovery>
 
+---
+
+## 6. Giao Thức Đánh Giá Độc Lập & Đa Harness (Cross-Harness Review)
+
+<cross_harness_review>
+  <rule id="implementer_cannot_review">
+    Subagent hoặc harness đã trực tiếp viết mã triển khai TUYỆT ĐỐI KHÔNG được đóng vai trò là người phê duyệt duy nhất cho lát cắt đó.
+    Nhằm triệt tiêu thiên kiến xác nhận, hãy ủy quyền việc thẩm định các lát cắt phức tạp hoặc nhạy cảm bảo mật cho một subagent đánh giá độc lập, hoặc yêu cầu kỹ sư con người ký duyệt quality gate.
+  </rule>
+
+  <rule id="adversarial_verification">
+    Subagent đánh giá phải được giao nhiệm vụ chủ động tìm kiếm các trường hợp biên (edge cases), vi phạm tuân thủ và vi phạm phạm vi so với `<scope_contract>`, thay vì chỉ xác nhận thụ động tuyên bố thành công của người viết mã.
+  </rule>
+
+  <rule id="fresh_context_mandate">
+    Subagent đánh giá độc lập phải vận hành với ngữ cảnh sạch: chỉ nhận yêu cầu của task, git diff và lệnh kiểm thử mà không bị ảnh hưởng bởi nhật ký hội thoại hay các suy luận phỏng đoán trong vòng lặp triển khai.
+  </rule>
+</cross_harness_review>
+
 </orchestration_protocol>