openmoneta-dev-kit 1.9.0

package/skills/module-architect/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: module-architect
+description: Quy tắc chia module theo SRP (1 module = 1 trách nhiệm, có README riêng) + workflow update README sau khi sửa code. KHÔNG đếm dòng để tách. Dùng ở Bước 2 (thiết kế) và Bước 5 (update doc) của quy trình 6 bước.
+---
+
+# Module Architect
+
+Skill này phụ trách 2 trách nhiệm của quy trình 6 bước:
+
+- **Bước 2 — Thiết kế**: chia module theo SRP, quyết định khi nào cần module mới.
+- **Bước 5 — Update doc**: sync `README.md` của module sau khi code đổi (đã merge từ skill `doc-maintainer` cũ).
+
+Mục tiêu chung: cấu trúc code dễ navigate cho cả người và AI, tiết kiệm token khi đọc.
+
+## Phần 1 — Thiết kế module (Bước 2)
+
+### Nguyên tắc cốt lõi
+
+#### 1. Single Responsibility
+
+Mỗi module trả lời được câu: "Module này làm gì?" trong 1 câu, KHÔNG có chữ "và".
+
+- ✅ "Xử lý xác thực JWT cho API requests"
+- ❌ "Xử lý JWT và quản lý session và send email" (3 trách nhiệm → 3 module)
+
+#### 2. Tránh "lò xo" — tách khi vi phạm SRP, KHÔNG vì đếm dòng
+
+> **KHÔNG** có hard rule về số dòng. Câu hỏi đúng KHÔNG phải "file này bao nhiêu dòng?" mà là "file này đang làm bao nhiêu việc khác nhau?". 1 file 800 dòng làm 1 việc = OK. 1 file 200 dòng làm 4 việc = tách.
+
+Khi nào cân nhắc tách (theo SRP):
+
+- File mô tả được trong 1 câu KHÔNG có chữ "và" → đang OK, không cần tách dù dài.
+- File phải có chữ "và" để mô tả → SRP violation → tách (dù 100 dòng).
+- File khó đặt tên ngắn gọn → mơ hồ trách nhiệm → tách.
+
+Khi nào IGNORE rule (không tách dù dài):
+
+- Generated code (Prisma client, GraphQL schema, OpenAPI types).
+- Pure types/constants/schemas (không có logic).
+- Test fixtures, seed data.
+- Config files (webpack, playwright, biome, ...).
+- File có cohesion cực cao (vd 1 state machine 500 dòng cho 1 workflow rõ ràng).
+
+#### 3. Mỗi module có `README.md` riêng (3 sections, lean)
+
+```markdown
+# <Tên module>
+
+**Trách nhiệm**: <1 câu, không có chữ "và">
+
+## Public API
+
+- `funcA(arg1: X, arg2: Y): Z` — mô tả 1 dòng
+- `class Foo` — mô tả 1 dòng
+
+## Dependencies
+
+- Internal: `modules/auth`, `modules/db`
+- External: `axios`, `zod`
+```
+
+> Chỉ 3 sections. KHÔNG thêm Owner/Stability/Cách dùng/Anti-patterns vào README mặc định — chúng dễ stale và AI hiếm khi dùng. Nếu module có quirk đặc biệt (vd phải init theo thứ tự), thêm section `## Lưu ý` ngắn ≤5 bullet.
+
+### Cấu trúc folder mẫu
+
+```
+src/modules/<module-name>/
+├── README.md              # Bắt buộc (3 sections)
+├── index.ts               # Public API (re-export)
+├── types.ts               # TypeScript types/interfaces
+├── <core>.ts              # Logic chính
+├── <helpers>.ts           # Helpers nội bộ (không export)
+└── __tests__/
+    └── <core>.test.ts
+```
+
+### Dependency rules
+
+- Module **CHỈ** import từ:
+  - Public API của module khác (qua `index.ts`)
+  - External packages
+- KHÔNG import file nội bộ của module khác (vd: `modules/auth/internals/foo.ts`).
+- KHÔNG có circular dependency. Phát hiện → tách common module mới.
+
+### Khi nào tách module (đã có)
+
+Tách khi xảy ra ít nhất 1 (đều là **SRP signal**):
+
+- Module thay đổi vì >2 lý do business khác nhau.
+- 2 phần của module có lifecycle deploy/release khác nhau.
+- 2 phần có owner/team khác nhau.
+- Mô tả trách nhiệm phải dùng chữ "và".
+- Test setup của 2 phần khác xa nhau.
+
+### Khi nào TẠO module mới (BẮT BUỘC, không nhét vào module cũ)
+
+> Mục tiêu: cô lập sửa code, giảm xung đột. Mỗi feature mới gần như luôn xứng đáng có module riêng.
+
+Trigger ép tạo module mới (đều là **SRP/concept signal**):
+
+1. **Feature mới có concept business riêng** (vd: "Notifications" — gửi email/push/SMS) → tạo module `notifications/`. KHÔNG nhét vào `utils/` / `common/` / `shared/`.
+2. **Sửa module cũ thêm trách nhiệm thứ 2** vi phạm SRP → tách trách nhiệm mới ra module riêng.
+3. **Code mới không thuộc trách nhiệm rõ ràng của module nào hiện có** → tạo module riêng tên theo concept business.
+4. **2 feature dùng chung logic non-trivial** → extract ra module `<concept>/`, không paste duplicate.
+
+#### Anti-pattern (TUYỆT ĐỐI tránh)
+
+- Nhét code mới vào `utils/` / `common/` / `helpers/` / `shared/` "cho tiện".
+- Đặt tên module generic kiểu `core`, `lib`, `misc` — bắt buộc tên theo **concept business** (`auth`, `billing`, `notifications`, `tenant`, ...).
+- Tạo module mới cho 1 utility nhỏ trivial (vd: 1 hàm `formatDate`) → gộp vào module gần nhất có cùng concept.
+
+### Workflow khi feature mới
+
+Trước khi viết code, ở Bước 2 plan:
+
+1. Feature này thuộc **concept business** nào? Đặt tên module candidate.
+2. Search `docs/INDEX.md` (bảng "Modules hiện có" + "Token Routing") xem module đó đã có chưa.
+3. **CHƯA có** + thỏa ≥1 trigger trên → tạo `docs/modules/<new-slug>/README.md` (3 sections) + tạo source folder tương ứng.
+4. **ĐÃ có** → check section "Trách nhiệm": feature mới có khớp 1 câu trách nhiệm không? Khớp → reuse. Không khớp → tạo module mới.
+
+## Phần 2 — Workflow cho dự án EXISTING (BẮT BUỘC trước khi sang Bước 3)
+
+> Khi vào dự án **đã có code sẵn** (không khởi tạo bằng `init-project.sh`), AI thường bỏ sót Bước 2 vì code đã tồn tại. Workflow sau bắt buộc chạy 1 lần đầu cho mỗi dự án existing.
+
+### Bước 2.0 — Auto-detect module có sẵn
+
+```bash
+# Monorepo (apps/ + packages/)
+ls apps/ 2>/dev/null | sed 's|^|apps/|'
+ls packages/ 2>/dev/null | sed 's|^|packages/|'
+
+# Single-repo (src/modules/)
+ls src/modules/ 2>/dev/null | sed 's|^|src/modules/|'
+
+# Fallback
+ls src/ 2>/dev/null | sed 's|^|src/|'
+```
+
+### Bước 2.1 — Map module thực → folder docs
+
+Quy ước slug:
+
+| File path mẫu | Module slug | Docs path |
+|---|---|---|
+| `apps/landing/src/...` | `apps-landing` | `docs/modules/apps-landing/` |
+| `packages/tenant/src/...` | `packages-tenant` | `docs/modules/packages-tenant/` |
+| `src/modules/auth/...` | `auth` | `docs/modules/auth/` |
+| `src/auth/...` (single-repo, không có `modules/`) | `auth` | `docs/modules/auth/` |
+
+> Helper: `bash ~/.cursor/scripts/list-affected-modules.sh .cursor/.session-changes.json` infer slug từ file đã sửa.
+
+### Bước 2.2 — Backfill khi chạm vào module chưa có docs
+
+Khi plan sẽ sửa module mà `docs/modules/<slug>/` **chưa tồn tại**:
+
+1. Tạo `docs/modules/<slug>/README.md` với 3 sections (Trách nhiệm + Public API + Dependencies). Đọc `package.json` + entry point của module để fill nội dung.
+2. **Cập nhật `docs/INDEX.md`**:
+   - Thêm dòng vào bảng "Modules hiện có".
+   - **BẮT BUỘC: thêm 3-5 keyword (VN+EN) vào bảng "Feature/Keyword → Module"** để hook `enforce-docs-first` + Bước 1 token-aware reading hoạt động hiệu quả. Vd module `auth` keyword: "đăng nhập, login, OAuth, JWT, session, authentication".
+
+### Bước 2.3 — Token Routing maintenance (CRITICAL)
+
+> Bảng "Feature/Keyword → Module" trong `docs/INDEX.md` là **tim của hệ thống token-aware**. Stale → AI không tìm được module → đọc loạn → tốn token.
+
+Quy tắc maintenance:
+
+- **Tạo module mới** → thêm dòng + 3-5 keyword (VN+EN).
+- **Đổi tên module** → update slug trong cột "Module liên quan".
+- **Xóa module** → xóa dòng + check không có file nào còn ref module đó.
+- **Module mở rộng concept** (vd `auth` thêm SSO) → thêm keyword mới vào dòng đã có.
+
+## Phần 3 — Update README sau code đổi (Bước 5, merge từ doc-maintainer)
+
+> Đây là phần đuôi tự nhiên của Bước 2 — module đã thiết kế xong, code đã sửa, giờ sync README để session sau AI đọc lại không bị lệch.
+
+### Bước 5 workflow — Sync module README (BẮT BUỘC)
+
+> Hook `verify-completion` Check 6 sẽ **CHẶN** session kết thúc nếu module bị sửa nhưng không có `docs/modules/<slug>/README.md`.
+
+**Cách xác định module từ file path** (cho file đã sửa trong session):
+
+| File path mẫu | Module slug | Docs path |
+|---|---|---|
+| `apps/landing/src/x.ts` | `apps-landing` | `docs/modules/apps-landing/` |
+| `packages/tenant/src/y.ts` | `packages-tenant` | `docs/modules/packages-tenant/` |
+| `src/modules/auth/z.ts` | `auth` | `docs/modules/auth/` |
+| `src/auth/z.ts` (no `modules/`) | `auth` | `docs/modules/auth/` |
+
+> Helper script: `bash ~/.cursor/scripts/list-affected-modules.sh .cursor/.session-changes.json`.
+
+**Workflow cho mỗi module slug**:
+
+1. Nếu `docs/modules/<slug>/` **chưa tồn tại** → backfill theo Bước 2.2 ở trên.
+2. Mở `docs/modules/<slug>/README.md`.
+3. Check section **Public API**:
+   - Có function/class mới đã export? → thêm vào.
+   - Có function/class bị xóa hoặc đổi signature? → update/xóa.
+4. Check section **Dependencies**:
+   - Có `import` mới từ module khác? → thêm.
+   - Có `import` bị xóa? → xóa.
+5. Nếu module **mới được backfill** ở Bước 2.2 → đảm bảo `docs/INDEX.md` đã có trong bảng "Modules hiện có" + Token Routing.
+
+> KHÔNG cần update `changelog.md` cấp module — v1.5.0 bỏ enforcement này. Lịch sử dùng `git log` thay.
+
+### Anti-patterns
+
+- ❌ Copy nguyên block code vào README (sẽ stale).
+- ❌ Viết tutorial dài dòng — README chỉ cần Public API list.
+- ❌ Không update Token Routing khi tạo module mới → AI sẽ không tìm thấy.
+- ❌ Viết "TODO: update later" → KHÔNG defer, làm ngay.
+- ❌ Viết bằng tiếng Anh khi project rule là tiếng Việt.
+
+### Checklist trước khi đánh dấu Bước 5 xong
+
+- [ ] Module README đã sync với public API thực tế (nếu API đổi).
+- [ ] Module mới được tạo → đã thêm vào bảng "Modules hiện có" + Token Routing trong `docs/INDEX.md`.
+- [ ] Plan đánh dấu `Status: Done`.
+- [ ] Plan file đã `git mv` sang `plans/archive/<file>.md` (auto-archive).
+- [ ] `plans/INDEX.md` đã chuyển plan từ Active sang Archived.
+
+## Anti-overengineering checklist (Karpathy #2)
+
+> Tham khảo: [`templates/karpathy-reference.md`](../../templates/karpathy-reference.md) — nguyên tắc "Simplicity First".
+
+Trước khi commit code, tự hỏi từng câu. **CÓ → simplify trước commit:**
+
+- [ ] Code có abstraction (interface / abstract class / Protocol) chỉ có **1 implementation** không?
+- [ ] Có class với suffix `Factory` / `Manager` / `Helper` / `Service` mà chỉ wrap 1 function không?
+- [ ] Có config / option / flag không được yêu cầu, "phòng khi sau cần" không?
+- [ ] Có error handling cho case **không thể xảy ra** trong contract hiện tại không?
+- [ ] Code 100+ dòng cho task có thể giải bằng 30 dòng không?
+- [ ] Senior engineer review sẽ nói "overcomplicated" không?
+
+Nếu CÓ ≥1 câu → rewrite đơn giản hơn TRƯỚC khi commit.
+
+### Pattern cấm trừ khi user yêu cầu rõ
+
+- Generic types phức tạp (`Result<Either<Maybe<T>, E>>`) cho code không cần generic.
+- Plugin system / strategy pattern khi chỉ có 1 strategy.
+- Event bus / pub-sub cho 2 component giao tiếp.
+- Dependency injection container cho < 5 dependency.
+- Cache layer cho data đọc < 10 lần / giờ.
+- Wrapper class chỉ để rename method của lib bên ngoài.
+
+### Pattern CHO PHÉP
+
+- Test fixture / mock có abstraction (vì test cần variation).
+- Public library API (cần stable interface, dù chỉ 1 internal impl).
+- Khi user yêu cầu rõ và có lý do business cụ thể.
+- Validate input của user (input validation ≠ handle impossible).
+
+### Quy tắc 200 → 50
+
+Sau khi viết xong implementation, đọc lại:
+- Có thể giảm xuống 50% dòng mà vẫn đủ chức năng + đủ test pass không?
+- Nếu có → rewrite. Code ngắn hơn = ít bug hơn + dễ maintain hơn.

package/skills/plan-writer/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: plan-writer
+description: Adaptive planning cho quy trình 6 bước. Task nhỏ có thể không cần plan. Task lớn/rủi ro phải tạo repo plan trong plans/YYYY-MM-DD-<slug>.md với Status: Draft, trình user review, chỉ triển khai sau khi user approve và đổi Status: In Progress.
+---
+
+# Plan Writer
+
+Đây là **Bước 3** của quy trình 6 bước. Từ v1.7.0, plan là **adaptive**:
+
+- Task nhỏ/rõ ràng: có thể không cần plan, Agent triển khai luôn.
+- Task lớn/rủi ro: BẮT BUỘC tạo repo plan với `Status: Draft`, trình user review, chỉ code sau khi user approve và đổi `Status: In Progress`.
+- Nếu đã có plan `In Progress`: hook `check-plan-exists` enforce file scope.
+- Nếu có plan `Draft`: hook chặn code edit để bảo đảm user review trước triển khai.
+
+Hook `verify-completion` Check 9 sẽ CHẶN session kết thúc nếu plan không có section "## Hiểu yêu cầu" (audit trail clarify).
+
+## Naming convention
+
+```
+plans/YYYY-MM-DD-<slug-kebab-case>.md
+```
+
+- `YYYY-MM-DD`: ngày tạo plan (theo local timezone).
+- `<slug>`: ngắn gọn, mô tả tính năng/fix chính. Ví dụ: `add-google-login`, `fix-cart-overflow`, `refactor-payment-service`.
+## Khi nào cần plan?
+
+### Không cần plan (Agent làm luôn)
+
+Chỉ áp dụng khi TẤT CẢ điều kiện đúng:
+- ≤1-2 file thường.
+- Diff nhỏ, không đổi public API.
+- Yêu cầu rõ, không có nhiều hướng triển khai.
+- Không chạm dữ liệu nhạy cảm, auth, payment, admin, permission, database, migration, deploy.
+- Không tạo/xóa nhiều file, không refactor lớn.
+
+Ví dụ: fix typo, đổi text UI nhỏ, sửa CSS rõ ràng, update docs nhỏ, đổi 1 hằng số.
+
+### Bắt buộc tạo plan + user review
+
+Tạo plan nếu có BẤT KỲ dấu hiệu nào:
+- Task mơ hồ hoặc có nhiều hướng triển khai.
+- Đụng >2 file code hoặc >1 module.
+- Refactor, migration, schema/database.
+- Auth/OAuth/session/token/secret/security.
+- Payment/billing/checkout/subscription.
+- Admin/permission/RBAC/role.
+- Deploy/infra/CI/CD/git flow.
+- Public API change hoặc nguy cơ regression.
+- User yêu cầu "lên kế hoạch", "plan", "thiết kế", "phân tích kỹ".
+
+Plan tạo trong Agent mode phải dừng ở `Status: Draft` để user review.
+
+## Review gate bắt buộc
+
+Khi tạo plan:
+1. Tạo file trong `plans/YYYY-MM-DD-<slug>.md`.
+2. Set `**Status**: Draft`.
+3. Trình bày tóm tắt plan cho user.
+4. Hỏi user bằng `AskQuestion`:
+   - Approve plan và triển khai.
+   - Sửa plan.
+   - Hủy plan.
+   - Làm nhanh không cần plan (chỉ cho task không nhạy cảm).
+5. Chỉ khi user approve: đổi `Status: In Progress`, rồi mới edit code.
+
+Không được tự tạo plan rồi tự approve.
+
+## Template chuẩn (5 sections)
+
+```markdown
+# <Tiêu đề plan ngắn gọn>
+
+**Status**: Draft | In Progress | Done
+**Created**: YYYY-MM-DD HH:mm
+**Tiny**: no | yes (≤1 file, ≤20 dòng diff, không tạo/xóa file)
+
+## Hiểu yêu cầu
+
+> BẮT BUỘC. Hook `verify-completion` Check 9 chặn nếu trống.
+
+**Câu hỏi đã hỏi user** (skip nếu task trivial):
+- Q: <câu hỏi> → A: <user trả lời>
+
+HOẶC
+
+**Lý do skip clarify**: <vd: "user spec đầy đủ trong message", "fix typo rõ ràng từ screenshot">
+
+## Mục tiêu
+
+<1-2 câu: làm gì, vì sao>
+
+## Modules ảnh hưởng
+
+> Hook `verify-completion` Check 6 sẽ chặn nếu module ở đây không có README. Quy ước slug xem skill `module-architect` Bước 2.1.
+
+| Module | Docs path | Trạng thái | Files thay đổi (subset) |
+|---|---|---|---|
+| `apps-landing` | `docs/modules/apps-landing/` | có sẵn | `apps/landing/src/middleware.ts` |
+| `notifications` | `docs/modules/notifications/` | NEW | `src/modules/notifications/email.ts` |
+| `legacy-cart` | `docs/modules/legacy-cart/` | backfill | `src/cart/checkout.ts` |
+
+Cột "Trạng thái":
+- `có sẵn` — module đã có docs/source.
+- `NEW` — sẽ tạo mới (theo trigger `module-architect` "Khi nào TẠO module mới").
+- `backfill` — module có source nhưng chưa có docs, cần tạo `docs/modules/<slug>/README.md` trước khi sang Bước 4.
+
+Quy tắc:
+- Mỗi file ở section "Files ảnh hưởng" PHẢI map về 1 dòng trong bảng này.
+- Plan chỉ đụng `docs/`, `plans/`, `.gitignore`, `.env.example` → có thể bỏ qua section này (hook tự skip).
+
+### Cross-module discipline (>2 module = red flag)
+
+Nếu bảng "Modules ảnh hưởng" có **>2 module** → BẮT BUỘC thêm subsection:
+
+```markdown
+### Lý do cross-module
+
+<Vì sao plan này phải đụng N module thay vì cô lập trong 1-2 module?>
+
+Đã cân nhắc các option đơn giản hơn:
+- [ ] Có thể giới hạn trong 1-2 module bằng cách thêm public API ở module X? → Không, vì ...
+- [ ] Có thể tách thành nhiều plan nhỏ, mỗi plan 1 module? → Không, vì ...
+- [ ] Có phải đây là cross-cutting concern (logging, telemetry, i18n) không? → ...
+```
+
+Hook `verify-completion` Check 7 (WARN) sẽ cảnh báo nếu session đụng >3 module.
+
+## Files ảnh hưởng
+
+> Hook `check-plan-exists` đọc section này. Liệt kê chính xác đường dẫn file sẽ tạo/sửa.
+
+- `src/auth/google.ts` (create)
+- `src/components/LoginButton.tsx` (modify)
+- `tests/e2e/login.spec.ts` (create)
+
+## Tasks
+
+> **Karpathy #4**: mỗi task PHẢI có verify check cụ thể. Tham khảo: [`templates/karpathy-reference.md`](../../templates/karpathy-reference.md).
+
+Format:
+
+- [ ] Task 1: <hành động cụ thể> → **Verify**: <lệnh / cách kiểm tra cụ thể>
+- [ ] Task 2: <hành động cụ thể> → **Verify**: <...>
+
+Ví dụ tốt:
+
+- [ ] Thêm endpoint `POST /api/login` → **Verify**: `curl -X POST localhost:3000/api/login -d '{"email":"x"}' | jq .status` trả `401`
+- [ ] Validate email format → **Verify**: unit test `auth.test.ts::validateEmail` 5 case pass
+
+Ví dụ xấu (thiếu verify cụ thể):
+
+- [ ] ~~Login chạy được~~ ❌ (không đo được)
+- [ ] ~~Code clean~~ ❌ (vô nghĩa)
+```
+
+## Plan minimal (chỉ khi vẫn muốn audit cho task nhỏ)
+
+**Định nghĩa task nhỏ** (TẤT CẢ điều kiện phải đúng):
+- Edit ≤1 file
+- Diff ≤20 dòng
+- Không tạo file mới
+- Không xóa file
+- Không đổi public API
+- Không đụng auth/payment/PII
+
+Vd: fix typo, đổi 1 string i18n, bump version 1 dependency, đổi 1 hằng số.
+
+**Template tiny:**
+
+```markdown
+# Fix typo header (tiny)
+
+**Status**: Done
+**Created**: 2026-04-23 16:42
+**Tiny**: yes (1 file, 3 dòng)
+
+## Hiểu yêu cầu
+
+**Lý do skip clarify**: typo rõ ràng từ screenshot user gửi.
+
+## Files ảnh hưởng
+
+- `src/components/Header.tsx` (modify)
+```
+
+Plan minimal là optional. Nếu sau khi sửa thấy vượt ngưỡng (>20 dòng / >1 file / đổi API) → tạo plan đầy đủ và xin user review trước khi tiếp tục.
+
+## Sau khi tạo plan
+
+1. Update `plans/INDEX.md`:
+   - Thêm dòng vào bảng "Active" với link và status `Draft`.
+2. Chờ user review/approve.
+3. Đổi Status từ `Draft` → `In Progress` sau khi user approve.
+4. Tick checkbox `[x]` cho mỗi task xong.
+5. Đổi Status → `Done` ở Bước 5 sau khi update module README xong.
+6. **AUTO-ARCHIVE**: ngay khi đổi Status → Done, chạy:
+   ```bash
+   git mv plans/<file>.md plans/archive/<file>.md
+   ```
+   Update `plans/INDEX.md` (chuyển plan từ Active → Archived). Lý do: giảm noise trong `plans/` để session sau AI scan ít file hơn.
+
+## Hook behavior (v1.7.0)
+
+- Không có plan active + file thường → hook allow.
+- Không có plan active + file nhạy cảm/rủi ro cao → hook block và yêu cầu plan.
+- Có plan `Draft` → hook block code edit cho đến khi user approve.
+- Có plan `In Progress` → hook enforce file nằm trong `## Files ảnh hưởng` / `## Files thay đổi`.
+
+## Surgical Changes (Karpathy #3)
+
+> Hook chỉ chặn **file** ngoài scope. Tự discipline ở **line-level**:
+
+- **Mỗi dòng đổi phải trace về 1 task trong plan này.** Không có task tương ứng → không đổi.
+- KHÔNG "improve" code adjacent: đừng đổi format, comment, tên biến không liên quan task.
+- KHÔNG refactor function chưa hỏng vì plan này. Refactor là task riêng, plan riêng.
+- **Match existing style** (indent, naming, import order).
+- Phát hiện dead code không liên quan → ghi vào section "Notes" của plan, KHÔNG xóa.
+
+## AC ví dụ minh họa (cho task lớn)
+
+Task >5 file hoặc breaking change → có thể tự thêm section `## Acceptance Criteria` (optional). Format:
+
+**Tốt (đo lường được):**
+- "POST `/api/login` với body `{idToken: string}` trả `200 {user, accessToken}` hoặc `401 {error}`."
+- "Button 'Đăng nhập Google' click mở popup OAuth, success → redirect `/dashboard`, fail → toast lỗi 5s."
+
+**Xấu (mơ hồ):**
+- "Login chạy được" ❌
+- "UI đẹp" ❌

package/skills/requirement-analysis/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: requirement-analysis
+description: Phân tích yêu cầu user, đọc TOKEN-AWARE docs/INDEX.md (hook enforced), sinh giả thuyết/edge case/rủi ro và đặt câu hỏi critical để làm rõ yêu cầu, phân tích mọi trường hợp có thể xảy ra, phản biện và đề xuất phương án tối ưu hơn nếu có TRƯỚC khi lập plan. Output câu hỏi/trả lời sẽ ghi vào plan section "Hiểu yêu cầu" (verify-completion Check 9 enforce).
+---
+
+# Phân tích yêu cầu
+
+Đây là **Bước 1** của quy trình 6 bước. KHÔNG được code/plan khi chưa hoàn tất bước này.
+
+> **3 nguyên tắc bất biến của bước này** (theo yêu cầu user):
+> 1. Hỏi clarify TRƯỚC khi plan/code (trừ task trivial → khai báo lý do skip).
+> 2. Đọc doc liên quan + phân tích module/file ảnh hưởng + đánh giá có cần module mới không.
+> 3. Output câu hỏi/trả lời/lý do skip → ghi vào plan section "## Hiểu yêu cầu" (Bước 3).
+
+## Workflow 5 bước con
+
+### Bước 1.1 — Đọc context dự án TOKEN-AWARE (HOOK ENFORCED)
+
+> **HOOK ENFORCEMENT (v1.4.3+)**: Hook `enforce-docs-first` sẽ **chặn mọi `Read/Glob/Grep` lên `apps/`, `packages/`, `src/`, `lib/`, `components/`, `server/`, `modules/`** nếu chưa đọc `docs/INDEX.md` trong session. Marker: `<workspace>/.cursor/.docs-index-read` (auto-clean ở mỗi sessionStart).
+
+**Đọc 2 file lõi (BẮT BUỘC theo thứ tự)**:
+
+1. **`docs/INDEX.md` ĐẦU TIÊN**:
+   - Bảng "Modules hiện có" → danh sách module + responsibility.
+   - Bảng "Feature/Keyword → Module (Token Routing)" → map keyword user → module candidate.
+2. **`plans/INDEX.md`** → check plan active có overlap không (tránh trùng work).
+
+### Bước 1.2 — Map yêu cầu → module candidate
+
+- Match keyword trong yêu cầu user với bảng "Token Routing" → 1-3 module candidate.
+- Vd: user nói "thêm Google login" → keyword `auth, login, OAuth, JWT` → module `auth` / `apps-admin-ui`.
+- Nếu không match → đây là feature mới → áp dụng skill `module-architect` Bước "Khi nào TẠO module mới".
+
+### Bước 1.3 — Đọc CHỈ README của module candidate
+
+- `docs/modules/<candidate>/README.md` (3 sections: Trách nhiệm, Public API, Dependencies).
+- **KHÔNG đọc** README của module không liên quan.
+- **KHÔNG scan** `docs/architecture/`, `docs/api/`, `docs/security/` trừ khi yêu cầu user trực tiếp đụng đến.
+- Sau khi đọc README → mới được Read/Grep/Glob source code của module đó (hook đã unlock).
+
+#### Anti-pattern token waste
+
+- ❌ Đọc tất cả `docs/modules/*/README.md` "để hiểu toàn bộ dự án" → 19 module × 30 dòng = ~9k tokens phí phạm.
+- ❌ Đọc `docs/architecture/overview.md` đầy đủ cho task fix bug nhỏ.
+- ❌ `Read` file source code không thuộc module candidate.
+
+#### Khi nào ĐƯỢC đọc rộng
+
+- User explicit yêu cầu refactor cross-cutting (vd "đổi log format toàn bộ").
+- Task affect ≥3 module → đọc thêm để hiểu dependency.
+- Audit security/performance toàn bộ dự án.
+
+### Bước 1.4 — Liệt kê 3 nhóm + đánh giá module
+
+Viết tóm tắt yêu cầu (2-3 câu) **bằng ngôn từ của bạn** + 3 nhóm:
+
+```markdown
+**Tóm tắt yêu cầu**: <2-3 câu>
+
+**Module ảnh hưởng** (theo Token Routing + đọc source):
+- `<slug>` (có sẵn / NEW / backfill) — vì sao
+- `<slug>` ...
+
+**Giả thuyết** (assume mà chưa chắc):
+- ...
+
+**Edge cases** (dễ bị bỏ sót):
+- ...
+
+**Rủi ro** (kỹ thuật / business / bảo mật):
+- ...
+```
+
+> Output này sẽ ghi vào `## Hiểu yêu cầu` của plan ở Bước 3.
+
+### Bước 1.5 — Hỏi clarify (BẮT BUỘC, trừ task trivial)
+
+> **Nguyên tắc bất biến #1 của user**: AI tự đặt giả thuyết + truy vấn user TRƯỚC khi plan/code. Hook `verify-completion` Check 9 sẽ chặn nếu plan thiếu section "## Hiểu yêu cầu".
+
+Dùng tool `AskQuestion`. Quy tắc:
+
+- Hỏi câu **critical** — câu trả lời sẽ thay đổi đáng kể plan/implementation.
+- KHÔNG hỏi câu user đã ngầm trả lời trong yêu cầu.
+- KHÔNG hỏi vì sợ sai — hỏi để làm rõ ambiguity thực sự.
+- Mỗi câu nên có **2-4 options cụ thể**, kèm trade-off ngắn.
+- Số lượng câu hỏi tùy thuộc vào độ phức tạp của task. Task phức tạp nhiều ẩn số có thể cần nhiều câu hơn để làm rõ toàn bộ yêu cầu trước khi lập plan.
+
+#### Khi nào ĐƯỢC skip clarify (task trivial)
+
+- Fix typo rõ ràng (user gửi screenshot / quote chính xác).
+- Bump version 1 dependency theo yêu cầu cụ thể.
+- Đổi 1 hằng số / string i18n theo spec rõ.
+- Format code / lint fix.
+- Rename file/biến theo yêu cầu rõ.
+
+→ Khi skip, BẮT BUỘC ghi vào plan: `**Lý do skip clarify**: <ngắn gọn>`. Hook Check 9 chấp nhận lý do này.
+
+#### Khi nào BẮT BUỘC hỏi (kể cả nghe có vẻ rõ)
+
+- Feature mới có ≥2 cách implement với trade-off khác nhau.
+- Thay đổi behavior có thể ảnh hưởng user hiện tại.
+- Đụng auth/payment/PII/permission.
+- Plan có >2 module ảnh hưởng (cross-module).
+- User dùng từ mơ hồ ("cải thiện UI", "tối ưu performance", "refactor service").
+
+#### Ví dụ câu hỏi tốt
+
+```
+"Khi user đăng nhập Google fail, behavior nên là gì?"
+- Option A: Hiện modal lỗi + giữ nguyên trang
+- Option B: Redirect về /login với query ?error=
+- Option C: Fallback sang đăng nhập email
+```
+
+#### Ví dụ câu hỏi xấu
+
+- "Bạn muốn tôi làm gì?" (quá vague)
+- "Frontend hay backend?" (nên tự suy ra)
+- "Có cần test không?" (test on-demand, hỏi user nếu thật sự cần)
+
+### Bước 1.6 — Đề xuất cách đơn giản hơn (Karpathy #1)
+
+> Tham khảo: [`templates/karpathy-reference.md`](../../templates/karpathy-reference.md).
+
+Trước khi sang Bước 2, tự hỏi:
+
+- Có cách giải quyết bài toán user nêu **đơn giản hơn** không?
+- Nếu **CÓ** → trình bày trade-off ngắn cho user, **KHÔNG tự chọn**.
+
+Ví dụ:
+
+User: "Tạo abstract Repository pattern cho User CRUD."
+
+AI:
+> Tôi nhận thấy hiện chỉ có 1 implementation (Postgres). Repository pattern thường có giá trị khi có ≥2 backends.
+>
+> **Đề xuất thay thế**: dùng function `userRepo.findById(id)` đơn giản trong file `userRepo.ts`. Khi cần thêm backend mới sẽ refactor (đã có test bao phủ).
+>
+> Vẫn muốn pattern abstract như yêu cầu? Reply YES.
+
+#### Khi nào KHÔNG cần đề xuất
+
+- Task trivial (rename, sửa typo, format).
+- User đã giải thích rõ lý do business cho cách phức tạp.
+- Đã đề xuất ≥1 lần và user khẳng định.
+
+## Khi nào delegate sang subagent `requirement-analyst`
+
+- Yêu cầu rất lớn, cần đọc nhiều file/tài liệu (>5 file lớn).
+- Cần explore codebase rộng để hiểu impact.
+- Bạn cảm thấy sẽ tốn nhiều context cho việc phân tích.
+
+Subagent trả về tóm tắt + danh sách câu hỏi, parent agent dùng để hỏi user.
+
+## Output bắt buộc trước khi sang Bước 2
+
+- [ ] Đã đọc `docs/INDEX.md` (hook unlock cho phép Read source).
+- [ ] Tóm tắt yêu cầu (2-3 câu).
+- [ ] Liệt kê module ảnh hưởng (slug + trạng thái có sẵn / NEW / backfill).
+- [ ] Giả thuyết / edge cases / rủi ro.
+- [ ] Đã hỏi user đủ câu hỏi để làm rõ yêu cầu, phân tích trường hợp, phản biện và đề xuất phương án tối ưu (HOẶC đã có lý do skip clarify rõ ràng).
+- [ ] Đã cân nhắc cách đơn giản hơn (pass nếu đã tối giản).
+- [ ] User đã trả lời (nếu hỏi) → ghi vào plan section "## Hiểu yêu cầu" ở Bước 3.