@damphuquy/agent-init 1.4.0 → 1.4.2

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

@@ -0,0 +1,143 @@
+# Quyết Định Kỹ Thuật (Decision): [DEC-ID] [Task ID]
+
+<technical_decision task_id="[TASK-ID]" dec_id="[DEC-ID]" version="1.0" framework="RIPER-5">
+
+<!-- GIAI ĐOẠN CHỈ ĐỌC (READ-ONLY). Đề xuất các phương án. Không tự ý quyết định khi chưa có kỹ sư duyệt. -->
+<decision_status>
+  <phase>INNOVATE</phase>
+  <mode>READ-ONLY</mode>
+  <decision_owner></decision_owner>
+  <last_updated></last_updated>
+</decision_status>
+
+---
+
+## 1. Ngữ Cảnh (Context)
+
+<context>
+  <task>[Liên kết tới task.md hoặc Task ID]</task>
+  <research_artifact>[Liên kết tới research.md]</research_artifact>
+  <constraints>
+    [Các ràng buộc chính từ khảo sát làm thu hẹp không gian giải pháp.]
+  </constraints>
+</context>
+
+---
+
+## 2. Vấn Đề Cần Quyết Định (Decision Required)
+
+<decision_question>
+  [Tuyên bố chính xác điều cần quyết định. Một câu hỏi trọng tâm cho mỗi artifact quyết định.]
+</decision_question>
+
+---
+
+## 3. Các Phương Án Đề Xuất (Options)
+
+<options>
+
+  <option id="A">
+    <approach>[Hướng tiếp cận triển khai tổng quan]</approach>
+    <advantages>-</advantages>
+    <disadvantages>-</disadvantages>
+    <complexity>LOW | MEDIUM | HIGH</complexity>
+    <compatibility>[Tác động tương thích ngược]</compatibility>
+    <concurrency_transaction_risk>[Race conditions, tranh chấp khóa lock, độ phức tạp rollback]</concurrency_transaction_risk>
+    <testability>[Mức độ thuận tiện khi viết test kiểm chứng phương án này]</testability>
+    <maintainability>[Gánh nặng bảo trì dài hạn]</maintainability>
+  </option>
+
+  <option id="B">
+    <approach>[Hướng tiếp cận triển khai tổng quan]</approach>
+    <advantages>-</advantages>
+    <disadvantages>-</disadvantages>
+    <complexity>LOW | MEDIUM | HIGH</complexity>
+    <compatibility>[Tác động tương thích ngược]</compatibility>
+    <concurrency_transaction_risk>[Race conditions, tranh chấp khóa lock, độ phức tạp rollback]</concurrency_transaction_risk>
+    <testability>[Mức độ thuận tiện khi viết test kiểm chứng phương án này]</testability>
+    <maintainability>[Gánh nặng bảo trì dài hạn]</maintainability>
+  </option>
+
+  <option id="C">
+    <approach>[Hướng tiếp cận triển khai tổng quan]</approach>
+    <advantages>-</advantages>
+    <disadvantages>-</disadvantages>
+    <complexity>LOW | MEDIUM | HIGH</complexity>
+    <compatibility>[Tác động tương thích ngược]</compatibility>
+    <concurrency_transaction_risk>[Race conditions, tranh chấp khóa lock, độ phức tạp rollback]</concurrency_transaction_risk>
+    <testability>[Mức độ thuận tiện khi viết test kiểm chứng phương án này]</testability>
+    <maintainability>[Gánh nặng bảo trì dài hạn]</maintainability>
+  </option>
+
+</options>
+
+---
+
+## 4. Ma Trận Đánh Đổi (Trade-off Matrix)
+
+<tradeoff_matrix>
+
+| Tiêu chí | A | B | C |
+|---|:---:|:---:|:---:|
+| Khả năng tương thích | | | |
+| Độ phức tạp | | | |
+| Mức độ rủi ro | | | |
+| Khả năng kiểm thử | | | |
+| Khả năng bảo trì | | | |
+
+<!-- Thang điểm: 1 (kém) → 5 (xuất sắc) -->
+</tradeoff_matrix>
+
+---
+
+## 5. Đề Xuất Của Agent (Recommendation)
+
+<recommendation>
+  [Phương án Agent đề xuất kèm lý do lập luận. Đây là đề xuất — kỹ sư con người sẽ quyết định.]
+</recommendation>
+
+---
+
+## 6. Quyết Định Của Kỹ Sư (Engineer Decision)
+
+<!-- Phần này BẮT BUỘC kỹ sư con người phải điền trước khi Gate 1 được thông qua -->
+<engineer_decision>
+  <selected_option></selected_option>
+  <rationale></rationale>
+  <rejected_alternatives>
+    - Phương án [X]: [Lý do từ chối]
+  </rejected_alternatives>
+</engineer_decision>
+
+---
+
+## 7. Ràng Buộc Phái Sinh Từ Quyết Định Này (Constraints Created)
+
+<constraints_created>
+  [Liệt kê các ràng buộc mới lên khâu triển khai sẽ chuyển tiếp vào plan.md]
+  -
+</constraints_created>
+
+---
+
+## 8. Bằng Chứng Còn Cần Xác Minh (Evidence Still Required)
+
+<evidence_required>
+  [Bất kỳ sự thật nào chưa được khẳng định cần xác minh trong giai đoạn Plan hoặc Execute]
+  -
+</evidence_required>
+
+---
+
+## Gate 1 — Phê Duyệt Quyết Định (Decision Approved)
+
+<gate id="G1">
+  - [ ] Toàn bộ phương án đã được trình bày và phân tích đánh đổi.
+  - [ ] Kỹ sư đã xem xét các phương án.
+  - [ ] Phương án do kỹ sư chọn đã được ghi nhận ở trên.
+  - [ ] Không còn quyết định nghiệp vụ / schema / bảo mật nào đang bỏ ngỏ.
+  <approved_by></approved_by>
+  <approved_date></approved_date>
+</gate>
+
+</technical_decision>

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

@@ -0,0 +1,79 @@
+# Biên Bản Bàn Giao (Handoff): [TASK-ID]
+
+<handoff task_id="[TASK-ID]" version="2.0" framework="RIPER-5">
+
+<!-- Tóm tắt bàn giao cuối cùng. Cố tình thiết kế ngắn gọn. Không lặp lại các chi tiết dài dòng trong research/plan/review. -->
+<!-- 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ì? -->
+
+<handoff_status>
+  <review_decision>PASS</review_decision>  <!-- Bắt buộc phải là PASS trước khi bàn giao hợp lệ -->
+  <review_artifact>[Liên kết tới review.md]</review_artifact>
+  <completed_date></completed_date>
+</handoff_status>
+
+---
+
+## 1. Những Gì Đã Thay Đổi (What Changed)
+
+<what_changed>
+  [Tóm tắt súc tích về thay đổi hành vi đã hoàn thành. Tham chiếu tới mục tiêu trong task.md.]
+</what_changed>
+
+<main_changes>
+  - `duong/dan/toi/file` — [Bản chất thay đổi]
+</main_changes>
+
+---
+
+## 2. Lý Do Thay Đổi (Why)
+
+<why>
+  [Lập luận kỹ thuật hoặc nghiệp vụ. Một đoạn văn ngắn gọn. Liên kết tới task.md để xem toàn bộ ngữ cảnh.]
+</why>
+
+---
+
+## 3. Bằng Chứng Xác Minh (What Proves It)
+
+<evidence>
+
+| AC | Công cụ kiểm chứng (Verifier) | Kết quả |
+|---|---|---|
+| AC-1 | `[lệnh]` | PASS |
+| AC-2 | `[lệnh]` | PASS |
+| AC-3 | `[lệnh]` | PASS |
+
+<!-- Lệnh để tái lập kiểm chứng: -->
+```bash
+[Các lệnh kiểm chứng theo thứ tự]
+```
+
+</evidence>
+
+---
+
+## 4. Rủi Ro Tồn Đọng (What Remains Risky)
+
+<residual_risk>
+  [Bất kỳ rủi ro nào đã được chấp thuận tại Gate 3 mà người tiếp nhận cần lưu ý.]
+  - [Mục rủi ro — khuyến nghị giảm thiểu hoặc giám sát]
+</residual_risk>
+
+---
+
+## 5. Quyết Định & Giả Định (Decisions & Assumptions)
+
+<decisions_and_assumptions>
+  <!-- Chỉ liệt kê các quyết định ảnh hưởng đến người bảo trì tương lai. Chi tiết xem tại decision.md. -->
+  - [Tóm tắt quyết định — vì sao chọn giải pháp này thay vì các lựa chọn khác]
+</decisions_and_assumptions>
+
+---
+
+## 6. Hành Động Tiếp Theo (Next Action)
+
+<next_action>
+  [Những việc người hoặc giai đoạn tiếp theo nên làm, nếu có. Nếu không: NONE.]
+</next_action>
+
+</handoff>

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

@@ -0,0 +1,135 @@
+# Kế Hoạch Lát Cắt (Plan): [PLAN-ID] [Task ID]
+
+<execution_plan task_id="[TASK-ID]" plan_id="[PLAN-ID]" version="2.0" framework="RIPER-5">
+
+<!-- GIAI ĐOẠN LẬP KẾ HOẠCH (PLAN). Chỉ tạo/sửa artifact kế hoạch. Không sửa mã nguồn. -->
+<plan_status>
+  <phase>PLAN</phase>
+  <last_updated></last_updated>
+</plan_status>
+
+---
+
+## 1. Artifact Đầu Vào (Input Artifacts)
+
+<input_artifacts>
+  <task_spec>[Liên kết tới task.md]</task_spec>
+  <research>[Liên kết tới research.md]</research>
+  <decision>[Liên kết tới decision.md — DEC-ID, phương án đã chọn]</decision>
+</input_artifacts>
+
+---
+
+## 2. Ràng Buộc Thực Thi (Execution Constraints)
+
+<!-- Các ràng buộc này có tính pháp lý ràng buộc giai đoạn Execute. Agent không được vượt quá. -->
+<execution_constraints>
+  <allowed_files>
+    - `src/duong/dan/...` — [Lý do cho phép]
+    - `tests/duong/dan/...` — [Lý do cho phép]
+  </allowed_files>
+  <forbidden_files>
+    - `src/public-api/...` — [Không nằm trong phạm vi]
+    - `schema/...` — [Thay đổi schema yêu cầu phê duyệt riêng]
+  </forbidden_files>
+  <allowed_commands>
+    - `[lệnh chạy test]`
+    - `[lệnh chạy lint/format]`
+  </allowed_commands>
+  <restricted_operations>
+    - Không chạy migration database khi chưa có sự phê duyệt rõ ràng từ kỹ sư.
+    - Không thêm thư viện bên thứ ba mới khi chưa có sự phê duyệt rõ ràng từ kỹ sư.
+  </restricted_operations>
+  <required_approvals>
+    - [Liệt kê các điểm cần dừng xin phép giữa chừng, ví dụ: trước khi sửa module dùng chung]
+  </required_approvals>
+</execution_constraints>
+
+---
+
+## 3. Bảng Tóm Tắt Lát Cắt (Slice Summary)
+
+<slice_summary>
+
+| ID | Hành vi | Ranh giới | Danh sách file | AC | Verifier | Rủi ro | Mode | Rollback |
+|---|---|---|---|---|---|---|---|---|
+| S1 | | | | | | | | |
+| S2 | | | | | | | | |
+
+</slice_summary>
+
+---
+
+## 4. Chi Tiết Từng Lát Cắt (Slice Details)
+
+<slices>
+
+  <slice id="S1">
+    <objective>[Hành vi cụ thể mà lát cắt này mang lại]</objective>
+    <change>[Những gì cụ thể sẽ được chỉnh sửa]</change>
+    <allowed_files>
+      - `src/duong/dan/file.py`
+    </allowed_files>
+    <acceptance_criteria>
+      - [ ] AC-N: [Tiêu chí mà lát cắt này thỏa mãn]
+    </acceptance_criteria>
+    <verifier>
+      ```bash
+      # Lệnh kiểm chứng chứng minh lát cắt này hoạt động chính xác
+      ```
+    </verifier>
+    <expected_evidence>[Đầu ra mong muốn từ lệnh verifier]</expected_evidence>
+    <rollback_point>[Cách hoàn nguyên nếu lát cắt này thất bại — git stash / revert commit / flag]</rollback_point>
+    <stop_conditions>
+      - [Điều kiện bắt buộc dừng lại và yêu cầu con người hướng dẫn]
+    </stop_conditions>
+  </slice>
+
+  <!-- Sao chép khối <slice> này cho từng lát cắt bổ sung -->
+
+</slices>
+
+---
+
+## 5. Hợp Đồng Phạm Vi (Scope Contract)
+
+<scope_contract>
+  <allowed>
+    - [Những gì Agent được phép chỉnh sửa]
+  </allowed>
+  <forbidden>
+    - [Những gì Agent tuyệt đối không bao giờ được chạm vào trong kế hoạch này]
+  </forbidden>
+</scope_contract>
+
+---
+
+## 6. Ma Trận Kiểm Chứng (Verification Matrix)
+
+<!-- Đượ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 | | | |
+
+</verification_matrix>
+
+---
+
+## Gate 2 — Phê Duyệt Kế Hoạch (Plan Approved)
+
+<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.
+  - [ ] Đ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ê.
+  - [ ] Kỹ sư đã ký duyệt.
+  <approved_by></approved_by>
+  <approved_date></approved_date>
+</gate>
+
+</execution_plan>

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

@@ -0,0 +1,56 @@
+# Chương Trình Nhiều Giai Đoạn (Program): [PROG-ID] [Tên Chương Trình]
+
+<program_umbrella_plan version="2.0" framework="RIPER-5">
+
+<metadata>
+  <program_id>[PROG-ID]</program_id>
+  <lead>@engineering_lead</lead>
+  <target_timeline>[ví dụ: Sprint 1-3]</target_timeline>
+</metadata>
+
+## 1. Chiến Lược & Kết Quả Kỳ Vọng (Executive Strategy & Outcome)
+<strategy>
+  <target_outcome>
+    [Mục tiêu kiến trúc hoặc nghiệp vụ đo lường được ở cấp độ cao.]
+  </target_outcome>
+
+  <system_impact>
+    [Các subsystem bị ảnh hưởng, downstream services, hoặc chỉ tiêu hiệu năng.]
+  </system_impact>
+</strategy>
+
+---
+
+## 2. Phân Rã Giai Đoạn & Bán Kính Ảnh Hưởng (Phase Breakdown & Blast Radius)
+<phase_breakdown>
+  <phase number="1" id="phase-01">
+    <title>[Domain Models & Port Interfaces]</title>
+    <scope>`src/domain/`, `src/application/port_*`</scope>
+    <blast_radius level="LOW">Không ảnh hưởng dependency bên ngoài</blast_radius>
+    <status>NOT_STARTED</status>
+  </phase>
+
+  <phase number="2" id="phase-02">
+    <title>[Infrastructure Adapters & Persistence]</title>
+    <scope>`src/infrastructure/`</scope>
+    <blast_radius level="MEDIUM">Phụ thuộc vào hợp đồng domain của Phase 01</blast_radius>
+    <status>NOT_STARTED</status>
+  </phase>
+
+  <phase number="3" id="phase-03">
+    <title>[API Exposure & End-to-End Integration]</title>
+    <scope>`src/api/`</scope>
+    <blast_radius level="HIGH">Mở public HTTP endpoints và DTO contracts</blast_radius>
+    <status>NOT_STARTED</status>
+  </phase>
+</phase_breakdown>
+
+---
+
+## 3. Bất Biến Toàn Cục & Quy Tắc Cổng Phase (Global Invariants & Phase Gate Rules)
+<phase_gates>
+  <rule>Mỗi phase bắt buộc phải pass 100% các lệnh kiểm thử xác minh trước khi phase tiếp theo bắt đầu.</rule>
+  <rule>Không phase nào được đưa ra breaking change lên các public API hiện có khi chưa có sự chấp thuận trước.</rule>
+</phase_gates>
+
+</program_umbrella_plan>

package/templates/vi/process/_seeds/results-template.tsv.seed

@@ -0,0 +1,5 @@
+# Bảng Đăng Ký Đánh Giá Benchmark & Số Liệu Định Lượng (RIPER-5 Framework)
+# Khởi tạo dưới tên results.tsv trong thư mục task khi cần theo dõi hiệu năng, độ trễ latency, bộ nhớ hoặc điểm eval.
+iteration	timestamp	slice_id	metric_name	baseline	observed	unit	diff_pct	status	notes
+0	2026-01-01T00:00:00Z	baseline	p99_latency_ms	100.0	100.0	ms	0.0%	BASELINE	Đo lường baseline ban đầu
+1	2026-01-01T01:00:00Z	slice-01	p99_latency_ms	100.0	75.0	ms	-25.0%	PASS	Áp dụng tối ưu hóa slice 1

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

@@ -0,0 +1,149 @@
+# Biên Bản Nghiệm Thu (Review): [REVIEW-ID] [Task ID]
+
+<review_artifact task_id="[TASK-ID]" review_id="[REVIEW-ID]" version="1.0" framework="RIPER-5">
+
+<!-- GIAI ĐOẠN CHỈ ĐỌC (READ-ONLY). Có thể chạy lệnh kiểm thử. Không sửa mã nguồn trong lúc review. -->
+<review_status>
+  <phase>REVIEW</phase>
+  <mode>READ-ONLY</mode>
+  <reviewer></reviewer>
+  <last_updated></last_updated>
+</review_status>
+
+---
+
+## 1. Phạm Vi Nghiệm Thu (Review Scope)
+
+<review_scope>
+  <task_spec>[Liên kết tới task.md]</task_spec>
+  <plan>[Liên kết tới plan.md]</plan>
+  <diff>[Khoảng git diff hoặc liên kết PR]</diff>
+  <tests>[Đường dẫn các bộ test suite đã chạy]</tests>
+</review_scope>
+
+---
+
+## 2. Nghiệm Thu Hành Vi (Behavior Review)
+
+<behavior_review>
+
+| AC | Hành vi kỳ vọng | Hành vi thực tế | Bằng chứng | Kết quả |
+|---|---|---|---|---|
+| AC-1 | | | | PASS / FAIL |
+| AC-2 | | | | PASS / FAIL |
+| AC-3 | | | | PASS / FAIL |
+
+</behavior_review>
+
+---
+
+## 3. Nghiệm Thu Kiến Trúc (Architecture Review)
+
+<architecture_review>
+  <dependency_direction>[Chiều import/dependency có tuân thủ đúng quy tắc kiến trúc không?]</dependency_direction>
+  <boundary_violations>[Có lời gọi vượt ranh giới vi phạm phạm vi đã khai báo không?]</boundary_violations>
+  <unnecessary_abstraction>[Có lớp trừu tượng hay cấu trúc bắc cầu nào được thêm vào mà không có lý do không?]</unnecessary_abstraction>
+  <unrelated_refactor>[Có thay đổi refactor nào không bắt nguồn từ đặc tả task không?]</unrelated_refactor>
+</architecture_review>
+
+---
+
+## 4. Nghiệm Thu Dữ Liệu (Data Review)
+
+<data_review>
+  <transaction>[Ranh giới transaction đã đúng chưa? Có nguy cơ partial commit không?]</transaction>
+  <consistency>[Tính nhất quán dữ liệu có được đảm bảo khi có ghi đồng thời?]</consistency>
+  <concurrency>[Xung đột race condition, tranh chấp khóa, kiểm soát optimistic locking?]</concurrency>
+  <migration>[Các thay đổi schema cơ sở dữ liệu có tương thích ngược không?]</migration>
+  <constraints>[Các ràng buộc database constraints có được tôn trọng không?]</constraints>
+</data_review>
+
+---
+
+## 5. Nghiệm Thu Bảo Mật (Security Review)
+
+<security_review>
+  <authentication>[Ngữ cảnh xác thực có được kiểm tra tại các điểm bắt buộc không?]</authentication>
+  <authorization>[Kiểm tra phân quyền đã được đặt đúng chỗ chưa?]</authorization>
+  <validation>[Validation và chuẩn hóa dữ liệu đầu vào đã đầy đủ chưa?]</validation>
+  <secrets>[Không có token, secret hoặc credential nào bị lộ trong code hay log?]</secrets>
+  <injection>[Các nguy cơ SQL/command injection đã được phòng chống triệt để chưa?]</injection>
+  <sensitive_logging>[Không có dữ liệu nhạy cảm PII bị ghi vào log hệ thống?]</sensitive_logging>
+</security_review>
+
+---
+
+## 6. Nghiệm Thu Hồi Quy (Regression Review)
+
+<regression_review>
+  <existing_behavior>[Các bài test cũ còn chạy pass không? Có bài test nào trước đây pass nay bị fail?]</existing_behavior>
+  <backward_compatibility>[Public API / schema có duy trì tương thích ngược không?]</backward_compatibility>
+  <existing_tests>[Có bài test có sẵn nào bị chỉnh sửa mà thiếu lý do chính đáng không?]</existing_tests>
+</regression_review>
+
+---
+
+## 7. Bảng Phát Hiện (Findings)
+
+<findings>
+
+| ID | Danh mục | Mức độ | Loại | Bằng chứng | File/Ký hiệu | Hành động yêu cầu |
+|---|---|---|---|---|---|---|
+| F-1 | Behavior | HIGH | Confirmed Defect | | | |
+
+<!-- Danh mục (Category): Behavior | Architecture | Data | Security | Regression | Scope -->
+<!-- Mức độ (Severity): CRITICAL | HIGH | MEDIUM | LOW | INFO -->
+<!-- Loại (Type): Confirmed Defect (Lỗi xác nhận) | Risk requiring validation (Rủi ro cần kiểm chứng) | Optional Improvement (Cải tiến tùy chọn) -->
+
+</findings>
+
+---
+
+## 8. Ma Trận Kiểm Chứng (Verification Matrix)
+
+<verification_matrix>
+
+| AC / Rủi ro | Công cụ kiểm chứng | Kết quả | Bằng chứng | Điểm chưa kiểm chứng |
+|---|---|---|---|---|
+| AC-1 | | PASS / FAIL | | |
+| AC-2 | | PASS / FAIL | | |
+| AC-3 | | PASS / FAIL | | |
+
+</verification_matrix>
+
+---
+
+## 9. Rủi Ro Tồn Đọng (Residual Risk)
+
+<residual_risk>
+  [Các rủi ro vẫn còn lại sau review. Bắt buộc phải được chấp nhận rõ ràng trước khi Gate 3 thông qua.]
+  -
+</residual_risk>
+
+---
+
+## 10. Quyết Định Nghiệm Thu (Review Decision)
+
+<review_decision>
+  <!-- Chọn một trong ba: PASS | CHANGES_REQUIRED | BLOCKED -->
+  <decision></decision>
+  <rationale></rationale>
+</review_decision>
+
+---
+
+## Gate 3 — Nghiệm Thu Đạt (Review Passed)
+
+<gate id="G3">
+  - [ ] Toàn bộ git diff đã được kiểm toán (không có thay đổi ngoài luồng).
+  - [ ] 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).
+  - [ ] Rủi ro tồn đọng đã được chấp nhận rõ ràng.
+  - [ ] Quyết định review: PASS.
+  - [ ] Sẵn sàng bàn giao (handoff).
+  <approved_by></approved_by>
+  <approved_date></approved_date>
+</gate>
+
+</review_artifact>