dsh-pstack 0.0.0-stage → 0.2.0-beta.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 dsh-pstack contributors
+Copyright (c) 2026 Lauren Tan (upstream pstack, https://github.com/cursor/plugins)
+
+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

@@ -1,3 +1,134 @@
-# Temporary Holding Version
+# dsh-pstack
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="static/icon.png" alt="pstack logo" width="96" height="96">
+
+pstack 的 DeepSeek Harness 移植。它把 Cursor pstack 的技能、playbook、原则和角色化子代理工作流带到 DSH。
+
+安装后，`/poteto-mode` 启动一次严谨任务，`/setup-pstack` 配置各角色使用的模型和推理预算，`/poteto-help` 帮助选择技能或排查用法。
+
+## 支持的 DSH 版本
+
+支持 `0.2.1-rc.3`。安装包在 `engines.dsh` 声明支持的 DSH 版本，其他版本未经验证。新版本验证通过后补充到本节。
+
+## 实现原理
+
+上游 pstack 对 Claude Code 的适配保留技能原文，生成独立的宿主资产，再用一份宿主适配说明处理工具、路径、模型和能力差异。
+
+dsh-pstack 沿用这个思路。上游技能是内容源，DSH 专用资产单独生成，宿主差异集中说明。上游更新可以持续同步，DSH 特有的行为不会散落在每个技能里。
+
+## 必要依赖
+
+- worktree 插件。并行写入和隔离工作目录需要它。未启用时插件自动启用，已启用时不会重复启用。
+- DSH 的 skills 和 subagents 能力，由支持的 DSH 版本提供。
+- Node.js `>=22.19`。仅 npm CLI 部署需要它出现在 `PATH` 上；Desktop（Electron）部署走 Host 自己的运行时。
+- Git。worktree 需要 Git 仓库。
+
+随包的编排、PR watcher、计划检查、worktree 审计和决策日志脚本已构建为单文件 Node 产物，依赖全部内联。运行时通过 `pstack_script` 工具以宿主进程启动它们，因此**不需要 Bun，也不需要 bash，更不需要安装任何依赖**。Desktop 用户不在 `PATH` 上放 `node` 也能用：工具用 Electron 自带的 Node 运行时执行，并在需要时自动附加 `ELECTRON_RUN_AS_NODE`。脚本从**会话目录**启动，所以参数里的相对路径落在当前工作区或 worktree 内。
+
+`pstack_script` 直接 `spawn` 子进程，因此**不经过命令审批，也不受 DSH 的 sandbox policy 约束**：它只能执行本包随附、由封闭 `id` 枚举选中的脚本，但脚本实际读了什么、写了哪里，Host 不会拦。这是为了在没有 `PATH` `node` 的部署里仍能运行为此付出的代价。需要审批与沙箱约束的命令请用 DSH 自己的 bash 工具。
+
+worktree 只隔离工作目录和分支，不提供 VM、网络、凭据或端口隔离。需要独立机器或云端执行时，worktree 不是替代品。
+
+Linux 和 macOS 是主要验证目标，Windows 未在实机验证。脚本本身已不含 shell 依赖，但 Windows 上的真实行为仍未验收。
+
+## 与 Agent Team 的兼容性
+
+> **兼容性警告**
+>
+> 当前版本禁止与 Agent Team 同时启用。Agent Team 会用同名工具遮蔽 `send_message`、`interrupt_agent` 和 `list_agents`，pstack 无法再用它们 steer、列出或中断自己的子代理。两者还共享子代理激活容量。`pstack_subagent` 的角色路由和 reasoning effort 计算本身不受影响，但同一 profile 中的 Team 工具会改变可见工具面。
+>
+> 需要同时使用时，请使用两个独立 profile。
+
+决策记录见 [docs/decisions/2026-10-24-no-agent-team-coexistence.md](https://github.com/l246804/dsh-pstack/blob/main/docs/decisions/2026-10-24-no-agent-team-coexistence.md)：`docs/` 不在发布包的文件清单里，所以这里用绝对 URL，避免 npm 页面上的相对链接指向不存在的路径。
+
+## 安装
+
+通过 npm 包 `dsh-pstack` 安装。`<profile>` 换成目标 profile，例如 `web`。
+
+```bash
+dsh plugin --profile <profile> add dsh-pstack
+```
+
+安装会启用 bundle。DSH 提示重启时按提示操作。
+
+## 快速开始
+
+1. 安装插件，进入目标 profile。
+2. 运行 `/setup-pstack`，选择推理预算和每个角色的模型。
+3. 用 `/poteto-mode` 加任务开始一次严谨工作流。
+4. 不确定用哪个技能时，运行 `/poteto-help`。
+
+`/poteto-mode` 会匹配 playbook，把步骤写进 todo，并按需读取其他技能。小改动可以直接做，不必使用它。
+
+## 角色配置
+
+`/setup-pstack` 写入 `$DSH_HOME/pstack-models.md`，一行一个角色。`$DSH_HOME` 是 DSH 的用户目录。值可以是 `inherit-parent`，也可以是 `provider/model` 加推理档位。
+
+- `inherit-parent` 使用父会话的模型和推理档位。
+- panel 角色的值是列表，每一项启动一个子代理。
+- 删除某个角色的行，该角色回落到父路由。
+- 重新运行 `/setup-pstack` 会更新配置，不会叠加旧值。
+
+模型必须出现在当前 DSH 的 provider 和模型列表中。
+
+### 推理档位
+
+角色行里的档位是那个角色**起步**用的档位。实际档位随任务难度双向浮动：
+
+- 调用 `pstack_subagent` 时传 `reasoningEffort`，覆盖本次派发中每个 panel 项的档位。难任务调高，机械活调低。
+- 子代理自己可以调 `set_reasoning_effort`，从下一步生效，已在飞行中的请求不受影响。
+
+合法档位由目标模型自己广告。本包不假设通用阶梯，所以参数是自由字符串而不是枚举。值不被支持时，调用在启动任何子代理**之前**失败，并在错误里列出该模型真实支持的档位。panel 中任一项不支持时整次失败，不会只启动一半。
+
+
+## 功能范围与已知限制
+
+包含 55 个技能、23 个 playbook、24 个原则和两个子代理人格。
+
+- `make-bot-ui` 不在支持范围。它依赖 Cursor 的 webhook routine 和 secret request，DSH 没有等价闭环。
+- Cursor 专属能力没有等价物，包括 Automations、cloud agents、Custom Modes 和 Bugbot 配置。相关技能会在需要它们的步骤说明不支持，不伪造替代。
+- `/loop` 没有同名命令，也没有事件订阅，属于降级映射。能覆盖的是目标与定时输入：`create_goal` 记录目标和相位，`schedule_create` 只能作定时心跳，它把一条消息投回创建它的会话，不能盯着 PR 或 CI，子代理也无法自己布置。不能覆盖的是事件唤醒和云端存活：goal 不会自己感知外部事件，自动续跑还取决于 profile 是否挂载 goal round driver，未挂载时长时间任务只是同一个会话里被监督的运行。
+- `typescript-best-practices` 的 `paths` 自动触发不支持，需要时显式调用 `/typescript-best-practices`。
+- worktree 只隔离工作目录，不是 VM。schedule 是定时提醒，不是事件订阅。
+- 多模型评审需要配置真实不同的 route。只有同一 route 时，评审会标为同模型复核。
+- 子代理和 panel 会增加 token 消耗，只在需要严谨流程的任务上使用 `/poteto-mode`。
+
+## 更新与卸载
+
+升级：
+
+```bash
+dsh plugin --profile <profile> add dsh-pstack@latest
+```
+
+卸载：
+
+```bash
+dsh plugin --profile <profile> remove dsh-pstack
+```
+
+角色文件在 DSH 用户目录，卸载不会删除它。不再使用时自行删除 `$DSH_HOME/pstack-models.md`。升级或卸载后按 DSH 提示重启会话。
+
+## 安全与数据
+
+- 代理在 DSH 权限模型下读写文件、执行命令，子代理继承调用方的策略和权限边界。
+- 需要审批的操作按 DSH 配置请求确认。不要在无人值守任务中放宽不理解的权限。
+- 不要把 API key、token 或密码写进角色文件、prompt 或仓库。
+- 会话记录保存在 DSH 的会话存储中，pstack 不另建云端记录。
+- 上游技能可能要求访问网络或代码托管平台。是否允许由 DSH 的审批和沙箱配置决定。
+
+## 故障排查
+
+按顺序检查。
+
+1. 确认 DSH 版本在支持范围内。
+2. 确认 worktree 插件可用，必要时先手动启用一次。
+3. 确认当前 profile 没有同时启用 Agent Team。
+4. 运行 `/setup-pstack` 检查角色配置。
+5. 仍有问题时在 [GitHub Issues](https://github.com/l246804/dsh-pstack/issues) 提交，附 DSH 版本、profile 名、复现步骤和错误信息。不要贴密钥或私有会话内容。
+
+## 许可证与上游归属
+
+MIT，见 [LICENSE](LICENSE)。
+
+上游 pstack 版权归 Lauren Tan，使用 MIT 许可证。技能、playbook 和代理文本来自 [cursor/plugins](https://github.com/cursor/plugins/tree/main/pstack)。

package/assets/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/assets/agents/poteto-agent.md

@@ -0,0 +1,8 @@
+---
+name: poteto-agent
+description: Delegate subagent for code-writing and helper tasks spawned during a `/poteto-mode` run. Use for delegates, not as the runner for `/poteto-mode` itself. Spawn a fresh `poteto-agent` for each new task, and resume one only in the strict cases that poteto-mode's Subagents section names. Reads the `poteto-mode` skill's `SKILL.md` in full before any work, including its inline Principles index. Substituting `general` skips that read and drifts.
+---
+
+# Poteto subagent
+
+You are operating as poteto-mode's full agent style. The chat that receives `/poteto-mode` owns the playbook, the todo list, and every `pstack_subagent` spawn. You are one of its delegates. Read the `poteto-mode` skill's `SKILL.md` in full before doing any work, including its inline Principles index. `pstack_subagent` injects that absolute path into your brief. Use the path it gave you and read the file there. Your skill catalog also hides this skill, so a missing catalog entry does not mean pstack is absent. If the brief gave no path and you cannot read the file, stop and tell your parent. Navigate to a leaf `principle-*` skill whenever you apply that principle.

package/assets/docs/guide/01-setup.md

@@ -0,0 +1,64 @@
+# Set up pstack
+
+In this page you install the plugin, pick which models pstack uses, and run your first task. Setup is one command plus a short conversation.
+
+## Install the plugin
+
+Install the bundle into the profile you work in. `<profile>` is that profile's name, such as `web`:
+
+```bash
+dsh plugin --profile <profile> add dsh-pstack
+```
+
+DSH reports whether the bundle still has to be enabled and whether the change needs a new Session. Follow that prompt, and expect the skill catalog and `pstack_subagent` to load only after it.
+
+## Pick your models
+
+Run:
+
+```text
+/setup-pstack
+```
+
+[`/setup-pstack`](../../skills/setup-pstack/SKILL.md) detects the models you have access to, asks for a reasoning budget, shows you each role (code delegates, judgment, the review panels), and asks what you want. Answer the questions. It writes `$DSH_HOME/pstack-models.md`, the small file every pstack skill reads.
+
+The skill defaults target `xhigh` reasoning, the same as the `large` budget. `unlimited` targets `max`; `medium` targets `high`, and `small` targets `medium`. Each target is applied only to a route you explicitly choose: use it when that model advertises it, otherwise use the highest advertised effort at or below the target. If the model advertises none, `/setup-pstack` asks you to choose instead of inventing an effort. The adapter's list decides, not the model's brand. A role set to `inherit-parent` or `auto` has no route-specific effort to change.
+
+You only override what you care about. A role with no line in the file keeps the skill's default. To restore a default, delete that role's line. A rerun of `/setup-pstack` keeps any role whose model differs from the default. When a default changes, a file written before the change still pins the old default, so delete those role lines, or delete the file, then run `/setup-pstack` again.
+
+You might be wondering what happens if you use Auto. Set a role to `inherit-parent` or `auto` and pstack sends no explicit `agentOptions` for that child, so DSH resolves it on the parent chat route. Both values mean the same thing, and neither is a model slug. For a panel role the value is a list, and one subagent runs per entry, so the list length sets the panel size. Setup also configures `swarm workers`, the default model for every `/swarm` worker unless a race names a model for each arm.
+
+## Accept the verification offers, or don't
+
+At the end of setup, `/setup-pstack` looks for a way to prove app behavior in your project, either a `verify-*` skill or an existing harness. If it finds neither, it offers once to generate one with [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md).
+
+Say yes and it writes `.dsh/skills/verify-<app>/`, a project-local skill that teaches agents to drive your app the way a user does. It proves the skill works once before handing it over. Say no and setup moves on. You can run `/create-verification-skill` yourself any time. [Verify and ship](./06-verify-and-ship.md#create-a-project-verification-skill) covers it in depth.
+
+If you're new to pstack, say yes. An agent that can check its own work keeps going until the check passes. An agent that can't hands every result back to you to check by hand. Of everything in this guide, the verification skill pays off the most.
+
+Then setup offers once to generate a formal verification skill with [`/create-formal-verification-skill`](../../skills/create-formal-verification-skill/SKILL.md), unless the project already has one. Tests check the cases someone thought to write. A formal verification skill checks one key property of your code, such as "a job never runs twice at once", in every case within a stated scope. Say yes when your code has concurrency, retries, a state machine, or a parser, where a bug is costly and tests rarely reach the case that breaks. Otherwise say no, and run it later if that changes. [Verify and ship](./06-verify-and-ship.md#prove-a-property-with-a-formal-verification-skill) covers it.
+
+After setup the file applies from the next delegation on, because `pstack_subagent` re-reads it every time.
+
+## Keep the cost in check
+
+pstack spends extra tokens on subagents and review panels. That's the price of the rigor. To spend fewer:
+
+- Rerun `/setup-pstack` and pick a smaller reasoning budget or cheaper models. A strong model in the main chat with cheaper, faster models in the code roles is a good split.
+- Set a role to `auto` or `inherit-parent` so it runs on the chat's own model.
+- Shorten a panel list. Each entry runs one subagent.
+- Save `/poteto-mode` for work that needs rigor. A small, obvious edit doesn't.
+
+## 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` attaches to the task that invoked it and does not carry over to the next one, so start each new task by typing it again. There is no persistent mode and no keyboard shortcut that keeps it on: this host has neither, and a skill that should apply again has to be invoked again.
+
+Next: [Route work through `/poteto-mode`](./02-poteto-mode.md).

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

@@ -0,0 +1,139 @@
+# 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[Read the Principles section]
+    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, opening a PR, babysitting a PR or stack to merge-ready, shipping a verified stack, running a PR queue or a stack 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>`.
+
+## What goes in a prompt
+
+A useful prompt carries up to five things, and each one fits in a sentence:
+
+- **The goal.** Say what's wrong, or what you want.
+- **The done check.** It must be able to pass or fail. "Make it better" and "work on it for an hour" aren't checks.
+- **The proof you want to see.** Ask for the real command output, a video of the flow, the stored value, or a before-and-after number.
+- **What you already know.** A symptom, a repro step, a log line, or a link saves the agent a search.
+- **The real constraints.** "repro first", "don't change any code yet", "zero behavior change", and "let me review before proceeding" each change what the agent does.
+
+Here's one prompt with all five:
+
+```text
+/poteto-mode the csv export drops its last row since yesterday's deploy. failing job id is 4812. repro first, then fix. done means the 60k-row fixture exports every row. show me the row counts before and after.
+```
+
+Two things are worth leaving out:
+
+- **The how.** Say what to achieve, and leave the agent room to find a better path than the one you'd pick. The same goes for a list of skills, covered in the pitfall below.
+- **Your theory of the cause, at first.** A stated guess narrows the search to wherever you pointed. Let the agent restate the problem before you share your hunch.
+
+For a noisy report, such as a long thread or a vague bug, make the restatement the first step:
+
+```text
+/poteto-mode read this thread. restate the underlying issue in your own words, in plain english. don't change any code yet.
+```
+
+A misreading shows up in the restatement, before any code exists. Correct it there, and it costs you one message instead of one wrong fix. For the restatement alone, with no playbook, run [`/in-your-own-words`](../../skills/in-your-own-words/SKILL.md). It restates what the agent thinks your goals are and what problem you're trying to solve.
+
+When you're unsure whether a prompt is aimed right, run [`/sharpen`](../../skills/sharpen/SKILL.md) on it before you send it:
+
+```text
+/sharpen write a migration guide for the v2 config format.
+```
+
+The agent says what a top professional would do that you didn't ask for, the rawest material they would start from, the methods and tools they would use, and what other than you or the agent would show the result is right. Then it rewrites your prompt to ask for exactly that, deeper but not bigger, and leaves your choices open. It doesn't do the task. Read the rewrite, then send it, for example with `/poteto-mode`.
+
+## Follow up short
+
+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 playbook holds the structure, and `/poteto-mode` attaches to the task that invoked it. Nothing keeps the skill in context after that task, so type it again for each new one; [set up pstack](./01-setup.md) shows a first task. 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 on one computer, they will fight over the working tree, the ports, and the build output. There is no cloud machine and no VM here: every agent is a local child of this Session and ends when the host process ends. What you can give each writer is its own working directory and branch, through the official worktree rows this bundle mounts, so ask for a `create_worktree` checkout per writer and pass its absolute path as that child's `cwd`. Ports, caches, credentials, and services stay shared, so run one app instance and one heavy build at a time.
+
+Ask for a worktree 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. Worktrees cost disk and machine resources, so a laptop runs only a handful at once. 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/assets/docs/guide/03-understand.md

@@ -0,0 +1,79 @@
+# Understand the code before changing it
+
+Editing code you don't understand is how subtle regressions ship, and that's as true for the agent as for you. Agents usually fail in one of two ways. They misread what you want, or they don't have the context to do the work right. [What goes in a prompt](./02-poteto-mode.md#what-goes-in-a-prompt) handles the first. This page handles the second.
+
+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. Each one also makes the agent explain itself in words you can check. That's how you supervise an agent that may know the code better than you do.
+
+![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)
+
+## Start with a read-only investigation
+
+When the cause is unclear, ask for findings, not a fix:
+
+```text
+/poteto-mode investigate why background jobs time out every few hours. give me what we know, what data you used, and your best hypotheses. don't change any code yet.
+```
+
+"don't change any code yet" routes this to the [Investigation playbook](../../skills/poteto-mode/playbooks/investigation.md). It runs `/how`, adds `/why` for questions about motivation, and returns a cited explanation. For a choice between options, it returns a recommendation with a trade-offs table. Asking "what data you used" makes the agent separate its evidence from its guesses. When the findings point at a fix, start the fix as a new task.
+
+## 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 fans out two to four read-only explorers first. For a narrow question it just 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) 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 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 reusing. It turns the explanation into an argument you can test instead of a tour.
+
+It works on the agent's own choices too:
+
+```text
+/teach me why you implemented it this way and not with a queue. what did you trade off, and why?
+```
+
+Teaching helps the agent as much as you. An agent that has to explain its work must read the code and back each claim with evidence, instead of stating it confidently and moving on.
+
+## 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. Your old chats hold context that a fresh agent lacks, so start new work on an old topic by loading it first, then hand over the new input:
+
+```text
+/recall my work on the virtualized list from yesterday, then read this bug report.
+```
+
+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).

package/assets/docs/guide/04-design.md

@@ -0,0 +1,133 @@
+# Design before you write code
+
+One attempt at a hard design locks in the first shape the model thought of. `/architect` settles types and boundaries before implementation. `/arena` runs several attempts at the same brief and merges the best parts. `/interrogate` has other models try to break the result. When the job is coverage rather than design synthesis, `/swarm` fans out slices or races and aggregates their results.
+
+The two most common design mistakes are taking the agent's first design and polishing a plan that no code has tested. This page fixes both. You plan through code. Prototypes answer the open questions, a README or tutorial sets the target, and the written plan comes last.
+
+![Three robots draft competing bridge models at their own tables under /architect, /arena, and /interrogate panels, while a judge robot with a clipboard inspects skeptically.](./images/design.jpg)
+
+## Settle the shape with `/architect`
+
+```text
+/architect design the import pipeline before writing any code. i care most about how callers use it.
+```
+
+[`/architect`](../../skills/architect/SKILL.md) grounds itself first, running `/how` over the code the design touches and `/why` when it moves ownership or layers. Then it runs `/arena` to produce competing design sketches, with the caller's usage written first in each, followed by types, signatures, and a module map.
+
+By default it proceeds straight from the synthesized design into implementation. If you want to see the design first, say so:
+
+```text
+/architect with checkpoint. stop and show me before implementing.
+```
+
+The design isn't sacred once code starts. If implementation shows the same workaround in unrelated places, or types that only compile with `any` or forced casts, `/architect` treats that as proof the design is wrong. It scraps the sketch and starts over instead of patching around it.
+
+## Fan out attempts with `/arena`
+
+```text
+/arena take my prompt to the arena verbatim. i want to compare their proposals with yours.
+```
+
+[`/arena`](../../skills/arena/SKILL.md) is the general tool underneath. N subagents attempt the same design or code brief in parallel, each writing to its own worktree or directory. A read-only judge, on a different model family when your configuration allows one, scores every candidate against a rubric. The coordinator reads each candidate end to end, picks a base, grafts in the best ideas from the losers, and verifies the result.
+
+```mermaid
+flowchart LR
+    A[One task] --> B[Configured panel]
+    B --> C[Candidate 1]
+    B --> D[Candidate 2]
+    B --> E[Candidate N]
+    C --> F[Cross-judge]
+    D --> F
+    E --> F
+    F --> G[Pick a base]
+    G --> H[Graft the best parts]
+    H --> I[Verify]
+```
+
+The panel comes from your [`/setup-pstack`](../../skills/setup-pstack/SKILL.md) configuration, and you can adjust it per task. Ask for more candidates when the decision matters, fewer when it doesn't:
+
+```text
+/arena this, 5 candidates. the cache key format is expensive to change later.
+```
+
+## Cover slices and races with `/swarm`
+
+```text
+/swarm check every package under packages/ against its check.sh. one worker per package. one report.
+```
+
+[`/swarm`](../../skills/swarm/SKILL.md) fans N workers across independent slices, coverage matrices, gauntlet lanes, exploration partitions, or declared race arms. Each worker gets its own scope and check, then reports `PASS`, `ISSUES`, or `BLOCKED`. The parent waits for the workers and returns one compact report with any gaps or dropouts.
+
+Reach for it when parallelism buys coverage or lets independent checks race. `/arena` gives every worker the same design or code brief, then picks a base and grafts the best parts. `/swarm` covers slices or runs a race with a selection rule declared up front. It does not use the base-selection and grafting ceremony.
+
+## Break it with `/interrogate`
+
+```text
+/interrogate the whole branch, but skeptically. no nitpicks unless it's an actual bug or regression.
+```
+
+[`/interrogate`](../../skills/interrogate/SKILL.md) sends the same diff, intent, and rubric to reviewers on different model families. Model diversity is the point. Different models have different blind spots, so a finding two models raise independently is high-confidence signal. The lead sorts everything into `Act on`, `Consider`, `Noted`, and `Dismissed`, with a reason for each dismissal, and applies nothing automatically.
+
+Read the dismissals too. The lead is a pragmatic senior engineer, not an oracle, and you can override it.
+
+## Prototype instead of debating
+
+Never take the first design. Ask for a few, and pick from evidence you can see:
+
+```text
+/poteto-mode prototype a few options for the new dropdown menu. take screenshots or videos for me to compare.
+```
+
+The [Prototype playbook](../../skills/poteto-mode/playbooks/prototype.md) builds throwaway sketches in a scratch directory, puts the variants behind one switcher, drives each one, and captures screenshots or timings. It also works for behavior and algorithms, not just UI. Prototypes are planning with code. They let the agent answer its own open questions by running something instead of asking you, and they leave room for an option you wouldn't have thought of.
+
+The same idea scales up to a real design. Pair `/architect` with prototypes and keep a review gate:
+
+```text
+/poteto-mode we need rate limiting for external webhooks. /architect it first, and answer open questions with prototypes. let me review before proceeding.
+```
+
+Don't spend reviewers on an abstract plan. `/interrogate` belongs on a diff. Point adversarial review at a plan with no code behind it and the reviewers invent theoretical risks and edge cases that will never happen. Let prototypes settle the questions, then review what got built.
+
+## Write the README first for shared code
+
+For a package or API that other code will use, start with the doc a user would read:
+
+```text
+/poteto-mode write a tutorial for how i would use the new config package first. then /teach me why it beats the current one.
+```
+
+Writing the tutorial first forces the caller's view. You describe the API to a hypothetical user and work back to the implementation. The doc also becomes a concrete target the agent checks its own work against. Name [`/technical-writing`](../../skills/technical-writing/SKILL.md) when the doc itself matters, so a tutorial stays a tutorial instead of drifting into reference and explanation at once.
+
+## Plan after the design settles
+
+pstack has no planning skill, on purpose. When you do want a written plan, ask for it once the design is settled:
+
+```text
+/poteto-mode turn this design into a plan. small verifiable PRs, each with its own verification steps.
+```
+
+The [Multi-phase plan playbook](../../skills/poteto-mode/playbooks/multi-phase-plan.md) settles any remaining open questions by prototype, then writes one section per PR, each ending in proof that the change works. A passing test suite alone doesn't count as that proof. The plan is the deliverable. The playbook doesn't implement it, and it names which execution playbook should run it next.
+
+For a migration, state the bar in the prompt:
+
+```text
+/poteto-mode plan the migration of our ui library to the new styling system. small verifiable PRs, each with visual regression checks. the result must match the original exactly, bugs included.
+```
+
+"bugs included" keeps the migration from quietly fixing things on the way, which would make the old and new output impossible to compare. For a project that spans many days, you can commit the plan to the repo for a while so other agents see the work in progress. Delete it when the work lands.
+
+## How much design work does a task deserve?
+
+You might be wondering whether every change needs this. No. Most changes need none of it. A rough ladder:
+
+- A small, finished change you're unsure about needs `/interrogate` alone.
+- A change that crosses function boundaries or moves ownership earns `/architect`, which brings `/arena` with it.
+- A standalone decision where independent attempts would help, like naming, formats, or an algorithm, is `/arena` directly.
+- A coverage matrix, set of parallel checks, or race with declared arms is `/swarm`.
+- An open question you could answer by running something, like a layout, a timing, or an approach, gets a prototype, not a debate.
+- A contested design that's expensive to reverse gets `/architect`, then `/interrogate` before shipping.
+- Work that spans several PRs gets a plan, written after the design settles.
+
+`/poteto-mode` already applies this ladder. Boundary-crossing work triggers `/architect` on its own, so you reach for these directly mainly when you want more or less scrutiny than the default.
+
+Next: [Build and clean the change](./05-build-and-clean.md).