dw-kit 1.0.0

package/.dw/config/presets/solo-quick.yml

@@ -0,0 +1,37 @@
+# dw-kit Preset: Solo Developer — Quick Workflow
+# Dùng cho: 1 dev, task nhỏ, prototype, side project
+# Kế thừa từ: config/dw.config.yml (copy và modify)
+
+project:
+  name: "my-project"
+  language: "vi"
+
+workflow:
+  default_depth: "quick"
+
+team:
+  roles:
+    - dev
+
+quality:
+  test_command: ""
+  lint_command: ""
+  block_on_fail: false
+
+tracking:
+  estimation: false
+  log_work: false
+
+paths:
+  tasks: ".dw/tasks"
+  docs: ".dw/docs"
+
+claude:
+  structured_output: false
+  worktree_execution: false
+  mcp: []
+
+_toolkit:
+  core_version: "1.0"
+  platform_version: "1.0"
+  capability_version: "1.0"

package/.dw/core/QUALITY.md

@@ -0,0 +1,220 @@
+<!-- core-version: 1.0 -->
+
+# Quality Strategy — 4-Layer Framework
+
+> **Nguyên tắc**: Quality là constant. Ceremony adapts.
+> Không có "quality level" — chỉ có depth phù hợp với context.
+
+---
+
+## Overview
+
+```
+Layer 1: Requirements Clarity   → trước khi code
+Layer 2: Test-Driven Development → trong khi code
+Layer 3: Cross-Review           → sau khi code
+Layer 4: Automated Gates + QA   → trước khi merge
+```
+
+Mỗi layer build on top of layer trước. Skip layer sớm → vấn đề phát sinh muộn hơn với chi phí cao hơn.
+
+---
+
+## Layer 1: Requirements Clarity (Trước Khi Code)
+
+**Mục tiêu**: Đảm bảo hiểu đúng và đủ TRƯỚC khi bắt đầu implement.
+
+### Given/When/Then Format
+
+Mỗi feature/subtask nên có acceptance criteria theo format:
+
+```
+Given [trạng thái ban đầu / precondition]
+When  [hành động / trigger]
+Then  [kết quả mong đợi / postcondition]
+```
+
+Ví dụ:
+```
+Given user đã đăng nhập và có items trong cart
+When user logout rồi login lại
+Then cart items vẫn còn nguyên
+```
+
+### Checklist Requirements Clarity
+
+- [ ] Business logic được mô tả bằng Given/When/Then
+- [ ] Edge cases được identify upfront (không phải sau khi code xong)
+- [ ] Acceptance criteria per subtask: testable và specific (không mơ hồ)
+- [ ] Out-of-scope được ghi rõ (tránh scope creep)
+- [ ] Nếu có TL: TL đã review requirements trước khi dev bắt đầu
+
+### Red Flags
+
+- Acceptance criteria dùng "should work" / "hoạt động đúng" — không đo lường được
+- Edge cases không được hỏi khi plan, chỉ phát hiện khi test
+- "Tôi hiểu rồi" mà không có written acceptance criteria
+
+---
+
+## Layer 2: Test-Driven Development (Trong Khi Code)
+
+**Mục tiêu**: Tests là specification, không phải afterthought.
+
+### TDD Cycle Per Subtask
+
+```
+RED   → Viết test trước (failing) — test mô tả behavior mong muốn
+GREEN → Implement tối thiểu để test pass — không over-engineer
+REFACTOR → Cải thiện code structure, không thay đổi behavior
+COMMIT → Một subtask = một commit
+```
+
+### Test Coverage Priorities
+
+1. **Happy path**: nominal flow với input hợp lệ
+2. **Error cases**: invalid input, missing data, permission denied
+3. **Edge cases**: boundary values, empty collections, concurrent operations
+4. **Regression**: verify fixed bugs không tái xuất hiện
+
+### Test Naming Convention
+
+```
+should [expected behavior] when [condition]
+
+Ví dụ:
+- should return empty cart when user has no items
+- should throw AuthError when token is expired
+- should preserve cart when user re-logs in
+```
+
+### Checklist TDD
+
+- [ ] Test file tạo TRƯỚC khi implement
+- [ ] Test fail first (RED) đã verify
+- [ ] Implement minimal để pass (GREEN)
+- [ ] Refactor nếu code smell (không thay đổi tests)
+- [ ] Coverage: happy + error + edge cases
+- [ ] Tests independent (không phụ thuộc thứ tự run)
+- [ ] Không mock internal implementation — chỉ mock external boundaries
+
+---
+
+## Layer 3: Cross-Review (Sau Khi Code)
+
+**Mục tiêu**: Phát hiện issues mà người viết không thấy.
+
+### TL Architecture Review (nếu có techlead)
+
+Tập trung vào:
+- Architecture decisions đúng không? Có alternatives tốt hơn?
+- Patterns nhất quán với codebase không?
+- Scalability và performance implications?
+- Security design đúng không?
+
+Output: Approve hoặc Request Changes với lý do cụ thể.
+
+### Peer Code Review Checklist
+
+```
+CORRECTNESS
+[ ] Logic đúng? Edge cases handled?
+[ ] Error handling đầy đủ? Logged đủ context?
+[ ] No silent failures
+
+SECURITY
+[ ] Input validation ở boundaries?
+[ ] No SQL injection / XSS / command injection?
+[ ] Auth/authz checks đúng?
+[ ] No sensitive data in logs/responses
+
+PERFORMANCE
+[ ] N+1 queries?
+[ ] Missing indexes?
+[ ] Unnecessary loops trong hot path?
+
+MAINTAINABILITY
+[ ] Naming rõ ràng, self-documenting?
+[ ] Functions làm 1 việc?
+[ ] No dead code?
+[ ] Complex logic có comment (WHY, không WHAT)?
+
+TESTS
+[ ] Tests cover happy path + error + edge cases?
+[ ] Test names mô tả behavior?
+[ ] No flaky tests?
+```
+
+### A/B Testing Cho Uncertain Decisions
+
+Khi có 2 approaches và không rõ approach nào tốt hơn:
+1. Prototype cả 2 (minimal implementation)
+2. So sánh: performance, readability, testability, maintainability
+3. TL decide và ghi lý do vào task docs
+4. Loại bỏ prototype không chọn
+
+### Review Output Format
+
+Reviewer phân loại theo mức độ:
+
+| Mức độ | Ký hiệu | Ý nghĩa |
+|--------|---------|---------|
+| Critical | 🔴 | Phải sửa trước khi merge. Block merge. |
+| Warning | 🟡 | Nên sửa. Không block nhưng ưu tiên cao. |
+| Suggestion | 🔵 | Cân nhắc. Không block. |
+| Positive | ✅ | Ghi nhận điểm tốt. |
+
+---
+
+## Layer 4: Automated Gates + QA Confirmation (Trước Merge)
+
+**Mục tiêu**: Machine-verifiable checks và human QA sign-off.
+
+### Automated Gates
+
+Chạy tự động, block nếu fail (nếu `block_on_fail: true`):
+
+```bash
+# Quality check script
+{quality.test_command}    # unit + integration tests
+{quality.lint_command}    # code style + static analysis
+```
+
+Mandatory (luôn chạy, không configurable):
+- No debug code: `console.log`, `debugger`, `var_dump`, `dd()`
+- No sensitive data: passwords, API keys, tokens trong diff
+
+### QA Confirmation (thorough depth + có qc role)
+
+QA không phải developer — QA là independent verification:
+
+1. QA nhận test plan (từ Phase 3)
+2. QA verify acceptance criteria từ Layer 1
+3. QA chạy regression checklist
+4. QA sign-off là **explicit gate** — không implied, không assumed
+5. Nếu QA find issues → developer fix → QA re-verify
+
+### Merge Checklist
+
+Trước khi merge PR:
+
+- [ ] Layer 1: Tất cả acceptance criteria pass
+- [ ] Layer 2: Tests pass locally và CI
+- [ ] Layer 3: Code review approved (0 CRITICAL, warnings resolved hoặc acknowledged)
+- [ ] Layer 4: Automated gates pass + QA sign-off (nếu required)
+- [ ] No debug code, no sensitive data
+- [ ] Commit messages follow convention
+- [ ] Branch up to date với main
+
+---
+
+## Quality Anti-Patterns
+
+| Anti-pattern | Vấn đề | Fix |
+|-------------|--------|-----|
+| Tests sau khi code xong | Tests được viết để match implementation, không verify behavior | Test-first |
+| Mock everything | Tests pass nhưng integration fails | Chỉ mock external boundaries |
+| "It works on my machine" | Không có automated gate | CI/CD + pre-commit hooks |
+| Skip review vì "urgent" | Bugs slip to production, harder to fix | Fast review còn tốt hơn no review |
+| LGTM without reading | Review là ceremony, không quality gate | Structured checklist |
+| QA là formality | Issues found late, expensive to fix | QA reviews against acceptance criteria |

package/.dw/core/ROLES.md

@@ -0,0 +1,257 @@
+<!-- core-version: 1.0 -->
+
+# Team Roles & Authority
+
+> **Nguyên tắc**: Roles = capabilities, không phải hierarchy.
+> Config `team.roles` quyết định phases nào available, không phải quality tier.
+
+---
+
+## Role Overview
+
+| Role | Ký hiệu config | Core responsibility | Decision authority |
+|------|----------------|--------------------|--------------------|
+| Developer | `dev` | Implementation, testing | Code-level decisions |
+| Tech Lead | `techlead` | Architecture, code standards | Architecture decisions, plan approval |
+| Business Analyst | `ba` | Requirements, user stories | Requirements sign-off |
+| QC Engineer | `qc` | Test planning, quality verification | QA sign-off (Layer 4) |
+| Product Manager | `pm` | Progress visibility, metrics | Sprint planning, backlog priority |
+
+> `dev` luôn required. Các roles khác là optional — không có thì phase đó gracefully degrade.
+
+---
+
+## Developer (`dev`)
+
+**Trách nhiệm chính**: Research → Plan → Execute → Commit
+
+### Phases Developer Owns
+
+| Phase | Responsibility |
+|-------|---------------|
+| Initialize | Tạo task docs, scope assessment |
+| Understand | Codebase research, context gathering |
+| Plan | Solution design, subtask breakdown |
+| Execute | Implementation, TDD, subtask commits |
+| Verify | Self-review (Layer 1), automated gates (Layer 2) |
+| Close | Commit, effort log, handoff |
+
+### Decision Authority
+
+- Code implementation decisions
+- Library/dependency choices (minor)
+- Subtask ordering và approach (trong scope của plan approved)
+- **DỪNG và hỏi khi**: architecture change, API contract change, scope expansion
+
+### Best Practices
+
+- Commit nhỏ, thường xuyên (mỗi subtask = 1 commit)
+- Update progress file sau mỗi subtask
+- Không implement ngoài scope plan đã approve
+- Phát hiện giả định sai → ghi Changelog + hỏi TL trước khi tiếp tục
+
+---
+
+## Tech Lead (`techlead`)
+
+**Trách nhiệm chính**: Architecture quality, standards enforcement, plan approval
+
+### Phases TL Owns
+
+| Phase | Responsibility |
+|-------|---------------|
+| Plan | Architecture review, approve plan trước Execute |
+| Execute | Unblock architecture decisions during implementation |
+| Verify | Code review (Layer 3 — architecture focus) |
+| Close | Final technical sign-off |
+
+### Decision Authority
+
+- Architecture decisions (service boundaries, patterns, data models)
+- Plan approval: **explicit gate** — Execute không bắt đầu khi chưa có TL approve
+- A/B testing resolution: TL chọn approach khi hai approaches không rõ ưu/nhược
+- Technical debt acknowledgment: quyết định "acceptable" hay "must fix"
+
+### Architecture Review Checklist
+
+```
+[ ] Approach consistent với codebase patterns?
+[ ] Scalability implications acceptable?
+[ ] Security design đúng?
+[ ] API contract backward compatible (hoặc migration plan có)?
+[ ] Subtask breakdown hợp lý? Dependencies đúng?
+[ ] Risks identified và có mitigation?
+```
+
+### TL không có?
+
+- Plan vẫn proceed nhưng developer self-review architecture decisions
+- Ghi rõ trong plan: "Architecture decision by dev (no TL review)"
+- Architecture decisions nên bảo thủ hơn khi không có TL
+
+---
+
+## Business Analyst (`ba`)
+
+**Trách nhiệm chính**: Requirements clarity, user stories, acceptance criteria
+
+### Phases BA Owns
+
+| Phase | Responsibility |
+|-------|---------------|
+| Initialize | Requirements gathering, user stories |
+| Plan | Review subtask acceptance criteria |
+| Verify | Acceptance criteria verification |
+
+### Decision Authority
+
+- Requirements sign-off: "dev builds the right thing"
+- Scope boundary: in-scope vs out-of-scope
+- Acceptance criteria: testable, specific, agreed
+
+### Requirements Output Format
+
+```markdown
+## User Story
+As a [role], I want [goal] so that [benefit].
+
+## Acceptance Criteria
+Given [precondition]
+When [action]
+Then [outcome]
+
+## Out of Scope
+- [explicitly excluded items]
+
+## Edge Cases to Handle
+- [edge case 1]
+- [edge case 2]
+```
+
+### BA không có?
+
+- Developer writes requirements từ conversation với stakeholder
+- Requirements review là developer + TL (không có independent BA)
+- Risk cao hơn về misunderstood requirements — tăng frequency of check-ins
+
+---
+
+## QC Engineer (`qc`)
+
+**Trách nhiệm chính**: Test planning, independent quality verification
+
+### Phases QC Owns
+
+| Phase | Responsibility |
+|-------|---------------|
+| Plan | Test plan tạo song song với dev plan |
+| Verify | Execute test plan, Layer 4 sign-off |
+
+### Decision Authority
+
+- QA sign-off: **explicit gate** cho `thorough` depth — không thể self-approve
+- Bug severity classification
+- Regression scope: gì cần test lại sau change
+
+### Test Plan Structure
+
+```markdown
+## Test Cases
+### TC-1: [Test case name]
+- **Given**: [precondition]
+- **When**: [action]
+- **Then**: [expected result]
+- **Priority**: P1/P2/P3
+
+## Regression Checklist
+- [ ] [Feature 1 không bị ảnh hưởng]
+- [ ] [Feature 2 không bị ảnh hưởng]
+
+## Security Checklist (nếu applicable)
+- [ ] Input validation
+- [ ] Auth/authz checks
+- [ ] No data exposure
+
+## Performance Checklist (nếu applicable)
+- [ ] Response time acceptable
+- [ ] No N+1 queries introduced
+```
+
+### QC không có?
+
+- Developer tự execute test plan (nếu có) hoặc manual verification
+- Layer 4 QA sign-off skip — nhưng automated gates (Layer 4a) vẫn chạy
+- Risk cao hơn về undiscovered bugs
+
+---
+
+## Product Manager (`pm`)
+
+**Trách nhiệm chính**: Progress visibility, metrics, sprint planning
+
+### Phases PM Owns
+
+| Phase | Responsibility |
+|-------|---------------|
+| Initialize | Sprint planning, priority |
+| Close | Sprint review, velocity tracking |
+| Standalone: Reports | Dashboard generation |
+
+### PM View
+
+PM không cần đọc code — PM đọc:
+- Progress files (status per subtask)
+- Dashboard reports (velocity, metrics)
+- Sprint review summaries
+
+### Dashboard Metrics
+
+| Metric | Source | Update frequency |
+|--------|--------|-----------------|
+| Tasks: done/in-progress/blocked | Progress files | Real-time |
+| Velocity | Closed tasks per sprint | Per sprint |
+| Estimate accuracy | Estimate vs actual | Per task |
+| DORA: deployment frequency | Git history | Per release |
+| DORA: lead time | Task start → deploy | Per release |
+
+---
+
+## Multi-Role Workflow
+
+Full team workflow (tất cả roles):
+
+```
+BA: /dw-requirements     → requirements doc + user stories
+     ↓
+TL: /dw-arch-review      → architecture decision + approve
+     ↓
+Dev: /dw-task-init       → task docs
+Dev: /dw-research        → codebase analysis
+Dev+QC: /dw-plan         → dev plan + test plan (parallel)
+     ↓
+TL approve plan
+     ↓
+Dev: /dw-execute         → TDD implementation, commits
+     ↓
+TL: /dw-review           → architecture + code review
+     ↓
+QC: manual/auto testing  → Layer 4 verification
+     ↓
+Dev: /dw-commit          → pre-commit gates
+     ↓
+PM: /dw-dashboard        → visibility, metrics
+```
+
+Không phải mọi task cần full chain. `default_depth` + available roles quyết định.
+
+---
+
+## Role-Depth Matrix
+
+| Role | Quick | Standard | Thorough |
+|------|-------|----------|----------|
+| dev | required | required | required |
+| techlead | not needed | arch decisions only | full review + approval |
+| ba | not needed | requirements check | full requirements |
+| qc | not needed | not needed | full test plan + sign-off |
+| pm | not needed | optional | dashboard |

package/.dw/core/THINKING.md

@@ -0,0 +1,126 @@
+<!-- core-version: 1.0 -->
+
+# Tư Duy Phản Biện, Hệ Thống, Đa Góc Nhìn & First Principles
+
+Framework tư duy cho cả người và AI agent khi research, plan, và implement.
+
+---
+
+## 1. First Principles Thinking
+
+**Mục đích**: Bỏ qua assumptions, trở về câu hỏi cơ bản nhất. Tránh "chúng tôi luôn làm vậy."
+
+### Quy Trình
+
+1. **Decompose**: Tách vấn đề thành các phần cơ bản nhất — không thể tách nhỏ hơn
+2. **Question assumptions**: Mỗi assumption: "Điều này có đúng không? Có thể kiểm chứng được không?"
+3. **Rebuild**: Từ những gì đã verify, build lại solution từ đầu
+4. **Compare**: Solution mới có ưu việt hơn solution cũ không? Tại sao?
+
+### Câu Hỏi First Principles
+
+- "Vấn đề thực sự cần giải quyết là gì?" (không phải symptom)
+- "Nếu không có bất kỳ constraint nào, solution tốt nhất là gì?"
+- "Constraint nào là thực sự hard, constraint nào là assumed?"
+- "Ai đang được served bởi solution này? Họ thực sự cần gì?"
+
+---
+
+## 2. Tư Duy Phản Biện (Critical Thinking)
+
+**Mục đích**: Không chấp nhận giả định một chiều. Đặt câu hỏi, xem xét rủi ro, phương án thay thế.
+
+### Câu Hỏi Khi Research & Plan
+
+- **Giả định**: Những giả định nào đang coi là đúng? Nếu sai thì ảnh hưởng thế nào?
+- **Bằng chứng**: Kết luận dựa trên đâu (code, doc, đo lường)? Thiếu bằng chứng ở đâu?
+- **Edge cases**: Trường hợp biên nào có thể làm hỏng thiết kế? (null, empty, concurrent, rollback)
+- **Rủi ro**: Rủi ro kỹ thuật, vận hành, bảo mật? Xác suất và tác động?
+- **Phương án thay thế**: Còn cách nào khác? Trade-off so với approach hiện tại?
+- **Phản diện (Devil's advocate)**: Lý do mạnh nhất để KHÔNG làm theo approach đang chọn?
+- **Đơn giản hơn**: Có cách nào đơn giản hơn đạt cùng mục tiêu không?
+
+### Áp Dụng Trong Task
+
+- **Research**: Ghi rõ "Giả định", "Hạn chế đã biết", "Chưa rõ / cần kiểm chứng"
+- **Plan**: Có mục "Rủi ro & Giả định" và "Phương án đã xem xét"
+- **Execute**: Phát hiện giả định sai → DỪNG, ghi Changelog, cập nhật plan
+
+---
+
+## 3. Tư Duy Hệ Thống (Systems Thinking)
+
+**Mục đích**: Xem task trong bối cảnh hệ thống lớn. Dependencies, tác động lan truyền, failure modes.
+
+### Các Khía Cạnh Cần Xem Xét
+
+- **Dependencies**: Task này phụ thuộc vào gì? Ai phụ thuộc vào kết quả của task này?
+- **Boundaries**: Ranh giới rõ ràng chưa? Interfaces ổn định chưa?
+- **Data flow**: Dữ liệu đi từ đâu đến đâu? Thêm DB/cache/queue? Consistency?
+- **Feedback loops**: Thay đổi có tạo vòng lặp không? Cần giới hạn hay debounce?
+- **Failure modes**: Một phần lỗi → hệ thống còn lại ứng xử thế nào? Graceful degradation?
+- **Scale**: Khi tải tăng, điểm nghẽn ở đâu? N+1 queries, missing indexes, locks?
+
+### Áp Dụng Trong Task
+
+- **Research**: Mô tả (hoặc diagram) luồng hiện tại và vị trí của task
+- **Plan**: Mục "Tác động hệ thống" — modules bị ảnh hưởng, API changes, migration
+- **Subtasks**: Tách rõ schema / service / route / frontend để review dependencies
+
+---
+
+## 4. Đa Góc Nhìn (Multiple Perspectives)
+
+**Mục đích**: Tránh optimize cho một role. Cân bằng nhu cầu nhiều bên liên quan.
+
+### Bảng Góc Nhìn
+
+| Góc nhìn | Câu hỏi điển hình |
+|----------|-------------------|
+| **End user** | Dễ dùng không? Feature có match use case thực tế? |
+| **Developer** | Code dễ đọc, test được không? API nhất quán? |
+| **Security** | Ai được làm gì? Có lộ data không? Auth/authz đúng? Rate limit? |
+| **Ops/Vận hành** | Deploy thế nào? Migration cần gì? Metric/log/debug khi lỗi? |
+| **Business/Product** | Giải quyết đúng pain point chưa? Ship được từng phần? |
+| **Ngắn hạn vs dài hạn** | Ship nhanh vs kiến trúc bền vững. Tech debt chấp nhận được không? |
+
+### Áp Dụng Trong Task
+
+- **Plan**: Mục "Góc nhìn & Trade-offs" — mỗi quyết định lớn, ghi tác động per role
+- **Acceptance criteria**: Có thể tách "User: ...", "Dev: ...", "Security: ..."
+- **Review**: Nếu chỉ đúng về kỹ thuật nhưng bỏ qua security/ops → bổ sung
+
+---
+
+## 5. Checklist Nhanh (Trước Khi Kết Thúc Mỗi Phase)
+
+### Research
+
+- [ ] Đã ghi giả định và có thể sai không?
+- [ ] Đã ghi những gì chưa rõ / cần kiểm chứng?
+- [ ] Đã identify failure modes của kiến trúc hiện tại?
+
+### Plan
+
+- [ ] Đã xem xét ≥2 approaches và so sánh trade-offs?
+- [ ] Có mục Rủi ro & Giả định?
+- [ ] Có mục Edge cases?
+- [ ] Có mục Tác động hệ thống?
+- [ ] Đã xem xét ≥2 góc nhìn (user, security, dev, ops)?
+- [ ] Devil's advocate: lý do mạnh nhất để không làm approach này?
+
+### Execute
+
+- [ ] Có assumption nào bị chứng minh sai? → Ghi Changelog, cập nhật plan
+- [ ] Có scope thay đổi? → Cập nhật plan, hỏi human
+
+---
+
+## 6. Prompt Gợi Ý Cho Agent
+
+Khi giao task cho AI agent:
+
+> "Khi làm task này, áp dụng framework trong `core/THINKING.md`:
+> - Trước khi viết plan, liệt kê: (1) giả định đang dùng, (2) 2 rủi ro chính, (3) 1 phương án thay thế đã loại và lý do
+> - Xem xét tác động lên ít nhất 2 góc nhìn (vd: user + security)
+> - Nếu phát hiện giả định sai trong khi execute → dừng, ghi Changelog, hỏi"