# Deepworkplan Verify

> Verify that a repository is DeepWorkPlan-conformant (AI-first) and that its plans are well-formed, producing an objective pass/fail report. Use when the developer asks to verify, audit, or check conformance of a repo or a plan.

- Skill: `dailybothq/deepworkplan-verify` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add dailybothq/deepworkplan-verify`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dailybothq/deepworkplan-verify/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: dailybothq (https://skillmd.com/u/dailybothq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dailybothq/deepworkplan-verify

---


# DeepWorkPlan — Verify (conformance check)

Check, objectively, whether a repository is **DeepWorkPlan-conformant** (AI-first
and agent-pilotable) and whether its Deep Work Plans are well-formed. This
sub-skill is **read-only**: it reports pass/fail, it does not change files. The
normative criteria are defined in the specification's Conformance document
(<https://deepworkplan.com/spec>).

## Shared resources (read these)

- [`../shared/context.sh`](../shared/context.sh) — resolve the repo root and `.dwp/`.
- [`../shared/dwp-paths.md`](../shared/dwp-paths.md) — plans live at `.dwp/plans/PLAN_{name}/`.
- [`conformance.sh`](conformance.sh) — the mechanical conformance layer (run it first).
- [`../spec/PLAN_STATE.md`](../spec/PLAN_STATE.md) — the machine-readable state layer the desync checks enforce.

## Run the mechanical layer first

Start every verification by running the automated checker — it covers the
structural checks below objectively, exits `0`/`1`, and detects
markdown-vs-`state.json` desync:

```bash
bash {skill_dir}/verify/conformance.sh            # repo + every plan
bash {skill_dir}/verify/conformance.sh --repo-only
bash {skill_dir}/verify/conformance.sh --plan PLAN_{name}
```

Its exit code is CI-friendly: a repo can run it as a pipeline gate. Then layer
the judgment checks (real commands, real toolchain, catalog-matches-disk) on
top — the script verifies *structure*; you verify *substance*.

## Parameter support

- `/dwp-verify` — verify the repository (the default).
- `/dwp-verify plan {name}` — also verify a specific plan's well-formedness.
- `/dwp-verify all` — verify the repository and every plan under `.dwp/plans/`.

## The overriding rule

Report what is **true on disk**, not what should be true. A criterion passes only
if the artifact exists *and* carries real, repository-specific content. A generic
stub, a placeholder, or a command that cannot run in this repository **fails** the
criterion — say so explicitly. Never mark a check passed without evidence.

## Repository checks

Run these from the repo root and record each result. Prefer the mechanical check;
fall back to reading the file when judgment is required (for example, deciding
whether `AGENTS.md` commands are real).

```bash
# 1. AGENTS.md at the root, with a Quick Commands block
test -f AGENTS.md && grep -qiE 'quick commands|## commands' AGENTS.md && echo "AGENTS.md: ok" || echo "AGENTS.md: FAIL"

# 2. CLAUDE.md resolves to AGENTS.md (symlink or equivalent single source)
[ -L CLAUDE.md ] && [ "$(readlink CLAUDE.md)" = "AGENTS.md" ] && echo "CLAUDE.md symlink: ok" || echo "CLAUDE.md symlink: CHECK"

# 3. docs/ with the standard categories
test -d docs && echo "docs/: present" || echo "docs/: FAIL"
for d in PRODUCT_SPEC ARCHITECTURE STANDARDS TESTING_GUIDE DEVELOPMENT_COMMANDS SECURITY AI_AGENT_ONBOARDING; do
  ls docs/ 2>/dev/null | grep -qi "$d" && echo "  docs/$d: ok" || echo "  docs/$d: missing"
done

# 4. .agents/ home with agents/ commands/ skills/ + a docs catalog; .claude resolves
for d in .agents/agents .agents/commands .agents/skills .agents/docs; do
  test -d "$d" && echo "$d: ok" || echo "$d: FAIL"
done
[ -e .claude ] && echo ".claude resolves: ok" || echo ".claude resolves: FAIL"
[ -e .cursor ] && echo ".cursor resolves: ok" || echo ".cursor resolves: FAIL"

# 5. dwp-* commands are thin delegators (≤ ~30 lines, reference the skill)
for f in .agents/commands/dwp-*.md; do
  [ -f "$f" ] || continue
  lines=$(wc -l < "$f")
  grep -qi 'deepworkplan' "$f" && [ "$lines" -le 40 ] && echo "$(basename "$f"): thin ok" || echo "$(basename "$f"): CHECK ($lines lines)"
done

# 6. .dwp/ gitignored with plans/ + drafts/; tmp/ gitignored
git check-ignore .dwp >/dev/null 2>&1 && echo ".dwp gitignored: ok" || echo ".dwp gitignored: FAIL"
test -d .dwp/plans && test -d .dwp/drafts && echo ".dwp structure: ok" || echo ".dwp structure: FAIL"
git check-ignore tmp >/dev/null 2>&1 && echo "tmp gitignored: ok" || echo "tmp gitignored: SHOULD"
```

Then, by reading rather than grepping:

- **Real commands.** Open `AGENTS.md` and confirm the Quick Commands actually correspond to this repo (the real package manager, test, lint, and build commands). Flag any command that could not run here.
- **Testing toolchain defined.** Open `docs/TESTING_GUIDE.md` and confirm it describes either a **real** test/lint setup (framework, file convention, how to run, coverage expectation) or — for a repo without one — a concrete **proposed** stack-appropriate setup (`../spec/DOCUMENTATION_STANDARD.md` §3.3). An empty file, a generic stub, or "no tests" **fails** this check: the repo then has no objective validation gate for future plans.
- **Catalog matches disk.** Confirm `.agents/docs/` (the skills/agents catalog) lists exactly the skills, agents, and commands that exist under `.agents/` — no dead links, no missing entries.
- **Skill resolvable.** Confirm the DeepWorkPlan skill is installed or referenced so its sub-skills can be invoked.

## Plan checks (when verifying a plan)

For each plan under `.dwp/plans/PLAN_{name}/`:

- Every task file declares an explicit scope, **acceptance criteria**, and at least one **validation gate** (a runnable command or check).
- **Test discipline.** Tasks that add new core functionality or change product behavior require automated test coverage in their Acceptance Criteria and run the repo's tests + lint/type-check in their Validation (`DWP_SPECIFICATION.md` §5.1.1). A behavior-changing plan with zero test work is a finding, not a pass.
- **Security discipline.** Tasks that touch auth, input handling, secrets/config, network surface, or dependencies carry security expectations in their Acceptance Criteria (`DWP_SPECIFICATION.md` §5.1.2); where the plan has a dedicated security-hardening task, it is ordered before the comprehensive-tests task.
- `PROGRESS.md` exists and is updated, so the plan is resumable.
- The three mandatory final tasks are present — Security Review, Skills & Agents Discovery, and the Executive Report. On a completed plan, `analysis_results/SECURITY_REVIEW.md` exists and reports no unresolved critical finding.
- Tasks re-anchor to the plan goal before executing.
- **State layer (when present).** `state.json` and `manifest.json` parse, and
  `state.json` agrees with the README checkboxes — on desync the markdown wins
  and the state file must be regenerated (`../spec/PLAN_STATE.md` §5).
  `conformance.sh` automates this. In a workspace without git
  (`../spec/ARCHETYPES.md` §4) the state layer is REQUIRED, not optional.

## Output

Produce a concise report:

```
DeepWorkPlan conformance — {repo name}

Repository
  [x] AGENTS.md (real Quick Commands)
  [x] CLAUDE.md -> AGENTS.md
  [ ] docs/ — missing SECURITY.md
  [x] .agents/ + catalog matches disk
  [x] .cursor -> .agents
  [x] .dwp/ gitignored (plans/, drafts/)
  [x] tmp/ gitignored
  [x] skill resolvable

Verdict: NOT CONFORMANT — 1 issue.
Next: run /dwp-create "fix conformance gaps" to plan the remediation, then /dwp-execute.
```

End with one of: **CONFORMANT** (all MUST criteria pass) or **NOT CONFORMANT — N issue(s)**, listing each failure. If gaps exist, offer to capture the fixes as a Deep Work Plan with `/dwp-create` — do not fix them silently inside this read-only check.

> **Large repo / in-progress onboarding.** A big repo may be mid-onboarding via
> the plan-driven path (onboard Phase 2b) — its documentation is being generated
> task-by-task by an onboarding Deep Work Plan rather than all at once. If you
> find a `PLAN_onboard_*` under `.dwp/plans/`, report conformance gaps as
> **in progress, not failures**, and point the developer at `/dwp-status` and
> `/dwp-resume` to finish that plan rather than starting a new remediation plan.