dw-kit

🇬🇧 English · 🇻🇳 Tiếng Việt

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.

npm install -g dw-kit && dw init

Then, inside your AI IDE:

/dw:flow build the thing you actually want

That's it. dw drives the rest — and stops for your approval before it writes code.

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; a generic adapter gives everything else the methodology layer.

Why dw-kit?

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.

   Initialize → Understand → Plan → Execute → Verify → Close
        │            │         │        │        │       │
      scope       survey    design    TDD,    quality  handoff
      + docs       code    (✋ STOP   1 commit  gates +  notes +
                          for OK)  /subtask  review   archive

• ✋ Human checkpoints — the agent pauses at Plan for your sign-off, never silently barrels ahead.
• 🛡️ Guards — hooks block commits of secrets, .env, and unsafe edits before they happen.
• 🧠 Memory that survives sessions — decisions, task docs, and handoff notes let the next session resume cold.
• 🌏 Fully bilingual — English + Vietnamese UX out of the box.

Built to self-correct — with you in the loop

Two mechanisms keep the agent honest instead of merely busy.

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)

   measure gap → act → re-measure ──┐
        ▲                           │
        └──── stuck? escalate ◀──────┘   climb the ladder, don't repeat
   exit only when the Key Result is met

Autonomy is a dial: supervised (stop every loop) → checkpoint (--auto, stop at each KR) → full (--auto=full, hard-stops only), bounded by --max-iter.

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.

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.

The harness: how dw governs your agent

dw-kit sits above your coding agent as a thin governance harness — three durable layers it reads and writes as it works:

| Layer | Manages | Artifacts | |-------|---------|-----------| | Context | What the agent knows, every session | CLAUDE.md, ADRs (/dw:decision), handoff notes | | Tasks | One source of truth per unit of work | task.md (v3 — lint + schema, status drift-proof), ACTIVE.md index | | Goals | Outcomes above the task line | dw goal *, Key Results, task ↔ goal links |

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.

Parallel multi-agent orchestration (Agent OS)

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:

dw agent claim payments --subtasks ST-1 --write "src/api/**" --vendor claude --lease 1h
dw agent claim payments --subtasks ST-2 --write "test/**"    --vendor codex
dw agent conflicts        # exit 1 if two claims overlap on files or subtasks

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)

Quick start

# 1. Install
npm install -g dw-kit

# 2. Set up in your project (wizard, or --solo for zero-config)
dw init
dw init --solo        # vibe-coder mode: guards only, no task docs

# 3. Drive a task from your AI IDE
/dw:flow add user authentication

Other skills worth knowing:

/dw:prompt      # turn a vague idea into a sharp, actionable prompt
/dw:plan        # plan + red/blue self-critique, then stop for approval
/dw:review      # correctness · security · conventions · coverage
/dw:decision    # capture an architectural decision (ADR)
/dw:goal        # drive a Goal toward its Key Results (pursuit loop)

Tutorial: ship your first feature

dw init                          # one-time: scaffold .dw/ + .claude/ in your repo

Then, inside Claude Code:

/dw:flow add password reset via email

What unfolds, in order:

1. Initialize + Understand — dw scopes the task, scaffolds a task.md, and surveys your auth code (no edits yet).
2. Plan — proposes subtasks, self-critiques red/blue, then stops. You reply "go" or steer.
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.
4. Verify — runs your tests + a /dw:review pass (correctness · security · conventions).
5. Close — writes handoff notes so tomorrow's session resumes without you re-explaining.

Prefer manual control? Run the phases yourself and approve between each:

/dw:plan  →  (you review)  →  /dw:execute  →  /dw:review  →  /dw:commit

Pick your depth

One size never fits all. Set a default, override per task when risk rises.

| Depth | Best for | Workflow | |-------|----------|----------| | quick | Hotfix, familiar code, solo | Understand → Execute → Close | | standard | New features, small teams | Full 6 phases | | thorough | API / DB / security changes | Full workflow + arch-review + test-plan + debate |

# .dw/config/dw.config.yml
workflow:
  default_depth: "standard"

Core commands

dw init [--solo]        # setup wizard / presets (solo · team · enterprise)
dw doctor               # installation health check
dw upgrade [--check]    # update toolkit files (keeps your customizations)
dw task new <name>      # scaffold a v3 task doc
dw task show [name]     # ANSI snapshot of a task
dw goal status          # Goals → Key Results progress
dw trust status         # Trust Mode — opt-in gate auto-approval (ADR-0022, off by default)
dw autopilot preflight  # gate an unattended overnight run (ADR-0023); + `dw overnight digest`
dw security-scan        # AI-native supply-chain guard (OSV + heuristics)
dw dashboard            # active tasks + ADRs + telemetry summary
dw metrics              # local-only telemetry (opt out: DW_NO_TELEMETRY=1)

Full command reference and skills index live in docs/.

What gets added to your repo

.dw/
  core/       methodology + PILLARS.md
  config/     dw.config.yml (+ optional .local.yml)
  decisions/  ADRs — architectural decision records
  tasks/      task docs + ACTIVE.md index
  metrics/    local telemetry (opt-out)
.claude/      skills, hooks, agents, rules for your AI IDE
CLAUDE.md     project context the agent reads on every session

Everything is plain Markdown + YAML — auditable, diff-able, and yours.

The 5 pillars

dw-kit is a context-first governance layer, not a prescriptive engine. Five verb-based pillars:

| Pillar | Purpose | Examples | |--------|---------|----------| | Guards | Safety before action | privacy-block, pre-commit-gate | | Surfaces | Make state visible | ACTIVE.md, dw dashboard | | Records | Preserve memory | ADRs, task docs | | Bridges | Continuity across sessions | auto-handoff, task.md | | Tunes | Adapt to team shape | presets, config flags |

Design principle — the obsolescence test: every feature must answer "will this be more valuable when AI is smarter?" If not, it gets cut.

Full spec: .dw/core/PILLARS.md.

Requirements

• Node.js ≥ 18
• An agentic coding tool with a CLI — Claude Code (full harness) or any other agent / IDE via the generic adapter (methodology layer)

Links

Changelog · Releases · Security policy · License (Apache-2.0)

Made with care by huygdv · Report an issue