dsh-pstack 0.1.0 → 0.2.0-beta.1

package/LICENSE

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

package/README.md

@@ -1,159 +1,134 @@
 # dsh-pstack
 
-pstack for DeepSeek Harness. Rigorous agent workflows ported from
-[`cursor/plugins/pstack`](https://github.com/cursor/plugins/tree/main/pstack).
+<img src="static/icon.png" alt="pstack logo" width="96" height="96">
 
-pstack helps you write less, but higher quality code. `/poteto-mode` reads a
-task, picks a playbook, and routes the work through the same skills Lauren Tan
-uses at Cursor: investigation, design, implementation, verification, review,
-shipping. This package ports those skills to DSH and gives them a native
-delegation tool.
+pstack 的 DeepSeek Harness 移植。它把 Cursor pstack 的技能、playbook、原则和角色化子代理工作流带到 DSH。
 
-Upstream is pinned as a git submodule at `upstream/cursor-plugins`. The DSH
-tree under `assets/` is generated from it, so upstream fixes flow through a
-repeatable sync instead of a hand fork. The generated tree is committed: it is
-what makes a sync reviewable as a `git diff`.
+安装后，`/poteto-mode` 启动一次严谨任务，`/setup-pstack` 配置各角色使用的模型和推理预算，`/poteto-help` 帮助选择技能或排查用法。
 
-## Install
+## 支持的 DSH 版本
 
-```bash
-dsh plugin --profile web add github:your-org/dsh-pstack
-```
+支持 `0.2.1-rc.3`。安装包在 `engines.dsh` 声明支持的 DSH 版本，其他版本未经验证。新版本验证通过后补充到本节。
 
-Or from a checkout:
+## 实现原理
 
-```bash
-git submodule update --init --depth 1
-dsh plugin --profile web add .
-```
+上游 pstack 对 Claude Code 的适配保留技能原文，生成独立的宿主资产，再用一份宿主适配说明处理工具、路径、模型和能力差异。
 
-Restart `dsh web` after install. The bundle patch mounts two rows:
+dsh-pstack 沿用这个思路。上游技能是内容源，DSH 专用资产单独生成，宿主差异集中说明。上游更新可以持续同步，DSH 特有的行为不会散落在每个技能里。
 
-- `pstack` registers the bundled skill provider. Every converted skill appears
-  in the session catalog with its Cursor invocation policy preserved:
-  `/poteto-mode` and friends stay user-invocable, and the principles stay
-  model-invocable.
-- `pstack-subagent` registers the `pstack_subagent` tool, the DSH replacement
-  for Cursor's `Task` tool.
+## 必要依赖
 
-Verify the layer without booting:
+- worktree 插件。并行写入和隔离工作目录需要它。未启用时插件自动启用，已启用时不会重复启用。
+- DSH 的 skills 和 subagents 能力，由支持的 DSH 版本提供。
+- Node.js `>=22.19`。仅 npm CLI 部署需要它出现在 `PATH` 上；Desktop（Electron）部署走 Host 自己的运行时。
+- Git。worktree 需要 Git 仓库。
 
-```bash
-dsh --profile web --dump-config | grep -A2 'pstack'
-```
+随包的编排、PR watcher、计划检查、worktree 审计和决策日志脚本已构建为单文件 Node 产物，依赖全部内联。运行时通过 `pstack_script` 工具以宿主进程启动它们，因此**不需要 Bun，也不需要 bash，更不需要安装任何依赖**。Desktop 用户不在 `PATH` 上放 `node` 也能用：工具用 Electron 自带的 Node 运行时执行，并在需要时自动附加 `ELECTRON_RUN_AS_NODE`。脚本从**会话目录**启动，所以参数里的相对路径落在当前工作区或 worktree 内。
 
-## Use
+`pstack_script` 直接 `spawn` 子进程，因此**不经过命令审批，也不受 DSH 的 sandbox policy 约束**：它只能执行本包随附、由封闭 `id` 枚举选中的脚本，但脚本实际读了什么、写了哪里，Host 不会拦。这是为了在没有 `PATH` `node` 的部署里仍能运行为此付出的代价。需要审批与沙箱约束的命令请用 DSH 自己的 bash 工具。
 
-Start with a real task:
+worktree 只隔离工作目录和分支，不提供 VM、网络、凭据或端口隔离。需要独立机器或云端执行时，worktree 不是替代品。
 
-```text
-/poteto-mode add a --json flag to this command. text output stays byte-identical. verify both.
-```
+Linux 和 macOS 是主要验证目标，Windows 未在实机验证。脚本本身已不含 shell 依赖，但 Windows 上的真实行为仍未验收。
+
+## 与 Agent Team 的兼容性
 
-`/poteto-mode` opens a todo list whose first items are the matched playbook's
-steps. Each step names the skill it routes to. The other skills work directly:
-`/how`, `/why`, `/architect`, `/arena`, `/swarm`, `/interrogate`, `/tdd`,
-`/no-comments`, `/unslop`, `/technical-writing`, `/sharpen`, `/teach`, and the
-twenty-four `principle-*` rules.
+> **兼容性警告**
+>
+> 当前版本禁止与 Agent Team 同时启用。Agent Team 会用同名工具遮蔽 `send_message`、`interrupt_agent` 和 `list_agents`，pstack 无法再用它们 steer、列出或中断自己的子代理。两者还共享子代理激活容量。`pstack_subagent` 的角色路由和 reasoning effort 计算本身不受影响，但同一 profile 中的 Team 工具会改变可见工具面。
+>
+> 需要同时使用时，请使用两个独立 profile。
 
-See the converted [pstack guide](assets/docs/guide/README.md) and the
-[DSH adapter reference](assets/docs/harness/dsh.md).
+决策记录见 [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 页面上的相对链接指向不存在的路径。
 
-### Configure roles
+## 安装
 
-`/setup-pstack` detects the routes your session can use and writes
-`~/.dsh/pstack-models.md`. One role per line:
+通过 npm 包 `dsh-pstack` 安装。`<profile>` 换成目标 profile，例如 `web`。
 
-```text
-# pstack model configuration. One line per role.
-# Value: inherit-parent | <provider>/<model> [effort]
-# budget: large (xhigh)
-feature, refactoring: deepseek-official/deepseek-reasoner high
-judgment and prose: inherit-parent
+```bash
+dsh plugin --profile <profile> add dsh-pstack
 ```
 
-A missing line means the role inherits the parent chat's route. The tool reads
-this file on every delegation, so edits apply without restarting.
+安装会启用 bundle。DSH 提示重启时按提示操作。
 
-### Delegate
+## 快速开始
 
-`pstack_subagent` is the one delegation surface:
+1. 安装插件，进入目标 profile。
+2. 运行 `/setup-pstack`，选择推理预算和每个角色的模型。
+3. 用 `/poteto-mode` 加任务开始一次严谨工作流。
+4. 不确定用哪个技能时，运行 `/poteto-help`。
 
-```text
-pstack_subagent(
-  description: "port the retry helper",
-  prompt: "Port src/retry.ts ... prove it with pnpm test retry",
-  agent: "poteto-agent",
-  role: "feature, refactoring",
-)
-```
+`/poteto-mode` 会匹配 playbook，把步骤写进 todo，并按需读取其他技能。小改动可以直接做，不必使用它。
+
+## 角色配置
+
+`/setup-pstack` 写入 `$DSH_HOME/pstack-models.md`，一行一个角色。`$DSH_HOME` 是 DSH 的用户目录。值可以是 `inherit-parent`，也可以是 `provider/model` 加推理档位。
 
-- `agent`: `poteto-agent` (default), `general`, or `comment-sicko`. The tool
-  prepends the packaged agent instructions for the first and third.
-- `role`: a line from `~/.dsh/pstack-models.md`. Omit it to inherit the parent
-  route.
-- `cwd`: optional child working directory.
+- `inherit-parent` 使用父会话的模型和推理档位。
+- panel 角色的值是列表，每一项启动一个子代理。
+- 删除某个角色的行，该角色回落到父路由。
+- 重新运行 `/setup-pstack` 会更新配置，不会叠加旧值。
 
-The call returns `started subagent <id>` immediately. The runtime reports the
-final answer in a completion notice. Use `send_message` to steer a running
-child and `list_agents` to enumerate them.
+模型必须出现在当前 DSH 的 provider 和模型列表中。
 
-## What changed from Cursor
+### 推理档位
 
-| Cursor                                                                      | DSH                                                                                                     |
-| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `Task` tool                                                                 | `pstack_subagent`                                                                                       |
-| `subagent_type`                                                             | `agent`                                                                                                 |
-| model slug                                                                  | `role` resolved from `~/.dsh/pstack-models.md`                                                          |
-| `readonly` / `run_in_background` / `environment`                            | Background by default; say "do not edit" in the prompt                                                  |
-| `~/.cursor/rules/pstack-models.mdc`                                         | `~/.dsh/pstack-models.md`                                                                               |
-| `.cursor/skills/`                                                           | `.dsh/skills/`                                                                                          |
-| Automations, Bugbot, cloud agents, Custom Modes, `/loop`, `cursor-team-kit` | Marked skipped, or remapped to `schedule_create`, `create_goal`, worktree subagents, and `/no-comments` |
+角色行里的档位是那个角色**起步**用的档位。实际档位随任务难度双向浮动：
 
-`skills/make-bot-ui` is not ported: it depends entirely on Cursor Automations.
-It is not shipped, in any form. If you need it, read it from the upstream
-submodule at `upstream/cursor-plugins/pstack/skills/make-bot-ui/`.
+- 调用 `pstack_subagent` 时传 `reasoningEffort`，覆盖本次派发中每个 panel 项的档位。难任务调高，机械活调低。
+- 子代理自己可以调 `set_reasoning_effort`，从下一步生效，已在飞行中的请求不受影响。
 
-## Develop
+合法档位由目标模型自己广告。本包不假设通用阶梯，所以参数是自由字符串而不是枚举。值不被支持时，调用在启动任何子代理**之前**失败，并在错误里列出该模型真实支持的档位。panel 中任一项不支持时整次失败，不会只启动一半。
 
-Requirements: Node 22.19+ and pnpm. Vite+ provides the build, test, lint, and
-format toolchain.
+
+## 功能范围与已知限制
+
+包含 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
-vp install          # install dependencies
-git submodule update --init --depth 1
-vp run sync         # regenerate assets/ from upstream pstack
-vp check            # format, lint, type-check
-vp test             # unit tests
-vp pack             # build dist/
+dsh plugin --profile <profile> add dsh-pstack@latest
 ```
 
-### Repository layout
-
-```text
-src/provider.ts          bundled skill provider (ctx.skills)
-src/subagent.ts          pstack_subagent tool (ctx.subagents + ctx.tools)
-src/roles.ts             ~/.dsh/pstack-models.md parsing and role resolution
-src/frontmatter.ts       SKILL.md frontmatter parser
-scripts/adapt.ts         upstream-to-DSH rewrite rules
-scripts/sync-upstream.ts generator: upstream -> assets/
-tests/                   unit tests for provider, roles, and prompt assembly
-assets/                  generated: skills, agents, docs (committed)
-cordis.patch.yml         the bundle layer this package installs
-upstream/cursor-plugins  git submodule, upstream reference only
+卸载：
+
+```bash
+dsh plugin --profile <profile> remove dsh-pstack
 ```
 
-`assets/` is generated. Never hand-edit it. Change `scripts/adapt.ts` or a
-skill's upstream source, then run `vp run sync`.
+角色文件在 DSH 用户目录，卸载不会删除它。不再使用时自行删除 `$DSH_HOME/pstack-models.md`。升级或卸载后按 DSH 提示重启会话。
+
+## 安全与数据
+
+- 代理在 DSH 权限模型下读写文件、执行命令，子代理继承调用方的策略和权限边界。
+- 需要审批的操作按 DSH 配置请求确认。不要在无人值守任务中放宽不理解的权限。
+- 不要把 API key、token 或密码写进角色文件、prompt 或仓库。
+- 会话记录保存在 DSH 的会话存储中，pstack 不另建云端记录。
+- 上游技能可能要求访问网络或代码托管平台。是否允许由 DSH 的审批和沙箱配置决定。
+
+## 故障排查
+
+按顺序检查。
 
-[`docs/porting/`](docs/porting/README.md) is the policy the converter enforces:
-translate names, not sentences; awkward grammar is acceptable, changed meaning
-is not. It also records why the generated tree is committed rather than ignored.
+1. 确认 DSH 版本在支持范围内。
+2. 确认 worktree 插件可用，必要时先手动启用一次。
+3. 确认当前 profile 没有同时启用 Agent Team。
+4. 运行 `/setup-pstack` 检查角色配置。
+5. 仍有问题时在 [GitHub Issues](https://github.com/l246804/dsh-pstack/issues) 提交，附 DSH 版本、profile 名、复现步骤和错误信息。不要贴密钥或私有会话内容。
 
-`vp run sync:check` fails when the committed tree differs from a fresh
-conversion and when a rewrite no longer matches its upstream anchor. Run it
-before publishing.
+## 许可证与上游归属
 
-## License
+MIT，见 [LICENSE](LICENSE)。
 
-MIT. The ported skills are MIT, copyright Lauren Tan; see [LICENSE](LICENSE).
+上游 pstack 版权归 Lauren Tan，使用 MIT 许可证。技能、playbook 和代理文本来自 [cursor/plugins](https://github.com/cursor/plugins/tree/main/pstack)。

package/assets/agents/comment-sicko.md

@@ -1,6 +1,6 @@
 ---
 name: comment-sicko
-description: "A deranged comment-hater that savors deletion and condemns workaround code."
+description: A deranged comment-hater that savors deletion and condemns workaround code.
 ---
 
 # Comment Sicko

package/assets/agents/poteto-agent.md

@@ -1,8 +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 `agent: \"general\"` skips that read and drifts."
+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. Use the absolute path your parent gave you. With no path, before any other work, search `~/.dsh/plugins/` for a file whose path ends in `skills/poteto-mode/SKILL.md`. If more than one file matches, use the copy whose `package.json` has the highest `version`. Your skill catalog hides this skill, so a missing catalog entry does not mean pstack is absent. If no such file exists, stop and tell your parent. Navigate to a leaf `principle-*` skill whenever you apply that principle.
+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

@@ -4,13 +4,13 @@ In this page you install the plugin, pick which models pstack uses, and run your
 
 ## Install the plugin
 
-Install the bundle into your DSH profile:
+Install the bundle into the profile you work in. `<profile>` is that profile's name, such as `web`:
 
 ```bash
-dsh plugin --profile web add github:your-org/dsh-pstack
+dsh plugin --profile <profile> add dsh-pstack
 ```
 
-Restart `dsh web` after install. The bundle mounts the pstack skill provider and the `pstack_subagent` tool.
+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
 
@@ -20,13 +20,13 @@ Run:
 /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/pstack-models.md`, a small rule every pstack skill reads.
+[`/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 defaults inherit the parent chat route, so they cost nothing extra beyond the children themselves. A real route written as `<provider>/<model> [effort]` pins that role; `unlimited`, `large`, `medium`, and `small` set the effort token on those routes.
+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 rule 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 rule written before the change still pins the old default, so delete those role lines, or delete the file, then run `/setup-pstack` again.
+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.
 
-`inherit-parent` means the child runs on the parent chat model. Both `inherit-parent` and `auto` are accepted aliases, and neither is a model slug. For a panel role the value is a comma-separated list, and one subagent runs per entry, so the list length sets the panel size. Setup also configures `swarm workers`, the default route for every `/swarm` worker unless a race names a route for each arm.
+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
 
@@ -38,7 +38,7 @@ If you're new to pstack, say yes. An agent that can check its own work keeps goi
 
 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, start a new chat. The model rule applies to new sessions.
+After setup the file applies from the next delegation on, because `pstack_subagent` re-reads it every time.
 
 ## Keep the cost in check
 
@@ -59,6 +59,6 @@ Pick something real but small, and describe it the way you'd describe it to a co
 
 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. DSH has no persistent custom mode. Start each new task with `/poteto-mode`, and its instructions apply to that turn.
+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

@@ -90,7 +90,7 @@ continue
 keep going until done
 ```
 
-Short works because the playbook holds the structure, and `/poteto-mode` applies to that turn. [Set up pstack](./01-setup.md#run-your-first-task) shows how to start one. Your words carry the intent, and the skill carries the rigor.
+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"
 
@@ -102,11 +102,11 @@ A long chat accumulates context from the last task. When you change subjects, sa
 
 "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 machine
+## 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. The cleanest isolation is a [worktree subagent](https://cursor.com/docs/subagents#cloud-subagents). Each one gets its own worktree and branch, so it can install dependencies, run your app, and record video of the result without touching your machine. Ask the parent chat to hand the work to a worktree subagent.
+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.
 
-When the work has to stay local, ask for a worktree up front:
+Ask for a worktree up front:
 
 ```text
 /poteto-mode new task. branch off <base> in a fresh worktree, then port the parser change there.

package/assets/docs/guide/05-build-and-clean.md

@@ -56,7 +56,7 @@ In context, that's enough. [`/tdd`](../../skills/tdd/SKILL.md) writes the smalle
 
 ## Clean before you commit
 
-The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) runs the pre-commit cleanup on the diff before each commit and applies [`/unslop`](../../skills/unslop/SKILL.md) to the PR description and commit bodies. No single skill does this here. Ask for the same outcome in plain words: remove narrating comments, unsupported guards, dead compatibility paths, and unrelated edits.
+The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) reads the diff for narrative comments, unsupported guards, dead compatibility paths, and unrelated edits before each commit, and applies [`/unslop`](../../skills/unslop/SKILL.md) to the PR description and commit bodies. `/deslop` ships in Cursor's `cursor-team-kit` and has no counterpart here. Ask for the same outcome in plain words: remove narrating comments, unsupported guards, dead compatibility paths, and unrelated edits.
 
 For prose, `/unslop` takes a target and any extra rules you have:
 
@@ -76,8 +76,8 @@ Comments need their own pass, and not from the agent that wrote them. An author
 
 [`/no-comments`](../../skills/no-comments/SKILL.md) spawns [Comment Sicko](../../agents/comment-sicko.md), a read-only reviewer with a short keep list: license headers, doc comments on a public API, links that explain what code can't, behavior forced by an external dependency you can't reshape. Everything else goes. A surprise in your own code gets no such pass. The comment comes back as a refactor flag, and `/no-comments` fixes the flags it accepts at the root cause. When a comment claims a constraint, "do not remove", the skill offers to encode the claim as a type, test, or lint. Either way, the comment comes out.
 
-The division of labor is worth keeping straight. The pre-commit cleanup removes slop from the code, `/unslop` cleans it out of prose, and `/no-comments` hands the comments to a reviewer who didn't write them.
+The division of labor is worth keeping straight. The diff read-through and `/no-comments` clean the code, `/unslop` cleans slop out of prose, and `/no-comments` hands the comments to a reviewer who didn't write them.
 
-**Pitfall:** cleanup is not optional polish. A diff with narrating comments and defensive dead weight reads as unfinished to reviewers, and the extra code is where the next bug hides. If the diff feels padded, say `strip the slop` before you commit, not after review calls it out.
+**Pitfall:** cleanup is not optional polish. A diff with narrating comments and defensive dead weight reads as unfinished to reviewers, and the extra code is where the next bug hides. If the diff feels padded, say `deslop it` before you commit, not after review calls it out.
 
 Next: [Verify and ship](./06-verify-and-ship.md).

package/assets/docs/guide/06-verify-and-ship.md

@@ -19,7 +19,7 @@ Now the agent has three checks it can run, not a mood to satisfy. When the reply
 Match the check to the change:
 
 - A CLI change runs the real command.
-- A UI change walks the changed flow in the running app. When it must match a reference pixel for pixel, the [Visual parity playbook](../../skills/poteto-mode/playbooks/visual-parity.md) diffs screenshots against a frozen baseline instead of judging by eye.
+- A UI change walks the changed flow in the running app. When it must match a reference pixel for pixel, the [Visual parity playbook](../../skills/poteto-mode/playbooks/visual-parity.md) requires a real image comparison against a frozen baseline, not judgment by eye. Name the comparison tool and the per-image delta it reports; this package does not supply one. If it is unavailable, mark parity unverified rather than claiming a match.
 - A parser or migration replays a saved input.
 - A perf change compares before and after profiles.
 - A storage change reads back the written value.
@@ -85,7 +85,7 @@ While you're there, make the dev setup repeatable too: seeded data, test users,
 
 ## Keep the verification skill honest
 
-Apps change, and feature maps go out of date. Run this at least once a day, ideally from a scheduled automation so nobody has to remember:
+Apps change, and feature maps go out of date. Run this at least once a day, ideally from a cron job or a `schedule_create` reminder hoisted by the top-level agent, so nobody has to remember:
 
 ```text
 /maintain-verification-skill

package/assets/docs/guide/07-overnight.md

@@ -1,6 +1,6 @@
 # Run work while you sleep
 
-This is the payoff for everything before it. An agent you can trust to verify its own work is an agent you can leave alone with a hard task. What makes that safe isn't hope. It's a checkable finish condition, an isolated worktree or a worktree subagent, and a decision log you audit in the morning.
+This is the payoff for everything before it. An agent you can trust to verify its own work is an agent you can leave alone with a hard task. What makes that safe isn't hope. It's a checkable finish condition, a goal that carries the run, an isolated worktree, and a decision log you audit in the morning.
 
 ![She waves goodnight from the door while robots keep the factory running, one updating a DECISION LOG wall board under a BUILD LOOP ACTIVE sign.](./images/overnight.jpg)
 
@@ -9,7 +9,7 @@ This is the payoff for everything before it. An agent you can trust to verify it
 A loop you don't trust just produces unchecked work faster, and the mess compounds with every iteration. Before you leave one running, check that it has earned it:
 
 - You've done the task once by hand, or watched an agent do it, so you know what good looks like.
-- The agent has the tools and signals you'd use yourself: the verification skill, the profiler, the logs.
+- The agent has the tools and signals you'd use yourself: the verification skill and the logs, plus the profiler or tracer this task actually needs. Check that it can capture the real artifact; if it cannot, report the missing measurement rather than treating the task as verified.
 - Every stage proves its work and can stop the line when the work misses the bar.
 - You've read a few transcripts and turned the repeated failures into tools, skills, or checks.
 
@@ -23,7 +23,7 @@ A good handoff has the goal, the finish condition, permissions, and an escape ha
 /poteto-mode im going to bed. migrate every caller to the new parser in a fresh worktree off <base>.
 done means zero old callers, all parser fixtures pass, old api deleted.
 keep a decision log. don't ask me before committing.
-Arm a `schedule_create` heartbeat for the finish condition. if you're truly stuck after a few hours, stop and write up why.
+register the predicate as a goal and keep going until it holds. if you're truly stuck after a few hours, stop and write up why.
 ```
 
 Walk through what each line buys you:
@@ -32,12 +32,12 @@ Walk through what each line buys you:
 - "done means..." turns the goal into checks every iteration can run.
 - "fresh worktree off `<base>`" keeps the run from colliding with anything else you have open.
 - "don't ask me before committing" pre-answers the permission the agent would otherwise block on.
-- `schedule_create` is a DSH tool, not a pstack skill. The [Autonomous run playbook](../../skills/poteto-mode/playbooks/autonomous-run.md) uses it to re-check the finish condition on events or a heartbeat.
+- "register the predicate as a goal" maps to `create_goal`. The goal is what survives a long run, and it is what the [Autonomous run playbook](../../skills/poteto-mode/playbooks/autonomous-run.md) drives: `get_goal` reads the phase back, `update_goal` with `complete` ends it, and a `schedule_create` reminder can only act as a heartbeat, because it delivers a message into this Session and cannot watch CI or a pull request.
 - The escape hatch lets it stop at a genuine dead end and write up why, which beats eight hours of creative goal reinterpretation.
 
 Because you'll review this work after stepping away, `/poteto-mode` routes it through [`/figure-it-out`](../../skills/figure-it-out/SKILL.md), which designs the run's phases before any code and wires in the decision log.
 
-To stop a run on purpose, tell the agent to pause, or that you're about to go offline or restart the harness. The [Pause safely playbook](../../skills/poteto-mode/playbooks/pause-safely.md) finishes or backs out of the current step, commits a work-in-progress checkpoint, and writes a resume note. A fresh chat picks the work up from that note through the Session pickup playbook. Saying "keep going" never triggers a pause.
+To stop a run on purpose, tell the agent to pause, or that you're about to go offline. Closing this host ends every child and leaves nothing running in the background, and an active goal comes back disarmed, so a restarted Session has to be resumed on purpose instead of continuing by itself. The [Pause safely playbook](../../skills/poteto-mode/playbooks/pause-safely.md) finishes or backs out of the current step, commits a work-in-progress checkpoint, and writes a resume note. A fresh chat picks the work up from that note through the Session pickup playbook. Saying "keep going" never triggers a pause.
 
 ## What the loop does all night
 
@@ -93,12 +93,12 @@ The contract above drives one task to one finish condition. Some nights hold mor
 
 ## Run many projects in parallel
 
-A long-running coordinator needs one agent with a persistent thread. The coordinator doesn't write code. It directs subagents, which run in the background, so the work continues while you are elsewhere. That's the shape the Orchestrate playbook expects. Start your prompts to the coordinator with `/poteto-mode`, and the subagents it spawns follow the playbooks.
+There is no managed thread and no remote machine here, so a program runs in one long-lived Session on this computer and stops when that Session stops. The coordinator still doesn't write code. It directs `pstack_subagent` children, each in its own worktree, and it keeps its state in the store on disk, which is what lets a cold start pick the program up. That is the shape the Orchestrate playbook expects. Start every prompt to the coordinator with `/poteto-mode`, and the children it starts follow the playbooks.
 
 A few habits help:
 
-- Give each body of work its own Project, such as a feature, a migration, a perf push, or a tech-debt cleanup. Several can run side by side.
-- Drag related chats into the Project, finished ones included. They become context for every agent in it.
+- Give each body of work its own store directory, such as a feature, a migration, a perf push, or a tech-debt cleanup. Several can run side by side in separate Sessions.
+- Point each new Session at the finished runs it needs, because a child does not inherit another Session's context and a brief is the only thing it starts from.
 - Give each PR a verification swarm before it merges, and let Autopilot-stack or Autopilot-full carry the queue.
 - Ask the coordinator for a plan backed by data, and have it answer open questions with prototypes before it asks you.
 
@@ -110,13 +110,11 @@ One prompt can carry a whole Project, from research through execution:
 
 ## Let loops start themselves
 
-Every loop above still waits for you to start it. A scheduled or event-driven automation removes that step. Software maintenance splits into stages that suit this well: triage a report, reproduce it, fix it, verify the fix. Two rules keep such a line trustworthy:
+Every loop above still waits for you to start it. A reminder on a wall clock can begin the next pass, and that is the whole of it: `schedule_create` delivers a follow-up into the Session that created it, cannot watch a report arrive or a pull request change, and refuses a delegated caller. Software maintenance splits into stages that suit this well: triage a report, reproduce it, fix it, verify the fix. Two rules keep such a line trustworthy:
 
 - Every stage can stop the line. Triage can decide the report is expected behavior, repro can fail to reproduce it, and the fixer can judge the change too risky. Each of those outcomes is useful, because it keeps bad work from reaching the next stage, where it costs more to undo.
 - Every stage hands over evidence. Repro attaches screenshots and video of the broken state, and the fix attaches before-and-after proof. A human can then check that the agent fixed the right thing before reading a line of code.
 
-pstack ships this as a dormant [automation pack](../../automations/benny/README.md) for Slack issue reports. One automation triages each report. The other reproduces confirmed bugs and may prepare a small draft fix. Point an agent at its [`FOR_AGENTS.md`](../../automations/benny/FOR_AGENTS.md) and name the target repository to set it up.
-
-**Pitfall:** a duration is not a finish condition. "work on this for 4 hours" gives the agent nothing to check, and you'll wake up to four hours of motion instead of a result. Give the wake prompt a predicate that can pass or fail.
+**Pitfall:** a duration is not a finish condition. "work on this for 4 hours" gives the agent nothing to check, and you'll wake up to four hours of motion instead of a result. Give the goal a predicate that can pass or fail.
 
 Next: [Steer with principle names](./08-principles.md).

package/assets/docs/guide/09-make-it-yours.md

@@ -10,7 +10,7 @@ Start smaller than you think. You don't need many skills on day one, or even thi
 /automate-me
 ```
 
-You don't describe your style, because [`/automate-me`](../../skills/automate-me/SKILL.md) reads it out of your history. It mines your recent transcripts in the active workspace for repeated preferences, in how you like replies, delegation, verification, code, prose, and process, then asks you which patterns are really you. It drafts `.dsh/skills/<your-name>-mode/SKILL.md` through the authoring-a-skill playbook, runs the draft through [`/unslop`](../../skills/unslop/SKILL.md), and opens a PR from a worktree so you review it like any other change.
+You don't describe your style, because [`/automate-me`](../../skills/automate-me/SKILL.md) reads it out of your history. Through `pstack_history` it reads this Session and its reviewable direct children as raw events, and it covers other Sessions in the same workspace with the official search, looking for repeated preferences in how you like replies, delegation, verification, code, prose, and process, then asks you which patterns are really you. It drafts `.dsh/skills/<your-name>-mode/SKILL.md` with the authoring playbook, runs the draft through [`/unslop`](../../skills/unslop/SKILL.md), and opens a PR from a worktree so you review it like any other change.
 
 Run it again whenever your habits drift:
 
@@ -57,7 +57,7 @@ When you already know the workflow you want to capture:
 /poteto-mode write a skill for verifying database migrations in this repo
 ```
 
-Writing a skill matches the [Authoring or modifying a skill playbook](../../skills/poteto-mode/playbooks/authoring-a-skill.md), which routes through the authoring-a-skill playbook, validates the frontmatter and links, and ships the result through the Opening a PR playbook. Agent-facing prose has a higher bar than human prose, because an unhelpful sentence becomes an instruction some future agent follows. Let the playbook hold that bar rather than writing a `SKILL.md` freehand.
+Writing a skill matches the [Authoring or modifying a skill playbook](../../skills/poteto-mode/playbooks/authoring-a-skill.md), which writes the `SKILL.md` by hand, validates the frontmatter, links, and structure with this package's own checks, and ships the result through the Opening a PR playbook. Agent-facing prose has a higher bar than human prose, because an unhelpful sentence becomes an instruction some future agent follows. Let the playbook hold that bar rather than writing a `SKILL.md` freehand.
 
 Two special cases have their own generators. A skill that must drive your app and prove behavior is a verification skill, so use [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md) and [`/maintain-verification-skill`](../../skills/maintain-verification-skill/SKILL.md) instead. A skill that checks a property of your code with a model checker, a proof, or another verifier is a formal verification skill, so use [`/create-formal-verification-skill`](../../skills/create-formal-verification-skill/SKILL.md) and [`/maintain-formal-verification-skill`](../../skills/maintain-formal-verification-skill/SKILL.md). [Verify and ship](./06-verify-and-ship.md#prove-a-property-with-a-formal-verification-skill) covers both kinds.
 
@@ -91,10 +91,6 @@ The [Eval playbook](../../skills/poteto-mode/playbooks/eval.md) is built around
 
 Read every output yourself before accepting the verdict. If you disagree with the judge, suspect the rubric before you suspect your judgment.
 
-## One skill is deliberately not ported
-
-`/make-bot-ui` is not ported. It depends on Cursor Automations, which DSH does not provide. Copy it from the upstream submodule if you need it.
-
 **Pitfall:** don't edit a skill mid-task because it's misbehaving. Fix it in its own PR and keep the task moving. A skill edit that ships tangled into feature work is invisible to review and impossible to evaluate.
 
 Next: [Recipes and pitfalls](./10-recipes-and-pitfalls.md).

package/assets/docs/guide/10-recipes-and-pitfalls.md

@@ -2,7 +2,7 @@
 
 Prompts worth copying, then the mistakes everyone makes once. Swap in your own paths and finish conditions. The recipes are deliberately informal. That's how they get typed in practice, and the skills read intent fine.
 
-![She tastes a finished dish while robots cook from a recipe box, with pinned cards reading /how, /tdd, and /loop above the counter.](./images/recipes.jpg)
+![She tastes a finished dish while robots cook from a recipe box, with pinned cards reading /how and /tdd above the counter.](./images/recipes.jpg)
 
 ## Understand an unfamiliar subsystem
 
@@ -161,11 +161,11 @@ That's the whole prompt. [`/bro`](../../skills/bro/SKILL.md) restates the last m
 ## The pitfalls
 
 - **Enumerating skills in the prompt.** "use /how then /architect then /arena" reorders steps the playbook already sequences. State the goal and constraints. Name a skill only to override a default.
-- **A vague finish condition.** "make it better" gives the loop nothing to check. Give a command or artifact that can pass or fail.
+- **A vague finish condition.** "make it better" gives a goal nothing to check. Give a command or artifact that can pass or fail.
 - **Leading with your theory of the cause.** The agent searches wherever you pointed. Ask it to restate the problem first, then share your hunch.
 - **Taking the first design.** One attempt locks in the first shape the model thought of. Ask for prototypes or `/architect` and pick from evidence.
 - **Polishing an abstract plan.** Adversarial review of a plan with no code behind it invents risks that will never happen. Settle the open questions with prototypes, then review what got built.
-- **Parallel agents in one worktree.** They overwrite each other, and nobody can tell which agent changed what. Run them as worktree subagents, or say "own worktree per attempt".
+- **Parallel agents in one worktree.** They overwrite each other, and nobody can tell which agent changed what. Say "own worktree per attempt", and pass each child its checkout's absolute path as `cwd`, because a shared checkout isolates nothing.
 - **Looping before you trust the loop.** A loop that can't verify its own work only makes unchecked work faster. Get the verification skill working first.
 - **Trusting an unvetted number.** A warm cache or a skipped code path can fake a speedup. Run `/benchmark-checklist` before the number goes anywhere.
 - **Correcting the same mistake by hand.** A correction in chat helps one run. `/correct` fixes the repo so no later run repeats it.

package/assets/docs/guide/README.md

@@ -10,7 +10,7 @@ Here's what you'll learn:
 4. [Design the change](./04-design.md). `/architect`, `/arena`, `/swarm`, `/interrogate`, prototypes, and plans before code locks in a shape.
 5. [Build and clean the change](./05-build-and-clean.md). The build playbooks, `/tdd`, `/unslop`, and `/no-comments`.
 6. [Verify and ship](./06-verify-and-ship.md). Prove behavior on the real app, formally verify what tests rarely reach, vet numbers with `/benchmark-checklist`, then open a focused PR and drive it to merged.
-7. [Run work while you sleep](./07-overnight.md). Trust before loops, an overnight contract, a decision log you can audit, and Projects and automations that scale past one agent.
+7. [Run work while you sleep](./07-overnight.md). Trust before long runs, an overnight contract, a decision log you can audit, and goals, reminders, and worktrees that carry a run past one agent.
 8. [Steer with principle names](./08-principles.md). The 24 names that redirect an agent mid-task.
 9. [Make it yours](./09-make-it-yours.md). Your own mode, `/correct` for repeated mistakes, and how to test a skill change.
 10. [Recipes and pitfalls](./10-recipes-and-pitfalls.md). Prompts to copy and mistakes to skip.