dw-kit 1.2.1 → 1.3.0

package/.claude/skills/dw-decision/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: dw:decision
+description: "Tạo hoặc update Architecture Decision Record (ADR). Tự động đánh số, dùng template chuẩn. Wizard hướng dẫn qua: Context → Options → Decision → Consequences."
+argument-hint: "[tên quyết định ngắn gọn]"
+user-invocable: true
+---
+
+# ADR Wizard
+
+Decision: **$ARGUMENTS**
+
+## Bước 1 — Xác định số ADR
+
+1. Đọc `.dw/decisions/` (tạo nếu chưa có)
+2. Tìm file `NNNN-*.md` có số cao nhất
+3. New ID: `ADR-{max+1}` zero-padded 4 digits
+
+## Bước 2 — Thu thập input (hỏi user từng section)
+
+### Context
+- Tại sao decision này cần được đưa ra?
+- Forces đang tác động? (deadline, constraint, incident, opportunity)
+- Current state dẫn đến decision này là gì?
+
+### Options Considered (BẮT BUỘC ≥2 phương án)
+
+Cho MỖI option hỏi:
+- **Option N: {Name}**
+- **Pros:** (≥2 điểm cụ thể, không vague)
+- **Cons:** (≥1 điểm thật, không "not chosen" placeholder)
+- **Rejected because:** (nếu không chọn — lý do từ góc nhìn người quyết định)
+
+### Decision
+- Option nào được chọn?
+- **Why this one** (not "because it's best" — cite concrete reason từ context)
+
+### Consequences
+- **Positive:** (≥2 outcomes expected)
+- **Negative (trade-offs chấp nhận):** (≥1 — nếu nói "no cons" thì chưa nghĩ đủ)
+- **Neutral:** (optional — side effects không tốt cũng không xấu)
+
+### Metadata
+- **Status:** default `Proposed`
+- **Impact:** `patch` (small) | `minor` (feature-level) | `major` (breaking or strategic)
+- **Deciders:** tên hoặc role
+- **Cost estimate** (optional): rough effort
+
+## Bước 3 — Tạo file
+
+Path: `.dw/decisions/{NNNN}-{kebab-case-title}.md`
+
+Copy structure từ `.dw/decisions/_template.md`. Điền:
+
+```yaml
+---
+id: ADR-{NNNN}
+title: {title}
+status: Proposed
+date: {YYYY-MM-DD}
+deciders: {name}
+impact: {patch|minor|major}
+supersedes: null
+superseded-by: null
+---
+```
+
+Nếu là major impact → thêm section **Assumptions & Invalidation Triggers** và **Commitment Signals** (time-box).
+
+## Bước 4 — Confirm & save
+
+Show preview (first 30 lines) rồi ask:
+```
+Save this ADR to .dw/decisions/{NNNN}-{title}.md? (Y/n)
+```
+
+Nếu yes → write file + print:
+```
+✓ ADR-{NNNN} created
+  Status: Proposed
+  Next: Review → change status to Accepted when approved
+        Related task: update tracking.md với reference
+```
+
+## Quality Bar
+
+Reject auto-save nếu detect:
+- Options considered < 2
+- No "Rejected because" lý do cho options loại
+- Consequences Negative trống (nghĩa là không nghĩ kỹ)
+- Decision không cite cụ thể evidence từ context
+
+Trong các case này, đẩy lại user với câu hỏi clarify.
+
+## Khi NÀO Dùng ADR
+
+✅ Architectural choice (framework, DB, pattern)
+✅ Cross-cutting concern (auth, caching, logging)
+✅ Breaking change affecting users
+✅ Trade-off với long-term implications
+✅ Decision reverses earlier ADR (mark old as Superseded)
+
+❌ Bug fix (commit message đủ)
+❌ Implementation detail (code comments đủ)
+❌ Personal style preference
+
+## Examples
+
+- `.dw/decisions/0001-v2-pragmatic-lean.md` — strategic direction (major)
+- `.dw/decisions/0002-skill-naming-namespace.md` — breaking UX change (minor)
+
+## Super-power: Link related task
+
+Sau khi save ADR, nếu đang trong task folder (check `.dw/tasks/*/tracking.md` có reference đến decision này không):
+
+1. Append vào `tracking.md` section Changelog: `Referenced: ADR-{NNNN}`
+2. Update `spec.md` frontmatter `related_adr: ADR-{NNNN}` nếu chưa có

package/.claude/skills/dw-docs-update/SKILL.md

@@ -1,125 +1,125 @@
----
-name: dw-docs-update
-description: "Cập nhật living docs khi code thay đổi. Phát hiện docs lỗi thời và cập nhật tự động. Dùng sau khi execute hoặc commit."
-argument-hint: "[scope: all | architecture | api | models | task-name]"
----
-
-# Cập Nhật Living Docs
-
-Scope: **$ARGUMENTS**
-
-## Đọc Config
-
-Đọc `.dw/config/dw.config.yml` → kiểm tra:
-- `paths.docs` → thư mục living docs (mặc định: `.dw/docs`)
-- `workflow.default_depth` → nếu `quick`, gợi ý nhưng không bắt buộc
-
-## Living Docs Structure
-
-```
-{paths.docs}/
-├── ARCHITECTURE.md      # Kiến trúc tổng quan hệ thống
-├── API.md               # API endpoints & contracts
-├── DATA-MODELS.md       # Database schema & data models
-├── DECISIONS.md         # Architecture Decision Records (ADR)
-├── GLOSSARY.md          # Thuật ngữ dự án
-├── SETUP.md             # Hướng dẫn setup & chạy dự án
-└── modules/
-    └── [module-name].md # Docs riêng cho từng module
-```
-
-## Quy Trình
-
-### Bước 0: Scaffold (lần đầu chạy)
-
-Nếu `{paths.docs}/` không tồn tại hoặc trống → tạo cấu trúc ban đầu:
-```bash
-mkdir -p {paths.docs}/modules
-```
-Tạo các file skeleton: `ARCHITECTURE.md`, `API.md`, `DATA-MODELS.md`, `DECISIONS.md`, `GLOSSARY.md`, `SETUP.md`.
-Thông báo: "Khởi tạo living docs tại `{paths.docs}/` — lần chạy đầu tiên."
-
-### Nếu scope = "all" hoặc không có argument
-
-1. **Detect changes**:
-   ```bash
-   git diff --name-only HEAD~10   # 10 commits gần nhất
-   git diff --name-only --cached  # staged changes
-   ```
-
-2. **Classify changes** theo pattern:
-   | Pattern file | Docs cần update |
-   |-------------|-----------------|
-   | `*model*`, `*schema*`, `*migration*`, `*entity*` | `DATA-MODELS.md` |
-   | `*route*`, `*controller*`, `*handler*`, `*endpoint*` | `API.md` |
-   | `*config*`, `*app.*`, `package.json`, `*.yml` | `ARCHITECTURE.md` |
-   | `*.md` trong project (không phải `.dw/docs/`) | Kiểm tra DECISIONS.md |
-   | Thư mục mới xuất hiện | `ARCHITECTURE.md` + tạo `modules/[name].md` |
-
-3. **Stale check**: Với mỗi doc cần update, đọc nội dung hiện tại, so sánh với code thực tế. Ghi rõ: "Phần X đang mô tả Y nhưng code hiện tại là Z."
-
-4. **Update**: Chỉ cập nhật những gì thực sự lỗi thời. Thêm timestamp cuối mỗi update.
-
-### Nếu scope = "architecture"
-- Đọc cấu trúc thư mục, main config files, entry points
-- Cập nhật ARCHITECTURE.md với cấu trúc hiện tại
-
-### Nếu scope = "api"
-- Grep tất cả route/endpoint definitions
-- Cập nhật API.md với danh sách endpoints hiện tại
-
-### Nếu scope = "models"
-- Đọc schema definitions, migration files, model files
-- Cập nhật DATA-MODELS.md
-
-### Nếu scope = [task-name]
-- Đọc progress file của task
-- Cập nhật docs liên quan đến thay đổi của task
-
-## Khi Tạo Doc Mới (lần đầu)
-
-Nếu file doc chưa tồn tại → tạo mới với cấu trúc chuẩn:
-
-### ARCHITECTURE.md
-```markdown
-# Kiến Trúc Hệ Thống
-
-## Tổng Quan
-[Mô tả high-level]
-
-## Tech Stack
-| Layer | Technology |
-|-------|-----------|
-
-## Cấu Trúc Thư Mục
-[Tree structure]
-
-## Modules
-| Module | Vai trò | Entry point |
-|--------|---------|-------------|
-
-## Data Flow
-[Diagram]
-
-## Cập nhật lần cuối: [date]
-```
-
-### DECISIONS.md (ADR Format)
-```markdown
-# Architecture Decision Records
-
-## ADR-001: [Tiêu đề]
-- **Ngày**: [date]
-- **Trạng thái**: Accepted | Superseded | Deprecated
-- **Bối cảnh**: [Tại sao cần quyết định]
-- **Quyết định**: [Đã chọn gì]
-- **Hệ quả**: [Ảnh hưởng]
-```
-
-## Output
-
-Sau khi cập nhật, báo cáo:
-- Files đã cập nhật: [danh sách]
-- Thay đổi chính: [tóm tắt]
-- Docs vẫn có thể stale: [nếu có]
-- Ghi timestamp "Cập nhật lần cuối" vào mỗi doc file
+---
+name: dw:docs-update
+description: "Cập nhật living docs khi code thay đổi. Phát hiện docs lỗi thời và cập nhật tự động. Dùng sau khi execute hoặc commit."
+argument-hint: "[scope: all | architecture | api | models | task-name]"
+---
+
+# Cập Nhật Living Docs
+
+Scope: **$ARGUMENTS**
+
+## Đọc Config
+
+Đọc `.dw/config/dw.config.yml` → kiểm tra:
+- `paths.docs` → thư mục living docs (mặc định: `.dw/docs`)
+- `workflow.default_depth` → nếu `quick`, gợi ý nhưng không bắt buộc
+
+## Living Docs Structure
+
+```
+{paths.docs}/
+├── ARCHITECTURE.md      # Kiến trúc tổng quan hệ thống
+├── API.md               # API endpoints & contracts
+├── DATA-MODELS.md       # Database schema & data models
+├── DECISIONS.md         # Architecture Decision Records (ADR)
+├── GLOSSARY.md          # Thuật ngữ dự án
+├── SETUP.md             # Hướng dẫn setup & chạy dự án
+└── modules/
+    └── [module-name].md # Docs riêng cho từng module
+```
+
+## Quy Trình
+
+### Bước 0: Scaffold (lần đầu chạy)
+
+Nếu `{paths.docs}/` không tồn tại hoặc trống → tạo cấu trúc ban đầu:
+```bash
+mkdir -p {paths.docs}/modules
+```
+Tạo các file skeleton: `ARCHITECTURE.md`, `API.md`, `DATA-MODELS.md`, `DECISIONS.md`, `GLOSSARY.md`, `SETUP.md`.
+Thông báo: "Khởi tạo living docs tại `{paths.docs}/` — lần chạy đầu tiên."
+
+### Nếu scope = "all" hoặc không có argument
+
+1. **Detect changes**:
+   ```bash
+   git diff --name-only HEAD~10   # 10 commits gần nhất
+   git diff --name-only --cached  # staged changes
+   ```
+
+2. **Classify changes** theo pattern:
+   | Pattern file | Docs cần update |
+   |-------------|-----------------|
+   | `*model*`, `*schema*`, `*migration*`, `*entity*` | `DATA-MODELS.md` |
+   | `*route*`, `*controller*`, `*handler*`, `*endpoint*` | `API.md` |
+   | `*config*`, `*app.*`, `package.json`, `*.yml` | `ARCHITECTURE.md` |
+   | `*.md` trong project (không phải `.dw/docs/`) | Kiểm tra DECISIONS.md |
+   | Thư mục mới xuất hiện | `ARCHITECTURE.md` + tạo `modules/[name].md` |
+
+3. **Stale check**: Với mỗi doc cần update, đọc nội dung hiện tại, so sánh với code thực tế. Ghi rõ: "Phần X đang mô tả Y nhưng code hiện tại là Z."
+
+4. **Update**: Chỉ cập nhật những gì thực sự lỗi thời. Thêm timestamp cuối mỗi update.
+
+### Nếu scope = "architecture"
+- Đọc cấu trúc thư mục, main config files, entry points
+- Cập nhật ARCHITECTURE.md với cấu trúc hiện tại
+
+### Nếu scope = "api"
+- Grep tất cả route/endpoint definitions
+- Cập nhật API.md với danh sách endpoints hiện tại
+
+### Nếu scope = "models"
+- Đọc schema definitions, migration files, model files
+- Cập nhật DATA-MODELS.md
+
+### Nếu scope = [task-name]
+- Đọc progress file của task
+- Cập nhật docs liên quan đến thay đổi của task
+
+## Khi Tạo Doc Mới (lần đầu)
+
+Nếu file doc chưa tồn tại → tạo mới với cấu trúc chuẩn:
+
+### ARCHITECTURE.md
+```markdown
+# Kiến Trúc Hệ Thống
+
+## Tổng Quan
+[Mô tả high-level]
+
+## Tech Stack
+| Layer | Technology |
+|-------|-----------|
+
+## Cấu Trúc Thư Mục
+[Tree structure]
+
+## Modules
+| Module | Vai trò | Entry point |
+|--------|---------|-------------|
+
+## Data Flow
+[Diagram]
+
+## Cập nhật lần cuối: [date]
+```
+
+### DECISIONS.md (ADR Format)
+```markdown
+# Architecture Decision Records
+
+## ADR-001: [Tiêu đề]
+- **Ngày**: [date]
+- **Trạng thái**: Accepted | Superseded | Deprecated
+- **Bối cảnh**: [Tại sao cần quyết định]
+- **Quyết định**: [Đã chọn gì]
+- **Hệ quả**: [Ảnh hưởng]
+```
+
+## Output
+
+Sau khi cập nhật, báo cáo:
+- Files đã cập nhật: [danh sách]
+- Thay đổi chính: [tóm tắt]
+- Docs vẫn có thể stale: [nếu có]
+- Ghi timestamp "Cập nhật lần cuối" vào mỗi doc file

package/.claude/skills/dw-estimate/SKILL.md

@@ -1,90 +1,90 @@
----
-name: dw-estimate
-description: "Ước lượng effort cho task. Phân tích subtasks từ plan và đưa ra estimate theo đơn vị cấu hình (hours/story-points/t-shirt). Dùng sau /plan."
-argument-hint: "[task-name]"
-allowed-tools:
-  - Read
-  - Grep
-  - Glob
----
-
-# Ước Lượng Effort
-
-Task: **$ARGUMENTS**
-
-## Đọc Config
-
-Đọc `.dw/config/dw.config.yml`:
-- `tracking.estimation` — nếu `false` → thông báo "Estimation chưa bật cho project này" và DỪNG
-- `tracking.estimation_unit` → đơn vị (hours / story-points / t-shirt)
-- `paths.tasks` → location task docs
-
-## Điều Kiện
-
-Nếu chưa có plan (`{paths.tasks}/$ARGUMENTS/$ARGUMENTS-plan.md`) → thông báo cần chạy `/dw-plan` trước.
-
-## Quy Trình Estimation
-
-### 1. Đọc plan & context
-- Đọc toàn bộ subtasks
-- Đọc context để hiểu technical complexity
-- Hiểu dependencies giữa subtasks
-
-### 2. Estimate từng subtask
-
-Với mỗi subtask, phân tích:
-- **Complexity**: Low / Medium / High
-  - Low: Rõ ràng, ít dependencies, code cũ đã có pattern
-  - Medium: Cần thiết kế, có vài dependencies
-  - High: Phức tạp, nhiều unknowns, cần research thêm
-- **Uncertainty**: Low / Medium / High (có unknown chưa giải quyết?)
-- **Estimate**: Dựa trên complexity + uncertainty
-
-**Reference nhanh (hours):**
-| Complexity | Low uncertainty | Medium | High uncertainty |
-|-----------|-----------------|--------|-----------------|
-| Low | 1-2h | 2-4h | 4-8h |
-| Medium | 2-4h | 4-8h | 8-16h |
-| High | 4-8h | 8-16h | 16-40h |
-
-**Reference (story points - Fibonacci):** 1, 2, 3, 5, 8, 13, 21
-**Reference (t-shirt):** XS(<2h), S(2-4h), M(4-8h), L(8-16h), XL(16-40h), XXL(>40h)
-
-### 3. Uncertainty buffer
-
-- Low uncertainty overall: +0%
-- Medium: +20%
-- High: +50%
-- Nhiều unknowns / first-time tech: +100% (double)
-
-### 4. Breakdown theo categories
-
-```
-Research:      [X]
-Planning:      [done]
-Coding:        [X per subtask]
-Testing:       [X — thường 20-30% coding]
-Review:        [X — thường 10-15% coding]
-Documentation: [X — nếu living docs bật]
-Buffer:        [X%]
-Total:         [sum]
-```
-
-## Ghi Vào Plan
-
-Cập nhật phần "Estimation Tổng" trong plan file.
-
-## Trình Bày
-
-```markdown
-## Estimation Summary: $ARGUMENTS
-
-| Subtask | Complexity | Uncertainty | Estimate |
-|---------|-----------|-------------|---------|
-| ST-1 | Low | Low | 2h |
-| ST-2 | Medium | Medium | 6h |
-
-**Total Estimate**: X hours (với buffer Y%)
-**Confidence**: High / Medium / Low
-**Risk note**: [nếu có unknowns lớn]
-```
+---
+name: dw:estimate
+description: "Ước lượng effort cho task. Phân tích subtasks từ plan và đưa ra estimate theo đơn vị cấu hình (hours/story-points/t-shirt). Dùng sau /plan."
+argument-hint: "[task-name]"
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+---
+
+# Ước Lượng Effort
+
+Task: **$ARGUMENTS**
+
+## Đọc Config
+
+Đọc `.dw/config/dw.config.yml`:
+- `tracking.estimation` — nếu `false` → thông báo "Estimation chưa bật cho project này" và DỪNG
+- `tracking.estimation_unit` → đơn vị (hours / story-points / t-shirt)
+- `paths.tasks` → location task docs
+
+## Điều Kiện
+
+Nếu chưa có plan (`{paths.tasks}/$ARGUMENTS/$ARGUMENTS-plan.md`) → thông báo cần chạy `/dw:plan` trước.
+
+## Quy Trình Estimation
+
+### 1. Đọc plan & context
+- Đọc toàn bộ subtasks
+- Đọc context để hiểu technical complexity
+- Hiểu dependencies giữa subtasks
+
+### 2. Estimate từng subtask
+
+Với mỗi subtask, phân tích:
+- **Complexity**: Low / Medium / High
+  - Low: Rõ ràng, ít dependencies, code cũ đã có pattern
+  - Medium: Cần thiết kế, có vài dependencies
+  - High: Phức tạp, nhiều unknowns, cần research thêm
+- **Uncertainty**: Low / Medium / High (có unknown chưa giải quyết?)
+- **Estimate**: Dựa trên complexity + uncertainty
+
+**Reference nhanh (hours):**
+| Complexity | Low uncertainty | Medium | High uncertainty |
+|-----------|-----------------|--------|-----------------|
+| Low | 1-2h | 2-4h | 4-8h |
+| Medium | 2-4h | 4-8h | 8-16h |
+| High | 4-8h | 8-16h | 16-40h |
+
+**Reference (story points - Fibonacci):** 1, 2, 3, 5, 8, 13, 21
+**Reference (t-shirt):** XS(<2h), S(2-4h), M(4-8h), L(8-16h), XL(16-40h), XXL(>40h)
+
+### 3. Uncertainty buffer
+
+- Low uncertainty overall: +0%
+- Medium: +20%
+- High: +50%
+- Nhiều unknowns / first-time tech: +100% (double)
+
+### 4. Breakdown theo categories
+
+```
+Research:      [X]
+Planning:      [done]
+Coding:        [X per subtask]
+Testing:       [X — thường 20-30% coding]
+Review:        [X — thường 10-15% coding]
+Documentation: [X — nếu living docs bật]
+Buffer:        [X%]
+Total:         [sum]
+```
+
+## Ghi Vào Plan
+
+Cập nhật phần "Estimation Tổng" trong plan file.
+
+## Trình Bày
+
+```markdown
+## Estimation Summary: $ARGUMENTS
+
+| Subtask | Complexity | Uncertainty | Estimate |
+|---------|-----------|-------------|---------|
+| ST-1 | Low | Low | 2h |
+| ST-2 | Medium | Medium | 6h |
+
+**Total Estimate**: X hours (với buffer Y%)
+**Confidence**: High / Medium / Low
+**Risk note**: [nếu có unknowns lớn]
+```