deepworkplan
DeepWorkPlan — turn any repo AI-first and run Deep Work Plans. Routes to create, execute, refine, resume, status, verify, upgrade, and repo-onboarding sub-skills based on intent. Use when the developer wants to plan, execute, manage, or verify structured multi-task work, or make
Install
npx skills add https://github.com/DailybotHQ/deepworkplan-skill/tree/main/skills/deepworkplan
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install dailybothq-deepworkplan-skill@llmmart
git clone https://github.com/DailybotHQ/deepworkplan-skill.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole dailybothq/deepworkplan-skill collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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) andshared/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.mdand execute it. It is non-destructive: detect existingAGENTS.md,docs/,.agents/, orCLAUDE.md, reconcile rather than overwrite, and ask the developer before replacing anything. The result:AGENTS.md+CLAUDE.mdsymlink, a reasoneddocs/tree, per-module docs, a.agents/kit, and a gitignored.dwp/— the repository becomes the agent harness. - Verify conformance. Read
verify/SKILL.mdand 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/autoor 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 andPROGRESS.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.mdwith 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 throughonboardinupgrademode, 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/autoauthorizes 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.jsoncontract pointer, acontract.json, or acontracts/revision chain is v6 (contract generation v6 or v7,spec/V7_CONTRACT.md) — create and execute route it through theirv6.mdloops (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-createor 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.
Files (deepworkplan-skill)
-
addons
-
agentkit
-
templates
-
INTEGRATION.md 3.4 KB
Loading…
-
-
addon.json 414 B
Loading… -
SKILL.md 15.9 KB
Loading… -
SPEC.md 9.4 KB
Loading…
-
-
ai-diff-reviewer
-
templates
-
INTEGRATION.md 17.9 KB
Loading…
-
-
addon.json 302 B
Loading… -
SKILL.md 24.6 KB
Loading… -
SPEC.md 32.5 KB
Loading…
-
-
dailybot
-
templates
-
INTEGRATION.md 10.5 KB
Loading…
-
-
addon.json 279 B
Loading… -
SKILL.md 15.8 KB
Loading… -
SPEC.md 16.4 KB
Loading…
-
-
dependency-upgrade
-
templates
-
ecosystems.md 5.8 KB
Loading… -
lib-upgrade-command.md 2 KB
Loading… -
upgrade-report.md 1.4 KB
Loading…
-
-
addon.json 221 B
Loading… -
SKILL.md 10.4 KB
Loading… -
SPEC.md 8.5 KB
Loading…
-
-
design-system
-
templates
-
agent_prompt_guide.md 2.2 KB
Loading… -
design-system-command.md 2.7 KB
Loading… -
DESIGN.md.md 8 KB
Loading… -
presets.md 6.3 KB
Loading…
-
-
addon.json 212 B
Loading… -
SKILL.md 13.9 KB
Loading… -
SPEC.md 21.7 KB
Loading…
-
-
devcontainer
-
templates
-
INTEGRATION.md 4 KB
Loading…
-
-
addon.json 326 B
Loading… -
SKILL.md 22.9 KB
Loading… -
SPEC.md 15.3 KB
Loading…
-
-
herdr
-
templates
-
INTEGRATION.md 3.5 KB
Loading…
-
-
addon.json 409 B
Loading… -
install.md 3.6 KB
Loading… -
SKILL.md 13.6 KB
Loading… -
SPEC.md 13 KB
Loading…
-
-
vim
-
templates
-
INTEGRATION.md 9.8 KB
Loading…
-
-
addon.json 454 B
Loading… -
SKILL.md 9.1 KB
Loading… -
SPEC.md 15.6 KB
Loading…
-
-
machine-installs.md 2.9 KB
Loading… -
README.md 12 KB
Loading…
-
-
author
-
templates
-
AGENT_TEMPLATE.md 585 B
Loading… -
COMMAND_TEMPLATE.md 853 B
Loading… -
SKILL_TEMPLATE.md 638 B
Loading…
-
-
SKILL.md 10.9 KB
Loading…
-
-
create
-
addon-augmentations.md 4.7 KB
Loading… -
decisions.md 3.8 KB
Loading… -
orchestrator.md 2.7 KB
Loading… -
SKILL.md 54.5 KB
Loading… -
team-agents.md 4.6 KB
Loading… -
v6.md 7.2 KB
Loading…
-
-
examples
-
CREATE_PLAN.md 6.9 KB
Loading… -
ORCHESTRATOR_TASK_TEMPLATE_create_child_dwp.md 15 KB
Loading… -
ORCHESTRATOR_TASK_TEMPLATE_execute_child_dwp.md 16.7 KB
Loading… -
ORCHESTRATOR_TASK_TEMPLATE_integration_checkpoint.md 9 KB
Loading… -
PROMPTS_TEMPLATE.md 4 KB
Loading… -
TEAM_AGENTS_TASK_TEMPLATE.md 5.1 KB
Loading… -
V6_PLAN_EXAMPLE.md 5.5 KB
Loading…
-
-
execute
-
debate.md 3.8 KB
Loading… -
delegation.md 3.5 KB
Loading… -
orchestrator.md 5.2 KB
Loading… -
SKILL.md 41.6 KB
Loading… -
team-agents.md 2.8 KB
Loading… -
v6.md 11.8 KB
Loading…
-
-
guide
-
authoring.md 28.5 KB
Loading… -
execution.md 21 KB
Loading… -
GUIDE.md 8 KB
Loading… -
large-repo-onboarding.md 3.3 KB
Loading… -
orchestration-at-scale.md 11.4 KB
Loading… -
orchestrator.md 37.9 KB
Loading… -
prompts.md 10.1 KB
Loading… -
skills-integration.md 6.5 KB
Loading… -
structure.md 6.2 KB
Loading… -
swarm.md 21.2 KB
Loading… -
team-agents.md 12.3 KB
Loading…
-
-
onboard
-
command-templates
-
agent-create.md 904 B
Loading… -
dwp-create.md 1.3 KB
Loading… -
dwp-execute.md 884 B
Loading… -
dwp-refine.md 943 B
Loading… -
dwp-resume.md 891 B
Loading… -
dwp-status.md 881 B
Loading… -
dwp-upgrade.md 911 B
Loading… -
dwp-verify.md 889 B
Loading… -
skill-create.md 889 B
Loading…
-
-
presets
-
angular.md 7.5 KB
Loading… -
astro-svelte.md 6.7 KB
Loading… -
django.md 7.8 KB
Loading… -
fastapi.md 7.8 KB
Loading… -
flutter.md 7.1 KB
Loading… -
generic.md 6.5 KB
Loading… -
go.md 6.7 KB
Loading… -
laravel.md 6.8 KB
Loading… -
nestjs.md 7 KB
Loading… -
nextjs.md 7.8 KB
Loading… -
node-ts-service.md 6.7 KB
Loading… -
nuxt.md 7.2 KB
Loading… -
python-package-cli.md 6.8 KB
Loading… -
rails.md 6.8 KB
Loading… -
react-native.md 7.2 KB
Loading… -
README.md 7 KB
Loading… -
rust.md 6.7 KB
Loading… -
spring-boot.md 7.4 KB
Loading… -
sveltekit.md 7 KB
Loading… -
swift-ios.md 7.6 KB
Loading… -
terraform.md 7.8 KB
Loading… -
ts-lambda.md 7.5 KB
Loading… -
vue-vite.md 6.7 KB
Loading…
-
-
templates
-
onboarding-plan.md 9.1 KB
Loading…
-
-
addons.md 18.4 KB
Loading… -
all-addons.md 10.2 KB
Loading… -
SKILL.md 59.7 KB
Loading… -
v6.md 4.7 KB
Loading…
-
-
refine
-
SKILL.md 22.1 KB
Loading…
-
-
resume
-
SKILL.md 19 KB
Loading… -
v6.md 4.3 KB
Loading…
-
-
shared
-
adaptation.md 2.7 KB
Loading… -
addon_sync.py 17.7 KB
Loading… -
benchmark.py 97.6 KB
Loading… -
config.py 47.9 KB
Loading… -
context.sh 4.2 KB
Loading… -
context_manifest.py 40.8 KB
Loading… -
contract_v6.py 82.7 KB
Loading… -
delegators.py 3 KB
Loading… -
dwp-paths.md 5.8 KB
Loading… -
finalize_plan.py 7.2 KB
Loading… -
install-verification.md 1.8 KB
Loading… -
ledger.py 141.5 KB
Loading… -
migrate_v6.py 46.5 KB
Loading… -
outcomes.py 27.2 KB
Loading… -
plan_paths.py 4.8 KB
Loading… -
resources.py 49 KB
Loading… -
scheduler.py 41.6 KB
Loading… -
state_contract.py 9.8 KB
Loading… -
swarm.py 27.3 KB
Loading… -
troubleshooting.md 7.4 KB
Loading… -
update-state.py 12.5 KB
Loading… -
views.py 21 KB
Loading… -
working-principles.md 7.1 KB
Loading…
-
-
spec
-
schema
-
addon-descriptor-v1.schema.json 5.5 KB
Loading… -
benchmark-record.schema.json 14 KB
Loading… -
context-manifest-v6.schema.json 12.5 KB
Loading… -
dwp-config-v1.schema.json 4 KB
Loading… -
dwp-handoff-v1.schema.json 3 KB
Loading… -
journal-event-v6.schema.json 22.3 KB
Loading… -
journal-event-v7.schema.json 24.9 KB
Loading… -
learnings-record.schema.json 6 KB
Loading… -
plan-contract-v6.schema.json 16.4 KB
Loading… -
plan-contract-v7.schema.json 16.6 KB
Loading… -
plan-manifest-v2.schema.json 1 KB
Loading… -
plan-manifest-v5.schema.json 1.3 KB
Loading… -
plan-manifest-v6.schema.json 2 KB
Loading… -
plan-manifest-v7.schema.json 1.7 KB
Loading… -
plan-manifest.schema.json 1.8 KB
Loading… -
plan-snapshot-v6.schema.json 7.8 KB
Loading… -
plan-state-v2.schema.json 6.4 KB
Loading… -
plan-state-v5.schema.json 6.7 KB
Loading… -
plan-state.schema.json 3.7 KB
Loading…
-
-
ADDONS.md 27.8 KB
Loading… -
AGENT_PROTOCOL.md 28.4 KB
Loading… -
ARCHETYPES.md 10.6 KB
Loading… -
BENCHMARK.md 20.3 KB
Loading… -
CONFIG.md 10.5 KB
Loading… -
DOCUMENTATION_STANDARD.md 40.7 KB
Loading… -
DWP_SPECIFICATION.md 65.1 KB
Loading… -
LITE_PLANS.md 4 KB
Loading… -
PLAN_STATE.md 34.9 KB
Loading… -
README.md 11.5 KB
Loading… -
V6_CONTEXT.md 6.4 KB
Loading… -
V6_CONTRACT.md 12.3 KB
Loading… -
V6_LIFECYCLE.md 13.5 KB
Loading… -
V6_RESOURCES.md 4.7 KB
Loading… -
V7_ABILITIES.md 4.9 KB
Loading… -
V7_CONTRACT.md 6.4 KB
Loading… -
V7_ROADMAP.md 4.6 KB
Loading…
-
-
status
-
SKILL.md 8.9 KB
Loading…
-
-
upgrade
-
SKILL.md 11.3 KB
Loading…
-
-
verify
-
conformance.sh 15.7 KB
Loading… -
plan_contract.py 46.9 KB
Loading… -
SKILL.md 17.1 KB
Loading…
-
-
SKILL.md 12 KB
--- name: deepworkplan description: DeepWorkPlan — turn any repo AI-first and run Deep Work Plans. Routes to create, execute, refine, resume, status, verify, upgrade, and repo-onboarding sub-skills based on intent. Use when the developer wants to plan, execute, manage, or verify structured multi-task work, or make a repository AI-agent-ready. version: "7.10.0" documentation_url: https://deepworkplan.com user-invocable: true allowed-tools: Bash, Read, Grep, Glob, Edit, Write metadata: {"openclaw":{"emoji":"🧠","homepage":"https://deepworkplan.com","requires":{"anyBins":["git","bash"]}}} --- # 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/`](spec/README.md) (v5 base and v6 extensions) and [`shared/adaptation.md`](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`](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`](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`](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`](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`](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`](create/SKILL.md) | | "execute the plan", "run the plan", "/dwp-execute" | **Execute** → read [`execute/SKILL.md`](execute/SKILL.md) | | "modify the plan", "change the scope", "/dwp-refine" | **Refine** → read [`refine/SKILL.md`](refine/SKILL.md) | | "resume", "continue the interrupted plan", "/dwp-resume" | **Resume** → read [`resume/SKILL.md`](resume/SKILL.md) | | "plan status", "what's left", "/dwp-status" | **Status** → read [`status/SKILL.md`](status/SKILL.md) | | "verify", "is this repo AI-first?", "check conformance", "/dwp-verify" | **Verify** → read [`verify/SKILL.md`](verify/SKILL.md) | | "make this repo AI-first", "onboard this repo", "set up AGENTS.md + docs + .agents" | **Onboard** → read [`onboard/SKILL.md`](onboard/SKILL.md) | | "upgrade DWP", "update the skill", "is there a newer version?", "/dwp-upgrade" | **Upgrade** → read [`upgrade/SKILL.md`](upgrade/SKILL.md) | | "create/update a skill or agent", "evolve the kit", "/skill-create", "/agent-create" | **Author** → read [`author/SKILL.md`](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/`](spec/README.md): 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`](shared/context.sh) — detect repo root, branch, and agent tool; resolve the `.dwp/` output location. - [`shared/dwp-paths.md`](shared/dwp-paths.md) — the `.dwp/` output convention (plans under `.dwp/plans/`) and how to override it. - [`shared/adaptation.md`](shared/adaptation.md) — the reasoning-over-copy-paste principle and the two repository archetypes (individual repo vs orchestrator hub). - [`shared/troubleshooting.md`](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/`](addons/README.md) 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. -
TRUST.md 16.1 KB
Loading…
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.