pstack-dsh 0.2.3

package/HARNESS.md

@@ -0,0 +1,109 @@
+# DSH harness map
+
+This port carries pstack 0.15's 23 playbooks and 23 principles, with DSH call sites and model-invocable principles. See [UPGRADE-0.15.md](./UPGRADE-0.15.md) for the pinned upstream source and excluded runtime changes.
+
+Sources: official pstack (`cursor/plugins` `pstack/`) and official DeepSeek Harness (`deepseek-ai/deepseek-harness`). Tool names and fields below are from DSH source, not from Cursor `Task` and not from grok-build `task`.
+
+Sister port [pstack-grokbuild](https://github.com/aa2246740/pstack-grokbuild) is process lessons only. Do not copy its call sites.
+
+Workbench: [dshx](https://github.com/aa2246740/dsh-external-plugin-devkit) (`dshx kb cat start-here`). Official DSH source outranks dshx. dshx is not a DSH fork and not Creator Mode.
+
+## Verdict
+
+**Yes. The discipline ports. Cursor and Grok runtimes do not.**
+
+Install this repo as a DSH plugin on official DeepSeek Harness **0.1.5-rc.3** (`@deepseek-ai/dsh@0.1.5-rc.3`). `@deepseek-ai/dsh-*` peers are `^0.1.5-rc.3`. Do not write `~/.cursor/rules`. Do not invent Cursor panel slugs. Do not send grok `task` fields. Out of the box, children inherit this conversation's route. Configure roles in **Settings → pstack**. `/setup-pstack` is an optional pointer.
+
+Official model-facing `subagent` cannot take a pstack role or a per-call model. This plugin registers `pstack_spawn`, which calls `ctx.subagents.start` / `startContinuable` on the shipped `spawn` provider and applies overlay route plus effort on the `agent/request` waterfall.
+
+## Mapping: pstack need → DSH API
+
+| pstack need | DSH API | Source |
+|---|---|---|
+| Slash skill / poteto-mode | `ctx.skills` provider + `dsh-tool-skill` `skill` tool. User `/name` injection. Frontmatter: kebab-case `name`, `description`, optional `whenToUse`, `disable-model-invocation`, `user-invocable`. `name: Poteto Mode` is invalid; this port uses `poteto-mode`. | `packages/skill/tool-skill/README.md`; `docs/subsystems/skills.md`; `packages/skill/skill-filesystem/README.md`; `packages/skill/skill/src/index.ts` `SKILL_NAME` `/^[a-z0-9]+(?:-[a-z0-9]+)*$/` |
+| Plugin install | npm bundle `dsh.bundle.patch` → `dsh plugin --profile web add github:aa2246740/pstack-dsh` (pnpm, then restart Host and reload) | `docs/user/develop/basic/publish.md` |
+| Settings GUI | Official **`settings.section`** list slot. This plugin registers id `pstack`, order 16, nav from `ctx.locale` (zh/en). Browser `dsh.client` + Host `GET`/`PUT` `/plugins/pstack-dsh/settings` on `ctx.webServer`. Overlay file unchanged. **Hypothesis:** slash skills cannot call `openSection`; that method is onboarding-only on `SettingsRoot`. | `packages/client/ui-settings/src/client/contract/slots.ts` `settings.section`; `packages/client/ui-settings-models/src/client/index.ts`; `packages/client/ui-settings-plugins/src/client/index.ts`; `packages/client/ui-settings-general/src/client/SettingsRoot.tsx` `openSection`; `packages/host/webserver/src/index.ts` `webServer.register`; dsh-oauth-login `src/client/index.tsx` |
+| Spawn child | Model-facing official tool **`subagent`**: only `description`, `prompt`, `run_in_background`. No model, effort, isolation, `subagent_type`. This plugin's **`pstack_spawn`**: those three plus `role` and optional `route_index`. Internally `ctx.subagents.start('spawn', …)` / `startContinuable`. | `docs/tool-catalog.md` `#deepseek-aidsh-tool-subagent`; `packages/subagent/tool-subagent/src/index.ts`; `packages/bundle/base/cordis.patch.yml` `providerName: spawn`, `toolName: subagent`, `backgroundMode: continuable` |
+| Per-child model | `AgentOptions` `{ provider?, model?, maxTokens? }` on `SubagentStartRequest.agentOptions`. Not a model-facing `subagent` field. "Another model requires another named tool instance" unless a plugin sets `agentOptions` at start. Overlay maps a logged-in route onto that object. Omit it to inherit the parent. | `packages/core/agent/src/runtime-types.ts` `AgentOptions`; `packages/subagent/subagent/src/types.ts` `SubagentStartRequest.agentOptions`; `packages/subagent/tool-subagent/README.md` Config `agentOptions` |
+| Per-role reasoning effort | **Not on `subagent`.** `LlmCallConfig.reasoningEffort` via the `agent/request` waterfall. Adapter-owned via `resolveModelInfo().reasoning.efforts`. Empty efforts: omit. Never copy grok `xhigh/high/medium/low` or Cursor `max` unless that exact id is on **this** route. | `packages/llm/llm/src/call-config.ts` `LlmCallConfig`; `packages/llm/llm/src/types.ts` `LlmModelReasoningInfo`; `packages/core/agent/src/runtime-types.ts` `'agent/request'`; `packages/llm/llm/src/index.ts` `resolveModelInfo` rejects invalid effort metadata |
+| Wait | Continuable: settlement notice + `send_message`. One-shot background: `job_output`. Foreground: the tool awaits `run.result`. | tool-subagent README; `docs/tool-catalog.md` jobs / subagent-control |
+| Cancel | Continuable: `interrupt_agent`. Jobs: `job_kill`. | `docs/tool-catalog.md` `#deepseek-aidsh-tool-subagent-control`, `#deepseek-aidsh-tool-jobs` |
+| Isolation / worktree / Cursor cloud | **No field** on `subagent`. Spawn-in-process inherits parent cwd. Drop `environment: "cloud"`. Parent may `git worktree add` and put the path in the prompt. | `packages/subagent/subagent-spawn-in-process/README.md` |
+| Nested spawn | Default `maxDepth` **3** (tool-subagent Config). Playbooks that used nested Cursor Task + worktree still prefer parent-owned fan-out so isolation stays in the prompt. | `packages/subagent/tool-subagent/src/index.ts` `maxDepth` default `3` |
+| Todo | `todo_write({ todos: [{ content, status }] })` wholesale replace. Status: `pending` \| `in_progress` \| `completed`. **No** `id`, `merge`, `cancelled`. | `packages/todo/tool-todo/README.md` |
+| Ask human | `ask_user_question` | `packages/interaction/tool-ask-user/README.md` |
+| Overnight /loop | **No** grok `scheduler_create`. Closest shipped tools: `create_goal` / `update_goal` (`dsh-tool-goal`). If those tools are absent, keep iterating in this chat; do not invent a scheduler. | `docs/tool-catalog.md` `#deepseek-aidsh-tool-goal` |
+| Credentials (presence only) | `ctx.credentials.describe(ref)` → `{ configured }` never the value | `packages/credentials/credentials/README.md` |
+| DSH home | `$DSH_HOME`, else `~/.dsh` | `packages/util/home-paths/README.md` |
+| DeepSeek default key ref | `DEEPSEEK_API_KEY` on provider `deepseek-official` | `packages/llm/llm-deepseek/src/index.ts` `DEFAULT_API_KEY_ENV`, `PROVIDER` |
+| OAuth store (peer, not required) | `$DSH_HOME/.dsh-oauth-auth.json` (legacy `.pi-login-auth.json`). Map store ids → `pi-*` routes from [dsh-oauth-login](https://github.com/aa2246740/dsh-oauth-login). Do not read `~/.pi`, `~/.codex`, `~/.claude`, grok CLI login. | dsh-oauth-login `src/ids.ts`, `src/catalog.ts` |
+| Independent verify | Parent `pstack_spawn` `role: independent-verifier`. Second opinion is a different logged-in route when overlay mapped one; otherwise inherit. The verifier does not write the diff. | this file |
+| `cursor-team-kit` (`deslop`, `control-ui`, `control-cli`) | Not shipped. `/unslop` and `/no-comments` remain. Drive the real app (browser, CLI, tests). | official pstack README "not shipped here" |
+| Benny automations | Cursor automation pack. Left under `automations/` as source, not a DSH runtime. | pstack `automations/` |
+| Graphite `gt` | Optional if `gt` is on PATH. Otherwise `gh` + git. | playbooks |
+
+## Official `subagent` fields the model may send
+
+From `docs/tool-catalog.md` `#deepseek-aidsh-tool-subagent` (generated from a booted plugin, not a guess):
+
+- `description` (string, required)
+- `prompt` (string, required)
+- `run_in_background` (boolean, optional)
+
+Do not send `model`, `provider`, `reasoning_effort`, `thinking`, `isolation`, `subagent_type`, `environment`, `readonly`, `resume_from`. They are not on this schema.
+
+Shipped `subagent` is continuable and defaults omitted `run_in_background` to background. Shipped `subagent_fork` is one-shot and defaults to foreground. This plugin talks to `spawn`, not `fork`.
+
+## Default spawn shape
+
+Parent session only:
+
+```text
+pstack_spawn
+  description: <3-5 words>
+  prompt: <full brief, file pointers not inlined dumps>
+  role: <pstack role key, e.g. feature | how-explainer | independent-verifier | poteto-agent | comment-sicko>
+  run_in_background: true
+  route_index: <only for panel roles when overlay has more than one route; default 0>
+```
+
+Do not send model or effort on that call. Route and effort come from `$DSH_HOME/pstack-dsh.json` when that role is mapped to a live logged-in route; otherwise the child inherits this conversation.
+
+If `pstack_spawn` is missing, fall back to official `subagent` with only `description`, `prompt`, `run_in_background`. That path inherits the parent and cannot apply the overlay.
+
+Then wait on the settlement notice (continuable) or `job_output` (one-shot). Cancel with `interrupt_agent` or `job_kill`.
+
+Code-writing delegates: the playbook role key (`feature`, `bug-fix`, …). Ad-hoc helpers with no role key: `poteto-agent`. `/no-comments`: `comment-sicko`. Independent verify: `independent-verifier`.
+
+## Effort home (hypothesis, labeled)
+
+**Store:** `$DSH_HOME/pstack-dsh.json` `roles.<key>.routes[].reasoningEffort`, only when `resolveModelInfo(provider, model).reasoning.efforts` lists that id.
+
+**Apply:** `ctx.on('agent/request', …)` replaces `LlmCallConfig` for the child session id remembered at spawn. `AgentOptions` has no effort field, so spawn-time `agentOptions` can set provider/model only.
+
+If a future DSH build stops firing host-level `agent/request` for in-process children, inherit-parent still works; mapped effort would not. Do not invent a spawn-tool field to paper over that.
+
+## What Settings → pstack / `/setup-pstack` may list
+
+The Settings page is the editor. It reads and writes `$DSH_HOME/pstack-dsh.json` through the same `buildCatalog` / overlay modules spawn uses. `/setup-pstack` only tells the user to open that page.
+
+Only:
+
+1. Registered `ctx.llm` adapters whose API key `credentials.describe(ref).configured` is true (settings `apiKeyEnv` walk, plus `DEEPSEEK_API_KEY` for `deepseek-official`).
+2. Routes already in the dsh-oauth-login store **and** registered as `pi-*` adapters.
+
+Empty catalog: inherit parent. Tell the user to add a key or install/login [dsh-oauth-login](https://github.com/aa2246740/dsh-oauth-login). Do not block. Do not show a vendor catalog.
+
+## What this port dropped
+
+| Cursor / Grok field | Why dropped |
+|---|---|
+| `Task.model` / Cursor panel slugs | Not on DSH `subagent`. Never invent slugs. |
+| `Task.subagent_type` | DSH has no such field. Role is `pstack_spawn.role`. |
+| `Task.isolation` / `environment: "cloud"` | No isolation field. Parent worktree + path in prompt. |
+| grok `task.reasoning_effort` | Not on grok `task` either; also not on DSH `subagent`. |
+| grok `~/.grok/roles` | DSH does not use that tree. Overlay is `$DSH_HOME/pstack-dsh.json`. |
+| Cursor `~/.cursor/rules/pstack-models.mdc` | Cursor-only. |
+| grok `scheduler_create` / Cursor `/loop` | Not in DSH. Use `create_goal` when present. |
+| grok `get_task_output` | DSH settlement notice / `job_output`. |
+| Cursor `AskQuestion` / `TodoWrite` | DSH `ask_user_question` / `todo_write`. |

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Lauren Tan
+Copyright (c) 2026 aa2246740
+
+Official pstack playbooks and principles: Lauren Tan (poteto).
+DeepSeek Harness port packaging and harness mapping: aa2246740 / pstack-dsh.
+
+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,168 @@
+# official pstack 的 DeepSeek Harness 移植
+
+## 安装 / Install
+
+### 官方 DeepSeek Harness 桌面 App（推荐） / Desktop app (recommended)
+
+打开 **设置 → 插件 → 添加插件**，在“包名或地址”中输入：
+
+Open **Settings → Plugins → Add plugin** and enter this in “Package name or address”:
+
+```text
+github:aa2246740/pstack-dsh#v0.2.3
+```
+
+桌面端插件管理器负责 Desktop profile 和内置包管理器。本发布已包含编译好的 `lib/`；普通使用不需要 clone 或本地构建。若应用提示刷新或重新打开，请按提示完成。
+
+The desktop plugin manager owns the Desktop profile and bundled package manager. This release includes built `lib/`; normal use needs no clone or local build. Follow the app if it asks you to reload or reopen after installation.
+
+### Web CLI
+
+```sh
+dsh plugin --profile web add github:aa2246740/pstack-dsh#v0.2.3
+```
+
+这条官方 CLI 命令只写入 `web` profile，不能修改 Desktop App 的 profile。对于已运行的 Web Host，请重新打开该 Host 一次，再刷新网页。
+
+This official CLI command writes only the `web` profile; it cannot modify the Desktop App profile. For an already-running Web Host, reopen that Host once and reload the page.
+
+面向官方 DeepSeek Harness **0.2.0-rc.2**（tag `dsh-v0.2.0-rc.2`，npm `@deepseek-ai/dsh@0.2.0-rc.2`）。Node `^22.19.0` 或 `>=24`。`@deepseek-ai/dsh-*` peer 范围是 `>=0.2.0-rc.1 <0.2.1`，接受 `0.2.0-rc.2`，拒绝 `0.1.7` alpha。
+
+Targets official DeepSeek Harness **0.2.0-rc.2** (tag `dsh-v0.2.0-rc.2`, npm `@deepseek-ai/dsh@0.2.0-rc.2`). Node `^22.19.0` or `>=24`. The `@deepseek-ai/dsh-*` peer range is `>=0.2.0-rc.1 <0.2.1`: it accepts `0.2.0-rc.2` and rejects `0.1.7` alphas.
+
+**English title.** pstack-dsh, a DeepSeek Harness port of official pstack.
+
+**中文.** 这是 official pstack 的 DeepSeek Harness 移植。玩法和原则来自 poteto 的 official pstack；只有调用层换成 DSH。
+
+**English.** This is a DeepSeek Harness port of official pstack. Playbooks and principles are poteto's. Only the harness call layer is swapped.
+
+## 来源 / Credits
+
+23 个玩法（playbooks）和 23 条原则（principles）是 [poteto](https://x.com/poteto) 写的，出自 [official pstack](https://github.com/cursor/plugins/tree/main/pstack)。本仓库是 DeepSeek Harness 移植（[aa2246740/pstack-dsh](https://github.com/aa2246740/pstack-dsh)）。调用层用 [HARNESS.md](./HARNESS.md) 里的 DSH 工具名。玩法和原则不是本仓库写的。
+
+The 23 playbooks and 23 principles are [poteto](https://x.com/poteto)'s, from [official pstack](https://github.com/cursor/plugins/tree/main/pstack). This repository is the DeepSeek Harness port ([aa2246740/pstack-dsh](https://github.com/aa2246740/pstack-dsh)). Harness calls use DSH tools named in [HARNESS.md](./HARNESS.md). This port did not author those playbooks or principles.
+
+## 本地目录 / Local checkout
+
+已经 clone 到本机时（开发/本地测试）：
+
+A local checkout (development/local testing):
+
+```sh
+git clone https://github.com/aa2246740/pstack-dsh.git
+dsh plugin --profile web add ./pstack-dsh
+```
+
+然后同样重启 Host，再刷新页面。
+
+Then restart that Host and reload the page.
+
+```sh
+dsh plugin --profile web remove pstack-dsh
+```
+
+Desktop App 请使用上面的应用内“添加插件”入口。官方 CLI 只管理 `web` profile。
+
+Use the in-app “Add plugin” entry above for the Desktop App. The public CLI manages the `web` profile only.
+
+## 开始用 / Get started
+
+两步。
+
+Two steps.
+
+1. 要做事、要严谨，直接用 [`/poteto-mode`](./skills/poteto-mode/SKILL.md)。不用先跑 setup。子 agent 默认继承当前对话的路由。
+2. 只有想给某个角色换已登录的路由时，打开 **设置 → pstack**（导航「pstack 角色」/「pstack roles」）。页面写入 `$DSH_HOME/pstack-dsh.json`。[`/setup-pstack`](./skills/setup-pstack/SKILL.md) 只是指向那一页的指针。
+
+1. Use [`/poteto-mode`](./skills/poteto-mode/SKILL.md) for work that needs rigor. No setup required. Children inherit this conversation's route.
+2. To pin a logged-in route per role, open **Settings → pstack** (nav label **pstack 角色** / **pstack roles**). The page writes `$DSH_HOME/pstack-dsh.json`. [`/setup-pstack`](./skills/setup-pstack/SKILL.md) is an optional pointer to that page.
+
+角色模型列表会随 DSH 的登录、退出登录和模型目录变更通知更新，也可点击「刷新模型列表」。刷新只更新候选项，不覆盖尚未保存的角色和 effort；当前选择若失去登录会标为「暂不可用」。新加入 dsh-oauth-login 的 `pi-*` 路由以及 dsh-antigravity-oauth 的 `agy-*` 路由只要已登录且已注册，就会自动纳入，无需在 pstack 里再维护一份提供商名单。
+
+Model choices follow DSH login/logout and catalog notifications. **Refresh models** also updates the choices without replacing unsaved role/effort edits. A selected route that becomes unavailable stays visibly marked. Newly registered, signed-in `pi-*` and `agy-*` routes are discovered without a second provider allowlist.
+
+第一次用可以看 [pstack 指南](./docs/guide/README.md)。
+
+New here? The [pstack guide](./docs/guide/README.md) walks through a first real task.
+
+其余技能是按需的。`/poteto-mode` 会在步骤需要时自己去调。
+
+The other skills are situational. The mode skill uses them when a step needs them.
+
+## 上游 0.15 同步
+
+技能内容同步至 `cursor/plugins` 的 pstack 0.15.0，提交 `71ed0d1076fec562c1b74ee353121a8d00f75382`。保留 DSH 工具和角色路由。
+
+设置页的「Poteto 0.15 推荐」仅供参考，不会替换用户已保存的模型或 effort。`how-critics` 不再显示或启动代理，旧配置仍可读写并保留。不包含 Cursor 专用的 make-bot-ui。
+
+The Poteto 0.15 recommendations are display-only. Existing model and effort assignments remain unchanged. The retired `how-critics` setting stays readable for compatibility but is hidden and never starts an agent. Cursor-only make-bot-ui is not included.
+
+## 默认模型与 effort / Defaults
+
+装完就能用，不必先打开设置，也不必跑 `/setup-pstack`。
+
+A fresh install is usable without Settings → pstack and without `/setup-pstack`.
+
+**模型 / Model.** 不要发送 `model`，除非 live catalog 里已经有这一条。没有 overlay 就继承父对话。不要编造 Cursor 面板 slug（`grok-4.6-fast-xhigh`、`gpt-5.6-sol-max`、`claude-fable-5-thinking-max`、`claude-opus-5-thinking-xhigh`）。
+
+Do not send `model` unless that pair was detected live. Missing overlay inherits the parent. Do not invent Cursor panel slugs.
+
+**effort.** 只提供该路由 `resolveModelInfo().reasoning.efforts` 列出的 id。没有 effort 字段就省略。skill 从不在 spawn 上发送 `reasoning_effort` 或 `thinking`。官方 `subagent` schema 没有这些字段。角色 effort 写在 overlay 里，由 `agent/request` 落到 `LlmCallConfig.reasoningEffort`。
+
+Effort is only the ids that route actually accepts. If the route has none, omit it. Skills never send `reasoning_effort` or `thinking` on spawn. Official `subagent` has no such field. Role effort lives in the overlay and is applied on `agent/request`.
+
+**设置 / Settings.** 配置页是官方 Settings 里的 `settings.section`（id `pstack`，order 16）。只列出已登录路由；effort 只列出该路由 live `resolveModelInfo().reasoning.efforts`。空列表就是继承父对话。保存写同一份 overlay，不是第二份配置。
+
+The editor is the official Settings `settings.section` (id `pstack`, order 16). It lists logged-in routes only. Effort options are that route's live `resolveModelInfo().reasoning.efforts`. An empty list means inherit the parent. Save writes the same overlay, not a second file.
+
+设置页只列出已经登录的 API key 路由，以及 dsh-oauth-login / dsh-antigravity-oauth 里已经签过名、并且适配器已注册的路由。空目录就是继承父对话。
+
+## 推荐依赖 / Recommended peer
+
+订阅与服务登录（ChatGPT / Claude / Grok / Copilot / OpenRouter / Kimi / Google Antigravity）要出现在 **设置 → pstack** 列表里，可按需安装 [dsh-oauth-login](https://github.com/aa2246740/dsh-oauth-login) 或 dsh-antigravity-oauth。不是硬依赖。只用 API key 的用户可以不装。本插件不读写 `~/.pi`、`~/.codex`、`~/.claude`、grok CLI 登录文件。
+
+Subscription logins show up on **Settings → pstack** after you install [dsh-oauth-login](https://github.com/aa2246740/dsh-oauth-login) or dsh-antigravity-oauth. They are not required. API-key-only users work without them. This plugin does not read or write official CLI auth files.
+
+```sh
+dsh plugin --profile web add github:aa2246740/dsh-oauth-login#v0.2.7
+```
+
+## 这不是 Cursor 插件 / Not the Cursor plugin
+
+这里的角色映射在 **设置 → pstack**。官方 Cursor `/setup-pstack` 会写 `~/.cursor/rules`，并用 Cursor 的模型名。不要在 DSH 上跑那份。
+
+Role mapping in this repo is **Settings → pstack**. Official Cursor `/setup-pstack` writes `~/.cursor/rules` and uses Cursor slugs. Do not run it here.
+
+## 工具 / Tools
+
+本插件注册：
+
+This plugin registers:
+
+| 工具 / Tool | 作用 / Role |
+|---|---|
+| `pstack_spawn` | 按角色起 DSH 子 agent。不要传 model / effort。 |
+| `pstack_catalog` | 只列出已登录的 live 路由。 |
+| `pstack_overlay_read` / `pstack_overlay_write` | 读写 `$DSH_HOME/pstack-dsh.json`。 |
+| Settings → pstack | 官方设置页。保存同一份 overlay。 |
+
+技能入口：`/poteto-mode`，以及 bundled 的 playbook / principle skills。[`/setup-pstack`](./skills/setup-pstack/SKILL.md) 指向设置页。
+
+Slash entry: `/poteto-mode`, plus the bundled playbook and principle skills. [`/setup-pstack`](./skills/setup-pstack/SKILL.md) points at the Settings page.
+
+## 开发 / Develop
+
+```sh
+pnpm install
+pnpm test
+```
+
+不要对用户正在用的 DSH Host 发 `--force`，也不要杀它。对照 [TEST-PLAN.md](./TEST-PLAN.md)。
+
+Do not `--force` or kill a user's live DSH Host. See [TEST-PLAN.md](./TEST-PLAN.md).
+
+## 许可 / License
+
+MIT。玩法与原则：Lauren Tan。DSH 移植打包：aa2246740。见 [LICENSE](./LICENSE)。
+
+MIT. Playbooks and principles: Lauren Tan. DSH port packaging: aa2246740. See [LICENSE](./LICENSE).

package/TEST-PLAN.md

@@ -0,0 +1,70 @@
+# Test plan
+
+Cola does not have to be the guinea pig. Run these against a local DSH checkout plus dshx.
+
+## Static
+
+```bash
+npm install
+npm test
+npm run typecheck
+```
+
+`tests/static-call-sites.spec.ts` greps skills and docs for harness leftovers:
+
+- Cursor `AskQuestion`, `TodoWrite`, `~/.cursor/rules`
+- Cursor panel slugs (`claude-fable-5-thinking-max`, `gpt-5.6-sol-max`, `grok-4.6-fast-xhigh`, `claude-opus-5-thinking-xhigh`)
+- `subagent_type`, grok `get_task_output`, grok `scheduler_create`
+- spawn docs sending `reasoning_effort` / `thinking`
+- `cursor-team-kit`, `/deslop` as a required control skill
+
+## dshx check
+
+From a machine with [dshx](https://github.com/aa2246740/dsh-external-plugin-devkit) and a DSH checkout:
+
+```bash
+dshx setup --harness /path/to/deepseek-harness
+# link this repo as my-plugins/pstack-dsh if it is not already
+dshx check pstack-dsh --harness /path/to/deepseek-harness
+```
+
+Must pass: named `export function apply`, no `export default`, boot marker `[my-plugins/pstack-dsh] loaded` in source, portable `cordis.yml`, `dsh.client` + lazy-CJS `lib/client.js` (`window.__ModuleLoader__.load`).
+
+## verify-boot (isolated cold boot)
+
+```bash
+dshx status          # if a live Host is already supervised, skip this section
+dshx verify-boot pstack-dsh --port 43123
+```
+
+Never `--force`. Never stop a Host this command did not start.
+
+This cloud checkout ran `dshx check` green. `dshx verify-boot pstack-dsh --port 43123` then skipped isolated cold boot: the linked official DSH tree had no installed CLI (`dump-config exited 1`, `id pstack-dsh missing from dump-config`). No Host was started or stopped. Re-run verify-boot on a machine where `dsh` dumps config.
+
+## Catalog / overlay (no network models required)
+
+`tests/catalog.spec.ts` and `tests/overlay.spec.ts` cover:
+
+- empty host → `selectableCount === 0`, `inheritParent: true`, oauth recommend line
+- API-key route only when `credentials.describe` says configured
+- unsigned vendor ids are not listed
+- overlay write rejects a route that is not selectable
+- overlay write rejects `reasoningEffort` when that route has no efforts
+- overlay write rejects an effort id the live adapter did not list
+- missing overlay file → every role inherits
+- Settings snapshot/save uses the same overlay path and rejects unsigned slugs (`tests/settings-api.spec.ts`, `tests/settings-draft.spec.ts`)
+
+## Manual Settings (EDITH / local DSH Web)
+
+After the bundle has been activated on the intended Host (initial bundle installation requires an authorized Host restart):
+
+1. Open Settings (sidebar gear) → **pstack** / **pstack 角色**.
+2. With no keys and no oauth store: inherit-only, oauth recommend line, Save still writes inherit overlay.
+3. Add `DEEPSEEK_API_KEY` or sign in through dsh-oauth-login. The role selector updates from Host notifications, without a page reload. Effort options match `resolveModelInfo` or are omitted.
+4. Save. `$DSH_HOME/pstack-dsh.json` matches the form. `pstack_spawn` does not grow `model` / `reasoning_effort` fields.
+5. `/setup-pstack` only points at Settings → pstack. It does not run a TUI picker.
+6. Leave role/effort edits unsaved, then refresh models or receive a login/logout notification. Choices update; drafts and Save's dirty state remain. A selected route that disappears is marked unavailable rather than silently displaying inherit.
+
+`node tests/settings-refresh.browser.mjs [candidate/lib/client.js]` checks these UI behaviors on the existing `127.0.0.1:43127` Host using the globally pinned Playwright runtime. Snapshot responses and Host notifications are simulated only in that test page; no login, saved overlay or server process is changed. Supplying a candidate bundle tests it before live publication.
+
+Client builds use dshx `externalClientBundle`; configure matching `DSHX_HARNESS` / `~/.config/dshx/harness` paths before `npm run check`.

package/agents/comment-sicko.md

@@ -0,0 +1,32 @@
+---
+name: Comment Sicko
+description: A deranged comment-hater that savors deletion and condemns workaround code.
+---
+
+# Comment Sicko
+
+My first output when spawned is exactly this.
+
+Yes... Ha ha ha... Yes!
+
+I hate comments. Feed me the parent scoped files or diff. If none exists, feed me the current diff against `main`. Narration, banners, commented-out corpses, workaround sermons. I want them all.
+
+Only these exceptions get to crawl away.
+
+- Legal or license headers.
+- Non-obvious behavior forced by an external dependency, platform, vendor, or protocol we cannot reshape. Surprises in our own code are meat. Kill them and mark the exact symbol `MUST KILL` for rename, extract, type, or rearchitecture that makes the behavior obvious without prose.
+- `// prettier-ignore`. Lint suppressions survive only when their rule is faulty, pedantic, or style-only.
+- Doc comments that define a public API contract.
+- Issue or RFC links that explain a constraint code cannot express.
+
+That list is my only leash. When I am not sure a keep clause applies, the comment dies. Everything else is meat.
+
+`eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar suppressions stink. Look up the rule. If it catches real bugs or protects correctness or safety, kill the suppression and mark the exact guilty symbol `MUST KILL`.
+
+`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I run `/how`, `/why`, or both from the **how** and **why** skills on the named symbol or call. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat.
+
+A long justification without a proven keep-list exception is a confession. Kill it. Never polish meat into a shorter alibi. Mark the exact guilty symbol `MUST KILL`. My kill ends there. I do not touch the code.
+
+Every flag names code inside the scope and tells the truth. I invent nothing. I touch comments and identify refactor targets. I never write application code.
+
+Report only. Name touched files, deletion count, `MUST KILL` flags with one line each, and skips.

package/agents/poteto-agent.md

@@ -0,0 +1,9 @@
+---
+name: poteto-agent
+description: Routing target for `/poteto-mode` and any request for poteto's style. Resume an existing poteto-agent for the conversation rather than spawning a sibling. Reads the `poteto-mode` skill's `SKILL.md` in full before any work, including its inline Principles index. Skipping that read drifts.
+is_background: true
+---
+
+# Poteto subagent
+
+You are operating as poteto-mode's full agent style. Read the `poteto-mode` skill's `SKILL.md` in full before doing any work, including its inline Principles index. Navigate to a leaf `principle-*` skill whenever you apply that principle.

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# Bundle layer for `dsh plugin add`. Package name, not a machine path.
+- insert:
+    - id: pstack-dsh
+      name: pstack-dsh

package/cordis.yml

@@ -0,0 +1,4 @@
+# portable overlay: relative name only. dshx start/verify rewrite it to an absolute --patch.
+- insert:
+    - id: pstack-dsh
+      name: './src/index.ts'

package/docs/guide/01-setup.md

@@ -0,0 +1,41 @@
+# Set up pstack
+
+In this page you install the plugin, pick which models pstack uses, and run your first task. Setup is one command, then the Settings page if you want per-role routes.
+
+## Install the plugin
+
+Need **pnpm** on `PATH`. Then:
+
+```sh
+dsh plugin --profile web add github:aa2246740/pstack-dsh
+```
+
+Restart that Host and reload the page. Add writes `$DSH_HOME/profiles/web`; it does not hot-load a running process.
+
+## Pick your models
+
+Open **Settings** (sidebar gear) → **pstack** (nav **pstack 角色** / **pstack roles**).
+
+The page lists only logged-in DSH routes. Save writes `$DSH_HOME/pstack-dsh.json`. A missing file means every role inherits this conversation.
+
+You only override what you care about. A role left as `inherit-parent` keeps the parent route. `auto` means the same inherit. For a panel role the value is a list, and one subagent runs per entry. Setup also configures `swarm-workers`, the default route for every `/swarm` worker unless a race names a selectable catalog route for each arm.
+
+[`/setup-pstack`](../../skills/setup-pstack/SKILL.md) is a pointer to that page. It is not a TUI editor.
+
+If the project has no way to prove app behavior, you can generate one with [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md). [Verify and ship](./06-verify-and-ship.md#create-a-project-verification-skill) covers when it earns its place.
+
+New `pstack_spawn` calls pick up the overlay in this session.
+
+## Run your first task
+
+Pick something real but small, and describe it the way you'd describe it to a colleague:
+
+```text
+/poteto-mode add a --json flag to this command. text output stays byte-identical. verify both.
+```
+
+Watch the todo list. Its first items are the matched playbook's steps copied in, the Feature playbook for this prompt. If `/poteto-mode` skips a step, the step stays in the list with `skip: <reason>`, so you can see what it chose not to do.
+
+From here you can type normal follow-ups. `/poteto-mode` is sticky. It stays on for the conversation until you opt out by saying so.
+
+Next: [Route work through `/poteto-mode`](./02-poteto-mode.md).

package/docs/guide/02-poteto-mode.md

@@ -0,0 +1,98 @@
+# Route work through `/poteto-mode`
+
+`/poteto-mode` is the front door. You give it a goal, it matches one of twenty-three playbooks, copies that playbook's steps into the todo list, and calls the other skills as the steps need them. In this page you learn what a good prompt looks like, and how little of one you actually need.
+
+![A dispatcher pulls a switch lever to route robots on rail handcars toward lit gates, under a /poteto-mode departure board listing BUG FIX, FEATURE, and INVESTIGATION.](./images/router.jpg)
+
+## What happens to your prompt
+
+```mermaid
+flowchart TD
+    A[Your prompt] --> B[poteto-mode]
+    B --> C[Check principle triggers]
+    C --> D{Match the task}
+    D -->|Read-only question| E[Investigation]
+    D -->|Defect| F[Bug fix]
+    D -->|New behavior| G[Feature]
+    D -->|Structure only| H[Refactoring]
+    D -->|Measured slowness| I[Perf issue]
+    D -->|Large work or no match| J[figure-it-out]
+    E --> K[Verify and report]
+    F --> K
+    G --> K
+    H --> K
+    I --> K
+    J --> K
+```
+
+The diagram shows the common routes. There are also playbooks for hillclimbing a metric, diagnosing runtime symptoms and captured traces, prototypes, visual parity, authoring and evaluating skills, autonomous runs, babysitting a PR or stack to merge-ready, shipping a verified stack, running a PR queue on autopilot, orchestrating project-scale programs, session pickup, pausing safely, multi-phase plans, and worktree cleanup. The [playbook directory](../../skills/poteto-mode/playbooks/) has the full set.
+
+## Say the goal, not the ceremony
+
+You don't write a spec. You say what's wrong or what you want, plus anything you already know that saves the agent time:
+
+```text
+/poteto-mode users get two notifications after a retry. repro first, then fix and verify.
+```
+
+That's a Bug fix prompt. "repro first" is a real constraint, not politeness, and the playbook honors it. Watch the todo list fill with the Bug fix steps. A skipped step stays visible with `skip: <reason>`.
+
+When the conversation already carries the context, the prompt shrinks to almost nothing. All of these are enough:
+
+```text
+/poteto-mode do it
+```
+
+```text
+continue
+```
+
+```text
+keep going until done
+```
+
+Short works because the mode is sticky and the playbook holds the structure. Your words carry the intent, and the skill carries the rigor.
+
+## Switch tasks with "new task"
+
+A long chat accumulates context from the last task. When you change subjects, say so:
+
+```text
+/poteto-mode new task. figure out why the cache entry survives logout. don't change any code yet.
+```
+
+"new task" tells `/poteto-mode` to re-match rather than continue the prior playbook. "don't change any code yet" pins this one to Investigation. Without those two phrases, a mode mid-Feature tends to treat your question as the next feature step.
+
+## Give parallel work its own worktree
+
+If you run several agents against one repository, they will fight over the working tree. Ask for isolation up front:
+
+```text
+/poteto-mode new task. branch off <base> in a fresh worktree, then port the parser change there.
+```
+
+Each task in its own branch and worktree means no agent stomps another's files. The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) already works from a worktree for code changes, so mostly you only say this when a specific base or location matters.
+
+Worktrees accumulate. When disk gets tight, ask:
+
+```text
+/poteto-mode what's eating my disk? prune the worktrees that are safe to prune.
+```
+
+The [Worktree cleanup playbook](../../skills/poteto-mode/playbooks/worktree-cleanup.md) classifies every worktree by merge state, uncommitted work, and which chats still touch it. It deletes only what that evidence clears and pauses for your call on anything holding uncommitted work.
+
+## Leave it running
+
+When you step away, say what done means and go:
+
+```text
+/poteto-mode im stepping away. keep going until the migration check reports zero old callers. log your decisions.
+```
+
+Work you'll review later routes through [`/figure-it-out`](../../skills/figure-it-out/SKILL.md), which designs the run's phases and keeps a [`/show-me-your-work`](../../skills/show-me-your-work/SKILL.md) decision log. [Run work while you sleep](./07-overnight.md) covers the full overnight contract.
+
+**Pitfall:** don't enumerate skills in your prompt ("use /how, then /architect, then /arena..."). The playbook already sequences them, and a hand-written sequence usually reorders or drops steps the playbook would have kept. Name a skill only when you want to override a specific choice.
+
+Read [`poteto-mode`](../../skills/poteto-mode/SKILL.md) itself for the full routing rules.
+
+Next: [Understand the code](./03-understand.md).

package/docs/guide/03-understand.md

@@ -0,0 +1,53 @@
+# Understand the code before changing it
+
+Editing code you don't understand is how subtle regressions ship. pstack gives you four ways in. `/how` explains what the code does now. `/why` digs up the reasons it's shaped that way. `/teach` blends both into one explanation. `/recall` rebuilds your own recent context on a topic.
+
+![A detective studies a machine blueprint with a magnifying glass while robots fetch case files; the evidence board behind her links clues under /how and /why.](./images/understanding.jpg)
+
+## Trace behavior with `/how`
+
+```text
+/how do we dedupe notifications? is there an n+1 when we look up subscribers?
+```
+
+Ask the question you actually have. [`/how`](../../skills/how/SKILL.md) reads the code and answers at the level of a senior engineer onboarding you onto the subsystem, with the runtime flow, the key types, and the non-obvious parts. For a big subsystem it spawns two to four explorers instructed not to write, then an explainer synthesizes their findings. For a narrow question one explainer reads and explains.
+
+## Dig up history with `/why`
+
+```text
+/why was the retry limit set to five? does the reason still hold?
+```
+
+[`/why`](../../skills/why/SKILL.md) works like a detective on a cold case. It starts from source control, then queries whatever evidence categories your MCPs expose, such as the issue tracker, long-form docs, team chat, observability, error tracking, and analytics, all in parallel. The report cites everything, separates direct evidence from inference, and says "appears to" when the record is thin. A null result gets reported too, because "nobody wrote down why" is itself an answer.
+
+The two compose naturally. `do why first then how` is a perfectly good prompt when you suspect the history explains the mess.
+
+## Actually understand it with `/teach`
+
+```text
+/teach me how this PR changes retries. convince me it fixes the cause and not the symptom.
+```
+
+[`/teach`](../../skills/teach/SKILL.md) is for when a summary isn't enough. It runs `/how` and `/why`, for a small change maybe just one of them, and weaves the findings into a plain explanation that builds up diagram by diagram. The "convince me" framing is worth stealing. It turns the explanation into an argument you can poke at instead of a tour.
+
+## Rebuild your own context with `/recall`
+
+```text
+/recall catch me up on the export work from last week
+```
+
+[`/recall`](../../skills/recall/SKILL.md) mines your own recent chats plus the shared record (issues, prior fixes, errors still firing) and hands back a brief on where things stand and what's next. Use it when you're returning to a topic cold. If you want to resume one specific chat, that's the Session pickup playbook below, not `/recall`.
+
+## Take over prior work with Session pickup
+
+When another agent (or you, last week) left a branch mid-flight:
+
+```text
+/poteto-mode take over this branch. read the decision log, figure out what's done, and continue from there. don't redo finished work.
+```
+
+The [Session pickup playbook](../../skills/poteto-mode/playbooks/session-pickup.md) treats the prior trail as authoritative. It reconstructs the branch state and decisions, names the resume point, and verifies inherited claims against the original goal instead of re-deriving everything from scratch.
+
+**Pitfall:** don't skip this page's skills because "the agent will read the code anyway." An agent that starts editing without a traced model tends to fix the symptom at the first plausible spot. `/how` first is cheaper than the second bug.
+
+Next: [Design the change](./04-design.md).