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

The methodology skill delegates intent to nine specialized sub-skills: six core execution operations, two lifecycle helpers, and an authoring engine:

  • create — Generate a new plan from a goal. The agent analyzes the goal, decomposes it into sequential tasks, and writes the plan files. In guided mode the agent materializes a Lite plan directly (compact and inline in README.md), allowing the developer to retain, promote, or edit it; in trust mode it materializes the requested representation (Lite or Full) directly without prompting. Requirements analysis and plan-quality checks run in both modes.
  • execute — Run the plan task by task sequentially. The agent updates the progress log, runs validation gates, and commits after each task. In trust mode, execution continues unattended without prompting between tasks.
  • refine — Modify an existing plan (adding, editing, splitting, or reordering tasks, or promoting a Lite plan to Full) while strictly preserving completed evidence and prohibiting unconfirmed criterion weakening.
  • resume — Continue an interrupted plan. The agent reads the append-only journal and task files to reconstruct state, then continues from the first incomplete task without repeating finished work.
  • status — Report progress without executing (strictly read-only). The agent summarizes completed, in-progress, and pending tasks and changes nothing.
  • verify — Check conformance without changing anything (strictly read-only). The agent reports whether the repository meets the AI-first standard and whether plan tasks have explicit criteria and validation gates.
  • onboard — Inspect the target repository to reason—never copy-paste—an adapted AGENTS.md, a standard docs/ hierarchy, module docs, and the .agents/ kit with compatibility symlinks.
  • upgrade — Check upstream releases, prompt for developer consent before download, install pinned stable tags, and reconcile local adaptations while leaving existing .dwp/ plans untouched.
  • author — Create or evolve repo-local skills, agents, or slash commands to match real recurring workflows, and keep the .agents/docs/ catalog synchronized.

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. Repository-level addon configuration is recorded in .dwp/config.json (dwp-config/v1), while plans reside in flat numbered directories:

.dwp/
├── config.json
└── plans/
    └── PLAN_001_<slug>/
        ├── manifest.json
        ├── contract.json
        ├── journal.ndjson
        ├── state.json
        ├── README.md
        ├── PROGRESS.md
        ├── 1.task_<slug>.md
        ├── 2.task_<slug>.md
        └── analysis_results/

The ten-section task anatomy

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

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 closes with the Final Review — the security pass over the whole change set, the full validation on the final state, and the reconciliation of skills decisions. 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.

v6 and v7: the same methodology, stricter structure

The current DWP standard is 7.0.0, implemented by the 7.x skill line. That pack uses v7 for every new plan by default; an explicit v6 request still materializes a v6 plan. Existing v1, v2, v5, and v6 plans keep their recorded generation and are never silently migrated; moving a v5 plan to v6 requires an explicit migration request.

v6 retains the same plan → task → validation-gate → completion methodology, slash commands, and .dwp/plans/ location. It makes the engineering structure stricter with a contract, append-only journal, task context manifests, scheduler, and explicit runtime capability declarations. v7 keeps that record layer and adds an optional parallel_safe task marker, a delegation journal event for bounded work handed to another agent, and the .dwp/config.json addon registry; with no delegation addon enabled, every plan still runs sequentially in the current session. The architecture decision is GO; empirical superiority or non-inferiority in agent outcomes has not been measured.