dw-kit 1.0.1 → 1.1.0

package/.claude/rules/code-style.md

@@ -1,37 +1,37 @@
-# Code Style & Conventions
-
-## Nguyên tắc chung
-- Đặt tên biến/hàm rõ ràng, tự giải thích (self-documenting)
-- Ưu tiên đơn giản, dễ đọc hơn clever code
-- Mỗi function làm MỘT việc
-- Comments giải thích WHY, không phải WHAT
-- Xử lý errors ở đầu function (guard clauses / early return)
-
-## Naming Conventions
-- Variables/Functions: camelCase
-- Classes/Components: PascalCase
-- Constants: UPPER_SNAKE_CASE
-- Files: kebab-case hoặc theo convention của framework
-- Directories: kebab-case
-
-## File Organization
-- 1 component/class per file (trừ khi strongly related)
-- Group imports: external → internal → relative
-- Export ở cuối file hoặc inline (nhất quán trong project)
-
-## Error Handling
-- KHÔNG swallow errors (catch rỗng)
-- Log đủ context để debug (error message, input data, stack)
-- Dùng custom error types cho domain errors
-- Validate input ở boundary (API, form, external data)
-
-## Testing
-- Test file cùng tên với source: `foo.ts` → `foo.test.ts` hoặc `foo.spec.ts`
-- Mỗi test case kiểm tra MỘT behavior
-- Test name mô tả expected behavior: "should return error when input is empty"
-- Arrange → Act → Assert pattern
-- KHÔNG mock internal implementation details
-
-## NOTE
-Đây là quy tắc mặc định. Team tùy chỉnh theo stack cụ thể của dự án.
-Thêm framework-specific rules vào file này hoặc tạo file riêng trong `.claude/rules/`.
+# Code Style & Conventions
+
+## Nguyên tắc chung
+- Đặt tên biến/hàm rõ ràng, tự giải thích (self-documenting)
+- Ưu tiên đơn giản, dễ đọc hơn clever code
+- Mỗi function làm MỘT việc
+- Comments giải thích WHY, không phải WHAT
+- Xử lý errors ở đầu function (guard clauses / early return)
+
+## Naming Conventions
+- Variables/Functions: camelCase
+- Classes/Components: PascalCase
+- Constants: UPPER_SNAKE_CASE
+- Files: kebab-case hoặc theo convention của framework
+- Directories: kebab-case
+
+## File Organization
+- 1 component/class per file (trừ khi strongly related)
+- Group imports: external → internal → relative
+- Export ở cuối file hoặc inline (nhất quán trong project)
+
+## Error Handling
+- KHÔNG swallow errors (catch rỗng)
+- Log đủ context để debug (error message, input data, stack)
+- Dùng custom error types cho domain errors
+- Validate input ở boundary (API, form, external data)
+
+## Testing
+- Test file cùng tên với source: `foo.ts` → `foo.test.ts` hoặc `foo.spec.ts`
+- Mỗi test case kiểm tra MỘT behavior
+- Test name mô tả expected behavior: "should return error when input is empty"
+- Arrange → Act → Assert pattern
+- KHÔNG mock internal implementation details
+
+## NOTE
+Đây là quy tắc mặc định. Team tùy chỉnh theo stack cụ thể của dự án.
+Thêm framework-specific rules vào file này hoặc tạo file riêng trong `.claude/rules/`.

package/.claude/rules/commit-standards.md

@@ -1,37 +1,37 @@
-# Commit Standards
-
-## Format
-```
-<type>(<scope>): <mô tả tiếng Việt hoặc tiếng Anh>
-
-[Body - chi tiết thay đổi, lý do]
-[Blank line]
-[Footer - breaking changes, references]
-
-Co-Authored-By: Claude <noreply@anthropic.com>
-```
-
-## Types
-| Type | Khi nào dùng |
-|------|-------------|
-| `feat` | Tính năng mới |
-| `fix` | Sửa lỗi |
-| `refactor` | Tái cấu trúc, không thay đổi behavior |
-| `test` | Thêm/sửa tests |
-| `docs` | Tài liệu, comments |
-| `chore` | Build, config, dependencies |
-| `style` | Format, whitespace (không thay đổi logic) |
-| `perf` | Cải thiện performance |
-
-## Quy tắc
-- Mỗi commit = 1 subtask hoặc 1 đơn vị logic hoàn chỉnh
-- Mô tả ngắn <= 72 ký tự
-- Dùng thì hiện tại: "thêm", "sửa", "cập nhật" (không phải "đã thêm")
-- KHÔNG commit files chứa secrets (.env, credentials, tokens)
-- KHÔNG commit console.log/debugger còn sót
-
-## Branch Naming
-```
-<type>/<task-name>
-```
-Ví dụ: `feat/user-auth`, `fix/login-redirect`, `refactor/api-structure`
+# Commit Standards
+
+## Format
+```
+<type>(<scope>): <mô tả tiếng Việt hoặc tiếng Anh>
+
+[Body - chi tiết thay đổi, lý do]
+[Blank line]
+[Footer - breaking changes, references]
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+## Types
+| Type | Khi nào dùng |
+|------|-------------|
+| `feat` | Tính năng mới |
+| `fix` | Sửa lỗi |
+| `refactor` | Tái cấu trúc, không thay đổi behavior |
+| `test` | Thêm/sửa tests |
+| `docs` | Tài liệu, comments |
+| `chore` | Build, config, dependencies |
+| `style` | Format, whitespace (không thay đổi logic) |
+| `perf` | Cải thiện performance |
+
+## Quy tắc
+- Mỗi commit = 1 subtask hoặc 1 đơn vị logic hoàn chỉnh
+- Mô tả ngắn <= 72 ký tự
+- Dùng thì hiện tại: "thêm", "sửa", "cập nhật" (không phải "đã thêm")
+- KHÔNG commit files chứa secrets (.env, credentials, tokens)
+- KHÔNG commit console.log/debugger còn sót
+
+## Branch Naming
+```
+<type>/<task-name>
+```
+Ví dụ: `feat/user-auth`, `fix/login-redirect`, `refactor/api-structure`

package/.claude/rules/workflow-rules.md

@@ -12,6 +12,8 @@ Trước khi thực hiện bất kỳ skill nào, PHẢI đọc `.dw/config/dw.c
 
 | Skill | Level 1 | Level 2 | Level 3 |
 |-------|---------|---------|---------|
+| onboard | yes | yes | yes |
+| retroactive | yes | yes | yes |
 | task-init | yes | yes | yes |
 | research | yes | yes | yes |
 | plan | skip | yes | yes |
@@ -43,6 +45,19 @@ Trước khi thực hiện bất kỳ skill nào, PHẢI đọc `.dw/config/dw.c
 - Ghi rõ: đang ở subtask nào, blockers, context quan trọng
 - Commit work-in-progress nếu có thay đổi đáng kể
 
+## Adoption Workflow (Existing Project)
+
+```
+Lần đầu dùng dw trên project đang chạy:
+/dw-onboard → .dw/context/project-map.md + module docs (breadth-first)
+     ↓
+Khi cần AI hiểu sâu module cụ thể:
+/dw-retroactive [module] → .dw/tasks/[module]/ as-built docs (depth-first)
+     ↓
+Task mới liên quan module đã documented:
+/dw-research [task] → AI đọc context có sẵn làm foundation
+```
+
 ## Multi-Role Workflow
 
 ```

package/.claude/settings.json

@@ -52,7 +52,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "Trước khi kết thúc, kiểm tra: (1) Có uncommitted changes quan trọng không? (2) Task đang làm dở chưa cập nhật progress? (3) Có blocker nào chưa ghi lại? Nếu có vấn đề, trả về {\"decision\": \"block\", \"reason\": \"[mô tả]\"}. Nếu OK, trả về {\"decision\": \"allow\"}."
+            "prompt": "Session context: $ARGUMENTS\n\nIf stop_hook_active is true in the context above, reply ONLY: {\"decision\":\"allow\"} to prevent infinite loops.\n\nOtherwise check: any uncommitted important changes? any in-progress task with outdated progress file? any unrecorded blockers?\n\nReply with ONLY valid JSON, no other text:\n- {\"decision\":\"block\",\"reason\":\"<describe what needs attention>\"} if action needed\n- {\"decision\":\"allow\"} if all clear"
           }
         ]
       }

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

@@ -0,0 +1,201 @@
+---
+name: dw-onboard
+description: "Onboard dw-kit vào project đang chạy. Scan codebase, tạo project map và context docs cho các modules hiện có. Chạy một lần khi adopt dw vào existing project."
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Write
+  - "Bash(git log *)"
+  - "Bash(git shortlog *)"
+  - "Bash(ls *)"
+  - "Bash(wc *)"
+---
+
+# dw-onboard — Onboard Existing Project vào dw-kit
+
+> Dùng khi adopt dw-kit vào project đã chạy. Chạy **một lần**. Output là project map và context docs cho các modules hiện có — làm nền tảng cho AI trong các sessions sau.
+
+---
+
+## Đọc Config
+
+Đọc `.dw/config/dw.config.yml`:
+- `paths.tasks` → base tasks path
+- `project.language` → ngôn ngữ output
+- `project.name` → tên project
+
+## Bước 1: Khám phá cấu trúc project
+
+Scan top-level structure của codebase:
+
+```
+Glob: src/**, app/**, lib/**, packages/**, services/**, modules/**
+Bash: ls -la (top level)
+```
+
+Xác định:
+- **Project type**: monorepo / single app / microservices / library
+- **Tech stack**: ngôn ngữ, framework chính (từ package.json, go.mod, requirements.txt, Cargo.toml, v.v.)
+- **Entry points**: main files, index files, routers
+- **Major directories**: mỗi dir là 1 potential module
+
+## Bước 2: Phân loại modules
+
+Với mỗi major directory/module, xác định:
+
+| Module | Type | Vai trò | Files | Phức tạp? |
+|--------|------|---------|-------|-----------|
+| [dir] | feature/service/util/infra | [mô tả 1 dòng] | [số files] | Cao/TB/Thấp |
+
+**Phức tạp = Cao** nếu: nhiều files (>10), có DB/API, business logic phức tạp.
+→ Modules phức tạp Cao: recommend `/dw-retroactive [module]` sau.
+
+## Bước 3: Phân tích nhanh từng module
+
+Với mỗi module (không cần đọc toàn bộ — chỉ đọc đủ để hiểu):
+
+1. **Entry file**: đọc file chính (index, main, router, controller)
+2. **Exports/Public API**: function/class/endpoint nào được expose?
+3. **Dependencies**: module này gọi đến module nào khác?
+4. **Git activity**: `git shortlog --since="6 months ago" -- [path]` → ai đang maintain?
+
+Ghi tóm tắt ngắn gọn (3-5 dòng) per module.
+
+## Bước 4: Check git history toàn project
+
+```bash
+git log --oneline --since="3 months ago" | head -30
+git shortlog -sn --since="3 months ago" | head -10
+```
+
+Xác định:
+- Modules nào đang active development
+- Modules nào stable / ít thay đổi
+- Contributors chính
+
+## Bước 5: Tạo output
+
+### 5a. Project Map
+
+Tạo `.dw/context/project-map.md`:
+
+```markdown
+# Project Map: [project.name]
+
+## Ngày tạo: [date]
+## Tạo bởi: dw-onboard
+
+---
+
+## Tech Stack
+
+- **Ngôn ngữ**: [language]
+- **Framework**: [framework]
+- **Database**: [db nếu có]
+- **Infrastructure**: [docker, k8s, cloud nếu có]
+
+## Cấu Trúc Tổng Quan
+
+```
+[ASCII tree của top-level structure]
+```
+
+## Modules
+
+| Module | Type | Vai trò | Phức tạp | Active? | Deep-dive? |
+|--------|------|---------|----------|---------|------------|
+| [name] | [type] | [mô tả ngắn] | Cao/TB/Thấp | Có/Không | `/dw-retroactive [name]` |
+
+## Dependencies giữa Modules
+
+```
+[Module A] → [Module B] → [Module C]
+     ↓
+[Module D]
+```
+
+## Entry Points chính
+
+- [file/endpoint]: [mô tả]
+
+## Conventions phát hiện
+
+- [Convention 1]: [mô tả]
+- [Convention 2]
+
+## Git Activity (3 tháng gần nhất)
+
+- **Active modules**: [danh sách]
+- **Stable modules**: [danh sách]
+- **Top contributors**: [tên]
+
+## Gợi ý Deep-dive
+
+Các modules phức tạp nên chạy `/dw-retroactive` để AI có context đầy đủ:
+- [ ] `/dw-retroactive [module-a]` — [lý do: nhiều files, core business logic]
+- [ ] `/dw-retroactive [module-b]`
+```
+
+### 5b. Module context docs
+
+Với mỗi module **phức tạp Cao**: tạo `.dw/context/modules/[module-name].md`:
+
+```markdown
+# Module: [module-name]
+
+## Vai trò
+[1-2 câu mô tả]
+
+## Files chính
+| File | Vai trò |
+|------|---------|
+| [file] | [vai trò] |
+
+## Public API / Exports
+- [function/endpoint]: [mô tả]
+
+## Dependencies
+- Upstream: [modules gọi đến đây]
+- Downstream: [modules được đây gọi]
+
+## Conventions riêng
+- [Convention đặc thù của module này]
+
+## Lưu ý cho AI
+- [Gotchas, tech debt, context quan trọng]
+```
+
+Với modules **phức tạp TB/Thấp**: chỉ ghi entry trong project-map.md, không tạo file riêng.
+
+## Bước 6: Báo cáo kết quả
+
+```
+╔══════════════════════════════════════════════════════╗
+║  ✅ dw-onboard complete: [project.name]
+╠══════════════════════════════════════════════════════╣
+║  Modules discovered   : [N]
+║  Docs tạo             :
+║    .dw/context/project-map.md
+║    .dw/context/modules/[X files]
+║  Tech stack           : [summary]
+╠══════════════════════════════════════════════════════╣
+║  Gợi ý tiếp theo:
+║  Modules phức tạp cần deep-dive:
+║  → /dw-retroactive [module-a]
+║  → /dw-retroactive [module-b]
+║
+║  Khi bắt đầu task mới liên quan module đã có:
+║  → AI sẽ tự đọc .dw/context/ để có context
+╚══════════════════════════════════════════════════════╝
+```
+
+---
+
+## Lưu ý
+
+- **Không tạo `.dw/tasks/`** — onboard output vào `.dw/context/`, tách khỏi task docs
+- **Không đọc toàn bộ code** — chỉ cần đủ để hiểu vai trò và interface của module
+- **Không analyze chi tiết logic** — đó là việc của `/dw-retroactive` khi cần deep-dive
+- Nếu project đã có `.dw/context/project-map.md` → hỏi user: "Đã có project map. Update hay skip?"

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

@@ -0,0 +1,62 @@
+---
+name: dw-prompt
+description: "Improve a vague task description into a clear, actionable prompt. Uses git log + recent dw tasks for project context. Output is concise — human dev will refine further."
+argument-hint: "[task description] [--vi]"
+---
+
+# Prompt Builder
+
+Input: **$ARGUMENTS**
+
+## Bước 0 — Parse options
+
+- Nếu `$ARGUMENTS` chứa `--vi`: output bằng **tiếng Việt**, bỏ flag `--vi` ra khỏi description
+- Mặc định: output bằng **tiếng Anh**
+
+## Bước 1 — Lấy context từ git log
+
+Extract 1–2 keywords chính từ description (bỏ qua stop words: fix, add, feat, the, a, in, of).
+
+Chạy **cả hai** để có context tốt nhất:
+
+```bash
+# Tìm commits liên quan theo keyword
+git log --oneline --no-merges --all --grep="<keyword1>" -15
+git log --oneline --no-merges --all --grep="<keyword2>" -15
+
+# Fallback: 30 commits gần nhất
+git log --oneline --no-merges -30
+```
+
+Dùng kết quả để nhận ra: module names, naming conventions, commit style của project.
+
+## Bước 2 — Lấy context từ dw tasks gần đây
+
+Đọc danh sách task đang/đã làm:
+
+```bash
+ls .dw/tasks/
+```
+
+Nếu có task liên quan đến keyword → đọc file `*-progress.md` để hiểu thêm context (scope, decisions, findings).
+
+## Bước 3 — Improve prompt
+
+**Nếu $ARGUMENTS rỗng (sau khi bỏ flags):** hỏi ngắn "Describe your task:" trước.
+
+**Rules:**
+- **1–2 dòng tối đa** — human dev sẽ tự sửa thêm
+- Giữ: **what** + **scope** (nếu rõ từ context) + **outcome** (nếu rõ)
+- Active voice, present tense: "Fix...", "Add...", "Refactor..."
+- Không bullet points, không markdown headers trong output
+- Match naming conventions từ git log nếu nhận ra được
+
+## Output format
+
+```
+─── Improved prompt ──────────────────────
+<1–2 line improved prompt>
+──────────────────────────────────────────
+```
+
+Không thêm gì khác ngoài block trên.