DWP specification

Version 4.0.0. Status: Stable. This document is the normative specification for the Deep Work Plan (DWP) methodology. The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119.

Additive in 2.4.0, no breaking changes. (1) The Touched Surface section — the contract between what a task changes and what must be validated, with gate selection by risk class (isolated / seam / shared-core / unknown); (2) full validation becomes a final-state requirement run in the plan’s single mandatory Final Review, with explicit evidence-reuse rules; (3) task-local skills decisions move into the owning task, and the Executive Report becomes optional, on request; (4) a mode-aware create flow — trust mode materializes directly while keeping the analysis and quality checks; (5) Lite-first plan materialization — guided create produces a directly executable Lite plan instead of a non-executable draft, promotable to a Full plan at any point (see Lite plans); and (6) an explicit compatibility matrix: plans and repositories from earlier versions remain conformant.

Standard 4.0.0. The version jump aligns the standard’s number with the product line — 2.x is historical and there is no 3.x standard — and changes no requirement from 2.4.0. Plans and repositories from earlier versions remain conformant.

Definition

A Deep Work Plan is a structured, markdown-only artifact that describes a complex engineering task decomposed into sequential, reviewable units of work, designed to be created, executed, and maintained by AI coding agents working autonomously.

DWP is spec-driven: the plan is the specification, and agents MUST execute against its explicit acceptance criteria and validation gates rather than improvising. The specification — not a chat transcript — is the durable source of truth, so the work is verifiable and resumable across sessions and agents. It is also harness engineering made portable: the context, control loop, guardrails, and resumable state that make an agent reliable are installed into the repository itself as plain markdown, so any conformant agent MAY pilot the repository without a tool-specific framework.

Create flow — single step, mode-aware

The create flow gathers the objective, context, constraints, and task outline once, performs its requirements analysis (scope, dependency ordering between tasks, validation selection from the Touched Surface, proportional-rigor tier), and then materializes according to the mode the developer chose:

• Guided mode (default). The flow materializes a Lite plan directly — a compact, already-executable proposal with inline {#task-N} task records, reviewable in one pass — and asks the developer to retain it as Lite, promote it to a Full plan, request edits, or stop. No intermediate non-executable draft is produced.
• Trust mode (trust / auto). The flow materializes the chosen representation (Lite, or Lite followed immediately by promotion to Full) directly, with no review step — the developer waived it. The requirements analysis, dependency ordering, and a plan-quality check still run: trust waives the review, not the analysis. A trust-mode plan is recorded as pre-approved for unattended execution.

Both modes decide the plan’s format (Lite or Full) as part of the same requirements analysis, never as an afterthought. See Lite plans for the full representation, creation-and-selection, and promotion lifecycle.

Plan structure

A plan MUST be a directory under .dwp/plans/ named PLAN_<slug>/, in one of two representations:

• Full. The directory MUST contain README.md (plan overview, goal, task table, and status), one file per task named <n>.task_<slug>.md, and PROGRESS.md (a running log of execution).
• Lite. Compact, fully executable task records live inline in README.md behind stable {#task-N} anchors instead of separate task files — each record still carries a goal, Touched Surface, acceptance criteria, validation, and completion log. PROGRESS.md is still REQUIRED. A Lite plan MAY be promoted to Full at any point. See Lite plans for the full lifecycle rather than duplicating it here.

A plan MAY additionally carry the machine-readable state layer: manifest.json (static identity, written once at materialization) and state.json (live per-task execution state). The state layer is RECOMMENDED for new plans and REQUIRED for unattended execution and for agent workspaces without git. See Plan state.

Task anatomy

Task file

1. 01 Title
2. 02 Context
3. 03 Read Before Starting
4. 04 Goal
5. 05 Touched Surface
6. 06 Instructions
7. 07 Acceptance Criteria
8. 08 Outputs
9. 09 Validation
10. 10 Execution Checklist + Completion & Log

Every task file follows the ten normative sections rendered above, in the order defined by the installed skill.

The Touched Surface

The Touched Surface is the contract between what a task changes and what must be validated. It exists so that validation is selected by effect, not by habit, and so a later reader can see why a gate was chosen. A behavior-changing task MUST record:

• Planned surface — the paths, modules, packages, or configuration the task intends to change, written before editing.
• Actual surface — the reconciled list after editing, taken from the real diff. The agent MUST reconcile planned and actual surfaces before selecting the gate.
• Affected consumers — modules, packages, or services that depend on the actual surface, as far as the repository’s documented mapping can establish. Where it cannot, the entry MUST say so.
• Risk class — one of: isolated (confined to one module and its tests); seam (alters a contract, persistence, routing, serialization, auth, or framework wiring between collaborators); shared/core (imported widely, or a dependency, migration, build/test config, schema, or toolchain change); unknown (the mapping is missing, stale, or unverified).
• Test mapping used — which documented mapping or tool produced the selection.
• Selected gate and reason — the exact commands and why they cover the actual surface.

Configuration files, schemas, dependency manifests, templates, fixtures, migrations, and agent instruction files can change behavior and MUST be classified by their effect, never by file extension. A task that changes only prose, comments, or research artifacts MAY declare the surface not applicable and still runs the repository’s non-runtime checks.

The Delta section (brownfield changes)

Most real work modifies existing behavior rather than creating new behavior. A task that changes how an existing system behaves SHOULD carry a Delta section describing the change as an explicit before/after contract, using three list headings:

• ADDED — behavior that exists after the task and did not before.
• MODIFIED — behavior that exists in both, stated as was: … → now: ….
• REMOVED — behavior that existed before and is intentionally gone after.

Each entry MUST be observable behavior — an endpoint’s response, a CLI flag, a UI state, a default value — not an implementation detail. The Delta section is the reviewer’s diff at the behavior level: acceptance criteria verify the ADDED/MODIFIED entries, and the REMOVED entries are the explicit license to delete. Anything not listed as REMOVED MUST keep working.

Validation gates — selected by risk class

Validation is the gate that turns a claim of completion into evidence of it: a task MUST NOT be marked complete until every command in its Validation section has run and passed. The gate of a behavior-changing task is selected from its reconciled Touched Surface, by risk class:

A behavior change MUST produce a non-empty, relevant test selection — an invalid selector or a runner that selected zero tests is not coverage. Where the repository’s testing map is stale, the correct invocation is derived and the mapping update recorded; a small missing command never requires a full onboarding run. Where no scoped invocation exists, the full applicable suite applies — legacy behavior, never an error.

When a task adds new core functionality or materially changes existing behavior, its acceptance criteria MUST include automated test coverage for the new or changed behavior, and its validation runs the repository’s tests together with lint, type-check, and format checks — not the build alone. Existing tests MUST stay green.

Final-state validation

Per-task gates validate what each task touched; they do not replace validation of the plan as a whole. Before a plan completes, the repository’s complete applicable validation MUST run and pass on the final relevant state, after the last substantive change — in the Final Review. Broader runs earlier happen at integration boundaries or after shared/core changes, not on a task-count schedule. A passing result MAY be reused only with evidence that the relevant inputs are equivalent; otherwise it is rerun. Each gate run leaves a concise record: command, scope, revision, result, and an evidence path.

Security discipline

Security is first-class in the same way tests are, and it follows the same two-layer model: per-task discipline while the work happens, plus the security pass of the Final Review over the full change set at the end. Whenever a task touches authentication or authorization, input handling, secrets or configuration, network, file, or shell surface, or dependencies:

• Its acceptance criteria MUST state the security expectations of the change — input validated and escaped, no secret material in code or fixtures, auth checks preserved or strengthened — consistent with docs/SECURITY.md.
• Every commit MUST be confirmed free of secrets or credentials before it lands, test fixtures and documentation examples included. A secret in a pushed commit MUST be treated as leaked and rotated, not merely removed.
• Where the security-sensitive work is substantial, a dedicated hardening task SHOULD be placed immediately after the implementation tasks and before the comprehensive-tests task, so findings are fixed before tests encode the behavior and each finding becomes a regression case rather than rework.

This per-task discipline does not replace the Final Review’s security pass: per-task checks catch issues in the commit where they are born, while the final gate audits the whole plan — including the tests and documentation tasks themselves.

Plan lifecycle — the Final Review

Every conformant plan authored under this version ends with exactly one mandatory task: the Final Review (task N). Two responsibilities earlier versions placed in separate closing tasks are relocated: skills decisions move into the task that produced the pattern, and the Executive Report becomes an optional, on-request artifact. Nothing in the security pass is relaxed.

The Final Review MUST, in order:

(a) Security pass — review the plan’s full accumulated change set for hardcoded secrets, injection risks, new attack surface, weakened auth, and sensitive data in logs or docs; audit introduced dependencies; verify docs/SECURITY.md still reflects reality; write the security review report even when clean. A critical finding is fixed — or explicitly accepted by the user — before the plan completes.

(b) Final-state validation — the repository’s complete applicable validation runs and passes on the final relevant state.

(c) Skills reconciliation — every task carries a skills disposition and every recorded candidate has a disposition; no second discovery report.

(d) Completion — report completion with deliverables, validation evidence, and limitations; offer the Executive Report once. The plan is complete whether or not the offer is answered.

The Final Review runs sequentially after all other tasks and is never placed in a parallel group.

Task-local skills decisions

The question “did this work create a reusable pattern worth a skill or agent?” is answered inside the task that produced the pattern, while its evidence is in context. Every task’s Completion & Log carries a skills disposition: none, update an existing skill, create a named artifact, or a deferral with a reason. Warranted authoring happens inside that task, before its validation gate and commit, after checking the existing catalog for duplicates.

Executive report — optional, on request

The Executive Report is no longer a mandatory task. At completion the agent offers it once; it is generated only on an explicit request, satisfied from durable evidence without replaying the plan. No answer or an unattended run leaves the plan complete with no report generated.

Task completion protocol

After passing validation and before advancing to the next task, the agent MUST, in order: (1) mark the task [x] in the plan README; (2) increment the plan status count; (3) fill the task’s Completion & Log with no placeholder values; (4) add a 3–5 bullet entry to PROGRESS.md; (5) commit (where the plan commits) with the format {type}({scope}): {description} — Task {N} of PLAN_{name}; (6) where the plan carries the state layer, rewrite state.json atomically — task completed, gate records, outcome record, commit hash.

The six steps form one logical transaction. An agent interrupted mid-protocol MUST NOT start the next task — it must finish or unwind the partial completion first.

The DWP resume protocol

Resume MUST be possible from only the plan’s files plus the git log, with no external state. In a workspace without git — see Archetypes §3 — the plan’s state.json is REQUIRED and stands in for the git log.

A resuming agent — a new session, a different agent, a scheduled daemon turn, or a cloud session waking — MUST perform this ritual, in order:

1. Re-anchor. Read the plan README: goal, global guidelines, the task list.
2. Locate the checkpoint. Find the first unchecked task in the README; read the git log and git status (or state.json’s checkpoint where git is absent).
3. Reconcile state. Where state.json exists, compare it against the README checkboxes; on desync, regenerate it from the markdown before continuing.
4. Inspect the seam. Read the resume-point task’s Completion & Log and the last PROGRESS.md entry — the previous session’s last verified ground.
5. Smoke-test. Run the repository’s cheapest standing validation to confirm the world still works before building on it. A failing smoke test is investigated first, not built upon.
6. Continue atomically. Execute exactly the next task; do not batch ahead.

The agent MUST trust completed ([x]) marks and MUST NOT re-validate completed tasks unless the user explicitly requests it, or the smoke test fails in a way that implicates a completed task.

The execution loop

DWP defines five operations:

• create — Generate a new plan from a goal.
• execute — Execute the plan task by task.
• refine — Modify an existing plan.
• resume — Resume an interrupted plan.
• status — Report plan status without executing.

Output workspace

Output workspace

• .dwp/ gitignored · disposable
• plans/
• PLAN_<name>/
• README.md
• PROGRESS.md
• <n>.task_<slug>.md
• analysis_results/ reports
• SECURITY_REVIEW.md security review
• EXECUTIVE_REPORT.md executive report

All DWP artifacts MUST live under a gitignored .dwp/ directory at the repository root.

Machine-readable plan state

A plan MAY carry the machine-readable state layer — manifest.json (static identity) and state.json (live per-task state, validation-gate records, outcome records, checkpoint, blocked state). The markdown plan remains the source of truth; the JSON layer is a derived projection, regenerated at protocol points and reconciled on resume.

The state layer is RECOMMENDED for new plans, REQUIRED for unattended execution, and REQUIRED for agent workspaces without git. See the full normative definition in Plan state.

Proportional rigor

Rigor MUST be proportional to the work. Ceremony on trivial changes is a methodology failure, not extra safety. Every piece of work falls in exactly one tier:

An agent asked to create a plan for micro-tier work MUST say that a plan is disproportionate and offer the inline form instead. A plan folder MUST NOT be created for a trivial single-file change.

Micro-tier work still keeps the non-negotiables: an explicit goal, a validation gate that runs and passes, and test discipline for behavior changes. The tier changes the packaging, never the gates.

When scope grows mid-flight — a micro task uncovers real scope, a standard plan sprouts sub-repositories — the agent MUST stop and promote the work to the next tier rather than stretching the current one.

Compatibility

Plans and repositories from earlier versions remain conformant, and a conformance checker MUST distinguish a known legacy artifact (accepted) from an artifact that declares this version and is objectively invalid under it (rejected):

Versioning

This specification follows semantic versioning.