dw-kit 1.3.0 → 1.3.4

package/.claude/rules/dw.md

@@ -65,6 +65,8 @@ All dw skills invoke via `/dw:{name}` (colon namespace separator).
 
 Core workflow: `/dw:flow` · `/dw:task-init` · `/dw:research` · `/dw:plan` · `/dw:execute` · `/dw:commit` · `/dw:handoff`
 
+`/dw:plan` includes **Quick Debate** (red/blue self-critique): default ON for `thorough`, auto-trigger on high-stakes signals for `standard`, off for `quick`. Override via `--debate` / `--no-debate` / `--debate-deep`.
+
 Decisions: `/dw:decision [title]` — create ADR
 
 Dev: `/dw:debug` · `/dw:review` · `/dw:thinking` · `/dw:prompt` · `/dw:docs-update`

package/.claude/settings.json

@@ -29,7 +29,15 @@
       "Bash(bash -n /dev/stdin)",
       "Bash(dos2unix .claude/hooks/pre-commit-gate.sh)",
       "Bash(sed -i 's/\\\\r$//' .claude/hooks/pre-commit-gate.sh)",
-      "Bash(git add *)"
+      "Bash(git add *)",
+      "Edit(/.claude/skills/dw-task-init/**)",
+      "Edit(/.claude/skills/dw-retroactive/**)",
+      "Edit(/.claude/skills/dw-research/**)",
+      "Edit(/.claude/skills/dw-plan/**)",
+      "Edit(/.claude/skills/dw-execute/**)",
+      "Edit(/.claude/skills/dw-handoff/**)",
+      "Bash(git commit -m 'fix\\(v1.3.3\\): writer skills v1/v2 compat + cleanup legacy slash-command refs *)",
+      "Bash(git commit -m 'feat\\(v1.3.4\\): /dw:plan integrated Quick Debate \\(red/blue team\\) - depth-driven *)"
     ],
     "additionalDirectories": [
       "D:\\huygdv_projects\\dw-kit\\.claude\\rules"

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

@@ -18,8 +18,20 @@ Task: **$ARGUMENTS**
 - `tracking.log_work` → ghi effort tracking không
 - `workflow.default_depth` → `thorough` = cần docs-update, review bắt buộc
 
+## Detect Task Format (v1 vs v2)
+
+Kiểm tra `{paths.tasks}/$ARGUMENTS/`:
+- **v2**: có `spec.md` + `tracking.md` → đọc/ghi 2 files này.
+- **v1** (legacy): có `-context.md`/`-plan.md`/`-progress.md` → đọc/ghi bộ 3 files.
+
 ## Trước Khi Bắt Đầu
 
+**v2:**
+1. Đọc `{paths.tasks}/$ARGUMENTS/spec.md` — Intent, Scope, Subtasks, Success Criteria, Research Findings.
+2. Đọc `{paths.tasks}/$ARGUMENTS/tracking.md` — Subtask Progress table, Changelog, Handoff Notes.
+3. Xác nhận `spec.md` frontmatter có `status: Approved`.
+
+**v1:**
 1. Đọc `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-plan.md`
 2. Đọc `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-context.md`
 3. Đọc `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-progress.md`
@@ -52,16 +64,27 @@ Nếu có progress → tiếp tục từ subtask cuối cùng chưa done.
 - Nếu `quality.block_on_fail = false` → cảnh báo, cho phép tiếp tục
 
 ### Step 5: Cập nhật Progress
-Cập nhật `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-progress.md`:
+**v2**: Cập nhật `{paths.tasks}/$ARGUMENTS/tracking.md`:
+- Update row trong section `## Subtask Progress` table với status `✅ Done`, Date, Notes (commit SHA).
+- Append entry vào `## Changelog` theo format:
+  ```markdown
+  ### {date} — ST-N complete
+  **Actions taken:** ...
+  ```
+- Update frontmatter `last_updated`.
+
+**v1**: Cập nhật `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-progress.md`:
 ```markdown
 | ST-N | [Subtask name] | Done | abc1234 | [ghi chú] |
 ```
 
-Nếu `tracking.log_work = true`, ghi effort thực tế vào:
-```markdown
-### Effort Log
-| Subtask | Estimate | Actual | Ghi chú |
-```
+Nếu `tracking.log_work = true`, ghi effort thực tế:
+- **v2**: thêm cột "Actual" vào Subtask Progress table hoặc ghi trong Changelog entry.
+- **v1**:
+  ```markdown
+  ### Effort Log
+  | Subtask | Estimate | Actual | Ghi chú |
+  ```
 
 ### Step 6: Commit
 ```
@@ -91,7 +114,7 @@ Subtask ST-N of $ARGUMENTS
 
 ## Khi Hoàn Thành Tất Cả Subtasks
 
-1. Cập nhật progress: Trạng thái → `Done`
+1. Cập nhật status: **v2** `tracking.md` frontmatter `status: Done` · **v1** progress.md `Trạng thái: Done`.
 2. Tóm tắt: subtasks completed, commits, issues encountered
 3. Luôn gợi ý: "Tiếp theo: `/dw:review $ARGUMENTS`"
 4. Nếu `workflow.default_depth = thorough`: "Cần chạy `/dw:docs-update $ARGUMENTS`"

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

@@ -22,7 +22,13 @@ git stash list               # stashed work
 ```
 
 ### 2. Task progress
-Đọc `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-progress.md`:
+
+**Detect format**: Nếu có `tracking.md` → v2. Nếu có `-progress.md` → v1.
+
+- **v2**: Đọc `{paths.tasks}/$ARGUMENTS/tracking.md` — Subtask Progress table, Changelog, Handoff Notes (nếu đã có).
+- **v1**: Đọc `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-progress.md`.
+
+Tìm:
 - Subtask nào đã done?
 - Subtask nào đang làm dở?
 - Blockers nào đang tồn tại?
@@ -34,7 +40,11 @@ git stash list               # stashed work
 
 ## Viết Handoff Notes
 
-Ghi vào mục "Handoff Notes" trong `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-progress.md`:
+**v2**: Replace (hoặc append nếu muốn giữ lịch sử) section `## Handoff Notes` trong `{paths.tasks}/$ARGUMENTS/tracking.md`. Cũng update frontmatter `last_updated`.
+
+**v1**: Ghi vào mục "Handoff Notes" trong `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-progress.md`.
+
+Format (chung cho cả 2):
 
 ```markdown
 ## Handoff Notes
@@ -76,6 +86,7 @@ Sau khi ghi xong, hiển thị:
 - Tóm tắt handoff notes
 - Lệnh để người/agent tiếp theo bắt đầu:
   ```
-  Đọc: {paths.tasks}/$ARGUMENTS/$ARGUMENTS-progress.md
+  Đọc: {paths.tasks}/$ARGUMENTS/tracking.md     (v2)
+    hoặc {paths.tasks}/$ARGUMENTS/$ARGUMENTS-progress.md  (v1 legacy)
   Tiếp tục: /dw:execute $ARGUMENTS
   ```

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

@@ -1,11 +1,12 @@
 ---
 name: dw:plan
-description: "Lập kế hoạch implementation chi tiết sau khi đã research. Thiết kế giải pháp, phân chia subtasks, xác định rủi ro. DỪNG để chờ approval trước khi execute."
-argument-hint: "[task-name]"
+description: "Lập kế hoạch implementation chi tiết sau khi đã research. Thiết kế giải pháp, phân chia subtasks, xác định rủi ro. Tích hợp Quick Debate (red/blue team) tùy depth. DỪNG để chờ approval trước khi execute."
+argument-hint: "[task-name] [--debate | --no-debate]"
 allowed-tools:
   - Read
   - Grep
   - Glob
+  - Agent
 ---
 
 # Lập Kế Hoạch Implementation
@@ -27,10 +28,18 @@ Task: **$ARGUMENTS**
 - CHỈ đọc, phân tích, và viết plan
 - DỪNG LẠI cuối cùng để chờ user/TL approve
 
+## Detect Task Format (v1 vs v2)
+
+Kiểm tra `{paths.tasks}/$ARGUMENTS/`:
+- **v2**: có `spec.md` + `tracking.md` → plan output update trực tiếp vào `spec.md` (sections Scope/Subtasks/Risks/Success Criteria).
+- **v1** (legacy): có `-context.md`/`-plan.md`/`-progress.md` → plan output ghi vào `$ARGUMENTS-plan.md`.
+- Chưa có gì → gợi ý `/dw:task-init $ARGUMENTS` trước.
+
 ## Bước 1: Đọc Context
 
-Đọc `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-context.md` — file research đã tạo.
-Nếu chưa có → thông báo: "Cần chạy `/dw:research $ARGUMENTS` trước."
+- **v2**: Đọc `{paths.tasks}/$ARGUMENTS/spec.md` (bao gồm section `## Research Findings` nếu đã chạy `/dw:research`).
+- **v1**: Đọc `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-context.md` — file research đã tạo.
+- Nếu chưa có research findings → thông báo: "Cần chạy `/dw:research $ARGUMENTS` trước."
 
 ## Bước 2: Thiết kế giải pháp
 
@@ -62,7 +71,15 @@ Thứ tự subtasks theo dependency graph:
 
 ## Bước 4: Viết plan
 
-Ghi vào `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-plan.md`:
+**v2**: Update `spec.md` trực tiếp — điền vào các section có sẵn:
+- `## Scope → In Scope`: thêm ST-1, ST-2, ... với mô tả + acceptance + effort
+- `## Scope → Out of Scope`: các điểm loại trừ rõ ràng
+- `## Risks & Mitigations`: bảng risks
+- `## Success Criteria`: tiêu chí measurable
+- `## Dependencies`: blockers upstream / external
+Frontmatter: đổi `status: Draft` → `status: Approved` chỉ SAU khi user approve.
+
+**v1**: Ghi vào `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-plan.md` theo template:
 
 ```markdown
 # Plan: [Task Name]
@@ -114,12 +131,92 @@ Ghi vào `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-plan.md`:
 - Total: [sum]
 ```
 
+## Bước 4.5: Quick Debate (depth-driven, pre-approval gate)
+
+Trước khi trình bày cho user, chạy red/blue quick debate để tự phản biện plan. Tránh ceremony overhead:
+
+### Khi nào chạy
+
+| Depth | Behavior | Override |
+|-------|----------|----------|
+| `quick` | **SKIP** debate | `--debate` bật thủ công |
+| `standard` | **SKIP** mặc định — CHẠY nếu detect signal high-stakes | `--debate` bật / `--no-debate` tắt |
+| `thorough` | **DEFAULT ON** | `--no-debate` tắt |
+
+**Auto-detect signal (standard depth)** — chạy nếu plan đụng:
+- API contract changes (new endpoints, breaking signatures)
+- Database schema migrations
+- Auth / security / permissions
+- Cross-module refactoring ≥3 modules
+- Third-party integration mới
+- Performance-critical path
+
+Nếu nghi ngờ → chạy. Chi phí debate < chi phí rollback.
+
+### Mode A — Lightweight (single-agent, 2-pass) — DEFAULT
+
+Tự thực hiện 2 pass liên tiếp trong cùng session:
+
+**Pass 1 — Red Team (attack)**: Đọc lại plan vừa viết, trả lời cụ thể:
+1. Top 3 giả định đáng nghi nhất — cái nào chưa verify?
+2. Top 3 failure modes — plan fail thế nào trong edge cases?
+3. Subtask nào over-scoped (làm nhiều hơn cần) hoặc under-scoped (thiếu)?
+4. Dependency nào bị missing / fragile?
+
+**Pass 2 — Blue Team (strengthen)**: Respond từng red concern:
+1. Concern đó valid? Nếu valid → đề xuất mitigation cụ thể.
+2. Top 2 strengthenings để plan resilient hơn (thêm test, fallback, kiểm tra assumption).
+
+### Mode B — Deep (parallel subagents) — opt-in `--debate-deep`
+
+Chỉ khi stakes cực cao (breaking change, regulatory, production incident). Spawn 2 subagents parallel:
+
+```
+Agent[red-bot]: critique plan như tấn công — tìm failure modes, hidden assumptions, timing issues
+Agent[blue-bot]: defend + strengthen — propose concrete improvements
+```
+
+Dùng `Agent` tool với `subagent_type: general-purpose` (hoặc `Plan` cho review sâu). Prompt phải self-contained (subagent không thấy conversation).
+
+### Output debate
+
+**v2 format** — Append vào `tracking.md` section `## Agent Debate Log`:
+
+```markdown
+### {date} — Plan debate
+
+**Mode:** lightweight / deep
+**Red-bot findings:**
+- [Concern 1] — severity: H/M/L
+- [Concern 2] — ...
+- [Concern 3] — ...
+
+**Blue-bot response:**
+- [Mitigation or counter-argument]
+- [Strengthening proposal]
+
+**Incorporated into plan:**
+- [Specific change made to spec.md — e.g., "Added ST-X: validate schema migration on staging before prod"]
+
+**Deferred (noted but not blocking):**
+- [Lower-priority items for post-execute review]
+```
+
+**v1 format** — Append "## Debate Log" vào `$ARGUMENTS-plan.md` với cùng cấu trúc.
+
+### Nguyên tắc
+
+- **Không ceremony**: nếu debate không catch gì mới sau 2 pass → ghi "No new concerns" rồi tiếp tục. Đừng tạo finding giả để fill template.
+- **Incorporate hoặc defer rõ ràng**: mỗi red concern phải có quyết định (fix now / defer / won't fix + reason).
+- **Thời gian cap**: Mode A ≤3 phút agent time. Mode B ≤10 phút.
+
 ## Bước 5: DỪNG & Trình bày
 
 Trình bày plan cho user với:
 1. Tóm tắt approach (3-5 câu)
 2. Số subtasks và estimate tổng (nếu có)
 3. Top 2 risks
-4. Yêu cầu: "Approve plan này để tiếp tục `/dw:execute $ARGUMENTS`"
+4. **Nếu chạy debate**: Top 2 debate findings + incorporated changes (1-2 dòng)
+5. Yêu cầu: "Approve plan này để tiếp tục `/dw:execute $ARGUMENTS`"
 
 Nếu team có TL: "Plan cần TL review trước khi execute."

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

@@ -24,10 +24,20 @@ Task: **$ARGUMENTS**
 
 Đọc `.dw/config/dw.config.yml` → lấy `paths.tasks` để biết output location.
 
+## Detect Task Format (v1 vs v2)
+
+Kiểm tra `{paths.tasks}/$ARGUMENTS/`:
+- Nếu có `spec.md` + `tracking.md` → **v2 format**. Output ghi vào spec.md section "## Research Findings".
+- Nếu có `-context.md`/`-plan.md`/`-progress.md` → **v1 format** (legacy). Output ghi vào `$ARGUMENTS-context.md` như cũ.
+- Nếu chưa có gì → gợi ý user chạy `/dw:task-init $ARGUMENTS` trước.
+
+Trong các bước dưới, "context file" = `spec.md` (v2) hoặc `$ARGUMENTS-context.md` (v1).
+
 ## Bước 1: Đọc yêu cầu
 
-- Đọc file `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-plan.md` nếu đã có mô tả yêu cầu
-- Hoặc lấy yêu cầu từ conversation context
+- **v2**: Đọc `{paths.tasks}/$ARGUMENTS/spec.md` lấy Intent + Scope.
+- **v1**: Đọc `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-plan.md` nếu đã có mô tả yêu cầu.
+- Hoặc lấy yêu cầu từ conversation context.
 
 ## Bước 2: Khảo sát
 
@@ -53,7 +63,11 @@ Từ framework `.claude/skills/dw-thinking/THINKING.md`:
 
 ## Bước 4: Ghi kết quả
 
-Ghi vào `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-context.md` theo cấu trúc:
+**v2 format**: Append (hoặc replace nếu đã có) section `## Research Findings` vào `spec.md`, đặt ngay sau section `## Intent`. Giữ frontmatter và các section khác không đổi.
+
+**v1 format** (legacy): Ghi vào `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-context.md`.
+
+Cấu trúc nội dung (dùng chung cho cả 2 format):
 
 ```markdown
 # Context: [Task Name]
@@ -103,7 +117,7 @@ Dùng template `.claude/templates/agent-report.md` với:
 - 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 đã đủ.
+> Quick depth tasks: bỏ qua bước này — tracking.md (v2) / progress.md (v1) đã đủ.
 
 ## Bước 6: Tóm tắt