dw-kit 1.9.2 → 1.9.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +150 -121
- package/README.vi.md +230 -0
- package/package.json +4 -1
- package/src/commands/voice.mjs +431 -2
- package/src/lib/board-data.mjs +23 -57
- package/src/lib/goal-driver.mjs +312 -0
- package/src/lib/goal-progress.mjs +193 -0
- package/src/lib/process-kill.mjs +77 -0
- package/src/lib/task-md-utils.mjs +78 -0
package/README.md
CHANGED
|
@@ -1,201 +1,230 @@
|
|
|
1
1
|
# dw-kit
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
🇬🇧 **English** · [🇻🇳 Tiếng Việt](README.vi.md)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/dw-kit)
|
|
6
|
+
[](https://www.npmjs.com/package/dw-kit)
|
|
7
|
+
[](https://nodejs.org)
|
|
8
|
+
[](LICENSE)
|
|
6
9
|
|
|
7
|
-
|
|
10
|
+
> A **governance harness for AI-assisted development**. Give your coding agent a repeatable workflow, safety guards, and a memory that outlives the chat window — so it ships review-ready work instead of confident guesses.
|
|
8
11
|
|
|
9
|
-
|
|
12
|
+
```bash
|
|
13
|
+
npm install -g dw-kit && dw init
|
|
14
|
+
```
|
|
10
15
|
|
|
11
|
-
|
|
16
|
+
Then, inside your AI IDE:
|
|
12
17
|
|
|
13
18
|
```
|
|
14
|
-
|
|
19
|
+
/dw:flow build the thing you actually want
|
|
15
20
|
```
|
|
16
21
|
|
|
17
|
-
|
|
22
|
+
That's it. `dw` drives the rest — and **stops for your approval** before it writes code.
|
|
18
23
|
|
|
19
|
-
|
|
24
|
+
> **Works with any agentic CLI** — Claude Code, Codex, Gemini, Cursor, Windsurf, Copilot. The `dw` CLI and the Markdown methodology are universal: if your agent can read files and run a shell, it can run dw-kit. The *full* harness (hooks, skill automation, multi-agent orchestration) is first-class on **[Claude Code](https://claude.ai/code)**; a generic adapter gives everything else the methodology layer.
|
|
20
25
|
|
|
21
|
-
|
|
26
|
+
---
|
|
22
27
|
|
|
23
|
-
|
|
28
|
+
## Why dw-kit?
|
|
24
29
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
30
|
+
AI agents are fast but stateless: they forget context between sessions, skip planning, and have no notion of "wait, get a human to look at this first." dw-kit wraps your agent in a lightweight process so the speed stays and the chaos doesn't.
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
Initialize → Understand → Plan → Execute → Verify → Close
|
|
34
|
+
│ │ │ │ │ │
|
|
35
|
+
scope survey design TDD, quality handoff
|
|
36
|
+
+ docs code (✋ STOP 1 commit gates + notes +
|
|
37
|
+
for OK) /subtask review archive
|
|
38
|
+
```
|
|
32
39
|
|
|
33
|
-
|
|
40
|
+
- **✋ Human checkpoints** — the agent pauses at Plan for your sign-off, never silently barrels ahead.
|
|
41
|
+
- **🛡️ Guards** — hooks block commits of secrets, `.env`, and unsafe edits before they happen.
|
|
42
|
+
- **🧠 Memory that survives sessions** — decisions, task docs, and handoff notes let the next session resume cold.
|
|
43
|
+
- **🌏 Fully bilingual** — English + Vietnamese UX out of the box.
|
|
34
44
|
|
|
35
45
|
---
|
|
36
46
|
|
|
37
|
-
##
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
**Drift fix structurally.** v2 split `spec.md` + `tracking.md` was leaking status markers across both files. v3 puts everything in one `task.md` (Sections 1-7: Snapshot · Intent · Tracker · Changelog · Handoff · Annexes · Debate). Status lives ONLY in Section 3 — enforced by `dw task lint` strict default.
|
|
57
|
-
|
|
58
|
-
- **`dw task new <name>`** — scaffold v3 task from template, frontmatter ajv-validated.
|
|
59
|
-
- **`dw task show [name]`** — ANSI terminal snapshot (~30 lines).
|
|
60
|
-
- **`dw task view [name]`** — lean HTML dashboard in browser. 4 cards: snapshot + progress bar + subtask tracker + recent activity + handoff. ~10KB, self-contained (no CDN), scan-in-5-seconds. Trace `task.md` for full details.
|
|
61
|
-
- **`dw task watch [name]`** — live-preview server. fs.watch + 800ms debounce + browser auto-refresh on save. Pair-with-agent workflow.
|
|
62
|
-
- **`dw task render [name]`** — `timeline.svg` sidecar via `dw-kit-render` (satori+resvg). Bounded composition. Mermaid Gantt fallback if sub-package absent.
|
|
63
|
-
- **`dw task lint [name]`** — schema validate + drift-marker detect + line-cap thresholds. Default `strict` (exit 1 on errors). Configurable via `task.lint: warn|off`.
|
|
64
|
-
- **`dw task migrate <name>`** — v2 → v3 with `--dry-run`, `--diff`, `--rollback`, `--all`. `.v2bak` backups preserved (gitignored).
|
|
65
|
-
- **`dw task rotate [name]`** — auto Section-4 overflow > 400 lines → `timeline-history.md`. Invoked by `stop-check` hook.
|
|
66
|
-
- **3-tier auto-sync**: `stop-check` (session end) · `pre-commit-gate` (commit gate) · `dw task watch` (real-time opt-in).
|
|
67
|
-
- **7 skills v3-aware** (task-init / execute / handoff / research / plan / decision / retroactive) — read v3 first, fall back v2/v1.
|
|
68
|
-
|
|
69
|
-
### What's in v1.3.6 for your team
|
|
70
|
-
|
|
71
|
-
Reaction time when a supply-chain incident drops goes from 24-72 hours (wait for OSV index + npm publish cycle) to **~1 hour** (AI edits lockfile → hook fires → heuristic flags BEFORE anyone knows).
|
|
72
|
-
|
|
73
|
-
- **3-pillar default scan** — `dw security-scan` now runs OSV snapshot + curated IoC fixture + AI-Native heuristic in one go. Heuristic only probes NEW/bumped packages from `git show HEAD:package-lock.json` diff — typical edit = 1-5 packages probed, not 1000+.
|
|
74
|
-
- **npm registry metadata heuristic** — composite scoring on `recent_publish` (<72h), `popular_package` (≥10k weekly DL), `maintainer_change_recent`, `major_version_jump`, `typo_squat`. Per-package metadata cached 1h. Tunable threshold via `.dw/config/dw.config.yml`.
|
|
75
|
-
- **Version-aware IoC fixture** — `affected_range` per entry. Concrete versions out-of-range are skipped (no false positives). Range specs (`^1.169.0`) emit ambiguity warnings with severity downgrade.
|
|
76
|
-
- **Hook fires `dw security-scan --heuristic-only`** on Claude Code lockfile edit — fast diff-only check.
|
|
77
|
-
- **Telemetry per pillar** — `source: 'osv' | 'fixture' | 'heuristic'` tracked separately so the 2026-08-12 sunset review attributes catches to the right pillar.
|
|
78
|
-
- **`>1000 packages`** crash bug from v1.3.5 fixed (chunked OSV batches).
|
|
79
|
-
|
|
80
|
-
### What's in v1.3.5 for your team
|
|
81
|
-
|
|
82
|
-
- **`dw security-scan`** — scan for known supply-chain advisories against your project's `package-lock.json` (full match) or `package.json` (pre-install approximate). Uses [OSV.dev](https://osv.dev/) as data source (multi-maintainer upstream feed; no solo-curated bundle to go stale).
|
|
83
|
-
- **AI-aware hook** — fires when Claude Code edits a lockfile. Auto-wired by `dw init --preset team` or `--preset enterprise`; opt-in OFF for `--preset solo`.
|
|
84
|
-
- **Scoped `.gitignore`** — `dw init` and `dw upgrade` write `.dw/.gitignore` and `.claude/.gitignore` managed blocks. Framework files stay out of your repo; tasks/decisions/docs/config stay in.
|
|
85
|
-
- **`dw doctor`** has a new security section that fails loud if advisory snapshot is stale (>7 days) or schema-incompatible.
|
|
86
|
-
- **Sunset rule** — feature retires silently in v1.4.x if 90-day telemetry shows zero real catches OR >5% false-positive rate. Disciplined experiment, not panic ship.
|
|
47
|
+
## Built to self-correct — with you in the loop
|
|
48
|
+
|
|
49
|
+
Two mechanisms keep the agent honest instead of merely busy.
|
|
50
|
+
|
|
51
|
+
**The pursuit loop — `/dw:goal`.** Most agents optimize for *"I did the task."* dw-kit optimizes for the *outcome*. Give it a Goal with measurable Key Results and it runs an OODA-style loop, re-measuring the gap every pass. When an approach fails it **escalates its thinking** — climbs a reasoning ladder — instead of retrying the same move. It exits only when the KR actually hits target, not when it runs out of steam. *(ADR-0016)*
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
measure gap → act → re-measure ──┐
|
|
55
|
+
▲ │
|
|
56
|
+
└──── stuck? escalate ◀──────┘ climb the ladder, don't repeat
|
|
57
|
+
exit only when the Key Result is met
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Autonomy is a dial: **supervised** (stop every loop) → **checkpoint** (`--auto`, stop at each KR) → **full** (`--auto=full`, hard-stops only), bounded by `--max-iter`.
|
|
61
|
+
|
|
62
|
+
**Adversarial review, then you — `/dw:plan`.** Before a plan ever reaches you, dw grills it with a **red-team / blue-team debate**: red attacks for failure modes and hidden assumptions, blue strengthens or concedes. You receive the *sharpened* plan plus what was contested — then **execution stops for your approval.** The same reflex recurs at **Verify** (`/dw:review`: correctness · security · conventions · coverage) and at every commit gate. The agent proposes; you decide and steer.
|
|
63
|
+
|
|
64
|
+
> Debate is depth-aware — off for `quick`, auto-triggered on high-stakes signals for `standard`, on by default for `thorough`. Override with `--debate` / `--no-debate`.
|
|
87
65
|
|
|
88
66
|
---
|
|
89
67
|
|
|
90
|
-
##
|
|
68
|
+
## The harness: how dw governs your agent
|
|
69
|
+
|
|
70
|
+
dw-kit sits *above* your coding agent as a thin governance harness — three durable layers it reads and writes as it works:
|
|
71
|
+
|
|
72
|
+
| Layer | Manages | Artifacts |
|
|
73
|
+
|-------|---------|-----------|
|
|
74
|
+
| **Context** | What the agent knows, every session | `CLAUDE.md`, ADRs (`/dw:decision`), handoff notes |
|
|
75
|
+
| **Tasks** | One source of truth per unit of work | `task.md` (v3 — lint + schema, status drift-proof), `ACTIVE.md` index |
|
|
76
|
+
| **Goals** | Outcomes above the task line | `dw goal *`, Key Results, task ↔ goal links |
|
|
77
|
+
|
|
78
|
+
Because this state lives in **plain files, not a chat window**, it survives session resets, model swaps, and handoffs between agents or humans — the part a session-scoped IDE assistant structurally cannot own.
|
|
79
|
+
|
|
80
|
+
### Parallel multi-agent orchestration (Agent OS)
|
|
81
|
+
|
|
82
|
+
A task rarely needs just one agent. **Agent OS** lets an orchestrator split a `task.md` into bounded work units and hand them to *different* agents running **in parallel** — say Claude Code on the API, Codex on the tests, Gemini on the docs, a human on the tricky migration:
|
|
91
83
|
|
|
92
84
|
```bash
|
|
93
|
-
|
|
85
|
+
dw agent claim payments --subtasks ST-1 --write "src/api/**" --vendor claude --lease 1h
|
|
86
|
+
dw agent claim payments --subtasks ST-2 --write "test/**" --vendor codex
|
|
87
|
+
dw agent conflicts # exit 1 if two claims overlap on files or subtasks
|
|
94
88
|
```
|
|
95
89
|
|
|
90
|
+
Each agent **claims** its subtasks + file scope before editing, so parallel work doesn't collide. It's **cooperative, not forced**: overlaps are caught by `dw agent conflicts` and the `pre-commit-gate` hook, every agent's report merges back into the one `task.md`, and the **orchestrator stops for your approval before any push.** *(ADR-0009)*
|
|
91
|
+
|
|
96
92
|
---
|
|
97
93
|
|
|
98
94
|
## Quick start
|
|
99
95
|
|
|
100
|
-
Setup dw in project directory:
|
|
101
|
-
|
|
102
96
|
```bash
|
|
97
|
+
# 1. Install
|
|
98
|
+
npm install -g dw-kit
|
|
99
|
+
|
|
100
|
+
# 2. Set up in your project (wizard, or --solo for zero-config)
|
|
103
101
|
dw init
|
|
102
|
+
dw init --solo # vibe-coder mode: guards only, no task docs
|
|
103
|
+
|
|
104
|
+
# 3. Drive a task from your AI IDE
|
|
105
|
+
/dw:flow add user authentication
|
|
104
106
|
```
|
|
105
107
|
|
|
106
|
-
|
|
108
|
+
Other skills worth knowing:
|
|
107
109
|
|
|
108
110
|
```
|
|
109
|
-
/dw:
|
|
111
|
+
/dw:prompt # turn a vague idea into a sharp, actionable prompt
|
|
112
|
+
/dw:plan # plan + red/blue self-critique, then stop for approval
|
|
113
|
+
/dw:review # correctness · security · conventions · coverage
|
|
114
|
+
/dw:decision # capture an architectural decision (ADR)
|
|
115
|
+
/dw:goal # drive a Goal toward its Key Results (pursuit loop)
|
|
110
116
|
```
|
|
111
117
|
|
|
112
118
|
---
|
|
113
119
|
|
|
114
|
-
|
|
120
|
+
## Tutorial: ship your first feature
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
dw init # one-time: scaffold .dw/ + .claude/ in your repo
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Then, inside Claude Code:
|
|
115
127
|
|
|
116
128
|
```
|
|
117
|
-
/dw:
|
|
118
|
-
/dw:thinking
|
|
119
|
-
/dw:decision
|
|
120
|
-
...
|
|
129
|
+
/dw:flow add password reset via email
|
|
121
130
|
```
|
|
122
131
|
|
|
123
|
-
|
|
132
|
+
What unfolds, in order:
|
|
124
133
|
|
|
125
|
-
|
|
134
|
+
1. **Initialize + Understand** — dw scopes the task, scaffolds a `task.md`, and surveys your auth code (no edits yet).
|
|
135
|
+
2. **Plan** — proposes subtasks, self-critiques red/blue, then **stops.** You reply *"go"* or steer.
|
|
136
|
+
3. **Execute** — implements subtask-by-subtask, TDD, one commit each (or fan the subtasks out to parallel agents via Agent OS). Secrets / `.env` are blocked at the gate.
|
|
137
|
+
4. **Verify** — runs your tests + a `/dw:review` pass (correctness · security · conventions).
|
|
138
|
+
5. **Close** — writes handoff notes so tomorrow's session resumes without you re-explaining.
|
|
126
139
|
|
|
127
|
-
|
|
140
|
+
Prefer manual control? Run the phases yourself and approve between each:
|
|
128
141
|
|
|
129
|
-
```bash
|
|
130
|
-
dw init # setup wizard / presets
|
|
131
|
-
dw init --solo # zero-config solo dev setup (v1.3)
|
|
132
|
-
dw validate # validate .dw/config/dw.config.yml
|
|
133
|
-
dw doctor # installation health check
|
|
134
|
-
dw upgrade # update toolkit files (override-aware)
|
|
135
|
-
dw upgrade --check # check for updates only
|
|
136
|
-
dw upgrade --dry-run # preview changes
|
|
137
|
-
dw prompt # build a well-structured task prompt (autocomplete + wizard)
|
|
138
|
-
dw prompt --text "..." # non-interactive: structure a description directly
|
|
139
|
-
dw active # regenerate .dw/tasks/ACTIVE.md index (v1.3)
|
|
140
|
-
dw metrics # inspect local telemetry (v1.3, opt-out via DW_NO_TELEMETRY=1)
|
|
141
|
-
dw dashboard # active tasks + ADRs + telemetry summary (v1.3)
|
|
142
|
-
dw claude-vn-fix # patch Claude CLI to fix Vietnamese IME (backup/restore)
|
|
143
142
|
```
|
|
144
|
-
|
|
145
|
-
|
|
143
|
+
/dw:plan → (you review) → /dw:execute → /dw:review → /dw:commit
|
|
144
|
+
```
|
|
146
145
|
|
|
147
146
|
---
|
|
148
147
|
|
|
149
|
-
##
|
|
148
|
+
## Pick your depth
|
|
150
149
|
|
|
151
|
-
|
|
150
|
+
One size never fits all. Set a default, override per task when risk rises.
|
|
152
151
|
|
|
153
152
|
| Depth | Best for | Workflow |
|
|
154
153
|
|-------|----------|----------|
|
|
155
|
-
| `quick` |
|
|
156
|
-
| `standard` |
|
|
157
|
-
| `thorough` |
|
|
158
|
-
|
|
159
|
-
Configured in `.dw/config/dw.config.yml`:
|
|
154
|
+
| `quick` | Hotfix, familiar code, solo | Understand → Execute → Close |
|
|
155
|
+
| `standard` | New features, small teams | Full 6 phases |
|
|
156
|
+
| `thorough` | API / DB / security changes | Full workflow + arch-review + test-plan + debate |
|
|
160
157
|
|
|
161
158
|
```yaml
|
|
159
|
+
# .dw/config/dw.config.yml
|
|
162
160
|
workflow:
|
|
163
161
|
default_depth: "standard"
|
|
164
162
|
```
|
|
165
163
|
|
|
166
164
|
---
|
|
167
165
|
|
|
168
|
-
##
|
|
166
|
+
## Core commands
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
dw init [--solo] # setup wizard / presets (solo · team · enterprise)
|
|
170
|
+
dw doctor # installation health check
|
|
171
|
+
dw upgrade [--check] # update toolkit files (keeps your customizations)
|
|
172
|
+
dw task new <name> # scaffold a v3 task doc
|
|
173
|
+
dw task show [name] # ANSI snapshot of a task
|
|
174
|
+
dw goal status # Goals → Key Results progress
|
|
175
|
+
dw security-scan # AI-native supply-chain guard (OSV + heuristics)
|
|
176
|
+
dw dashboard # active tasks + ADRs + telemetry summary
|
|
177
|
+
dw metrics # local-only telemetry (opt out: DW_NO_TELEMETRY=1)
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Full command reference and skills index live in [`docs/`](docs/).
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
## What gets added to your repo
|
|
169
185
|
|
|
170
186
|
```
|
|
171
187
|
.dw/
|
|
172
188
|
core/ methodology + PILLARS.md
|
|
173
189
|
config/ dw.config.yml (+ optional .local.yml)
|
|
174
|
-
decisions/ ADRs
|
|
175
|
-
tasks/ task docs + ACTIVE.md index
|
|
176
|
-
metrics/ local telemetry (
|
|
177
|
-
.claude/
|
|
178
|
-
CLAUDE.md
|
|
190
|
+
decisions/ ADRs — architectural decision records
|
|
191
|
+
tasks/ task docs + ACTIVE.md index
|
|
192
|
+
metrics/ local telemetry (opt-out)
|
|
193
|
+
.claude/ skills, hooks, agents, rules for your AI IDE
|
|
194
|
+
CLAUDE.md project context the agent reads on every session
|
|
179
195
|
```
|
|
180
196
|
|
|
197
|
+
Everything is plain Markdown + YAML — auditable, diff-able, and yours.
|
|
198
|
+
|
|
181
199
|
---
|
|
182
200
|
|
|
183
|
-
## 5
|
|
201
|
+
## The 5 pillars
|
|
184
202
|
|
|
185
|
-
dw-kit is a **context-first governance layer
|
|
203
|
+
dw-kit is a **context-first governance layer**, not a prescriptive engine. Five verb-based pillars:
|
|
186
204
|
|
|
187
205
|
| Pillar | Purpose | Examples |
|
|
188
206
|
|--------|---------|----------|
|
|
189
|
-
| **Guards** | Safety before action | `
|
|
190
|
-
| **Surfaces** | Make state visible | `ACTIVE.md`, `dw dashboard
|
|
191
|
-
| **Records** | Preserve memory | ADRs
|
|
192
|
-
| **Bridges** | Continuity across sessions
|
|
193
|
-
| **Tunes** | Adapt to team shape | presets
|
|
207
|
+
| **Guards** | Safety before action | `privacy-block`, `pre-commit-gate` |
|
|
208
|
+
| **Surfaces** | Make state visible | `ACTIVE.md`, `dw dashboard` |
|
|
209
|
+
| **Records** | Preserve memory | ADRs, task docs |
|
|
210
|
+
| **Bridges** | Continuity across sessions | auto-handoff, `task.md` |
|
|
211
|
+
| **Tunes** | Adapt to team shape | presets, config flags |
|
|
212
|
+
|
|
213
|
+
**Design principle — the obsolescence test:** every feature must answer *"will this be more valuable when AI is smarter?"* If not, it gets cut.
|
|
214
|
+
|
|
215
|
+
Full spec: [`.dw/core/PILLARS.md`](.dw/core/PILLARS.md).
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
## Requirements
|
|
220
|
+
|
|
221
|
+
- **Node.js ≥ 18**
|
|
222
|
+
- An agentic coding tool with a CLI — [Claude Code](https://claude.ai/code) (full harness) or any other agent / IDE via the generic adapter (methodology layer)
|
|
194
223
|
|
|
195
|
-
|
|
224
|
+
## Links
|
|
196
225
|
|
|
197
|
-
|
|
226
|
+
[Changelog](CHANGELOG.md) · [Releases](https://github.com/dv-workflow/dv-workflow/releases) · [Security policy](SECURITY.md) · [License (Apache-2.0)](LICENSE)
|
|
198
227
|
|
|
199
228
|
---
|
|
200
229
|
|
|
201
|
-
|
|
230
|
+
Made with care by [huygdv](mailto:huygdv19@gmail.com) · [Report an issue](https://github.com/dv-workflow/dv-workflow/issues)
|
package/README.vi.md
ADDED
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
# dw-kit
|
|
2
|
+
|
|
3
|
+
[🇬🇧 English](README.md) · 🇻🇳 **Tiếng Việt**
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/dw-kit)
|
|
6
|
+
[](https://www.npmjs.com/package/dw-kit)
|
|
7
|
+
[](https://nodejs.org)
|
|
8
|
+
[](LICENSE)
|
|
9
|
+
|
|
10
|
+
> **Lớp harness quản trị cho việc dev cùng AI.** Cho con agent code của bạn một quy trình lặp lại được, hàng rào an toàn, và một bộ nhớ sống lâu hơn cửa sổ chat — để nó giao việc đã sẵn-sàng-review thay vì đoán mò đầy tự tin.
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
npm install -g dw-kit && dw init
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Sau đó, ngay trong AI IDE của bạn:
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
/dw:flow làm cái việc bạn thực sự muốn
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Xong. `dw` lo phần còn lại — và **dừng lại chờ bạn duyệt** trước khi viết code.
|
|
23
|
+
|
|
24
|
+
> **Dùng được với bất kỳ AI agent có CLI nào** — Claude Code, Codex, Gemini, Cursor, Windsurf, Copilot. Bản thân CLI `dw` và bộ methodology bằng Markdown là universal: agent của bạn đọc được file và chạy được shell là dùng được dw-kit. Bộ harness *đầy đủ* (hooks, tự động hóa skill, điều phối đa-agent) ở mức hạng-nhất trên **[Claude Code](https://claude.ai/code)**; các agent/IDE còn lại nhận lớp methodology qua generic adapter.
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## Vì sao cần dw-kit?
|
|
29
|
+
|
|
30
|
+
AI agent nhanh nhưng không nhớ gì: quên ngữ cảnh giữa các session, bỏ qua bước lập kế hoạch, và chẳng có khái niệm "khoan đã, để con người ngó qua cái này trước." dw-kit bọc agent của bạn trong một quy trình gọn nhẹ — giữ lại tốc độ, bỏ đi hỗn loạn.
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
Khởi tạo → Khảo sát → Lập KH → Thực thi → Kiểm chứng → Đóng
|
|
34
|
+
│ │ │ │ │ │
|
|
35
|
+
scope đọc thiết kế TDD, quality handoff
|
|
36
|
+
+ docs code (✋ DỪNG 1 commit gates + + lưu
|
|
37
|
+
chờ OK) /subtask review trữ
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
- **✋ Checkpoint của con người** — agent dừng ở bước Lập kế hoạch chờ bạn gật đầu, không tự ý phóng tới.
|
|
41
|
+
- **🛡️ Guards** — hook chặn commit secret, `.env`, và sửa đổi nguy hiểm ngay trước khi chúng xảy ra.
|
|
42
|
+
- **🧠 Bộ nhớ sống qua nhiều session** — quyết định, task docs, ghi chú bàn giao giúp session sau tiếp tục từ con số không.
|
|
43
|
+
- **🌏 Song ngữ trọn vẹn** — UX tiếng Anh + tiếng Việt ngay từ đầu.
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Sinh ra để tự hiệu chỉnh — với bạn trong vòng lặp
|
|
48
|
+
|
|
49
|
+
Hai cơ chế giữ cho agent trung thực chứ không chỉ "bận rộn".
|
|
50
|
+
|
|
51
|
+
**Vòng lặp đeo bám — `/dw:goal`.** Phần lớn agent tối ưu cho *"tôi đã làm xong task."* dw-kit tối ưu cho *kết quả*. Đưa cho nó một Goal với các Key Result đo được, nó chạy một vòng lặp kiểu OODA, **đo lại khoảng cách (gap) sau mỗi vòng**. Khi một cách thất bại, nó **nâng cấp tư duy** — leo lên một bậc thang lập luận — chứ không lặp lại nước đi cũ. Nó chỉ thoát khi KR thực sự chạm target, không phải khi hết hơi. *(ADR-0016)*
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
đo gap → hành động → đo lại ──┐
|
|
55
|
+
▲ │
|
|
56
|
+
└──── kẹt? leo bậc ◀───────┘ leo thang, đừng lặp lại
|
|
57
|
+
chỉ thoát khi Key Result đạt
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Độ tự chủ là một núm vặn: **supervised** (dừng mỗi vòng) → **checkpoint** (`--auto`, dừng ở mỗi KR đạt) → **full** (`--auto=full`, chỉ hard-stop), giới hạn bởi `--max-iter`.
|
|
61
|
+
|
|
62
|
+
**Phản biện đối kháng, rồi tới bạn — `/dw:plan`.** Trước khi một plan tới tay bạn, dw "quay" nó bằng một màn **tranh luận red-team / blue-team**: red tấn công tìm failure mode và giả định ngầm, blue củng cố hoặc nhượng bộ. Bạn nhận được plan *đã được mài sắc* kèm những điểm còn tranh cãi — rồi **việc thực thi dừng lại chờ bạn duyệt.** Phản xạ ấy lặp lại ở bước **Kiểm chứng** (`/dw:review`: tính đúng · bảo mật · convention · độ phủ) và ở mọi commit gate. Agent đề xuất; bạn quyết định và lái.
|
|
63
|
+
|
|
64
|
+
> Debate tùy theo depth — tắt với `quick`, tự kích hoạt khi phát hiện tín hiệu high-stakes ở `standard`, bật mặc định với `thorough`. Override bằng `--debate` / `--no-debate`.
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## Harness: dw quản trị agent của bạn như thế nào
|
|
69
|
+
|
|
70
|
+
dw-kit nằm *bên trên* con agent code như một lớp harness quản trị mỏng — ba tầng bền vững mà nó đọc và ghi trong lúc làm việc:
|
|
71
|
+
|
|
72
|
+
| Tầng | Quản lý | Artifact |
|
|
73
|
+
|------|---------|----------|
|
|
74
|
+
| **Context** | Thứ agent biết, ở mỗi session | `CLAUDE.md`, ADR (`/dw:decision`), ghi chú handoff |
|
|
75
|
+
| **Tasks** | Một nguồn sự thật cho mỗi đơn vị công việc | `task.md` (v3 — lint + schema, chống drift trạng thái), index `ACTIVE.md` |
|
|
76
|
+
| **Goals** | Kết quả ở tầng trên task | `dw goal *`, Key Results, link task ↔ goal |
|
|
77
|
+
|
|
78
|
+
Vì trạng thái này nằm trong **file thuần, không phải cửa sổ chat**, nó sống qua reset session, đổi model, và bàn giao giữa agent với agent hoặc với người — thứ một trợ lý IDE bó hẹp trong một session về cấu trúc không thể sở hữu.
|
|
79
|
+
|
|
80
|
+
### Điều phối đa-agent song song (Agent OS)
|
|
81
|
+
|
|
82
|
+
Một task hiếm khi chỉ cần một agent. **Agent OS** cho phép một orchestrator chia `task.md` thành các đơn vị công việc có ranh giới rồi giao cho *các* agent chạy **song song** — ví dụ Claude Code lo API, Codex lo test, Gemini lo docs, một con người lo phần migration hóc búa:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
dw agent claim payments --subtasks ST-1 --write "src/api/**" --vendor claude --lease 1h
|
|
86
|
+
dw agent claim payments --subtasks ST-2 --write "test/**" --vendor codex
|
|
87
|
+
dw agent conflicts # exit 1 nếu hai claim đè nhau về file hoặc subtask
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Mỗi agent **claim** subtask + phạm vi file trước khi sửa, nên việc song song không giẫm chân nhau. Đây là cơ chế **hợp tác, không cưỡng bức**: trùng lặp bị bắt bởi `dw agent conflicts` và hook `pre-commit-gate`, report của từng agent gộp ngược về một `task.md` duy nhất, và **orchestrator dừng chờ bạn duyệt trước khi push.** *(ADR-0009)*
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## Bắt đầu nhanh
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
# 1. Cài đặt
|
|
98
|
+
npm install -g dw-kit
|
|
99
|
+
|
|
100
|
+
# 2. Thiết lập trong project (wizard, hoặc --solo cho zero-config)
|
|
101
|
+
dw init
|
|
102
|
+
dw init --solo # chế độ vibe-coder: chỉ guards, không task docs
|
|
103
|
+
|
|
104
|
+
# 3. Drive một task từ AI IDE
|
|
105
|
+
/dw:flow thêm tính năng đăng nhập
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Vài skill khác nên biết:
|
|
109
|
+
|
|
110
|
+
```
|
|
111
|
+
/dw:prompt # biến ý tưởng mơ hồ thành prompt sắc, làm được ngay
|
|
112
|
+
/dw:plan # lập kế hoạch + tự phản biện red/blue, rồi dừng chờ duyệt
|
|
113
|
+
/dw:review # tính đúng · bảo mật · convention · độ phủ test
|
|
114
|
+
/dw:decision # ghi lại một quyết định kiến trúc (ADR)
|
|
115
|
+
/dw:goal # drive một Goal tới các Key Result (vòng lặp đeo bám)
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Hướng dẫn nhanh: ship tính năng đầu tiên
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
dw init # một lần: dựng .dw/ + .claude/ trong repo của bạn
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Sau đó, ngay trong Claude Code:
|
|
127
|
+
|
|
128
|
+
```
|
|
129
|
+
/dw:flow thêm chức năng reset mật khẩu qua email
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Diễn biến, theo thứ tự:
|
|
133
|
+
|
|
134
|
+
1. **Khởi tạo + Khảo sát** — dw chốt phạm vi, dựng `task.md`, và đọc code auth của bạn (chưa sửa gì).
|
|
135
|
+
2. **Lập kế hoạch** — đề xuất subtask, tự phản biện red/blue, rồi **dừng.** Bạn trả lời *"go"* hoặc lái lại.
|
|
136
|
+
3. **Thực thi** — làm từng subtask một, TDD, mỗi subtask một commit (hoặc rải subtask ra cho nhiều agent chạy song song qua Agent OS). Secret / `.env` bị chặn ở gate.
|
|
137
|
+
4. **Kiểm chứng** — chạy test của bạn + một lượt `/dw:review` (tính đúng · bảo mật · convention).
|
|
138
|
+
5. **Đóng** — ghi handoff để session ngày mai tiếp tục mà bạn không phải giải thích lại.
|
|
139
|
+
|
|
140
|
+
Thích kiểm soát thủ công? Tự chạy từng phase và duyệt giữa mỗi bước:
|
|
141
|
+
|
|
142
|
+
```
|
|
143
|
+
/dw:plan → (bạn review) → /dw:execute → /dw:review → /dw:commit
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## Chọn độ sâu (depth)
|
|
149
|
+
|
|
150
|
+
Không có cỡ nào vừa cho tất cả. Đặt mặc định, override theo từng task khi rủi ro tăng.
|
|
151
|
+
|
|
152
|
+
| Depth | Hợp với | Quy trình |
|
|
153
|
+
|-------|---------|-----------|
|
|
154
|
+
| `quick` | Hotfix, code quen, solo | Khảo sát → Thực thi → Đóng |
|
|
155
|
+
| `standard` | Tính năng mới, team nhỏ | Đủ 6 phase |
|
|
156
|
+
| `thorough` | Thay đổi API / DB / bảo mật | Đủ quy trình + arch-review + test-plan + debate |
|
|
157
|
+
|
|
158
|
+
```yaml
|
|
159
|
+
# .dw/config/dw.config.yml
|
|
160
|
+
workflow:
|
|
161
|
+
default_depth: "standard"
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## Lệnh cốt lõi
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
dw init [--solo] # wizard thiết lập / preset (solo · team · enterprise)
|
|
170
|
+
dw doctor # kiểm tra sức khỏe cài đặt
|
|
171
|
+
dw upgrade [--check] # cập nhật file toolkit (giữ nguyên tùy biến của bạn)
|
|
172
|
+
dw task new <name> # tạo khung task doc v3
|
|
173
|
+
dw task show [name] # ảnh chụp ANSI của một task
|
|
174
|
+
dw goal status # tiến độ Goals → Key Results
|
|
175
|
+
dw security-scan # supply-chain guard kiểu AI-native (OSV + heuristic)
|
|
176
|
+
dw dashboard # task đang chạy + ADR + tóm tắt telemetry
|
|
177
|
+
dw metrics # telemetry chỉ-cục-bộ (tắt bằng: DW_NO_TELEMETRY=1)
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Tham chiếu lệnh đầy đủ và danh mục skill nằm trong [`docs/`](docs/).
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
## Thứ được thêm vào repo của bạn
|
|
185
|
+
|
|
186
|
+
```
|
|
187
|
+
.dw/
|
|
188
|
+
core/ methodology + PILLARS.md
|
|
189
|
+
config/ dw.config.yml (+ tùy chọn .local.yml)
|
|
190
|
+
decisions/ ADR — bản ghi quyết định kiến trúc
|
|
191
|
+
tasks/ task docs + ACTIVE.md index
|
|
192
|
+
metrics/ telemetry cục bộ (có thể opt-out)
|
|
193
|
+
.claude/ skills, hooks, agents, rules cho AI IDE của bạn
|
|
194
|
+
CLAUDE.md ngữ cảnh project agent đọc mỗi session
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Tất cả là Markdown + YAML thuần — kiểm toán được, diff được, và là của bạn.
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## 5 trụ cột
|
|
202
|
+
|
|
203
|
+
dw-kit là một **lớp quản trị ưu tiên ngữ cảnh** (context-first), không phải cỗ máy áp đặt. Năm trụ cột theo động từ:
|
|
204
|
+
|
|
205
|
+
| Trụ cột | Mục đích | Ví dụ |
|
|
206
|
+
|---------|----------|-------|
|
|
207
|
+
| **Guards** | An toàn trước khi hành động | `privacy-block`, `pre-commit-gate` |
|
|
208
|
+
| **Surfaces** | Làm trạng thái hiện rõ | `ACTIVE.md`, `dw dashboard` |
|
|
209
|
+
| **Records** | Lưu giữ ký ức | ADR, task docs |
|
|
210
|
+
| **Bridges** | Liền mạch qua các session | auto-handoff, `task.md` |
|
|
211
|
+
| **Tunes** | Thích nghi theo hình hài team | preset, config flag |
|
|
212
|
+
|
|
213
|
+
**Nguyên tắc thiết kế — phép thử lỗi thời:** mỗi tính năng phải trả lời được *"liệu nó có giá trị **hơn** khi AI thông minh hơn không?"* Nếu không, nó bị cắt.
|
|
214
|
+
|
|
215
|
+
Đặc tả đầy đủ: [`.dw/core/PILLARS.md`](.dw/core/PILLARS.md).
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
## Yêu cầu
|
|
220
|
+
|
|
221
|
+
- **Node.js ≥ 18**
|
|
222
|
+
- Một công cụ code dạng agentic có CLI — [Claude Code](https://claude.ai/code) (harness đầy đủ) hoặc bất kỳ agent / IDE nào khác qua generic adapter (lớp methodology)
|
|
223
|
+
|
|
224
|
+
## Liên kết
|
|
225
|
+
|
|
226
|
+
[Changelog](CHANGELOG.md) · [Releases](https://github.com/dv-workflow/dv-workflow/releases) · [Chính sách bảo mật](SECURITY.md) · [Giấy phép (Apache-2.0)](LICENSE)
|
|
227
|
+
|
|
228
|
+
---
|
|
229
|
+
|
|
230
|
+
Thực hiện tận tâm bởi [huygdv](mailto:huygdv19@gmail.com) · [Báo lỗi](https://github.com/dv-workflow/dv-workflow/issues)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dw-kit",
|
|
3
|
-
"version": "1.9.
|
|
3
|
+
"version": "1.9.3",
|
|
4
4
|
"description": "AI development workflow toolkit — structured, quality-assured, team-ready. From requirements to dashboard.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -87,6 +87,9 @@
|
|
|
87
87
|
"url": "git+https://github.com/dv-workflow/dv-workflow.git"
|
|
88
88
|
},
|
|
89
89
|
"homepage": "https://github.com/dv-workflow/dv-workflow#readme",
|
|
90
|
+
"bugs": {
|
|
91
|
+
"url": "https://github.com/dv-workflow/dv-workflow/issues"
|
|
92
|
+
},
|
|
90
93
|
"dependencies": {
|
|
91
94
|
"ajv": "^8.18.0",
|
|
92
95
|
"chalk": "^5.6.2",
|