WHW organizes work around purpose, decisions, SQL state and evidence. Keep the delivery contract in your repository, resume after interruptions, and review what changed with artifacts you can rerun.
0.2.0 is published on npm and GitHub. This repository's documentation evolves independently of that immutable package. The 0.2.1 documentation patch packages this bilingual adoption journey; the quick start remains pinned to the verified 0.2.0 baseline.
Value · Audience · Quick start · Architecture · Delivery loop · Continuity · Compatibility · Evidence and limits · Documentation · Roadmap · Contributing
| Situation | WHW practice | Reviewable artifact |
|---|---|---|
| Resume after an interruption | Revalidate Git, queue and gates with resume |
Baseline, SQL status and gate checkpoints |
| Change tools | Carry the contract with handoff and canonical AGENTS.md |
Migration document and repository files |
| Explain a decision | Link a wave to an ADR and WHY | Versioned decision record |
| Review delivery | Require evidence and GO/NO_GO checks | Commits, test commands and PRs |
Durable context, governance and verification are the positioning priorities. September 2026 research and market context informs these priorities; it does not establish WHW performance results.
For developers and technical leaders who want explicit scope, continuity and evidence while using humans or coding agents. Start with one small wave. WHW supplies a process CLI and file contracts; your team supplies the code, project-specific checks, reviewers and approval policy.
Requires Node.js ≥22.13, npm and Git. WHW has zero runtime dependencies;
npx still downloads the package on first use. Review generated files before
adopting them in an existing repository; this example starts with an empty one.
mkdir whw-demo
cd whw-demo
git init
npx @fabioeloi/whw@0.2.0 init --tools claude,cursor,codex,copilot,gemini
npx @fabioeloi/whw@0.2.0 doctor
npx @fabioeloi/whw@0.2.0 program new adoption --waves 1
npx @fabioeloi/whw@0.2.0 wave new first-change --adr 0001In this new repository, the generated program ADR is 0001 and the wave is
001. Existing repositories allocate the next available numbers: use the
actual generated identifiers. Edit WHY.md, the program charter (scope,
exclusions, wave map and close criteria), and docs/plan.md before executing.
npx @fabioeloi/whw@0.2.0 sync --all
npx @fabioeloi/whw@0.2.0 queue
npx @fabioeloi/whw@0.2.0 claim wave001-AFinish A's planning artifacts and review them before recording completion:
npx @fabioeloi/whw@0.2.0 gate run --tier pr
npx @fabioeloi/whw@0.2.0 done \
wave001-A --evidence "planning/wave-001-first-change.todos.sql; docs/adr/0001-program-adoption.md; npx @fabioeloi/whw@0.2.0 gate run --tier pr"
npx @fabioeloi/whw@0.2.0 statusThis completes A only. B–E remain pending. Repeat the contract per letter;
close requires A–D done, the ADR addendum and green sync gates. Never close
immediately after A. See waves and the
worked example.
The installed package runs through npx @fabioeloi/whw@0.2.0 (or whw after
explicit installation). init scaffolds process files; it does not copy
bin/ or src/. Only inside a WHW source checkout use node ./bin/whw.js.
flowchart LR
WHY["WHY.md: purpose"] --> ADR["ADR: decisions"]
ADR --> W["Wave A–E: scope"]
W --> SQL["SQL: execution state"]
SQL --> EX["Human or agent execution"]
EX --> EV["Tests, gates, commits and PRs"]
EV --> ADR
planning/*.todos.sql is versioned input. sync loads local SQLite state
in .whw/state.db; the dependency-aware queue drives execution. The database
is ignored by Git: retain evidence in versioned artifacts and regenerate
state through WHW commands. File handoffs preserve process context, not a
model's hidden memory or private chat history.
| Letter | Responsibility | Delivery |
|---|---|---|
| A | Plan | Charter, SQL seeds, dependencies and acceptance |
| B | Build | Scoped implementation |
| C | Verify | Independent checks and rerunnable evidence |
| D | Decide | ADR addendum with outcome and limits |
| E | Close | Canonical SQL close, metrics and integration |
flowchart TD
R["resume / sync / queue"] --> C["claim"]
C --> X["Human or agent work"]
X --> Q{"Blocked?"}
Q -->|yes| B["block --reason"]
B --> R
Q -->|no| G["Tests and PR/ops gates"]
G --> V{"GO?"}
V -->|NO_GO| X
V -->|GO| E["done --evidence"]
E --> H["Human review and approval"]
H --> M["Merge; main green"]
M --> N{"A–D integrated?"}
N -->|no| R
N -->|yes| CL["close"]
A wave is terminal only when E merges. PR gates cover planning, ADR linkage, wave sync, README sync, adapter parity and secret scanning. Ops gates add program inventory, evidence quality, release readiness and maintenance audit. They check defined contracts; passing them does not certify software security or every documentation link.
Roles (planner, builder, evaluator, closer, autonomous-engineer)
are Markdown instructions. Evaluation Phase A runs configured deterministic
checks; Phase B ingests rubric scores. These mechanisms need project-specific
acceptance and independent review; a runner exit zero alone is insufficient.
npx @fabioeloi/whw@0.2.0 resume
npx @fabioeloi/whw@0.2.0 handoff --from codex --to clauderesume checks the Git baseline, syncs SQL, reports the queue and runs PR
gates; it does not auto-claim. handoff records a baseline, queue snapshot,
gate results and next action. Review that package before changing tools.
Keep private transcripts and credentials out of public artifacts.
See continuity.
| Layer | Available contract | What this establishes |
|---|---|---|
| Managed adapters | Claude, Cursor, Copilot, Gemini, Windsurf | Generated pointers to canonical AGENTS.md |
| Native/file readers | Codex, OpenCode; Aider with --read AGENTS.md |
Instruction-file integration; see adapter reference |
| Configurable runners | External CLI command via whw run; escalation can end with a human |
Requires separately installed/authenticated CLI; no default runner is configured here |
| Verified scenarios | Consumer init, SQL loop, handoff/resume; supervised Codex run | Specific proof boundaries below, not universal model/tool certification |
WHW requires no model API or vendor SDK. Tool instruction support and runner
availability are separate. doctor discovers executables without proving
login, entitlement or backend health. See config.
| Capability or practice | Public evidence | Limit |
|---|---|---|
| Consumer adoption and continuity | Consumer verification, e2e test | Local replay; no model conversation migration or Windows certification |
| Real runner | Codex runner proof | Operator-assisted: sandbox blocked Git commit; operator finalized Git/SQL; requested model metadata is not backend attestation |
| Secure release | Staged release verification, workflow | Observed dispatch recovery; future tag-triggered publication is not proved by that run |
| Shift-left comparison | Benchmark, ADR 0018 | Simulated ledger and published weights; not a field productivity or financial result |
This repository published 0.2.0 with GitHub Actions OIDC, staging-only npm permissions and human passkey approval. The recovery attestation identifies the workflow's main commit, not the tag checkout; a separate byte comparison established the tag's package contents. These are repository practices, not automatic guarantees for repositories adopting WHW. See security.
No measured WHW benchmark gain, financial saving, complete autonomy or
enterprise compliance claim is made. npm run benchmark compares the default
classic profile with the opt-in shift-left profile under a published cost
model; that report is not a measured productivity or financial gain. Custom
shell checks and runners execute code you configure: review them before use.
Start at the documentation index or the complete pt-BR adoption journey.
| Need | Reference |
|---|---|
| Purpose and principles | WHY, manifesto, principles |
| Process | Waves, gates, risk review, evidence |
| Technical reference | CLI, schema, adapters |
| Decisions and current work | ADRs, plan, canonical agent contract |
| State | Scope |
|---|---|
| Published 0.1.0 / 0.1.1 | Core CLI, SQL, gates, roles and initial distribution |
| Published 0.2.0 | Runner discovery, continuity verification, run metrics and consumer proof; changelog |
| 0.2.1 documentation patch | Distributes wave 018 bilingual adoption documentation; staging requires human approval |
| Proposals requiring new charters | Runner postcondition hardening, stronger context persistence, additional platform proofs; no delivery date promised |
Historical ADRs remain in English. See positioning for dated sources and ADR 0016 for this documentation scope.
Follow CONTRIBUTING.md: sync, queue, claim one task, implement a wave letter, record evidence and pass gates before merge. Report vulnerabilities privately under SECURITY.md. Every milestone ends with Status / Evidence / Next step.
MIT © 2026 Fabio Eloi. The WHY/HOW/WHAT ordering draws inspiration from Simon Sinek's Start With Why (2009), without affiliation or endorsement; see acknowledgments.