mattpocock-skills-dsh 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock (original skills, https://github.com/mattpocock/skills)
+Copyright (c) 2026 mattpocock-skills-dsh contributors (DSH port)
+
+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,188 @@
+# mattpocock-skills-dsh
+
+[![npm version](https://img.shields.io/npm/v/mattpocock-skills-dsh)](https://www.npmjs.com/package/mattpocock-skills-dsh)
+[![GitHub release](https://img.shields.io/github/v/release/gongyijie85/mattpocock-skills-dsh)](https://github.com/gongyijie85/mattpocock-skills-dsh/releases)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+为 **DeepSeek Harness (DSH)** 打造的 Matt Pocock 技能插件包:把
+[mattpocock/skills](https://github.com/mattpocock/skills)(来自
+[aihero.dev/skills](https://www.aihero.dev/skills) 的"真实工程师"技能集)
+移植到 DSH 的 Cordis 插件架构上。
+
+插件会向 `ctx.skills` 注册表的 **host 层** 注册一个技能提供者,因此每个
+agent preset 的作用域链都会合并这些技能。技能正文随包分发
+(`skills/<name>/SKILL.md`),通过 `import.meta.url` 定位——这是包的
+组装事实,不需要任何用户配置。
+
+> **非官方移植**:技能内容改编自 [mattpocock/skills](https://github.com/mattpocock/skills)(MIT,
+> © Matt Pocock)。上游以 Claude Code 插件格式发布;本包做的是 DSH 适配。
+
+## 快速上手:七课工作流(中英对照)
+
+> 出自 Matt Pocock 的 skills 邮件——整包技能的正确打开方式,就是按下面
+> 这条工作流从头跑到尾。`Sandcastle` 为外部工具,不在本包内。
+
+> Prompts are disposable. Workflows are reusable. That is the whole
+> difference, and these seven lessons are one workflow in the order you
+> would actually run it:
+>
+> 提示词用过即弃,工作流可以复用——全部区别就在于此。而这七课,合起来
+> 就是一条按真实执行顺序运行的工作流:
+
+| Step | 原文 | 对照中文 |
+| --- | --- | --- |
+| 0 | This email. Pick your path. | 这封邮件就是起点:选一条路。 |
+| 1 | `/grill-with-docs` , so the agent is not building from fog | 先把想法拷问清楚,agent 才不会在迷雾中开工 |
+| 2 | `/prototype` and `/handoff` , to test the uncertain part in a toy version | 用玩具原型验证不确定的部分,并留好交接 |
+| 3 | `/to-spec` and `/to-tickets` , to break big work into reviewable slices | 把大工作拆成可评审的切片 |
+| 4 | `Sandcastle` , to run AFK agents somewhere safe | 在安全的地方跑挂机(AFK)agent(外部工具,不在本包) |
+| 5 | `/code-review` , so each run teaches the next one | 每一次评审,都让下一次运行变得更好 |
+| 6 | The full loop, start to finish | 从起点到终点,跑完整条循环 |
+
+## 在 DeepSeek Harness 中安装与使用
+
+这是 DeepSeek Harness 的**插件包**。安装后会把技能注册进 host 技能注册表,
+你 profile 里的每个 agent 会话都能在技能目录中看到它们,并可用 `skill`
+工具加载。
+
+### 前置条件
+
+- 已安装 DeepSeek Harness,并且有 **pnpm** —— `dsh plugin` 命令内部调用
+  pnpm(用 `pnpm --version` 检查;没有的话到 https://pnpm.io 安装)
+- `dsh` 命令行。它随 Harness 一起提供,通常以 `npx @deepseek-ai/dsh web`
+  方式启动。要么把它装成全局命令,要么在所有命令前加 `npx`:
+
+  ```sh
+  # 方式一:全局安装 dsh,永久可用(推荐)
+  npm install -g @deepseek-ai/dsh
+  dsh --version
+
+  # 方式二:不安装,所有命令用 npx 形式
+  npx @deepseek-ai/dsh --version
+  ```
+
+  下文所有 `dsh ...` 示例都可以等价写成 `npx @deepseek-ai/dsh ...`。
+
+### 最简单:一条命令(从 GitHub 安装)
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add github:gongyijie85/mattpocock-skills-dsh
+```
+
+### 从本地文件夹安装(开发阶段)
+
+```sh
+# 任意目录下执行;文件夹安装是链接方式,改完重启 profile 即生效
+dsh plugin --profile web add D:\plugins\mattpocock-skills-dsh
+```
+
+### 让 DeepSeek Harness 帮你安装
+
+打开 DeepSeek Harness(Web 界面),新建对话,把下面这句话发给它:
+
+```
+帮我安装这个链接里边的插件:https://github.com/gongyijie85/mattpocock-skills-dsh
+```
+
+Agent 会自动完成安装(`dsh plugin add` → 重启 profile → 验证技能注册)。
+
+### 重启并验证
+
+bundle 层在 profile 启动时挂载,所以需要**重启 profile**(停掉后重新运行
+`dsh web` / `npx @deepseek-ai/dsh web`,再刷新浏览器)。确认层已组合:
+
+```sh
+dsh --profile web --dump-config     # 必须出现 `mattpocock-skills-dsh` 行
+```
+
+之后技能会出现在 agent 技能目录中,可以用 `skill` 工具加载。
+
+### 卸载
+
+```sh
+dsh plugin --profile web remove mattpocock-skills-dsh
+# 卸载后同样需要重启 profile
+```
+
+## 技能列表(全量 25 个 = 上游 promoted 集)
+
+### productivity(7)
+
+| 技能 | 用途 | 调用方式 |
+| --- | --- | --- |
+| `grill-me` | 入口:无情地拷问一个计划或设计 | 用户调用(指向 grilling) |
+| `grilling` | 把想法压力测试成设计树,逐轮提问直到共识 | 模型/用户调用 |
+| `handoff` | 把当前对话压成交接文档给下一个 agent | 用户调用 |
+| `teach` | 在多个会话里教用户一个概念 | 用户调用 |
+| `to-questionnaire` | 把答不了的决策转成给别人填的问卷 | 用户调用 |
+| `wait-what` | 停下:上一条消息没接住——重新表述 | 用户调用 |
+| `writing-for-agents` | 编写 agent 消费的文档(skill、AGENTS.md 等) | 模型/用户调用 |
+
+### engineering(18)
+
+| 技能 | 用途 | 调用方式 |
+| --- | --- | --- |
+| `ask-matt` | 路由器:问哪个技能/流程适合当前情况 | 用户调用 |
+| `code-review` | 双轴评审(标准 + 规格),并行子代理 | 模型/用户调用 |
+| `codebase-design` | 深模块设计词汇(module/interface/depth/seam...) | 模型/用户调用 |
+| `diagnosing-bugs` | 硬 bug 与性能回归的诊断循环 | 模型/用户调用 |
+| `domain-modeling` | 打磨项目领域语言,记录 ADR | 模型/用户调用 |
+| `grill-with-docs` | 带文档沉淀的拷问(ADR + 词汇表) | 用户调用 |
+| `implement` | 按 spec/票据实现一段工作 | 用户调用 |
+| `improve-codebase-architecture` | 扫描深挖机会,HTML 报告 + 拷问 | 用户调用 |
+| `prototype` | 用一次性原型回答设计问题 | 模型/用户调用 |
+| `research` | 背景代理查一手资料,产出引用 Markdown | 模型/用户调用 |
+| `resolving-merge-conflicts` | 按意图解决 merge/rebase 冲突 | 模型/用户调用 |
+| `setup-matt-pocock-skills` | 一次性配置 issue tracker/标签/文档布局 | 用户调用 |
+| `tdd` | 红-绿-重构实现循环 | 模型/用户调用 |
+| `to-spec` | 把对话合成 spec 发布到 tracker | 用户调用 |
+| `to-tickets` | 把 spec 拆成声明阻塞边的 tracer-bullet 票据 | 用户调用 |
+| `triage` | 把 issue/PR 走完三态机并写 agent 简报 | 用户调用 |
+| `wayfinder` | 超大会话工作:决策票据地图逐条解决 | 用户调用 |
+| `wizard` | 生成交互式 bash 向导,让人走只有人能走的步骤 | 模型/用户调用 |
+
+> 说明:`/clear`、`/compact` 是上游引用的 Claude Code 原生命令,非本包技能;
+> DSH 中对应"开新会话"与"手动摘要续接",详见
+> `skills/ask-matt/PHASE-BOUNDARIES.md` 的移植注记。
+
+## 移植说明(对比上游 mattpocock/skills)
+
+- **格式**:上游即标准 `SKILL.md`(YAML frontmatter:`name` +
+  `description`,可选 `whenToUse`),DSH 可直接消费,正文基本零改动。
+- **调用语义**:上游 `disable-model-invocation: true`(仅用户可调,如
+  `grill-me`、`wait-what`)映射为 DSH 的 `invocation.modelInvocable: false`,
+  保留原意图;其余技能模型/用户均可调用。
+- **工具名适配**:`grill-me` 原文 "Call the Skill tool with 'grilling'" 的
+  Claude Code 工具名改为 DSH 的 `skill` 工具;`grilling` 中的"dispatch a
+  sub-agent"对应 DSH 的 `subagent` 工具,原文措辞通用,未改动。
+- **未移植的辅助文件**:各技能目录下的 `agents/openai.yaml` 是 Codex 的
+  调用策略,DSH 不需要,已剔除;`writing-for-agents` 的相对引用
+  `SKILL-MECHANICS.md` 随包保留,由 `resourceBase` 解析。
+- **相对引用**:技能目录内相对文件(如 `SKILL-MECHANICS.md`)通过
+  `resourceBase` 指向技能所在目录,可正常加载。
+
+## 工作原理
+
+- **Bundle 层** —— `cordis.patch.yml` 在 dsh-base 层之上插入一行
+  (`- id: mattpocock-skills-dsh, name: mattpocock-skills-dsh`)。后面的层
+  (profile 的 `cordis.patch.yml`、`--patch` 叠加)仍可按 id 定位这一行。
+- **提供者** —— `lib/index.js` 调用 `ctx.skills.registerProvider(...)`:
+  - `list()` 扫描包内 `skills/` 目录,把每个 `<name>/SKILL.md` 作为候选,
+    从 YAML frontmatter 解析出 `name`、`description`、`whenToUse` 与
+    `disable-model-invocation`。
+  - `get()` 按需读取候选技能正文,返回完整技能定义,`resourceBase` 指向
+    技能所在目录,使相对引用可以正确解析。
+- **零运行时依赖** —— 插件只使用 Node 内置模块,消费注入的 `ctx.skills`
+  服务接口。
+
+## 添加自己的技能
+
+往包里放一个新的 `skills/<kebab-name>/SKILL.md` 即可——它必须以 YAML
+frontmatter 开头(`name` + `description`,可选 `whenToUse` 与
+`disable-model-invocation`)。无需改任何代码:`list()` 会自动发现它。
+
+## 许可证
+
+MIT。技能内容改编自
+[mattpocock/skills](https://github.com/mattpocock/skills)(MIT),© Matt
+Pocock;DSH 移植部分 © mattpocock-skills-dsh contributors。见 [LICENSE](LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# mattpocock-skills-dsh bundle patch: mount the matt-pocock skill provider
+# into the host skill registry (its rows are host-plane, so every agent
+# preset's scope chain merges the skills it registers).
+#
+# This patch is applied over the dsh-base layer; later layers (the profile's
+# own cordis.patch.yml and --patch overlays) can still address this row by id.
+- insert:
+    - id: mattpocock-skills-dsh
+      name: 'mattpocock-skills-dsh'

package/lib/index.js

@@ -0,0 +1,169 @@
+// mattpocock-skills-dsh: Matt Pocock's skills for the DeepSeek Harness.
+//
+// A Cordis plugin that registers one skill provider into the HOST layer of the
+// `ctx.skills` registry, so every agent preset's scope chain merges these
+// skills. Skill bodies live in `../skills/<name>/SKILL.md` inside this
+// package; the provider locates them from `import.meta.url` (an assembly
+// fact of this package, never user config) and loads bodies on demand.
+//
+// The provider protocol mirrors @deepseek-ai/dsh-skill-filesystem:
+//   - list()  discovers directory-bundle candidates (name/description from
+//     YAML frontmatter, body left unread until requested)
+//   - get()   parses the winning candidate's SKILL.md and returns the full
+//     definition with a directory resource base for relative references
+//
+// Upstream adaptation notes (vs https://github.com/mattpocock/skills):
+//   - `disable-model-invocation: true` (user-invoked skills such as
+//     grill-me / wait-what) maps to invocation.modelInvocable: false, so
+//     DSH keeps the upstream invocation semantics.
+//   - Harness-specific aux files (e.g. agents/openai.yaml for Codex) are
+//     not shipped; only SKILL.md and its relative references travel.
+//
+// @module mattpocock-skills-dsh
+import { readdir, readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const name = 'mattpocock-skills-dsh'
+const inject = ['skills']
+
+/** Registry precedence for packaged skill providers: ranks below the local bundled root. */
+const PACKAGED_SKILL_RANK = 550
+
+/** The source bucket these skills advertise under (prompt-visible metadata). */
+const SOURCE = 'custom'
+
+/**
+ * Parse the YAML frontmatter block of a SKILL.md into metadata plus body.
+ * Handles only the scalar fields DSH skill discovery consumes (name,
+ * description, whenToUse) plus the upstream invocation flag; richer metadata
+ * passes through verbatim.
+ * @param text - the raw skill file contents.
+ * @returns parsed metadata object and the markdown body after the block, or
+ *   null when the file has no frontmatter block at all.
+ */
+function parseFrontmatter(text) {
+  if (!text.startsWith('---')) return null
+  const end = text.indexOf('\n---', 3)
+  if (end === -1) return null
+  const block = text.slice(3, end)
+  const body = text.slice(end + 4).replace(/^\n+/, '')
+  const metadata = {}
+  for (const line of block.split('\n')) {
+    const match = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(line.trim())
+    if (!match) continue
+    let value = match[2].trim()
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1)
+    }
+    metadata[match[1]] = value
+  }
+  return { metadata, body }
+}
+
+/**
+ * Read and parse one skill directory's SKILL.md.
+ * @param skillFile - absolute path to the SKILL.md file.
+ * @param signal - optional cancellation; aborts the read.
+ * @returns the parsed skill record, or undefined when the file vanished.
+ */
+async function parseSkillFile(skillFile, signal) {
+  let text
+  try {
+    text = await readFile(skillFile, 'utf8')
+  } catch {
+    return undefined
+  }
+  if (signal?.aborted) return undefined
+  const parsed = parseFrontmatter(text)
+  if (parsed === null) return undefined
+  return {
+    name: parsed.metadata.name ?? '',
+    description: parsed.metadata.description ?? '',
+    whenToUse: parsed.metadata.whenToUse,
+    metadata: parsed.metadata,
+    content: parsed.body
+  }
+}
+
+/**
+ * Upstream `disable-model-invocation: true` marks a user-invoked skill
+ * (reachable only by the human). Map it onto DSH's invocation flags;
+ * anything else stays model- and user-invocable.
+ * @param metadata - parsed frontmatter metadata.
+ * @returns the DSH invocation record.
+ */
+function invocationFrom(metadata) {
+  if (metadata['disable-model-invocation'] === 'true') {
+    return { modelInvocable: false, userInvocable: true }
+  }
+  return { modelInvocable: true, userInvocable: true }
+}
+
+/**
+ * Discover packaged skill candidates by scanning the package's `skills/`
+ * directory: one subdirectory per skill, each carrying a SKILL.md.
+ * @param skillsRoot - absolute path to this package's skills directory.
+ * @param signal - optional cancellation.
+ * @returns the candidate list.
+ */
+async function discoverCandidates(skillsRoot, signal) {
+  let entries
+  try {
+    entries = await readdir(skillsRoot, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const candidates = []
+  for (const entry of entries) {
+    if (signal?.aborted) break
+    if (!entry.isDirectory()) continue
+    const skillDir = join(skillsRoot, entry.name)
+    const skillFile = join(skillDir, 'SKILL.md')
+    const parsed = await parseSkillFile(skillFile, signal)
+    if (parsed === undefined) continue
+    candidates.push({
+      name: parsed.name,
+      description: parsed.description,
+      ...(parsed.whenToUse !== undefined ? { whenToUse: parsed.whenToUse } : {}),
+      invocation: invocationFrom(parsed.metadata),
+      source: SOURCE,
+      provider: name,
+      rank: PACKAGED_SKILL_RANK,
+      locator: skillDir,
+      path: skillFile,
+      ...(Object.keys(parsed.metadata).length > 0 ? { metadata: parsed.metadata } : {})
+    })
+  }
+  return candidates
+}
+
+/** Register the packaged matt-pocock provider on `ctx.skills`. */
+function apply(ctx) {
+  const skillsRoot = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills')
+  ctx.skills.registerProvider((control) => ({
+    name,
+    async list(options) {
+      return discoverCandidates(skillsRoot, options.signal)
+    },
+    async get(candidate, options) {
+      const parsed = await parseSkillFile(candidate.path, options.signal)
+      if (parsed === undefined) return undefined
+      return {
+        name: parsed.name,
+        description: parsed.description,
+        ...(parsed.whenToUse !== undefined ? { whenToUse: parsed.whenToUse } : {}),
+        invocation: invocationFrom(parsed.metadata),
+        source: SOURCE,
+        provider: name,
+        resourceBase: { kind: 'directory', path: candidate.locator },
+        path: candidate.path,
+        ...(Object.keys(parsed.metadata).length > 0 ? { metadata: parsed.metadata } : {}),
+        content: parsed.content
+      }
+    }
+  }))
+}
+
+export { apply, name, inject }
+export default { apply, name, inject }

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "mattpocock-skills-dsh",
+  "description": "Matt Pocock's skills for the DeepSeek Harness: grilling, writing-for-agents, wait-what and more — adapted from https://github.com/mattpocock/skills",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "skills",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gongyijie85/mattpocock-skills-dsh.git"
+  },
+  "homepage": "https://github.com/gongyijie85/mattpocock-skills-dsh",
+  "bugs": {
+    "url": "https://github.com/gongyijie85/mattpocock-skills-dsh/issues"
+  },
+  "scripts": {
+    "verify": "node scripts/verify-provider.mjs",
+    "prepublishOnly": "node scripts/verify-provider.mjs"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "skills",
+    "mattpocock",
+    "aihero"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/skills/ask-matt/PHASE-BOUNDARIES.md

@@ -0,0 +1,60 @@
+# Phase boundaries
+
+> DSH port note: `/clear` and `/compact` below are Claude Code session
+> commands, not skills in this pack. In DeepSeek Harness, `/clear` maps to
+> starting a fresh session and `/compact` has no direct equivalent — carry
+> the summary into a new session manually when context runs low.
+
+A **phase** is a chunk of work inside a session — the grilling, the implementation, the QA. The definition is fuzzy on purpose: a phase ends when you think *"ok, we're done with that"*.
+
+The **phase boundary** is the gap between two phases, and it is the only place this decision belongs. Mid-phase there is no decision to make — continue, or split the work that's left into subagents. Compacting mid-phase makes the agent lose the thread.
+
+## The five options
+
+| Option       | What it does                                                    |
+| ------------ | --------------------------------------------------------------- |
+| **Continue** | Stay in the session. No context switch at all.                    |
+| **`/clear`** | Empty the context window and start from nothing.                  |
+| **`handoff`** | Write a portable markdown file and seed a session anywhere with it. |
+| **Subagent** | Send the task to its own context window and get a report back.     |
+| **`/compact`** | Compress this context and seed a fresh session with the summary.  |
+
+## The tree
+
+Work top to bottom at the boundary. The first **yes** wins.
+
+**1. Can you continue in this session?** Two things make the answer yes: the next phase needs this phase as a **primary source**, or you have enough [smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone) left (~150k tokens) for the next phase to fit. Grilling → implementation is the standard yes: the implementation wants the reasoning verbatim, not a summary of it. Continue costs nothing and loses nothing, so rule it out before anything else.
+
+**2. Is the context irrelevant to what comes next?** Is everything in this session — the exploration, the decisions, the dead ends — disposable? 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.
+
+The cost of getting this wrong is one-way. Clear a *relevant* context and you lose the **why** behind what you built, and no amount of reading the diff back gets it returned.
+
+**3. Do you need to hand off?** `handoff` is narrow. You need it only when you are:
+
+- swapping to a **new harness** (Claude → Codex),
+- moving to a **new directory** or repo,
+- sending the work to a **colleague**,
+- or forking a side task you found **mid-phase** without derailing what you're doing.
+
+That list is the whole clause. What `handoff` buys is **portability** — a file that travels. If nothing is travelling, you don't need it.
+
+**4. Can the task be done AFK?** Is it scoped tightly enough to run with you away from the keyboard, no steering? Then send it to a **subagent** and leave this session untouched. Automated review is the standard case: the agent reads the diff and reports, and you aren't needed while it does.
+
+**5. Otherwise, `/compact`.** Relevant context, same harness, same directory, and you need to stay in the loop — this is where the tree lands, and it lands here often. Pass it an instruction (`/compact we're going to QA this area`) so the summary keeps what the next phase needs.
+
+`/compact` is the **default, not the first reach**. It sits at the bottom because the four questions above it are all cheaper or more precise. The failure mode when people start here is a fresh session that is confidently wrong about a decision the summary flattened.
+
+## Primary and secondary sources
+
+Every move except **Continue** turns a **primary source** into a **secondary source** — the session as it happened, replaced by a summary of it. The trade is always the same shape:
+
+| Source                            | Information | Noise | Room to move |
+| --------------------------------- | ----------- | ----- | ------------ |
+| Primary (Continue)                | Full        | Lots  | Little       |
+| Secondary (`/compact`, `handoff`) | Lossy       | Less  | Lots         |
+
+This is why question 1 comes first. You only pay the lossiness when staying costs more than it saves.
+
+## These are judgement calls
+
+The questions are not objective — each has taste in it, and the same boundary can go two ways on two days. The value is in asking them **in order**, at the boundary rather than in the middle of the work.

package/skills/ask-matt/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: ask-matt
+description: Ask which skill or flow fits your situation. A router over the skills in this repo.
+disable-model-invocation: true
+---
+
+# Ask Matt
+
+You don't remember every skill, so ask.
+
+A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.
+
+## The main flow: idea → ship
+
+The route most work travels. You have an idea and want it built.
+
+1. **`grill-with-docs`** — sharpen the idea by interview. Start here whenever you are **working in a working directory**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No working directory? Use `grill-me` — see Standalone. Both run the same `grilling` primitive; `grill-with-docs` is the one that leaves a paper trail, which makes it the better of the two whenever a repo is there to leave it in.)
+2. **Branch — can you settle every question in conversation?** If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by **`handoff`** in both directions (a prototype lives in its own directory, which is exactly what `handoff` is for — see Phase boundaries):
+   - **`handoff`** out, then open a fresh session against that file,
+   - **`prototype`** to answer the question with throwaway code,
+   - **`handoff`** back what you learned, and reference it from the original idea thread.
+3. **Branch — is this a multi-session build?**
+   - **Yes** → **`to-spec`** (turn the thread into a spec), then **`to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's one file per ticket under `.scratch/<feature>/issues/`, worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`implement`** per ticket, **`/clear`ing context between each one**. Each ticket is self-contained, so the last one's context is disposable.
+   - **No** → **`implement`** right here, in the same context window.
+
+   Either way, **`implement`** builds each issue by driving **`tdd`** internally — one red-green slice at a time — then closes out by running **`code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`code-review`** on its own whenever you want to review a branch or PR against a fixed point.
+
+### Context hygiene
+
+Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `to-tickets` — so the grilling, spec, and tickets all build on the same thinking. Each `implement` then starts fresh, working from the ticket.
+
+The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~150k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `to-tickets`, don't push on degraded — `/compact` at the nearest phase boundary and carry on (see Phase boundaries).
+
+## On-ramps
+
+A starting situation that generates work, then merges onto the main flow.
+
+- **Bugs and requests piling up** → **`triage`**. It moves issues through triage roles and produces agent-ready issues, which **`implement`** later picks up.
+
+  Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Tickets that `to-tickets` produced are already agent-ready, so **don't triage them**.
+
+- **Something's broken** → **`diagnosing-bugs`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. It refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`improve-codebase-architecture`** when the real finding is that there's no good seam to lock the bug down.
+
+- **A huge, foggy effort — a greenfield project or a huge feature build, too big for one session** → **`wayfinder`**, the most cognitively demanding flow here. When the way from here to the destination isn't visible yet, it charts a **shared map** of **decision tickets** on the issue tracker and resolves them one at a time — producing **decisions, not deliverables** — until the fog is pushed back and the way is clear. Where **`grill-with-docs`** sharpens an idea you can hold in one session, wayfinder is for the idea you can't — and it's slower and denser, so save it for exactly that, never a well-scoped feature.
+
+  When the map clears, **it hands off, it doesn't build**: merge onto the main flow at **`to-spec`**, which collapses the map's linked decisions into a buildable plan, then `to-tickets` and `implement` as usual. Looping the map straight into `implement` skips that collapse and throws the linked detail away — go straight to `implement` only when the effort turned out genuinely small.
+
+## Codebase health
+
+Not feature work — upkeep.
+
+- **`improve-codebase-architecture`** — run whenever you have a spare moment to keep the codebase good for agents to operate in. It surfaces **deepening opportunities**; picking one _generates an idea_ you can take into the main flow at `grill-with-docs`. It's the survey that finds the candidates; **`codebase-design`** (below) is the bench you design the chosen one on.
+
+## Vocabulary underneath
+
+Two model-invoked references that run *beneath* the other skills — each the single source of truth for its vocabulary. Reach for them directly when the **words**, not the process, are the problem; or let the skills above pull them in.
+
+- **`domain-modeling`** — sharpen the project's *domain* language: challenge a fuzzy term, resolve an overloaded word ("account" doing three jobs), record a hard-to-reverse decision as an ADR. It's the active discipline `grill-with-docs` drives to keep `CONTEXT.md` a clean glossary.
+- **`codebase-design`** — the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing a module's *shape*: a lot of behaviour behind a small interface at a clean seam. `tdd` and `improve-codebase-architecture` both speak it.
+
+## Phase boundaries
+
+A **phase** is a chunk of work inside a session — the grilling, the implementation, the QA. At the **boundary** between two of them you have five options, and picking between them is the fuzziest decision in this whole map:
+
+- **Continue** — stay put. Costs nothing, loses nothing.
+- **`/clear`** — empty the window, when nothing here matters to what's next.
+- **`handoff`** — write a portable markdown file. Narrow: only for a **new harness**, a **new directory**, a **colleague**, or forking a side task **mid-phase**. What it buys is portability.
+- **Subagent** — send a tightly-scoped task to its own window and get a report back.
+- **`/compact`** — compress this context and seed a fresh session with it. The **default**, at the bottom of the tree rather than the first reach.
+
+Read [PHASE-BOUNDARIES.md](PHASE-BOUNDARIES.md) for the ordered tree — the five questions, the reasoning behind each branch, and why the primary-source cost makes **Continue** the one to rule out first. Make the decision **at** a boundary; mid-phase, continue or split the rest into subagents.
+
+## Standalone
+
+Off the main flow entirely.
+
+- **`grill-me`** — the same relentless interview as `grill-with-docs`, but **stateless**: it saves nothing locally and builds no `CONTEXT.md`. Reach for it when you are **not working in a working directory** — sharpening a plan, a design, a piece of writing, anything with no repo under it. If you are in a working directory, use `grill-with-docs` instead: it runs the same interview and leaves a paper trail, so it is strictly the better one.
+- **`grilling`** — the interview primitive itself: rounds, the frontier, facts are the agent's job and decisions are yours. `grill-me` and `grill-with-docs` are the two named ways in, and `triage`, `wayfinder` and `improve-codebase-architecture` all run it internally. Reach for it directly only when you want the interview with no wrapper around it.
+- **`resolving-merge-conflicts`** — work an in-progress merge or rebase conflict hunk by hunk, resolving by **intent** traced to each side's primary source rather than by picking lines, then finish the operation. It never runs `--abort`. Standalone and off every flow: reach for it when you are already mid-conflict.
+- **`prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway is a constraint on how the code is written, not a promise to destroy it: the answer folds into the real code, and the prototype itself is kept as a **primary source** on a `prototype/<name>` branch out of main, pointed at from the implementation issue. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
+- **`research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `grill-with-docs` — research feeds the thinking, it doesn't replace it.
+- **`to-questionnaire`** — when the thing blocking you isn't in your head or the codebase but in **someone else's**, this writes them a questionnaire to fill in. It's the inverse of `grill-me`: instead of interviewing you about the subject, it interviews you about the **send** — who it's going to, what you need back — and aims the questions at the gap. What comes back is material for `grill-with-docs` or `to-spec`.
+- **`wizard`** — for the steps only a **human** can take: provisioning infrastructure, setting up credentials or CI secrets, clicking through an unfamiliar third-party dashboard, running a one-off migration or cutover. It generates an interactive bash script that opens each URL, captures each value, and writes it into `.env` and GitHub secrets — so the procedure stops being something you re-explain to an agent every time. Model-invoked, so the agent reaches for it the moment it hits a wall only you can pass. If the agent could just do it itself, it should; this is for where a human is genuinely in the loop.
+- **`wait-what`** — the corrective for a message that didn't land. Use it mid-conversation, inside any other skill, and the agent re-pitches what it just said with the context you were missing, in plain English, using the `CONTEXT.md` vocabulary. It works after the fact; `grill-with-docs` is the upfront cure, because a shared language agreed early is what stops the jargon arriving at all.
+- **`teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace.
+- **`writing-for-agents`** — reference for writing documents agents consume: skills, AGENTS.md, pointed-at docs.
+
+## Precondition
+
+**`setup-matt-pocock-skills`** — run before your first engineering flow to configure the issue tracker, triage labels, and doc layout the other skills assume. Custom issue trackers also work.