alp-code 0.9.0

package/skills/docs-seeker/workflows/library-search.md

@@ -0,0 +1,73 @@
+# Tìm tài liệu cả thư viện
+
+**Dùng khi:** câu hỏi rộng về cả một thư viện/framework, hoặc khi tìm theo chủ đề trả 404.
+
+Chậm hơn và tốn context hơn `topic-search.md`. **Thử đường chủ đề trước.**
+
+## Nhận dạng
+
+- "tài liệu {thư viện}"
+- "bắt đầu với {thư viện}"
+- "{thư viện} dùng thế nào"
+- "API reference của {thư viện}"
+
+## Quy trình
+
+```bash
+# 1. Phân loại
+node .claude/skills/docs-seeker/scripts/detect-topic.js "<câu hỏi>"
+# → {"isTopicSpecific": false}
+
+# 2. Lấy llms.txt
+node .claude/skills/docs-seeker/scripts/fetch-docs.js "<câu hỏi>"
+# → nội dung llms.txt, thường 5–20+ URL
+
+# 3. Xếp hạng URL — BƯỚC KHÔNG ĐƯỢC BỎ
+cat llms.txt | node .claude/skills/docs-seeker/scripts/analyze-llms-txt.js -
+# → {totalUrls, grouped: {critical, important, supplementary}, distribution}
+```
+
+Bước 3 là bước quyết định. 20 URL mà đọc hết thì phá ngân sách context của cả phiên. Script
+xếp chúng thành ba nhóm — đọc `critical` trước, `important` nếu còn ngân sách, bỏ qua
+`supplementary` trừ khi câu hỏi cần đúng phần đó.
+
+## Đọc bao nhiêu
+
+Script có trường `distribution` gợi ý chia việc cho nhiều agent song song. **Bỏ qua trường
+đó** nếu loadout không cho giao việc.
+
+Dùng thứ tự đọc thay cho chia agent:
+
+| Số URL | Cách làm |
+|---|---|
+| 1–3 | đọc hết bằng `WebFetch` |
+| 4–10 | đọc nhóm `critical`, rồi `important` nếu còn ngân sách |
+| 11+ | **chỉ** nhóm `critical`; nói rõ là đã cắt và cắt theo tiêu chí nào |
+
+Cắt bớt thì phải nói rõ đã cắt gì. Im lặng cắt rồi trình bày như đã đọc hết là báo cáo sai.
+
+## Ví dụ — Astro
+
+```bash
+node .claude/skills/docs-seeker/scripts/detect-topic.js "tài liệu Astro"
+# {"isTopicSpecific": false}
+
+node .claude/skills/docs-seeker/scripts/fetch-docs.js "tài liệu Astro"
+# script gọi: context7.com/withastro/astro/llms.txt → 8 URL
+
+node .claude/skills/docs-seeker/scripts/analyze-llms-txt.js < llms.txt
+# {totalUrls: 8, grouped: {critical: [...], important: [...], ...}}
+```
+
+Đọc `critical` (bắt đầu, cài đặt), rồi `important` (khái niệm lõi, component) nếu ngân
+sách còn.
+
+## Khi không ra
+
+Script tự fallback theo thứ tự:
+
+1. `fetch-docs.js` thử context7.com.
+2. 404 → gợi ý dùng `WebSearch` tìm `llms.txt` của dự án.
+3. Vẫn không có → `repo-analysis.md` (đọc thẳng repo GitHub).
+
+Script lỗi thì **sửa rồi chạy lại cho tới khi được**, đừng bỏ script rồi tự đoán URL.

package/skills/docs-seeker/workflows/repo-analysis.md

@@ -0,0 +1,90 @@
+# Đọc thẳng repo — khi không có llms.txt
+
+**Đường cuối cùng.** Chậm (5–10 phút), tốn context nhất. Chỉ dùng khi
+`topic-search.md` và `library-search.md` đều không ra.
+
+## Khi nào
+
+- Thư viện không có trên context7.com.
+- Site chính thức không có `llms.txt`.
+- Tài liệu tồn tại nhưng thiếu, phải đọc code mới rõ.
+
+## Quy trình
+
+### 1. Tìm repo
+
+`WebSearch`: `"{thư viện} github repository"`
+
+**Xác minh trước khi clone:** đúng repo chính thức chưa (không phải fork), còn hoạt động
+không (commit gần đây), có `docs/` không. Clone nhầm một fork bỏ hoang rồi kết luận theo nó
+là sai nguồn.
+
+### 2. Clone
+
+```bash
+git clone <repo-url> /tmp/docs-analysis
+```
+
+Cần đúng một phiên bản thì `git checkout <tag>`. **Luôn ghi lại tag/commit đã đọc** —
+`research` yêu cầu ghi phiên bản kèm ngày cho mọi nguồn.
+
+Clone về máy là tải mã nguồn lạ. Repo lớn hoặc không rõ nguồn gốc → **báo lại trước**.
+
+### 3. Đóng gói
+
+```bash
+repomix --version || echo "chưa cài"
+cd /tmp/docs-analysis
+repomix --token-count-tree           # XEM TRƯỚC token nằm ở đâu
+repomix --include "README.md,docs/**,examples/**" -o repomix-output.xml
+```
+
+Chưa cài `repomix` thì báo lại, đừng tự `npm install -g` (HOUSE-RULES §1.2).
+
+**Chạy `--token-count-tree` trước và lọc bằng `--include`.** Gói cả repo rồi mới phát hiện
+nó 200k token là hỏng cả phiên. Thứ bạn cần gần như luôn nằm ở `README.md`, `docs/`,
+`examples/` — không phải toàn bộ `src/`.
+
+### 4. Đọc và rút
+
+Đọc file đã gói, rút theo thứ tự:
+
+| Nguồn trong repo | Cho biết |
+|---|---|
+| `README.md` | cài đặt, tổng quan, ví dụ tối thiểu |
+| `docs/` | hướng dẫn dùng, API reference |
+| `examples/` | mẫu code thật |
+| `CHANGELOG.md` | breaking change, phiên bản |
+| `src/` | chỉ khi tài liệu không trả lời được |
+
+`CHANGELOG.md` hay bị bỏ qua mà nó là nguồn tốt nhất cho câu hỏi "bản này có gì đổi".
+
+### 5. Dọn
+
+```bash
+rm -rf /tmp/docs-analysis
+```
+
+Bỏ bước này thì lần sau clone đè lên bản cũ và bạn đọc nhầm phiên bản.
+
+## Ghi rõ khi báo cáo
+
+Kết quả từ đường này **không phải tài liệu chính thức**. Bắt buộc ghi:
+
+```
+Nguồn: đọc repo <org/repo> tại <tag hoặc commit>, ngày <…>
+Lưu ý: rút từ code và README, không phải tài liệu chính thức
+Sức khoẻ repo: <số sao, commit gần nhất>
+```
+
+Dòng "sức khoẻ repo" quan trọng cho việc đánh giá của `research`: một thư viện không có
+commit nào 18 tháng là thông tin, kể cả khi code của nó tốt.
+
+## Không có repo nào
+
+Không tìm được repo thì nói thẳng: không có nguồn sơ cấp. Những gì gom được từ
+blog, tutorial, Stack Overflow là **nguồn thứ cấp** — chất lượng không đều, phải đối chiếu
+ít nhất hai nguồn độc lập, và phải ghi rõ là thứ cấp trong báo cáo.
+
+Bản gốc của workflow này gợi ý "chia cho nhiều Researcher agent" — bỏ qua nếu loadout
+không cho giao việc.

package/skills/docs-seeker/workflows/topic-search.md

@@ -0,0 +1,69 @@
+# Tìm tài liệu theo chủ đề cụ thể
+
+**Dùng khi:** cần tài liệu về một tính năng / component / khái niệm cụ thể.
+
+Nhanh nhất (10–15s), tốn ít token nhất, kết quả trúng đích nhất. **Đây là đường mặc định** —
+chỉ chuyển sang tìm cả thư viện khi đường này không ra.
+
+## Nhận dạng
+
+- "dùng {tính năng} trong {thư viện} thế nào?"
+- "tài liệu {component} của {thư viện}"
+- "triển khai {tính năng} bằng {thư viện}"
+
+## Quy trình
+
+Đường dẫn tính từ CWD của phiên (`active workspace`), qua symlink skill.
+
+```bash
+# 1. Phân loại truy vấn
+node .claude/skills/docs-seeker/scripts/detect-topic.js "<câu hỏi>"
+# → {"topic": "X", "library": "Y", "isTopicSpecific": true}
+
+# 2. Lấy tài liệu — script tự dựng URL và tự fallback
+node .claude/skills/docs-seeker/scripts/fetch-docs.js "<câu hỏi>"
+# script gọi: context7.com/{library}/llms.txt?topic={topic}
+# → nội dung llms.txt, thường 1–5 URL
+```
+
+Rồi đọc URL bằng `WebFetch`.
+
+**1–5 URL thì đọc thẳng.** Bản gốc của workflow này có bước "chia cho 2–3 Explorer agent
+song song" — bỏ qua nếu loadout không cho giao việc. Đọc tuần tự, trong ngân sách 5 lượt
+của `research`.
+
+## Ví dụ
+
+**Date picker của shadcn**
+
+```bash
+node .claude/skills/docs-seeker/scripts/detect-topic.js "dùng date picker trong shadcn thế nào?"
+# {"topic": "date", "library": "shadcn/ui", "isTopicSpecific": true}
+
+node .claude/skills/docs-seeker/scripts/fetch-docs.js "dùng date picker trong shadcn thế nào?"
+# script gọi: context7.com/shadcn-ui/ui/llms.txt?topic=date
+# → 2–3 URL về date
+```
+
+**Cache của Next.js**
+
+```bash
+node .claude/skills/docs-seeker/scripts/detect-topic.js "Next.js caching strategies"
+# {"topic": "cache", "library": "next.js", "isTopicSpecific": true}
+# script gọi: context7.com/vercel/next.js/llms.txt?topic=cache
+```
+
+## Vì sao đường này đáng ưu tiên
+
+Trả về **chỉ tài liệu liên quan**, không phải toàn bộ thư viện. Nhanh hơn nhiều lần và
+không phải lọc — quan trọng vì lý do một lượt tra cứu tồn tại là giữ context của bên giao
+việc sạch.
+
+## Khi không ra
+
+URL theo chủ đề trả 404 → chuyển sang `library-search.md` (tìm cả thư viện).
+
+context7 không có thư viện đó → `repo-analysis.md` (đọc thẳng repo GitHub).
+
+Cả ba đều không ra → nói thẳng là không tìm được tài liệu sơ cấp, và những gì tìm
+được là nguồn thứ cấp. Đừng lấp bằng blog rồi trình bày như tài liệu chính thức.

package/skills/git/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: git
+description: Thao tác git với conventional commit — stage, quét secret, tách commit theo type/scope, push, PR, merge. Kích hoạt khi principal yêu cầu commit/push/mở PR, hoặc khi cần đọc trạng thái repo trước lúc bàn giao.
+---
+
+# git — commit có kỷ luật
+
+Skill này cần `Write`/`Edit` và `Bash`. Execution policy không cấp đủ thì chỉ đọc được trạng thái
+repo, không commit được.
+
+## Cổng chặn — đọc trước mọi thứ khác
+
+**Không commit, không push, trừ khi principal yêu cầu** (HOUSE-RULES §1.3).
+
+Không có ngoại lệ nào kiểu "làm xong rồi commit luôn cho gọn". Viết code xong thì báo cáo
+và dừng; principal quyết định có commit không.
+
+Bốn hành động **luôn phải hỏi lại từng lần**, kể cả khi lần trước đã được duyệt
+(HOUSE-RULES §1.2):
+
+| Hành động | Vì sao |
+|---|---|
+| `git push` | ra ngoài máy, người khác thấy ngay |
+| `--force`, `--force-with-lease` | ghi đè lịch sử của người khác |
+| `merge` vào nhánh chính | khó đảo ngược, ảnh hưởng mọi người |
+| `git reset --hard`, xoá nhánh | mất việc chưa lưu |
+
+## Quy trình commit
+
+### 1. Stage và nhìn
+
+```bash
+git add -A && git diff --cached --stat && git diff --cached --name-only
+```
+
+Đọc `--stat` trước khi viết message. Commit mà không biết mình đang commit gì là cách
+nhanh nhất để kéo nhầm file sinh ra vào lịch sử.
+
+### 2. Quét secret — bắt buộc, không bỏ
+
+```bash
+git diff --cached | grep -iE '(api[_-]?key|token|password|secret|credential)'
+```
+
+Có khớp → **DỪNG**, báo principal, đề xuất `.gitignore`. Không tự quyết định là "chắc chỉ
+là tên biến".
+
+Với alp-code còn hai thứ **không bao giờ được vào commit**:
+
+- `memory/` — trí nhớ là dữ liệu cục bộ từng máy, đã có trong `.gitignore`.
+- `dist/` và `~/.alp/executions/` — compiled output và machine-local execution state.
+
+Thấy chúng trong `--cached` nghĩa là `.gitignore` hỏng. Báo principal, đừng tự `git rm`.
+
+### 3. Quyết định tách commit
+
+**Tách khi:** trộn nhiều type (`feat` + `fix`, code + docs) · nhiều scope (`agents` +
+`runtime`) · trộn config/deps với code · trên 10 file không liên quan nhau.
+
+**Một commit khi:** cùng type và scope, ≤ 3 file, ≤ 50 dòng.
+
+### 4. Viết message
+
+Conventional commit, **tiếng Việt** cho phần mô tả — khớp lịch sử repo:
+
+```
+fix: repoRoot của phiên + workspaces không còn path tuyệt đối
+feat(acl): register alp-plugin workspace
+docs: báo cáo chẩn đoán repoRoot
+```
+
+Thân commit trả lời **vì sao**, không phải **làm gì** — `git diff` đã nói làm gì rồi.
+Có issue liên quan thì dẫn số.
+
+Chuẩn đầy đủ: `references/commit-standards.md`.
+
+## Mẫu báo cáo về principal
+
+```
+✓ staged: N file (+X/−Y dòng)
+✓ secret: sạch
+✓ commit: <hash> type(scope): mô tả
+✗ push: CHƯA — chờ principal duyệt
+```
+
+Chưa push thì ghi rõ chưa push. Không viết mập mờ để principal tự hiểu là xong.
+
+## Xử lý lỗi
+
+| Lỗi | Làm gì |
+|---|---|
+| phát hiện secret | chặn commit, liệt kê file, báo principal |
+| không có thay đổi | dừng, nói rõ, không tạo commit rỗng |
+| push bị từ chối | đề xuất `git pull --rebase`, **hỏi trước khi chạy** |
+| xung đột merge | báo principal, không tự chọn bên |
+
+## Worktree
+
+alp-code dùng worktree cho nhánh triển khai cô lập (`.worktrees/` đã trong `.gitignore`).
+Stash stack **dùng chung** giữa mọi worktree — `git stash pop` trần có thể lấy nhầm việc
+của phiên khác. Cần cất việc tạm thì tạo commit WIP, đừng stash.
+
+## Tham chiếu
+
+| File | Nội dung |
+|---|---|
+| `references/workflow-commit.md` | quy trình commit, logic tách |
+| `references/workflow-push.md` | push và xử lý lỗi |
+| `references/workflow-pr.md` | tạo PR, phân tích diff với remote |
+| `references/workflow-merge.md` | merge nhánh |
+| `references/commit-standards.md` | chuẩn conventional commit |
+| `references/safety-protocols.md` | phát hiện secret, bảo vệ nhánh |
+| `references/branch-management.md` | đặt tên, vòng đời nhánh |
+| `references/gh-cli-guide.md` | lệnh `gh` |
+
+## Ranh giới
+
+- Không có subagent nào để đẩy output dài sang. Output git dài thì lọc bằng `--stat`,
+  `--oneline`, `-n`, đừng đổ nguyên vào context.
+- Không push lên `main`/`master`, không force-push, không merge — trừ khi principal nói
+  thẳng, trong phiên này.

package/skills/git/references/branch-management.md

@@ -0,0 +1,90 @@
+# Quản lý nhánh
+
+## Đặt tên
+
+**Dạng:** `<type>/<mô-tả-kebab>`
+
+| Type | Dùng cho | Ví dụ |
+|---|---|---|
+| `feature/` | tính năng mới | `feature/oauth-login` |
+| `fix/` | sửa lỗi | `fix/session-repo-root` |
+| `refactor/` | đổi cấu trúc | `refactor/api-cleanup` |
+| `docs/` | tài liệu | `docs/api-reference` |
+| `test/` | test | `test/integration-suite` |
+| `chore/` | bảo trì | `chore/deps-update` |
+| `hotfix/` | sửa gấp trên production | `hotfix/payment-crash` |
+
+Xem `git branch -a` trước khi đặt tên mới — theo mẫu đang có, đừng tự nghĩ dạng mới.
+
+## Vòng đời
+
+### Tạo
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b feature/ten-nhanh
+```
+
+Luôn tạo từ `main` **đã pull mới**. Tạo từ một nhánh cũ thì diff sẽ dính cả thay đổi của
+người khác, và PR sau đó không đọc được.
+
+### Trong lúc làm
+
+```bash
+git add <file> && git commit -m "type(scope): mô tả"
+
+git fetch origin
+git rebase origin/main      # HỎI TRƯỚC — rebase viết lại commit của bạn
+```
+
+### Trước khi merge
+
+```bash
+git push origin feature/ten-nhanh
+```
+
+Sau rebase thì phải force — **chỉ trên nhánh feature của mình**, và dùng
+`--force-with-lease`:
+
+```bash
+git push --force-with-lease origin feature/ten-nhanh
+```
+
+### Sau khi merge
+
+```bash
+git branch -d feature/ten-nhanh                    # xoá local (an toàn: -d từ chối nếu chưa merge)
+git push origin --delete feature/ten-nhanh         # xoá remote — HỎI TRƯỚC
+```
+
+Dùng `-d`, **không** dùng `-D`. `-d` từ chối xoá nhánh chưa merge; `-D` xoá bất chấp và đó
+là cách mất việc.
+
+## Worktree trong alp-code
+
+Repo này dùng worktree cho nhánh triển khai cô lập (`.worktrees/` đã trong `.gitignore`).
+
+Điều dễ nhầm: **nhánh là dùng chung giữa mọi worktree, chỉ working tree là riêng.** Một
+nhánh đang được checkout ở worktree khác thì không checkout lại được ở đây — đó là tính
+năng, không phải lỗi.
+
+Stash stack cũng dùng chung. Xem phần cuối `safety-protocols.md`.
+
+## Nhánh trong alp-code
+
+`main` là nhánh chính. **Không push thẳng lên `main`** — làm trên nhánh, mở PR, principal
+quyết định merge.
+
+## Lệnh nhanh
+
+| Việc | Lệnh |
+|---|---|
+| liệt kê nhánh | `git branch -a` |
+| nhánh hiện tại | `git rev-parse --abbrev-ref HEAD` |
+| chuyển nhánh | `git checkout <nhánh>` |
+| tạo và chuyển | `git checkout -b <nhánh>` |
+| xoá local | `git branch -d <nhánh>` |
+| xoá remote | `git push origin --delete <nhánh>` |
+| đổi tên | `git branch -m <cũ> <mới>` |
+| liệt kê worktree | `git worktree list` |

package/skills/git/references/commit-standards.md

@@ -0,0 +1,82 @@
+# Chuẩn commit message
+
+## Dạng
+
+```
+type(scope): mô tả
+```
+
+Mô tả viết **tiếng Việt** — khớp lịch sử repo. Xem `git log --oneline -20` trước khi viết
+cái đầu tiên.
+
+## Type
+
+| Type | Dùng khi |
+|---|---|
+| `feat` | tính năng mới |
+| `fix` | sửa lỗi |
+| `refactor` | đổi cấu trúc, không đổi hành vi |
+| `docs` | chỉ tài liệu |
+| `test` | test |
+| `chore` | bảo trì, deps, config |
+| `perf` | hiệu năng |
+| `style` | định dạng, không đổi logic |
+| `ci` | CI/CD |
+
+## Scope trong alp-code
+
+Lấy theo vùng thật của repo, không tự đặt mới:
+
+`agents` · `delegation` · `runtime` · `hooks` · `installer` · `skills` · `scripts` · `memory`
+
+Scope là tuỳ chọn. Thay đổi trải rộng nhiều vùng thì bỏ scope, đừng liệt kê ba scope một lúc.
+
+## Luật
+
+- **Dòng đầu ≈72 ký tự.** Rõ quan trọng hơn ngắn — thà 76 ký tự mà đọc hiểu ngay.
+- Không có dấu chấm cuối dòng đầu.
+- Dòng đầu nói **cái gì**. Thân commit nói **vì sao**.
+- `git diff` đã kể *làm gì*, nên thân commit đừng kể lại. Nó tồn tại để trả lời câu hỏi
+  người đọc `git log` sáu tháng sau sẽ hỏi: *tại sao lại làm thế này?*
+- Có issue liên quan thì dẫn số.
+
+## Thân commit
+
+Thay đổi không hiển nhiên thì **phải** có thân. Mẫu theo repo:
+
+```
+fix: repoRoot của phiên + workspaces không còn path tuyệt đối
+
+<vì sao cách cũ hỏng — mô tả triệu chứng thật, không mô tả code>
+
+- <thay đổi 1 — và vì sao chọn cách này>
+- <thay đổi 2>
+```
+
+## Attribution
+
+Repo này **có** dùng trailer attribution — 5/8 commit gần nhất có. Giữ nguyên thói quen đó:
+
+```
+Co-Authored-By: <model> <noreply@anthropic.com>
+```
+
+Đây là khác biệt so với bản gốc của skill (cấm attribution). alp-code làm ngược lại, và
+lịch sử repo là nguồn sự thật, không phải tài liệu skill.
+
+## Ví dụ đúng
+
+```
+feat(agents): register alp-plugin workspace
+fix(runtime): resolve claude/codex command via PATHEXT
+docs: báo cáo chẩn đoán repoRoot + gitignore session-state ở gốc repo
+```
+
+## Ví dụ sai
+
+| Sai | Vì sao |
+|---|---|
+| `Updated files` | không nói gì |
+| `Fix bug` | bug nào? |
+| `feat(auth): thêm login dùng bcrypt với salt 12 vòng` | kể *làm thế nào*, thuộc về thân commit |
+| `feat(acl,hooks,skills): …` | ba scope một lúc — tách commit ra |

package/skills/git/references/gh-cli-guide.md

@@ -0,0 +1,132 @@
+# Hướng dẫn `gh`
+
+Lệnh `gh` chia làm hai loại. Đọc bảng này trước khi chạy bất cứ lệnh nào bên dưới.
+
+| Loại | Lệnh | Quy tắc |
+|---|---|---|
+| **Đọc** | `list`, `view`, `diff`, `status`, `browse` | chạy tự do |
+| **Tác động ra ngoài** | `create`, `merge`, `comment`, `close`, `rerun`, `auth` | **hỏi principal từng lần** (HOUSE-RULES §1.2) |
+
+## Xác thực
+
+```bash
+gh auth status       # kiểm trạng thái — đọc, chạy được
+gh auth login        # tương tác — KHÔNG tự chạy, báo principal
+gh auth logout       # KHÔNG tự chạy
+```
+
+Chưa đăng nhập thì báo principal chạy `gh auth login` — nó cần tương tác, agent chạy sẽ treo.
+
+## Pull Request
+
+### Tạo — cần duyệt
+
+```bash
+gh pr create --base main --head <nhánh> --title "feat: …" --body "…"
+```
+
+Thân dài dùng heredoc:
+
+```bash
+gh pr create --base main --title "feat(acl): …" --body "$(cat <<'EOF'
+## Tóm tắt
+- …
+
+## Kiểm chứng
+- [ ] …
+EOF
+)"
+```
+
+```bash
+gh pr create --draft --title "WIP: …"        # nháp — rẻ hơn mở PR thật rồi phải đóng
+gh pr create --reviewer @user1,@user2
+gh pr create --label "bug,priority:high"
+```
+
+Việc chưa xong hẳn thì mở **draft**. Xem `workflow-pr.md`.
+
+### Đọc — chạy tự do
+
+```bash
+gh pr list
+gh pr view 123
+gh pr view 123 --web
+gh pr checkout 123          # đổi nhánh làm việc — báo principal trước
+gh pr diff 123
+gh pr status
+```
+
+### Merge — cần duyệt
+
+```bash
+gh pr merge 123               # merge commit
+gh pr merge 123 --squash
+gh pr merge 123 --rebase
+gh pr merge 123 --auto        # tự merge khi check xanh
+gh pr merge 123 --delete-branch
+```
+
+**`--auto` đặc biệt nguy hiểm với agent:** nó merge *sau này*, không phải bây giờ. Chạy
+xong rồi mà principal đổi ý thì merge vẫn xảy ra. Không dùng trừ khi principal nói thẳng.
+
+### Bình luận — cần duyệt
+
+```bash
+gh pr comment 123 --body "…"                     # ra ngoài, người khác thấy
+gh api repos/{owner}/{repo}/pulls/123/comments   # đọc, tự do
+```
+
+## Issue
+
+```bash
+gh issue list                                    # đọc
+gh issue view 42                                 # đọc
+gh issue create --title "…" --body "…"           # cần duyệt
+gh issue develop 42 -c                           # tạo nhánh từ issue — cần duyệt
+```
+
+## Repo
+
+```bash
+gh repo view
+gh browse
+gh browse path/to/file:42     # mở file đúng dòng
+gh repo clone owner/repo      # tải về máy — báo principal
+```
+
+## Workflow
+
+```bash
+gh run list                   # đọc
+gh run view <run-id>          # đọc
+gh run watch                  # đọc, nhưng CHẶN cho tới khi workflow xong — cân nhắc
+gh run rerun <run-id>         # tốn tài nguyên CI — cần duyệt
+```
+
+Đọc log CI hỏng: xem `alp-debug` nếu vai đó được giao, hoặc `gh run view <id> --log-failed`.
+
+## Xuất JSON — để lọc, không để đọc
+
+```bash
+gh pr list --json number,title,author
+gh pr view 123 --json commits,reviews
+gh issue list --json number,title --jq '.[].title'
+```
+
+Dùng `--json` + `--jq` để **cắt output trước khi nó vào context**. Không có subagent để
+đẩy output dài sang, nên lọc là việc của bạn.
+
+## Mẫu KHÔNG dùng
+
+```bash
+# ❌ tạo PR rồi tự merge — hai thao tác cần duyệt, gộp thành một dòng
+gh pr create --fill && gh pr merge --auto --squash
+
+# ❌ đóng hàng loạt PR
+gh pr list --state open --json number -q '.[].number' | xargs -I {} gh pr close {}
+```
+
+Hai mẫu này có trong bản gốc của skill. Chúng vi phạm HOUSE-RULES §1.2 — thao tác khó đảo
+ngược, hàng loạt, không có bước dừng để principal xem. Cần làm thì làm từng cái, mỗi cái
+một lần duyệt.