dw-kit 1.0.2 → 1.2.0

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

@@ -0,0 +1,311 @@
+---
+name: dw-retroactive
+description: "Retroactively document một feature/task đã được implement trước khi dùng dw. Reverse-engineer từ code + git history, tạo đầy đủ context + as-built plan + progress docs. Dùng khi cần AI hiểu sâu một module cũ."
+argument-hint: "[feature-name]"
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Write
+  - "Bash(git log *)"
+  - "Bash(git diff *)"
+  - "Bash(git show *)"
+  - "Bash(git blame *)"
+  - "Bash(git shortlog *)"
+  - "Bash(ls *)"
+---
+
+# dw-retroactive — Retroactive Documentation
+
+Feature: **$ARGUMENTS**
+
+> Reverse-engineer feature đã tồn tại từ code và git history. Tạo đầy đủ task docs như thể đã đi qua workflow dw — để AI (và team) có context đầy đủ khi làm việc liên quan feature này.
+
+---
+
+## Đọc Config
+
+Đọc `.dw/config/dw.config.yml`:
+- `paths.tasks` → output location (mặc định `.dw/tasks`)
+- `project.language` → ngôn ngữ docs
+
+## Kiểm tra đã có docs chưa
+
+Kiểm tra `{paths.tasks}/$ARGUMENTS/` đã tồn tại chưa:
+- Nếu rồi → hỏi user: "Đã có task docs cho `$ARGUMENTS`. Overwrite hay skip?"
+- Nếu chưa → tiếp tục
+
+---
+
+## Bước 1: Tìm files liên quan
+
+Dùng tên `$ARGUMENTS` như keyword để tìm:
+
+```
+Glob: **/*$ARGUMENTS*
+Grep: "$ARGUMENTS" trong toàn codebase (case-insensitive)
+Grep: tên function/class/route liên quan (nếu có thể suy ra từ tên)
+```
+
+Nếu không tìm được → hỏi user: "Không tìm thấy files liên quan `$ARGUMENTS`. Bạn có thể cung cấp thêm keyword hoặc path không?"
+
+## Bước 2: Đọc và phân tích code
+
+Với mỗi file tìm được:
+
+1. **Đọc toàn bộ file** (hoặc phần liên quan)
+2. Xác định:
+   - Vai trò của file trong feature này
+   - Logic chính / business rules
+   - Input/Output/Side effects
+   - Error handling patterns
+3. **Trace data flow**: đầu vào từ đâu → xử lý gì → kết quả đi đâu
+4. **Tìm dependencies**: module này gọi gì? Ai gọi module này?
+5. **Tìm tests**: test files liên quan, coverage hiện tại
+
+## Bước 3: Phân tích git history
+
+```bash
+# Commits liên quan feature
+git log --oneline --follow -- [files-found]
+
+# Ai đã implement
+git shortlog -sn -- [files-found]
+
+# Thay đổi đáng kể
+git log --oneline --diff-filter=A -- [files-found]   # khi files được tạo
+
+# Context của lần commit đầu tiên
+git show [first-commit] --stat
+```
+
+Xác định:
+- Feature được tạo khi nào
+- Ai implement (để biết ai có thể được hỏi)
+- Có breaking changes nào đã được fix sau đó không
+- Tech debt nào đang tồn tại (TODO, FIXME trong code)
+
+## Bước 4: Áp dụng tư duy phản biện
+
+Từ framework `core/THINKING.md` (hoặc `.claude/skills/dw-thinking/THINKING.md`):
+
+- **Giả định**: Code đang giả định gì về input, state, environment?
+- **Failure modes**: Điều gì có thể làm feature này fail? Edge cases nào?
+- **Tech debt**: Có TODO/FIXME? Có antipatterns? Code mùi?
+- **Security**: Có điểm nào đáng lo ngại về auth, validation, data exposure?
+
+## Bước 5: Tạo task docs
+
+Tạo thư mục `{paths.tasks}/$ARGUMENTS/` và 3 files:
+
+### 5a. Context doc
+
+Tạo `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-context.md`:
+
+```markdown
+# Context: $ARGUMENTS
+
+## Ngày khảo sát: [date]
+## Loại: Retroactive Documentation
+## Người thực hiện: agent (dw-retroactive)
+
+---
+
+## Mô Tả Feature
+
+[2-3 câu mô tả feature làm gì, phục vụ ai]
+
+## Codebase Analysis
+
+### Files Liên Quan
+
+| # | File | Vai trò | Ghi chú |
+|---|------|---------|---------|
+| 1 | [file] | [vai trò] | |
+
+### Kiến Trúc
+
+```
+[ASCII diagram hoặc mô tả luồng]
+Input → [Module] → Output
+           ↓
+      [Dependencies]
+```
+
+### Data Flow
+
+- **Input**: [từ đâu, format gì]
+- **Processing**: [logic chính]
+- **Output**: [đi đâu, format gì]
+- **Side effects**: [DB writes, events, external calls]
+
+## Dependencies
+
+### Upstream (feature phụ thuộc vào)
+- [ ] [Module/Service] — [vai trò]
+
+### Downstream (ai phụ thuộc vào feature này)
+- [ ] [Module/Service] — [ảnh hưởng thế nào]
+
+## Git History
+
+- **Tạo lần đầu**: [date] bởi [author]
+- **Commits**: [N commits]
+- **Maintainer chính**: [author]
+- **Thay đổi đáng kể**: [mô tả nếu có]
+
+## Test Coverage
+
+- [ ] Có tests: [Có/Không]
+- Test files: [danh sách]
+- Coverage: [mô tả]
+- Gaps: [thiếu test ở đâu]
+
+## Giả Định & Hạn Chế
+
+| # | Giả định/Hạn chế | Mức độ rủi ro |
+|---|-----------------|--------------|
+| 1 | [giả định trong code] | Cao/TB/Thấp |
+
+## Tech Debt & Warnings
+
+- [ ] [TODO/FIXME đang có]
+- [ ] [Antipatterns phát hiện]
+- [ ] [Security concerns]
+
+## Ghi Chú Cho AI
+
+> Context quan trọng khi làm task liên quan feature này:
+- [Gotcha 1]
+- [Gotcha 2]
+```
+
+### 5b. As-Built Plan doc
+
+Tạo `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-plan.md`:
+
+```markdown
+# As-Built Plan: $ARGUMENTS
+
+## Ngày tạo: [date]
+## Loại: As-Built (Retroactive) — không phải forward plan
+## Trạng thái: Done (implemented trước khi adopt dw)
+## Implemented by: [author từ git history]
+
+---
+
+> ⚠ Đây là tài liệu retroactive — mô tả những gì ĐÃ được implement,
+> không phải plan cho việc sẽ làm. Dùng để AI và team hiểu context.
+
+## Tóm Tắt Giải Pháp Đã Implement
+
+[Mô tả approach được dùng, dựa trên code analysis]
+
+## Những Gì Đã Implement
+
+### Component 1: [Tên]
+- **Mô tả**: [làm gì]
+- **Files**: [danh sách]
+- **Cách hoạt động**: [tóm tắt logic]
+
+### Component 2: [Tên]
+...
+
+## Quyết Định Kỹ Thuật Đáng Chú Ý
+
+| Quyết định | Approach đã dùng | Lý do suy đoán |
+|-----------|-----------------|----------------|
+| [decision] | [approach] | [inferred from code/commits] |
+
+## Rủi Ro & Hạn Chế Đã Biết
+
+| # | Mô tả | Mức độ | Trạng thái |
+|---|-------|--------|-----------|
+| 1 | [risk] | Cao/TB/Thấp | Open/Resolved |
+
+## Edge Cases
+
+- [ ] [Edge case được xử lý hay chưa?]
+
+## Tác Động Hệ Thống
+
+- **Modules ảnh hưởng**: [danh sách]
+- **API**: [endpoints liên quan]
+- **Database**: [schema/tables liên quan]
+```
+
+### 5c. Progress doc
+
+Tạo `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-progress.md`:
+
+```markdown
+# Progress: $ARGUMENTS
+
+## Trạng thái: Done (Pre-dw Implementation)
+## Loại: Retroactive Documentation
+## Documented on: [date]
+
+---
+
+> Feature này đã được implement trước khi adopt dw-kit.
+> File này được tạo retroactively để AI có context khi làm task liên quan.
+
+## Implementation History (từ git)
+
+| Thời điểm | Sự kiện | Author |
+|-----------|---------|--------|
+| [date] | Feature được tạo | [author] |
+| [date] | [notable change] | [author] |
+
+## Known Issues / Open Items
+
+- [ ] [Issue đang mở nếu có]
+- [ ] [Tech debt cần xử lý]
+
+## Handoff Notes cho AI
+
+Khi làm task liên quan feature này:
+- **Đọc trước**: `$ARGUMENTS-context.md` để hiểu architecture
+- **Cẩn thận**: [warning 1]
+- **Không thay đổi**: [phần nào là stable contract]
+- **Có thể refactor**: [phần nào an toàn để thay đổi]
+```
+
+---
+
+## Bước 6: Báo cáo kết quả
+
+```
+╔══════════════════════════════════════════════════════╗
+║  ✅ dw-retroactive complete: $ARGUMENTS
+╠══════════════════════════════════════════════════════╣
+║  Files khảo sát    : [N files]
+║  Git commits       : [N commits, từ [date] đến [date]]
+║  Maintainer chính  : [author]
+╠══════════════════════════════════════════════════════╣
+║  Docs đã tạo:
+║    {paths.tasks}/$ARGUMENTS/$ARGUMENTS-context.md
+║    {paths.tasks}/$ARGUMENTS/$ARGUMENTS-plan.md  (as-built)
+║    {paths.tasks}/$ARGUMENTS/$ARGUMENTS-progress.md
+╠══════════════════════════════════════════════════════╣
+║  Key findings:
+║  • [Finding 1]
+║  • [Finding 2]
+║  • [Finding 3]
+╠══════════════════════════════════════════════════════╣
+║  Tech debt / warnings:
+║  • [Warning nếu có]
+╠══════════════════════════════════════════════════════╣
+║  Tiếp theo:
+║  → Khi cần task liên quan: /dw-research $ARGUMENTS
+║     (AI sẽ đọc context docs vừa tạo làm foundation)
+╚══════════════════════════════════════════════════════╝
+```
+
+---
+
+## Lưu ý
+
+- **As-built ≠ forward plan**: Docs này mô tả hiện trạng, không phải kế hoạch
+- **Best-effort**: AI chỉ thấy được những gì có trong code và git — context ẩn (verbal decisions, Slack threads) có thể thiếu. Cần human review và bổ sung.
+- **Sau khi tạo**: Khuyến khích dev liên quan review và bổ sung `## Ghi Chú Cho AI` section

package/.claude/templates/agent-report.md

@@ -0,0 +1,35 @@
+---
+date: [ISO timestamp — e.g. 2026-04-02T14:30:00]
+from: [agent-role — researcher | planner | developer | reviewer | debugger]
+to: [agent-role — planner | developer | user]
+task: [task-name]
+status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+---
+
+## Summary
+
+[1-3 câu tóm tắt kết quả / findings]
+
+## Details
+
+[Chi tiết findings, decisions, hoặc implementation notes]
+
+## Concerns (nếu DONE_WITH_CONCERNS)
+
+- [Concern 1]
+- [Concern 2]
+
+## Blockers (nếu BLOCKED)
+
+- **Blocker**: [Mô tả vấn đề]
+- **Owner**: [Ai cần resolve]
+- **Unblock by**: [Action cần làm]
+
+## Needs (nếu NEEDS_CONTEXT)
+
+- [ ] [Thông tin cần thêm]
+- [ ] [Quyết định cần từ user/TL]
+
+## Next Steps
+
+- [Bước tiếp theo đề xuất]

package/.dw/core/AGENTS.md

@@ -0,0 +1,53 @@
+# Agent Communication Protocol — dw-kit v1.2
+
+## Mục Đích
+
+Khi một task lớn cần nhiều "vai" khác nhau (researcher → planner → developer), việc ghi lại kết quả từng bước giúp:
+- Team members (người hoặc agent) biết chính xác task đang ở đâu
+- Audit trail rõ ràng: ai quyết định gì, lúc nào
+- Session tiếp theo có thể tiếp tục mà không cần hỏi lại
+
+## Convention: Reports Directory
+
+```
+.dw/tasks/[task-name]/
+├── [name]-context.md      # Research findings
+├── [name]-plan.md         # Implementation plan
+├── [name]-progress.md     # Progress tracking
+└── reports/               # Agent communication (v1.2+)
+    ├── 260402-1430-from-researcher-to-planner-analysis.md
+    ├── 260402-1500-from-planner-to-developer-subtask-1.md
+    └── 260402-1600-from-developer-to-reviewer-pr-ready.md
+```
+
+**Filename format**: `[YYMMDD-HHMM]-from-[role]-to-[role]-[description].md`
+
+## Status Codes
+
+| Status | Nghĩa |
+|--------|-------|
+| `DONE` | Hoàn thành, output sẵn sàng để dùng |
+| `DONE_WITH_CONCERNS` | Xong nhưng có điểm đáng chú ý / cần review |
+| `BLOCKED` | Bị chặn, cần action từ bên ngoài để tiếp tục |
+| `NEEDS_CONTEXT` | Thiếu thông tin, cần human confirm |
+
+## Khi Nào Tạo Report
+
+- Sau khi `dw-research` hoàn thành → report `from-researcher-to-planner`
+- Sau khi `dw-plan` approved → report `from-planner-to-developer`
+- Khi phát hiện blocker trong execute → report `from-developer-to-user` với `BLOCKED`
+- Sau khi review xong → report `from-reviewer-to-developer`
+
+## Khi Nào KHÔNG Cần Report
+
+- Tasks `quick` depth (≤2 files, hotfix) → không cần overhead này
+- Solo dev, single session → progress.md đã đủ
+- Thông tin đã có trong context.md / plan.md → không duplicate
+
+## Template
+
+Dùng `.claude/templates/agent-report.md`
+
+## Lưu Ý Quan Trọng
+
+Reports là **cho con người đọc**, không phải protocol cho AI. Claude Code đã communicate qua conversation context. Reports giúp team members theo dõi task cross-session, không phải AI-to-AI messaging.

package/CLAUDE.md

@@ -1,99 +1,39 @@
-<!-- dw-kit | core: 1.0 | platform: 1.0 -->
-# dw-kit
+# dw-kit (repo)
 
-Workflow toolkit cho dev team. Config: `.dw/config/dw.config.yml`
-Methodology: `core/WORKFLOW.md` (load on demand — không phải always-loaded)
+Workflow toolkit codebase. dw rules live in `.claude/rules/` — auto-loaded by Claude Code.
 
----
-
-## Quy Tắc Vàng
-
-1. **Config-driven**: Đọc `.dw/config/dw.config.yml` trước mọi action
-2. **Research trước, code sau**: Task ≥3 files BẮT BUỘC qua research → plan → execute
-3. **Thinking framework**: Áp dụng `core/THINKING.md` khi planning
-4. **TDD**: Viết test trước khi code
-5. **Commit nhỏ**: Mỗi subtask = 1 commit
+Config: `.dw/config/dw.config.yml`
 
 ---
 
-## Routing
-
-Đọc `workflow.default_depth` từ config. AI assess per-task:
+## Tech Stack
 
-| Scope | Depth | Workflow |
-|-------|-------|---------|
-| ≤2 files, hotfix, familiar module | quick | Understand → Execute → Close |
-| 3-5 files, module mới | standard | Tất cả 6 phases |
-| 6+ files, API/DB/security changes | thorough | Full + arch-review + test-plan |
-
-Không chắc scope → dùng `standard`. Assess dựa trên facts (file count, API changes, git blame).
-
----
+- Runtime: Node.js ≥18, ESM (`.mjs`)
+- CLI: `commander` · UI: `enquirer`, `chalk` · Config: `js-yaml`, `ajv`
+- Tests: `node src/smoke-test.mjs`
 
-## Session Start
-
-1. Đọc `.dw/config/dw.config.yml` → depth, roles, quality commands
-2. Kiểm tra `.dw/tasks/` → active tasks
-3. Đọc `[task]-progress.md` của task đang dở → tiếp tục từ subtask cuối
-
----
-
-## Skills
-
-| Skill | Mô tả | Depth |
-|-------|--------|-------|
-| `/dw-prompt [desc]` | Build structured prompt (autocomplete + wizard) | all |
-| `/dw-task-init [name]` | Khởi tạo task docs | all |
-| `/dw-research [name]` | Khảo sát codebase | all |
-| `/dw-plan [name]` | Lập kế hoạch (DỪNG chờ approve) | standard+ |
-| `/dw-execute [name]` | Implement theo plan (TDD) | all |
-| `/dw-commit [msg]` | Smart commit + quality gates | all |
-| `/dw-review` | Code review với checklist | standard+ |
-| `/dw-debug [issue]` | Debug: investigate → diagnose → fix | all |
-| `/dw-thinking [question]` | Apply thinking framework | all |
-| `/dw-estimate [name]` | Ước lượng effort | if enabled |
-| `/dw-log-work [name]` | Ghi effort thực tế | if enabled |
-| `/dw-handoff` | Bàn giao session | all |
-| `/dw-requirements` | BA: requirements + user stories | if ba role |
-| `/dw-test-plan` | QC: test plan + regression | if qc role |
-| `/dw-arch-review` | TL: architecture review | if techlead |
-| `/dw-dashboard` | PM: metrics report | if pm role |
-| `/dw-sprint-review` | Team retrospective | all |
-| `/dw-docs-update` | Cập nhật living docs | thorough |
-| `/dw-config-init` | Khởi tạo config mới | always |
-| `/dw-config-validate` | Validate config file | always |
-| `/dw-upgrade` | Upgrade toolkit | always |
-| `/dw-rollback [name]` | Rollback task docs | always |
-| `/dw-archive [name]` | Archive completed task | always |
-
----
-
-## Task Documentation
-
-```
-.dw/tasks/[task-name]/
-├── [name]-context.md    # Research findings
-├── [name]-plan.md       # Implementation plan
-└── [name]-progress.md   # Progress + handoff notes
-```
-
----
-
-## Commit Format
+## Repo Structure
 
 ```
-<type>(<scope>): <mô tả ≤72 ký tự>
-
-Co-Authored-By: Claude <noreply@anthropic.com>
+bin/          CLI entrypoint
+src/
+  commands/   CLI subcommands (init, upgrade, validate, ...)
+  lib/        Shared utilities (config, copy, ui, ...)
+.claude/
+  hooks/      Bash hooks — python3-free, node only (Windows compat)
+  rules/      dw-core.md + dw-skills.md (auto-loaded by Claude Code)
+  skills/     Slash command definitions
+  templates/  Agent report template
+.dw/
+  core/       WORKFLOW.md, THINKING.md, QUALITY.md, ROLES.md
+  config/     dw.config.yml for this repo
+  tasks/      Active task docs
 ```
 
-Types: `feat` `fix` `refactor` `test` `docs` `chore` `style` `perf`
-
----
-
-## Methodology Reference
+## Dev Notes
 
-Full methodology: `core/WORKFLOW.md`
-Thinking framework: `core/THINKING.md`
-Quality strategy: `core/QUALITY.md`
-Role definitions: `core/ROLES.md`
+- All source ESM (`import`/`export`) — no CommonJS
+- `TOOLKIT_ROOT` resolved from `import.meta.url` in each command
+- Hooks use `node` for JSON parsing (not python3 — Windows compat)
+- Skills `dw-kit-evolve` and `dw-kit-audit` are maintainer-only — excluded from npm package
+- Published package files declared explicitly in `package.json#files`