@damphuquy/agent-init 1.3.0 → 1.4.1

package/templates/vi/.agents/guardrails.md

@@ -0,0 +1,113 @@
+# Ranh Giới An Toàn Của Agent (Guardrails)
+
+<agent_guardrails version="1.0">
+
+<description>
+  Ranh giới an toàn phổ quát cho quá trình thực thi của Agent: ngân sách thử lại (retry budget),
+  điều kiện kích hoạt dừng khẩn cấp (escalation triggers), điều kiện dừng (stop conditions) và cổng hoàn thành.
+  Độc lập với dự án — áp dụng cho mọi ngôn ngữ, framework hoặc toolchain.
+</description>
+
+---
+
+## 1. Ngân Sách Thử Lại (Retry Budget)
+
+<retry_budget max_attempts="3">
+  Tối đa 3 lần thử lại liên tiếp cho cùng một triệu chứng lỗi.
+
+  Quy tắc:
+  - Tuyệt đối không giấu lỗi bằng các cờ bỏ qua kiểm tra (ví dụ: `# type: ignore`, `eslint-disable`,
+    `@SuppressWarnings`) để vượt qua cổng một cách giả tạo.
+  - Ghi nhận mọi lần thất bại vào `state.md > <failure_memory>` với:
+    - failure signature (mô tả triệu chứng lỗi duy nhất)
+    - hypothesis tested (giả thuyết nguyên nhân đã đặt ra)
+    - experiment run (thử nghiệm đã thực hiện)
+    - result observed (kết quả quan sát thực tế)
+  - Nếu hết ngân sách thử lại: DỪNG LẠI (HALT), ghi vào `<open_decisions>` trong `task.md`,
+    và yêu cầu con người hướng dẫn xử lý.
+</retry_budget>
+
+---
+
+## 2. Điều Kiện Kích Hoạt Dừng Khẩn Cấp (Escalation & Stop Conditions)
+
+<escalation_triggers>
+  Dừng lại ngay lập tức và yêu cầu con người hướng dẫn nếu BẤT KỲ điều nào sau đây xảy ra:
+
+  1. Ngân sách thử lại đã cạn kiệt cho một lỗi lặp đi lặp lại.
+  2. Thay đổi cần thiết chạm vào Public API, database schema, hoặc chính sách bảo mật
+     chưa được khai báo trong kế hoạch đã duyệt.
+  3. Thay đổi cần thiết chạm vào tệp nằm ngoài phạm vi được định nghĩa trong `plan.md`.
+  4. Cần một quyết định nghiệp vụ hoặc chính sách chưa có trong `<approved_decisions>`.
+  5. Cần mở rộng phạm vi ra ngoài mục `<out_of_scope>` trong `task.md`.
+
+  Ngoại lệ: KHÔNG dừng nếu thay đổi đã được người dùng ủy quyền rõ ràng
+  trong prompt/spec, hoặc nếu đó là tệp test đi kèm bắt buộc hay cập nhật import.
+</escalation_triggers>
+
+---
+
+## 3. Cổng Hoàn Thành (Completion Gate)
+
+<completion_gate>
+  Một task CHỈ ĐƯỢC COI LÀ HOÀN THÀNH khi TẤT CẢ các điều sau đồng thời thỏa mãn:
+
+  1. Mọi Tiêu chí nghiệm thu (AC) trong `task.md` đều được kiểm chứng (`- [x]`) kèm
+     bằng chứng được ghi lại trong `review.md`.
+  2. Mọi lệnh kiểm tra tự động (như định nghĩa trong `AGENTS.md`) thực thi với
+     0 lỗi (zero errors) và 0 cảnh báo (zero warnings).
+  3. Gate 3 trong `review.md` được đánh dấu đạt và quyết định review là PASS.
+  4. Lệnh `git diff` cuối cùng không chứa bất kỳ sửa đổi ngoài luồng hay chưa được review nào,
+     đồng thời mọi mã debug tạm thời / artifact scratch đã được dọn sạch 100%.
+  5. Thư mục task được di chuyển sang `completed/` và tệp `handoff.md` đã được tạo.
+</completion_gate>
+
+---
+
+## 4. Bảo Toàn Tính Bất Biến (Invariant Preservation)
+
+<invariants>
+  - Tuyệt đối không ghi đè hoặc xóa nội dung đặc tả do con người viết trong `task.md`.
+  - Chỉ đánh dấu `- [x]` sau khi lệnh kiểm chứng tương ứng thực sự pass —
+    không bao giờ tích trước.
+  - Giữ các chỉnh sửa trong phạm vi subsystem đã khai báo trừ khi có yêu cầu
+    phối hợp liên hệ thống rõ ràng và đã được phê duyệt.
+</invariants>
+
+---
+
+## 5. Ranh Giới An Toàn Lệnh & Danh Sách Cấm Phá Hủy (Command Safety & Blacklist)
+
+<command_safety>
+  Agent TUYỆT ĐỐI KHÔNG BAO GIỜ thực thi các lệnh có tính phá hủy, không thể hoàn nguyên hoặc làm rò rỉ thông tin xác thực:
+
+  - **Thao tác Git:** Không bao giờ chạy `git push --force`, `git push -f`, `git reset --hard`,
+    hoặc `git clean -fdx` trừ khi được kỹ sư con người ủy quyền rõ ràng trong session hiện tại.
+  - **Xóa File Hệ Thống:** Không bao giờ chạy lệnh xóa đệ quy không giới hạn (ví dụ: `rm -rf /`,
+    `rm -rf ~`, `rm -rf .`) hoặc xóa các tệp nằm ngoài phạm vi task đang hoạt động.
+  - **DDL/DML Cơ Sở Dữ Liệu:** Không bao giờ chạy các thao tác phá hủy dữ liệu khi chưa có sự chấp thuận rõ ràng
+    (`DROP DATABASE`, `DROP TABLE`, `TRUNCATE`, hoặc câu lệnh `DELETE` thiếu mệnh đề `WHERE` cụ thể).
+  - **Bí Mật & Chứng Thư (Secrets):** Không bao giờ đọc, in ra màn hình, ghi log hoặc export nội dung
+    `.env*`, `*.pem`, `*.key`, SSH keys hoặc credential cloud vào artifact task hoặc cửa sổ chat.
+  - **Cô Lập Môi Trường:** Chỉ thực thi lệnh thông qua khung kiểm thử chỉ định
+    `<validation_commands>` hoặc trình quản lý gói chuẩn. Không bao giờ tải và chạy các script
+    nhị phân từ xa tùy tiện (`curl ... | bash`).
+</command_safety>
+
+---
+
+## 6. Giao Thức Dọn Dẹp & Giải Phóng Phiên (Housekeeping & Teardown)
+
+<housekeeping_protocol>
+  Trước khi đề nghị ký duyệt Gate 3 hoặc đánh dấu task là COMPLETE, Agent phải dọn dẹp toàn diện:
+
+  1. **Xóa Debug Tạm Thời:** Gỡ bỏ toàn bộ các dòng log tạm (`console.log`, `print()`,
+     `debugger`, `dump()`, `pprint()`, hoặc các đoạn code thử nghiệm bị comment lại) sinh ra trong lúc làm việc.
+  2. **Dọn Dẹp Scratch:** Xóa các tệp mock tạm, script test nháp và tệp SQLite / dump dữ liệu tạm sinh ra
+     trong vòng lặp thực thi.
+  3. **Làm Sạch Git Diff:** Chạy `git status` và `git diff` để đảm bảo chỉ có các tệp
+     có chủ đích nằm trong phạm vi đã thống nhất ở `plan.md` bị thay đổi.
+  4. **Chốt Trạng Thái:** Đảm bảo `state.md` được đồng bộ sạch sẽ và tạo tệp `handoff.md`.
+</housekeeping_protocol>
+
+</agent_guardrails>

package/templates/vi/AGENTS.md

@@ -0,0 +1,133 @@
+# Hướng dẫn Điều phối Agent trong Repository (RIPER-5 Framework)
+
+<agent_guidelines version="4.0">
+
+<overview>
+  Cấu hình điểm khởi đầu (Entry-point) cho các AI Agent trong subsystem/project này.
+  Thiết lập các cài đặt riêng của dự án và kết nối 2 tầng quy chuẩn dùng chung:
+  - **`.agents/`** — quy tắc điều khiển hành vi của Agent (behavior, guardrails, conventions)
+  - **`process/`** — quy trình thực thi task, chuỗi artifact và cơ sở tri thức dài hạn
+
+  Tệp này CHỈ chứa những gì đặc thù của dự án: lệnh kiểm thử/build,
+  hiệu chỉnh ranh giới kiến trúc và tham chiếu đường dẫn.
+</overview>
+
+---
+
+## 1. Tham chiếu Tầng Điều khiển Agent (.agents/)
+
+<agent_control_ref>
+  Các quy tắc điều khiển Agent dùng chung nằm trong [`.agents/`](.agents/README.md):
+
+  | Tệp | Phạm vi quản lý |
+  |-----|----------------|
+  | [`.agents/behavior.md`](.agents/behavior.md) | Khai báo chế độ (Mode), khởi động session, thứ tự ưu tiên ngữ cảnh |
+  | [`.agents/guardrails.md`](.agents/guardrails.md) | Ngân sách thử lại (Retry budget), điều kiện kích hoạt dừng khẩn cấp, cổng hoàn thành |
+  | [`.agents/conventions/naming.md`](.agents/conventions/naming.md) | Quy chuẩn đặt tên và vệ sinh cấu trúc mã nguồn |
+
+  Đọc các tệp này khi bắt đầu session. Chúng không yêu cầu chỉnh sửa riêng cho từng dự án.
+</agent_control_ref>
+
+---
+
+## 2. 4 Trụ cột Cốt lõi (Core Pillars)
+
+<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>Đị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>
+  </pillar>
+
+  <!-- Trụ cột 2: Context Navigation -->
+  <pillar id="context" title="Điều hướng & Nạp ngữ cảnh (Context Navigation)">
+    <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>
+  </pillar>
+
+  <!-- Trụ cột 3: Engineering Harness & Guardrails -->
+  <pillar id="harness" title="Khung kiểm thử & Ranh giới an toàn (Harness & Guardrails)">
+    <validation_commands>
+      # ── Tùy chỉnh theo dự án: điều chỉnh các lệnh sau phù hợp với toolchain của bạn ──
+      # Python:  uv run pytest && uv run mypy --strict . && uv run ruff check . && uv run ruff format --check .
+      # Node/TS: npm run test && npm run typecheck && npm run lint
+      # Go:      go test ./... && go vet ./...
+    </validation_commands>
+    <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.
+    </architecture_guardrail>
+  </pillar>
+</foundations>
+
+---
+
+## 3. Giao thức Vận hành RIPER-5 (Trụ cột 4: Vòng lặp)
+
+<riper5_protocol>
+
+  <!-- ─────────────────── RÀNG BUỘC TỪNG GIAI ĐOẠN ─────────────────── -->
+
+  <phase name="RESEARCH" order="1">
+    <constraint>CHỈ ĐỌC (READ-ONLY). Không chỉnh sửa mã nguồn.</constraint>
+    <constraint>Không tự ý ra quyết định triển khai.</constraint>
+    <constraint>Không tự ý chọn lựa kiến trúc.</constraint>
+    <output>Tạo/cập nhật `research.md`. Phân loại bằng chứng thành Đã xác nhận (Confirmed) / Quan sát thấy (Observed) / Giả thuyết (Hypothesized).</output>
+    <gate id="G0">Đánh dấu đạt tất cả Tiêu chí rời khỏi Khảo sát (Research Exit Criteria) trong `research.md` trước khi chuyển tiếp.</gate>
+  </phase>
+
+  <phase name="INNOVATE" order="2">
+    <constraint>CHỈ ĐỌC (READ-ONLY). Không chỉnh sửa mã nguồn.</constraint>
+    <constraint>Đề xuất 2–3 phương án khả thi kèm ma trận đánh đổi (Trade-off). KHÔNG tự ý đơn phương quyết định.</constraint>
+    <constraint>Tuyệt đối không tự ý quyết định Public API / DB schema / chính sách bảo mật / quy tắc nghiệp vụ khi chưa có sự phê duyệt của con người.</constraint>
+    <output>Tạo `decision.md`. Để trống phần `<engineer_decision>` — kỹ sư sẽ điền phần này.</output>
+    <gate id="G1">Gate 1 trong `decision.md` phải được kỹ sư kiểm tra và ký duyệt trước khi chuyển sang Plan.</gate>
+  </phase>
+
+  <phase name="PLAN" order="3">
+    <constraint>Chỉ tạo/sửa artifact lập kế hoạch. Không chỉnh sửa mã nguồn.</constraint>
+    <constraint>Mỗi lát cắt (slice) phải có công cụ kiểm chứng (verifier), bằng chứng kỳ vọng và điểm hoàn nguyên (rollback point).</constraint>
+    <constraint>Hợp đồng phạm vi (danh sách file được phép / cấm sửa) phải tường minh.</constraint>
+    <output>Tạo `plan.md`. Điền sẵn các tiêu đề của Ma trận Kiểm chứng (Verification Matrix).</output>
+    <gate id="G2">Gate 2 trong `plan.md` phải được kỹ sư kiểm tra và ký duyệt trước khi chuyển sang Execute.</gate>
+  </phase>
+
+  <phase name="EXECUTE" order="4">
+    <constraint>Chỉ đọc/ghi trong phạm vi file đã được phê duyệt trong `plan.md`.</constraint>
+    <constraint>Thực hiện từng lát cắt một. Chạy verifier sau mỗi slice. Kiểm tra diff sau mỗi slice.</constraint>
+    <constraint>Không refactor lan man. Không sửa các file bị cấm.</constraint>
+    <constraint>Cập nhật `state.md` ngay sau mỗi slice hoàn thành.</constraint>
+    <output>Mã nguồn + kiểm thử + cập nhật `state.md` kèm bằng chứng kiểm chứng.</output>
+  </phase>
+
+  <phase name="REVIEW" order="5">
+    <constraint>CHỈ ĐỌC (READ-ONLY). Có thể chạy các lệnh kiểm thử tự động.</constraint>
+    <constraint>Không sửa mã nguồn trong lúc review. Ghi nhận các phát hiện vào `review.md`.</constraint>
+    <constraint>Bao quát: hành vi (behavior), kiến trúc (architecture), dữ liệu (data), bảo mật (security), hồi quy (regression).</constraint>
+    <output>Tạo `review.md` với các phát hiện được phân loại theo danh mục/mức độ/loại và checklist Gate 3.</output>
+    <gate id="G3">Gate 3 trong `review.md` phải được ký duyệt trước khi bàn giao. Quyết định review phải là PASS.</gate>
+  </phase>
+
+  <!-- Quy tắc hành vi (khai báo mode, retry, escalation, cổng hoàn thành) →
+       xem .agents/behavior.md và .agents/guardrails.md -->
+
+</riper5_protocol>
+
+---
+
+## 4. Quy tắc Không gian Làm việc (Workspace Protocols)
+
+<workspace_rules>
+  <rule id="env">Thực thi mọi lệnh bên trong môi trường ảo / khung runtime được chỉ định.</rule>
+  <rule id="sync">Chỉ đánh dấu `- [x]` sau khi lệnh kiểm chứng tương ứng thực sự pass. Tuyệt đối không ghi đè đặc tả do con người viết.</rule>
+  <rule id="isolation">Giữ các chỉnh sửa trong phạm vi subsystem này trừ khi có yêu cầu phối hợp liên hệ thống rõ ràng.</rule>
+  <rule id="subagents">Việc phân công subagent phải tuân thủ [`process/development-protocols/orchestration.md`](process/development-protocols/orchestration.md).</rule>
+  <rule id="no_stale_context">Đọc lại các tệp liên quan sau khi mã nguồn trong repository thay đổi. Không dựa vào ngữ cảnh hội thoại đã cũ.</rule>
+  <rule id="command_safety">Không bao giờ chạy các lệnh phá hủy (force push, hard reset, rm -rf bừa bãi, DDL drop DB, đọc secrets). Xem .agents/guardrails.md.</rule>
+  <rule id="housekeeping">Dọn dẹp sạch sẽ toàn bộ debug log, artifact tạm (scratch) và kiểm tra git diff tinh gọn trước khi đề nghị Gate G3.</rule>
+</workspace_rules>
+
+</agent_guidelines>

package/templates/vi/process/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.tsv]
+indent_style = tab
+
+[*.md]
+trim_trailing_whitespace = false

package/templates/vi/process/README.md

@@ -0,0 +1,150 @@
+# Quy Trình & Điều Phối Task (RIPER-5 Framework)
+
+<process_orchestration version="3.0" framework="RIPER-5">
+
+<overview>
+  Trung tâm điều phối vận hành và mẫu chuẩn để quản lý các tác vụ kỹ thuật, điều phối thực thi AI Agent trong subsystem/project này. Mỗi task đang active là một không gian kỹ thuật độc lập khép kín với đầy đủ chuỗi artifact RIPER-5.
+</overview>
+
+---
+
+## 1. Cấu Trúc Thư Mục
+
+```text
+process/
+├── README.md                         # Hướng dẫn vận hành (tệp này)
+├── .editorconfig                     # Cấu hình định dạng chuẩn cho markdown, tsv, json
+├── _seeds/                           # Blueprints mẫu chuẩn (chỉ đọc)
+│   ├── _GUIDE.md                     # Danh mục mẫu, chuỗi artifact và lệnh khởi tạo
+│   ├── task-template.md.seed         # Hợp đồng master & lưu vết trạng thái RIPER
+│   ├── context-group.md.seed         # Artifact giai đoạn Research (Khảo sát)
+│   ├── decision-template.md.seed     # Artifact giai đoạn Innovate (Lưu vết Gate 1)
+│   ├── plan-template.md.seed         # Artifact giai đoạn Plan (Hợp đồng thực thi, Gate 2)
+│   ├── state-template.md.seed        # Bộ nhớ bền vững trong vòng lặp Execute
+│   ├── review-template.md.seed       # Artifact giai đoạn Review (Gate 3)
+│   ├── handoff-template.md.seed      # Tóm tắt bàn giao cuối cùng (ngắn gọn)
+│   ├── cancellation-template.md.seed # Biên bản hủy task lưu giữ tri thức
+│   ├── results-template.tsv.seed     # Bảng theo dõi số liệu benchmark & định lượng
+│   └── program-template.md.seed      # Bản thiết kế chương trình lớn nhiều giai đoạn
+├── context/                          # Cơ sở tri thức bền vững & router định tuyến
+│   ├── all-context.md                # Router định tuyến ngữ cảnh gốc
+│   ├── planning/all-planning.md      # Quy chuẩn lập kế hoạch & lát cắt dọc (vertical slice)
+│   └── tests/all-tests.md            # Kim tự tháp test, chính sách harness & quy ước mock
+├── development-protocols/            # Quy tắc kỹ thuật & harness thực thi
+│   ├── all-development-protocols.md  # Mục lục protocols
+│   ├── orchestration.md              # Quy tắc phân công subagent
+│   └── implementation-standards.md  # Tiêu chuẩn kiểu dữ liệu, linting và kiểm thử
+├── features/                         # Tính năng theo domain (≥5 files / ≥3 phases)
+│   ├── active/                       # Thư mục task đang làm: {CHG-ID}-{task-slug}/
+│   │   └── CHG-XXX-example/          # Mỗi task một thư mục riêng biệt
+│   │       ├── task.md               # Hợp đồng master & lưu vết trạng thái
+│   │       ├── research.md           # Kết quả khảo sát mã nguồn
+│   │       ├── decision.md           # Các phương án đề xuất (Innovate)
+│   │       ├── plan.md               # Kế hoạch lát cắt dọc chi tiết
+│   │       ├── state.md              # Bộ nhớ tiến độ vòng lặp thực thi
+│   │       ├── review.md             # Biên bản nghiệm thu kiểm thử
+│   │       ├── handoff.md            # Tóm tắt bàn giao
+│   │       ├── results.tsv           # (Tùy chọn) Theo dõi benchmark & metric
+│   │       └── cancelled.md          # (Nếu hủy) Lưu vết nguyên nhân & hoàn nguyên
+│   ├── completed/                    # Lưu trữ các task đã hoàn thành
+│   └── backlog/                      # Ghi chú task tồn đọng: {note_slug}_NOTE_{dd-mm-yy}.md
+└── general-plans/                    # Task độc lập, xuyên suốt, sửa bug nhanh (<5 files)
+    ├── active/
+    ├── completed/
+    └── backlog/
+```
+
+---
+
+## 2. Chuỗi Artifact RIPER-5 & Quy Trình Thực Thi
+
+Mỗi task tạo ra một chuỗi artifact tuần tự. Khởi tạo chúng từng bước khi task tiến triển:
+
+```mermaid
+flowchart TD
+    subgraph Init["0. Khởi tạo"]
+        Seed["task-template.md.seed"] -->|Khởi tạo| Task["task.md (Đặc tả & Tiêu chí AC)"]
+    end
+    subgraph R1["1. RESEARCH (Chỉ đọc)"]
+        Task --> Res["research.md"] --> G0{"Gate G0 (Tự động)"}
+    end
+    subgraph I2["2. INNOVATE (Chỉ đọc)"]
+        G0 --> Dec["decision.md (2-3 Phương án)"] --> G1{"Gate G1 (Kỹ sư duyệt)"}
+    end
+    subgraph P3["3. PLAN (Chỉ lập kế hoạch)"]
+        G1 --> Plan["plan.md (Lát cắt dọc)"] --> G2{"Gate G2 (Kỹ sư ký duyệt)"}
+    end
+    subgraph E4["4. EXECUTE (Đọc/Ghi theo phạm vi)"]
+        G2 --> Code["Thực thi từng Slice"] --> Test["Chạy Verifiers"] --> State["state.md (Bộ nhớ)"]
+    end
+    subgraph R5["5. REVIEW (Chỉ đọc)"]
+        State --> Rev["review.md (Kiểm toán diff)"] --> G3{"Gate G3 (Kỹ sư duyệt)"}
+    end
+    subgraph Done["6. HOÀN THÀNH"]
+        G3 --> Arch["Chuyển sang completed/"] --> Handoff["handoff.md"]
+    end
+```
+
+```text
+task.md          ← (luôn có) Hợp đồng master, trạng thái RIPER phase/gate, AC, decisions
+research.md      ← (Research) Luồng thực thi, bằng chứng, ranh giới hệ thống
+decision.md      ← (Innovate) Các phương án, bảng đánh đổi, Gate 1 — kỹ sư bắt buộc duyệt
+plan.md          ← (Plan) Các lát cắt, verifiers, hợp đồng phạm vi, Gate 2 — kỹ sư duyệt
+state.md         ← (Execute) Tiến độ từng slice, bộ nhớ lỗi, ngân sách thử lại
+review.md        ← (Review) Phát hiện kiểm toán, ma trận kiểm chứng, Gate 3
+handoff.md       ← (Complete) Tóm tắt bàn giao ngắn gọn
+```
+
+### Bảng Ánh Xạ Khái Niệm → Tệp Artifact
+
+| Khái niệm | Artifact |
+|---|---|
+| Task / Đặc tả | `task.md` |
+| Khảo sát / Ngữ cảnh | `research.md` |
+| Đề xuất / Quyết định | `decision.md` |
+| Kế hoạch lát cắt | `plan.md` |
+| Trạng thái vòng lặp | `state.md` |
+| Thực thi | mã nguồn + kiểm thử + `state.md` |
+| Nghiệm thu | `review.md` |
+| Bàn giao | `handoff.md` |
+| Hủy task | `cancelled.md` (lưu giữ tri thức khi hủy bỏ) |
+| Benchmark / Định lượng | `results.tsv` (theo dõi hiệu năng và số liệu đánh giá) |
+| Gate 1 | Phê duyệt trong `decision.md` |
+| Gate 2 | Phê duyệt trong `plan.md` |
+| Gate 3 | Phê duyệt trong `review.md` |
+| Harness / Chính sách | `AGENTS.md` + `development-protocols/` |
+
+---
+
+## 3. Các Giai Đoạn Vận Hành RIPER-5
+
+<operational_phases>
+  <phase order="1" name="Research">
+    CHỈ ĐỌC. Nạp đặc tả task; tuân theo `<information_priority>`; tạo `research.md`.
+    Phân loại bằng chứng: Confirmed (Đã xác nhận) / Observed (Quan sát) / Hypothesized (Giả thuyết).
+    Vượt qua Tiêu chí rời khỏi Khảo sát (Gate 0) trước khi chuyển tiếp.
+  </phase>
+
+  <phase order="2" name="Innovate">
+    CHỈ ĐỌC. Đề xuất 2–3 phương án kèm ma trận đánh đổi. Không tự ý đơn phương quyết định.
+    Tạo `decision.md`. Kỹ sư phê duyệt Gate 1.
+  </phase>
+
+  <phase order="3" name="Plan">
+    Chỉ tạo/sửa artifact kế hoạch — không sửa mã nguồn.
+    Phân rã thành các lát cắt dọc (vertical slices) kèm verifiers, điểm hoàn nguyên và hợp đồng phạm vi.
+    Tạo `plan.md`. Kỹ sư phê duyệt Gate 2.
+  </phase>
+
+  <phase order="4" name="Execute">
+    Chỉ đọc/ghi trong phạm vi đã duyệt từ `plan.md`.
+    Thực hiện từng lát cắt một. Chạy verifier sau mỗi slice. Cập nhật `state.md` sau mỗi slice.
+  </phase>
+
+  <phase order="5" name="Review">
+    CHỈ ĐỌC. Có thể chạy các lệnh kiểm thử xác minh. Không sửa mã nguồn.
+    Tạo `review.md` kèm các phát hiện. Gate 3 phải PASS trước khi bàn giao.
+  </phase>
+</operational_phases>
+
+</process_orchestration>

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

@@ -0,0 +1,170 @@
+# Cẩm Nang Blueprints & Seeds Mẫu (Seeds Guide)
+
+<seeds_guide version="2.0" framework="RIPER-5">
+
+<scope>
+  `_seeds/` là thư mục mẫu chuẩn chỉ đọc (read-only scaffolding).
+  Sao chép và khởi tạo các seed này khi tạo task mới, chương trình lớn hoặc nhóm ngữ cảnh.
+  Không bao giờ chỉnh sửa trực tiếp bên trong `_seeds/` — luôn luôn sao chép trước khi dùng.
+</scope>
+
+---
+
+## 1. Danh Mục Blueprints Mẫu
+
+<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.
+    Bao gồm: Metadata kiểm soát task, Đặ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).
+  </seed>
+
+  <seed type="research" path="context-group.md.seed">
+    Artifact của giai đoạn Khảo sát (Research). CHỈ ĐỌC trong lúc thực hiện.
+    Bao gồm: Hành vi hiện tại, Luồng thực thi, Các thành phần liên quan, Ranh giới hệ thống,
+    Test hiện có, Cấu hình/Runtime, Phân tích nguồn sự thật, Phân loại bằng chứng
+    (Confirmed / Observed / Hypothesized), Giả định, Danh sách file bị ảnh hưởng,
+    Quyết định mở, và Tiêu chí rời khỏi Khảo sát.
+  </seed>
+
+  <seed type="decision" path="decision-template.md.seed">
+    Artifact của giai đoạn Đề xuất giải pháp (Innovate). Bộ nhớ lưu vết Gate 1.
+    Bao gồm: Câu hỏi quyết định, Các phương án (A/B/C) kèm ma trận đánh đổi (Trade-off),
+    Khuyến nghị của Agent, Quyết định của Kỹ sư (bắt buộc con người điền), Ràng buộc phái sinh,
+    Bằng chứng còn cần xác minh, và Checklist Gate 1.
+  </seed>
+
+  <seed type="plan" path="plan-template.md.seed">
+    Artifact của giai đoạn Lập kế hoạch (Plan). Bản hợp đồng thực thi.
+    Bao gồm: Artifact đầu vào, Ràng buộc thực thi (file được phép/bị cấm, lệnh được phép),
+    Bảng tóm tắt lát cắt (Slice Summary), Chi tiết từng slice (mục tiêu, thay đổi cụ thể,
+    verifier, bằng chứng kỳ vọng, điểm hoàn nguyên rollback, điều kiện dừng),
+    Hợp đồng phạm vi (Scope Contract), Ma trận kiểm chứng, và Checklist Gate 2.
+  </seed>
+
+  <seed type="state" path="state-template.md.seed">
+    Bộ nhớ bền vững của vòng lặp Thực thi (Execute). Cập nhật ngay sau mỗi slice.
+    Bao gồm: Phase/Gate hiện tại, Tham chiếu task, Mục tiêu/Bất biến, Quyết định đã duyệt,
+    Các slice đã xong, Slice hiện tại, Git diff hiện tại, Bằng chứng kiểm chứng,
+    Bộ nhớ lỗi (failure memory: signature/hypothesis/experiment/result), Ngân sách thử lại,
+    Thay đổi phạm vi, Rủi ro mở, Hành động tiếp theo, và Kiểm tra độ tươi mới của ngữ cảnh.
+  </seed>
+
+  <seed type="review" path="review-template.md.seed">
+    Artifact của giai đoạn Nghiệm thu (Review). Tách biệt hoàn toàn với Handoff.
+    Bao gồm: Phạm vi review, Review hành vi, Review kiến trúc, Review dữ liệu,
+    Review bảo mật, Review hồi quy, Bảng phát hiện (findings: category/severity/type),
+    Ma trận kiểm chứng, Rủi ro tồn đọng (residual risk), Quyết định review, và Checklist Gate 3.
+  </seed>
+
+  <seed type="handoff" path="handoff-template.md.seed">
+    Artifact tóm tắt bàn giao cuối cùng. Cố tình thiết kế ngắn gọn.
+    Trả lời 4 câu hỏi: Đã thay đổi gì? Vì sao? Bằng chứng nào chứng minh? Còn rủi ro gì?
+    KHÔNG lặp lại chi tiết dài dòng từ các artifact research/plan/review.
+  </seed>
+
+  <seed type="program" path="program-template.md.seed">
+    Bản thiết kế chương trình lớn nhiều giai đoạn với kế hoạch tổng thể, phân rã phase,
+    danh mục bán kính ảnh hưởng (blast radius), và quy tắc cổng chuyển giao từng phase.
+  </seed>
+
+  <seed type="cancellation" path="cancellation-template.md.seed">
+    Biên bản hủy task. Lưu giữ kết quả khảo sát, lý do quyết định,
+    các prototype/test có thể tái sử dụng, và kiểm tra hoàn nguyên khi một task đang làm bị dừng giữa chừng.
+  </seed>
+
+  <seed type="results" path="results-template.tsv.seed">
+    Bảng đăng ký đánh giá số liệu benchmark và định lượng.
+    Dùng để theo dõi latency, throughput, bộ nhớ hoặc điểm đánh giá qua các vòng lặp và lát cắt dọc.
+  </seed>
+
+</catalog>
+
+---
+
+## 2. Chuỗi Artifact Trong Mỗi Task
+
+Mỗi task active đều tuân thủ chuỗi artifact sau:
+
+```text
+task.md         ← Hợp đồng master & lưu vết trạng thái RIPER
+research.md     ← Đầu ra giai đoạn Research (chế độ CHỈ ĐỌC)
+decision.md     ← Đầu ra giai đoạn Innovate, lưu vết Gate 1
+plan.md         ← Đầu ra giai đoạn Plan, hợp đồng thực thi, Gate 2
+state.md        ← Bộ nhớ tiến độ vòng lặp Execute (cập nhật sau mỗi slice)
+review.md       ← Đầu ra giai đoạn Review, Gate 3
+handoff.md      ← Tóm tắt bàn giao cuối cùng (ngắn gọn)
+```
+
+### Bảng Ánh Xạ Khái Niệm → Tệp Artifact
+
+| Khái niệm | Artifact |
+|---|---|
+| Task / Đặc tả | `task.md` |
+| Khảo sát / Ngữ cảnh | `research.md` |
+| Đề xuất / Quyết định | `decision.md` |
+| Kế hoạch lát cắt | `plan.md` |
+| Trạng thái vòng lặp | `state.md` |
+| Thực thi | mã nguồn + kiểm thử + `state.md` |
+| Nghiệm thu | `review.md` |
+| Bàn giao | `handoff.md` |
+| Gate 1 | Phê duyệt trong `decision.md` |
+| Gate 2 | Phê duyệt trong `plan.md` |
+| Gate 3 | Phê duyệt trong `review.md` |
+
+---
+
+## 3. Cấu Trúc Thư Mục Task Được Khuyến Nghị
+
+### Cấu Trúc Dự Án Đơn Chuẩn (Standard Single-Project)
+```text
+process/features/active/CHG-017-your-feature/
+├── task.md          ← khởi tạo từ task-template.md.seed (Đặc tả Master & AC)
+├── research.md      ← khởi tạo từ context-group.md.seed (Kết quả khảo sát)
+├── decision.md      ← khởi tạo từ decision-template.md.seed (Phương án Gate 1)
+├── plan.md          ← khởi tạo từ plan-template.md.seed (Hợp đồng thực thi Gate 2)
+├── state.md         ← khởi tạo từ state-template.md.seed (Bộ nhớ tiến độ)
+├── review.md        ← khởi tạo từ review-template.md.seed (Biên bản kiểm toán Gate 3)
+├── handoff.md       ← khởi tạo từ handoff-template.md.seed (Tóm tắt bàn giao)
+├── results.tsv      ← (Tùy chọn) khởi tạo từ results-template.tsv.seed (Metrics/Benchmarks)
+└── cancelled.md     ← (Nếu hủy task) khởi tạo từ cancellation-template.md.seed
+```
+
+### Cấu Trúc Monorepo / Đa Miền (Tùy Chọn)
+Khi làm việc trong Monorepo với các domain độc lập (ví dụ: `mobile-app`, `billing-service`), phân chia features theo domain:
+```text
+process/features/{domain-slug}/
+├── active/
+│   └── CHG-XXX-your-feature/
+├── backlog/
+└── completed/
+```
+
+Không nhất thiết phải tạo tất cả các artifact ngay từ đầu. Hãy tạo dần dần khi task tiến triển qua các giai đoạn RIPER.
+
+---
+
+## 4. Các Lệnh Khởi Tạo Mẫu (Copy Commands)
+
+```bash
+# Tạo thư mục task mới
+mkdir -p process/features/active/CHG-XXX-your-feature
+
+# Khởi tạo các seed cơ bản vào thư mục task
+cp process/_seeds/task-template.md.seed     process/features/active/CHG-XXX-your-feature/task.md
+cp process/_seeds/context-group.md.seed    process/features/active/CHG-XXX-your-feature/research.md
+cp process/_seeds/decision-template.md.seed process/features/active/CHG-XXX-your-feature/decision.md
+cp process/_seeds/plan-template.md.seed    process/features/active/CHG-XXX-your-feature/plan.md
+cp process/_seeds/state-template.md.seed   process/features/active/CHG-XXX-your-feature/state.md
+cp process/_seeds/review-template.md.seed  process/features/active/CHG-XXX-your-feature/review.md
+cp process/_seeds/handoff-template.md.seed process/features/active/CHG-XXX-your-feature/handoff.md
+
+# (Tùy chọn) Khi cần theo dõi hiệu năng hoặc số liệu benchmark:
+cp process/_seeds/results-template.tsv.seed process/features/active/CHG-XXX-your-feature/results.tsv
+
+# (Khi cần hủy bỏ một task đang dang dở):
+cp process/_seeds/cancellation-template.md.seed process/features/active/CHG-XXX-your-feature/cancelled.md
+```
+
+</seeds_guide>