openmoneta-dev-kit 1.9.0

package/skills/safe-push/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: safe-push
+description: "CORE CONDITIONAL: kích hoạt khi user yêu cầu commit + push / push code / đẩy code / merge lên remote / lên main. Đảm bảo pre-push sync + conflict resolution + safe fast-forward push, không đè code người khác. KHÔNG dùng --force trên shared branch."
+---
+
+# Safe Push (CORE CONDITIONAL)
+
+Skill này chạy ở **Bước 6 — Pre-push Sync + Safe Push**.
+
+Chỉ kích hoạt khi user yêu cầu rõ:
+- "commit + push"
+- "push code"
+- "đẩy code"
+- "đẩy lên remote"
+- "merge lên main"
+- "push bản này"
+
+Không kích hoạt cho task code bình thường chưa có yêu cầu push.
+
+## Mục tiêu
+
+Đảm bảo trước khi `git push`, local branch đã đồng bộ với remote mới nhất để không đè code người khác trong repo có nhiều contributor.
+
+Vấn đề cần chặn:
+
+```text
+T0: AI bắt đầu sửa file a từ remote v1
+T1: Người khác sửa file a và push remote v2
+T2: AI push code dựa trên v1
+```
+
+Bước 6 bắt buộc `fetch + rebase` ngay trước push. Nếu remote có commit mới, local phải rebase lên commit đó trước. Nếu có conflict logic, hỏi user, không tự đoán.
+
+## Nguyên tắc bắt buộc
+
+1. **Không force push shared branch**: tuyệt đối không chạy `git push --force` hoặc `git push -f` lên `main`, `master`, `develop`, `staging`, `production`.
+2. **Không auto-resolve conflict code logic**: file code business (`*.ts`, `*.tsx`, `*.py`, `*.go`, `*.java`, `*.rb`, `*.php`, `*.rs`) phải hỏi user nếu conflict cùng logic/dòng.
+3. **Re-test sau rebase/conflict**: code đã đổi ngữ cảnh sau rebase, phải chạy lại verify tối thiểu phù hợp repo trước khi push.
+4. **Push thường trước**: dùng `git push` fast-forward. Nếu rejected do remote mới, quay lại fetch/rebase. Loop tối đa 3 lần.
+5. **Không deploy trong skill này**: CI/CD/deploy là pipeline ngoài scope trừ khi user yêu cầu skill riêng.
+
+## Workflow 7 bước
+
+### 1. Pre-flight branch
+
+Chạy:
+
+```bash
+git status --short
+git branch --show-current
+git remote -v
+```
+
+Nếu branch là `main`, `master`, `develop`, `staging`, `production`:
+- Cảnh báo user đây là shared branch.
+- Chỉ tiếp tục nếu user đã yêu cầu push rõ.
+- Không dùng force push trong mọi trường hợp.
+
+Nếu working tree chưa clean:
+- Nếu user yêu cầu commit + push: commit trước theo Git Safety Protocol.
+- Nếu còn file conflict/untracked không rõ scope: hỏi user.
+
+### 2. Fetch remote ngay trước push
+
+```bash
+BRANCH=$(git branch --show-current)
+git fetch origin "$BRANCH"
+```
+
+Nếu branch chưa track remote:
+- Dùng `git push -u origin HEAD` sau khi các bước sync/test đã pass.
+
+### 3. So sánh local với remote
+
+```bash
+git status -sb
+git rev-list --left-right --count HEAD...origin/$BRANCH
+```
+
+Diễn giải:
+- `0 0`: local == remote, có thể push nếu đã có commit mới local.
+- `N 0`: local ahead remote, có thể push sau test.
+- `0 N`: remote ahead, phải rebase.
+- `N M`: diverged, phải rebase.
+
+### 4. Rebase với remote nếu cần
+
+```bash
+git pull --rebase origin "$BRANCH"
+```
+
+Nếu rebase sạch:
+- Chuyển sang bước test.
+
+Nếu conflict:
+- Chuyển sang bước 5.
+
+### 5. Conflict resolution policy
+
+Trước tiên liệt kê conflict:
+
+```bash
+git status --short
+git diff --name-only --diff-filter=U
+```
+
+| Loại file conflict | Strategy |
+|---|---|
+| `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` | Không sửa tay nếu tránh được. Resolve package files rồi regenerate bằng package manager phù hợp (`npm install`, `yarn install`, `pnpm install`). |
+| Generated files (`dist/`, `build/`, `.next/`, `coverage/`) | Cảnh báo user. Thường không nên commit generated output. |
+| Code logic (`*.ts`, `*.tsx`, `*.py`, `*.go`, ...) | Hỏi user bằng `AskQuestion`. Không tự chọn ours/theirs nếu thay đổi có ý nghĩa business. |
+| Migration/schema SQL | Escalate user. Có thể cần đổi thứ tự/tên migration để giữ lịch sử đúng. |
+| Docs/plans (`*.md`) | Có thể merge thủ công nếu rõ ràng; nếu nội dung user/team conflict, hỏi user. |
+
+Sau khi user quyết định:
+
+```bash
+git add <resolved-files>
+git rebase --continue
+```
+
+Nếu không thể resolve an toàn:
+- `git rebase --abort`
+- Báo user rõ file conflict và lý do dừng.
+
+### 6. Re-run verify tối thiểu
+
+Chọn verify theo repo:
+- Nếu có `package.json`: chạy lint/typecheck/test script liên quan nếu tồn tại.
+- Nếu không có script test: chạy check nhẹ nhất có sẵn (`npm run lint`, `npm run typecheck`, `go test ./...`, `pytest`, v.v.).
+- Nếu user không yêu cầu test và repo lớn: chạy smoke verify đã ghi trong plan.
+
+Nếu verify fail:
+- Fix nếu lỗi đơn giản và nằm trong scope.
+- Nếu lỗi do conflict logic hoặc ngoài scope: dừng và hỏi user.
+
+### 7. Safe push
+
+```bash
+git push
+```
+
+Nếu push rejected vì remote có commit mới:
+1. Quay lại bước 2.
+2. Loop tối đa 3 lần.
+3. Nếu vẫn rejected/conflict liên tục, dừng và báo user.
+
+Không dùng:
+
+```bash
+git push --force
+git push -f
+```
+
+Chỉ cân nhắc `--force-with-lease` trên feature branch cá nhân khi user yêu cầu rõ và branch không phải shared branch.
+
+## Output bắt buộc
+
+Sau khi push thành công, báo ngắn:
+- Branch đã push.
+- Commit SHA mới nhất.
+- Remote status.
+- Có rebase/conflict không.
+- Verify đã chạy gì.
+
+Ví dụ:
+
+```text
+Đã push branch feature/search-form.
+- SHA: abc1234
+- Pre-push sync: remote ahead 1 commit, rebase sạch
+- Verify: npm run lint pass
+- Push: git push pass
+```
+
+Nếu dừng vì conflict:
+
+```text
+Đã dừng trước push vì conflict code logic ở src/a.ts.
+Remote có thay đổi mới của người khác trên cùng block logic.
+Cần bạn chọn hướng merge trước khi tiếp tục.
+```

package/skills/security-checklist/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: security-checklist
+description: "ON-DEMAND ONLY: chỉ kích hoạt khi user explicitly yêu cầu security audit/review (vd 'audit security login flow', 'check OWASP cho API /payment'), HOẶC task có chạm auth/payment/PII và bạn muốn tự kiểm tra trước commit. KHÔNG tự trigger trong quy trình bình thường (v1.5.0 đã bỏ Bước 5 Security khỏi core process)."
+---
+
+# Security Checklist (ON-DEMAND)
+
+Skill này **KHÔNG** nằm trong quy trình core (v1.5.0+). Chỉ dùng khi:
+
+- User explicit yêu cầu: "audit security X", "review OWASP cho Y", "check secrets".
+- Bạn (AI) chủ động muốn check trước commit nếu task chạm auth/payment/PII/admin/permission.
+- Trước major release.
+
+Có thể delegate sang sub-agent `security-auditor` để có audit độc lập.
+
+## Checklist 10 mục (OWASP Top 10 mapping)
+
+Áp dụng các mục liên quan đến task hiện tại. Tick từng mục:
+
+### A01 — Broken Access Control
+- [ ] Mọi endpoint có middleware authn check
+- [ ] Authz check (role/permission) đúng resource owner
+- [ ] Không trả về data của user khác trong response
+- [ ] IDOR: sequential ID không cho enumerate
+
+### A02 — Cryptographic Failures
+- [ ] HTTPS only (HSTS header)
+- [ ] Password hash bằng bcrypt/argon2 (KHÔNG md5/sha1)
+- [ ] JWT dùng RS256/ES256 (HS256 chỉ khi shared secret đảm bảo)
+- [ ] Sensitive data không log
+
+### A03 — Injection
+- [ ] SQL: dùng parameterized query / ORM (không string concat)
+- [ ] NoSQL: validate operator (`$where`, `$ne` blacklist)
+- [ ] OS command: dùng `execFile` thay `exec`, escape arg
+- [ ] HTML output: escape qua framework (React, Vue auto-escape)
+
+### A04 — Insecure Design
+- [ ] Rate limit ở endpoint sensitive (login, password reset)
+- [ ] Account lockout sau N lần fail
+- [ ] Workflow business logic không bypass được
+
+### A05 — Security Misconfiguration
+- [ ] Default credentials đã đổi
+- [ ] Stack trace KHÔNG lộ trong production
+- [ ] CORS không `*` cho endpoint có credentials
+- [ ] Security headers: CSP, X-Frame-Options, X-Content-Type-Options
+
+### A06 — Vulnerable Components
+- [ ] `npm audit` / `pip-audit` / `cargo audit` không có HIGH/CRITICAL
+- [ ] Dependencies cập nhật trong 6 tháng
+
+### A07 — Identification and Authentication Failures
+- [ ] MFA cho admin
+- [ ] Session timeout hợp lý
+- [ ] Logout invalidate token thật sự (server-side)
+- [ ] Password policy: min 8 char, không common password
+
+### A08 — Software and Data Integrity Failures
+- [ ] CI/CD pipeline pin version dependency
+- [ ] Subresource Integrity cho external scripts
+- [ ] Verify webhook signature (Stripe, GitHub, etc.)
+
+### A09 — Security Logging and Monitoring Failures
+- [ ] Log auth events (login success/fail)
+- [ ] Log access control fail
+- [ ] Log không chứa secrets/PII
+
+### A10 — Server-Side Request Forgery (SSRF)
+- [ ] Không cho user input URL để fetch không validate
+- [ ] Block private IP range (10.x, 192.168.x, 169.254.x)
+
+## Secrets scan command
+
+Chạy ở root project trước commit:
+
+```bash
+# Tìm các pattern khả nghi
+rg -i "(api[_-]?key|secret|token|password|private[_-]?key)\s*[:=]\s*['\"][^'\"]{8,}" \
+  --glob '!node_modules' --glob '!*.lock' --glob '!.env*' --glob '!CHANGELOG.md'
+
+# Check .env không vô tình commit
+git ls-files | grep -E '\.env$|\.env\.local$|\.env\.production$' && echo "WARNING: .env committed!"
+
+# Test bypass token check
+rg "TEST_BYPASS_TOKEN\s*=" --glob '!.env.test' --glob '!*.tpl'
+```
+
+## Khi nào delegate sang `security-auditor`
+
+- Task ảnh hưởng auth/authz
+- Task xử lý payment/PII
+- Task expose endpoint mới ra internet
+- Trước mỗi major release
+
+Sub-agent sẽ chạy checklist độc lập + scan secrets, output report ngắn để parent review.
+
+## Output bắt buộc
+
+Vào section `## Security Check` của plan:
+
+```markdown
+## Security Check
+
+**Date**: YYYY-MM-DD HH:mm
+**Checked by**: parent | security-auditor
+
+- [x] A01: ... (notes)
+- [x] A03: ... (notes)
+- [N/A] A10: không có user-input URL
+
+**Issues found**:
+- (none) | <description + plan to fix>
+
+**Secrets scan**: PASS | FAIL <details>
+```

package/skills/test-strategy/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: test-strategy
+description: "ON-DEMAND ONLY: chỉ kích hoạt khi user explicitly yêu cầu viết test (vd 'viết unit test cho X', 'add E2E cho login flow'), HOẶC khi bạn (AI) cần TDD-first cho bug fix khó. KHÔNG tự trigger trong quy trình bình thường (v1.5.0 đã bỏ Bước 6 Test khỏi core process). Phân tầng test: Unit ~70%, Integration ~20%, E2E ~10% với tools mặc định theo stack (Vitest/Jest/Pytest/Go test)."
+---
+
+# Test Strategy
+
+## Test Pyramid
+
+```
+         /\
+        /E2\        ~10% — chậm, đắt, kiểm tra user flow thật
+       /----\
+      / Inte \      ~20% — kiểm tra modules giao tiếp với nhau
+     /--------\
+    / Unit     \    ~70% — nhanh, kiểm tra function/class riêng lẻ
+   /------------\
+```
+
+## Chọn tool theo stack
+
+| Stack | Unit | Integration | E2E | Coverage |
+|---|---|---|---|---|
+| Node/TS | Vitest (default) hoặc Jest | Vitest + supertest/msw | Playwright | c8 (vitest), jest --coverage |
+| Python | Pytest | Pytest + httpx/responses | Playwright (python) | pytest-cov |
+| Go | go test | go test (build tag integration) | Playwright (gọi từ Go binary) | go test -cover |
+| Rust | cargo test | cargo test (integration_tests/) | Playwright | tarpaulin |
+
+Phát hiện stack qua: `package.json`, `pyproject.toml`/`requirements.txt`, `go.mod`, `Cargo.toml`.
+
+## Khi nào dùng loại nào
+
+### Unit test (~70%)
+
+- ✅ Logic thuần (validation, transform, computation)
+- ✅ Edge cases của 1 function
+- ✅ Pure functions, hooks không side-effect
+- ❌ Test framework code (React component render → integration thì hơn)
+
+### Integration test (~20%)
+
+- ✅ Module A gọi module B với data thật
+- ✅ API endpoint với mock DB hoặc test DB
+- ✅ React component với providers (router, store)
+- ❌ Test browser behavior thật → E2E
+
+### E2E test (~10%)
+
+- ✅ User flow critical (đăng ký, đăng nhập, checkout)
+- ✅ Cross-browser/multi-viewport behavior
+- ✅ Smoke test sau deploy
+- ❌ Test mọi edge case → quá chậm, dùng unit
+
+## Quy tắc viết test
+
+### 1. AAA Pattern (Arrange / Act / Assert)
+
+```ts
+test('parseDate trả null khi input rỗng', () => {
+  // Arrange
+  const input = '';
+  // Act
+  const result = parseDate(input);
+  // Assert
+  expect(result).toBeNull();
+});
+```
+
+### 2. Test name = behavior
+
+- ✅ "trả null khi input rỗng"
+- ✅ "throw khi user không có quyền admin"
+- ❌ "test parseDate" (vô nghĩa)
+- ❌ "should work" (không nói được gì)
+
+### 3. Một test → một behavior
+
+Nhiều `expect` OK nếu cùng một behavior. Nhưng nhiều behavior → tách test.
+
+### 4. Coverage không phải metric duy nhất
+
+- Aim: branch coverage **≥80%** cho code business
+- Aim: branch coverage **≥95%** cho code security/payment
+- KHÔNG aim 100% mù quáng — test trivial getters tốn công vô ích.
+
+## Bug fix workflow — TDD bắt buộc (Karpathy #4)
+
+> Tham khảo: [`templates/karpathy-reference.md`](../../templates/karpathy-reference.md) — nguyên tắc "Goal-Driven Execution".
+
+Cho **bug fix** (KHÔNG áp dụng cho feature mới — feature mới linh hoạt theo workflow chuẩn bên dưới):
+
+1. **Viết test reproducing bug TRƯỚC** — test phải FAIL.
+   - Test name = mô tả bug. Vd: `test('parseDate trả null khi input là "0"', ...)`.
+   - Chạy → confirm RED (fail đúng symptom user báo).
+2. **Commit test** riêng với message `test: reproduce <bug-summary>`.
+3. **Fix code**.
+4. Chạy lại → confirm GREEN.
+5. **Commit fix** riêng với message `fix: <bug-summary>`.
+6. (Optional) Refactor → vẫn GREEN.
+
+### Lý do TDD-first cho bug
+
+- Bug pass test sau fix nhưng KHÔNG có test reproducing → không chứng minh được bug exact đã fix → dễ regression.
+- 2 commit riêng (test + fix) giúp `git log` tự document được bug + fix tương ứng.
+- Reviewer thấy ngay test đã fail trước khi fix.
+
+### Output bắt buộc trong plan (cho bug fix)
+
+- [ ] Test reproducing bug đã viết và confirm FAIL trước khi fix → **Verify**: `git log --oneline | grep '^test: reproduce'`
+- [ ] Test PASS sau khi fix → **Verify**: command chạy test cụ thể trả 0 fail
+- [ ] 2 commit riêng (test + fix), không squash trước review
+
+## Workflow Bước 6a (feature mới)
+
+1. Đọc plan → xác định AC cần verify.
+2. Mỗi AC ≥ 1 test (unit/integration/E2E tùy nature).
+3. Viết test trước hoặc sau code đều OK (cho **feature mới**), nhưng phải xanh trước khi sang Bước 7.
+4. Chạy:
+   - JS/TS: `npx vitest run --coverage` (hoặc `jest --coverage`)
+   - Python: `pytest --cov`
+   - Go: `go test ./... -cover`
+5. Ghi coverage % vào plan section "Test Plan".
+6. Lưu kết quả vào `.cursor/.last-test-result` (hook `verify-completion` đọc):
+   ```json
+   {"status": "pass", "timestamp": "2026-04-23T14:30:00Z", "coverage": 87.5}
+   ```
+
+## Khi delegate sang `qa-autonomous`
+
+Nên delegate khi:
+- Test loop có thể nhiều iteration (>3 lần fix)
+- Test log dài, sẽ nhồi context parent
+- Cần debug deeper với nhiều variations
+
+Sub-agent tự loop test-fix-retest, chỉ báo cáo khi pass hoặc fail >3 lần.

package/skills/ui-test-loop/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: ui-test-loop
+description: "ON-DEMAND ONLY: chỉ kích hoạt khi user explicitly yêu cầu UI test loop (vd 'test UI mobile + tablet + desktop, fix lỗi rồi retest', 'visual regression test cho component X'). KHÔNG tự trigger trong quy trình bình thường (v1.5.0 đã bỏ hook ui-checkpoint). Workflow loop test-fix-retest cho UI/UX bằng Playwright. Hard limit 5 vòng trước khi escalate user."
+---
+
+# UI Test Loop với Checkpoint
+
+Workflow chuẩn để **AI tự test UI, tự fix, tự retest** đến khi đạt yêu cầu — nhưng có **safety checkpoint** mỗi 2 vòng để user duyệt và tránh đi sai hướng quá lâu.
+
+## Workflow
+
+```mermaid
+flowchart LR
+    Start[Đọc AC từ plan] --> Sess[Tạo .ui-session.json]
+    Sess --> Write[Viết Playwright test theo AC]
+    Write --> Run[Chạy multi-viewport]
+    Run --> Pass{Pass?}
+    Pass -->|Có| Done[Cleanup .ui-session.json + báo cáo]
+    Pass -->|Không| Fix[Đọc lỗi, sửa code]
+    Fix --> Inc[iter++]
+    Inc --> Limit{iter >= 10?}
+    Limit -->|Có| Escalate[Escalate user]
+    Limit -->|Không| Run
+```
+
+Hook `subagentStop` (`ui-checkpoint.sh`) tự động kích hoạt **mỗi 2 vòng subagent stop** — buộc subagent show screenshot trước khi tiếp tục.
+
+## Bước thực hiện (cho `ui-tester` subagent)
+
+### 1. Khởi tạo session
+
+Tạo file `.cursor/.ui-session.json` ở workspace để hook biết kích hoạt:
+
+```bash
+mkdir -p .cursor
+cat > .cursor/.ui-session.json <<EOF
+{
+  "plan_slug": "$(basename "$PLAN_FILE" .md)",
+  "started_at": "$(date -Iseconds)",
+  "iter": 0
+}
+EOF
+```
+
+Set env:
+```bash
+export PLAN_SLUG="2026-04-23-add-google-login"
+export UI_ITER=0
+```
+
+### 2. Đọc Acceptance Criteria
+
+Mở plan file → tìm section `## Acceptance Criteria`. Mỗi AC = 1 hoặc nhiều test case.
+
+### 3. Viết test
+
+```ts
+import { test, expect } from '@playwright/test';
+
+// AC1: Button "Đăng nhập Google" hiển thị icon + text đúng
+test('AC1: login button visible with correct content', async ({ page }, testInfo) => {
+  await page.goto('/login');
+  
+  const btn = page.getByRole('button', { name: /Đăng nhập Google/i });
+  await expect(btn).toBeVisible();
+  await expect(btn.locator('img[alt*="Google"]')).toBeVisible();
+  
+  await page.screenshot({
+    path: `tests/screenshots/${process.env.PLAN_SLUG}/iter-${process.env.UI_ITER}/${testInfo.project.name}-ac1.png`,
+    fullPage: true,
+  });
+});
+
+// AC2: Click button mở popup OAuth
+test('AC2: click opens OAuth popup', async ({ page, context }) => {
+  await page.goto('/login');
+  const popupPromise = context.waitForEvent('page');
+  await page.getByRole('button', { name: /Đăng nhập Google/i }).click();
+  const popup = await popupPromise;
+  await expect(popup).toHaveURL(/accounts\.google\.com/);
+});
+```
+
+### 4. Chạy test multi-viewport
+
+```bash
+UI_ITER=$((UI_ITER + 1)) npx playwright test login.spec.ts
+```
+
+Lưu kết quả:
+```bash
+STATUS=$([[ $? == 0 ]] && echo "pass" || echo "fail")
+echo "{\"status\": \"$STATUS\", \"timestamp\": \"$(date -Iseconds)\", \"tool\": \"playwright\", \"iter\": $UI_ITER}" > .cursor/.last-test-result
+```
+
+### 5. Loop quyết định
+
+```
+if test pass:
+  → cleanup .ui-session.json
+  → báo cáo "✅ UI tests pass sau N vòng. Screenshots tại tests/screenshots/<slug>/iter-N/"
+  → end
+
+if test fail:
+  → đọc lỗi từ tests/playwright-report/
+  → debug: ưu tiên fix CSS/component, KHÔNG sửa test cho match code sai
+  → UI_ITER++
+  → loop lại bước 4
+```
+
+### 6. Checkpoint (tự động qua hook)
+
+Hook `ui-checkpoint.sh` chạy ở `subagentStop`. Khi `loop_count` chia hết cho 2 → trả `followup_message` buộc subagent:
+- Show screenshot mới nhất ở `tests/screenshots/<slug>/iter-<n>/`
+- Mô tả ngắn những gì đã thử và kết quả
+- **Dừng và chờ user duyệt** trước khi loop tiếp
+
+User trả lời:
+- "OK tiếp tục" → loop tiếp
+- "Sửa thêm X" → adjust và loop
+- "Stop, tôi tự xử" → cleanup `.ui-session.json` và end
+
+### 7. Hard limit & Escalate
+
+Sau **5 checkpoint** (≈ 10 iteration), hook không gửi followup nữa, subagent phải:
+- Tóm tắt tất cả những gì đã thử (mỗi iter ngắn 1 dòng)
+- List screenshots quan trọng để user xem
+- Hypothesis: vì sao chưa pass
+- Đề xuất: cần user can thiệp gì
+
+## Quy tắc fix
+
+1. **Ưu tiên fix code, không fix test** — trừ khi test sai assertion.
+2. **Fix cause, không fix symptom** — nếu CSS overflow, sửa root cause (flex layout) thay vì hack `overflow: hidden`.
+3. **Một thay đổi 1 lần** — không fix nhiều thứ cùng lúc, khó debug.
+4. **Verify với 1 viewport trước**, OK mới chạy full multi-viewport.
+
+## Cleanup khi xong
+
+```bash
+rm -f .cursor/.ui-session.json
+unset PLAN_SLUG UI_ITER
+```
+
+## Output bắt buộc
+
+Trong báo cáo cuối:
+
+```markdown
+## UI Test Result
+
+- Plan: `plans/<plan-slug>.md`
+- Iterations: N
+- Checkpoints: M (user duyệt qua các vòng 2, 4, ...)
+- Final status: PASS | FAIL (escalated)
+- Screenshots: `tests/screenshots/<slug>/iter-<final>/`
+- Coverage AC:
+  - [x] AC1: ...
+  - [x] AC2: ...
+  - [ ] AC3: ... (escalate vì <reason>)
+```

package/src/cli.js

@@ -0,0 +1,63 @@
+const { setPkgRoot, isInstalled } = require("./lib/paths")
+const { getLocalVersion } = require("./lib/version")
+
+async function cli(pkgRoot) {
+  setPkgRoot(pkgRoot)
+
+  const cmd = process.argv[2]
+  const args = process.argv.slice(3)
+
+  switch (cmd) {
+    case "install":
+      return require("./commands/install").run(args)
+    case "init":
+      return require("./commands/init").run(args)
+    case "update":
+      return require("./commands/update").run(args)
+    case "uninstall":
+      return require("./commands/uninstall").run(args)
+    case "check":
+    case "--check":
+      return require("./commands/check").run(args)
+    case "--version":
+    case "-v":
+      console.log(`v${getLocalVersion() || "unknown"}`)
+      return
+    case "--help":
+    case "-h":
+    default:
+      return showHelp()
+  }
+}
+
+function showHelp() {
+  const v = getLocalVersion() || "unknown"
+
+  console.log(`
+OpenMoneta Dev Kit v${v}
+──────────────────────────────────────────────
+Biến Cursor IDE / OpenCode thành team developer hoàn chỉnh.
+
+  openmoneta install              Cài vào Cursor (~/.cursor/)
+  openmoneta install --opencode   Cài vào OpenCode (~/.config/opencode/)
+  openmoneta install --yes        Cài không hỏi xác nhận
+
+  openmoneta init                 Khởi tạo project (tạo AGENTS.md, docs/INDEX.md, plans/INDEX.md)
+  openmoneta init --opencode      Init cho OpenCode
+  openmoneta init /path/to/proj   Init project ở path chỉ định
+
+  openmoneta update               Update global + sync project hiện tại
+  openmoneta update --yes         Auto-sync, skip nếu đã latest
+  openmoneta update --check       Chỉ kiểm tra có version mới không
+
+  openmoneta check                Kiểm tra version mới nhất từ npm
+
+  openmoneta uninstall            Gỡ cài đặt
+
+Trạng thái: Cursor: ${isInstalled("cursor") ? "đã cài" : "chưa cài"} | OpenCode: ${isInstalled("opencode") ? "đã cài" : "chưa cài"}
+
+Docs: https://github.com/rapperkey/OpenMoneta-Dev-Kit
+`)
+}
+
+module.exports = { cli }

package/src/commands/check.js

@@ -0,0 +1,30 @@
+const { getLocalVersion, getLatestVersion } = require("../lib/version")
+
+async function run(args) {
+  const local = getLocalVersion()
+  const latest = getLatestVersion()
+
+  console.log(`\n  OpenMoneta Dev Kit`)
+  console.log(`  ─────────────────`)
+  console.log(`  Local : v${local || "unknown"}`)
+  console.log(`  Latest: v${latest || "không xác định (không có mạng?)"}`)
+
+  if (!latest) {
+    console.log(`\n  ❓ Không thể kiểm tra version mới nhất. Kiểm tra kết nối mạng.`)
+    return
+  }
+
+  if (!local) {
+    console.log(`\n  📦 Chưa cài đặt. Chạy: openmoneta install`)
+    return
+  }
+
+  if (local === latest) {
+    console.log(`\n  ✅ Đã ở phiên bản mới nhất.`)
+  } else {
+    console.log(`\n  🔔 Có phiên bản mới: v${local} → v${latest}`)
+    console.log(`     Chạy: openmoneta update`)
+  }
+}
+
+module.exports = { run }