dw-kit 1.2.1 → 1.3.4
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/.claude/hooks/post-write.sh +64 -58
- package/.claude/hooks/pre-commit-gate.sh +96 -90
- package/.claude/hooks/privacy-block.sh +99 -94
- package/.claude/hooks/progress-ping.sh +53 -47
- package/.claude/hooks/safety-guard.sh +60 -54
- package/.claude/hooks/scout-block.sh +88 -82
- package/.claude/hooks/session-init.sh +6 -0
- package/.claude/hooks/stop-check.sh +88 -36
- package/.claude/hooks/telemetry-log.sh +34 -0
- package/.claude/rules/dw.md +138 -0
- package/.claude/settings.json +28 -1
- package/.claude/skills/dw-arch-review/SKILL.md +119 -119
- package/.claude/skills/dw-archive/SKILL.md +81 -81
- package/.claude/skills/dw-commit/SKILL.md +81 -81
- package/.claude/skills/dw-config-init/SKILL.md +91 -91
- package/.claude/skills/dw-config-validate/SKILL.md +75 -75
- package/.claude/skills/dw-dashboard/SKILL.md +209 -209
- package/.claude/skills/dw-debug/SKILL.md +97 -97
- package/.claude/skills/dw-decision/SKILL.md +116 -0
- package/.claude/skills/dw-docs-update/SKILL.md +125 -125
- package/.claude/skills/dw-estimate/SKILL.md +90 -90
- package/.claude/skills/dw-execute/SKILL.md +121 -98
- package/.claude/skills/dw-flow/SKILL.md +274 -274
- package/.claude/skills/dw-handoff/SKILL.md +92 -81
- package/.claude/skills/dw-kit-report/SKILL.md +152 -152
- package/.claude/skills/dw-log-work/SKILL.md +69 -69
- package/.claude/skills/dw-onboard/SKILL.md +201 -201
- package/.claude/skills/dw-plan/SKILL.md +222 -125
- package/.claude/skills/dw-prompt/SKILL.md +62 -62
- package/.claude/skills/dw-requirements/SKILL.md +98 -98
- package/.claude/skills/dw-research/SKILL.md +128 -114
- package/.claude/skills/dw-retroactive/SKILL.md +195 -311
- package/.claude/skills/dw-review/SKILL.md +66 -66
- package/.claude/skills/dw-rollback/SKILL.md +90 -90
- package/.claude/skills/dw-sprint-review/SKILL.md +99 -99
- package/.claude/skills/dw-task-init/SKILL.md +71 -59
- package/.claude/skills/dw-test-plan/SKILL.md +113 -113
- package/.claude/skills/dw-thinking/SKILL.md +70 -70
- package/.claude/skills/dw-upgrade/SKILL.md +72 -72
- package/.dw/core/PILLARS.md +122 -0
- package/.dw/core/ROLES.md +257 -257
- package/.dw/core/templates/v2/spec.md +68 -0
- package/.dw/core/templates/v2/tracking.md +62 -0
- package/.dw/core/v14-evaluation-protocol.md +118 -0
- package/CLAUDE.md +42 -39
- package/MIGRATION-v1.3.md +202 -0
- package/README.md +35 -6
- package/package.json +4 -2
- package/src/cli.mjs +29 -1
- package/src/commands/dashboard.mjs +116 -0
- package/src/commands/doctor.mjs +165 -149
- package/src/commands/init.mjs +339 -332
- package/src/commands/metrics.mjs +185 -0
- package/src/lib/active-index.mjs +87 -0
- package/src/lib/cut-analysis.mjs +240 -0
- package/src/lib/telemetry.mjs +80 -0
- package/.claude/rules/dw-core.md +0 -100
- package/.claude/rules/dw-skills.md +0 -53
- package/.claude/rules/workflow-rules.md +0 -77
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# v1.4 Evaluation Protocol
|
|
2
|
+
|
|
3
|
+
> How to decide what to cut in v1.4, based on telemetry evidence from v1.3 in production.
|
|
4
|
+
> Anchored to [ADR-0001](../decisions/0001-v2-pragmatic-lean.md) Cut Criteria Matrix.
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## Purpose
|
|
9
|
+
|
|
10
|
+
Prove dw-kit can **cut itself** when data says so — validates the "not a framework cage" principle and grows organizational memory via ADRs.
|
|
11
|
+
|
|
12
|
+
## Timeline
|
|
13
|
+
|
|
14
|
+
| Phase | Dates | Activity |
|
|
15
|
+
|-------|-------|----------|
|
|
16
|
+
| Prep | Week 0 | v1.3.0 published + installed on all teams |
|
|
17
|
+
| Collect | Week 1–4 | Normal use; telemetry accumulates locally per dev |
|
|
18
|
+
| Aggregate | End of Week 4 | Each dev exports `.dw/metrics/events.jsonl`, TechLead merges |
|
|
19
|
+
| Analyze | Week 5 (day 1–2) | Run `dw metrics cut-analysis` on merged data |
|
|
20
|
+
| Survey | Week 5 (day 2–3) | Team survey on flagged items (qualitative check) |
|
|
21
|
+
| Decide | Week 5 (day 4) | ADR per confirmed cut |
|
|
22
|
+
| Execute | Week 5 (day 5) | Remove files + settings + write MIGRATION-v1.4.md |
|
|
23
|
+
| Ship | Week 6 | v1.4.0 release |
|
|
24
|
+
|
|
25
|
+
## Evaluation Steps
|
|
26
|
+
|
|
27
|
+
### 1. Collect (end of week 4)
|
|
28
|
+
|
|
29
|
+
Each dev runs:
|
|
30
|
+
```bash
|
|
31
|
+
cp .dw/metrics/events.jsonl ~/dw-metrics-<dev-name>.jsonl
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
TechLead merges into a single evaluation workspace:
|
|
35
|
+
```bash
|
|
36
|
+
mkdir -p ~/dw-v14-eval/.dw/metrics
|
|
37
|
+
cat ~/dw-metrics-*.jsonl > ~/dw-v14-eval/.dw/metrics/events.jsonl
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### 2. Analyze
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
cd ~/dw-v14-eval
|
|
44
|
+
dw metrics cut-analysis --since 2026-05-12
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Output flags skills/hooks qualifying per [ADR-0001 Cut Criteria](../decisions/0001-v2-pragmatic-lean.md):
|
|
48
|
+
|
|
49
|
+
- **Skill**: `uses/week/dev < 5` AND `devs ≥ 5` AND `coverage_days ≥ 21`
|
|
50
|
+
- **Hook**: `avg_latency > 500ms` OR `fires/session > 10`
|
|
51
|
+
|
|
52
|
+
**Caveat**: session-hash proxy undercounts real headcount. If flagged count is borderline → lean keep.
|
|
53
|
+
|
|
54
|
+
### 3. Survey (qualitative gate)
|
|
55
|
+
|
|
56
|
+
For each flagged item, ask the team:
|
|
57
|
+
|
|
58
|
+
1. Did you use `/dw:{name}` in the last 4 weeks?
|
|
59
|
+
2. If removed, would you miss it? (1=no / 5=yes)
|
|
60
|
+
3. Any use case that telemetry wouldn't capture?
|
|
61
|
+
|
|
62
|
+
**Cut only if**: telemetry flags AND <30% of devs answer ≥4 on question 2.
|
|
63
|
+
|
|
64
|
+
### 4. Decide (per cut)
|
|
65
|
+
|
|
66
|
+
For each confirmed cut:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
/dw:decision "Remove {hook-or-skill-name}"
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
ADR must include:
|
|
73
|
+
- Evidence: uses/week/dev, fires/session, latency (paste from `cut-analysis`)
|
|
74
|
+
- Survey result
|
|
75
|
+
- Rollback plan (git revert SHA + how to reinstate)
|
|
76
|
+
- Supersedes line if any prior ADR protected this item
|
|
77
|
+
|
|
78
|
+
### 5. Execute
|
|
79
|
+
|
|
80
|
+
For each cut:
|
|
81
|
+
- Delete `.claude/hooks/{name}.sh` or `.claude/skills/dw-{name}/`
|
|
82
|
+
- Remove entry from `.claude/settings.json` hooks block
|
|
83
|
+
- Remove from `package.json#files` if listed
|
|
84
|
+
- Add row to `MIGRATION-v1.4.md` with "What changed / Why / Rollback"
|
|
85
|
+
|
|
86
|
+
### 6. Ship
|
|
87
|
+
|
|
88
|
+
- Version bump: `1.3.x → 1.4.0`
|
|
89
|
+
- Split commits: one per cut + one for MIGRATION doc
|
|
90
|
+
- `npm publish`
|
|
91
|
+
- Announce to teams with link to MIGRATION-v1.4.md and relevant ADRs
|
|
92
|
+
|
|
93
|
+
## Protected Items (never cut in v1.4)
|
|
94
|
+
|
|
95
|
+
**Critical-path skills** (workflow load-bearing):
|
|
96
|
+
`dw:flow`, `dw:task-init`, `dw:commit`, `dw:handoff`, `dw:execute`, `dw:plan`, `dw:research`, `dw:thinking`, `dw:review`, `dw:debug`, `dw:decision`
|
|
97
|
+
|
|
98
|
+
**Per-project skills** (low cadence is expected):
|
|
99
|
+
`dw:onboard`, `dw:retroactive`, `dw:config-init`, `dw:upgrade`, `dw:rollback`
|
|
100
|
+
|
|
101
|
+
If any flagged by matrix → override is "keep" with a 1-line note in the analysis report.
|
|
102
|
+
|
|
103
|
+
## Failure Modes
|
|
104
|
+
|
|
105
|
+
| Failure | Mitigation |
|
|
106
|
+
|---------|------------|
|
|
107
|
+
| <21 days coverage | Postpone v1.4, extend collection window |
|
|
108
|
+
| <5 unique sessions | Insufficient data; wait or onboard more devs to v1.3 |
|
|
109
|
+
| Data merge error | Each jsonl is self-contained; re-merge from backups |
|
|
110
|
+
| Team disagrees with data | Qualitative survey overrides; document in ADR |
|
|
111
|
+
| Post-cut regret | Execute rollback plan from ADR; issue v1.4.1 patch |
|
|
112
|
+
|
|
113
|
+
## Success Signals
|
|
114
|
+
|
|
115
|
+
- ≥2 ADRs written (shows data-driven cuts happened, not just "feels right")
|
|
116
|
+
- Auto-loaded rules bytes ↓ ≥30% from v1.3 baseline ([baseline.md](../tasks/dw-kit-v2-lean-optimization/baseline.md))
|
|
117
|
+
- Team NPS for dw-kit ≥ v1.3 level (cuts didn't hurt workflow)
|
|
118
|
+
- Zero rollback in first 2 weeks post-v1.4
|
package/CLAUDE.md
CHANGED
|
@@ -1,39 +1,42 @@
|
|
|
1
|
-
# dw-kit (repo)
|
|
2
|
-
|
|
3
|
-
Workflow toolkit codebase.
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
.dw/
|
|
28
|
-
core/ WORKFLOW
|
|
29
|
-
|
|
30
|
-
tasks/ Active
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
-
|
|
38
|
-
-
|
|
39
|
-
-
|
|
1
|
+
# dw-kit (repo)
|
|
2
|
+
|
|
3
|
+
Workflow toolkit codebase. Rules live in `.claude/rules/` (auto-loaded).
|
|
4
|
+
|
|
5
|
+
**v2.0 direction:** Context-First SDLC Governance Layer (5 pillars — see `.dw/core/PILLARS.md`)
|
|
6
|
+
**Current:** v1.4.0-dev · v1.3.0 ready to ship · ADR-0001 active
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Tech Stack
|
|
11
|
+
|
|
12
|
+
- Runtime: Node.js ≥18, ESM (`.mjs`)
|
|
13
|
+
- CLI: `commander` · UI: `enquirer`, `chalk` · Config: `js-yaml`, `ajv`
|
|
14
|
+
- Tests: `node src/smoke-test.mjs`
|
|
15
|
+
|
|
16
|
+
## Repo Structure
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
bin/ CLI entrypoint
|
|
20
|
+
src/
|
|
21
|
+
commands/ CLI subcommands (init, upgrade, dashboard, metrics, ...)
|
|
22
|
+
lib/ Shared utilities (config, telemetry, active-index, ...)
|
|
23
|
+
.claude/
|
|
24
|
+
hooks/ Bash hooks (Guards pillar)
|
|
25
|
+
rules/ dw.md (consolidated) + code-style + commit-standards
|
|
26
|
+
skills/ Slash commands with dw:* namespace
|
|
27
|
+
.dw/
|
|
28
|
+
core/ WORKFLOW · THINKING · QUALITY · ROLES · PILLARS · templates/
|
|
29
|
+
decisions/ ADRs (Records pillar)
|
|
30
|
+
tasks/ Active + archive/ (Bridges pillar — via tracking.md)
|
|
31
|
+
metrics/ Local telemetry (events.jsonl)
|
|
32
|
+
config/ dw.config.yml
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Dev Notes
|
|
36
|
+
|
|
37
|
+
- All source ESM — no CommonJS
|
|
38
|
+
- `TOOLKIT_ROOT` resolved from `import.meta.url` in each command
|
|
39
|
+
- Hooks python3-free (node only — Windows compat)
|
|
40
|
+
- `dw-kit-evolve` + `dw-kit-audit` are maintainer-only — excluded from npm package
|
|
41
|
+
- Published package files declared explicitly in `package.json#files`
|
|
42
|
+
- Telemetry local-only, `DW_NO_TELEMETRY=1` to disable
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
# Migration Guide — dw-kit v1.2.x → v1.3
|
|
2
|
+
|
|
3
|
+
**Current version:** 1.3.4
|
|
4
|
+
**Patch chain:** 1.3.0 → 1.3.1 (task-init + retroactive emit v2) → 1.3.2 (task-doc health metric) → 1.3.3 (writer skills v1/v2 compat + docs cleanup) → 1.3.4 (/dw:plan Quick Debate)
|
|
5
|
+
**Status:** Shipped
|
|
6
|
+
|
|
7
|
+
This guide documents all user-visible changes in v1.3. v1.3 is **fully backward compatible** with v1.2.x — existing projects continue to work. New features are opt-in.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## At a Glance
|
|
12
|
+
|
|
13
|
+
| Area | Change | Impact |
|
|
14
|
+
|------|--------|--------|
|
|
15
|
+
| Task docs | New 2-file format (`spec.md` + `tracking.md`) available; 3-file legacy still works | Opt-in |
|
|
16
|
+
| Decisions layer | New `.dw/decisions/` directory for ADRs | New feature |
|
|
17
|
+
| ACTIVE index | `.dw/tasks/ACTIVE.md` auto-generated | New feature |
|
|
18
|
+
| Telemetry | Local-only metrics in `.dw/metrics/events.jsonl` | Opt-out via `DW_NO_TELEMETRY=1` |
|
|
19
|
+
| Solo preset | `dw init --preset solo` available | New option |
|
|
20
|
+
| Skill naming | `/dw-*` renamed to `/dw:*` (verified working in Claude CLI) | **Breaking** — update custom prompts |
|
|
21
|
+
| `/dw:plan` debate | Quick Debate (red/blue self-critique) integrated — depth-driven | v1.3.4 opt-in for standard, default for thorough |
|
|
22
|
+
| Archive | 8 Done tasks moved to `.dw/tasks/archive/` in dw-kit repo itself | No user impact |
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## New Features (Opt-In)
|
|
27
|
+
|
|
28
|
+
### 1. Task Docs v2 Format
|
|
29
|
+
|
|
30
|
+
**Before (v1.x):** 3 files per task
|
|
31
|
+
```
|
|
32
|
+
.dw/tasks/{name}/
|
|
33
|
+
├── {name}-context.md
|
|
34
|
+
├── {name}-plan.md
|
|
35
|
+
└── {name}-progress.md
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
**Now (v1.3):** Simpler 2-file default
|
|
39
|
+
```
|
|
40
|
+
.dw/tasks/{name}/
|
|
41
|
+
├── spec.md # Intent + plan merged
|
|
42
|
+
└── tracking.md # Progress + handoff
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Templates at `.dw/core/templates/v2/spec.md` and `.dw/core/templates/v2/tracking.md`.
|
|
46
|
+
|
|
47
|
+
**Migration:** Existing 3-file tasks continue to work. For new tasks, copy from new templates.
|
|
48
|
+
|
|
49
|
+
### 2. Decisions Layer (ADRs)
|
|
50
|
+
|
|
51
|
+
New `.dw/decisions/` directory for Architecture Decision Records.
|
|
52
|
+
|
|
53
|
+
- Template: `.dw/decisions/_template.md`
|
|
54
|
+
- Format: YAML frontmatter + TL;DR + Context + Options + Decision + Consequences
|
|
55
|
+
- Example: `.dw/decisions/0001-v2-pragmatic-lean.md` (dw-kit's own v2 direction)
|
|
56
|
+
|
|
57
|
+
**Why:** Capture *why* decisions were made, not just *what*. Complements code and git history.
|
|
58
|
+
|
|
59
|
+
### 3. ACTIVE.md Auto-Index
|
|
60
|
+
|
|
61
|
+
`.dw/tasks/ACTIVE.md` auto-generated with 1 line per active task. Format:
|
|
62
|
+
```
|
|
63
|
+
- `{task-name}` · {status} · {last-updated} · {blockers}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Excludes `.dw/tasks/archive/`. TechLead can `cat .dw/tasks/ACTIVE.md` to see team state at a glance.
|
|
67
|
+
|
|
68
|
+
**New CLI:** `dw active` to regenerate.
|
|
69
|
+
|
|
70
|
+
### 4. Local Telemetry
|
|
71
|
+
|
|
72
|
+
**Privacy-first design:**
|
|
73
|
+
- **Local-only by default.** Zero network calls.
|
|
74
|
+
- Schema: append-only JSONL at `.dw/metrics/events.jsonl`
|
|
75
|
+
- Events logged: skill invocations, hook fires, task lifecycle
|
|
76
|
+
- Inspect: `dw metrics show`
|
|
77
|
+
- Opt-out: `DW_NO_TELEMETRY=1` environment variable
|
|
78
|
+
|
|
79
|
+
**What's collected:** timestamps, event type, skill/hook name, session hash, depth, latency. **Not collected:** file contents, prompts, personal data.
|
|
80
|
+
|
|
81
|
+
**Internal team policy (for 2 internal teams only):** Mandatory for v1.4 cut decisions. Can still set `DW_NO_TELEMETRY=1` on specific machine.
|
|
82
|
+
|
|
83
|
+
### 5. Solo Preset
|
|
84
|
+
|
|
85
|
+
**New:** `dw init --preset solo` — optimized for solo developers / vibe coders.
|
|
86
|
+
|
|
87
|
+
**Enabled by default:** `privacy-block`, `pre-commit-gate` hooks only (safety-critical).
|
|
88
|
+
**Disabled:** Task docs, session-init, scout-block, post-write, progress-ping, telemetry.
|
|
89
|
+
|
|
90
|
+
Target: working setup in <30 seconds, zero friction.
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## Potentially Breaking (Pending Verification)
|
|
95
|
+
|
|
96
|
+
### Skill Naming: `/dw-{name}` → `/dw:{name}`
|
|
97
|
+
|
|
98
|
+
**Status:** Pending Claude Code harness verification.
|
|
99
|
+
|
|
100
|
+
**Rationale:** Colon creates clear namespace separator, matches industry conventions (`git:log`, `npm:run`).
|
|
101
|
+
|
|
102
|
+
**Change:** SKILL.md frontmatter `name:` field. Directory names unchanged (`:` illegal on Windows filesystems).
|
|
103
|
+
|
|
104
|
+
**Before:** `name: dw-thinking` → invoke `/dw-thinking`
|
|
105
|
+
**After:** `name: dw:thinking` → invoke `/dw:thinking`
|
|
106
|
+
|
|
107
|
+
**Mapping table (if applied):**
|
|
108
|
+
|
|
109
|
+
| v1.x | v1.3+ |
|
|
110
|
+
|------|-------|
|
|
111
|
+
| `/dw-flow` | `/dw:flow` |
|
|
112
|
+
| `/dw-task-init` | `/dw:task-init` |
|
|
113
|
+
| `/dw-research` | `/dw:research` |
|
|
114
|
+
| `/dw-plan` | `/dw:plan` |
|
|
115
|
+
| `/dw-execute` | `/dw:execute` |
|
|
116
|
+
| `/dw-commit` | `/dw:commit` |
|
|
117
|
+
| `/dw-handoff` | `/dw:handoff` |
|
|
118
|
+
| `/dw-debug` | `/dw:debug` |
|
|
119
|
+
| `/dw-review` | `/dw:review` |
|
|
120
|
+
| `/dw-thinking` | `/dw:thinking` |
|
|
121
|
+
| `/dw-prompt` | `/dw:prompt` |
|
|
122
|
+
| `/dw-docs-update` | `/dw:docs-update` |
|
|
123
|
+
| `/dw-requirements` | `/dw:requirements` |
|
|
124
|
+
| `/dw-test-plan` | `/dw:test-plan` |
|
|
125
|
+
| `/dw-arch-review` | `/dw:arch-review` |
|
|
126
|
+
| `/dw-dashboard` | `/dw:dashboard` |
|
|
127
|
+
| `/dw-sprint-review` | `/dw:sprint-review` |
|
|
128
|
+
| `/dw-estimate` | `/dw:estimate` |
|
|
129
|
+
| `/dw-log-work` | `/dw:log-work` |
|
|
130
|
+
| `/dw-onboard` | `/dw:onboard` |
|
|
131
|
+
| `/dw-retroactive` | `/dw:retroactive` |
|
|
132
|
+
| `/dw-config-init` | `/dw:config-init` |
|
|
133
|
+
| `/dw-config-validate` | `/dw:config-validate` |
|
|
134
|
+
| `/dw-upgrade` | `/dw:upgrade` |
|
|
135
|
+
| `/dw-rollback` | `/dw:rollback` |
|
|
136
|
+
| `/dw-archive` | `/dw:archive` |
|
|
137
|
+
| `/dw-kit-report` | `/dw:kit-report` |
|
|
138
|
+
| `/dw-kit-evolve` | `/dw:kit-evolve` |
|
|
139
|
+
| `/dw-kit-audit` | `/dw:kit-audit` |
|
|
140
|
+
|
|
141
|
+
See `ADR-0002` for full rationale.
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## Deprecations (No Removal in v1.3)
|
|
146
|
+
|
|
147
|
+
These are marked for removal in v1.4+ based on telemetry evidence:
|
|
148
|
+
|
|
149
|
+
| Feature | Replacement | Removal Target |
|
|
150
|
+
|---------|-------------|----------------|
|
|
151
|
+
| `scout-block.sh` hook | Permission allowlist in settings.json | v1.4 |
|
|
152
|
+
| `post-write.sh` hook | None (low-value reminder) | v1.4 |
|
|
153
|
+
| `progress-ping.sh` hook | `tracking.md` manual + Stop hook | v1.4 |
|
|
154
|
+
| `session-init.sh` hook inject context | `.dw/tasks/ACTIVE.md` auto-loaded | v1.4 |
|
|
155
|
+
| Split rules files (5 files) | Consolidated 1-2 files | v1.4 |
|
|
156
|
+
| 3-file task docs mandatory | 2-file default (legacy still works) | v2.0 |
|
|
157
|
+
| Prescriptive `/dw-research`, `/dw-plan`, `/dw-execute` | Context injector pattern | v2.0 |
|
|
158
|
+
|
|
159
|
+
**Escape hatch:** Set `legacy_features: true` in `.dw/config/dw.config.yml` to keep v1.x behavior through v2.0.
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## Upgrade Steps
|
|
164
|
+
|
|
165
|
+
### Automated
|
|
166
|
+
```bash
|
|
167
|
+
npx dw-kit upgrade
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
This will:
|
|
171
|
+
1. Merge new templates into `.dw/core/templates/v2/`
|
|
172
|
+
2. Create `.dw/decisions/` if missing
|
|
173
|
+
3. Generate initial `.dw/tasks/ACTIVE.md`
|
|
174
|
+
4. Add telemetry module (local-only)
|
|
175
|
+
5. NOT touch existing task docs or skills
|
|
176
|
+
|
|
177
|
+
### Manual Checks After Upgrade
|
|
178
|
+
|
|
179
|
+
- [ ] Verify `.dw/tasks/ACTIVE.md` generated correctly
|
|
180
|
+
- [ ] Read new `ADR-0001` to understand v2.0 direction
|
|
181
|
+
- [ ] Optional: set `DW_NO_TELEMETRY=1` if you want to opt out
|
|
182
|
+
- [ ] Optional: try `dw init --preset solo` for new projects
|
|
183
|
+
|
|
184
|
+
### Rollback
|
|
185
|
+
```bash
|
|
186
|
+
npm install -g dw-kit@1.2.1
|
|
187
|
+
```
|
|
188
|
+
Your existing `.dw/` data remains compatible with v1.2.1.
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## Known Issues
|
|
193
|
+
|
|
194
|
+
- Skill naming (`/dw:*`) pending Claude Code harness verification. If harness rejects `:` in skill `name:` field, rename will be reverted in v1.3.1.
|
|
195
|
+
|
|
196
|
+
---
|
|
197
|
+
|
|
198
|
+
## Feedback
|
|
199
|
+
|
|
200
|
+
- Internal teams: Slack channel `#dw-kit`
|
|
201
|
+
- Open source: https://github.com/dv-workflow/dv-workflow/issues
|
|
202
|
+
- Use `/dw-kit-report` (or `/dw:kit-report` after rename) to file structured feedback.
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
> An AI development workflow toolkit for teams using agentic IDEs (Claude Code, Cursor) — from idea to review-ready commits.
|
|
4
4
|
|
|
5
|
-
**v1.
|
|
5
|
+
**v1.3** · `npm install -g dw-kit` · [Docs](docs/README.md) · [Get started](docs/get-started.md) · [Cheatsheet](docs/cheatsheet.md) · [Migration v1.3](MIGRATION-v1.3.md) · [Changelog](CHANGELOG.md)
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
@@ -61,7 +61,7 @@ dw init
|
|
|
61
61
|
Then in **Claude Code CLI**, run the full workflow:
|
|
62
62
|
|
|
63
63
|
```
|
|
64
|
-
/dw
|
|
64
|
+
/dw:flow your-task-or-anythings
|
|
65
65
|
```
|
|
66
66
|
|
|
67
67
|
---
|
|
@@ -69,18 +69,21 @@ Then in **Claude Code CLI**, run the full workflow:
|
|
|
69
69
|
Discover other skills:
|
|
70
70
|
|
|
71
71
|
```
|
|
72
|
-
/dw
|
|
73
|
-
/dw
|
|
72
|
+
/dw:prompt
|
|
73
|
+
/dw:thinking
|
|
74
|
+
/dw:decision
|
|
74
75
|
...
|
|
75
|
-
|
|
76
76
|
```
|
|
77
77
|
|
|
78
|
+
> **v1.3 note**: Slash commands switched from `/dw-*` to `/dw:*` (namespace convention). See [MIGRATION-v1.3.md](MIGRATION-v1.3.md).
|
|
79
|
+
|
|
78
80
|
---
|
|
79
81
|
|
|
80
82
|
## CLI commands
|
|
81
83
|
|
|
82
84
|
```bash
|
|
83
85
|
dw init # setup wizard / presets
|
|
86
|
+
dw init --solo # zero-config solo dev setup (v1.3)
|
|
84
87
|
dw validate # validate .dw/config/dw.config.yml
|
|
85
88
|
dw doctor # installation health check
|
|
86
89
|
dw upgrade # update toolkit files (override-aware)
|
|
@@ -88,6 +91,9 @@ dw upgrade --check # check for updates only
|
|
|
88
91
|
dw upgrade --dry-run # preview changes
|
|
89
92
|
dw prompt # build a well-structured task prompt (autocomplete + wizard)
|
|
90
93
|
dw prompt --text "..." # non-interactive: structure a description directly
|
|
94
|
+
dw active # regenerate .dw/tasks/ACTIVE.md index (v1.3)
|
|
95
|
+
dw metrics # inspect local telemetry (v1.3, opt-out via DW_NO_TELEMETRY=1)
|
|
96
|
+
dw dashboard # active tasks + ADRs + telemetry summary (v1.3)
|
|
91
97
|
dw claude-vn-fix # patch Claude CLI to fix Vietnamese IME (backup/restore)
|
|
92
98
|
```
|
|
93
99
|
|
|
@@ -117,11 +123,34 @@ workflow:
|
|
|
117
123
|
## What gets added to your repo?
|
|
118
124
|
|
|
119
125
|
```
|
|
120
|
-
.dw/
|
|
126
|
+
.dw/
|
|
127
|
+
core/ methodology + PILLARS.md
|
|
128
|
+
config/ dw.config.yml (+ optional .local.yml)
|
|
129
|
+
decisions/ ADRs (v1.3) — architectural decision records
|
|
130
|
+
tasks/ task docs + ACTIVE.md index (v1.3)
|
|
131
|
+
metrics/ local telemetry (v1.3, opt-out)
|
|
121
132
|
.claude/ # Claude Code: skills, hooks, agents, rules
|
|
122
133
|
CLAUDE.md # project context for the agent
|
|
123
134
|
```
|
|
124
135
|
|
|
125
136
|
---
|
|
126
137
|
|
|
138
|
+
## 5-pillar architecture (v1.3+)
|
|
139
|
+
|
|
140
|
+
dw-kit is a **context-first governance layer** on top of your AI agent — not a prescriptive workflow engine. Five pillars, verb-based:
|
|
141
|
+
|
|
142
|
+
| Pillar | Purpose | Examples |
|
|
143
|
+
|--------|---------|----------|
|
|
144
|
+
| **Guards** | Safety before action | `safety-guard`, `privacy-block`, `pre-commit-gate` |
|
|
145
|
+
| **Surfaces** | Make state visible | `ACTIVE.md`, `dw dashboard`, `project-map.md` |
|
|
146
|
+
| **Records** | Preserve memory | ADRs in `.dw/decisions/`, task docs |
|
|
147
|
+
| **Bridges** | Continuity across sessions/roles | `session-init`, auto-handoff in `tracking.md` |
|
|
148
|
+
| **Tunes** | Adapt to team shape | presets (`solo`, `team`, `enterprise`), config flags |
|
|
149
|
+
|
|
150
|
+
Full spec: [`.dw/core/PILLARS.md`](.dw/core/PILLARS.md)
|
|
151
|
+
|
|
152
|
+
**Design principle — obsolescence test**: Every feature must answer "will this be *more* valuable when AI is smarter?" If no → cut or defer.
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
127
156
|
Maintainer: [huygdv](mailto:huygdv19@gmail.com)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dw-kit",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.3.4",
|
|
4
4
|
"description": "AI development workflow toolkit — structured, quality-assured, team-ready. From requirements to dashboard.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -24,6 +24,7 @@
|
|
|
24
24
|
".claude/skills/dw-config-validate/",
|
|
25
25
|
".claude/skills/dw-dashboard/",
|
|
26
26
|
".claude/skills/dw-debug/",
|
|
27
|
+
".claude/skills/dw-decision/",
|
|
27
28
|
".claude/skills/dw-docs-update/",
|
|
28
29
|
".claude/skills/dw-estimate/",
|
|
29
30
|
".claude/skills/dw-execute/",
|
|
@@ -46,7 +47,8 @@
|
|
|
46
47
|
".claude/skills/dw-upgrade/",
|
|
47
48
|
".claude/templates/",
|
|
48
49
|
".claude/settings.json",
|
|
49
|
-
"CLAUDE.md"
|
|
50
|
+
"CLAUDE.md",
|
|
51
|
+
"MIGRATION-v1.3.md"
|
|
50
52
|
],
|
|
51
53
|
"engines": {
|
|
52
54
|
"node": ">=18"
|
package/src/cli.mjs
CHANGED
|
@@ -28,7 +28,8 @@ export function run(argv) {
|
|
|
28
28
|
program
|
|
29
29
|
.command('init')
|
|
30
30
|
.description('Setup dw-kit in current project (interactive wizard)')
|
|
31
|
-
.option('-p, --preset <name>', 'Use preset: solo-quick | small-team | enterprise')
|
|
31
|
+
.option('-p, --preset <name>', 'Use preset: solo | solo-quick | small-team | team | enterprise')
|
|
32
|
+
.option('--solo', 'Shortcut for --preset solo (zero-config setup)')
|
|
32
33
|
.option('-a, --adapter <platform>', 'Target platform: claude-cli | cursor | generic', 'claude-cli')
|
|
33
34
|
.option('-s, --silent', 'Non-interactive mode (reads DW_NAME, DW_DEPTH, DW_ROLES, DW_LANG env vars)')
|
|
34
35
|
.action(async (opts) => {
|
|
@@ -73,6 +74,33 @@ export function run(argv) {
|
|
|
73
74
|
await promptCommand(opts);
|
|
74
75
|
});
|
|
75
76
|
|
|
77
|
+
program
|
|
78
|
+
.command('metrics [sub]')
|
|
79
|
+
.description('Inspect local telemetry (show | cut-analysis | clear). Default: show')
|
|
80
|
+
.option('--since <date>', 'Filter events since ISO date (YYYY-MM-DD)')
|
|
81
|
+
.option('--skill <name>', 'Filter by skill name')
|
|
82
|
+
.action(async (sub, opts) => {
|
|
83
|
+
const { metricsCommand } = await import('./commands/metrics.mjs');
|
|
84
|
+
await metricsCommand({ sub, ...opts });
|
|
85
|
+
});
|
|
86
|
+
|
|
87
|
+
program
|
|
88
|
+
.command('active')
|
|
89
|
+
.description('Regenerate .dw/tasks/ACTIVE.md index')
|
|
90
|
+
.action(async () => {
|
|
91
|
+
const { writeActiveIndex } = await import('./lib/active-index.mjs');
|
|
92
|
+
const target = writeActiveIndex();
|
|
93
|
+
console.log(chalk.green('✓') + ` Wrote ${target}`);
|
|
94
|
+
});
|
|
95
|
+
|
|
96
|
+
program
|
|
97
|
+
.command('dashboard')
|
|
98
|
+
.description('Show team dashboard — active tasks, ADRs, telemetry summary, health')
|
|
99
|
+
.action(async (opts) => {
|
|
100
|
+
const { dashboardCommand } = await import('./commands/dashboard.mjs');
|
|
101
|
+
await dashboardCommand(opts);
|
|
102
|
+
});
|
|
103
|
+
|
|
76
104
|
program
|
|
77
105
|
.command('claude-vn-fix')
|
|
78
106
|
.description('Patch Claude CLI to fix Vietnamese IME (local, with backup/restore)')
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
import { readEvents, summarize } from '../lib/telemetry.mjs';
|
|
2
|
+
import { generateActiveIndex } from '../lib/active-index.mjs';
|
|
3
|
+
import { existsSync, readdirSync, readFileSync } from 'node:fs';
|
|
4
|
+
import { join } from 'node:path';
|
|
5
|
+
import { banner, log, info, warn, ok } from '../lib/ui.mjs';
|
|
6
|
+
import chalk from 'chalk';
|
|
7
|
+
|
|
8
|
+
export async function dashboardCommand(opts) {
|
|
9
|
+
banner('dw-kit Dashboard');
|
|
10
|
+
|
|
11
|
+
const rootDir = process.cwd();
|
|
12
|
+
|
|
13
|
+
log(chalk.bold('📋 Active Tasks'));
|
|
14
|
+
log('');
|
|
15
|
+
const activeContent = generateActiveIndex(rootDir);
|
|
16
|
+
const taskLines = activeContent.split('\n').filter((l) => l.startsWith('- `'));
|
|
17
|
+
if (taskLines.length === 0) {
|
|
18
|
+
log(' (none)');
|
|
19
|
+
} else {
|
|
20
|
+
taskLines.forEach((l) => log(' ' + l));
|
|
21
|
+
}
|
|
22
|
+
log('');
|
|
23
|
+
|
|
24
|
+
log(chalk.bold('🗂️ Decisions (ADRs)'));
|
|
25
|
+
log('');
|
|
26
|
+
const decisionsDir = join(rootDir, '.dw/decisions');
|
|
27
|
+
if (existsSync(decisionsDir)) {
|
|
28
|
+
const adrs = readdirSync(decisionsDir).filter((f) => /^\d{4}-.*\.md$/.test(f));
|
|
29
|
+
if (adrs.length === 0) {
|
|
30
|
+
log(' (none)');
|
|
31
|
+
} else {
|
|
32
|
+
adrs.sort().forEach((f) => {
|
|
33
|
+
try {
|
|
34
|
+
const content = readFileSync(join(decisionsDir, f), 'utf8');
|
|
35
|
+
const statusMatch = content.match(/^status:\s*(.+)$/m);
|
|
36
|
+
const titleMatch = content.match(/^title:\s*(.+)$/m);
|
|
37
|
+
const status = statusMatch ? statusMatch[1].trim() : 'unknown';
|
|
38
|
+
const title = titleMatch ? titleMatch[1].trim() : f;
|
|
39
|
+
const statusColor =
|
|
40
|
+
status === 'Accepted'
|
|
41
|
+
? chalk.green
|
|
42
|
+
: status.startsWith('Proposed')
|
|
43
|
+
? chalk.yellow
|
|
44
|
+
: status === 'Deprecated'
|
|
45
|
+
? chalk.gray
|
|
46
|
+
: chalk.white;
|
|
47
|
+
log(` ${chalk.cyan(f.replace(/\.md$/, ''))} · ${statusColor(status)}`);
|
|
48
|
+
log(` ${chalk.dim(title)}`);
|
|
49
|
+
} catch {
|
|
50
|
+
log(` ${f} · (unreadable)`);
|
|
51
|
+
}
|
|
52
|
+
});
|
|
53
|
+
}
|
|
54
|
+
} else {
|
|
55
|
+
log(' (decisions layer not initialized — run `/dw:decision` to create first ADR)');
|
|
56
|
+
}
|
|
57
|
+
log('');
|
|
58
|
+
|
|
59
|
+
log(chalk.bold('📊 Telemetry Summary'));
|
|
60
|
+
log('');
|
|
61
|
+
if (process.env.DW_NO_TELEMETRY === '1') {
|
|
62
|
+
warn('Telemetry disabled (DW_NO_TELEMETRY=1)');
|
|
63
|
+
} else {
|
|
64
|
+
const events = readEvents(rootDir);
|
|
65
|
+
if (events.length === 0) {
|
|
66
|
+
log(' No events yet. Use dw-kit normally to populate.');
|
|
67
|
+
} else {
|
|
68
|
+
const s = summarize(events);
|
|
69
|
+
log(` Total events: ${s.totalEvents}`);
|
|
70
|
+
if (s.dateRange) {
|
|
71
|
+
log(` Range: ${s.dateRange.from.slice(0, 10)} → ${s.dateRange.to.slice(0, 10)}`);
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
const topSkills = Object.entries(s.bySkill)
|
|
75
|
+
.sort((a, b) => b[1] - a[1])
|
|
76
|
+
.slice(0, 5);
|
|
77
|
+
if (topSkills.length > 0) {
|
|
78
|
+
log('');
|
|
79
|
+
log(chalk.dim(' Top 5 skills:'));
|
|
80
|
+
topSkills.forEach(([n, c]) => log(` ${c.toString().padStart(4)}× /${n}`));
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
const topHooks = Object.entries(s.byHook)
|
|
84
|
+
.sort((a, b) => b[1] - a[1])
|
|
85
|
+
.slice(0, 5);
|
|
86
|
+
if (topHooks.length > 0) {
|
|
87
|
+
log('');
|
|
88
|
+
log(chalk.dim(' Top 5 hooks:'));
|
|
89
|
+
topHooks.forEach(([n, c]) => log(` ${c.toString().padStart(4)}× ${n}`));
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
log('');
|
|
94
|
+
|
|
95
|
+
log(chalk.bold('🔧 Health'));
|
|
96
|
+
log('');
|
|
97
|
+
const checks = [
|
|
98
|
+
{ path: '.dw/config/dw.config.yml', label: 'Config' },
|
|
99
|
+
{ path: '.dw/tasks/ACTIVE.md', label: 'ACTIVE index' },
|
|
100
|
+
{ path: '.dw/decisions', label: 'Decisions layer' },
|
|
101
|
+
{ path: '.claude/hooks/privacy-block.sh', label: 'Privacy guard' },
|
|
102
|
+
{ path: '.claude/hooks/pre-commit-gate.sh', label: 'Commit gate' },
|
|
103
|
+
];
|
|
104
|
+
|
|
105
|
+
for (const c of checks) {
|
|
106
|
+
const full = join(rootDir, c.path);
|
|
107
|
+
if (existsSync(full)) {
|
|
108
|
+
ok(`${c.label}: ${c.path}`);
|
|
109
|
+
} else {
|
|
110
|
+
warn(`${c.label}: missing (${c.path})`);
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
log('');
|
|
115
|
+
info('Run `dw metrics show` for detailed telemetry, `dw doctor` for full health check.');
|
|
116
|
+
}
|