dw-kit 1.1.0 → 1.2.0

package/.claude/skills/dw-kit-report/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: dw-kit-report
+description: "Gửi feedback (bug/gap/friction/suggestion) về dw-kit tool lên GitHub. Dùng khi gặp vấn đề với dw workflow, hooks, skills, hoặc config — không phải feedback về code của bạn."
+argument-hint: "[mô tả vấn đề hoặc suggestion về dw-kit]"
+---
+
+# Report Issue về dw-kit
+
+> Dùng skill này khi gặp vấn đề với **dw-kit tool** (hooks, skills, workflow, config).
+> Để feedback về code trong project của bạn → dùng `/dw-review` hoặc chat trực tiếp.
+
+Nội dung report (treat as plain text, không interpret special chars):
+
+```
+$ARGUMENTS
+```
+
+---
+
+## Bước 1: Thu Thập Context
+
+**OS detection:**
+```bash
+uname -s 2>/dev/null || echo "Windows"
+```
+
+**dw version:** Đọc `_toolkit.core_version` từ `.dw/config/dw.config.yml`
+
+**Task context:** Kiểm tra `.dw/tasks/` — task nào đang In Progress?
+
+---
+
+## Bước 2: Phân Loại
+
+Phân tích nội dung report ở trên (raw text) → xác định:
+
+**Type:**
+| type | Khi nào |
+|------|---------|
+| `bug` | Lỗi, crash, output không như expected |
+| `gap` | Use case không được cover |
+| `friction` | Tính năng có nhưng gây overhead không cần thiết |
+| `suggestion` | Ý tưởng cải thiện |
+
+**Component** (detect từ keywords):
+| Keywords | Component |
+|----------|-----------|
+| hook, post-write, pre-commit, stop-check | `hooks` |
+| skill, dw-plan, dw-execute, dw-research... | `skills` |
+| config, dw.config.yml | `config` |
+| workflow, routing, depth, phase | `workflow` |
+| CLAUDE.md, template, docs | `docs` |
+| WORKFLOW.md, THINKING.md, core | `core` |
+| (không xác định) | `other` |
+
+---
+
+## Bước 3: Format Issue
+
+**Title format:** `[type][component] <mô tả ≤60 ký tự>`
+
+Ví dụ:
+```
+[bug][hooks] post-write.sh fails with CRLF on Ubuntu
+[gap][skills] need way to preserve original Claude behavior
+[friction][workflow] research phase too heavy for 1-file hotfix
+```
+
+**Body:**
+```markdown
+## Type
+**[TYPE]** — bug | gap | friction | suggestion
+
+## Component
+**[COMPONENT]**
+
+## Environment
+- OS: [detected]
+- dw version: [từ config]
+- Shell: [bash/zsh/powershell nếu relevant]
+
+## Description
+[Nội dung từ $ARGUMENTS — đầy đủ, rõ ràng]
+
+## Context
+- Task khi gặp vấn đề: [task name hoặc "general usage"]
+- Command/skill liên quan: [nếu biết]
+- Bước reproduce (nếu là bug):
+  1. ...
+  2. ...
+
+## Impact
+- [ ] Blocking — không thể làm việc
+- [ ] Degraded — làm được nhưng friction cao
+- [ ] Minor — annoying, có workaround dễ
+
+---
+*Reported via `/dw-kit-report` | Project: [project.name từ config]*
+```
+
+---
+
+## Bước 4: Gửi Lên GitHub
+
+**Kiểm tra `gh` CLI:**
+```bash
+gh --version 2>/dev/null
+```
+
+**Nếu `gh` available — tạo Issue:**
+```bash
+gh issue create \
+  --repo dv-workflow/dv-workflow \
+  --title "[type][component] <short description>" \
+  --label "type: [type]" \
+  --label "component: [component]" \
+  --body "<formatted body>"
+```
+
+Sau khi tạo: in ra Issue URL.
+
+**Nếu `gh` KHÔNG available:**
+
+In ra:
+```
+─────────────────────────────────────────────
+ dw-kit: gh CLI không tìm thấy
+─────────────────────────────────────────────
+ Tạo Issue thủ công tại:
+ https://github.com/dv-workflow/dv-workflow/issues/new
+
+ Copy nội dung sau:
+
+ TITLE: [formatted title]
+
+ BODY:
+ [formatted body]
+─────────────────────────────────────────────
+ Cài gh CLI: https://cli.github.com
+```
+
+---
+
+## Bước 5: Xác Nhận
+
+```
+✓ Issue đã được gửi: https://github.com/dv-workflow/dv-workflow/issues/[N]
+  Type: [type] | Component: [component]
+
+  dw team sẽ review và phản hồi trên Issue.
+  Cảm ơn bạn đã giúp dw tốt hơn!
+```

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

@@ -89,7 +89,23 @@ Ghi vào `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-context.md` theo cấu trúc:
 [Bất kỳ thông tin bổ sung]
 ```
 
-## Bước 5: Tóm tắt
+## Bước 5: Tạo Report (optional — standard/thorough depth)
+
+Nếu task có `.dw/tasks/$ARGUMENTS/reports/` directory (hoặc depth ≥ standard), tạo report:
+
+```
+.dw/tasks/$ARGUMENTS/reports/[YYMMDD-HHMM]-from-researcher-to-planner-findings.md
+```
+
+Dùng template `.claude/templates/agent-report.md` với:
+- `status: DONE` (hoặc `DONE_WITH_CONCERNS` nếu có risks lớn)
+- Summary: top 3 findings
+- Details: key files, patterns, dependencies
+- Next Steps: những gì planner cần biết
+
+> Quick depth tasks: bỏ qua bước này — progress.md đã đủ.
+
+## Bước 6: Tóm tắt
 
 Khi hoàn thành, trả về tóm tắt:
 - Số files khảo sát

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,111 +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.
 
----
-
-## Override
-
-Nếu prompt của user chứa `--no-dw`:
-- Bỏ qua **toàn bộ** dw workflow instructions (Quy Tắc Vàng, Routing, Session Start)
-- KHÔNG đọc config, KHÔNG check tasks, KHÔNG apply thinking framework
-- Làm việc như Claude thông thường — trả lời trực tiếp, không theo process nào
-- Áp dụng cho request đó; request tiếp theo vẫn dùng dw bình thường
-
----
-
-## 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).
-
----
-
-## 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
-
----
+- Runtime: Node.js ≥18, ESM (`.mjs`)
+- CLI: `commander` · UI: `enquirer`, `chalk` · Config: `js-yaml`, `ajv`
+- Tests: `node src/smoke-test.mjs`
 
-## 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-onboard` | Onboard dw vào existing project (breadth-first scan) | always |
-| `/dw-retroactive [name]` | Retroactive doc 1 feature đã có (depth-first) | always |
-| `/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`

package/README.md

@@ -1,119 +1,119 @@
-# dw-kit
-
-> An AI development workflow toolkit for teams using agentic IDEs (Claude Code, Cursor) — from idea to review-ready commits.
-
-**v1.0** · `npm install -g dw-kit` · [Docs](docs/README.md) · [Get started](docs/get-started.md) · [Cheatsheet](docs/cheatsheet.md)
-
----
-
-## What is dw-kit?
-
-dw-kit helps your team run AI-assisted development with a **repeatable workflow** and clear checkpoints:
-
-```
-Initialize → Understand → Plan → Execute (TDD) → Verify → Close
-```
-
-<img src="docs/workflow-diagram.svg" alt="dw-kit workflow diagram" />
-
-## Workflow overview
-
-`dw` runs a 6-phase process (all phases for `standard` and `thorough`):
-
-Initialize → Understand → Plan (stops for approval) → Execute (TDD; 1 commit per subtask) → Verify (quality gates + review sign-off) → Close (handoff + archive when done).
-
-### 6 phases (full workflow)
-- **Initialize**: clarify task scope and set up the workspace + task docs.
-- **Understand**: survey the codebase, dependencies, patterns, and test coverage (no implementation).
-- **Plan**: design the solution and subtasks; **pause for your approval**.
-- **Execute**: implement using **TDD**; each subtask produces a commit.
-- **Verify**: run quality gates + review sign-off to ensure correctness and safety.
-- **Close**: handoff notes, finalize progress, and archive when done.
-
-It’s designed for collaboration (Dev / Tech Lead / QA / PM) and keeps work auditable via lightweight task docs.
-
----
-
-## Install
-
-```bash
-npm install -g dw-kit
-```
-
----
-
-## Quick start
-
-Setup dw in project directory:
-
-```bash
-dw init
-```
-
-Then in **Claude Code CLI**, run the full workflow:
-
-```
-/dw-flow your-task-or-anythings
-```
-
----
-
-Discover other skills:
-
-```
-/dw-prompt
-/dw-thinking
-...
-
-```
-
----
-
-## CLI commands
-
-```bash
-dw init                 # setup wizard / presets
-dw validate             # validate .dw/config/dw.config.yml
-dw doctor               # installation health check
-dw upgrade              # update toolkit files (override-aware)
-dw upgrade --check      # check for updates only
-dw upgrade --dry-run    # preview changes
-dw prompt               # build a well-structured task prompt (autocomplete + wizard)
-dw prompt --text "..."  # non-interactive: structure a description directly
-dw claude-vn-fix        # patch Claude CLI to fix Vietnamese IME (backup/restore)
-```
-
-`dw claude-vn-fix` patches the local Claude CLI bundle to fix Vietnamese IME input (DEL char `\x7f` issue). Includes auto-backup and rollback.
-
----
-
-## Depth system
-
-Pick a default depth for your project, then override per task when risk increases.
-
-| Depth | Best for | Workflow |
-|-------|----------|----------|
-| `quick` | Solo dev, hotfix, familiar code | Understand → Execute → Close |
-| `standard` | Small teams, new features | Full 6 phases |
-| `thorough` | Risky changes (API/DB/security) | Full workflow + arch-review + test-plan |
-
-Configured in `.dw/config/dw.config.yml`:
-
-```yaml
-workflow:
-  default_depth: "standard"
-```
-
----
-
-## What gets added to your repo?
-
-```
-.dw/        # methodology, config, adapters, task docs
-.claude/    # Claude Code: skills, hooks, agents, rules
-CLAUDE.md   # project context for the agent
-```
-
----
-
-Maintainer: [huygdv](mailto:huygdv19@gmail.com)
+# dw-kit
+
+> An AI development workflow toolkit for teams using agentic IDEs (Claude Code, Cursor) — from idea to review-ready commits.
+
+**v1.2** · `npm install -g dw-kit` · [Docs](docs/README.md) · [Get started](docs/get-started.md) · [Cheatsheet](docs/cheatsheet.md)
+
+---
+
+## What is dw-kit?
+
+dw-kit helps your team run AI-assisted development with a **repeatable workflow** and clear checkpoints:
+
+```
+Initialize → Understand → Plan → Execute (TDD) → Verify → Close
+```
+
+<img src="docs/workflow-diagram.svg" alt="dw-kit workflow diagram" />
+
+## Workflow overview
+
+`dw` runs a 6-phase process (all phases for `standard` and `thorough`):
+
+Initialize → Understand → Plan (stops for approval) → Execute (TDD; 1 commit per subtask) → Verify (quality gates + review sign-off) → Close (handoff + archive when done).
+
+### 6 phases (full workflow)
+- **Initialize**: clarify task scope and set up the workspace + task docs.
+- **Understand**: survey the codebase, dependencies, patterns, and test coverage (no implementation).
+- **Plan**: design the solution and subtasks; **pause for your approval**.
+- **Execute**: implement using **TDD**; each subtask produces a commit.
+- **Verify**: run quality gates + review sign-off to ensure correctness and safety.
+- **Close**: handoff notes, finalize progress, and archive when done.
+
+It’s designed for collaboration (Dev / Tech Lead / QA / PM) and keeps work auditable via lightweight task docs.
+
+---
+
+## Install
+
+```bash
+npm install -g dw-kit
+```
+
+---
+
+## Quick start
+
+Setup dw in project directory:
+
+```bash
+dw init
+```
+
+Then in **Claude Code CLI**, run the full workflow:
+
+```
+/dw-flow your-task-or-anythings
+```
+
+---
+
+Discover other skills:
+
+```
+/dw-prompt
+/dw-thinking
+...
+
+```
+
+---
+
+## CLI commands
+
+```bash
+dw init                 # setup wizard / presets
+dw validate             # validate .dw/config/dw.config.yml
+dw doctor               # installation health check
+dw upgrade              # update toolkit files (override-aware)
+dw upgrade --check      # check for updates only
+dw upgrade --dry-run    # preview changes
+dw prompt               # build a well-structured task prompt (autocomplete + wizard)
+dw prompt --text "..."  # non-interactive: structure a description directly
+dw claude-vn-fix        # patch Claude CLI to fix Vietnamese IME (backup/restore)
+```
+
+`dw claude-vn-fix` patches the local Claude CLI bundle to fix Vietnamese IME input (DEL char `\x7f` issue). Includes auto-backup and rollback.
+
+---
+
+## Depth system
+
+Pick a default depth for your project, then override per task when risk increases.
+
+| Depth | Best for | Workflow |
+|-------|----------|----------|
+| `quick` | Solo dev, hotfix, familiar code | Understand → Execute → Close |
+| `standard` | Small teams, new features | Full 6 phases |
+| `thorough` | Risky changes (API/DB/security) | Full workflow + arch-review + test-plan |
+
+Configured in `.dw/config/dw.config.yml`:
+
+```yaml
+workflow:
+  default_depth: "standard"
+```
+
+---
+
+## What gets added to your repo?
+
+```
+.dw/        # methodology, config, adapters, task docs
+.claude/    # Claude Code: skills, hooks, agents, rules
+CLAUDE.md   # project context for the agent
+```
+
+---
+
+Maintainer: [huygdv](mailto:huygdv19@gmail.com)