Skip to content
Deep Work Plan is live on Product Hunt today Upvote it
← All spec documents

Conformance

Version 1.3. Status: Stable. This document defines what it means for a repository to be Deep Work Plan-conformant — that is, AI-first and agent-pilotable. The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119.

Conformance exists so that “AI-first” is an objective, checkable property rather than an impression. A repository either meets the criteria below or it does not. The verify sub-skill (/dwp-verify) checks them mechanically.

A conformant repository

A DWP-conformant repository MUST satisfy all of the following. Every artifact MUST be reasoned for the repository — adapted to its real languages, frameworks, and commands. A generic stub, a placeholder, or content copied from another repository does not satisfy a criterion.

  1. AGENTS.md at the root. The repository MUST contain a root AGENTS.md that includes (a) an index of the documentation, (b) the mandatory rules for the repository, and (c) a Quick Commands block whose commands are real and runnable in this repository. Placeholder commands (for example, npm test in a repository that does not use npm) MUST NOT appear. The index MUST NOT link a docs/ file that does not exist, and the file SHOULD stay within a 150–500 line budget, moving detail into docs/ and linking it rather than growing without bound.
  2. CLAUDE.md resolves to AGENTS.md. A CLAUDE.md MUST exist and resolve to AGENTS.md (a symlink, or an equivalent that guarantees a single source of truth). The two MUST NOT diverge.
  3. A docs/ hierarchy. The repository MUST contain a docs/ directory covering the standard categories (architecture, standards, testing, development commands, security, and agent onboarding) with real, repository-specific content. Complex modules SHOULD carry their own README.md. The testing guide MUST define a real test, lint, and type-check toolchain — or, for a repository that has none, a concrete setup proposed from the stack during onboarding. An empty testing guide or “no tests” does not satisfy this criterion: without a defined way to validate behavior, a plan has no objective validation gate.
  4. A .agents/ home. The repository MUST contain a .agents/ directory with agents/, commands/, and skills/, plus a catalog under .agents/docs/ that matches what is on disk. The dwp-* commands MUST be thin delegators to the installed skill. A .claude path MUST resolve to .agents.
  5. A gitignored .dwp/ workspace. The repository MUST contain a .dwp/ directory with plans/, and .dwp/ MUST be gitignored. A tmp/ scratch space SHOULD exist and SHOULD be gitignored.
  6. The methodology skill is resolvable. The Deep Work Plan skill MUST be installed or referenced such that an agent in the repository can invoke its sub-skills.

A repository is fully conformant with zero optional addons. The optional addons (devcontainer, Dailybot, dependency-upgrade, design-system) MUST NOT be required for conformance. Since standard 2.3.0 the AI Diff Reviewer local review (vendored skill + extension file) is part of the baseline: its absence is a failure for a repository declaring 2.3.0 or newer and a harness-version finding for a legacy repository. Its CI surface stays optional.

A well-formed plan

A Deep Work Plan in .dwp/plans/ is well-formed when:

  1. Every task MUST declare an explicit scope, acceptance criteria, and at least one validation gate (a command or check that objectively passes or fails).
  2. Every task that adds new core functionality or changes product behavior MUST include automated test coverage for that behavior in its acceptance criteria, and MUST run the repository’s tests together with its lint and type-check checks in its validation gate — not the build alone. Existing tests MUST stay green; a behavior change MUST update a test it breaks rather than delete or skip it. Pure-documentation, configuration, or research tasks are exempt from creating tests but still run the repository’s gate.
  3. Every task that touches authentication, input handling, secrets or configuration, network surface, or dependencies MUST carry the security expectations of that change in its acceptance criteria, and every commit MUST be free of secret material.
  4. The plan MUST persist progress so that work survives interruption and can be resumed by a different agent. A task MUST NOT be recorded completed while any of its validation-gate records still shows a failing, unresolved run, and a task’s own completion log MUST NOT contradict its recorded status (for example a completed task whose log still reads “Status: pending” is a defect, not a pass).
  5. The plan MUST close with its recorded final review. A plan authored under this version MUST end with exactly one mandatory Final Review — the security pass, the final-state validation, and skills reconciliation. A plan authored under an earlier version ends with the three mandatory final tasks (Security Review, Skills & Agents Discovery, Executive Report) and remains conformant. A critical security finding blocks completion until fixed or explicitly accepted. Completion itself is a verified, recoverable transaction rather than a status flip: the terminal task closes through a guarded publication step that validates the finished plan’s artifacts before writing state and leaves a machine-checkable FINALIZATION.json receipt; an interrupted publication is recovered from evidence, never silently re-declared complete. Any evidence pointer a gate record cites MUST resolve inside the plan’s own folder — a dangling or escaping pointer is a finding, not passing evidence.
  6. Tasks SHOULD re-anchor to the plan’s goal before executing, to prevent drift over a long horizon.

Verifying conformance

Conformance SHOULD be verified mechanically rather than by inspection. Running /dwp-verify produces a pass/fail report against the criteria above: the presence and real-content of AGENTS.md, the CLAUDE.md resolution, the docs/ categories, the .agents/ catalog-versus-disk match, the .dwp/ and tmp/ gitignore status, and — for a plan — that every task carries acceptance criteria and a validation gate, with test coverage for behavior-changing tasks and the recorded final review present. For a plan, it also checks that the plan’s markdown and its machine-readable state agree (a desynced README and state.json is a finding, never a silent pass), that completed tasks carry non-contradictory gate and log evidence, and — where a completed plan reaches it — that a publication receipt backs the completion it claims. The checker is version-aware: it MUST accept a legacy plan (three mandatory final tasks, no Touched Surface) as conformant, and MUST reject a plan that declares this version and is objectively invalid under it. It also reports a missing or stale DWP standard: provenance line as a finding that names the targeted harness upgrade. The mechanical layer is honest about its limits: without a capable interpreter (Python 3.9+) it exits non-zero with an explicit UNVERIFIED verdict instead of skipping its checks — a checker never reports a result it did not verify.

A repository SHOULD be re-verified after onboarding and after each completed plan, so that conformance is maintained rather than asserted once.