deepworkplan

DeepWorkPlan — Methodology Skill (Router)

Models matter; context matters more. The DeepWorkPlan skill turns any repository into a structured environment — context, guardrails, and a durable plan — where any coding agent executes reliably on short or long work. It makes the repository "AI-first" — AGENTS.md + docs/ + per-module docs + .agents/ (with the .claude → .agents and .cursor → .agents symlinks) — and runs structured Deep Work Plans: Lite plans for bounded work and Full task-file plans for longer work; an AI agent creates, refines, executes task-by-task, and resumes. All plan output lands in a gitignored .dwp/ directory at the repo root (.dwp/plans/).

Source of truth: https://deepworkplan.com. License: MIT.

Start here (first run)

This skill is a self-sufficient entry point: whether a developer arrives from https://deepworkplan.com/init.md or simply installs this skill, the setup plan is the same — and it lives here, so no network is required.

If the repository is not yet AI-first — there is no root AGENTS.md and no .agents/ directory — the recommended first action is to onboard it, even if the developer's request was vague ("set this up", "make this repo AI-first", or a plain install). Before routing anywhere else:

Read the standard locally. Read spec/ (v5 base and v6 extensions) and shared/adaptation.md. The overriding rule is REASON, do not copy-paste: this skill is the reusable engine; what you produce must be adapted to this repository, never templated.
Run onboarding. Read onboard/SKILL.md and execute it. It is non-destructive: detect existing AGENTS.md, docs/, .agents/, or CLAUDE.md, reconcile rather than overwrite, and ask the developer before replacing anything. The result: AGENTS.md + CLAUDE.md symlink, a reasoned docs/ tree, per-module docs, a .agents/ kit, and a gitignored .dwp/ — the repository becomes the agent harness.
Verify conformance. Read verify/SKILL.md and run it to confirm, objectively, that the repository now meets the standard (AGENTS.md with real commands, the .agents/ catalog, the gitignored .dwp/, and so on).
Then plan and execute. With the harness in place, create and execute Deep Work Plans (below) — long-horizon, gated, resumable work an agent can run autonomously for hours.

If the repository is already AI-first but its harness predates this skill — AGENTS.md / .agents/ exist, yet there is no DWP standard: provenance line, the provenance line is from an earlier series (2.x, 4.x, or 5.x; see spec/V6_LIFECYCLE.md), or docs/TESTING_GUIDE.md lacks the scoped-invocation and mapping content the standard requires, or its agent rules lack the working principles described in spec/DOCUMENTATION_STANDARD.md §2.3.1 (equivalent wording counts) — offer the targeted harness upgrade before routing. Say in one line what is out of date, then run onboard/SKILL.md in upgrade mode (Phase 0), which reconciles only the missing or outdated pieces, leaves every handwritten section, custom skill and in-flight plan untouched, and changes nothing on a second run. When the developer instead wants the skill itself current (newer published version, or a fresh init pass end-to-end), route to upgrade/SKILL.md: it checks the latest published tag, downloads only on explicit acceptance, and re-runs onboarding as a fresh init — .dwp/ plans are never migrated. An in-flight plan keeps its recorded lifecycle; migrating one is a separate, explicit refine migrate. If the developer declines, route by intent as normal.

Unattended runs record the gap; they never stop to offer. Under trust/auto or a pre-approved plan, that offer is the confirmation authorization already removed. So do not ask: write it down where the work will see it (a plan flow's README notes and PROGRESS.md; otherwise the flow's own report) and route by intent. A stale harness is a recorded finding like any missing optional tool (spec/AGENT_PROTOCOL.md §7.2) — never a question, and never a silent omission either.

A partially AI-first repository takes this same branch. The branches above are the clean cases; real repositories land in between (an AGENTS.md with no .agents/, an .agents/ with no provenance line, docs without a testing guide). Any repository with some of the harness and not the rest counts as out-of-date harness, not as a fresh one: reconcile through onboard in upgrade mode, which adds only what is absent. Never re-onboard from scratch over a repository that already carries part of the harness — that is the one path that can overwrite handwritten work.

If the repository is already AI-first and current, skip onboarding and route by intent silently — do not announce the detection or the routing decision (no "the repo is already AI-first" / "routing to the create sub-skill" preamble). Just begin the matched sub-skill's flow directly.

What it does

This is the router. It does not run any flow itself — it maps the developer's intent to the right sub-skill and tells the agent to read that sub-skill's SKILL.md and execute it there.

Trust boundary (write scope)

allowed-tools includes write-capable Edit, Write, and Bash because the sub-skills this router delegates to need them; the router itself only reads (the repo tree, the local spec/, shared/, and sub-skill files). Writes happen inside the delegated sub-skill, each of which declares its own trust boundary:

Onboard writes AGENTS.md, docs/, per-module docs, .agents/, and appends to .gitignore — reconciling with, never clobbering, what exists, and asking before replacing anything.
Create / refine write plan artifacts under the gitignored .dwp/ directory only.
Execute / resume write task outputs, progress, and per-task commits — gated by each task's validation, never committing secrets, never pushing without the developer's instruction.
Addons install or configure anything only after the developer explicitly accepts the offer, always via pinned, verified install paths.

It MUST NOT: make network calls in the core flow, read or commit credentials, run installers unprompted, or write anywhere outside the surfaces above. The full guarantees and a runnable self-audit live in TRUST.md.

For the agent — routing rules

When the developer wants to plan, execute, or manage structured work, or make a repo AI-agent-ready, match the intent below and read that sub-skill's SKILL.md to execute it. Do not answer directly — each sub-skill carries the full step-by-step flow.

Developer says…	Route to
"create a plan", "plan this small fix", "organize this work", "new deep work plan", "/dwp-create"	Create → read `create/SKILL.md`
"execute the plan", "run the plan", "/dwp-execute"	Execute → read `execute/SKILL.md`
"modify the plan", "change the scope", "/dwp-refine"	Refine → read `refine/SKILL.md`
"resume", "continue the interrupted plan", "/dwp-resume"	Resume → read `resume/SKILL.md`
"plan status", "what's left", "/dwp-status"	Status → read `status/SKILL.md`
"verify", "is this repo AI-first?", "check conformance", "/dwp-verify"	Verify → read `verify/SKILL.md`
"make this repo AI-first", "onboard this repo", "set up AGENTS.md + docs + .agents"	Onboard → read `onboard/SKILL.md`
"upgrade DWP", "update the skill", "is there a newer version?", "/dwp-upgrade"	Upgrade → read `upgrade/SKILL.md`
"create/update a skill or agent", "evolve the kit", "/skill-create", "/agent-create"	Author → read `author/SKILL.md`

If the intent is ambiguous between planning and managing existing work, ask the developer which they mean before routing.

Activation rules that hold for every row of the table:

Ordinary direct edits never become plans silently. "Fix this bug", "rename this function", "update the README" are done directly — a Deep Work Plan starts only when the developer asks for a plan (or picks a flow explicitly). The routing table maps requested flows; it is not an interception policy.
Trust is not a flow selector. trust / auto authorizes unattended continuation within the flow the developer requested; it never widens a read-only request into execution, and it never turns a direct edit into a plan.
Status and verify stay read-only. They report; they never execute tasks or mutate files — regardless of how they are invoked.
Plan generation is detected, never assumed. A plan folder carrying a manifest.json contract pointer, a contract.json, or a contracts/ revision chain is v6 (contract generation v6 or v7, spec/V7_CONTRACT.md) — create and execute route it through their v6.md loops (contract, journal, scheduler, verified closure). Anything else keeps the recorded v5 lifecycle, is never migrated silently, and a v5-only runner that meets a v6 plan reports it as unsupported rather than approximating it. Both generations can coexist in one .dwp/.
Hosts without slash commands use the same flows by name. Invoke the sub-skill as #deepworkplan-create or in plain text ("run deepworkplan-create"); the flows themselves are plain file reads, edits and shell commands (shared/troubleshooting.md §5 states the capability fallbacks). Flow discovery is local: the pack and the repo's .agents/ index live on disk — nothing routes through a network service.

Normative specification (ships with the skill)

The authoritative standard lives at spec/: retained v5 base documents plus the four current v6 extensions. It ships inside the skill so an agent reads the standard locally — no network needed. The onboard flow and shared/adaptation.md reference it as the standard to produce. The public, rendered version lives at https://deepworkplan.com/spec.

Shared resources used by every sub-skill

shared/context.sh — detect repo root, branch, and agent tool; resolve the .dwp/ output location.
shared/dwp-paths.md — the .dwp/ output convention (plans under .dwp/plans/) and how to override it.
shared/adaptation.md — the reasoning-over-copy-paste principle and the two repository archetypes (individual repo vs orchestrator hub).
shared/troubleshooting.md — read only when something is already wrong: discovery failure, stale installation, missing test command, unsupported host capability, inconsistent state.

Addons — one required local review, seven opt-in

The addons/ area holds what onboard layers onto a repo. Every repo gets the pack and the AI Diff Reviewer local review (baseline since 2.3.0: installed in Phase 7a, run by every Final Review). The other seven are opt-in — a repo is fully conformant with zero optional addons. Asked to set up or update them, or on a harness upgrade, onboarding detects every addon, upgrades the ones in use and offers the ones that fit.