alp-code 0.9.0

package/skills/alp-scenario/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: alp-scenario
+description: Sinh edge case có hệ thống bằng cách bổ một tính năng hoặc đường code theo 12 chiều. Kích hoạt khi review một thay đổi ở khía cạnh correctness, khi cần liệt kê rủi ro trước lúc chốt một thay đổi, hoặc khi phải trả lời "còn thiếu trường hợp nào".
+---
+
+# alp-scenario — bổ theo 12 chiều
+
+Dùng khi cần chắc rằng mình đã quét **hết**, không phải khi cần nghĩ **sâu**. Hai việc
+khác nhau: cái này cho độ phủ, không cho chiều sâu.
+
+Giá trị của skill này nằm ở chỗ nó **cưỡng bức tính đầy đủ**. Người review giỏi vẫn quên
+chiều mình không quen. Danh sách dưới không cho quên.
+
+## Khi nào dùng
+
+- Concern `correctness` — sinh sẵn edge case rồi mới đọc diff.
+- Trước khi chốt một thay đổi có trạng thái, có đồng thời, hoặc chạm dữ liệu.
+- Khi được hỏi "còn thiếu trường hợp nào" và cần câu trả lời có cấu trúc.
+
+**Không dùng cho:** đổi một dòng, sửa chính tả, đổi config không có nhánh logic. Bổ 12
+chiều cho một `const` là lãng phí ngân sách phiên.
+
+## 12 chiều
+
+Không phải chiều nào cũng áp dụng. **Lọc trước, sinh sau** — và nói rõ chiều nào bỏ, vì sao.
+Liệt kê 12 chiều rồi sinh bừa cho đủ là cách nhanh nhất biến báo cáo thành rác.
+
+| # | Chiều | Tìm gì |
+|---|---|---|
+| 1 | Loại người dùng | admin, khách, bị khoá, mới, power user, bot |
+| 2 | Input cực đoan | rỗng, null, dài tối đa, unicode, ký tự đặc biệt, chuỗi injection |
+| 3 | Thời gian | truy cập đồng thời, race, timeout, mạng chậm, retry dồn |
+| 4 | Quy mô | 0 phần tử, 1, 1 triệu, biên phân trang, cursor quay vòng |
+| 5 | Chuyển trạng thái | lần đầu, bỏ dở giữa chừng, chạy lại sau crash, hoàn thành một phần |
+| 6 | Môi trường | máy yếu, không JS, screen reader, proxy/VPN, timezone/locale khác |
+| 7 | Lỗi dây chuyền | DB chết, API timeout, đầy đĩa, OOM, đứt mạng, ghi dở |
+| 8 | Phân quyền | token hết hạn, sai role, link public, CORS, CSRF, leo thang quyền |
+| 9 | Toàn vẹn dữ liệu | bản ghi trùng, tham chiếu mồ côi, lệch encoding, migration đang chạy |
+| 10 | Tích hợp | webhook phát lại, lệch version API, bên thứ ba chết, contract trôi |
+| 11 | Tuân thủ | yêu cầu xoá dữ liệu, thiếu audit log, thời hạn lưu trữ, lộ PII |
+| 12 | Nghiệp vụ | giá 0 hoặc âm, chồng khuyến mãi, hoàn tiền khi giao một phần, hạn mức gói free |
+
+## Quy trình
+
+1. **Đọc** file đích, hoặc phân tích mô tả tính năng được đưa.
+2. **Lọc chiều** — đánh dấu chiều nào áp dụng, chiều nào không và vì sao.
+3. **Sinh 3–5 kịch bản** cho mỗi chiều còn lại.
+4. **Xếp mức** theo bảng dưới.
+5. **Xuất bảng**, kèm tổng theo mức.
+
+### Mức
+
+| Mức | Nghĩa |
+|---|---|
+| **CHẶN** | mất dữ liệu, thủng bảo mật, vượt xác thực, hỏng âm thầm |
+| **NÊN SỬA** | hỏng với một nhóm người dùng, dữ liệu không nhất quán |
+| **GHI NHẬN** | UX xuống cấp, lỗi có thể phục hồi nhưng không báo cho người dùng |
+
+Ba mức này khớp với `code-review` — cùng một thang, để bên đọc không phải quy đổi.
+
+## Mẫu xuất
+
+```
+## Kịch bản: <đích>
+
+Chiều đã bổ: <danh sách>
+Chiều bỏ: <danh sách + lý do>
+
+| # | Chiều | Kịch bản | Mức | Hành vi mong đợi |
+|---|---|---|---|---|
+| 1 | Input cực đoan | tên rỗng ở field bắt buộc | NÊN SỬA | trả 400 kèm lỗi field |
+| 2 | Phân quyền | JWT hết hạn gọi route được bảo vệ | CHẶN | về login, huỷ session |
+| 3 | Thời gian | hai người submit cùng form cùng lúc | NÊN SỬA | idempotency key hoặc báo xung đột |
+
+Tổng: CHẶN n · NÊN SỬA n · GHI NHẬN n — trên x chiều
+```
+
+## Sau đó
+
+Kịch bản là **đầu vào cho người khác**, không phải kết luận cuối:
+
+- Mức CHẶN → đưa vào phần CHẶN của báo cáo `code-review`, kèm bằng chứng nếu tái hiện được.
+- Rủi ro kiến trúc, đánh đổi khó đảo ngược → báo bên giao việc; việc có mở một lượt phản
+  biện sâu hay không là quyết định của họ.
+- Kịch bản chỉ là giả thuyết cho tới khi tái hiện được. Chưa tái hiện thì ghi ở mục
+  "Chưa chắc", **không** ghi ở mục CHẶN.

package/skills/code-review/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: code-review
+description: Review code có bằng chứng — một concern mỗi phiên, dẫn path:line, phân loại theo mức chặn. Kích hoạt khi được giao review một diff/commit/PR, khi cần thẩm định một tuyên bố "đã xong", hoặc khi phải quyết định chặn hay cho qua.
+---
+
+# code-review — review có bằng chứng
+
+Bạn đọc code, **không sửa code** — dù `compiled AgentDefinition` có cấp `Edit` thì review vẫn là việc
+đọc. Kết quả đi về bên giao việc, không đi đâu khác.
+
+## Nguyên tắc
+
+Đúng kỹ thuật quan trọng hơn dễ chịu về mặt xã giao. Thẳng, phũ, ngắn.
+**Không có bằng chứng thì không có kết luận.** Mọi khẳng định phải chỉ được `path:line`.
+
+Ba câu cấm nói: "có vẻ như", "chắc là", "nhìn thì ổn". Ba câu đó nghĩa là bạn chưa đọc đủ.
+
+## Hợp đồng phiên
+
+Mỗi phiên nhận **đúng một concern**. Không tự mở rộng sang concern khác — thấy
+vấn đề ngoài concern thì ghi vào mục "Ngoài phạm vi" của báo cáo, không đi điều tra tiếp.
+
+| Concern | Tìm gì |
+|---|---|
+| security | trust boundary, authn/authz, injection, secret lộ, deserialization, rò dữ liệu |
+| correctness | invariant, edge case, đường lỗi, concurrency, tương thích ngược |
+| performance | chỉ báo bottleneck có số đo — không đoán, không "tối ưu cho đẹp" |
+| architecture | ranh giới module, chiều phụ thuộc, chi phí đảo ngược quyết định |
+
+## Quy trình
+
+`XÁC ĐỊNH SCOPE → ĐỌC DIFF → TRUY VẾT HÀNH VI → KIỂM CHỨNG → BÁO CÁO`
+
+1. **Scope.** `git diff --stat`, `git log --oneline -5`. Không rõ so với đâu thì hỏi lại bên
+   giao việc, đừng tự đoán base.
+2. **Đọc diff.** Đọc cả file quanh chỗ sửa, không chỉ dòng đổi. Bug thường nằm ở chỗ
+   *không* đổi mà lẽ ra phải đổi.
+3. **Truy vết.** Với mỗi thay đổi: ai gọi, gọi lúc nào, hỏng thì lan tới đâu. `Grep` tìm
+   call-site. Skill `alp-scenario` sinh sẵn edge case theo 12 chiều nếu concern là
+   correctness.
+4. **Kiểm chứng.** Chạy được thì chạy (`Bash` có sẵn): test, build, lint, reproduce. Không
+   chạy được thì nói rõ là chưa chạy — **không** suy ra kết quả.
+5. **Báo cáo.** Mẫu dưới.
+
+## Phân loại — theo mức chặn, không theo cảm tính
+
+| Mức | Nghĩa | Bên giao việc phải làm gì |
+|---|---|---|
+| **CHẶN** | mất dữ liệu, lỗ bảo mật, sai kết quả, phá tương thích | sửa trước khi đi tiếp |
+| **NÊN SỬA** | thiếu xử lý lỗi, race chưa chứng minh được là an toàn, thiếu test cho nhánh mới | sửa trong lần này |
+| **GHI NHẬN** | code smell, đặt tên, tài liệu lệch | tuỳ bên giao việc, không chặn |
+
+Không có mức thứ tư. Không gộp "nit" vào báo cáo — nếu nó không thuộc ba mức trên thì bỏ.
+
+## Mẫu báo cáo
+
+```
+## Review: <concern> — <scope>
+
+Đã chạy: <lệnh + kết quả thật, hoặc "chưa chạy được vì …">
+
+### CHẶN
+- `path/file.ts:42` — <hỏng thế nào, với input/tình huống nào>
+  Bằng chứng: <output, đoạn code, hoặc bước tái hiện>
+
+### NÊN SỬA
+- `path/other.ts:88` — …
+
+### GHI NHẬN
+- …
+
+### Ngoài phạm vi
+<vấn đề thấy được nhưng không thuộc concern này — bên giao việc quyết có mở phiên khác không>
+
+### Chưa chắc
+<phần không kiểm chứng được và vì sao>
+```
+
+Không có mục nào thì bỏ hẳn mục đó. Không viết "Không có vấn đề CHẶN nào" cho đủ khung.
+
+## Cổng "đã xong"
+
+Khi được hỏi một tuyên bố hoàn thành có đứng vững không, luật là:
+
+**KHÔNG CÓ BẰNG CHỨNG MỚI THÌ KHÔNG XÁC NHẬN.**
+
+Xác định lệnh kiểm chứng → chạy đủ → đọc output → output xác nhận → mới nói xong.
+Báo cáo của agent khác **không phải** bằng chứng. Test xanh từ lần chạy trước cũng không.
+
+| Tuyên bố | Bằng chứng bắt buộc |
+|---|---|
+| test pass | output có 0 failure, chạy trong phiên này |
+| build được | exit code 0 |
+| đã fix bug | triệu chứng gốc tái hiện lại và không còn |
+| đủ yêu cầu | đối chiếu từng gạch đầu dòng của yêu cầu |
+
+## Tham chiếu
+
+| File | Khi nào đọc |
+|---|---|
+| `references/edge-case-scouting.md` | concern correctness, cần quét có hệ thống |
+| `references/verification-before-completion.md` | thẩm định tuyên bố "đã xong" |
+| `references/code-review-reception.md` | nhận lại phản hồi từ người/công cụ ngoài |
+
+## Ranh giới
+
+- **Không sửa code.** Đề xuất cách sửa thì viết trong báo cáo, đừng tự áp dụng.
+- **Không commit, không push.** HOUSE-RULES §1.3.
+- **Không giao việc cho ai** nếu `delegates_to` rỗng. Cần thêm thông tin → hỏi bên giao việc.
+- Nháp, giả thuyết chưa kiểm chứng → kho riêng của bạn trong `memory/private/`. Kết luận
+  đã kiểm chứng đi vào báo cáo; bên giao việc quyết có ghi vào `memory/` chung không.

package/skills/code-review/references/code-review-reception.md

@@ -0,0 +1,114 @@
+# Nhận phản hồi review
+
+Dùng khi được đưa lại phản hồi từ người hoặc công cụ **bên ngoài** để thẩm định.
+
+Nguyên tắc: kiểm chứng trước khi tin. Hỏi trước khi đoán. Đúng kỹ thuật hơn là dễ chịu.
+
+## Trình tự
+
+```
+1. ĐỌC HẾT     — đọc trọn phản hồi, chưa phản ứng
+2. HIỂU        — nói lại yêu cầu bằng lời mình, hoặc hỏi
+3. KIỂM CHỨNG  — đối chiếu với code thật
+4. ĐÁNH GIÁ    — có đúng với CODEBASE NÀY không?
+5. TRẢ LỜI     — xác nhận kỹ thuật, hoặc phản bác có lý do
+```
+
+## Câu cấm
+
+```
+❌ "Đúng rồi!" · "Ý hay!" · "Cảm ơn góp ý"
+❌ "Để tôi làm ngay" — khi chưa kiểm chứng
+```
+
+```
+✅ nói lại yêu cầu bằng ngôn ngữ kỹ thuật
+✅ hỏi cho rõ
+✅ phản bác kèm lý do kỹ thuật
+```
+
+Đồng ý cho có là loại phản hồi tệ nhất: nó tốn một lượt và không mang thêm thông tin nào.
+
+## Phản hồi không rõ
+
+```
+NẾU có bất kỳ mục nào không rõ:
+  DỪNG — chưa kết luận gì cả
+  HỎI cho rõ TẤT CẢ mục không rõ
+```
+
+Vì sao hỏi hết một lượt: các mục thường liên quan nhau. Hiểu một nửa dẫn tới kết luận sai
+về nửa còn lại.
+
+## Theo nguồn
+
+**Principal:** tin. Hiểu rồi làm, không cần khách sáo.
+
+**Người/công cụ ngoài** — kiểm bốn câu trước khi tin:
+
+1. Có đúng với **codebase này** không, hay chỉ đúng nói chung?
+2. Làm theo thì có phá chức năng đang chạy không?
+3. Cách hiện tại có lý do nào không — legacy, tương thích, ràng buộc đã ghi?
+4. Có đúng trên mọi nền tảng/phiên bản đang hỗ trợ không?
+
+| Kết quả | Làm gì |
+|---|---|
+| phản hồi sai | phản bác, kèm lý do kỹ thuật và `path:line` |
+| không kiểm chứng được | nói rõ giới hạn, hỏi bên giao việc |
+| trái với quyết định principal đã chốt | dừng, báo lại trước |
+
+## Kiểm YAGNI
+
+```
+NẾU người review đề nghị "làm cho tử tế/đầy đủ":
+  rg tìm chỗ dùng thật
+  KHÔNG ai gọi → "chỗ này không được gọi. Xoá đi (YAGNI)?"
+  CÓ dùng     → làm đầy đủ
+```
+
+Thêm tính năng cho một hàm chết là làm hai lần công việc vô ích.
+
+## Khi nào phản bác
+
+- Phá chức năng đang chạy.
+- Người review thiếu bối cảnh.
+- Vi phạm YAGNI — thêm cho thứ không ai dùng.
+- Sai về mặt kỹ thuật với stack này.
+- Có lý do legacy/tương thích.
+- Trái quyết định kiến trúc đã chốt.
+
+**Phản bác thế nào:** lý do kỹ thuật, câu hỏi cụ thể, dẫn test đang chạy làm bằng chứng.
+Không phản bác bằng cảm nhận.
+
+## Phản hồi đúng
+
+```
+✅ "Đúng — <vấn đề>. Nằm ở <path:line>."
+✅ ghi thẳng vào báo cáo, không bình luận thêm
+❌ mọi kiểu cảm ơn hay khen xã giao
+```
+
+## Khi mình phản bác sai
+
+```
+✅ "Bạn đúng — đã kiểm <X>, đúng là <Y>."
+❌ xin lỗi dài, biện minh, giải thích quá mức
+```
+
+Sửa rồi đi tiếp. Không kể lể.
+
+## Bảng nhanh
+
+| Sai | Sửa |
+|---|---|
+| đồng ý cho có | nói lại yêu cầu, hoặc làm |
+| tin ngay không kiểm | đối chiếu với code |
+| mặc định người review đúng | kiểm xem có phá gì không |
+| né phản bác | đúng kỹ thuật hơn dễ chịu |
+
+## Chốt
+
+Phản hồi từ ngoài là **đề xuất để thẩm định, không phải mệnh lệnh**.
+
+Kiểm chứng. Chất vấn. Rồi mới kết luận. Và review không sửa code — kết luận đi về
+bên giao việc dưới dạng báo cáo.

package/skills/code-review/references/edge-case-scouting.md

@@ -0,0 +1,78 @@
+# Quét vùng ảnh hưởng
+
+Tìm file bị ảnh hưởng mà diff **không** cho thấy. Chạy trước khi đọc chi tiết từng dòng.
+
+## Vì sao cần
+
+Đọc diff cho biết cái gì đổi. Nó **không** cho biết cái gì lẽ ra phải đổi mà không đổi —
+và đó mới là chỗ bug sống sót qua review.
+
+Ví dụ điển hình: đổi chữ ký một hàm dùng chung, sửa hết chỗ gọi trực tiếp, bỏ sót chỗ gọi
+qua một lớp wrapper. Diff sạch, test cũ vẫn xanh, hỏng lúc chạy thật.
+
+## Khi nào bắt buộc
+
+Tính năng nhiều file · refactor tiện ích dùng chung · sửa bug phức tạp · đổi chữ ký hàm
+hoặc hình dạng dữ liệu.
+
+Bỏ qua được: sửa một file, tài liệu, config không có nhánh logic.
+
+## Quy trình
+
+### 1. Lấy danh sách file đổi
+
+```bash
+git diff --name-only HEAD~1     # hoặc so với base được giao
+```
+
+### 2. Tìm ngược ra ngoài diff
+
+Tự làm bằng `Grep`/`Glob`/`Bash`, không giao đi.
+
+Với mỗi symbol công khai bị đổi trong diff:
+
+```bash
+rg -n '<tên hàm|tên hằng|tên type>' --glob '!node_modules'
+```
+
+Sáu thứ phải trả lời được:
+
+1. **File nào import/phụ thuộc module đã đổi** — kể cả gọi gián tiếp qua wrapper.
+2. **Dữ liệu chảy qua hàm đã sửa đi tới đâu**, và ai đọc kết quả đó.
+3. **Đường lỗi nào chưa được test** — nhánh `catch`, `else`, giá trị trả về khi thất bại.
+4. **Biên:** null, rỗng, 0, một phần tử, độ dài tối đa.
+5. **Bất đồng bộ:** có race không, có thứ tự nào bị giả định ngầm không.
+6. **Trạng thái dùng chung:** biến module, cache, singleton bị sửa ở đâu.
+
+Cần đầy đủ tuyệt đối (trước một refactor lớn) → báo bên giao việc để nhờ một lượt phân
+tích ảnh hưởng bằng `gkg`. `rg` khớp chuỗi, `gkg` đi theo quan hệ AST.
+
+Bổ có hệ thống hơn nữa: skill `alp-scenario` (12 chiều).
+
+### 3. Xử lý
+
+| Phát hiện | Làm gì |
+|---|---|
+| file bị ảnh hưởng nằm ngoài diff | đưa vào phạm vi đọc, ghi rõ trong báo cáo |
+| đường dữ liệu có rủi ro | truy tiếp tới nơi tiêu thụ, đừng dừng ở hàm bị sửa |
+| edge case chưa có test | ghi vào NÊN SỬA |
+| thay đổi im lặng phá hành vi cũ | CHẶN |
+
+### 4. Đưa vào báo cáo
+
+Kết quả quét **không** phải một mục riêng. Nó nhập vào báo cáo `code-review` theo đúng ba
+mức CHẶN / NÊN SỬA / GHI NHẬN.
+
+Riêng phần đã kiểm mà **không** thấy vấn đề thì vẫn nói — nó cho bên giao việc biết phạm vi bạn đã
+phủ, và biết chỗ nào bạn chưa đụng tới:
+
+```
+Đã quét ngoài diff: <n> file gọi tới <symbol>
+Không thấy vấn đề ở: <danh sách>
+Chưa quét được: <chỗ nào, vì sao>
+```
+
+## Luật
+
+Quét trước, đọc sau. Và **đừng tin "thay đổi này đơn giản"** — thay đổi đơn giản là loại
+hay được cho qua nhất, nên cũng là loại sống sót qua review nhiều nhất.

package/skills/code-review/references/verification-before-completion.md

@@ -0,0 +1,117 @@
+# Cổng kiểm chứng trước khi nói "xong"
+
+Nói xong mà chưa kiểm chứng là **nói dối**, không phải làm nhanh.
+
+Nguyên tắc: bằng chứng trước, khẳng định sau. Luôn luôn.
+
+**Lách câu chữ của luật này là vi phạm luật này.**
+
+## Luật sắt
+
+```
+KHÔNG TUYÊN BỐ HOÀN THÀNH KHI CHƯA CÓ BẰNG CHỨNG MỚI
+```
+
+Chưa chạy lệnh kiểm chứng **trong phiên này** thì không được nói nó pass.
+
+## Hàm cổng
+
+```
+TRƯỚC khi nói bất cứ trạng thái nào, hoặc tỏ ra hài lòng:
+
+1. XÁC ĐỊNH: lệnh nào chứng minh được khẳng định này?
+2. CHẠY:     chạy ĐỦ lệnh đó, mới, không cắt
+3. ĐỌC:      đọc hết output, xem exit code, đếm số fail
+4. ĐỐI CHIẾU: output có xác nhận khẳng định không?
+   - KHÔNG → nói trạng thái thật, kèm bằng chứng
+   - CÓ    → nói khẳng định, KÈM bằng chứng
+5. RỒI MỚI: phát biểu
+
+Bỏ bước nào = nói dối, không phải kiểm chứng
+```
+
+## Bảng đối chiếu
+
+| Khẳng định | Bằng chứng bắt buộc | KHÔNG đủ |
+|---|---|---|
+| test pass | output test: 0 fail | lần chạy trước, "chắc pass" |
+| linter sạch | output linter: 0 lỗi | kiểm một phần rồi suy ra |
+| build được | lệnh build: exit 0 | linter xanh, log nhìn ổn |
+| đã fix bug | test triệu chứng gốc: pass | đã sửa code, cho là xong |
+| test hồi quy chạy đúng | đã làm chu trình đỏ-xanh | test pass một lần |
+| yêu cầu đã đủ | đối chiếu từng gạch đầu dòng | test xanh |
+| agent khác đã làm xong | `git diff` cho thấy thay đổi | nó báo "xong" |
+
+Dòng cuối quan trọng riêng với alp-code: **báo cáo của một agent khác không phải bằng
+chứng.** Nó chạy trong phiên riêng, bạn không thấy nó đã chạy gì. Kiểm độc lập.
+
+## Cờ đỏ — dừng lại
+
+- Dùng "chắc là", "nhiều khả năng", "có vẻ".
+- Tỏ ra hài lòng trước khi kiểm chứng ("ngon rồi!", "xong!").
+- Sắp commit/push/PR mà chưa kiểm chứng.
+- Tin báo cáo thành công của agent khác.
+- Dựa vào kiểm chứng một phần.
+- Nghĩ "lần này thôi".
+- Mệt và muốn xong cho rồi.
+- **Bất kỳ cách diễn đạt nào ngụ ý thành công mà chưa chạy kiểm chứng.**
+
+## Chặn lý do biện minh
+
+| Lý do | Thực tế |
+|---|---|
+| "chắc chạy được rồi" | thì CHẠY đi |
+| "tôi tự tin mà" | tự tin ≠ bằng chứng |
+| "lần này thôi" | không có ngoại lệ |
+| "linter xanh rồi" | linter ≠ compiler |
+| "bên kia bảo xong rồi" | kiểm độc lập |
+| "mệt quá" | mệt ≠ lý do |
+| "kiểm một phần là đủ" | một phần chứng minh không gì cả |
+| "tôi nói khác đi nên luật không áp dụng" | tinh thần, không phải câu chữ |
+
+## Mẫu
+
+**Test**
+
+```
+✅ [chạy lệnh test] [thấy: 34/34 pass] → "toàn bộ test pass"
+❌ "chắc pass rồi" / "nhìn thì đúng"
+```
+
+**Test hồi quy — chu trình đỏ-xanh**
+
+```
+✅ viết test → chạy (pass) → gỡ bản sửa → chạy (PHẢI FAIL) → khôi phục → chạy (pass)
+❌ "tôi đã viết test hồi quy" (chưa qua đỏ-xanh)
+```
+
+Test hồi quy chưa từng đỏ thì không chứng minh được gì — nó có thể pass ngay cả khi bug
+còn nguyên.
+
+**Build**
+
+```
+✅ [chạy build] [thấy: exit 0] → "build được"
+❌ "linter xanh" (linter không kiểm biên dịch)
+```
+
+**Yêu cầu**
+
+```
+✅ đọc lại yêu cầu → lập checklist → đối chiếu từng mục → báo chỗ thiếu hoặc báo đủ
+❌ "test xanh, coi như xong"
+```
+
+## Áp dụng khi nào
+
+**LUÔN LUÔN, trước:** mọi biến thể của câu nói xong · mọi biểu hiện hài lòng · mọi phát
+biểu tích cực về trạng thái công việc · commit, PR · chuyển sang việc kế tiếp.
+
+Luật áp dụng cho: câu nguyên văn, câu diễn đạt lại, câu đồng nghĩa, và **mọi cách nói ngụ ý
+đã xong hoặc đã đúng**.
+
+## Chốt
+
+Chạy lệnh. Đọc output. **Rồi mới** nói kết quả.
+
+Không thương lượng. Đây là lý do một phiên review tồn tại: để có người không cho qua.

package/skills/delegation/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: delegation
+description: "Delegate work through ALP's runtime-neutral Delegation API with role policy, prepared context, execution lifecycle, and backend selection enforced by ALP."
+---
+
+# ALP Delegation
+
+When work should be delegated, use ALP's delegation mechanism:
+
+```bash
+alp delegate <role> --project <path> -- "<task>"
+alp delegate <role> --background -- "<task>"
+alp delegation status <execution-id>
+alp delegation wait <execution-id>
+alp delegation cancel <execution-id>
+alp delegation cleanup <execution-id>
+alp delegation list
+```
+
+`scripts/run-role.*` remains a compatibility facade and calls the same service.
+
+Do not invoke runtime-specific delegation tools directly. In particular, do not call
+`paseo`, `create_agent`, or `spawn_agent` to delegate ALP work.
+
+ALP policy determines:
+
+- which role may delegate;
+- which role can be targeted (`delegates_to`);
+- what identity and task context is passed;
+- what project/shared/private memory is visible;
+- which workspace and write policy apply.
+
+The backend only runs the prepared execution: it spawns the runtime as a child process and
+owns nothing about role, ACL, memory, or task ownership. There is one backend and no way to
+select another — `--backend` and `alp delegation switch` were removed on 2026-09-03.
+
+If `--project` is omitted, the execution workspace is the caller's current directory. ALP
+pins that canonical path into context and blocks access to other registered source workspaces
+for the duration of the execution. Prefer an explicit absolute `--project` for important work.
+
+The principal may talk to a role directly. In direct sessions, answer the principal. In a
+delegated execution, return lifecycle/results to the delegation parent; direct interaction
+still does not expand ACL or `delegates_to`.
+
+Use `alp delegation health` for generic diagnosis. Runtime-specific tools are reserved for
+principal/admin maintenance outside delegated role sessions.

package/skills/docs-seeker/.env.example

@@ -0,0 +1,15 @@
+# Context7 API Configuration (optional)
+# Get your API key from https://context7.com/dashboard/api-keys
+CONTEXT7_API_KEY=
+
+# Gemini API Configuration (optional, for ai-multimodal integration)
+# Get your API key from https://aistudio.google.com/app/apikey
+GEMINI_API_KEY=
+
+# GitHub Token (optional, for higher rate limits on repository analysis)
+# Create at https://github.com/settings/tokens
+GITHUB_TOKEN=
+
+# Output settings
+OUTPUT_FORMAT=json
+DEBUG=false

package/skills/docs-seeker/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: docs-seeker
+description: Tìm tài liệu thư viện/framework qua chuẩn llms.txt (context7.com) và phân tích repo GitHub. Kích hoạt khi cần API doc chính xác của một thư viện, khi phải đọc tài liệu bản mới nhất, hoặc khi gặp URL repo GitHub cần hiểu nội dung.
+---
+
+# docs-seeker — lấy tài liệu bằng script
+
+Dùng khi cần **nguồn sơ cấp** của một thư viện cụ thể — tài liệu chính thức, không phải
+blog viết lại.
+
+Ba script làm hết phần dựng URL, chuỗi fallback và bắt lỗi. **Chạy script, đừng tự đoán
+URL context7** — đoán sai thì `WebFetch` trả 404 và bạn tốn một lượt trong ngân sách 5 lượt
+của `research`.
+
+## Đường dẫn
+
+CWD của phiên là active workspace; gọi script qua repo path hoặc skill path runtime cung cấp:
+
+```
+<alp-repo>/skills/docs-seeker/scripts/<tên>.js
+```
+
+Không dùng `node scripts/…` — đường dẫn đó tính từ CWD và sẽ không tìm thấy file.
+
+## Quy trình
+
+```bash
+# 1. Phân loại truy vấn: hỏi một chủ đề cụ thể hay hỏi cả thư viện?
+node .claude/skills/docs-seeker/scripts/detect-topic.js "<câu hỏi>"
+
+# 2. Lấy tài liệu theo kết quả bước 1
+node .claude/skills/docs-seeker/scripts/fetch-docs.js "<câu hỏi>"
+
+# 3. Chỉ khi bước 2 trả về nhiều URL — phân loại theo mức quan trọng
+cat llms.txt | node .claude/skills/docs-seeker/scripts/analyze-llms-txt.js -
+```
+
+Rồi đọc URL bằng `WebFetch`.
+
+| Script | Làm gì | Trả về |
+|---|---|---|
+| `detect-topic.js` | tách tên thư viện + từ khoá chủ đề | `{topic, library, isTopicSpecific}` |
+| `fetch-docs.js` | dựng URL context7, tự fallback chủ đề → tổng quát → lỗi | nội dung llms.txt hoặc thông báo lỗi |
+| `analyze-llms-txt.js` | xếp URL theo critical/important/supplementary | JSON |
+
+Script chạy trong `Bash`, không nạp gì vào context — đó là lý do phải dùng script thay vì
+tự làm bằng tay.
+
+## Hai kiểu truy vấn
+
+**Hỏi chủ đề cụ thể** — "dùng date picker trong shadcn thế nào?" → `isTopicSpecific: true`,
+`fetch-docs.js` trả 2–3 URL. Nhanh, đọc hết được.
+
+**Hỏi cả thư viện** — "tài liệu Next.js" → `isTopicSpecific: false`, trả 8+ URL. Chạy
+`analyze-llms-txt.js` để biết đọc cái nào trước.
+
+Với truy vấn tổng quát, `analyze-llms-txt.js` có gợi ý chia việc cho nhiều agent song song.
+**Bỏ qua gợi ý đó** nếu execution policy không cho giao việc. Dùng phần
+xếp hạng critical/important/supplementary để tự chọn thứ tự đọc, và đọc trong ngân sách.
+
+## Khoá API
+
+Ba khoá đều **tuỳ chọn**, không có vẫn chạy: `CONTEXT7_API_KEY` (rate limit cao hơn),
+`GITHUB_TOKEN` (phân tích repo), `GEMINI_API_KEY`.
+
+Script đọc theo thứ tự: `process.env` → `.env` trong thư mục skill → `.claude/.env`.
+
+**Không tự tạo file `.env` trong `skills/`** — `skills/` là hạ tầng đóng băng, chỉ principal
+sửa. Cần khoá thì báo lại; principal sẽ đặt vào biến môi trường.
+
+## Tham chiếu
+
+| File | Khi nào đọc |
+|---|---|
+| `workflows/topic-search.md` | hỏi chủ đề cụ thể — đường nhanh nhất |
+| `workflows/library-search.md` | hỏi cả thư viện — quét rộng |
+| `workflows/repo-analysis.md` | context7 không có, phải đọc thẳng repo GitHub |
+| `references/context7-patterns.md` | mẫu URL, repo đã biết |
+| `references/errors.md` | script lỗi, chuỗi fallback |
+| `references/advanced.md` | phiên bản, đa ngôn ngữ, ca biên |
+
+## Sau khi lấy được
+
+Tài liệu lấy về là **bằng chứng cho `research`**, không phải báo cáo. Ghi lại phiên bản và
+ngày của tài liệu — tài liệu không có phiên bản thì gần như vô dụng cho việc đánh giá.
+
+Script lỗi thì sửa rồi chạy lại cho tới khi được. Không bỏ qua script rồi tự đoán URL.