DeepWorkPlan — Upgrade (Sub-Skill)

Keep a repository's installed DeepWorkPlan skill and its declared DWP standard current. Three phases, strictly ordered: check (read-only, safe to run anytime), consent (nothing downloads without an explicit yes), upgrade (same install command a fresh consumer runs, then onboarding re-executed as if https://deepworkplan.com/init.md were executed fresh). An upgrade never touches .dwp/ plans — plans and their recorded evidence are history, not state to migrate (../spec/DWP_SPECIFICATION.md §6.5); its one .dwp/ write is the addon registry back-fill (Phase 3 step 4).

Trust boundary (write scope)

allowed-tools includes write-capable Edit, Write and Bash. Phase 1 (check) and Phase 2 (consent) are read-only. Only after the developer's explicit acceptance does Phase 3 write: the vendored skill tree at the exact accepted stable tag (pre-release tags only on an explicit request for that channel), through the documented installer, then the onboarding reconciliation. It MUST NOT download anything before acceptance, install a moving ref (@main, @latest) or an unpinned source, overwrite local adaptations without showing their diff first, touch any plan under .dwp/, or read, print or write a secret.

When to use

• "upgrade DWP", "update the deepworkplan skill", "is there a newer version?", "re-run the init", "/dwp-upgrade"
• Before a long plan, when the developer wants the harness current
• Not for first-time onboarding (route to ../onboard/SKILL.md)
• Not for changing an in-flight plan's scope or shape (../refine/SKILL.md)
• Not for the targeted harness upgrade of one outdated piece — that is ../onboard/SKILL.md Phase 0; this sub-skill replaces the whole skill first

Context detection

Run the shared context helper to resolve the repo, branch, agent and .dwp/ location:

bash ../shared/context.sh

Then locate the installed pack: the deepworkplan/ directory this sub-skill was read from (in a repo, typically .agents/skills/deepworkplan/; a global install lives under ~/.<agent>/skills/deepworkplan/). Everything below reads versions relative to that directory.

Phase 1 — Check (read-only)

1. Installed version. Read version: from the installed pack's SKILL.md frontmatter — read it, never edit it. Also read the DWP standard the installed checker implements (SUPPORTED_SPEC in verify/conformance.sh) and the standard the repository declares (the DWP standard: line in AGENTS.md, if present).
2. Latest published version. Through the documented channel, resolve the newest release tag:

   git ls-remote --tags https://github.com/DailybotHQ/deepworkplan-skill.git

   Sort the stable vX.Y.Z tags numerically and take the highest; ignore pre-release tags (vX.Y.Z-beta.N, -rc.N, -alpha.N) unless the developer explicitly asks for the pre-release channel. (gh release view --repo DailybotHQ/deepworkplan-skill — which never returns a pre-release — is an equivalent alternative when the GitHub CLI is present.)
3. Report, then stop. State, in a few lines: installed skill version, latest published version, the standard each implements (the series are 2.x, 4.x, 5.x and 6.x historical and 7.x current — ../spec/README.md), and where the changelog lives (https://github.com/DailybotHQ/deepworkplan-skill/blob/main/CHANGELOG.md). If installed == latest, say the repository is current and end here.
4. Offline or unreachable upstream. If the network call fails (no network, DNS, proxy, rate limit), say so in one line, state the installed version, and exit cleanly — no partial state, no error cascade, no retry loop.

Phase 2 — Consent (nothing moves without an explicit yes)

1. Name what the upgrade overwrites: the vendored skill files under the installed pack directory (and only those). Name what it does not touch: .dwp/ (plans, state, evidence), AGENTS.md, docs/, .agents/ outside the vendored pack, and every addon the repository configured. Name the one registry write: already-installed addons the registry does not name are recorded in .dwp/config.json (Phase 3 step 4).
2. Surface local adaptations before overwriting anything. Repositories deliberately adapt their vendored copy (a repo may pin and maintain its own edition — a blind reinstall would erase that work). Stage the incoming tag into a temporary directory and diff it against the installed tree:

   diff -r --brief .agents/skills/deepworkplan "$TMP/incoming/deepworkplan" || true

   Report the differing files grouped two ways: files where the incoming tag itself changed (a normal upgrade), and files where the installed tree differs from the tag it claims (installed version:) — those are local adaptations. In a git repository the vendored tree is tracked, so the after-install git diff shows the full picture the same way.
3. Ask. One question, listing both groups: proceed with the upgrade, and for adapted files — re-apply the adaptation on top of the new version, or take the new version as-is? Only an explicit acceptance starts Phase 3; a decline or silence ends the sub-skill with the Phase 1 report standing.

Phase 3 — Upgrade (accepted)

1. Install the exact tag the developer accepted, using the same documented command a fresh consumer would run through the skills.sh channel (both -y flags are required in a non-interactive session):

   npx --yes skills add https://github.com/DailybotHQ/deepworkplan-skill/tree/vX.Y.Z --skill deepworkplan --force -y

   A repository that installed via Method 2 or 3 upgrades through its own documented channel instead (openclaw skills update deepworkplan, or git pull && ./setup.sh in the clone). Around every CLI install, run the Phase 7 install-verification contract from ../onboard/SKILL.md (two CLI defects are known from round-1 evidence — ../shared/troubleshooting.md §2): pre-create .agents/skills/deepworkplan/ before the call, then verify the installed SKILL.md frontmatter version: equals the accepted tag and the directory is non-empty. A mismatch or an empty/false success aborts the phase with the difference stated — retry once after pre-creating the directory, then fall back to the byte-exact git archive <tag> install with a diff -rq byte-check and record the event; never continue on a wrong or empty install.
2. Re-run onboarding as if executing https://deepworkplan.com/init.md fresh. Read ../onboard/SKILL.md and execute it end-to-end as a first-run onboarding — not its Phase 0 targeted-upgrade branch: the skill files were just replaced, so every phase re-reasons against the new version. Its guarantees hold unchanged — non-destructive, reconcile-don't-overwrite, idempotent on a second run. This re-detects the stack, reconciles AGENTS.md/docs//.agents/, and re-offers addons under their standing policies (AI Diff Reviewer local install rides onboarding authorization; every optional addon still needs explicit acceptance). Short path for an onboarded repository (F-09). When the repository already declares DWP standard: 6.x and was conformant before the upgrade, the re-onboarding is this checklist instead of a full run: (a) python3 <pack>/shared/delegators.py check --repo . — present each DRIFT as keep (a deliberate adaptation) or refresh (from ../onboard/command-templates/), and offer each MISSING (F-23); (b) step 4's registry back-fill and .gitignore exception; (c) the host capability record from the existing AGENTS.md declaration (config.py host <capability> true, ../onboard/v6.md §1); (d) Phase 7b's offer of addons the registry does not name yet; then step 3 and step 6. Run the full onboarding when conformance failed, the declaration predates 6.0, or the developer asks for it.
3. Re-stamp the standard. The provenance line in AGENTS.md becomes DWP standard: <the standard the new pack implements> (onboarded YYYY-MM-DD; upgraded YYYY-MM-DD; skill x.y.z) — the upgrade variant of ../spec/DOCUMENTATION_STANDARD.md §3.5. Never edit the skill's own version: fields or CHANGELOG.md; the release process owns them.
4. Back-fill the addon registry (F-15). Addons installed before the registry existed are recorded, never re-decided: run python3 <pack>/shared/config.py backfill --repo . (dry run), show the list, then --write. A key the registry already names is never changed, and a machine-level install is only reported (offer it; never back-filled). Then propose the .gitignore exception that shares the registry (.dwp/* + !.dwp/config.json, ../spec/CONFIG.md §1).
5. Leave .dwp/ plans untouched. Plans keep their recorded lifecycle and their authored standard — an old plan declaring 2.x stays valid as historical and is never migrated by an upgrade; migrating one is a separate, explicit refine migrate decision (../spec/DWP_SPECIFICATION.md §6.5).
6. Close the loop. Re-apply the accepted adaptation decisions on the new files, run ../verify/SKILL.md conformance, and report: old → new skill version, old → new standard stamp, what the re-onboarding reconciled, the adaptations applied or dropped, and the conformance verdict.

Version discovery (consumers)

• The installed version is the version: of the installed deepworkplan/SKILL.md frontmatter. skills-lock.json records only a content hash (computedHash), never the tag — record the ref beside it by hand when you need it (F-07).
• A pre-release carries its identifier (7.0.0-beta.1). A page or manifest that shows the stable line reads the latest non-pre-release (GitHub releases/latest), never the frontmatter of a vendored pre-release (F-26).

Guarantees

• Read-only until accepted. Phase 1 writes nothing; Phase 3 starts only after an explicit yes naming exactly what changes.
• .dwp/ is history. No plan, state file, gate record or evidence file is migrated, rewritten or invalidated by an upgrade.
• No silent loss. Local adaptations are diffed, listed and decided before any overwrite; a git-tracked vendored tree keeps the full audit trail.
• Offline-safe. An unreachable upstream is a clean report and exit — never a partial install and never a guess.