hero-vibe-kit 0.1.0

package/templates/docs/vi/COMMUNICATION_PROTOCOL.md

@@ -0,0 +1,59 @@
+# Communication Protocol — Human ↔ AI
+
+> Hợp đồng giao tiếp giữa **người** (Product Owner / Dev) và **các agent AI** trong dự án. Áp dụng cho **mọi tương tác**, đặc biệt khi **làm rõ yêu cầu** (Phase 1). Là một phần bắt buộc của [AGENCY_WORKFLOW.md](./AGENCY_WORKFLOW.md).
+>
+> Vì sản phẩm này *là* một AI assistant, chất lượng làm rõ yêu cầu quyết định chất lượng sản phẩm — giao thức này nhằm loại bỏ hiểu lầm ngầm.
+
+## 1. Ngôn ngữ & phong cách
+- **Tiếng Việt** là ngôn ngữ mặc định khi trao đổi với User; **giữ nguyên thuật ngữ kỹ thuật tiếng Anh** (API, endpoint, prompt, token…).
+- Ngắn gọn, trực diện, không vòng vo. Trình bày phương án quan trọng kèm khuyến nghị rõ ràng.
+- Trích dẫn `file:line` khi nói về code.
+
+## 2. Nguyên tắc cốt lõi
+1. **No silent assumptions** — Không bao giờ tự bịa thông tin còn thiếu. Khi thiếu, hoặc **HỎI**, hoặc nêu **giả định tường minh** gắn nhãn `GIẢ ĐỊNH:` để User dễ bác bỏ.
+2. **Phân tầng độ chắc chắn** — Tách bạch rõ:
+   - ✅ **Chắc chắn** (đã đọc code/tài liệu, có bằng chứng)
+   - 🤔 **Suy đoán** (suy luận hợp lý nhưng chưa kiểm chứng)
+   - ❓ **Cần xác nhận** (phụ thuộc quyết định của User)
+3. **Sự thật trên sự đồng thuận** — AI phản biện khi thấy yêu cầu mâu thuẫn/rủi ro, không "gật cho xong". (Chiều ngược lại: khi nhận feedback, dùng skill `receiving-code-review` — kiểm chứng kỹ thuật, không đồng ý hình thức.)
+4. **Bằng chứng trước khẳng định** — Không tuyên bố "đã xong/đã pass" khi chưa chạy lệnh kiểm chứng (xem `verification-before-completion`).
+
+## 3. Giao thức làm rõ yêu cầu
+### 3.1. Phân loại câu hỏi
+| Loại | Định nghĩa | Cách xử lý |
+|------|-----------|-----------|
+| **Blocking** | Không có câu trả lời thì KHÔNG thể đi tiếp đúng hướng (vd: phạm vi, đối tượng dùng, ràng buộc cứng) | Phải hỏi & chờ User trả lời |
+| **Non-blocking** | Có giá trị mặc định hợp lý | AI **tự quyết theo default**, nêu rõ `GIẢ ĐỊNH:` đã dùng để User chỉnh sau |
+
+> Mục tiêu: không chặn tiến độ vì những thứ có default hợp lý; chỉ chặn ở những điều thực sự cần quyết định của người.
+
+### 3.2. Cách hỏi
+- **Câu hỏi độc lập** → gom lại hỏi một lượt qua **`AskUserQuestion`** (tối đa ~4 câu, mỗi câu có option + khuyến nghị).
+- **Câu hỏi thăm dò / phụ thuộc nhau** → hỏi **tuần tự, một câu mỗi lần** (theo skill `brainstorming`) để câu sau dựa trên câu trước.
+- Ưu tiên câu hỏi dạng lựa chọn hơn câu mở khi có thể.
+
+### 3.3. Kết thúc mỗi vòng làm rõ
+Mỗi lượt làm rõ phải khép lại bằng 3 mục:
+1. **Tóm tắt hiểu biết hiện tại** (1 đoạn ngắn — để User soi sai sót).
+2. **Câu hỏi còn mở** (blocking nào chưa trả lời).
+3. **Giả định đang giữ** (assumptions register — danh sách `GIẢ ĐỊNH:` đang dùng).
+
+## 4. Xác nhận, sign-off & sửa hiểu lầm
+- **Gate = Plan Mode thật**: chốt PRD/TDD qua `EnterPlanMode → ExitPlanMode`, không phải câu chữ "chờ duyệt".
+- **Đóng vòng khi hiểu sai (loop repair)**: khi User sửa/đính chính → AI **nhắc lại cách hiểu MỚI bằng lời của mình** và **chờ User xác nhận** trước khi tiếp tục. Không âm thầm "tự hiểu lại".
+- Sau khi User duyệt, coi đó là **commitment** — nếu muốn đổi, mở lại gate, không tự ý đổi hướng.
+
+## 5. Decision log & Assumptions register
+Mỗi feature ghi trong PRD (xem template):
+- **Decision Log**: `| Ngày | Câu hỏi/Vấn đề | Quyết định | Người quyết | Lý do |` — để sau này biết "vì sao hồi đó chọn thế".
+- **Assumptions Register**: danh sách giả định đang giữ + trạng thái (`chờ xác nhận` / `đã xác nhận` / `đã bác bỏ`).
+
+## 6. Quy tắc cho sub-agent (đa agent)
+- **Sub-agent KHÔNG giao tiếp trực tiếp với User.** Nếu thiếu thông tin / gặp quyết định cần người → **báo Main Agent**, Main Agent tổng hợp rồi mới hỏi User. Tránh nhiều agent hỏi loạn, mâu thuẫn.
+- Main Agent là **một cửa giao tiếp duy nhất** với User.
+- Prompt giao cho sub-agent phải **self-contained** (xem [TEAM_ROSTER.md](./TEAM_ROSTER.md)) — gồm cả các giả định/quyết định liên quan đã chốt với User.
+
+## 7. Liên quan
+- [AGENCY_WORKFLOW.md](./AGENCY_WORKFLOW.md) — Phase 1 áp dụng giao thức này.
+- [templates/PRD_AI_FEATURE.md](./templates/PRD_AI_FEATURE.md) — các chiều cần làm rõ cho feature AI.
+- [INTERACTION_PATTERNS.md](./INTERACTION_PATTERNS.md) — cách *sản phẩm* giao tiếp với end-user (khác với tài liệu này: đây là người↔AI trong quá trình phát triển).

package/templates/docs/vi/DEFINITION_OF_DONE.md

@@ -0,0 +1,60 @@
+# Definition of Done (DoD)
+
+> Tiêu chí hoàn thành **đo được**. Một thay đổi chỉ được coi là "xong" khi thỏa DoD của path tương ứng. Path do [AGENCY_WORKFLOW.md §1](./AGENCY_WORKFLOW.md#1-bảng-phân-loại-task--workflow-router) quyết định.
+
+## ⚙️ Placeholder cần điền khi chốt tech stack
+Stack chưa chốt — điền các giá trị sau ở PRD/TDD đầu tiên rồi cập nhật file này:
+
+| Biến | Giá trị | Ví dụ |
+|------|---------|-------|
+| `<TEST_CMD>` | lệnh chạy test | `npm test` / `pytest` |
+| `<LINT_CMD>` | lệnh lint + format check | `npm run lint` / `ruff check .` |
+| `<BUILD_CMD>` | lệnh build | `npm run build` / `—` |
+| `<COVERAGE_MIN>` | ngưỡng coverage tối thiểu | `80%` |
+| `<TYPECHECK_CMD>` | type check (nếu có) | `tsc --noEmit` / `mypy .` |
+
+---
+
+## Checklist theo path
+
+### Read-only (Q&A / Explain)
+- [ ] Trả lời đúng trọng tâm câu hỏi.
+- [ ] Có trích dẫn `file:line` cho mọi khẳng định về code.
+- [ ] Không tạo branch / không commit / không sửa file.
+
+### Fast path (Chore / Docs / Config / Bugfix nhỏ / Hotfix)
+- [ ] Đúng tiền tố branch ([BRANCHING.md](./BRANCHING.md)).
+- [ ] `<TEST_CMD>` xanh · `<LINT_CMD>` xanh · `<BUILD_CMD>` xanh.
+- [ ] **Bugfix/Hotfix:** có test tái hiện bug, đã chuyển từ ĐỎ → XANH; regression suite không hỏng.
+- [ ] **Chore/Docs:** không thay đổi hành vi runtime.
+- [ ] Commit theo Conventional Commits; MR mô tả ngắn gọn *what + why*.
+- [ ] Đã chạy `gitnexus_detect_changes` (khi đã có code) — phạm vi đúng dự kiến.
+- [ ] **Security (nhẹ):** không commit secret mới (xem [SECURITY_STANDARDS.md](./SECURITY_STANDARDS.md) §5). **Performance (nhẹ):** không gây hồi quy rõ rệt / không thêm N+1 ([PERFORMANCE_STANDARDS.md](./PERFORMANCE_STANDARDS.md) §4).
+
+### Standard path (Sửa logic / Refactor)
+Bao gồm toàn bộ Fast path, cộng thêm:
+- [ ] Đã qua **Gate** (Plan Mode) và User đã duyệt cách tiếp cận.
+- [ ] `gitnexus_impact` (upstream) đã chạy & **blast radius + mức rủi ro được báo cáo**; rủi ro HIGH/CRITICAL đã được User chấp thuận.
+- [ ] `<TYPECHECK_CMD>` xanh (nếu áp dụng).
+- [ ] **Refactor:** cùng bộ test pass trước & sau (hành vi không đổi); rename dùng `gitnexus_rename`, không find-replace tay.
+- [ ] **Sửa logic:** regression test cũ còn xanh + có test mới cho hành vi mới.
+- [ ] QA sub-agent đã review (`code-review`); `security-review` nếu chạm bề mặt nhạy cảm.
+- [ ] **Security (Standard):** input validation cho code chạm + kiểm quyền nếu chạm authz ([SECURITY_STANDARDS.md](./SECURITY_STANDARDS.md) §5). **Performance (Standard):** bench trước/sau cho hot-path; (AI) prompt caching còn nguyên ([PERFORMANCE_STANDARDS.md](./PERFORMANCE_STANDARDS.md) §4).
+
+### Full path (Feature mới)
+Bao gồm toàn bộ Standard path, cộng thêm:
+- [ ] **PRD** đã được duyệt (Gate 1) và có link trong ACTIVE_STATE.
+- [ ] **TDD** đã được duyệt (Gate 2): có threat model nhẹ + API/interface contract.
+- [ ] Coverage ≥ `<COVERAGE_MIN>` cho code mới.
+- [ ] Đáp ứng toàn bộ acceptance criteria trong PRD.
+- [ ] `security-review` đã chạy, không có finding mới chưa xử lý.
+- [ ] **Security standards (Full):** đạt [SECURITY_STANDARDS.md](./SECURITY_STANDARDS.md) §5; feature AI đã kiểm OWASP LLM Top 10 (§2) gồm ca lạm dụng.
+- [ ] **Performance standards (Full):** đạt budget [PERFORMANCE_STANDARDS.md](./PERFORMANCE_STANDARDS.md) §1; feature AI đạt token/latency ceiling §2; có số đo tải cho luồng chính.
+- [ ] **Handover:** CLAUDE.md cập nhật quyết định kiến trúc mới (nếu có); retro 3 dòng đã ghi; Serena memory cập nhật (con trỏ); task `completed` + ACTIVE_STATE cập nhật.
+
+---
+
+## Quy tắc bất biến (mọi path)
+1. **Không claim "đã xong/đã pass" mà chưa chạy lệnh kiểm chứng** — bằng chứng trước, khẳng định sau (`verification-before-completion`).
+2. **Test phải thực sự kiểm thử hành vi**, không phải test rỗng/mock toàn bộ để qua cho có.
+3. **ACTIVE_STATE.md được cập nhật** khi trạng thái công việc đổi.

package/templates/docs/vi/INTERACTION_PATTERNS.md

@@ -0,0 +1,58 @@
+# Interaction Patterns — Assistant ↔ End-User (Product Layer)
+
+> Thư viện **pattern giao tiếp của SẢN PHẨM với người dùng cuối**. Khác với [COMMUNICATION_PROTOCOL.md](./COMMUNICATION_PROTOCOL.md) (người↔AI trong lúc *phát triển*) — đây là cách *assistant đã build* nói chuyện với *end-user*.
+>
+> Là **tài sản dùng lại**: mỗi PRD feature AI (mục §3, §5, §8 của [template](./templates/PRD_AI_FEATURE.md)) tham chiếu các pattern ở đây thay vì thiết kế lại từ đầu. Ngưỡng/ chi tiết cụ thể (`<TBD>`) chốt ở từng PRD.
+
+## Nguyên tắc nền
+1. **Người dùng luôn nắm quyền kiểm soát** — assistant hỗ trợ, không tự ý thay người quyết định việc khó đảo ngược.
+2. **Minh bạch giới hạn** — nói rõ khi không chắc, không biết, hoặc không làm được; không bịa.
+3. **Chi phí lỗi định hình hành vi** — việc rủi ro thấp → cứ làm; rủi ro cao/khó đảo ngược → xác nhận trước.
+
+---
+
+## P1 — Clarification (làm rõ ý định)
+- **Khi nào hỏi lại:** intent mơ hồ, thiếu tham số bắt buộc, hoặc nhiều cách hiểu dẫn tới kết quả rất khác.
+- **Khi nào KHÔNG hỏi:** có default an toàn/rõ ràng → cứ làm và **nêu giả định đã dùng** ("Mình hiểu là X, nếu không đúng cho mình biết nhé").
+- **Cách hỏi:** một câu hỏi trọng tâm, kèm 2–4 lựa chọn nếu được; không tra tấn bằng chuỗi câu hỏi.
+- **Ngưỡng:** tối đa `<TBD>` câu trước khi đưa ra nỗ lực tốt nhất.
+
+## P2 — Confirmation (xác nhận trước hành động)
+- **Bắt buộc xác nhận** trước hành động: khó đảo ngược, ảnh hưởng dữ liệu/tiền/người khác, hoặc ra ngoài (gửi mail, public…).
+- **Không cần** với hành động đọc/không phá hủy.
+- Nêu rõ **việc sắp làm + hệ quả** rồi mới hỏi đồng ý.
+
+## P3 — Uncertainty / Low-confidence (thể hiện độ chắc)
+- Khi không chắc → **nói rõ mức độ chắc** + đề nghị kiểm chứng, thay vì khẳng định chắc nịch.
+- Trích nguồn/grounding khi có. Phân biệt "mình biết" vs "mình suy đoán".
+
+## P4 — Error & Graceful Degradation (lỗi & suy giảm mượt)
+- Lỗi → giải thích **bằng ngôn ngữ người dùng** (không nuốt lỗi, không đổ stack trace).
+- Ưu tiên **kết quả một phần + nêu phần thiếu** hơn là fail trắng.
+- Gợi ý bước tiếp theo / cách thử lại.
+
+## P5 — Refusal (từ chối an toàn)
+- Cấu trúc: **từ chối ngắn gọn + lý do + (nếu có) hướng thay thế hợp lệ**.
+- Giữ giọng tôn trọng, không phán xét; không tiết lộ chi tiết nội bộ về cách lọc.
+- Phân biệt "không được phép" vs "không làm được" vs "cần thêm thông tin".
+
+## P6 — Handoff to Human (chuyển người thật)
+- Khi nào escalate: vượt phạm vi, rủi ro cao, người dùng yêu cầu, hoặc lặp lại thất bại.
+- Chuyển kèm **tóm tắt ngữ cảnh** để người tiếp nhận không phải hỏi lại từ đầu.
+
+## P7 — Conversation Repair (sửa khi hiểu sai)
+- Người dùng nói "không phải vậy" → assistant **nhận lỗi gọn, nhắc lại cách hiểu mới, xác nhận** rồi mới tiếp.
+- Không lặp lại cùng câu trả lời sai; không phòng thủ.
+
+## P8 — Memory & Privacy (ghi nhớ & riêng tư)
+- Nói rõ assistant **nhớ gì / không nhớ gì**; cho người dùng cách xem/xoá.
+- Không phơi dữ liệu nhạy cảm trong phản hồi/log; tuân chính sách PII ở PRD §5.
+
+## P9 — Tone & Consistency (giọng điệu nhất quán)
+- Một persona thống nhất xuyên các feature (chốt ở [TEAM_ROSTER.md](./TEAM_ROSTER.md) §3 / PRD §4).
+- Ngắn gọn mặc định; chi tiết khi người dùng cần.
+
+---
+
+## Cách dùng
+Trong PRD feature AI: ở §3 (mơ hồ) trỏ **P1**; §5 (safety) trỏ **P5/P8**; §8 (fallback) trỏ **P4/P6/P7**; §4 (tone) trỏ **P9**. Mỗi pattern điền ngưỡng/chi tiết cụ thể cho feature đó.

package/templates/docs/vi/PERFORMANCE_STANDARDS.md

@@ -0,0 +1,31 @@
+# Performance Standards
+
+> Budget hiệu năng **đo được** cho {{PROJECT_NAME}}. Là một phần của [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md) và được xét ở **Phase 2 (đặt budget)** + **Phase 4 (kiểm)** trong [AGENCY_WORKFLOW.md](./AGENCY_WORKFLOW.md).
+>
+> Điền `<TBD>` theo yêu cầu sản phẩm khi chốt ở PRD/TDD đầu tiên.
+
+## 1. Budget chung (parameter hoá)
+- **Latency**: API p95 ≤ `<TBD>` ms, p99 ≤ `<TBD>` ms.
+- **Throughput**: ≥ `<TBD>` req/s ở tải mục tiêu.
+- **Kích thước**: payload/response ≤ `<TBD>`; bundle frontend (nếu có) ≤ `<TBD>` KB.
+- **Database**: không N+1; số query mỗi request ≤ `<TBD>`; có index cho truy vấn nóng.
+- **Memory/CPU**: không leak; mức nền ≤ `<TBD>`.
+
+## 2. AI-specific (bắt buộc cho feature AI)
+> Tham chiếu chéo `templates/PRD_AI_FEATURE.md §9`.
+- **Prompt caching — BẮT BUỘC**: tận dụng caching của Claude cho phần prompt tĩnh (system, tài liệu nền) để giảm chi phí & độ trễ. Đây là đòn bẩy lớn nhất.
+- **Chọn model theo task**: dùng model nhẹ nhất đủ dùng (Haiku → Sonnet → Opus); không mặc định model mạnh nhất cho mọi việc.
+- **Token/cost ceiling**: trần token & chi phí mỗi request `<TBD>`; cảnh báo khi vượt.
+- **Streaming**: stream phản hồi dài để giảm thời gian chờ cảm nhận.
+- **Context discipline**: chỉ nạp context cần thiết; tránh nhồi toàn bộ tài liệu vào mỗi lượt.
+- **Batching**: gộp khi xử lý khối lượng lớn không cần realtime.
+
+## 3. Gate hồi quy hiệu năng
+- **`change/` + `refactor/` chạm hot-path**: đo **bench trước & sau**, không để xấu đi quá `<TBD>`%.
+- **Feature** (Full path): có ít nhất 1 phép đo/đánh giá tải cho luồng quan trọng trước khi merge.
+- **Observability**: theo dõi p95/p99, token/cost, error rate sau khi lên prod (xem PRD §10).
+
+## 4. Checklist theo path (đưa vào DoD)
+- **Fast path**: không gây hồi quy hiệu năng rõ rệt; không thêm N+1.
+- **Standard path**: + bench trước/sau cho code chạm hot-path; + (AI) prompt caching còn nguyên/được áp dụng.
+- **Full path**: + đạt budget §1; + (feature AI) đạt token/latency ceiling §2; + có số đo tải cho luồng chính.

package/templates/docs/vi/SECURITY_STANDARDS.md

@@ -0,0 +1,37 @@
+# Security Standards
+
+> Baseline bảo mật **đo được** cho {{PROJECT_NAME}}. Là tiêu chí mà `security-review` (Phase 4) chấm theo và là một phần của [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md). Shift-left: phần lớn được xét ngay ở **threat modeling Phase 2** ([AGENCY_WORKFLOW.md](./AGENCY_WORKFLOW.md)).
+>
+> Điền các `<TBD>` theo stack/quy định cụ thể khi chốt ở PRD/TDD đầu tiên.
+
+## 1. Baseline chung (mọi project)
+- **Secrets**: KHÔNG hardcode secret/khoá/API token trong code hay log. Dùng biến môi trường / secret manager. `.env` phải nằm trong `.gitignore`. Bật secret-scanning (xem §4).
+- **Dependency & supply-chain**: khoá phiên bản (lockfile); chạy `<AUDIT_CMD>` (vd `npm audit` / `pip-audit`); bật cập nhật tự động (Dependabot/Renovate); chỉ thêm dependency có nguồn tin cậy.
+- **Input validation & output encoding**: validate mọi input từ ngoài (user, API, file); encode output theo ngữ cảnh (chống XSS/SQLi/command injection). Dùng parameterized query, không nối chuỗi.
+- **AuthN/AuthZ**: xác thực rõ ràng; **least privilege** cho mọi vai trò/khoá/tài nguyên; kiểm tra quyền ở phía server, không tin client.
+- **Transport & data at rest**: TLS cho mọi traffic; mã hoá dữ liệu nhạy cảm khi lưu nếu cần.
+- **Logging**: log đủ để điều tra nhưng **không lộ secret/PII**; không in stack trace/nội bộ ra cho người dùng cuối.
+- **Error handling**: thông báo lỗi cho user không tiết lộ chi tiết hệ thống (path, version, query…).
+
+## 2. AI-specific — OWASP LLM Top 10 (bắt buộc cho feature AI)
+> Tham chiếu chéo `templates/PRD_AI_FEATURE.md §5`.
+- **Prompt injection**: tách bạch **system prompt** với **nội dung không tin cậy** (input user, dữ liệu fetch, tool output). KHÔNG thực thi/đi theo lệnh nằm trong dữ liệu không tin cậy một cách mù quáng.
+- **Sensitive information disclosure**: không để model rò rỉ secret/PII/dữ liệu khách khác; lọc đầu ra; tối thiểu hoá dữ liệu đưa vào context.
+- **Excessive agency**: giới hạn **quyền của tool/agent** (chỉ cấp tool thực sự cần); hành động khó đảo ngược phải có xác nhận/human-in-the-loop (xem [INTERACTION_PATTERNS.md](./INTERACTION_PATTERNS.md) P2/P6).
+- **Insecure output handling**: coi đầu ra của model như **dữ liệu không tin cậy** — validate/sanitize trước khi render HTML, chạy code, hay truyền xuống hệ thống khác.
+- **Guardrails & refusal**: chính sách từ chối nội dung cấm (PRD §5); chống lạm dụng/jailbreak.
+- **Supply chain của model/plugin**: chỉ dùng model/MCP/plugin từ nguồn tin cậy; ghi rõ phiên bản.
+
+## 3. An toàn quy trình (đã enforce một phần qua hook)
+- `main` được bảo vệ; vào qua MR ([BRANCHING.md](./BRANCHING.md)). Hook `git-guard` chặn force-push, `commit --no-verify`, `reset --hard`.
+- Không bỏ qua hook/CI để "cho nhanh".
+
+## 4. Tool tự động (tùy chọn — degrade nếu thiếu)
+- **Secret scanning**: vd `gitleaks` (có thể chạy như pre-commit hook để **chặn**). `<TBD: bật/tắt>`
+- **`<AUDIT_CMD>`** trong CI / lệnh `doctor`.
+- **SAST** (tùy stack): `<TBD>`.
+
+## 5. Checklist theo path (đưa vào DoD)
+- **Fast path**: không secret mới bị commit; `<AUDIT_CMD>` không lỗi nghiêm trọng mới.
+- **Standard path**: + input validation cho code chạm; + kiểm quyền nếu chạm authz.
+- **Full path**: + threat model (Phase 2) đã xử lý; + `security-review` pass; + (feature AI) toàn bộ §2 đã kiểm, gồm ca lạm dụng.

package/templates/docs/vi/TEAM_ROSTER.md

@@ -0,0 +1,35 @@
+# Team Roster & Agent Personas
+
+> Persona là **lăng kính tư duy**, không phải nghi thức bắt buộc cho mọi task. Quy trình & các path: xem [AGENCY_WORKFLOW.md](./AGENCY_WORKFLOW.md) (SSOT).
+
+## 1. Main Agent (Lead)
+Giữ session, nói chuyện với User, điều phối sub-agent. Luân phiên đội mũ:
+- **BA** — `brainstorming`: làm rõ yêu cầu, viết PRD, lấy sign-off (Gate 1).
+- **System Architect** — `gitnexus_exploring` + `gitnexus_impact`: thiết kế, viết TDD, chốt API contract + threat model, chia task (Gate 2).
+- **Scrum Master** — quản lý [ACTIVE_STATE.md](./ACTIVE_STATE.md), cập nhật CLAUDE.md & Serena memory.
+
+## 2. Sub-agents (Dev / QA)
+Spawn qua `Agent` tool khi việc đủ lớn (Standard/Full path).
+
+> ⚠️ **Sub-agent KHÔNG tự kế thừa hội thoại, skill, hay context của Main Agent.** Vì vậy **mọi prompt spawn phải SELF-CONTAINED**, gồm:
+> 1. Link file **PRD/TDD** cụ thể cần đọc.
+> 2. Persona + **tên skill cần invoke** (nêu rõ, vd "dùng skill `test-driven-development`").
+> 3. **Tiêu chí Done** (trỏ path tương ứng trong [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md)).
+> 4. Danh sách file/khu vực liên quan + ràng buộc (API contract).
+
+| Vai | Skills/Tools | Nhiệm vụ |
+|-----|--------------|----------|
+| **Frontend Dev** | design direction đã chốt (xem §3), test-driven-development | Implement UI theo TDD, bám design system |
+| **Backend Dev** | test-driven-development | Logic / API / DB schema, an toàn & hiệu quả |
+| **Code Reviewer** (`code-reviewer`) | code-review, simplify | Review diff: correctness, security, cleanliness |
+| **QA / Security** | security-review, systematic-debugging, verification-before-completion, verify | Phá code, tìm bug, đảm bảo execution flow nguyên vẹn |
+
+## 3. Design direction — CHỌN MỘT
+Repo có nhiều design skill (`design-taste-frontend`, `minimalist-ui`, `industrial-brutalist-ui`, `high-end-visual-design`, `gpt-taste`, `brandkit`…). **Chỉ chốt MỘT direction cho {{PROJECT_NAME}}** (quyết ở PRD/TDD đầu tiên), định nghĩa tokens/type scale/spacing một lần, rồi Frontend bám theo đó.
+- Design direction đã chốt: **`<TBD — điền khi có feature UI đầu tiên>`**
+- KHÔNG gọi nhiều design skill cùng lúc trong một feature → tránh UI mỗi nơi một kiểu.
+
+## 4. Delegation rules
+1. **Không tự code phần lớn ở main thread** nếu việc lớn → delegate sub-agent.
+2. **Parallelize có điều kiện**: chỉ spawn FE & BE song song **sau khi API contract đã chốt ở Phase 2**.
+3. **Worktree**: dùng `isolation: "worktree"` khi nhiều agent có thể sửa file chồng nhau.

package/templates/docs/vi/templates/PRD_AI_FEATURE.md

@@ -0,0 +1,85 @@
+# PRD — <Tên feature AI>
+
+> Template PRD **dành riêng cho tính năng AI/assistant**. Mục đích: ép làm rõ những chiều mà phần mềm tất định thường bỏ sót. Điền hết; mục chưa biết → ghi `GIẢ ĐỊNH:` hoặc `<TBD>` (không để trống ngầm). Tuân [COMMUNICATION_PROTOCOL.md](../COMMUNICATION_PROTOCOL.md).
+>
+> Copy file này vào `docs/specs/YYYY-MM-DD-<feature>.md` khi bắt đầu Phase 1.
+
+**Trạng thái:** Draft | In Review | Approved
+**Ngày:** YYYY-MM-DD · **Product Owner:** · **Path (router):** Full / Standard
+
+---
+
+## 1. Bối cảnh & mục tiêu
+- **Vấn đề người dùng:** <feature giải quyết đau gì?>
+- **Mục tiêu đo được:** <vd: giảm X% thời gian, đạt Y% câu trả lời đúng>
+- **Persona / đối tượng dùng:**
+
+## 2. Intent & Scope của assistant  ⭐
+- **LÀM gì (in-scope):** <những việc assistant phải làm được>
+- **KHÔNG làm gì (out-of-scope, tường minh):** <ranh giới — quan trọng để chống scope creep & hành vi ngoài ý muốn>
+- **Use cases chính (ưu tiên):**
+
+## 3. Hành vi khi MƠ HỒ / thiếu thông tin  ⭐
+> Đây là quyết định cốt lõi của một assistant. Tham chiếu [INTERACTION_PATTERNS.md](../INTERACTION_PATTERNS.md).
+- Khi intent người dùng không rõ → assistant **hỏi lại / đoán-rồi-nêu / từ chối**? <chọn & nêu lý do>
+- **Ngưỡng confidence** để hành động vs hỏi lại: `<TBD>`
+- Số câu hỏi tối đa trước khi phải hành động: `<TBD>`
+
+## 4. Tone & Persona
+- Giọng điệu (formal/thân thiện/ngắn gọn…):
+- Điều assistant **không bao giờ** nói/làm về mặt phong cách:
+- Ngôn ngữ hỗ trợ:
+
+## 5. Guardrails & Safety  ⭐
+> Tuân [SECURITY_STANDARDS.md](../SECURITY_STANDARDS.md) — đặc biệt §2 (OWASP LLM Top 10).
+- **Refusal policy:** loại yêu cầu nào phải từ chối + cách từ chối (xem pattern Refusal trong INTERACTION_PATTERNS).
+- **Dữ liệu nhạy cảm / PII:** thu thập gì, lưu gì, ẩn/mask thế nào, tuân quy định nào.
+- **Prompt injection / lạm dụng:** biện pháp phòng (tách system/user content, kiểm tra đầu ra…).
+- **Nội dung cấm / giới hạn:**
+
+## 6. Định nghĩa "ĐÚNG" (vì output phi xác định)  ⭐
+> Không thể dùng một `assertEquals` cho output AI. Phải định nghĩa *thế nào là tốt*.
+- **Rubric đánh giá** (tiêu chí + thang điểm): vd đúng-sự-thật / bám-yêu-cầu / an-toàn / giọng-điệu.
+- **Golden examples** (input → hành vi/đầu ra mong đợi): ≥ 5–10 ví dụ đại diện, gồm cả ca khó/biên.
+  | Input | Hành vi/đầu ra mong đợi | Vì sao |
+  |-------|-------------------------|--------|
+  | | | |
+
+## 7. Eval strategy  ⭐
+- **Bộ eval tự động** chạy trên golden set (chấm theo rubric §6) — coi như "test" của feature AI.
+- **Regression prompt:** khi đổi prompt/model → chạy lại eval, so điểm trước/sau.
+- Ngưỡng đậu: `<TBD>` (vd điểm rubric trung bình ≥ X, không ca an-toàn nào fail).
+- Quan hệ với DoD: bổ sung vào [DEFINITION_OF_DONE.md](../DEFINITION_OF_DONE.md) cho feature AI.
+
+## 8. Fallback & Human-in-the-loop  ⭐
+- Khi model **fail / timeout / low-confidence** → assistant làm gì? (xin lỗi + gợi ý / trả kết quả một phần / chuyển người thật).
+- **Điểm cần con người** (HITL): hành động nào cần người duyệt trước khi thực thi?
+- Hành vi khi tool/API phụ thuộc lỗi.
+
+## 9. Model, chi phí & hiệu năng
+> Tuân [PERFORMANCE_STANDARDS.md](../PERFORMANCE_STANDARDS.md) §2 (AI-specific).
+- Model dùng (vd Claude Opus/Sonnet/Haiku) + lý do; **prompt caching BẮT BUỘC** cho phần prompt tĩnh.
+- Token budget / chi phí mục tiêu mỗi request (ceiling).
+- Latency mục tiêu (p95).
+
+## 10. Observability
+- Log gì (có ẩn PII), cách đánh giá chất lượng *sau khi* lên prod (thu feedback, sample review).
+- Metric theo dõi (tỉ lệ refusal, confidence, độ hài lòng…).
+
+## 11. Acceptance Criteria
+- [ ] <tiêu chí 1 — đo được>
+- [ ] Eval đạt ngưỡng §7
+- [ ] Guardrails §5 đã kiểm thử (gồm ca lạm dụng)
+
+## 12. API / Interface contract (cho parallelize)
+> Bắt buộc chốt trước khi spawn FE & BE song song (xem AGENCY_WORKFLOW Phase 2/3).
+
+## 13. Decision Log
+| Ngày | Câu hỏi/Vấn đề | Quyết định | Người quyết | Lý do |
+|------|----------------|-----------|-------------|-------|
+| | | | | |
+
+## 14. Assumptions Register
+| Giả định | Trạng thái (chờ/đã xác nhận/bác bỏ) |
+|----------|-------------------------------------|
+| | |