Skip to content
← All chapters

Chapter 02

The core loop

DWP defines a small set of operations that move a plan from a goal to completed, reviewable work: create → execute → refine → resume → status, with verify as the conformance check that confirms the result. Together they form the loop an agent follows throughout a plan’s life. Agents execute one task at a time, validating each step before moving on.

This loop is the operational form of spec-driven development. The plan is the specification an agent executes against, each task carries explicit acceptance criteria, and the validation step is the gate that turns a claim of completion into evidence of it. Because the plan and its progress log live in the repository, the loop is resumable across sessions and agents.

The operations

  • create — Generate a new plan from a goal. The agent analyzes the goal, decomposes it into sequential tasks, and writes the plan files. It should ask clarifying questions before writing when the goal is ambiguous.
  • execute — Run the plan task by task. The agent updates the progress log after each task and marks the task’s completion status. It must not skip tasks without recording why.
  • refine — Modify an existing plan. The agent may add, remove, or reorder tasks, but it must preserve completed work and update the task table.
  • resume — Continue an interrupted plan. The agent reads the progress log and the task files to reconstruct state, then continues from the first incomplete task.
  • status — Report progress without executing. The agent summarizes completed, in-progress, and pending tasks and changes nothing.
  • verify — Check conformance without changing anything. The agent reports whether the repository meets the standard and whether a plan is well-formed — every task carrying acceptance criteria and a validation gate. See the specification’s Conformance document.

The .dwp/ output directory

All DWP artifacts live under a gitignored .dwp/ directory at the repository root. Keeping the workspace out of version control means a plan’s working state never pollutes the project history.

.dwp/
├── plans/
│   └── PLAN_<slug>/
│       ├── README.md
│       ├── PROGRESS.md
│       └── <n>.task_<slug>.md
└── config.yaml

The nine-section task anatomy

Every task file contains these nine sections, in order. The structure guarantees that each unit of work is self-contained and reviewable:

  1. Goal — one paragraph stating what the task achieves.
  2. Context — background, links, and why this task exists.
  3. Steps — ordered, concrete actions to perform.
  4. Acceptance criteria — a checklist of conditions that define done.
  5. Validation — commands or tests to run to verify the work.
  6. Files — paths expected to be created or modified.
  7. Dependencies — other tasks or external prerequisites.
  8. Risks — what could go wrong, and mitigations.
  9. Completion & Log — a status marker plus chronological notes.

Validation, completion, and resumption

Validation is part of the task, not an afterthought: each task names the commands or tests that prove it is done, and the agent runs them before marking completion. Tests are first-class here — a task that adds new functionality or changes behavior must add or update automated tests for that behavior and run the repository’s full code-quality check (tests plus lint and type-check), not just confirm that the build succeeds; existing tests must stay green, updated to the intended behavior rather than skipped. Security is first-class in the same way — any task that touches authentication, input handling, secrets, network surface, or dependencies carries the security expectations of that change in its acceptance criteria and keeps every commit free of secrets, and every plan ends with a Security Review that audits the whole change set. Completion is recorded with an explicit status marker ([ ] not started, [~] in progress, [x] done, [!] blocked) in the Completion & Log section. Resumption relies on these markers and the progress log — an agent can reconstruct exactly where the plan stopped and continue from the first incomplete task without redoing finished work.