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.

1. 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.

1. 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).

1. 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.

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, four opt-in

The `addons/` area holds the capabilities the onboard flow layers onto a repo. The AI Diff Reviewer local review is part of the baseline since standard 2.3.0 (installed by onboard Phase 7a, run by every Final Review; its CI surface stays optional). The other four addons are opt-in and never part of the AI-first baseline — a repo is fully conformant with zero optional addons. The first optional addon is devcontainer support.