@maoleijin/dsh-mattpocock-skills 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# dsh-mattpocock-skills
+
+[Matt Pocock's engineering skills](https://github.com/mattpocock/skills), packaged for DeepSeek Harness with a verified DSH adaptation overlay and automated upstream synchronization.
+
+## What this package provides
+
+- All 37 skills currently present upstream, plus the `dsh-workflow` guide.
+- A read-only `ctx.skills` provider with lazy loading and invocation-policy preservation.
+- DSH adaptations applied in memory while vendored upstream files remain byte-identical.
+- Exact-match validation: changed upstream wording fails instead of silently producing a partial adaptation.
+- Cross-platform synchronization, generated manifests, tests, and scheduled update pull requests.
+
+This project combines work from [NmouZh/dsh-mattpocock-skills](https://github.com/NmouZh/dsh-mattpocock-skills) and [auggie246/dsh-mattpocock-skills](https://github.com/auggie246/dsh-mattpocock-skills). The original skills are MIT licensed and authored by Matt Pocock. See [LICENSE](LICENSE) and [vendor/VENDOR.md](vendor/VENDOR.md).
+
+## Install
+
+### DSH Web
+
+```powershell
+npx --yes @deepseek-ai/dsh plugin --profile web add @maoleijin/dsh-mattpocock-skills
+```
+
+Restart `dsh web`, refresh the page, and open a new session. Verify with:
+
+```powershell
+npx --yes @deepseek-ai/dsh --profile web --dump-config | Select-String "mattpocock"
+```
+
+### DSH Desktop
+
+DSH Desktop exclusively manages its profile. Open its plugin-management window, enter the npm package name below, inspect the preview, and confirm installation:
+
+```text
+@maoleijin/dsh-mattpocock-skills
+```
+
+Completely quit and reopen DSH Desktop, then start a new session. Desktop does not accept filesystem paths or GitHub URLs in the package field.
+
+See [docs/installation.md](docs/installation.md) or run [scripts/install-web.bat](scripts/install-web.bat) on Windows.
+
+## Use
+
+Start with:
+
+```text
+/dsh-workflow
+/setup-matt-pocock-skills
+```
+
+Common user-started flows include `/ask-matt`, `/grill-with-docs`, `/to-spec`, `/to-tickets`, `/implement`, and `/wayfinder`. Model-invocable disciplines include `tdd`, `code-review`, `diagnosing-bugs`, `domain-modeling`, `codebase-design`, and `research`.
+
+## Synchronize upstream
+
+With an upstream checkout next to this repository:
+
+```powershell
+npm ci
+npm run sync:local
+npm test
+```
+
+Or let the synchronizer clone the configured upstream into a temporary directory:
+
+```powershell
+npm run sync
+npm test
+```
+
+Set `MATTPOCOCK_SKILLS_REPOSITORY` to use another Git remote. Scheduled synchronization opens a pull request only after overlay and provider validation succeeds.
+
+## Validate
+
+```powershell
+npm ci
+npm run check
+npm test
+```
+
+If upstream rewrites text targeted by the DSH overlay, validation reports the exact stale rule. Update `overlay/patches.json`, regenerate the mechanical rules, and rerun the suite.

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# dsh-mattpocock-skills bundle patch: inserts the bundled skill provider row
+# into the web profile roster. Applied as a profile bundle layer (the
+# `dsh.bundle.patch` manifest field) over dsh-base; activate with
+# `dsh plugin --profile web add @maoleijin/dsh-mattpocock-skills`.
+#
+# The row is a bare plugin by package name: the host half registers a
+# read-only `ctx.skills` provider that serves the vendored mattpocock skill
+# tree from this package, so no skill file needs to be copied into a user root.
+# Optional config keys: enabled, rank, skillRoot, promote.
+- insert:
+    - id: mattpocock-skills
+      name: '@maoleijin/dsh-mattpocock-skills'

package/docs/installation.md

@@ -0,0 +1,51 @@
+# Installation
+
+The published package name is:
+
+```text
+@maoleijin/dsh-mattpocock-skills
+```
+
+No machine-specific filesystem path is required.
+
+## Web profile
+
+```powershell
+npx --yes @deepseek-ai/dsh plugin --profile web add @maoleijin/dsh-mattpocock-skills
+```
+
+Verify the provider:
+
+```powershell
+npx --yes @deepseek-ai/dsh --profile web --dump-config | Select-String "mattpocock"
+```
+
+Restart `dsh web`, refresh the client, and create a new session.
+
+## Desktop profile
+
+The CLI cannot modify the Desktop-managed profile. In DSH Desktop:
+
+1. Open the plugin-management window.
+2. Choose the action for installing a package.
+3. Enter `@maoleijin/dsh-mattpocock-skills`.
+4. Wait for the registry preview and verify the exact package name and version.
+5. Confirm installation.
+6. Completely quit and reopen DSH Desktop.
+7. Create a new session and invoke `/dsh-workflow`.
+
+The Desktop package field accepts npm registry package names, not local paths or GitHub URLs.
+
+## Windows helper
+
+Run `scripts\install-web.bat`. It checks Node.js and pnpm, installs the published package into the Web profile, and verifies registration. Desktop installation remains an explicit UI operation because Electron exclusively owns that profile.
+
+## Updating
+
+Web profile:
+
+```powershell
+npx --yes @deepseek-ai/dsh plugin --profile web update @maoleijin/dsh-mattpocock-skills
+```
+
+For Desktop, use the update action in its plugin-management window. Restart and create a new session after upgrading.

package/overlay/patches.json

@@ -0,0 +1,462 @@
+{
+  "schema": "dsh-mattpocock-skills/overlay@1",
+  "upstream": {
+    "repository": "https://github.com/mattpocock/skills",
+    "version": "1.2.3"
+  },
+  "$comment": [
+    "DSH adaptation layer. The vendored tree under skills/ stays a byte-for-byte copy of upstream;",
+    "everything in this file is applied in memory by the skill provider, so `vendor-skills.mjs --check`",
+    "can still prove the baseline is pristine. Each rule is an exact literal find/replace plus the",
+    "number of occurrences the rule expects: a count mismatch fails the drift check instead of",
+    "silently half-applying after an upstream reword.",
+    "Why these edits exist: upstream is written for Claude Code, where `/name` is a command the model",
+    "can run. In DSH `/name` is a user-facing slash command, and a skill marked",
+    "`disable-model-invocation: true` cannot be loaded by the model at all, so the routing prose has to",
+    "name skills instead of issuing commands. See skills/dsh-workflow/ for the model-facing contract."
+  ],
+  "rules": [
+    {
+      "file": "engineering/ask-matt/SKILL.md",
+      "note": "the router is the entry point: teach it DSH's two invocation surfaces before it lists flows",
+      "find": "You don't remember every skill, so ask.",
+      "replace": [
+        "You don't remember every skill, so ask.",
+        "",
+        "**In DSH** this router names skills instead of running them. Load a name below with the `skill` tool whenever that skill is model-invocable; when a name is marked **user-only** in [`dsh-workflow`](../dsh-workflow/SKILL.md), the model cannot load it — say so and let the user invoke it from their own session, so it starts in a fresh context window the way the flow expects."
+      ],
+      "expect": 1
+    },
+    {
+      "file": "engineering/ask-matt/SKILL.md",
+      "note": "context hygiene: /clear and /compact are the harness's controls, not skills",
+      "find": "kick off **`/implement`** per ticket, **`/clear`ing context between each one**.",
+      "replace": "kick off **`implement`** per ticket, **starting a fresh session between each one** (the user starts it; a new session is what keeps each ticket's context disposable).",
+      "expect": 1
+    },
+    {
+      "file": "engineering/ask-matt/PHASE-BOUNDARIES.md",
+      "note": "the move table's first row pair",
+      "find": "| **`/clear`** | Empty the context window and start from nothing.                  |",
+      "replace": "| **Fresh session** | Empty the context window and start from nothing. Only the user can start one; ask for it. |",
+      "expect": 1
+    },
+    {
+      "file": "engineering/ask-matt/PHASE-BOUNDARIES.md",
+      "note": "step 5 hands the model a slash command with an instruction argument",
+      "find": "Pass it an instruction (`/compact we're going to QA this area`) so the summary keeps what the next phase needs.",
+      "replace": "Pass it an instruction (`/compact we're going to QA this area`) so the summary keeps what the next phase needs — the user runs the command, so ask for it in those words.",
+      "expect": 1
+    },
+    {
+      "file": "engineering/ask-matt/PHASE-BOUNDARIES.md",
+      "note": "harness-swap example names two CLIs; DSH is a third",
+      "find": "- swapping to a **new harness** (Claude → Codex),",
+      "replace": "- swapping to a **new harness** (Claude Code → Codex → DSH),",
+      "expect": 1
+    },
+    {
+      "file": "engineering/triage/SKILL.md",
+      "note": "the maintainer's entry point, described from inside the skill",
+      "find": "The maintainer invokes `/triage` and describes what they want in natural language.",
+      "replace": "The maintainer invokes the `triage` skill (in DSH: a user-only slash command) and describes what they want in natural language.",
+      "expect": 1
+    },
+    {
+      "file": "engineering/setup-matt-pocock-skills/domain.md",
+      "note": "domain-doc consumer rules: this file is read as a reference, so it must not send the model to a user-only skill",
+      "find": "The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily",
+      "replace": "The `domain-modeling` skill (reached from the **user-only** `grill-with-docs` and `improve-codebase-architecture` skills) creates them lazily",
+      "expect": 1
+    },
+    {
+      "file": "engineering/setup-matt-pocock-skills/domain.md",
+      "note": "same file, the gap signal",
+      "find": "or there's a real gap (note it for `/domain-modeling`).",
+      "replace": "or there's a real gap (note it for a `domain-modeling` pass).",
+      "expect": 1
+    },
+    {
+      "file": "engineering/setup-matt-pocock-skills/issue-tracker-github.md",
+      "note": "tracker doc read by other skills",
+      "find": "Used by `/wayfinder`.",
+      "replace": "Used by the **user-only** `wayfinder` skill.",
+      "expect": 1
+    },
+    {
+      "file": "engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md",
+      "note": "same line in the GitLab template",
+      "find": "Used by `/wayfinder`.",
+      "replace": "Used by the **user-only** `wayfinder` skill.",
+      "expect": 1
+    },
+    {
+      "file": "engineering/setup-matt-pocock-skills/issue-tracker-local.md",
+      "note": "same line in the local-markdown template",
+      "find": "Used by `/wayfinder`.",
+      "replace": "Used by the **user-only** `wayfinder` skill.",
+      "expect": 1
+    },
+    {
+      "file": "engineering/improve-codebase-architecture/HTML-REPORT.md",
+      "note": "report template references the glossary skill three times",
+      "find": "(from the `/codebase-design` skill)",
+      "replace": "(from the `codebase-design` skill)",
+      "expect": 1
+    },
+    {
+      "file": "engineering/improve-codebase-architecture/HTML-REPORT.md",
+      "note": "second reference",
+      "find": "come straight from the `/codebase-design` skill.",
+      "replace": "come straight from the `codebase-design` skill.",
+      "expect": 1
+    },
+    {
+      "file": "engineering/improve-codebase-architecture/HTML-REPORT.md",
+      "note": "third reference",
+      "find": "If a term isn't in the `/codebase-design` glossary",
+      "replace": "If a term isn't in the `codebase-design` glossary",
+      "expect": 1
+    },
+    {
+      "file": "engineering/to-tickets/SKILL.md",
+      "note": "here the setup skill is named as configuration a human ran, so it only needs to stop reading as a command",
+      "find": "**How** depends on the tracker `/setup-matt-pocock-skills` configured",
+      "replace": "**How** depends on the tracker the `setup-matt-pocock-skills` setup chose",
+      "expect": 1
+    },
+    {
+      "file": "engineering/setup-matt-pocock-skills/SKILL.md",
+      "note": "the plugin ships every skill in one tree, so a folder probe is always true; the real signal is whether the session catalog carries triage",
+      "find": "- Is the `triage` skill installed? (a `triage` skill folder alongside this one, or `triage` in your available skills.) This decides whether Section B runs at all.",
+      "replace": "- Is the `triage` skill available? In DSH the whole mattpocock set ships in one bundle, so a `triage` folder always sits alongside this one — the folder proves nothing. Use your own available-skills catalog instead, and answer **yes** when it lists `triage`. This decides whether Section B runs at all.",
+      "expect": 1
+    },
+    {
+      "file": "in-progress/setup-ts-deep-modules/SKILL.md",
+      "note": "the done-when line repeats the file choice",
+      "find": "the repo's `CLAUDE.md`/`AGENTS.md` links to it.",
+      "replace": "the repo's instruction file (`AGENTS.md`, else `CLAUDE.md`) links to it.",
+      "expect": 1
+    },
+    {
+      "file": "productivity/handoff/SKILL.md",
+      "note": "the receiving session is a new DSH session, which cannot rely on the OS temp dir surviving or being found",
+      "find": "Save to the temporary directory of the user's OS - not the current workspace.",
+      "replace": "Save it inside the workspace, not the OS temp directory: the receiving agent is a fresh DSH session whose cwd is the workspace, so `handoff/<YYYY-MM-DD>-<slug>.md` is where it will actually look. Keep `/tmp` out of it — a temp path is neither discoverable from the repo nor guaranteed to survive a reboot.",
+      "expect": 1
+    },
+    {
+      "file": "in-progress/claude-handoff/SKILL.md",
+      "note": "blocker: the whole point of this skill is Claude Code's background CLI; DSH delegates in-process",
+      "find": "Write a handoff summary of the current conversation so a fresh agent can continue the work. Instead of saving it, launch a background agent seeded with the summary as its prompt: `claude --bg --name \"<descriptive name>\" \"<handoff summary>\"`. It starts in the current working directory and returns immediately; the user manages it with `claude agents`.",
+      "replace": "Write a handoff summary of the current conversation so a fresh agent can continue the work. In DSH you do not shell out to another CLI for this: delegate with the `subagent` tool, passing the summary as the prompt (it runs in this workspace and returns its own report), or `subagent_fork` when the child should inherit this conversation instead of just the summary. Both return a durable agent id immediately, so keep working and pick the result up later with `job_output`/`list_agents` and `send_message`.",
+      "expect": 1
+    },
+    {
+      "file": "engineering/ask-matt/PHASE-BOUNDARIES.md",
+      "note": "move table: the two non-skill moves lose their command spelling",
+      "find": "| **`/handoff`** | Write a portable markdown file and seed a session anywhere with it. |",
+      "replace": "| **Handoff** | Write a portable markdown file and seed a session anywhere with it. |",
+      "expect": 1
+    },
+    {
+      "file": "engineering/ask-matt/PHASE-BOUNDARIES.md",
+      "note": "same table, the compaction row",
+      "find": "| **`/compact`** | Compress this context and seed a fresh session with the summary.  |",
+      "replace": "| **Compact** | Compress this context and seed a fresh session with the summary (the DSH `/compact` command, run by the user). |",
+      "expect": 1
+    },
+    {
+      "file": "engineering/ask-matt/PHASE-BOUNDARIES.md",
+      "note": "step 3 opens on handoff as a command",
+      "find": "**3. Do you need to hand off?** `/handoff` is narrow.",
+      "replace": "**3. Do you need to hand off?** The user-only `handoff` skill is narrow.",
+      "expect": 1
+    },
+    {
+      "file": "engineering/ask-matt/PHASE-BOUNDARIES.md",
+      "note": "step 3's closing line",
+      "find": "That list is the whole clause. What `/handoff` buys is **portability**",
+      "replace": "That list is the whole clause. What `handoff` buys is **portability**",
+      "expect": 1
+    },
+    {
+      "file": "engineering/ask-matt/PHASE-BOUNDARIES.md",
+      "note": "step 5 is the compaction branch, and the command is the user's to run",
+      "find": "**5. Otherwise, `/compact`.**",
+      "replace": "**5. Otherwise, ask for `/compact`.**",
+      "expect": 1
+    },
+    {
+      "file": "engineering/ask-matt/PHASE-BOUNDARIES.md",
+      "note": "the default-not-first-reach paragraph opens on the command",
+      "find": "`/compact` is the **default, not the first reach**.",
+      "replace": "Compaction is the **default, not the first reach**.",
+      "expect": 1
+    },
+    {
+      "file": "engineering/ask-matt/PHASE-BOUNDARIES.md",
+      "note": "source table names both moves",
+      "find": "| Secondary (`/compact`, `/handoff`) |",
+      "replace": "| Secondary (Compaction, Handoff) |",
+      "expect": 1
+    },
+    {
+      "file": "engineering/ask-matt/PHASE-BOUNDARIES.md",
+      "note": "DSH has no /clear command; the user starts a fresh session instead",
+      "find": "If so, **`/clear`**. It is the cheapest move on the board: it takes no time and hands back the whole window. `/clear` also isn't terminal: the old session stays resumable.",
+      "replace": "If so, ask the user to start a **fresh session**. It is the cheapest move on the board: it takes no time and hands back the whole window. The old session stays resumable.",
+      "expect": 1
+    }
+  ],
+  "slashInvocations": {
+    "$comment": [
+      "Mechanical normalisation for files the hand-written rules above already touch: the remaining",
+      "`/name` references are commands upstream, but in DSH a skill is loaded by name and a session",
+      "command is run by the user. Applied after the hand-written rules, with the same exact-count",
+      "contract; `overlay-report.mjs` lists every one of them with its observed count.",
+      "ask-matt/PHASE-BOUNDARIES.md is excluded: its prose was rewritten by hand instead."
+    ],
+    "files": {
+      "engineering/ask-matt/SKILL.md": [
+        {
+          "find": "**`/clear`**",
+          "replace": "**Clear**",
+          "expect": 1,
+          "note": "clear is a session-level move the user asks for, so it is named in prose"
+        },
+        {
+          "find": "`/code-review`",
+          "replace": "`code-review`",
+          "expect": 2,
+          "note": "code-review is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/codebase-design`",
+          "replace": "`codebase-design`",
+          "expect": 2,
+          "note": "codebase-design is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "**`/compact`**",
+          "replace": "**Compact**",
+          "expect": 1,
+          "note": "compact is a session-level move the user asks for, so it is named in prose"
+        },
+        {
+          "find": "`/diagnosing-bugs`",
+          "replace": "`diagnosing-bugs`",
+          "expect": 1,
+          "note": "diagnosing-bugs is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/domain-modeling`",
+          "replace": "`domain-modeling`",
+          "expect": 1,
+          "note": "domain-modeling is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/grill-me`",
+          "replace": "`grill-me`",
+          "expect": 4,
+          "note": "grill-me is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/grill-with-docs`",
+          "replace": "`grill-with-docs`",
+          "expect": 10,
+          "note": "grill-with-docs is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/grilling`",
+          "replace": "`grilling`",
+          "expect": 2,
+          "note": "grilling is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/handoff`",
+          "replace": "`handoff`",
+          "expect": 5,
+          "note": "handoff is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/implement`",
+          "replace": "`implement`",
+          "expect": 7,
+          "note": "implement is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/improve-codebase-architecture`",
+          "replace": "`improve-codebase-architecture`",
+          "expect": 4,
+          "note": "improve-codebase-architecture is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/prototype`",
+          "replace": "`prototype`",
+          "expect": 2,
+          "note": "prototype is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/research`",
+          "replace": "`research`",
+          "expect": 1,
+          "note": "research is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/resolving-merge-conflicts`",
+          "replace": "`resolving-merge-conflicts`",
+          "expect": 1,
+          "note": "resolving-merge-conflicts is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/setup-matt-pocock-skills`",
+          "replace": "`setup-matt-pocock-skills`",
+          "expect": 1,
+          "note": "setup-matt-pocock-skills is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/tdd`",
+          "replace": "`tdd`",
+          "expect": 3,
+          "note": "tdd is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/teach`",
+          "replace": "`teach`",
+          "expect": 1,
+          "note": "teach is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/to-questionnaire`",
+          "replace": "`to-questionnaire`",
+          "expect": 1,
+          "note": "to-questionnaire is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/to-spec`",
+          "replace": "`to-spec`",
+          "expect": 3,
+          "note": "to-spec is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/to-tickets`",
+          "replace": "`to-tickets`",
+          "expect": 5,
+          "note": "to-tickets is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/triage`",
+          "replace": "`triage`",
+          "expect": 2,
+          "note": "triage is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/wait-what`",
+          "replace": "`wait-what`",
+          "expect": 1,
+          "note": "wait-what is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/wayfinder`",
+          "replace": "`wayfinder`",
+          "expect": 2,
+          "note": "wayfinder is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/wizard`",
+          "replace": "`wizard`",
+          "expect": 1,
+          "note": "wizard is a skill, not a command: name it instead of running it"
+        },
+        {
+          "find": "`/writing-for-agents`",
+          "replace": "`writing-for-agents`",
+          "expect": 1,
+          "note": "writing-for-agents is a skill, not a command: name it instead of running it"
+        }
+      ],
+      "engineering/code-review/SKILL.md": [
+        {
+          "find": "`/setup-matt-pocock-skills`",
+          "replace": "`setup-matt-pocock-skills`",
+          "expect": 1,
+          "note": "setup-matt-pocock-skills is a skill, not a command: name it instead of running it"
+        }
+      ],
+      "engineering/improve-codebase-architecture/SKILL.md": [
+        {
+          "find": "`/codebase-design`",
+          "replace": "`codebase-design`",
+          "expect": 1,
+          "note": "codebase-design is a skill, not a command: name it instead of running it"
+        }
+      ],
+      "engineering/setup-matt-pocock-skills/issue-tracker-github.md": [
+        {
+          "find": "`/triage`",
+          "replace": "`triage`",
+          "expect": 1,
+          "note": "triage is a skill, not a command: name it instead of running it"
+        }
+      ],
+      "engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md": [
+        {
+          "find": "`/triage`",
+          "replace": "`triage`",
+          "expect": 1,
+          "note": "triage is a skill, not a command: name it instead of running it"
+        }
+      ],
+      "engineering/to-spec/SKILL.md": [
+        {
+          "find": "`/setup-matt-pocock-skills`",
+          "replace": "`setup-matt-pocock-skills`",
+          "expect": 1,
+          "note": "setup-matt-pocock-skills is a skill, not a command: name it instead of running it"
+        }
+      ],
+      "engineering/to-tickets/SKILL.md": [
+        {
+          "find": "`/setup-matt-pocock-skills`",
+          "replace": "`setup-matt-pocock-skills`",
+          "expect": 1,
+          "note": "setup-matt-pocock-skills is a skill, not a command: name it instead of running it"
+        }
+      ],
+      "engineering/triage/AGENT-BRIEF.md": [
+        {
+          "find": "`/triage`",
+          "replace": "`triage`",
+          "expect": 1,
+          "note": "triage is a skill, not a command: name it instead of running it"
+        }
+      ],
+      "engineering/triage/SKILL.md": [
+        {
+          "find": "`/setup-matt-pocock-skills`",
+          "replace": "`setup-matt-pocock-skills`",
+          "expect": 1,
+          "note": "setup-matt-pocock-skills is a skill, not a command: name it instead of running it"
+        }
+      ],
+      "engineering/wayfinder/SKILL.md": [
+        {
+          "find": "`/setup-matt-pocock-skills`",
+          "replace": "`setup-matt-pocock-skills`",
+          "expect": 1,
+          "note": "setup-matt-pocock-skills is a skill, not a command: name it instead of running it"
+        }
+      ],
+      "in-progress/loop-me/SKILL.md": [
+        {
+          "find": "`/grilling`",
+          "replace": "`grilling`",
+          "expect": 1,
+          "note": "grilling is a skill, not a command: name it instead of running it"
+        }
+      ]
+    }
+  }
+}

package/overlay/skills/dsh-workflow/dsh-workflow/DSH-MAPPING.md

@@ -0,0 +1,40 @@
+# Upstream → DSH
+
+The vocabulary translation the skills assume, and the DSH features worth reaching for in each flow.
+Upstream is written for a harness whose conventions differ; the overlay rewrites the places where that
+would have changed behaviour, and this file is the short version of the same map.
+
+## Translation table
+
+| Upstream says | In DSH |
+| --- | --- |
+| `` `/grilling` `` (a command you run) | the skill named `grilling` — load it with the `skill` tool |
+| "run `/setup-matt-pocock-skills`" | that skill is **user-only**: ask the user to start it; you cannot load it |
+| `/clear` | a fresh session — only the user starts one (`/clear` does not exist in DSH) |
+| `/compact [instruction]` | the `/compact` command, run by the user; ask for it in those words |
+| "a sub-agent" / "a background agent" | the `subagent` tool (background, durable id, report back) or `subagent_fork` to inherit this conversation |
+| "spawn 3+ sub-agents in parallel" | several `subagent` calls in one message, or the `workflow` tool for a real fan-out with phases and structured results |
+| "the receiving session opens a file" | a fresh DSH session whose cwd is the workspace — so handoff files belong in the repo, not `/tmp` |
+| `CLAUDE.md` (first choice) | `AGENTS.md` is read first; `CLAUDE.md` is the fallback, and both still work |
+| `.claude/settings.json` hooks | **not read by DSH.** Use repo git hooks (`setup-pre-commit`) or DSH's permission settings |
+| "ask the user" | the `ask_user_question` tool when you want a structured choice; plain prose otherwise |
+| TodoWrite-style checklists | the `todo_write` tool |
+| "the issue tracker" | unchanged: `docs/agents/issue-tracker.md` in the repo, GitHub/GitLab via `gh`/`glab`, or local markdown under `.scratch/` |
+| `CONTEXT.md`, `docs/adr/`, `.out-of-scope/`, `docs/agents/` | unchanged — these are repo conventions, not harness features |
+
+## DSH features that fit these flows
+
+- **`subagent`** — the workhorse. Runs in its own context window in this workspace and returns a report, which is exactly what `code-review` (two axes), `codebase-design`'s design-it-twice (three or more alternatives) and `research` (fan-out per ticket) ask for. Start them in one message so they run concurrently; each returns a durable id you can follow up with.
+- **`workflow`** — when the fan-out is large or multi-stage (a research ticket per branch, a sweep over many files), it coordinates many subagents with phases instead of you hand-managing them.
+- **`subagent_fork`** — inherits this conversation. Use it when the child must know what was already decided, which the flows otherwise pay for with a handoff document.
+- **Plan mode** — `to-spec` and `wayfinder` produce a plan before anything is built; plan mode is how that conversation stays a proposal until the user approves it.
+- **Goals** — a multi-session build from `to-tickets` is the shape a long-running goal is for: one objective, continued across turns, with progress that survives session boundaries.
+- **Todo list** — `implement` walks tickets and red-green slices; `todo_write` is how that progress is visible instead of implied.
+- **`ask_user_question`** — `grilling`, `triage`, `setup-matt-pocock-skills` and `to-questionnaire` are interview-shaped. A structured question with options beats a paragraph when the answer is a choice; keep prose for open questions.
+
+## What deliberately does *not* change
+
+- The skills' substance: what a good test is, the triage roles, the deepening vocabulary, the review axes.
+- Repo conventions: `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/`, `docs/agents/`, `.scratch/`, `.out-of-scope/`.
+- The flow order and the phase-boundary tree, including which moves are cheap and which are lossy.
+- Upstream's choice to keep 20 skills user-started. DSH makes that a hard gate rather than a convention, which is why the rewrite list exists at all.