dsh-pstack 0.1.0 → 0.2.0-beta.1

package/assets/skills/poteto-mode/scripts/worktree-audit.sh

@@ -1,127 +0,0 @@
-#!/usr/bin/env bash
-# Read-only worktree prune audit. Classifies every git worktree by size, merge
-# state, uncommitted work, remote/PR state, and the most recent chat that
-# operated in it. Emits a table sorted by size with a suggested bucket. Never
-# deletes anything; deletion stays a human-gated step in the playbook.
-#
-# Usage: worktree-audit.sh [-b|--base <ref>] [repo-path]
-#   repo-path defaults to the current repo.
-#   -b sets the ref the MERGED column checks against (e.g. origin/integration).
-#   Without it the base is origin/HEAD, then origin/main, then origin/master.
-#   origin/HEAD is the remote's default branch, not necessarily the branch PRs
-#   merge into; pass -b when they differ.
-set -u
-
-base=""
-while [ $# -gt 0 ]; do
-	case "$1" in
-	-b|--base) [ $# -ge 2 ] || { echo "error: $1 needs a ref" >&2; exit 2; }; base="$2"; shift 2 ;;
-	-h|--help) sed -n '2,/^set -u/p' "$0" | sed '$d; s/^# \{0,1\}//'; exit 0 ;;
-	-*) echo "error: unknown option: $1" >&2; exit 2 ;;
-	*) break ;;
-	esac
-done
-
-repo="${1:-$(git rev-parse --show-toplevel 2>/dev/null)}"
-[ -z "$repo" ] && { echo "not in a git repo; pass a repo path" >&2; exit 1; }
-cd "$repo" || exit 1
-git rev-parse --git-dir >/dev/null 2>&1 || { echo "error: not a git repo: $repo" >&2; exit 1; }
-
-# Main worktree is the first entry; everything else is a candidate.
-main_wt=$(git worktree list --porcelain | awk '/^worktree /{print $2; exit}')
-
-if [ -z "$base" ]; then
-	for cand in "$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null)" origin/main origin/master; do
-		[ -n "$cand" ] && git rev-parse --verify --quiet "$cand^{commit}" >/dev/null && { base="$cand"; break; }
-	done
-	[ -z "$base" ] && { echo "error: no base ref (origin/HEAD, origin/main, origin/master all missing); pass -b <ref>" >&2; exit 1; }
-	echo "warn: no -b given; MERGED checks against $base" >&2
-fi
-
-# The base drives the merge check. The fetch is best-effort (stale is fine for
-# a first pass) and runs before the check, since -b may name a branch not
-# fetched yet. The explicit refspec creates it even in a single-branch clone.
-case "$base" in
-origin/*) git fetch origin "+refs/heads/${base#origin/}:refs/remotes/$base" --quiet 2>/dev/null \
-	|| echo "warn: could not fetch $base; merged column may be stale" >&2 ;;
-esac
-git rev-parse --verify --quiet "$base^{commit}" >/dev/null 2>&1 || { echo "error: base ref not found: $base" >&2; exit 1; }
-
-# PR state by branch, fetched once as [{number, state, head}] with a lowercase
-# state. Origin when its CLI can read this repo's PRs, otherwise gh. Empty when
-# neither can.
-prs=$(mktemp)
-if command -v origin >/dev/null 2>&1 \
-	&& raw=$(origin pr list --author "@me" --state all --limit 1000 \
-		--json number,status,headRef 2>/dev/null); then
-	printf '%s' "$raw" | jq '[.[] | {number, state: .status, head: .headRef}]' > "$prs" 2>/dev/null
-elif raw=$(gh pr list --author "@me" --state all --limit 1000 \
-	--json number,state,headRefName 2>/dev/null); then
-	printf '%s' "$raw" | jq '[.[] | {number, state: (.state | ascii_downcase), head: .headRefName}]' > "$prs" 2>/dev/null
-fi
-[ -s "$prs" ] || echo "[]" > "$prs"
-
-# Session logs root: $DSH_HOME/sessions/<workspace-slug>. Every directory level
-# below it is one session id, so a worktree matches when any log under it names
-# the worktree path.
-transcripts="${DSH_HOME:-$HOME/.dsh}/sessions"
-now=$(date +%s)
-
-echo "# base: $base"
-printf "SIZE\tAGE\tMERGED\tDIRTY\tREMOTE\tPR\tLAST_CHAT\tBUCKET\tWORKTREE\n"
-
-git worktree list --porcelain | awk '/^worktree /{print $2}' | while read -r wt; do
-	[ "$wt" = "$main_wt" ] && continue
-
-	size=$(du -sh "$wt" 2>/dev/null | awk '{print $1}')
-	head=$(git -C "$wt" rev-parse HEAD 2>/dev/null)
-	head_ts=$(git -C "$wt" log -1 --format='%ct' HEAD 2>/dev/null || echo 0)
-	age=$([ "$head_ts" -gt 0 ] 2>/dev/null && echo "$(( (now - head_ts) / 86400 ))d" || echo "?")
-
-	# Squash-merged branches are not ancestors of the base, so PR state is the
-	# real signal; merge-base only catches fast-forward/rebase merges.
-	git merge-base --is-ancestor "$head" "$base" 2>/dev/null && merged=YES || merged=no
-
-	# Distinguish real WIP (tracked edits) from disposable untracked scratch.
-	porcelain=$(git -C "$wt" status --porcelain 2>/dev/null)
-	if [ -z "$porcelain" ]; then dirty=clean
-	elif printf '%s\n' "$porcelain" | grep -qv '^??'; then
-		dirty="wip:$(printf '%s\n' "$porcelain" | grep -cv '^??')"
-	else dirty="scratch:$(printf '%s\n' "$porcelain" | grep -c '^??')"; fi
-
-	branch=$(git -C "$wt" symbolic-ref --quiet --short HEAD 2>/dev/null || echo "")
-	if [ -z "$branch" ]; then remote=detached
-	elif git -C "$wt" show-ref --verify --quiet "refs/remotes/origin/$branch"; then
-		[ "$(git -C "$wt" rev-parse "origin/$branch" 2>/dev/null)" = "$head" ] \
-			&& remote=pushed \
-			|| remote="ahead$(git -C "$wt" rev-list --count "origin/$branch..HEAD" 2>/dev/null)"
-	else remote=no-remote; fi
-
-	pr=$([ -n "$branch" ] && jq -r --arg b "$branch" \
-		'.[] | select(.head==$b) | "#\(.number)/\(.state)"' "$prs" 2>/dev/null | head -1)
-	[ -z "$pr" ] && pr="-"
-
-	# Most recent chat whose transcript operated in this worktree. Match path
-	# followed by "/" or a quote so glint-482 does not match glint-482-r37.
-	last="-"; last_ts=0
-	if [ -d "$transcripts" ]; then
-		f=$(rg -l -e "${wt}/" -e "${wt}\"" "$transcripts" 2>/dev/null \
-			| xargs stat -c '%Y %n' 2>/dev/null | sort -rn | head -1)
-		if [ -n "$f" ]; then last_ts=$(echo "$f" | awk '{print $1}')
-			last=$(date -r "$last_ts" '+%Y-%m-%d' 2>/dev/null); fi
-	fi
-	recent=$([ "$last_ts" -gt 0 ] 2>/dev/null && [ $(( (now - last_ts) / 86400 )) -le 4 ] && echo yes || echo no)
-
-	case "$dirty" in wip:*) bucket=hold-wip ;; *)
-		case "$pr" in */open|*/draft) bucket=hold-open-pr ;; *)
-			if [ "$recent" = yes ]; then bucket=verify-recent-chat
-			elif [ "$merged" = YES ] || [ "$pr" != "-" ]; then bucket=safe
-			else bucket=review; fi ;;
-		esac ;;
-	esac
-
-	printf "%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n" \
-		"$size" "$age" "$merged" "$dirty" "$remote" "$pr" "$last" "$bucket" "$wt"
-done | sort -t$'\t' -k1,1 -rh
-
-rm -f "$prs"

package/assets/skills/show-me-your-work/scripts/log.sh

@@ -1,42 +0,0 @@
-#!/usr/bin/env bash
-# Append a well-formed row to a show-me-your-work decision log (TSV).
-# Usage: log.sh <logfile> <phase> <decision> <why> <evidence> <result>
-set -euo pipefail
-
-if [ "$#" -ne 6 ]; then
-	printf 'usage: log.sh <logfile> <phase> <decision> <why> <evidence> <result>\n' >&2
-	exit 1
-fi
-
-logfile="$1"
-shift
-
-logdir="$(dirname "$logfile")"
-if [ -n "$logdir" ] && [ "$logdir" != "." ] && [ ! -d "$logdir" ]; then
-	mkdir -p "$logdir"
-fi
-
-# Use `>>` here, never `>`. A network mount can fail this test for a log
-# that exists. Then the cost is one stray header line, not the rows.
-if [ ! -s "$logfile" ]; then
-	printf 'ts\tphase\tdecision\twhy\tevidence\tresult\n' >> "$logfile"
-fi
-
-ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-# Strip tabs/newlines/CR so cells stay on one line, and prefix any cell
-# whose first char a spreadsheet would parse as a formula (=, +, -, @)
-# with a single quote. The skill expects this log to be read in
-# spreadsheets, so attacker-controlled evidence (PR titles, filenames,
-# generated text) must not become formula execution when a reviewer
-# opens the file.
-clean() {
-	local v
-	v=$(printf '%s' "$1" | tr '\t\n\r' '   ')
-	case "$v" in
-		=*|+*|-*|@*) printf "'%s" "$v" ;;
-		*) printf '%s' "$v" ;;
-	esac
-}
-printf '%s\t%s\t%s\t%s\t%s\t%s\n' \
-	"$ts" "$(clean "$1")" "$(clean "$2")" "$(clean "$3")" "$(clean "$4")" "$(clean "$5")" \
-	>> "$logfile"

package/dist/LICENSE

@@ -1,22 +0,0 @@
-MIT License
-
-Copyright (c) 2026 dsh-pstack contributors
-Copyright (c) 2025 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/dist/README.md

@@ -1,159 +0,0 @@
-# dsh-pstack
-
-pstack for DeepSeek Harness. Rigorous agent workflows ported from
-[`cursor/plugins/pstack`](https://github.com/cursor/plugins/tree/main/pstack).
-
-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.
-
-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`.
-
-## Install
-
-```bash
-dsh plugin --profile web add github:your-org/dsh-pstack
-```
-
-Or from a checkout:
-
-```bash
-git submodule update --init --depth 1
-dsh plugin --profile web add .
-```
-
-Restart `dsh web` after install. The bundle patch mounts two rows:
-
-- `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:
-
-```bash
-dsh --profile web --dump-config | grep -A2 'pstack'
-```
-
-## Use
-
-Start with a real task:
-
-```text
-/poteto-mode add a --json flag to this command. text output stays byte-identical. verify both.
-```
-
-`/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.
-
-See the converted [pstack guide](assets/docs/guide/README.md) and the
-[DSH adapter reference](assets/docs/harness/dsh.md).
-
-### Configure roles
-
-`/setup-pstack` detects the routes your session can use and writes
-`~/.dsh/pstack-models.md`. One role per line:
-
-```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
-```
-
-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.
-
-### Delegate
-
-`pstack_subagent` is the one delegation surface:
-
-```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",
-)
-```
-
-- `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.
-
-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.
-
-## 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/`.
-
-## Develop
-
-Requirements: Node 22.19+ and pnpm. Vite+ provides the build, test, lint, and
-format toolchain.
-
-```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/
-```
-
-### 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
-```
-
-`assets/` is generated. Never hand-edit it. Change `scripts/adapt.ts` or a
-skill's upstream source, then run `vp run sync`.
-
-[`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.
-
-`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. The ported skills are MIT, copyright Lauren Tan; see [LICENSE](LICENSE).

package/dist/assets/agents/comment-sicko.md

@@ -1,32 +0,0 @@
----
-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/dist/assets/agents/poteto-agent.md

@@ -1,8 +0,0 @@
----
-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."
----
-
-# 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.

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

@@ -1,64 +0,0 @@
-# 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 your DSH profile:
-
-```bash
-dsh plugin --profile web add github:your-org/dsh-pstack
-```
-
-Restart `dsh web` after install. The bundle mounts the pstack skill provider and the `pstack_subagent` tool.
-
-## 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/pstack-models.md`, a small rule 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.
-
-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.
-
-`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.
-
-## 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, start a new chat. The model rule applies to new sessions.
-
-## 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. DSH has no persistent custom mode. Start each new task with `/poteto-mode`, and its instructions apply to that turn.
-
-Next: [Route work through `/poteto-mode`](./02-poteto-mode.md).

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

@@ -1,139 +0,0 @@
-# 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` 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.
-
-## 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 machine
-
-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.
-
-When the work has to stay local, 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).