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:

1. 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.
2. 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.
3. 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).
4. 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.