dw-kit 1.3.0 → 1.3.4

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

@@ -1,6 +1,6 @@
 ---
 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ũ."
+description: "Retroactively document một feature/task đã được implement trước khi dùng dw. Reverse-engineer từ code + git history, tạo spec.md + tracking.md (v2 format, As-Built flavor)."
 argument-hint: "[feature-name]"
 allowed-tools:
   - Read
@@ -19,7 +19,7 @@ allowed-tools:
 
 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.
+> Reverse-engineer feature đã tồn tại từ code + git history. Tạo task docs v2 format (`spec.md` + `tracking.md`) với flavor As-Built — để AI và team có context đầy đủ khi làm task liên quan.
 
 ---
 
@@ -27,12 +27,12 @@ Feature: **$ARGUMENTS**
 
 Đọc `.dw/config/dw.config.yml`:
 - `paths.tasks` → output location (mặc định `.dw/tasks`)
-- `project.language` → ngôn ngữ docs
+- `project.language` → ngôn ngữ docs (vi/en)
 
 ## 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 có `spec.md` hoặc `tracking.md` → hỏi user: "Đã có task docs cho `$ARGUMENTS`. Overwrite hay skip?"
 - Nếu chưa → tiếp tục
 
 ---
@@ -47,229 +47,113 @@ 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?"
+Nếu không tìm được → hỏi user cung cấp thêm keyword hoặc path.
 
 ## 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
+2. Xác định: vai trò trong feature, logic chính, I/O, side effects, error handling
+3. **Trace data flow**: input → xử lý → output
+4. **Dependencies**: upstream (gọi ai) / downstream (ai gọi)
+5. **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 log --oneline --diff-filter=A -- [files-found]
 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)
+Xác định: thời điểm tạo, maintainer chính, breaking changes, tech debt (TODO/FIXME).
 
 ## 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)
+Từ framework `.dw/core/THINKING.md`:
+- **Giả định** trong code về input/state/environment
+- **Failure modes** + edge cases
+- **Tech debt** (TODO/FIXME/antipatterns)
+- **Security** (auth, validation, data exposure)
 
 ---
 
-## 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
+## Bước 5: Tạo task docs (v2 format, As-Built flavor)
 
-- [ ] Có tests: [Có/Không]
-- Test files: [danh sách]
-- Coverage: [mô tả]
-- Gaps: [thiếu test ở đâu]
+Tạo thư mục `{paths.tasks}/$ARGUMENTS/` và **2 files** theo template v2 tại `.dw/core/templates/v2/`.
 
-## Giả Định & Hạn Chế
+### 5a. spec.md (As-Built)
 
-| # | Giả định/Hạn chế | Mức độ rủi ro |
-|---|-----------------|--------------|
-| 1 | [giả định trong code] | Cao/TB/Thấp |
+Đọc template `.dw/core/templates/v2/spec.md`, điền:
 
-## Tech Debt & Warnings
+**Frontmatter:**
+- `task_id: $ARGUMENTS`
+- `created: [today]`
+- `status: Done` ← đã implement
+- `owner: [main author từ git shortlog]`
+- `depth: retroactive`
+- `related_adr: none`
+- `target_ship: [first-commit-date]`
 
-- [ ] [TODO/FIXME đang có]
-- [ ] [Antipatterns phát hiện]
-- [ ] [Security concerns]
+**Body sections** (lấp bằng findings retroactive):
 
-## 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`:
+- **Intent**: 1-2 paragraphs mô tả feature làm gì (dựa trên code)
+- **Why Now**: "As-built documentation — feature pre-dw adoption" + lý do document hóa
+- **Scope → In Scope**: liệt kê component đã implement dưới dạng ST-1, ST-2... với:
+  - Concrete action = mô tả component đã implement
+  - Acceptance = how it was verified (tests / manual check)
+  - Effort = `as-built`
+- **Scope → Out of Scope**: những gì rõ ràng KHÔNG nằm trong feature (suy từ code boundaries)
+- **Risks & Mitigations**: tech debt, antipatterns, security concerns phát hiện
+- **Success Criteria**: current behavior được kiểm chứng bằng gì (tests, prod metrics nếu biết)
+- **Dependencies**: upstream modules/services + downstream consumers
+- **Known Unknowns**: câu hỏi cần human review (verbal decisions không có trong code)
+- **Acceptance**: đánh dấu `[x]` các items đã done (feature đang chạy prod)
 
+**Thêm note trên đầu Intent**:
 ```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]
+> ⚠ As-Built Documentation — Generated retroactively from code + git history.
+> Verbal context (Slack threads, meetings) có thể thiếu. Cần human review bổ sung.
 ```
 
-### 5c. Progress doc
+Ghi vào `{paths.tasks}/$ARGUMENTS/spec.md`.
 
-Tạo `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-progress.md`:
+### 5b. tracking.md (As-Built)
 
-```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.
+Đọc template `.dw/core/templates/v2/tracking.md`, điền:
 
-## Implementation History (từ git)
+**Frontmatter:**
+- `task_id: $ARGUMENTS`
+- `started: [first-commit-date từ git]`
+- `last_updated: [today]`
+- `status: Done`
+- `current_phase: Maintained`
+- `blockers: none`
 
-| Thời điểm | Sự kiện | Author |
-|-----------|---------|--------|
-| [date] | Feature được tạo | [author] |
-| [date] | [notable change] | [author] |
+**Body sections:**
 
-## Known Issues / Open Items
+- **Status Snapshot**: Phase `Done (pre-dw)` · Next milestone `— (maintained as-is)`
+- **Subtask Progress** table: map các component đã tìm ở Bước 2 thành ST-N với status ✅ Done, Date = commit date đầu tiên của component, Notes = commit SHA hoặc file path
+- **Changelog**: parse git log ra thành entries theo ngày. Format:
+  ```
+  ### YYYY-MM-DD — [commit subject]
+  **Actions taken:** [summary]
+  ```
+- **Handoff Notes**: cho next session/agent:
+  - **Read first:** `spec.md` (as-built) + key files từ bước 2
+  - **Current state:** Done, maintained
+  - **Don't do:** [stable contracts không nên thay đổi]
+  - **Watch out:** [tech debt + gotchas]
+- **Friction Journal**: để trống hoặc nhập tech debt đã ghi nhận từ Bước 4
+- **Agent Debate Log**: bỏ qua (không applicable cho retroactive)
 
-- [ ] [Issue đang mở nếu có]
-- [ ] [Tech debt cần xử lý]
+Ghi vào `{paths.tasks}/$ARGUMENTS/tracking.md`.
 
-## Handoff Notes cho AI
+### 5c. Cập nhật ACTIVE.md
 
-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]
-```
+Chạy `dw active` (hoặc `writeActiveIndex`) để regenerate team index.
 
 ---
 
@@ -277,28 +161,27 @@ Khi làm task liên quan feature này:
 
 ```
 ╔══════════════════════════════════════════════════════╗
-║  ✅ dw-retroactive complete: $ARGUMENTS
+║  ✅ dw:retroactive complete: $ARGUMENTS
 ╠══════════════════════════════════════════════════════╣
 ║  Files khảo sát    : [N files]
-║  Git commits       : [N commits, từ [date] đến [date]]
+║  Git commits       : [N, 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
+║  Docs đã tạo (v2 format):
+║    {paths.tasks}/$ARGUMENTS/spec.md      (As-Built)
+║    {paths.tasks}/$ARGUMENTS/tracking.md  (Done, maintained)
 ╠══════════════════════════════════════════════════════╣
 ║  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)
+║  → Task liên quan:    /dw:research $ARGUMENTS
+║    (AI đọc spec.md làm foundation)
+║  → Human review:      điền Known Unknowns + Handoff Notes
 ╚══════════════════════════════════════════════════════╝
 ```
 
@@ -306,6 +189,7 @@ Khi làm task liên quan feature này:
 
 ## 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
+- **As-built ≠ forward plan**: spec.md mô tả hiện trạng, không phải kế hoạch tương lai.
+- **Best-effort**: AI chỉ thấy code + git — context ẩn (verbal decisions, Slack threads) có thể thiếu. Human review là bắt buộc cho phần `Known Unknowns`.
+- **v2 format**: Chỉ tạo 2 files (`spec.md` + `tracking.md`). Không dùng lại v1 3-file format (`context + plan + progress`) nữa.
+- **Tools khác vẫn đọc được**: `dw active`, `session-init` hook, `/dw:dashboard` đều hỗ trợ v2 format song song với legacy v1.

package/.claude/skills/dw-task-init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dw:task-init
-description: "Khởi tạo bộ documentation cho task mới. Tạo thư mục và 3 template files (context, plan, progress)."
+description: "Khởi tạo bộ documentation cho task mới. Tạo thư mục và 2 files v2 (spec.md + tracking.md)."
 argument-hint: "[task-name]"
 ---
 
@@ -8,52 +8,64 @@ argument-hint: "[task-name]"
 
 ## Đọc Config
 
-Đọc `.dw/config/dw.config.yml` để lấy:
+Đọc `.dw/config/dw.config.yml`:
 - `paths.tasks` → thư mục chứa task docs (mặc định: `.dw/tasks`)
 - `workflow.default_depth` → `quick | standard | thorough`
-- `tracking.estimation` → có tạo section estimation không
-- `tracking.log_work` → có tạo section effort log không
-- `team.roles` → hiển thị workflow phù hợp
-- `project.language` → chọn template ngôn ngữ
+- `project.language` → ngôn ngữ note thêm (templates hiện tại là vi/en-agnostic)
 
-## Tạo Thư Mục & Files
+## Tạo Thư Mục & Files (v2 format)
 
 ```
 {paths.tasks}/$ARGUMENTS/
-├── $ARGUMENTS-context.md    # Research findings & codebase analysis
-├── $ARGUMENTS-plan.md       # Implementation plan & design
-└── $ARGUMENTS-progress.md   # Progress tracking, effort log, changelog
+├── spec.md      # Intent + subtasks + success criteria (stable after approve)
+└── tracking.md  # Progress + changelog + handoff (mutable)
 ```
 
-### File context.md
-Đọc `project.language` từ config để chọn template:
-- `language: "vi"` → dùng `.claude/templates/task-context.md`
-- `language: "en"` → dùng `.claude/templates/en/task-context.md`
+### 1. Tạo spec.md
 
-Điền vào template:
-- `[Task Name]` = `$ARGUMENTS`
-- `[date]` = ngày hiện tại
+Đọc template từ `.dw/core/templates/v2/spec.md`, điền vào:
+- `{task-name}` → `$ARGUMENTS`
+- `{YYYY-MM-DD}` (created) → ngày hiện tại
+- `status` → `Draft`
+- `depth` → giá trị `workflow.default_depth` từ config
+- `owner` → để trống (user tự điền)
+- `related_adr` → `none`
+- `target_ship` → `none`
 
-### File plan.md
-Chọn template theo `project.language` (`.claude/templates/[lang]/task-plan.md`).
-- Nếu `tracking.estimation = true`: giữ nguyên section Estimation
-- Nếu `tracking.estimation = false`: xóa section Estimation
+Ghi vào `{paths.tasks}/$ARGUMENTS/spec.md`.
 
-### File progress.md
-Chọn template theo `project.language` (`.claude/templates/[lang]/task-progress.md`).
-- Điền `[Task Name]` = `$ARGUMENTS`
-- Điền `[date]` = ngày hiện tại
-- Nếu `tracking.log_work = true`: giữ section Effort Log
-- Nếu `tracking.log_work = false`: xóa section Effort Log
+### 2. Tạo tracking.md
+
+Đọc template từ `.dw/core/templates/v2/tracking.md`, điền vào:
+- `{task-name}` → `$ARGUMENTS`
+- `{YYYY-MM-DD}` (started & last_updated) → ngày hiện tại
+- `status` → `Not Started`
+- `current_phase` → `Init`
+- `blockers` → `none`
+
+Ghi vào `{paths.tasks}/$ARGUMENTS/tracking.md`.
+
+### 3. Cập nhật ACTIVE.md
+
+Sau khi tạo xong 2 files, chạy `dw active` (hoặc invoke `writeActiveIndex`) để regenerate `{paths.tasks}/ACTIVE.md` — team index sẽ thấy task mới.
 
 ## Sau Khi Tạo
 
 Hiển thị cho user:
-1. Danh sách files đã tạo
-2. Workflow tiếp theo dựa trên `workflow.default_depth`:
 
-**quick**: "Tiếp theo: Code ngay hoặc `/dw:research $ARGUMENTS` nếu cần khảo sát"
-**standard**: "Tiếp theo: `/dw:research $ARGUMENTS` → `/dw:plan $ARGUMENTS` → approve → `/dw:execute $ARGUMENTS`"
-**thorough**: "Tiếp theo: `/dw:requirements $ARGUMENTS` → `/dw:research $ARGUMENTS` → `/dw:estimate $ARGUMENTS` → `/dw:plan $ARGUMENTS`"
+1. Danh sách files đã tạo:
+   - `{paths.tasks}/$ARGUMENTS/spec.md`
+   - `{paths.tasks}/$ARGUMENTS/tracking.md`
+
+2. Workflow tiếp theo theo `workflow.default_depth`:
+   - **quick**: "Code ngay hoặc `/dw:research $ARGUMENTS` nếu cần khảo sát."
+   - **standard**: "`/dw:research $ARGUMENTS` → `/dw:plan $ARGUMENTS` → approve → `/dw:execute $ARGUMENTS`"
+   - **thorough**: "`/dw:requirements $ARGUMENTS` → `/dw:research $ARGUMENTS` → `/dw:estimate $ARGUMENTS` → `/dw:plan $ARGUMENTS`"
+
+3. Nếu team có BA role: "BA có thể chạy `/dw:requirements $ARGUMENTS` trước để chuẩn bị yêu cầu."
+
+## Lưu ý v2 format
 
-Nếu team có BA: "Gợi ý: BA có thể chạy `/dw:requirements $ARGUMENTS` trước để chuẩn bị yêu cầu"
+- `spec.md` ổn định sau khi approve — subtasks + success criteria không thay đổi mà không có lý do.
+- `tracking.md` mutable — cập nhật mỗi session (Subtask Progress table, Changelog, Friction Journal).
+- Legacy 3-file format (`context + plan + progress`) vẫn được đọc bởi các skill khác để backward compat, nhưng **không tạo mới** cho task mới.