@dtd-dev/agent-kb 0.1.0

package/template/ai/examples/testing-example.md

@@ -0,0 +1,32 @@
+<!-- Mục đích: mẫu viết test chuẩn. -->
+# Testing Example
+
+> Mẫu theo **Vitest/Jest** (cú pháp tương đương). Đổi sang test runner thật của dự án nếu khác.
+
+Tên test mô tả **hành vi** · cấu trúc **arrange–act–assert** · phủ happy path + ca lỗi.
+
+```ts
+import { describe, it, expect } from "vitest";
+import { withdraw, InsufficientBalanceError } from "../coding-example";
+
+describe("withdraw", () => {
+  it("trừ đúng số tiền khi đủ số dư", () => {
+    // arrange
+    const account = { id: "a1", balance: 100 };
+    // act
+    const balance = withdraw(account, 30);
+    // assert
+    expect(balance).toBe(70);
+  });
+
+  it("ném InsufficientBalanceError khi rút quá số dư", () => {
+    const account = { id: "a1", balance: 20 };
+    expect(() => withdraw(account, 50)).toThrow(InsufficientBalanceError);
+  });
+
+  it("từ chối số tiền dưới mức tối thiểu", () => {
+    const account = { id: "a1", balance: 100 };
+    expect(() => withdraw(account, 0)).toThrow(RangeError);
+  });
+});
+```

package/template/ai/memory/common-bugs.md

@@ -0,0 +1,11 @@
+<!-- Mục đích: bug hay tái diễn + cách xử nhanh. -->
+<!-- Các dòng dưới là MẪU (CarePay/Firebase). Thay/append theo bug thật của dự án bạn. -->
+# Common Bugs
+| Triệu chứng | Nguyên nhân gốc | Cách xử |
+|---|---|---|
+| Bị tính tiền 2 lần khi mạng chập | Client retry mà thiếu idempotency key | Bắt buộc `idempotencyKey`, "tạo nếu chưa có" trong transaction (BR-002) |
+| Số dư cộng đôi | Webhook gateway gửi lại, trigger chạy 2 lần | No-op nếu trạng thái đã ở đích; khớp theo `gatewayRef` (BR-003) |
+| Sai số tiền lẻ (lệch 1đ) | Dùng float cho tiền | Lưu/ tính bằng số nguyên (đồng); dồn dư vào kỳ trả góp cuối (BR-006) |
+| Query Firestore lỗi "needs an index" | Thiếu composite index cho where + orderBy | Thêm vào `firestore.indexes.json` rồi deploy |
+| `context.auth` undefined trong onCall | Client gọi khi chưa đăng nhập / token hết hạn | Chặn sớm, trả `UNAUTHENTICATED`; client refresh token |
+| Đổi role nhưng quyền không đổi | Custom claim cũ còn trong token | Gọi `getIdToken(true)` để lấy token mới sau khi set claim |

package/template/ai/memory/lessons-learned.md

@@ -0,0 +1,6 @@
+<!-- Mục đích: bài học tích luỹ. Append dần, đừng viết trước. -->
+<!-- Mục dưới là MẪU minh hoạ định dạng. Xoá khi bắt đầu ghi bài học thật. -->
+# Lessons Learned
+> Mỗi mục: chuyện gì xảy ra → học được gì → đổi cách làm thế nào.
+
+- 2024-03-10: Một đợt retry của đối tác làm double-charge vài giao dịch → idempotency phải áp dụng từ đầu cho MỌI mutation tiền bạc, không chỉ webhook → thêm `idempotencyKey` bắt buộc + kiểm tra trong code-review (BR-002, ADR-002).

package/template/ai/memory/troubleshooting.md

@@ -0,0 +1,19 @@
+<!-- Mục đích: cẩm nang gỡ rối theo tình huống. -->
+<!-- Các mục dưới là MẪU (CarePay/Firebase). Thay/append theo sự cố thật của dự án bạn. -->
+# Troubleshooting
+
+## Cloud Function trả 401/403 dù đã đăng nhập
+- Kiểm tra: client có đính ID token chưa; token hết hạn (refresh chưa); vừa đổi custom claim mà chưa `getIdToken(true)`.
+- Khắc phục: ép refresh token sau khi đổi claim; xác nhận `onCall` đọc `context.auth`, `onRequest` verify token qua Admin SDK.
+
+## Số dư Wallet sai sau thanh toán
+- Kiểm tra: trigger cập nhật số dư có chạy 2 lần không (webhook trùng); có bọc trong transaction không; có dùng số nguyên (đồng) không.
+- Khắc phục: bảo đảm idempotency theo `gatewayRef`/BR-002; đối chiếu `transactions` (append-only) để truy bút toán lệch.
+
+## Webhook gateway báo thành công nhưng Payment vẫn `pending`
+- Kiểm tra: chữ ký webhook có verify đúng không (sai → bị bỏ); URL webhook đúng môi trường chưa; log có `correlationId` của giao dịch không.
+- Khắc phục: tra Cloud Logging theo `paymentId`; nếu thứ tự đảo (webhook đến trước khi ghi `pending`), khớp theo `gatewayRef` rồi cập nhật.
+
+## Triệu chứng chỉ xảy ra trên production, không thấy ở local
+- Kiểm tra: đang dùng Firebase Emulator hay project thật; biến môi trường/secret giữa các môi trường; index Firestore đã deploy chưa.
+- Khắc phục: tái hiện bằng emulator với dữ liệu giống prod; so cấu hình theo `skills/devops/deployment.md`.

package/template/ai/product/business-rules.md

@@ -0,0 +1,19 @@
+<!-- Mục đích: ràng buộc nghiệp vụ. Load khi code logic nghiệp vụ. -->
+<!-- Nội dung dưới là MẪU (CarePay). Thay bằng rule thật của dự án bạn, giữ cách đánh số. -->
+# Business Rules
+
+> Mỗi rule đánh số để code/test tham chiếu được (vd: BR-001).
+
+- **BR-001 — Số tiền hợp lệ**: `amount` phải là số nguyên `> 0` và `<=` hạn mức mỗi giao dịch (mặc định 50.000.000đ). Sai → từ chối với `VALIDATION_ERROR`.
+- **BR-002 — Idempotency**: mỗi `createPayment` kèm `idempotencyKey` duy nhất; gọi lại cùng key trả về Payment đã tạo, KHÔNG tạo bản mới (chống double-charge khi retry/mạng chập).
+- **BR-003 — Trạng thái một chiều**: Payment chỉ đi `pending → succeeded | failed`; `succeeded → refunded`. Mọi chuyển trạng thái khác bị cấm.
+- **BR-004 — Số dư không âm**: thao tác làm `wallet.balance < 0` bị từ chối (`INSUFFICIENT_BALANCE`).
+- **BR-005 — Quyền sở hữu**: User chỉ đọc/thao tác Payment & Wallet của chính mình (enforce ở Security Rules + ở function).
+- **BR-006 — Trả góp**: tổng các Installment phải đúng bằng `amount` của Payment; số kỳ trong khoảng cho phép (vd 3–12).
+- **BR-007 — Hoàn tiền**: chỉ hoàn được Payment `succeeded`, trong cửa sổ cho phép; tạo Transaction đối ứng, không sửa Payment gốc.
+
+## Edge cases
+- Webhook gateway đến **trước** khi ghi `pending` xong → trigger phải chịu được thứ tự đảo (dùng `gatewayRef` để khớp).
+- Webhook **trùng** (gateway gửi lại) → bỏ qua nếu trạng thái đã ở đích (BR-002/BR-003).
+- User bị `status = disabled` giữa lúc thanh toán → từ chối trước khi gọi gateway.
+- Tiền lẻ khi chia trả góp → dồn phần dư vào kỳ cuối để tổng khớp (BR-006).

package/template/ai/product/domain-model.md

@@ -0,0 +1,22 @@
+<!-- Mục đích: thực thể nghiệp vụ và quan hệ. Load khi thiết kế data/model. -->
+<!-- Nội dung dưới là MẪU (CarePay, Firestore). Thay bằng domain thật của dự án bạn. -->
+# Domain Model
+
+## Entities
+- **User** (`users/{uid}`): người dùng đã đăng nhập (Firebase Auth). Thuộc tính: `displayName`, `phone`, `status`, `createdAt`. Một User có một Wallet.
+- **Wallet** (`wallets/{uid}`): số dư & trạng thái của User. `balance` (đơn vị: đồng, số nguyên), `currency`, `updatedAt`. Chỉ Cloud Functions được ghi.
+- **Provider** (`providers/{id}`): cơ sở y tế nhận tiền. `name`, `taxCode`, `payoutAccount`, `status`.
+- **Payment** (`payments/{id}`): một lần thanh toán. `userId`, `providerId`, `amount`, `status` (`pending|succeeded|failed|refunded`), `gatewayRef`, `idempotencyKey`, `createdAt`. Bất biến sau khi `succeeded` (chỉ chuyển sang `refunded`).
+- **Installment** (`payments/{id}/installments/{n}`): kỳ trả góp của một Payment. `seq`, `dueDate`, `amount`, `status`.
+- **Transaction** (`wallets/{uid}/transactions/{id}`): bút toán thay đổi số dư (audit log) — `type`, `amount`, `paymentId`, `balanceAfter`.
+
+## Quan hệ
+- User **1—1** Wallet.
+- User **1—n** Payment; Provider **1—n** Payment.
+- Payment **1—n** Installment (nếu trả góp).
+- Wallet **1—n** Transaction (mỗi thay đổi số dư = 1 bút toán, không sửa/xoá).
+
+## Quy ước dữ liệu
+- Tiền lưu bằng **số nguyên đơn vị nhỏ nhất** (đồng) — không dùng float.
+- Mọi document có `createdAt`/`updatedAt` (server timestamp).
+- Thay đổi số dư đi qua Transaction (append-only) để đối soát được.

package/template/ai/product/vision.md

@@ -0,0 +1,8 @@
+<!-- Mục đích: tầm nhìn sản phẩm. Hiếm cần khi code — chỉ load khi bàn hướng đi. -->
+<!-- Nội dung dưới là MẪU (CarePay). Thay bằng tầm nhìn thật của dự án bạn. -->
+# Product Vision
+- **Vấn đề giải quyết**: viện phí lớn, trả một lần gây áp lực tài chính; cơ sở y tế tốn công thu và đối soát thủ công.
+- **Người dùng mục tiêu**: bệnh nhân cần linh hoạt thanh toán (gồm trả góp); cơ sở y tế (Provider) muốn nhận tiền nhanh, đối soát tự động.
+- **Giá trị cốt lõi**: thanh toán viện phí an toàn, minh bạch, hỗ trợ trả góp; trải nghiệm vài chạm; đối soát tự động cho Provider.
+- **Không làm (out of scope)**: không phải ví điện tử đa năng; không cho vay tiêu dùng ngoài y tế; không lưu thông tin thẻ thô (uỷ thác cho gateway).
+- **Chỉ số thành công**: tỷ lệ thanh toán thành công, thời gian hoàn tất, tỷ lệ giao dịch lỗi/hoàn tiền.

package/template/ai/skills/backend/carepay-oncall-gen2.md

@@ -0,0 +1,24 @@
+<!-- Mục đích: quy trình on-call backend CarePay Gen2. Load khi task thuộc loại này. -->
+<!-- Nội dung dưới là MẪU minh hoạ pattern onCall. Sửa theo code thật của dự án bạn. -->
+# Skill: CarePay On-call (Gen2)
+
+## Khi nào dùng
+Viết/sửa **callable function** (`onCall`) Gen2 — thao tác gọi từ app đã đăng nhập (vd `createPayment`, `getWallet`).
+
+## Quy tắc / pattern
+- **Xác thực trước tiên**: đọc `request.auth`; chưa có → ném `HttpsError("unauthenticated", ...)`. Phân quyền theo `uid`/custom claim (ADR-001).
+- **Validate input ở biên** trước khi chạm dữ liệu (BR-001); trả `HttpsError("invalid-argument", ...)` với `code` rõ.
+- **Mutation tiền bạc phải idempotent + transaction** (BR-002, ADR-002): "tạo nếu chưa có" theo `idempotencyKey`.
+- **Trả dữ liệu tối thiểu** client cần; KHÔNG trả nội bộ/PII thừa. Lỗi dùng `HttpsError` với code máy đọc.
+- **Side-effect để cho trigger lo** (cập nhật số dư, gửi mail) — onCall chỉ tạo sự thay đổi nguồn.
+- **Cấu hình** vùng/secret qua env (Gen2: `defineSecret`/`defineString`), không hardcode.
+- **Log có `correlationId`** (= `paymentId`/request id), không log token/PII (ADR-003).
+
+## Cạm bẫy thường gặp
+- Quên verify `request.auth` → ai cũng gọi được; rò rỉ dữ liệu.
+- Đọc-rồi-ghi ngoài transaction → race condition double-charge.
+- Ném Error thường thay vì `HttpsError` → client nhận `internal` mất thông tin.
+
+## Tham chiếu
+- `decisions/ADR-001-auth.md`, `decisions/ADR-002-cache.md`
+- `specs/feature-a/` (ví dụ `createPayment`) · `core/coding-standards.md`

package/template/ai/skills/backend/carepay-request-gen2.md

@@ -0,0 +1,23 @@
+<!-- Mục đích: xử lý request backend CarePay Gen2. Load khi task thuộc loại này. -->
+<!-- Nội dung dưới là MẪU minh hoạ pattern onRequest. Sửa theo code thật của dự án bạn. -->
+# Skill: CarePay Request (Gen2)
+
+## Khi nào dùng
+Viết/sửa **HTTP function** (`onRequest`) Gen2 — endpoint cho đối tác ngoài / webhook (vd `paymentWebhook`), nơi không có Firebase Auth token.
+
+## Quy tắc / pattern
+- **Tự xác thực**: không có `request.auth` → phải **verify chữ ký** webhook (HMAC/secret từ env) hoặc verify ID token thủ công qua Admin SDK. Sai → `401/400`, dừng ngay.
+- **Idempotent theo khoá ngoài** (`gatewayRef`): xử lý lại cùng sự kiện = no-op (BR-002, BR-003). Trả `200` cả khi no-op để gateway ngừng retry.
+- **Chỉ chuyển trạng thái hợp lệ** (BR-003); chịu được **thứ tự đảo** (webhook đến trước khi ghi `pending`) bằng cách khớp theo `gatewayRef`.
+- **Validate payload** & method; trả HTTP status đúng ngữ nghĩa; body lỗi có `code`.
+- **Đáp nhanh, đẩy việc nặng cho trigger/Pub/Sub**: webhook nên ngắn, tránh timeout của gateway.
+- **Log `correlationId`**, không echo payload nhạy cảm (ADR-003).
+
+## Cạm bẫy thường gặp
+- Bỏ qua verify chữ ký → ai cũng giả webhook để đổi trạng thái thanh toán.
+- Trả `5xx` khi gặp sự kiện trùng → gateway retry vô hạn (nên no-op `200`).
+- Xử lý đồng bộ quá lâu trong webhook → timeout, gateway coi là thất bại.
+
+## Tham chiếu
+- `decisions/ADR-002-cache.md`, `decisions/ADR-003-logging.md`
+- `specs/feature-a/api.md` (webhook) · `architecture.md`

package/template/ai/skills/backend/carepay-trigger-gen2.md

@@ -0,0 +1,24 @@
+<!-- Mục đích: cách viết/sửa trigger backend CarePay Gen2. Load khi task thuộc loại này. -->
+<!-- Nội dung dưới là MẪU minh hoạ pattern trigger. Sửa theo code thật của dự án bạn. -->
+# Skill: CarePay Trigger (Gen2)
+
+## Khi nào dùng
+Viết/sửa **event-triggered function** Gen2 — chạy theo sự kiện Firestore/Auth/Pub/Sub để xử lý **hệ quả phụ** (vd `onPaymentSucceeded` cập nhật ví, gửi thông báo).
+
+## Quy tắc / pattern
+- **Idempotent** là bắt buộc: trigger **có thể chạy nhiều lần** cho cùng sự kiện. Dùng `event.id`/cờ trạng thái để no-op nếu đã xử lý (BR-002).
+- **Mutation số dư trong transaction**, ghi `transactions` (append-only) thay vì sửa số tại chỗ — để đối soát (domain-model).
+- **Bảo vệ vòng lặp**: nếu trigger ghi lại chính collection nó lắng nghe, phải có điều kiện thoát để không kích hoạt đệ quy vô hạn.
+- **Chỉ phản ứng đúng chuyển trạng thái** (so `before`/`after`, BR-003): vd chỉ xử khi `pending → succeeded`.
+- **Lỗi & retry**: trigger sẽ được retry khi ném lỗi — đảm bảo retry an toàn; phần "không nên retry" thì nuốt có chủ đích + log.
+- **Không nhận input từ client**: nguồn sự thật là document, không phải tham số người dùng.
+- **Log `correlationId`** = `paymentId` (ADR-003).
+
+## Cạm bẫy thường gặp
+- Cộng số dư không idempotent → cộng đôi khi trigger chạy lại.
+- Trigger tự ghi lại document đang nghe → loop vô hạn, đốt chi phí.
+- Giả định chạy đúng 1 lần / đúng thứ tự — Gen2 không đảm bảo điều đó.
+
+## Tham chiếu
+- `decisions/ADR-002-cache.md` · `product/domain-model.md` · `product/business-rules.md`
+- `specs/feature-a/design.md` (`onPaymentSucceeded`)

package/template/ai/skills/devops/deployment.md

@@ -0,0 +1,29 @@
+<!-- Mục đích: quy trình deploy lên môi trường. Load khi task thuộc loại này. -->
+# Skill: Deployment
+
+## Khi nào dùng
+Đưa code lên môi trường (staging/production), cấu hình release, rollback.
+
+## Quy tắc / pattern
+- **Promote qua môi trường**: dev → staging → production. Cùng một artifact đã test, không build lại cho từng môi trường.
+- **Config tách khỏi code**: khác biệt giữa môi trường nằm ở ENV/secret manager, không sửa code khi deploy.
+- **Chiến lược zero-downtime**: rolling update hoặc blue/green; có health check trước khi nhận traffic.
+- **Migration trước, tương thích ngược**: chạy migration DB trước khi deploy app; schema phải tương thích cả version cũ lẫn mới (expand → migrate → contract).
+- **Smoke test sau deploy**: kiểm tra nhanh các luồng chính trên môi trường vừa deploy.
+- **Rollback sẵn sàng**: biết cách quay về version trước trong vài phút (giữ artifact cũ / feature flag).
+- **Observability**: theo dõi error rate, latency, log ngay sau khi deploy.
+
+<!-- Điền lệnh/hạ tầng thật của dự án (vd: kubectl, terraform, script deploy, registry): -->
+## Lệnh & hạ tầng (điền theo dự án)
+- Môi trường: <!-- staging URL / production URL -->
+- Lệnh deploy: {{DEPLOY_CMD}}
+- Lệnh rollback: <!-- ... -->
+
+## Cạm bẫy thường gặp
+- Migration phá tương thích ngược → version cũ lỗi trong lúc rolling.
+- Deploy thủ công không lặp lại được → thiếu nhất quán giữa các lần.
+- Không có rollback rõ ràng → sự cố kéo dài.
+
+## Tham chiếu
+- `skills/devops/docker.md`, `skills/devops/github-actions.md`
+- `workflows/release.md`, `workflows/incident-response.md`

package/template/ai/skills/devops/docker.md

@@ -0,0 +1,24 @@
+<!-- Mục đích: build & chạy bằng Docker. Load khi task thuộc loại này. -->
+# Skill: Docker
+
+## Khi nào dùng
+Viết/sửa Dockerfile, đóng gói image, tối ưu build, chạy local bằng container/compose.
+
+## Quy tắc / pattern
+- **Multi-stage build**: tách stage build và runtime; image cuối chỉ chứa artifact + runtime cần thiết.
+- **Base image nhỏ & ghim version**: dùng `slim`/`alpine`/`distroless`; ghim tag cụ thể, không dùng `latest`.
+- **Tận dụng layer cache**: copy file manifest (`package.json`/`go.mod`...) và cài deps TRƯỚC khi copy source.
+- **`.dockerignore`**: loại `node_modules`, `.git`, build artifact, `.env` để build nhanh & tránh lộ secret.
+- **Chạy non-root**: tạo user riêng, `USER app`; không chạy bằng root.
+- **Cấu hình qua ENV**, không hardcode; secret truyền lúc runtime, không bake vào image.
+- **HEALTHCHECK** để orchestrator biết container sống/chết.
+- Một process chính mỗi container; log ra stdout/stderr.
+
+## Cạm bẫy thường gặp
+- `COPY . .` trước khi cài deps → vỡ cache, build lại từ đầu mỗi lần.
+- Bake secret/`.env` vào image (còn trong layer history dù đã xoá).
+- Image phình do để cả devDependencies/build tool trong stage runtime.
+
+## Tham chiếu
+- Build/deploy: `skills/devops/deployment.md`, `skills/devops/github-actions.md`
+- Stack & version: `core/tech-stack.md`

package/template/ai/skills/devops/github-actions.md

@@ -0,0 +1,26 @@
+<!-- Mục đích: pipeline CI/CD GitHub Actions. Load khi task thuộc loại này. -->
+# Skill: GitHub Actions
+
+## Khi nào dùng
+Tạo/sửa workflow CI/CD trong `.github/workflows/`, cấu hình test/build/deploy tự động.
+
+## Quy tắc / pattern
+- **Cấu trúc**: trigger (`on:`) → jobs → steps. Tách job `lint`/`test`/`build`/`deploy` cho rõ ràng và song song được.
+- **Ghim version action**: dùng tag (hoặc SHA cho action bên thứ ba) thay vì nhánh động.
+- **Cache dependencies**: `actions/cache` hoặc `cache:` của setup action để CI nhanh.
+- **Matrix** khi cần test nhiều version runtime/OS.
+- **Secret & quyền**:
+  - Dùng `secrets`, không in ra log; `permissions:` tối thiểu cho `GITHUB_TOKEN`.
+  - Ưu tiên **OIDC** để auth cloud thay vì lưu credential tĩnh.
+  - Cẩn trọng với `pull_request_target` (chạy với quyền cao + code chưa tin cậy).
+- **Gate merge**: bật required status checks; deploy chỉ chạy sau khi test xanh (`needs:`).
+- **Environment + approval** cho deploy production.
+- **Concurrency**: huỷ run cũ khi push mới (`concurrency:` + `cancel-in-progress`).
+
+## Cạm bẫy thường gặp
+- Echo secret hoặc để secret rơi vào log/artifact.
+- Không pin action → bản mới làm vỡ pipeline.
+- Cài lại deps mỗi lần vì thiếu cache → CI chậm & tốn phút.
+
+## Tham chiếu
+- Đóng gói: `skills/devops/docker.md` · Phát hành: `skills/devops/deployment.md`, `workflows/release.md`

package/template/ai/skills/frontend/carepay-firebase.md

@@ -0,0 +1,25 @@
+<!-- Mục đích: tích hợp Firebase phía frontend. Load khi task thuộc loại này. -->
+<!-- Nội dung dưới là MẪU minh hoạ pattern. Sửa theo code thật của dự án bạn. -->
+# Skill: CarePay Firebase
+
+## Khi nào dùng
+Tích hợp Firebase phía client: đăng nhập (Auth), đọc realtime Firestore, gọi callable function, dùng emulator khi dev.
+
+## Quy tắc / pattern
+- **Khởi tạo một lần**: tạo app/Auth/Firestore ở một module dùng chung; không `initializeApp` rải rác.
+- **Gọi backend qua callable** (`httpsCallable`) cho mọi mutation — KHÔNG ghi trực tiếp collection tiền bạc từ client (chặn ở Security Rules; xem `architecture.md`).
+- **Đọc realtime đúng chỗ**: dùng `onSnapshot` cho dữ liệu thay đổi (trạng thái Payment), `getDoc` cho đọc một lần. **Luôn huỷ subscribe** khi unmount (cleanup trong `useEffect`).
+- **Truyền idempotencyKey** (uuid client tạo) khi gọi `createPayment`; retry dùng lại cùng key (BR-002).
+- **Xử lý đủ trạng thái** loading / error / empty (xem `skills/frontend/react.md`, `ui-guideline.md`).
+- **Map lỗi `HttpsError`**: đọc `error.code`/`error.message` từ callable để hiện thông báo thân thiện theo `code`.
+- **Emulator khi dev**: trỏ Auth/Firestore/Functions sang emulator qua env, không chạm project thật.
+- **Không để secret trong client**: chỉ config Firebase công khai; logic nhạy cảm ở functions.
+
+## Cạm bẫy thường gặp
+- Quên huỷ `onSnapshot` → rò rỉ listener, cập nhật state sau khi unmount.
+- Ghi thẳng Firestore để "nhanh" → vỡ bảo mật & business rule (phải qua function).
+- Token hết hạn sau khi đổi claim → gọi `getIdToken(true)` để refresh.
+
+## Tham chiếu
+- `skills/frontend/react.md` · `architecture.md` · `decisions/ADR-001-auth.md`
+- Backend tương ứng: `skills/backend/carepay-oncall-gen2.md`

package/template/ai/skills/frontend/react.md

@@ -0,0 +1,24 @@
+<!-- Mục đích: convention React trong dự án. Load khi task thuộc loại này. -->
+# Skill: React
+
+## Khi nào dùng
+Viết/sửa component, hook, quản lý state, fetch dữ liệu phía React.
+
+## Quy tắc / pattern
+- **Function component + hooks**; không dùng class. Một component một trách nhiệm, giữ nhỏ.
+- **Tách logic ra custom hook** (`useXxx`) khi dùng lại được; tuân thủ rules-of-hooks (gọi ở top level).
+- **State đặt đúng chỗ**: cục bộ thì `useState`; chia sẻ gần thì lift up / context; server state thì dùng lib data-fetching (vd React Query) — đừng nhồi tất cả vào global store.
+- **Data fetching**: xử lý đủ 3 trạng thái loading / error / empty; tránh fetch trong vòng lặp render.
+- **Key danh sách** ổn định, không dùng index khi list có thể đổi thứ tự.
+- **Effect đúng mục đích**: `useEffect` cho side-effect + dọn dẹp (cleanup); không dùng effect để tính giá trị dẫn xuất (tính thẳng khi render hoặc `useMemo`).
+- **Tối ưu có đo lường**: chỉ `memo`/`useMemo`/`useCallback` khi thật sự cần; tránh tối ưu sớm.
+- **Controlled component** cho form; validate rõ ràng.
+- **A11y**: dùng thẻ ngữ nghĩa, `label` cho input, hỗ trợ bàn phím.
+
+## Cạm bẫy thường gặp
+- Thiếu/sai dependency array của `useEffect` → stale closure hoặc loop vô hạn.
+- Lạm dụng global state cho dữ liệu server → khó đồng bộ, dễ lệch.
+- Mutate trực tiếp state/props thay vì tạo bản mới.
+
+## Tham chiếu
+- `skills/frontend/ui-guideline.md` · `core/coding-standards.md` · ví dụ: `examples/coding-example.md`

package/template/ai/skills/frontend/ui-guideline.md

@@ -0,0 +1,29 @@
+<!-- Mục đích: hướng dẫn UI/UX, design tokens. Load khi task thuộc loại này. -->
+# Skill: UI Guideline
+
+## Khi nào dùng
+Dựng giao diện, đảm bảo nhất quán về spacing, màu, typography, trạng thái và accessibility.
+
+## Quy tắc / pattern
+- **Design token, không magic value**: màu/spacing/font lấy từ token tập trung (theme), không hardcode hex/px rải rác.
+- **Thang spacing nhất quán**: dùng scale (vd 4/8/12/16/24/32). Không chế số lẻ tuỳ tiện.
+- **Typography có hệ thống**: vài cấp heading/body rõ ràng; giới hạn số font/size.
+- **Responsive mobile-first**: thiết kế cho màn nhỏ trước, mở rộng bằng breakpoint.
+- **Đủ trạng thái UI**: luôn xử lý loading / empty / error / success — không chỉ happy path.
+- **Phản hồi tương tác**: hover/focus/active/disabled rõ ràng; thao tác lâu phải có loading indicator.
+- **Accessibility (WCAG)**: tương phản màu đạt chuẩn; focus nhìn thấy; điều hướng được bằng bàn phím; có `alt`/aria khi cần.
+- **Component tái dùng**: ưu tiên component dùng chung thay vì copy style; giữ biến thể (variant) trong một nơi.
+
+<!-- Điền token/brand thật của dự án (màu, font, breakpoint) hoặc trỏ tới design system: -->
+## Token dự án (điền theo dự án)
+- Màu chính / phụ: <!-- ... -->
+- Font: <!-- ... -->
+- Breakpoints: <!-- ... -->
+
+## Cạm bẫy thường gặp
+- Hardcode màu/spacing → khó đổi theme, dễ lệch.
+- Quên trạng thái empty/error → UI vỡ với dữ liệu thật.
+- Bỏ qua focus/contrast → không dùng được bằng bàn phím / người khiếm thị.
+
+## Tham chiếu
+- `skills/frontend/react.md` · `core/coding-standards.md`

package/template/ai/specs/feature-a/api.md

@@ -0,0 +1,26 @@
+<!-- Mục đích: hợp đồng API của feature. -->
+<!-- Nội dung dưới là MẪU (feature "Tạo thanh toán"). Thay bằng API thật của bạn. -->
+# Feature A — API
+
+## `callable createPayment` (onCall — cần Auth)
+- **Mô tả**: tạo một thanh toán cho Provider; idempotent theo `idempotencyKey`.
+- **Request**:
+  ```json
+  { "providerId": "prov_123", "amount": 250000, "idempotencyKey": "uuid-v4" }
+  ```
+- **Response (success)**:
+  ```json
+  { "paymentId": "pay_abc", "status": "pending" }
+  ```
+- **Lỗi** (chuẩn body: `code` máy đọc + `message` người đọc):
+  | code | Khi nào |
+  |---|---|
+  | `UNAUTHENTICATED` | Thiếu/sai Auth token (BR-005) |
+  | `VALIDATION_ERROR` | `amount` ≤ 0 hoặc vượt hạn mức (BR-001) |
+  | `PROVIDER_NOT_FOUND` | `providerId` không tồn tại |
+  | `INSUFFICIENT_BALANCE` | Số dư không đủ (nếu trả từ ví, BR-004) |
+
+## `POST /webhooks/payment` (onRequest — verify chữ ký gateway)
+- **Mô tả**: gateway báo kết quả; chuyển trạng thái Payment (BR-003). Idempotent theo `gatewayRef`.
+- **Request**: payload của gateway + header chữ ký.
+- **Response**: `200` khi đã xử lý (kể cả no-op nếu trùng); `400` nếu chữ ký sai.

package/template/ai/specs/feature-a/design.md

@@ -0,0 +1,12 @@
+<!-- Mục đích: thiết kế kỹ thuật của feature. -->
+<!-- Nội dung dưới là MẪU (feature "Tạo thanh toán"). Thay bằng feature thật của bạn. -->
+# Feature A — Design
+- **Tiếp cận**:
+  - Callable `createPayment` (onCall) verify Auth → validate (BR-001) → "tạo nếu chưa có" theo `idempotencyKey` trong Firestore transaction → gọi Payment Gateway → ghi `payments/{id}` status `pending`.
+  - Webhook `paymentWebhook` (onRequest) verify chữ ký gateway → chuyển trạng thái theo BR-003.
+  - Trigger `onPaymentSucceeded` (Firestore trigger) cập nhật `wallets/{uid}` + ghi `transactions` (append-only) + bắn thông báo.
+- **Thay đổi data model**: thêm collection `payments`, `idempotency/{key}`, subcollection `wallets/{uid}/transactions`. Index composite cho `payments` theo `userId + createdAt`.
+- **Đánh đổi**:
+  - Xử lý bất đồng bộ (gateway → webhook → trigger) phức tạp hơn đồng bộ, nhưng tránh giữ request lâu và chịu được retry.
+  - Tốn thêm đọc/ghi khoá idempotency mỗi giao dịch (chấp nhận, đổi lấy an toàn — ADR-002).
+- **Liên quan**: ADR-001 (auth), ADR-002 (idempotency), ADR-003 (logging). Cách viết function: `skills/backend/*`.

package/template/ai/specs/feature-a/requirements.md

@@ -0,0 +1,13 @@
+<!-- Mục đích: yêu cầu của feature. Copy thư mục feature-a/ này cho mỗi feature mới. -->
+<!-- Nội dung dưới là MẪU (feature "Tạo thanh toán"). Thay bằng feature thật của bạn. -->
+# Feature A — Tạo thanh toán (Create Payment)
+- **Mục tiêu**: cho phép người dùng đã đăng nhập thanh toán một khoản viện phí cho Provider, an toàn và không bị tính trùng.
+- **User story**: Là *bệnh nhân*, tôi muốn *thanh toán hoá đơn cho phòng khám* để *hoàn tất viện phí mà không phải tới quầy*.
+- **Acceptance criteria**:
+  - [ ] Người dùng chọn Provider + nhập số tiền → tạo Payment `pending` rồi chuyển `succeeded` khi gateway xác nhận.
+  - [ ] Gọi lại cùng `idempotencyKey` không tạo thêm Payment (BR-002).
+  - [ ] Số tiền sai (≤0 hoặc vượt hạn mức) bị từ chối với thông báo rõ ràng (BR-001).
+  - [ ] User chỉ thấy/thao tác Payment của chính mình (BR-005).
+  - [ ] UI hiển thị đủ trạng thái loading / thành công / lỗi.
+- **Ngoài phạm vi**: trả góp (Installment) — làm ở feature riêng; hoàn tiền; thanh toán cho người khác.
+- **Business rules liên quan**: BR-001, BR-002, BR-003, BR-004, BR-005.

package/template/ai/specs/feature-a/test-cases.md

@@ -0,0 +1,12 @@
+<!-- Mục đích: test case của feature. -->
+<!-- Nội dung dưới là MẪU (feature "Tạo thanh toán"). Thay bằng test case thật của bạn. -->
+# Feature A — Test Cases
+| ID | Tình huống | Input | Kỳ vọng |
+|----|-----------|-------|---------|
+| TC-1 | Happy path | user đã đăng nhập, `amount=250000`, key mới | Tạo Payment `pending`; sau webhook → `succeeded`; ví cập nhật đúng |
+| TC-2 | Idempotency (BR-002) | gọi lại cùng `idempotencyKey` | Trả về đúng Payment cũ, KHÔNG tạo bản mới |
+| TC-3 | Số tiền không hợp lệ (BR-001) | `amount=0` hoặc vượt hạn mức | `VALIDATION_ERROR`, không gọi gateway |
+| TC-4 | Chưa đăng nhập (BR-005) | không có Auth token | `UNAUTHENTICATED` |
+| TC-5 | Webhook trùng (BR-003) | gateway gửi lại cùng `gatewayRef` | No-op; trạng thái & số dư không đổi |
+| TC-6 | Webhook chữ ký sai | payload sai chữ ký | `400`, bỏ qua, không đổi trạng thái |
+| TC-7 | Thứ tự đảo | webhook đến trước khi ghi `pending` | Khớp theo `gatewayRef`, xử lý đúng khi `pending` xuất hiện |

package/template/ai/workflows/code-review.md

@@ -0,0 +1,25 @@
+<!-- Mục đích: checklist review (đóng vai reviewer). -->
+# Workflow: Code Review
+
+> Review theo ưu tiên: chặn (P0) trước, góp ý (P2) sau. Bám `core/coding-standards.md`.
+
+## P0 — Phải sửa trước khi merge
+- [ ] **Đúng yêu cầu**: khớp acceptance criteria trong `specs/<feature>/`.
+- [ ] **Correctness**: logic đúng; xử lý edge case (null/rỗng/biên/timeout).
+- [ ] **Bảo mật**: không hardcode secret; validate input; tránh injection/XSS; phân quyền đúng.
+- [ ] **Test**: logic mới có test; test xanh; có cả happy path lẫn ca thất bại.
+
+## P1 — Nên sửa
+- [ ] **Error handling**: không nuốt lỗi; tách lỗi nghiệp vụ vs hệ thống; log có ngữ cảnh.
+- [ ] **Dữ liệu/đồng thời**: race condition, transaction, idempotency (nếu liên quan).
+- [ ] **Hiệu năng**: không N+1 query, không load thừa, không vòng lặp tốn kém.
+- [ ] **Tương thích**: không phá API/contract cũ; có migration nếu đổi schema.
+
+## P2 — Chất lượng
+- [ ] Tên rõ nghĩa, hàm đủ nhỏ, không lặp code, không magic value.
+- [ ] Không code chết / import thừa / log debug sót lại.
+- [ ] Comment giải thích "vì sao", không lặp "cái gì".
+
+## Cách góp ý
+- Ghi rõ mức (P0/P1/P2) + lý do; gợi ý cách sửa, không chỉ chê.
+- Tách "bắt buộc" và "tuỳ chọn (nit)". Khen điểm tốt khi xứng đáng.

package/template/ai/workflows/create-feature.md

@@ -0,0 +1,37 @@
+<!-- Mục đích: quy trình tạo feature mới (đóng luôn vai trò developer/architect). -->
+# Workflow: Create Feature
+
+## Sinh spec từ mô tả (AI điền)
+> Khi người dùng nói kiểu *"sinh spec cho tính năng <X>: <mô tả>"* — agent tự viết spec, KHÔNG bắt người dùng điền tay.
+
+1. **Tạo khung** — chạy `agent-kb feature <slug>` (hoặc tạo `specs/<slug>/` từ khung trống). Slug ngắn gọn theo tên feature.
+2. **Đọc context trước khi viết** — `product/business-rules.md`, `product/domain-model.md`, `core/glossary.md`, `core/coding-standards.md` để spec khớp nghiệp vụ & quy ước sẵn có.
+3. **Điền 4 file** từ mô tả người dùng:
+   - `requirements.md`: mục tiêu, user story, acceptance criteria, ngoài phạm vi, BR liên quan.
+   - `design.md`: tiếp cận, thay đổi data model, đánh đổi.
+   - `api.md`: endpoint, request/response, mã lỗi (bỏ nếu feature không có API).
+   - `test-cases.md`: happy path + edge case + ca theo từng BR.
+4. **Quy tắc khi sinh**:
+   - Yêu cầu mơ hồ → **HỎI, không bịa** acceptance criteria/BR.
+   - Tham chiếu BR sẵn có theo mã (vd BR-001); **không tự đẻ rule mới** — thiếu rule thì đề xuất rồi hỏi.
+   - Giữ nhất quán với `domain-model.md` (tên entity) và `glossary.md` (thuật ngữ).
+   - Điền xong **xoá dòng `<!-- AI: ... -->`** trong mỗi file.
+5. **Dừng cho người dùng DUYỆT spec** rồi mới sang phần "Quy trình" code/test bên dưới (spec-first).
+
+## Quy trình
+1. **Hiểu yêu cầu** — đọc `specs/<feature>/requirements.md`. Chưa có thư mục spec thì tạo nhanh bằng `agent-kb feature <tên>`, rồi viết trước (mục tiêu, user story, acceptance criteria, ngoài phạm vi, BR liên quan).
+2. **Thiết kế** — `specs/<feature>/design.md`: tiếp cận, thay đổi data model, đánh đổi. Quyết định lớn → thêm ADR vào `decisions/`.
+3. **Chốt API** — nếu có endpoint, ghi hợp đồng vào `specs/<feature>/api.md` trước khi code.
+4. **Code** — theo `core/coding-standards.md` + skill liên quan (`skills/backend|frontend/*`). Commit nhỏ, từng phần chạy được.
+5. **Test** — viết theo `specs/<feature>/test-cases.md`; phủ happy path + edge case + business rule.
+6. **Tự review** — chạy `workflows/code-review.md` trước khi mở PR.
+
+## Definition of Done
+- [ ] Đủ acceptance criteria; không vỡ tính năng cũ.
+- [ ] Test xanh, có cho cả ca lỗi.
+- [ ] Đã cập nhật doc liên quan (spec/ADR/glossary).
+- [ ] Không secret/log debug sót; đã tự review.
+
+## Lưu ý
+- Mơ hồ yêu cầu thì hỏi, đừng đoán.
+- Phạm vi phình to → tách feature nhỏ hơn.

package/template/ai/workflows/fix-bug.md

@@ -0,0 +1,16 @@
+<!-- Mục đích: quy trình fix bug. -->
+# Workflow: Fix Bug
+
+## Quy trình
+1. **Tái hiện** — dựng lại bug một cách ổn định; ghi rõ bước tái hiện + môi trường + kết quả mong đợi vs thực tế.
+2. **Tra cứu** — check `memory/common-bugs.md` và `memory/troubleshooting.md` xem đã gặp chưa.
+3. **Khoanh vùng** — thu hẹp dần (log, bisect, test nhỏ) tới nơi gây lỗi.
+4. **Root cause** — tìm nguyên nhân gốc, không vá triệu chứng. Hỏi "vì sao" tới khi tới gốc.
+5. **Test bắt bug** — viết test fail trước, tái hiện đúng bug, rồi mới sửa cho test xanh (regression test).
+6. **Sửa** — đổi nhỏ nhất đủ giải quyết gốc; rà các nơi khác cùng pattern.
+7. **Xác minh** — chạy lại bước tái hiện + toàn bộ test liên quan.
+8. **Ghi lại** — nếu đáng nhớ, thêm vào `memory/common-bugs.md` (triệu chứng → nguyên nhân → cách xử).
+
+## Lưu ý
+- Bug production gấp → ưu tiên giảm thiểu trước theo `workflows/incident-response.md`, sửa gốc sau.
+- Không xoá test/giảm assertion để "qua bài".

package/template/ai/workflows/incident-response.md

@@ -0,0 +1,19 @@
+<!-- Mục đích: ứng phó sự cố production. -->
+# Workflow: Incident Response
+
+## Phân loại mức độ (severity)
+- **SEV1**: sập/dừng dịch vụ, mất/lộ dữ liệu → xử lý ngay, báo động.
+- **SEV2**: lỗi nặng nhưng còn workaround → xử lý trong giờ.
+- **SEV3**: ảnh hưởng nhỏ → đưa vào backlog.
+
+## Quy trình
+1. **Giảm thiểu trước** — khôi phục dịch vụ là ưu tiên #1: rollback, tắt feature flag, scale, chặn nguồn lỗi. Chưa cần biết root cause.
+2. **Chỉ định người điều phối** — 1 người chủ trì (incident commander); những người khác hỗ trợ.
+3. **Cập nhật liên lạc** — thông báo bên liên quan; cập nhật định kỳ trạng thái cho tới khi xong.
+4. **Ghi timeline** — mốc thời gian: phát hiện → hành động → kết quả. Ghi ngay khi đang xử lý.
+5. **Xác nhận đã hồi phục** — theo dõi metric/log đủ lâu để chắc chắn ổn định.
+
+## Sau sự cố
+- **Postmortem không đổ lỗi**: chuyện gì xảy ra, vì sao, phát hiện thế nào, cách phòng tái diễn.
+- Ghi bài học → `memory/lessons-learned.md`; bug gốc → `workflows/fix-bug.md` + `memory/common-bugs.md`.
+- Tạo action item có người chịu trách nhiệm và hạn.

package/template/ai/workflows/learn.md

@@ -0,0 +1,24 @@
+<!-- Mục đích: vòng tự học — chốt bài học sau mỗi task/incident vào memory/. Load khi cần ghi lại kinh nghiệm. -->
+# Workflow: Learn (tự học)
+
+> Sau mỗi bug khó, incident, hoặc khi người dùng sửa cách làm — agent **chủ động ghi lại** để lần sau không lặp. Đây là thứ biến `memory/` thành vòng lặp sống thay vì file chết.
+
+## Khi nào chạy
+- Vừa fix xong một bug đáng nhớ (root cause không hiển nhiên).
+- Sau postmortem một incident.
+- Người dùng chỉnh cách làm: *"lần sau làm X thay vì Y"*, *"đừng bao giờ Z"*.
+
+## Ghi vào đâu
+| Loại | File |
+|---|---|
+| Bài học chung (cách làm) | `memory/lessons-learned.md` — *chuyện gì → học được gì → đổi cách làm thế nào* |
+| Bug hay tái diễn | `memory/common-bugs.md` — *triệu chứng → nguyên nhân gốc → cách xử* |
+| Quy trình gỡ rối theo tình huống | `memory/troubleshooting.md` |
+| Quyết định kiến trúc | tạo ADR: `agent-kb adr <tiêu đề>` |
+
+## Quy tắc
+- Mục **ngắn gọn, có ngày** (YYYY-MM-DD). Append, không sửa lịch sử.
+- Chỉ ghi cái **khái quát hoá được** (có thể lặp ở task khác) — không ghi chi tiết vụn dùng một lần.
+- Trùng mục cũ → **cập nhật** mục đó, đừng tạo bản sao.
+- **Không ghi** secret/PII/dữ liệu nhạy cảm.
+- Mơ hồ "có đáng ghi không" → hỏi người dùng một câu, đừng tự phình memory.

package/template/ai/workflows/release.md

@@ -0,0 +1,23 @@
+<!-- Mục đích: quy trình release. -->
+# Workflow: Release
+
+## Trước khi release (gate)
+- [ ] Toàn bộ test xanh trên CI; không lỗi lint/build.
+- [ ] Đã review & merge xong; nhánh release cập nhật từ main.
+- [ ] Migration DB (nếu có) đã kiểm thử và có kế hoạch rollback.
+- [ ] Biến môi trường / secret cho version mới đã sẵn sàng.
+
+## Phát hành
+1. **Version** — bump theo SemVer: MAJOR (phá vỡ tương thích) / MINOR (thêm tính năng) / PATCH (sửa lỗi).
+2. **Changelog** — ghi thay đổi theo nhóm Added / Changed / Fixed / Removed.
+3. **Tag** — gắn tag version, tạo release note.
+4. **Deploy** — theo `skills/devops/deployment.md` (ưu tiên rolling/blue-green để zero-downtime).
+
+## Sau release
+- [ ] Smoke test các luồng chính trên production.
+- [ ] Theo dõi metric/log/error rate trong khoảng đầu sau deploy.
+- [ ] Có sự cố → `workflows/incident-response.md` (rollback nếu cần).
+
+## Nguyên tắc
+- Release nhỏ, thường xuyên hơn là gom lớn.
+- Tránh deploy sát giờ nghỉ / cuối tuần khi không có người trực.

package/template/github/copilot-instructions.md

@@ -0,0 +1,5 @@
+# Copilot Instructions
+
+Toàn bộ rule, tech-stack, coding-standards và cách load context nằm ở `AGENTS.md` tại gốc repo.
+Hãy đọc và tuân theo `AGENTS.md`, đặc biệt phần "Router: task → file cần đọc".
+Chỉ load file trong `.ai/` khớp với task hiện tại; không nuốt cả thư mục.

package/template/tools/pointer.md

@@ -0,0 +1,5 @@
+# agent-kb
+
+Toàn bộ rule, tech-stack, coding-standards và cách load context nằm ở `AGENTS.md` tại gốc repo.
+Hãy đọc và tuân theo `AGENTS.md`, đặc biệt phần "Router: task → file cần đọc thêm".
+Chỉ load file trong `.ai/` khớp với task hiện tại; không nuốt cả thư mục.