dw-kit 1.1.0 → 1.2.1

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/config/dw.config.yml

@@ -1,82 +1,82 @@
-# ============================================================================
-# dw-kit Configuration — v1
-# ============================================================================
-# Copy file này vào project và tùy chỉnh theo nhu cầu.
-# Toolkit đọc file này để điều chỉnh behavior per project.
-# ============================================================================
-
-# --- Project Info -----------------------------------------------------------
-project:
-  name: "my-project"
-  language: "vi"               # vi | en
-
-# --- Workflow ----------------------------------------------------------------
-workflow:
-  default_depth: "standard"   # quick | standard | thorough
-  # AI assesses per-task và có thể recommend depth khác nhau:
-  #   quick    : ≤2 files, hotfix, familiar module
-  #   standard : 3-5 files, module mới, unfamiliar code
-  #   thorough : 6+ files, API contract changes, DB schema, security
-
-# --- Team -------------------------------------------------------------------
-team:
-  roles:
-    - dev              # luôn có
-    - techlead         # architecture review, plan approval
-    # - ba             # requirements, user stories
-    # - qc             # test plans, QA sign-off
-    # - pm             # dashboard, reports
-
-# --- Quality Gates ----------------------------------------------------------
-quality:
-  test_command: ""     # ví dụ: "npm test" | "pytest" | "go test ./..."
-  lint_command: ""     # ví dụ: "npm run lint" | "ruff check ." | "golangci-lint run"
-  block_on_fail: false # true = block commit nếu test/lint fail
-
-# --- Tracking ---------------------------------------------------------------
-tracking:
-  estimation: false
-  log_work: false
-  estimation_unit: "hours"    # hours | story-points | t-shirt
-
-# --- Paths ------------------------------------------------------------------
-paths:
-  tasks: ".dw/tasks"
-  docs: ".dw/docs"
-
-# --- Claude Capabilities (Layer 2) ------------------------------------------
-# Tính năng đặc thù của Claude Code.
-claude:
-  # Model per phase — để trống = dùng model mặc định từ Claude Code settings
-  models:
-    plan: ""           # ví dụ: "claude-opus-4-6" cho complex planning
-    execute: ""        # ví dụ: "claude-sonnet-4-6"
-    review: ""
-
-  # Structured JSON output từ reviewer và estimate skills
-  structured_output: true
-
-  # Isolate execution trong git worktree (cho risky refactors)
-  worktree_execution: false
-
-  # MCP servers — Claude Code sẽ load các servers này
-  mcp: []
-  # Ví dụ:
-  # mcp:
-  #   - name: "github"
-  #     command: "npx @modelcontextprotocol/server-github"
-  #     env:
-  #       GITHUB_TOKEN: "${GITHUB_TOKEN}"
-  #   - name: "jira"
-  #     command: "npx @anthropic/mcp-server-jira"
-  #     env:
-  #       JIRA_URL: "${JIRA_URL}"
-  #       JIRA_TOKEN: "${JIRA_TOKEN}"
-
-# --- Toolkit Version (do not edit manually) ---------------------------------
-_toolkit:
-  core_version: "1.0"
-  platform_version: "1.0"
-  capability_version: "1.0"
-  installed: "2026-03-23"
-  last_upgrade: "2026-03-23"
+# ============================================================================
+# dw-kit Configuration — v1
+# ============================================================================
+# Copy file này vào project và tùy chỉnh theo nhu cầu.
+# Toolkit đọc file này để điều chỉnh behavior per project.
+# ============================================================================
+
+# --- Project Info -----------------------------------------------------------
+project:
+  name: "my-project"
+  language: "vi"               # vi | en
+
+# --- Workflow ----------------------------------------------------------------
+workflow:
+  default_depth: "standard"   # quick | standard | thorough
+  # AI assesses per-task và có thể recommend depth khác nhau:
+  #   quick    : ≤2 files, hotfix, familiar module
+  #   standard : 3-5 files, module mới, unfamiliar code
+  #   thorough : 6+ files, API contract changes, DB schema, security
+
+# --- Team -------------------------------------------------------------------
+team:
+  roles:
+    - dev              # luôn có
+    - techlead         # architecture review, plan approval
+    # - ba             # requirements, user stories
+    # - qc             # test plans, QA sign-off
+    # - pm             # dashboard, reports
+
+# --- Quality Gates ----------------------------------------------------------
+quality:
+  test_command: ""     # ví dụ: "npm test" | "pytest" | "go test ./..."
+  lint_command: ""     # ví dụ: "npm run lint" | "ruff check ." | "golangci-lint run"
+  block_on_fail: false # true = block commit nếu test/lint fail
+
+# --- Tracking ---------------------------------------------------------------
+tracking:
+  estimation: false
+  log_work: false
+  estimation_unit: "hours"    # hours | story-points | t-shirt
+
+# --- Paths ------------------------------------------------------------------
+paths:
+  tasks: ".dw/tasks"
+  docs: ".dw/docs"
+
+# --- Claude Capabilities (Layer 2) ------------------------------------------
+# Tính năng đặc thù của Claude Code.
+claude:
+  # Model per phase — để trống = dùng model mặc định từ Claude Code settings
+  models:
+    plan: ""           # ví dụ: "claude-opus-4-6" cho complex planning
+    execute: ""        # ví dụ: "claude-sonnet-4-6"
+    review: ""
+
+  # Structured JSON output từ reviewer và estimate skills
+  structured_output: true
+
+  # Isolate execution trong git worktree (cho risky refactors)
+  worktree_execution: false
+
+  # MCP servers — Claude Code sẽ load các servers này
+  mcp: []
+  # Ví dụ:
+  # mcp:
+  #   - name: "github"
+  #     command: "npx @modelcontextprotocol/server-github"
+  #     env:
+  #       GITHUB_TOKEN: "${GITHUB_TOKEN}"
+  #   - name: "jira"
+  #     command: "npx @anthropic/mcp-server-jira"
+  #     env:
+  #       JIRA_URL: "${JIRA_URL}"
+  #       JIRA_TOKEN: "${JIRA_TOKEN}"
+
+# --- Toolkit Version (do not edit manually) ---------------------------------
+_toolkit:
+  core_version: "1.2"
+  platform_version: "1.2"
+  capability_version: "1.0"
+  installed: "2026-03-23"
+  last_upgrade: "2026-04-15"

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`