dw-kit 1.0.2 → 1.1.0

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/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-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.md

@@ -6,6 +6,16 @@ Methodology: `core/WORKFLOW.md` (load on demand — không phải always-loaded)
 
 ---
 
+## 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
@@ -60,6 +70,8 @@ Không chắc scope → dùng `standard`. Assess dựa trên facts (file count,
 | `/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 |

package/README.md

@@ -14,27 +14,7 @@ dw-kit helps your team run AI-assisted development with a **repeatable workflow*
 Initialize → Understand → Plan → Execute (TDD) → Verify → Close
 ```
 
-```mermaid
-%%{init: {'flowchart': {'nodeSpacing': 10, 'rankSpacing': 18}}}%%
-flowchart LR
-  classDef extra fill:#f3f4f6,stroke:#9ca3af,stroke-width:1px,color:#111;
-
-  D["Init + Understand"] --> P["Plan (approve)"]
-  P -->|approved| E["Execute (TDD)"]
-  P -->|revise| P
-
-  E --> V["Verify (gates)"]
-  V -->|sign-off| C["Close (handoff + archive)"]
-  V -->|"revise (fix)"| E
-
-  subgraph Extra["Depth=thorough"]
-    R[Req] --> Est[Est] --> AR[Arch] --> P
-    P -.-> TP[Test] -.-> E
-    E -.-> DU[Docs] --> LW[Log] -.-> C
-  end
-
-  class R,Est,AR,TP,DU,LW extra
-```
+<img src="docs/workflow-diagram.svg" alt="dw-kit workflow diagram" />
 
 ## Workflow overview
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-kit",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "AI development workflow toolkit — structured, quality-assured, team-ready. From requirements to dashboard.",
   "type": "module",
   "bin": {
@@ -13,7 +13,12 @@
     ".dw/config/",
     ".dw/adapters/",
     "scripts/",
-    ".claude/",
+    ".claude/agents/",
+    ".claude/hooks/",
+    ".claude/rules/",
+    ".claude/skills/",
+    ".claude/templates/",
+    ".claude/settings.json",
     "CLAUDE.md"
   ],
   "engines": {

package/src/commands/init.mjs

@@ -276,7 +276,7 @@ function createRuntimeDirs(projectDir) {
 
 function updateGitignore(projectDir) {
   const gitignorePath = join(projectDir, '.gitignore');
-  const entriesToAdd = ['.dw/metrics/', '.dw/reports/', 'CLAUDE.local.md'];
+  const entriesToAdd = ['CLAUDE.local.md', '.claude/settings.local.json'];
 
   if (existsSync(gitignorePath)) {
     const content = readFileSync(gitignorePath, 'utf-8');

package/src/commands/prompt.mjs

@@ -1,14 +1,12 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { load as yamlLoad } from 'js-yaml';
 import { header, info, ok, warn, err, log } from '../lib/ui.mjs';
 import { copyToClipboard } from '../lib/clipboard.mjs';
 import { getSuggestions, isVague, expandTemplate } from '../lib/prompt-suggest.mjs';
+import { detectPlatform } from '../lib/platform.mjs';
 
 export async function promptCommand(opts) {
   header('dw-kit Prompt Builder');
 
-  const adapter = readAdapter();
+  const adapter = detectPlatform(process.cwd());
 
   // Non-interactive mode: --text <text>
   if (opts.text !== undefined) {
@@ -112,14 +110,3 @@ function outputResult(text, adapter) {
     info('(generic adapter — copy the text above manually)');
   }
 }
-
-function readAdapter() {
-  const configPath = join(process.cwd(), '.dw', 'config', 'dw.config.yml');
-  if (!existsSync(configPath)) return 'claude-cli';
-  try {
-    const config = yamlLoad(readFileSync(configPath, 'utf-8'));
-    return config?.adapter || 'claude-cli';
-  } catch {
-    return 'claude-cli';
-  }
-}

package/.claude/settings.local.json

@@ -1,13 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "WebFetch(domain:alexop.dev)",
-      "WebFetch(domain:github.com)",
-      "WebFetch(domain:docs.anthropic.com)",
-      "Bash(grep -rL \"^name:\" .claude/skills/dw-*/SKILL.md)",
-      "Bash(grep -c '\\\\$ARGUMENTS\\\\|context: fork\\\\|allowed-tools' .dw/adapters/generic/AGENT.md)",
-      "Bash(grep [v1.0.0] CHANGELOG.md)",
-      "Bash(node src/smoke-test.mjs)"
-    ]
-  }
-}