pstack-claude-mirror 0.0.0-stage → 0.9.133

package/plugins/pstack/skills/poteto-mode/references/merge-safety.md

@@ -0,0 +1,43 @@
+# Merge and restack safety
+
+Use this reference with [Shipping](../playbooks/shipping.md) and before topology changes in [Autopilot-stack](../playbooks/autopilot-stack.md). Keep the existing watcher responsible for CI and blocker classification. These operations add revision and destination checks; they do not grant merge authority.
+
+## Read both pending mechanisms
+
+Use `ship-pr` under the installed plugin's `skills/poteto-mode/scripts/watch-pr/` directory. It owns GitHub transport, parsing, cancellation order, and readback. The watcher and this command share one `LandingRevision` containing the repository, PR number, head OID, base branch, and base OID.
+
+```sh
+ship-pr inspect --repo "$owner/$repo" --pr "$pr" > "$record_file"
+ship-pr cancel-pending --record "$record_file"
+```
+
+Run the installed command by its full path when it is not on PATH. Inspect emits `kind: inspected` with a parsed landing record, including both pending mechanisms and the merge commit when present. Save that record with the verification evidence. Cancellation accepts the saved record, rereads current state, disables auto-merge when present, rereads queue membership, dequeues when needed, and verifies both mechanisms are absent on the same open landing revision. It does not merge, push, retarget, or grant landing authority.
+
+Only exit 0 with `kind: cancelled` permits the planned topology operation. `changed`, `not-open`, and `still-pending` return exit 1 with the observed record. `unavailable` returns exit 1 with the read or mutation failure. Missing fields and unsupported APIs never mean an absent request. Reconcile those outcomes before rewriting; do not replace the saved record merely to bypass a mismatch.
+
+Establish the affected dependency chain and coordinate with the owner of each branch the operation rewrites first. Inspect and cancel each affected PR, including descendants whose context will change; leave unrelated PRs alone. Cancellation is an observed condition, not a lock against another actor rearming afterward. If state changes, stop and reconcile. Origin must supply an equivalent validated operation through its installed service; this command is GitHub-specific and must not be presented as Origin support.
+
+## Preserve concurrent writes and child changes
+
+Capture the remote branch SHA before rewriting with `git ls-remote --exit-code origin "refs/heads/$branch"`, and validate that exactly the intended ref was returned. Keep that SHA in the operation record. An implicit lease or a prior read alone is insufficient; a background fetch can move a tracking ref.
+
+After confirming the parent squash landed in the intended destination, fetch trunk and identify the recorded old parent tip on which this child was built. Verify it is an ancestor of the child and inspect `old-parent..child` to confirm the range contains only child work. If it does not, reconstruct the boundary before proceeding. Never infer it from the parent's new squash commit.
+
+```sh
+git merge-base --is-ancestor "$old_parent_tip" "$child"
+git rebase --onto "$trunk_tip" "$old_parent_tip" "$child"
+git push --force-with-lease="refs/heads/$child:$captured_remote_head" \
+  origin "HEAD:refs/heads/$child"
+```
+
+Run the rebase in the child's clean worktree, where `HEAD` is the prepared child. This excludes the parent's old commits. Inspect the resulting diff and content, reassess review applicability, and run checks at the new head. If the lease refuses the push, fetch and reconcile the concurrent work; do not refresh the lease and retry the overwrite blindly. Retarget only after cancellation has been verified. Keep the recorded boundary for each remaining child when preparing later levels.
+
+## What the service guards
+
+GitHub's immediate merge head condition is `--match-head-commit` in `gh`, `expectedHeadOid` in GraphQL `mergePullRequest`, or `sha` in the REST merge endpoint. Use one, carrying the exact verified SHA. None of these supplies an expected base-branch condition. Observe the base immediately before and after and coordinate retargeting; do not call those observations atomic.
+
+A queue or automatic request may outlive its admission revision. Use it only when existing repository rules enforce the required verification for the eventual revision and merge context. A prose verdict or a green check on an older head is not such a gate. If those guarantees cannot be established, keep watching for an immediate guarded merge. If the repository requires a queue, stop at that unmet gate rather than bypassing protection.
+
+After a merge, confirm state `MERGED`, the approved final head, the intended base, and a non-null merge commit. Fetch the destination and run `git merge-base --is-ancestor "$merge_commit" "$destination_tip"`; then check resulting content before advancing. If the service cannot report the relevant facts, the outcome remains unconfirmed.
+
+Service references: [GitHub CLI merge flags](https://cli.github.com/manual/gh_pr_merge), [GraphQL pull requests and queue mutations](https://docs.github.com/en/graphql/reference/pulls), and [REST merge endpoint](https://docs.github.com/en/rest/pulls/pulls#merge-a-pull-request). Recheck installed service capabilities when these differ. Test service behavior in a disposable repository, never with production PRs.

package/plugins/pstack/skills/poteto-mode/references/minimax-tools.md

@@ -0,0 +1,93 @@
+# MiniMax Code tool mapping for pstack
+
+MiniMax Code loads the pstack Claude Code plugin through its Claude Code reader: the skills, the four plugin agents, and the `SessionStart` hook. The model sees MiniMax Code's own tools, so resolve each Claude tool a skill names here.
+
+## Tool actions
+
+| pstack / Claude action | MiniMax Code equivalent |
+|------------------------|-------------------------|
+| Read a file | `read` |
+| Create a file | `write` |
+| Edit a file | `edit` |
+| Run a shell command | `bash` |
+| Search file contents / find files | `grep` (ripgrep syntax) and `glob` |
+| Fetch a URL | `web_fetch` |
+| Search the web | `web_search` |
+| Invoke a skill (the `Skill` tool, `/command`) | `skill` with `name` set to the plugin skill, as in `pstack:poteto-mode` |
+| Dispatch a subagent (the `Agent`/`Task` tool) | `task` with `description`, `prompt`, and `agent_name` |
+| Dispatch N parallel subagents in one turn | N `task` calls in one response |
+| Wait for a subagent result | End the turn. A `<background-task-finished>` notice wakes the session, and `task_output` with the `task_id` reads the result. |
+| Continue or steer a subagent (`SendMessage`) | `task_append` with the `task_id` |
+| Stop a subagent | `task_stop` with the `task_id` |
+| Track tasks (the todolist; `TaskCreate` / `TaskUpdate`, or `TodoWrite` on Claude Code) | `todowrite` with the whole `todos` list, one item `in_progress` |
+| Ask the human a fixed-choice question (`AskUserQuestion`) | `ask_user`, one step per question with two to four `options`. Set `async: false` when the next step depends on the answer. |
+| Schedule a self-paced re-invocation (`ScheduleWakeup`, the `loop` skill) | `self_reminder` with `action: "set"`, `delay_seconds`, and the `prompt` to run, which wakes this conversation once. Only one reminder can be pending, so set the next one after it fires. Use `cron_create`, an on-demand tool found with `tool_search` and run with `mcp_invoke`, only for a schedule the user asks for. |
+| Call an MCP tool (`mcp__<server>__<tool>`) | `tool_search` for the tool, then `mcp_invoke` with its `tool_name` and `arguments` |
+| Search Claude Code transcripts under `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects/` | This mapping names no MiniMax Code transcript location. Do not read Claude Code's projects directory, which holds Claude Code history, not this session's. Say that session history is unavailable instead of reporting that something was never recorded. |
+
+## Subagent policy
+
+poteto-mode's Subagents section sets Claude-specific defaults (`subagent_type: "pstack:poteto-agent"`, `run_in_background: true`). On MiniMax Code:
+
+- The plugin's four agents register under the plugin namespace: `pstack:poteto-agent`, `pstack:comment-sicko`, `pstack:thermo-nuclear-review-subagent`, and `pstack:thermo-nuclear-code-quality-review-subagent`. Pass the name a skill gives as `subagent_type` as the `task` tool's `agent_name`. `general-purpose` maps to the built-in `worker` agent.
+- `poteto-agent` cannot find the `poteto-mode` skill on its own, since it searches Claude Code's plugin cache. Put the absolute path of `poteto-mode`'s `SKILL.md` in every `pstack:poteto-agent` brief, as poteto-mode asks. A local install in the default data directory keeps it at `~/.minimax/plugins/pstack/skills/poteto-mode/SKILL.md`.
+- `task` runs in the background by default, so `run_in_background: true` needs no field. Leave it unset when you start several children at once.
+- `readonly: true` (reviewers, explorers, critics) has no field. Say in the prompt that the child must not change files, or dispatch the built-in `explore` agent, and review the diff anyway.
+- A role's model and effort go in the `task` tool's `model` and `effort` (see Model names).
+- `isolation: "worktree"` has no field: every child works in the session's workspace. Before you dispatch a writer, create its worktree with `git worktree add` and name that path in the prompt, so the **swarm** skill's workers and the fan-out playbooks (`orchestrate`, `autopilot-full`, `autopilot-stack`) never share a checkout.
+- Keep the rest of the policy unchanged. Pass file pointers not inlined context, and review every subagent's diff yourself.
+
+## Model names
+
+Skills name Claude Code model aliases in their Models sections. Those aliases are not MiniMax Code model keys. MiniMax Code names a model `<provider>/<model>`, and the models a session can reach depend on the providers the user connected: MiniMax itself, OpenAI through its Codex sign-in, or a provider added with `mcode provider add`. So the MiniMax Code build ships no default models, and the user picks them once.
+
+- The model sheet is `~/.minimax/pstack-models.md`. Before a skill that needs a role model (`architect`, `arena`, `how`, `interrogate`, `no-comments`, `poteto-mode`, `reflect`, `swarm`, `thermos`, `why`), read it. With no sheet, load `setup-pstack` with the `skill` tool and finish it first.
+- A role line in the sheet is the user's explicit model instruction, so pass it as the `task` tool's `model`. Pass the role's `@level`, or the sheet's `default effort`, as `effort`. The `task` tool fails a model other than the parent's that offers effort levels when `effort` is missing or names a level the model does not offer, such as `high` on MiniMax M3, which offers only `on` and `off`. When the level is not one the model offers, ask the user which to use. `inherit-parent` or `auto` omits `model` and `effort`.
+- Roles that default to the worker model (`feature, refactoring`): the worker model the user chose.
+- Roles that default to the strongest model (`strongest judgment`): the strongest model the user chose.
+- Diverse-model panels (`arena`, `architect`, `interrogate`): the adversarial signal comes from model diversity, so fill a panel from distinct providers. If only one model family is reachable, vary reasoning effort and note in the verdict that diversity was reduced.
+
+`/setup-pstack` writes the configured model list. On MiniMax Code, list the models with `mcode provider list` or the `model` slash command and write only keys they show.
+
+## Session routing hook
+
+MiniMax Code runs the Claude Code plugin's `SessionStart` hook through its Claude Code reader. The hook finds `MINIMAX_PLUGIN_ROOT` in its environment and injects the poteto-mode mandate in MiniMax Code wording, which points here. It reads `session hook` from the MiniMax Code sheet, at the path in [setup-pstack's runtime table](../../setup-pstack/references/runtimes.md); `session hook: off` disables injection. MiniMax Code passes hooks and the `bash` tool a fixed set of environment variables that leaves out `MINIMAX_DATA_DIR`, so pstack keeps the sheet at `~/.minimax/pstack-models.md` even when the data directory moves. The hook is a POSIX `sh` script, and it is untested on Windows.
+
+A skills-only installation does not include the hook. Request `poteto-mode` explicitly or add a standing instruction to `AGENTS.md` in that case.
+
+## Driver and bundled skills pstack references
+
+The [driver policy](../SKILL.md#non-negotiables) selects the app driver. For skills and drivers named by these workflows, use these MiniMax Code equivalents:
+
+| Skill or driver named in pstack | On MiniMax Code |
+|---------------------------------|-----------------|
+| `run` (drive a CLI/TUI to see a change work) | Run the app yourself via `bash` and observe the real output. |
+| Project UI driver | Drive the UI with whatever automation you have, or hand the user a concrete manual check. Do not claim done without observing the artifact. |
+| `plugin-dev:skill-development` (Claude's SKILL.md authoring guidance) | MiniMax Code's built-in `skill-creator` skill. Keep `name` plus `description` frontmatter and progressive disclosure. |
+| `loop` (recurring/self-paced re-invocation, used by `babysit`) | `self_reminder`, set again after each check (see Tool actions). |
+
+Project skills, the ones `create-verification-skill` writes under `.claude/skills/`, load from `.claude/skills/`, `.agents/skills/`, or `.minimax/skills/` in the workspace.
+
+## Per-skill notes
+
+Most skills need only the tables above. These need one more mapping:
+
+| Skill | On MiniMax Code |
+|-------|-----------------|
+| `setup-pstack` | The skill's [Other runtimes](../../setup-pstack/references/runtimes.md) table names the MiniMax Code sheet path. List models with `mcode provider list` or the `model` slash command. |
+| `no-comments` | The `comment-sicko` dispatch is a `task` call with `agent_name: "pstack:comment-sicko"`. |
+| `thermos` | Both review dispatches are `task` calls with the agents' `pstack:` names. |
+| `swarm` | Each worker is a `task` call. Give each writing worker its own worktree first (see Subagent policy). |
+| `why` | The parallel investigators and the synthesizer map to `task` fan-out. List MCP servers with `tool_search`, not from Claude Code's MCP files. |
+| `recall` | Do not list or read `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects/`; it holds Claude Code history, not this session's (see Tool actions). Work from live state and the shared record. |
+| `reflect` | The transcript finder reads Claude Code's layout and has no MiniMax Code location to read, so pass the session digest step 1 allows instead. |
+| `show-me-your-work` | Check the log against this session's own context, not a Claude Code transcript. |
+| `automate-me` | The skill-authoring guidance resolves through the skills table above. This mapping names no MiniMax Code transcript location, so draw on the current session and the user's own account of how they work. Write the mode skill under `.agents/skills/` or `.claude/skills/`. |
+
+## Vendored scripts
+
+`skills/poteto-mode/scripts/` ships the `watch-pr` PR watcher and `worktree-audit.mjs`. These scripts use bun and Node.js and run the same on MiniMax Code; invoke them through `bash`. They need `bun` and `gh`, or `origin` when the forge is Origin. Run `worktree-audit.mjs` with `node`, as its shebang does. The audit finds each worktree's last chat only in the transcript directories that exist (Claude Code, Codex, Pi, GitHub Copilot); it does not read MiniMax Code sessions. It imports the transcript walker from the `reflect` skill, so keep the `reflect` skill installed beside `poteto-mode`.
+
+## Instructions file
+
+Where a pstack skill says "your instructions file", on MiniMax Code that is `AGENTS.md` in the workspace, or `AGENTS.md` in MiniMax Code's data directory (`~/.minimax` by default) for every workspace. On Claude Code it is `CLAUDE.md`.

package/plugins/pstack/skills/poteto-mode/references/muse-tools.md

@@ -0,0 +1,105 @@
+# Muse tool mapping for pstack
+
+pstack skills are written in Claude Code tool language (the `Skill` tool, the `Agent` tool, `AskUserQuestion`, Claude model names). On Muse the skills are the same files, loaded from the pstack Muse plugin; only the tool names resolve differently. Read this when a pstack skill names a Claude tool, a driver or bundled skill, or a Claude model. This file is Muse-specific. Other runtimes must use their own concrete tools, model names, and configuration paths.
+
+## Tool actions
+
+| pstack / Claude action | Muse equivalent |
+|------------------------|---------------|
+| Read a file | `read_file` |
+| Create a file | `write_file` |
+| Edit a file | `edit_file` (one exact text replacement) |
+| Delete a file | `bash` (`rm`) |
+| Run a shell command | `bash` |
+| Search file contents / find files | `search`, otherwise `bash` (`rg`, `grep`, `find`, `ls`) |
+| Fetch a URL | `web_fetch` |
+| Search the web | `web_search` |
+| Invoke a skill (the `Skill` tool, `/command`) | `read_skill` with the plugin skill id (`plugin:pstack:poteto-mode`), then follow its body. Muse lists each user-invocable skill as `/<name>` itself. |
+| Dispatch a subagent (the `Agent`/`Task` tool) | `subagent_spawn` (one child agent with a role and objective), or a Workflow child when the step needs model control or many parallel workers |
+| Dispatch N parallel subagents in one turn | N `subagent_spawn` calls in one response, or one Workflow run fanning out over its items |
+| Wait for a subagent result | `subagent_wait`, or end the turn: finished results arrive on their own. `subagent_read_result` reads a finished result again. |
+| Continue or steer a subagent (`SendMessage`) | `subagent_send_message`, addressed by the subagent id the spawn returned |
+| Stop a subagent | `subagent_cancel`; `subagent_status` lists what is running |
+| Track tasks (the todolist; `TaskCreate` / `TaskUpdate`, or `TodoWrite` on Claude Code) | `write_todos` |
+| Ask the human a fixed-choice question (`AskUserQuestion`) | `request_user_input` with two or three options per question. When it is withheld for the run, ask in plain text. |
+| Schedule a self-paced re-invocation (`ScheduleWakeup`, the `loop` skill) | `cron_create` for a cadence, or `monitor` to watch a long-running source. There is no one-shot wake-up call. |
+| Read this workspace's session transcripts (Claude Code's projects directory) | Muse sessions live at `${XDG_DATA_HOME:-~/.local/share}/muse/sessions/YYYY/MM/DD/<session-id>/session.jsonl`. Read only the sessions for this workspace, never a glob across every project. |
+
+A skills-only setup (the skills without the plugin) still has every tool above, since they are Muse's own tools. It lacks the plugin's agent definitions and routing hook, so read the Subagent policy fallback there.
+
+## Subagent policy
+
+poteto-mode's Subagents section sets Claude-specific defaults (`subagent_type: "pstack:poteto-agent"`, `run_in_background: true`). On Muse:
+
+- The plugin's four agent files register as agent definitions with scoped ids: `pstack/poteto-agent`, `pstack/comment-sicko`, `pstack/thermo-nuclear-review-subagent`, and `pstack/thermo-nuclear-code-quality-review-subagent`. Pass the scoped id as `subagent_spawn`'s `subagent_type`, or as a Workflow child's `agentType`. Map a skill's `pstack:poteto-agent`, and each other `pstack:<name>` dispatch, to `pstack/<name>` unchanged otherwise. `general-purpose`, or no type, runs the built-in general agent. In a skills-only setup none of these definitions exist: route an ad-hoc subagent through poteto-mode's style by telling it to read the `poteto-mode` skill in full first, and a `comment-sicko` dispatch to read the `comment-sicko` reference under `poteto-mode/references/agents/` first.
+- `subagent_spawn` children already run alongside your turn, so `run_in_background: true` has no separate flag. Issue the dispatch and continue; the result arrives when the child finishes.
+- `readonly: true` (reviewers, explorers, critics) has no flag. Say in the objective that the child must not change files, and review its diff anyway.
+- A role value's `@<level>`, or the `default effort` line, passes as the dispatch's effort field: `effort` on a Workflow child. `subagent_spawn` has no effort field and keeps the session's effort, so name the level it needs in the objective when the job turns on it. `session` sets nothing.
+- `isolation: "worktree"` maps to `worktree_isolation` on `subagent_spawn`, or `isolation` on a Workflow child. Muse runs every subagent on this machine, so the **swarm** skill's workers and the fan-out playbooks (`orchestrate`, `autopilot-full`, `autopilot-stack`) isolate writers with worktrees, as on Claude Code.
+- A completion notice on Muse means the child finished; the Claude Code caveat about a `completed` agent that keeps running does not apply. Stop an agent you abandon with `subagent_cancel` and confirm it stopped before replacing it.
+- Keep the rest of the policy unchanged. Pass file pointers not inlined context, give each worker its own worktree or branch when they write, review every subagent's diff yourself.
+
+## Model names
+
+Skills name Claude defaults (a single-role default for code/prose/judgment, a worker model for feature and refactoring code, plus a diverse-model panel for diverse-model panels; each model-consuming skill lists its own in a Models section). These slugs do not resolve on Muse. Substitute your configured Muse models:
+
+- Single-model roles: your primary Muse model (for example `muse-wonder-1.0`).
+- Roles that default to the Claude worker model (`feature, refactoring`): your fast Muse model (for example `muse-spark-1.3`).
+- Roles that default to the strongest Claude model (`strongest judgment`): your strongest Muse model (for example `muse-wonder-full-1.0`).
+- Diverse-model panels (`arena`, `architect`, `interrogate`): the adversarial signal comes from model diversity, so use the distinct Muse models available to you. A good default panel is `muse-wonder-full-1.0`, `muse-wonder-1.0`, `muse-spark-1.3`. Muse serves one model family, so vary reasoning effort across the panel too and note in the verdict that diversity was reduced.
+
+Pass a role's model where the dispatch takes one: a Workflow child's `model`, or the session model when the dispatch has no model field. `subagent_spawn` takes an agent definition, not a model, so a role dispatched that way runs on the session's model and effort; a Workflow child takes both (see Subagent policy). `inherit-parent` or `auto` omits `model`.
+
+`/setup-pstack` writes the configured model list. On Muse, set it to your Muse model IDs, as `muse model-profile` and the model catalog name them.
+
+## Session routing hook
+
+The native pstack Muse plugin bundles a `SessionStart` hook that injects the poteto-mode mandate in Muse wording, plus the saved role lines from the Muse sheet when the sheet has any. The manifest declares it twice, as `session-start` for the shell script and `session-start-windows` for the PowerShell script, and each stands down on the OS the other owns. On a machine without `sh` or without `powershell.exe`, that hook records a failed spawn at session start and the other delivers the context. Muse runs plugin hooks only after the user approves them (`muse plugins approve pstack`), so a fresh install routes nothing until then. Both hooks read `session hook` from the Muse sheet, at the path in [setup-pstack's runtime table](../../setup-pstack/references/runtimes.md); `session hook: off` disables injection.
+
+A skills-only installation does not include the hook. Request `poteto-mode` explicitly or add a standing instruction to `AGENTS.md` in that case.
+
+## Driver and bundled skills pstack references
+
+The [driver policy](../SKILL.md#non-negotiables) selects the app driver. For skills and drivers named by these workflows, use these Muse equivalents:
+
+| Skill or driver named in pstack | On Muse |
+|---------------------------------|---------|
+| `run` (drive a CLI/TUI to see a change work) | Run the app yourself via `bash` and observe the real output. |
+| Project UI driver | Drive the UI with whatever automation you have, or hand the user a concrete manual check. Do not claim done without observing the artifact. |
+| `plugin-dev:skill-development` (Claude's SKILL.md authoring guidance) | Follow Muse's bundled skill-authoring guidance and the Agent Skills shape. Keep `name` plus `description` frontmatter and progressive disclosure. |
+| `loop` (recurring/self-paced re-invocation, used by `babysit`) | `cron_create` on a cadence, or `monitor` on the PR or job. Re-run the step yourself when neither fits. |
+
+## Per-skill notes
+
+Affected skill entry points point here. Most skills need only the tables above. These need one more mapping:
+
+| Skill | On Muse |
+|-------|---------|
+| `interrogate` | The reviewer dispatch maps to parallel `subagent_spawn` calls or Workflow children; use Workflow children when the panel needs distinct models, and keep the panel model-diverse (see Model names). |
+| `setup-pstack` | The skill's [Other runtimes](../../setup-pstack/references/runtimes.md) table names the Muse sheet path; the plugin hook injects its role lines, so no include line is needed. The role rows are identical. |
+| `no-comments` | The `comment-sicko` dispatch resolves through `subagent_spawn` as written, with the scoped id (see Subagent policy). Run it without worktree isolation, so it sees the scope's uncommitted changes. |
+| `thermos` | Both review dispatches resolve through `subagent_spawn` with their scoped ids (see Subagent policy). |
+| `teach` | Running `how` and `why` in parallel maps to two `subagent_spawn` calls in one response. Draw with Mermaid or plain text when no image tool is available. |
+| `create-verification-skill` | Write the generated skill where Muse discovers project skills, `.agents/skills/verify/`, instead of under `.claude/skills/`. The app-driving harness is platform-neutral. |
+| `maintain-verification-skill` | The parallel per-feature source readers map to `subagent_spawn` fan-out; the project-local skill lives under `.agents/skills/`. |
+| `create-formal-verification-skill` | Write the generated skill to `.agents/skills/<area>/`, named for the area it verifies. The verifier and its run command are platform-neutral. |
+| `maintain-formal-verification-skill` | Project skills, the formal verification skill among them, live under `.agents/skills/`. |
+| `babysit` | `loop` and `AskUserQuestion` resolve through the tables above. |
+| `automate-me` | The skill-authoring guidance resolves through the skills table above. The workspace's transcripts are its Muse sessions (see Tool actions), and the mode skill lands in the Muse user skills directory or `.agents/skills/`. |
+| `architect` | The runner panel goes through the **arena** skill, so its fan-out and model substitution apply here too. |
+| `arena` | The parallel candidates and the cross-judge are Workflow children or `subagent_spawn` calls on the configured Muse models (see Model names). |
+| `how` | The parallel explorers and the explainer map to `subagent_spawn` fan-out; substitute your configured Muse models. |
+| `reflect` | The three reviewers and the synthesizer map to `subagent_spawn` fan-out. The transcript finder reads Claude Code's layout, so pass the session digest step 1 allows instead. |
+| `swarm` | Each worker is a `subagent_spawn` call or a Workflow child; give each writing worker worktree isolation or its own output directory (see Subagent policy). |
+| `why` | The parallel investigators and the synthesizer map to `subagent_spawn` fan-out; substitute your configured Muse models. List MCP servers from the tools Muse exposes to the session, not from Claude Code's MCP files. |
+| `typescript-best-practices` | Its frontmatter `paths` scoping is Claude Code metadata on Muse; invoke it by name for TypeScript work. |
+| `recall` | Search this workspace's Muse sessions (see Tool actions), not Claude Code's projects directory. |
+| `show-me-your-work` | Check the log against this run's Muse session file (see Tool actions), not a Claude Code transcript. |
+
+## Vendored scripts
+
+`skills/poteto-mode/scripts/` ships the `watch-pr` PR watcher and `worktree-audit.mjs`. These scripts use bun and Node.js and run the same on Muse; invoke them through `bash`. They need `bun` and `gh`, or `origin` when the forge is Origin. Run `worktree-audit.mjs` with `node`, as its shebang does. The audit finds each worktree's last chat only in the transcript directories that exist (Claude Code, Codex, Pi); it does not scan Muse sessions, so pass a Muse sessions directory explicitly when a worktree's last chat was a Muse one. It imports the transcript walker from the `reflect` skill, so keep the `reflect` skill installed beside `poteto-mode`.
+
+## Instructions file
+
+Where a pstack skill says "your instructions file", on Muse that is `AGENTS.md`, which Muse reads from the workspace (and which `muse init` scaffolds). On Claude Code it is `CLAUDE.md`.

package/plugins/pstack/skills/poteto-mode/references/omp-tools.md

@@ -0,0 +1,39 @@
+# OMP tool mapping for pstack
+
+OMP loads these skills from the installed pstack marketplace plugin. Skill names are unqualified unless a collision changes their namespace. For a pstack skill named by the routing instruction, read its file under the installed plugin path supplied by that instruction. This avoids resolving a same-named skill from another source. For interactive invocation, use the name shown by OMP; Claude Code's `pstack:` prefix is not an OMP skill name.
+
+| Claude Code action | OMP action |
+| --- | --- |
+| Read (`Read`), write (`Write`), edit (`Edit`), search (`Grep` / `Glob`), shell (`Bash`) | `read`, `write`, `edit`, `grep`, `glob`, `bash` |
+| Invoke the `Skill` tool | Read `skills/<name>/SKILL.md` in the installed plugin path supplied by the routing instruction |
+| Dispatch the `Agent` tool (`subagent_type`, `general-purpose`, `pstack:poteto-agent`) | Use `task` and its advertised agent roster; include the poteto-mode instructions in the brief |
+| Background dispatch (`run_in_background`) | Follow the active `task` schema; use `wait` for its result |
+| Read-only child (`readonly`) | Select an available read-only agent, or explicitly prohibit writes in its brief |
+| Isolated writer (`isolation: "worktree"`) | Use the active `task` schema or create separate worktrees before parallel writes |
+| Ask (`AskUserQuestion`) | `ask` |
+| Tasks (`TodoWrite` / `TaskCreate` / `TaskUpdate`) | `todo` |
+| Web (`WebSearch`) | `web_search` when available |
+| `plugin-dev:skill-development` | Use it only if available; otherwise report the missing authoring companion |
+| `CLAUDE.md` / `.claude/skills` | Follow OMP's discovered context files and skill catalog; do not install pstack skills into a standalone directory |
+| `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects` transcripts | Use OMP session history and the paths or internal URLs exposed by the active session |
+| `loop` | Use OMP's interactive `/loop` when available |
+
+OMP provides its own subagent roster and model selection. Use the agents and model options listed by the active `task` tool. Map a review panel to separate task items. Do not pass Claude-specific `subagent_type` or model aliases. Follow the active OMP tool schema for effort. A task result is evidence; inspect the actual artifact before reporting it as complete.
+
+OMP's `/loop` is an interactive session command, not a subagent tool. For a recurring interactive workflow, provide the user with the appropriate `/loop` command rather than emulating it with a sleep loop. If the current host does not expose it, follow that host's available scheduling mechanism or report the limitation.
+
+The plugin injects its routing instruction before each main-agent turn and this mapping pointer into main and subagent turns. Restart a session after changing `session hook` to clear previously injected context. The Pi extension and its agent tools are not loaded by the OMP marketplace plugin.
+
+OMP's marketplace skill discovery does not apply pstack's `paths` frontmatter as a file-triggered invocation rule. Invoke `typescript-best-practices` explicitly for TypeScript work when applicable.
+
+Use the OMP session's available browser or project verification tools to drive applications. Project instructions take precedence over generic driver guidance.
+
+## Model names
+
+OMP uses its own model selection; without a pstack sheet, use the runtime's defaults. The global `~/.omp/pstack-models.md` is shared across OMP profiles; `session hook: off` there disables main-session routing while retaining the subagent mapping. Configure models only when the user asks. List available chat models with `omp models --kind chat` and inspect the active OMP configuration with `omp config`. Ask which available models the user wants for routine, worker and demanding roles. Configure OMP's own `modelRoles` and `task.agentModelOverrides` through its configuration interface, preserving unrelated settings. Use only models listed by the active installation; do not copy Claude model aliases into OMP. If the available agent roster cannot select distinct models for a requested panel, report that limitation.
+
+## Per-skill notes
+
+| Skill | On OMP |
+| --- | --- |
+| `why` | Use OMP tools and available sources. |

package/plugins/pstack/skills/poteto-mode/references/opencode-tools.md

@@ -0,0 +1,29 @@
+# OpenCode mapping
+
+OpenCode 2 loads the native pstack plugin, which registers each skill as `pstack-<name>`. Invoke `pstack:how` as `pstack-how` with the `skill` tool, and resolve relative references from the skill's base directory. Map `Read` to `read`, `Bash` to `shell`, and the `Skill` tool to `skill`.
+
+## Claude action mapping
+
+- For the `Agent` tool, use `subagent` with its available `agent`, `description`, and `prompt` fields. A Claude `subagent_type` names a role, not an OpenCode agent ID. The plugin does not register `pstack:poteto-agent`; choose only an available agent and put the absolute path to `poteto-mode/SKILL.md` in its brief. Do not assume `general-purpose` exists.
+- Map `run_in_background: true` to the `subagent` tool's `background: true`. Use its returned `sessionID` to continue the same child. A Claude `readonly: true` flag has no direct equivalent; use an available read-only agent or permissions, and do not claim read-only isolation otherwise. `isolation: "worktree"` likewise requires a separately created worktree.
+- Map `AskUserQuestion` to the available `question` tool. Map `TaskCreate`, `TaskUpdate`, and `TodoWrite` to `todowrite` with the complete todo list, or use a local checklist if the tool is unavailable.
+- The `loop` skill's wake-up mechanism is runtime-specific. Use `schedule_create` only when the user authorizes a schedule; do not silently substitute a recurring schedule for a single wake-up.
+- `plugin-dev:skill-development` is a Claude plugin skill, not an OpenCode built-in. Use it only if available. Likewise, `.claude/skills/` and `CLAUDE.md` are Claude-specific paths, not proof that OpenCode loaded an instruction or skill.
+- `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects/` holds Claude transcripts, not this OpenCode session's history. Use an available OpenCode history source or say the history is unavailable.
+
+## Per-skill notes
+
+| Skill | On OpenCode 2 |
+| --- | --- |
+| `setup-pstack` | Use the configured models listed by OpenCode and the model names guidance below. |
+| `why` | Use connected sources where available and report missing evidence instead of assuming it. |
+
+## Model names
+
+Claude Code model aliases are not OpenCode model IDs. Select a configured chat model only when the user explicitly asks for a model or variant; otherwise let the subagent inherit its model. OpenCode accepts `providerID/modelID` or `providerID/modelID#variant` in the `subagent` tool's `model` field. Look up the ID and variant with the `models` tool; do not guess.
+
+- The model sheet is `${XDG_CONFIG_HOME:-~/.config}/opencode/pstack-models.md`. Add that path to the OpenCode configuration's `instructions` array to load role choices; the plugin reads the `session hook` setting directly.
+- For role-model skills (`architect`, `arena`, `how`, `interrogate`, `no-comments`, `poteto-mode`, `reflect`, `swarm`, `thermos`, `why`), treat a saved user choice as an explicit instruction only when it identifies a configured model. The `subagent` input has no separate effort field; use a listed `#variant` when requested. Omit `model` for `inherit-parent` or `auto`.
+- For diverse-model panels, use different available providers only when the user requests those models. Otherwise inherit and state that model diversity was not established.
+
+Use the `models` command to inspect configured models before writing the sheet.

package/plugins/pstack/skills/poteto-mode/references/pi-tools.md

@@ -0,0 +1,117 @@
+# Pi tool mapping for pstack
+
+pstack skills are written in Claude Code tool language (the `Skill` tool, the `Agent` tool, `AskUserQuestion`, Claude model names). On Pi the skills are the same files, loaded from the pstack package, and the package's Pi extension registers tools named after the Claude ones, so most names map one to one. Read this when a pstack skill names a Claude tool, a driver or bundled skill, or a Claude model. This file is Pi-specific.
+
+## Tool actions
+
+| pstack / Claude action | Pi equivalent |
+|------------------------|---------------|
+| Read a file | `read` |
+| Create a file | `write` |
+| Edit a file | `edit` (exact text replacement) |
+| Delete a file | `bash` (`rm`) |
+| Run a shell command | `bash` |
+| Search file contents / find files | `grep`, `find`, and `ls` when enabled, otherwise `bash` (`rg`, `grep`, `find`, `ls`). Pi enables only `read`, `bash`, `edit`, and `write` by default. |
+| Fetch a URL | `bash` with `curl` / `wget` |
+| Search the web | Pi has no web search tool. Use an MCP server that provides one. |
+| Invoke a skill (the `Skill` tool, `/command`) | Skills load natively. The model reads a skill when its description matches; `/skill:<name>` forces one. |
+| Dispatch a subagent (the `Agent`/`Task` tool) | `agent` |
+| Dispatch N parallel subagents in one turn | N `agent` calls with `run_in_background: true` in one response |
+| Wait for a subagent result | A foreground `agent` call returns the final text. A background agent's completion arrives as a message naming its id, status, and final text, after your current tool calls or as a new turn when you are idle, so do not poll. |
+| Continue or steer a subagent (`SendMessage`) | `send_message`, addressed by agent id or description |
+| List subagents | `list_agents`. Its `sessionFile` field is the agent's transcript, written once the first message is in. To let the user watch a running agent, give them `tail -f <sessionFile>`; for a finished one, `pi --export <sessionFile>` renders it as HTML. A running agent's `activity` field gives its current or last tool call and latest message. The user can run `/pstack-agents` for the same view. |
+| Stop a subagent | `stop_agent` |
+| Track tasks (the todolist; `TaskCreate` / `TaskUpdate`, or `TodoWrite` on Claude Code) | Pi has no task-tracking tool. Keep the `todo.md` checklist poteto-mode describes for that case. |
+| Ask the human a fixed-choice question (`AskUserQuestion`) | `ask_user_question`, same shape. Without an interactive UI (print or JSON mode), and in a child agent, it returns an error, so ask in plain text. When the Pi override sheet has `pi ask tool: off`, another extension provides `ask_user_question` and its behavior is that extension's; if the session declares no such tool, ask in plain text. |
+| Schedule a self-paced re-invocation (`ScheduleWakeup`) | `schedule_wakeup`, same shape. A due wakeup stays pending until the session is idle, including during manual compaction. `noop: true` only labels the wakeup, which is still scheduled, and `stop: true` cancels the pending wakeup and needs no other field. The prompt arrives as a `pstack-wakeup` custom message, not a user message, so a permission check does not read it as the user's request. A `/skill:` or prompt-template prompt arrives expanded, as Pi expands one the user types. A `/loop` prompt runs the loop, and what the loop sends also arrives as custom messages. Any other command, an extension's included, arrives as plain text and does not run. In print and JSON mode, and in a child agent, scheduling returns an error, because Pi exits when the run ends and the wakeup could never fire. After a `/loop` command ends or replaces the loop during a run, that run is refused every wakeup until it settles, whatever the prompt, and Pi tells the user. No other wakeup is refused. |
+| Read this workspace's session transcripts (Claude Code's `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects/<encoded-cwd>/`) | Pi sessions live in `~/.pi/agent/sessions/--<cwd>--/` (under `$PI_CODING_AGENT_DIR` when set), where `<cwd>` is the working directory without its leading `/` and with each `/` as `-`. Subagent sessions the extension started live in `<agent dir>/pstack/<parent session id>/agents/`. Each file opens with a `session` header line; every later line is an entry with an `id` and a `parentId`, and a message entry is `type: "message"` with `message.role` `user`, `assistant`, or `toolResult`. A session keeps abandoned branches in the same file, so follow `parentId` back from the last entry for the conversation that happened. The same privacy rule applies: read only this workspace's directory, never a glob across `sessions/`. |
+
+`agent`, `send_message`, `list_agents`, `stop_agent`, `ask_user_question`, and `schedule_wakeup` come from the pstack Pi extension, which `pi install` of the pstack package loads. A skills-only setup has none of them, and the fan-out skills (`interrogate`, `why`, `how`, `arena`, `reflect`) degrade to a single sequential pass. A required independent review does not degrade. It stays blocked, as poteto-mode's [Subagents](../SKILL.md#subagents) section says.
+
+## Subagent policy
+
+poteto-mode's Subagents section applies on Pi through the `agent` tool:
+
+- `subagent_type` takes the same values. `pstack:poteto-agent`, `pstack:comment-sicko`, `pstack:thermo-nuclear-review-subagent`, and `pstack:thermo-nuclear-code-quality-review-subagent` resolve to the plugin's agent files. A `.md` file in `pstack-agents` in the Pi agent directory adds a type under its file name with no `pstack:` prefix, as a Claude Code user agent has no plugin prefix, and the body after the frontmatter is the child's system prompt. Its `tools:`, `disallowedTools:`, and `isolation:` fields are ignored, so pass `readonly: true` or `isolation: "worktree"` on the `agent` call instead. A hidden file, a file whose name has a colon, and one that cannot be read are skipped. The extension reads the frontmatter as YAML, and a repeated key keeps its last value, as in Claude Code. When the YAML does not parse, it retries as Claude Code 2.1.310 does, reading an unquoted top-level value that holds YAML syntax, such as `description: Use for a: b`, as text and turning leading tabs into spaces. It skips a user file whose frontmatter still does not parse. A user file never replaces a type, so `poteto-agent.md` there adds `poteto-agent` and leaves `pstack:poteto-agent` alone. The extension does not read Pi's `agents` folder, whose files other subagent extensions write with their own frontmatter. `general-purpose`, or no `subagent_type`, runs a child with no agent file. Claude Code's built-in types such as `Explore` and `Plan` do not exist on Pi, so use `general-purpose` and put the constraint in the prompt. An unknown type errors and lists the valid ones. The `agent` tool's `subagent_type` description lists each type the session starts with and what it is for, from each agent file's `description:`, the user's files included.
+- `readonly: true`, which the `how` panel sets, runs the child without the `edit` and `write` tools. It keeps `bash`, so a reviewer can still run `git diff`; say in the prompt that it must not change files.
+- Each child is its own `pi --mode rpc` process in your working directory, and the extension sends it the prompt on its stdin. It loads the packages and settings saved on disk, so it sees the pstack skills when pstack was installed with `pi install`. It does not inherit the parent's command-line flags, such as `-e`, `--api-key`, or a one-off `-a` project trust, so a pstack loaded only through `-e` gives children no extension.
+- A child can start its own agents, down to three layers below the main session, as on Claude Code. A child at the third layer runs without the `agent` tool.
+- `isolation: "worktree"` runs the child in its own git worktree under `.claude/worktrees/`. A worktree the agent left nothing in is removed when the agent finishes; a change, a gitignored file it wrote, or a commit on its branch or on any commit its HEAD visited keeps it.
+- `run_in_background: true` returns the agent id at once. The completion joins the conversation after your current tool calls finish, as on Claude Code, or starts a turn when you are idle. In print and JSON mode (`pi -p`), where Pi exits once the run settles, the extension holds the settle while a background agent runs, so each completion still arrives as a turn and the process ends after the last one. A child agent holds its settle the same way while its own background agents run, because its parent closes its stdin once it settles, and a message from the parent ends the hold. Interactive and RPC main sessions settle as usual and take the completion when it arrives.
+- While a background agent runs, the extension blocks a `bash` command line in which the word `sleep` is followed by a literal duration of two seconds or more, anywhere in the line, poll loops included: `sleep 30`, `npm test; sleep 30`, `until gh pr checks 1; do sleep 30; done`, `sleep infinity`. A shorter sleep, a sleep backgrounded as `sleep 30 &`, and `sleep` inside a quoted string, a comment, or a heredoc all run. The rule errs toward blocking, so `timeout 5 sleep 30` and a sleep inside a backgrounded group are blocked too. The completion notice arrives on its own, so continue other work or end your turn.
+- An agent's status follows its process. `completed` means the child exited, and `stop_agent` reports `stopped` only once the child has exited, so the Claude Code caveat about a `completed` agent that keeps running does not apply to the agent itself. Stopping an agent, like the session shutdown that stops every agent, ends the child pi and the `bash` command it still has running, because Pi kills that command's process tree on SIGTERM. A process that a finished `bash` command left in the background (`cmd &`, `nohup cmd`) runs in its own process group and outlives the agent; stop it yourself. A stopped agent's notice joins the conversation without starting a turn, since `stop_agent` already returned.
+- Agents belong to the session that started them. Quitting, reloading, and starting, resuming, or forking a session all stop every running agent, and a parent process that exits signals its agents to stop. On restore, an agent still running under its launching Pi process is left alone. An orphan whose process identity matches the saved record is signalled to stop, and remains unavailable to `send_message` and `stop_agent` until its process exits. Without enough identity data to signal it safely, its process is left alone and continuation is refused until its exit is confirmed. Only then is the restored agent marked `stopped` and allowed to resume.
+- Each child's environment names the session that started it in `PI_SUBAGENT_PARENT_SESSION`, the variable `@gotgenes/pi-permission-system` reads to forward a child's permission ask to that session. Install that package globally so children load it too. As of its 42.0.0, the starting session then shows the ask at its own prompt while it has a UI, which `pi -p` does not. The ask names the child's `subagent_type`, which the package reads from an `<active_agent>` tag the extension adds to each child's system prompt. The package also applies the `permission:` frontmatter of an agent file with that name in Pi's `agents` folder or the project's `.pi/agents`; it does not read `pstack-agents`. A permission dialog the child opens itself reaches the pstack extension, which cancels every child dialog, so that call is denied as if the user had refused.
+- `send_message` to a running agent is an RPC `steer` on the child's stdin. The agent reads it after its current tool calls, as on Claude Code, carries on in the same run, and sends one completion notice. A message the child rejects returns an error, and the agent keeps running. A message to a finished agent resumes its session in the background with the context of its earlier runs. A message that arrives after the agent settled but before its process exited resumes the agent once the process has exited.
+- A role value's `@<level>`, or the sheet's `default effort` level, is passed as the `agent` tool's `effort`, which the extension passes to the child as `--thinking`. `session` omits it, so the child runs at its agent file's `effort`, else at the parent's current thinking level.
+- An agent file's `model:` and `effort:` frontmatter are defaults for a call that omits them, as on Claude Code, so the `agent` call's `model` and `effort` win. Claude Code's `model: inherit` runs the agent on the parent's model. The plugin's agent files set neither.
+- Keep the rest of the policy unchanged. Pass file pointers not inlined context, give each worker its own worktree when they write, review every subagent's diff yourself.
+
+## Model names
+
+Skills name models by the Claude aliases in their Models sections. On Pi, pass the alias as the `agent` tool's `model`. The pstack extension resolves it in the column of the provider the session's current model comes from, and in the `anthropic` column for any other provider:
+
+| Alias | `anthropic` | `openai` | `openai-codex` |
+| --- | --- | --- | --- |
+| `opus` | `anthropic/claude-opus-5-5` | `openai/gpt-6.1-sol` | `openai-codex/gpt-6.1-sol` |
+| `fable` | `anthropic/claude-fable-5-1` | `openai/gpt-6-astra` | `openai-codex/gpt-6-astra` |
+| `sonnet` | `anthropic/claude-sonnet-5-5` | `openai/gpt-6.1-sol` | `openai-codex/gpt-6.1-sol` |
+| `haiku` | `anthropic/claude-haiku-5-5` | `openai/gpt-6-luna` | `openai-codex/gpt-6-luna` |
+
+Pi warns that Anthropic bills Claude used through Pi per token, as extra usage, even on a Claude subscription. Pi shows that warning only in interactive mode, never for the `pi --mode rpc` children the `agent` tool runs.
+
+A `pi models: opus=<provider/id>, sonnet=<provider/id>` line in the Pi override sheet points each alias it names at another Pi model, whatever the session's provider. Add one when the session's provider has no column above and Pi has no credentials for `anthropic`, because each alias then resolves to an `anthropic/*` ID and the `agent` call fails with `No API key found for anthropic`. The `agent` tool also takes a full `provider/id`, passed through unchanged, and `inherit-parent`, `auto`, or no `model` runs the child on the parent's current model. Diverse-model panels (`arena`, `architect`, `interrogate`) stay diverse only while their aliases resolve to distinct models. If one model family is all you can reach, vary the reasoning effort and note in the verdict that diversity was reduced.
+
+`/setup-pstack` writes the configured model list. On Pi, keep the aliases and remap them with `pi models:`.
+
+## Session routing
+
+The pstack Pi extension adds the poteto-mode mandate, the text the Claude Code and Codex `SessionStart` hook injects, to the system prompt at every agent start, so the mandate survives compaction. It also adds the Pi override sheet, because Pi has no include syntax for context files. The sheet is `pstack-models.md` in the Pi agent directory, which is `$PI_CODING_AGENT_DIR` when set and `~/.pi/agent` otherwise. `session hook: off` in the sheet stops the mandate. Child agents that the `agent` tool starts get the sheet but not the mandate, as Claude Code subagents see CLAUDE.md but run no `SessionStart` hook. Every session, child agents and sessions with the hook off included, also gets a pointer to this file and Claude Code's sentence on making independent tool calls in one response.
+
+Without the extension nothing is injected. Request `poteto-mode` explicitly with `/skill:poteto-mode`, or add a standing instruction to `AGENTS.md`.
+
+## Driver and bundled skills pstack references
+
+The [driver policy](../SKILL.md#non-negotiables) selects the app driver. For skills and drivers named by these workflows, use these Pi equivalents:
+
+| Skill or driver named in pstack | On Pi |
+|---------------------------------|-------|
+| `run` (drive a CLI/TUI to see a change work) | Pi has no `run` skill. Run the app yourself via `bash` and observe the real output. |
+| `verify` (the project's `.claude/skills/verify/`, or Claude Code's bundled `/verify`) | Pi does not discover `.claude/skills/`. Read the project skill's SKILL.md by path, or add `../.claude/skills` to the `skills` list in `.pi/settings.json`. Without a project skill, drive the app as for `run`. |
+| Project UI driver | Drive the UI with whatever automation you have, or hand the user a concrete manual check. Do not claim done without observing the artifact. |
+| `plugin-dev:skill-development` (Claude's SKILL.md authoring guidance) | Follow Pi's skills documentation and the Agent Skills specification. Keep `name` + `description` frontmatter, name the directory after the skill, and use progressive disclosure. |
+| `loop` (recurring/self-paced re-invocation, used by `babysit`) | The extension's `/loop [interval] <prompt>` command. With an interval it re-fires on that cadence. Without one the prompt runs now and the model paces itself with `schedule_wakeup`. `/loop stop` cancels, also while an iteration runs: nothing that run then schedules is armed. A `/loop` given during a run starts once that run ends. |
+
+## Per-skill notes
+
+No skill file carries a Pi line. poteto-mode's Platform Adaptation section points here once, and the extension's system prompt points here in every session, so read a skill's row before you follow that skill. Most skills need only the tables above. These need one more mapping:
+
+| Skill | On Pi |
+|-------|-------|
+| `poteto-mode` | The todolist falls back to `todo.md`, and the Subagents defaults map through Subagent policy above. The Eval and Session pickup playbooks read transcripts from the Pi sessions directory (see Tool actions). |
+| `interrogate` | Adversaries dispatch through `agent` with the same `subagent_type` and `model` (see Subagent policy). Keep the panel on distinct models (see Model names). |
+| `recall` | Search the Pi sessions directory for this workspace (see Tool actions). Do not list or read `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects/`: it holds Claude Code transcripts, not this session's history. Match on `type: "message"` entries and their `message.role`. |
+| `show-me-your-work` | Check the log against this run's Pi session file (see Tool actions), not a Claude Code transcript. |
+| `setup-pstack` | The Pi sheet is `pstack-models.md` in the Pi agent directory (see Session routing), and the extension loads it, so no include line is needed. List models with `pi --list-models`. For a family whose model is not listed, offer a `pi models:` line (see Model names). The role rows and the five effort levels are identical. The `session hook` line applies on Pi too, where `off` stops the extension adding the mandate. When the user runs another Pi extension that registers `ask_user_question`, add `pi ask tool: off`, so the pstack extension leaves that tool name to it; Pi refuses to start while two extensions register the same name. When the user delegates through another Pi subagent extension, such as `pi-subagents`, add `pi agent tools: off`. The pstack extension then registers none of `agent`, `send_message`, `list_agents`, `stop_agent`, and `/pstack-agents`, so the model sees one set of delegation tools. When the session runs on `anthropic`, tell the user that Pi bills Claude per token as extra usage and that each multi-model panel multiplies that cost. |
+| `no-comments` | `pstack:comment-sicko` resolves through `agent` as written. Pass it the scope, not a request to run `/no-comments`, and run it without `isolation: "worktree"`, because a worktree starts from `HEAD` and lacks the scope's uncommitted changes. |
+| `teach` | Running `how` and `why` in parallel maps to two background `agent` calls. Pi has no image generation tool, so draw with Mermaid or plain text. |
+| `create-verification-skill` | The generated skill lands under `.claude/skills/verify/` on Claude Code. Write it where Pi discovers project skills, `.pi/skills/verify/` or `.agents/skills/verify/`, instead. The app-driving harness is platform-neutral. |
+| `maintain-verification-skill` | The parallel per-feature source readers map to background `agent` calls. The project-local skill lives under `.pi/skills/` or `.agents/skills/`, not `.claude/skills/`. |
+| `create-formal-verification-skill` | Write the generated skill where Pi discovers project skills, `.pi/skills/<area>/` or `.agents/skills/<area>/`, named for the area it verifies. The verifier and its run command are platform-neutral. |
+| `maintain-formal-verification-skill` | Project skills, the formal verification skill among them, live under `.pi/skills/` or `.agents/skills/`. |
+| `babysit` | `loop` and `AskUserQuestion` resolve through the tables above. |
+| `automate-me` | `plugin-dev:skill-development` resolves through the skills table above. The workspace's transcripts are its Pi sessions directory (see Tool actions). Pi does not discover `.claude/skills/`, so write the mode skill to `.pi/skills/<handle>-mode/SKILL.md` or `.agents/skills/<handle>-mode/SKILL.md` instead. |
+| `architect` | The runner panel goes through the **arena** skill, so its `agent` fan-out and model aliases apply here too. |
+| `arena` | The parallel candidates and the cross-judge are background `agent` calls on the configured aliases (see Model names). |
+| `how` | The parallel explorers and the explainer are `agent` calls, and `readonly` applies as written (see Subagent policy). |
+| `reflect` | The three reviewers and the synthesizer are background `agent` calls. The transcript finder reads Pi sessions too. Pass it this workspace's Pi sessions directory (see Tool actions) in place of Claude Code's projects directory. It follows the session's active branch to its opening prompt. Skill files load from the Pi package directory that `pi list` shows, not `${CLAUDE_CODE_PLUGIN_CACHE_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins}/`, so treat reads under that directory as plugin skill reads. |
+| `swarm` | Each worker is a background `agent` call on the configured alias. Give each writing worker `isolation: "worktree"` or its own output directory (see Subagent policy above). |
+| `why` | The parallel investigators and the synthesizer are background `agent` calls. List MCP servers from the tools Pi exposes to the session or `pi mcp list`, not from `.mcp.json` or `claude mcp list`. Spawn the synthesizer only after every investigator's completion notice has arrived, because those notices carry the findings the synthesizer gets. A `send_message` to an investigator returns no findings, so wait for its notice. |
+
+## Vendored scripts
+
+`skills/poteto-mode/scripts/` ships the `watch-pr` PR watcher and `worktree-audit.mjs`. These scripts use bun and Node.js and run the same on Pi; invoke them through `bash`. They need `bun` and `gh`, or `origin` when the forge is Origin. Run `worktree-audit.mjs` with `node`, as its shebang does. The audit follows each link in a worktree's ancestor directories with `stat` and matches it by the directory it lands on, under bun and node alike. A worktree whose own path bun cannot resolve loses its last chat and lands in `review`. A dangling or looping link is ignored. Any other link that `stat` cannot follow puts every worktree under the link's directory in `review`, with a warning that names the link. `worktree-audit.mjs` finds each worktree's last chat in every runtime's transcript directory that exists: Claude Code's projects under `$CLAUDE_CONFIG_DIR` (default `~/.claude`), Codex's sessions and archived sessions under `$CODEX_HOME` (default `~/.codex`), and Pi's `sessions/` and the pstack extension's subagent sessions under `$PI_CODING_AGENT_DIR` (default `~/.pi/agent`). Pass transcript directories after the repo path to scan others instead. It imports the transcript walker from `skills/reflect/scripts/find-transcript.mjs`, so keep the `reflect` skill installed beside `poteto-mode`.
+
+## Instructions file
+
+Where a pstack skill says "your instructions file", on Pi that is `AGENTS.md` or `CLAUDE.md`, which Pi loads from the working directory and each parent directory, plus `~/.pi/agent/AGENTS.md` for every directory. On Claude Code it is `CLAUDE.md`.

package/plugins/pstack/skills/poteto-mode/references/resume-storage.md

@@ -0,0 +1,20 @@
+# Resume storage
+
+Pause and pickup share one project locator. The `resume.mjs` command under `skills/poteto-mode/scripts/` resolves the project's Git common directory and stores checkpoints under its `pstack/resume/` directory. `latest.json` points to the latest complete checkpoint and records the worktree, branch, timestamp, note, and requested artifacts with content hashes.
+
+Claude Code, Codex, and other runtimes use this same command and location. Runtime-specific home directories and transcript encodings do not affect lookup. Git worktrees of the same repository share the locator, and Git excludes its contents from commits. This requires a local Git checkout whose common directory survives the interruption. It does not survive deleting or recloning the repository; transfer the complete checkpoint to durable storage before that happens and give the resumed session its locator.
+
+## Write a checkpoint
+
+1. Run `node <scripts>/resume.mjs begin --project <worktree>` to allocate a new checkpoint directory. Write `resume.md` there with intent, verified progress, current state, and next steps.
+2. Save requested artifacts in that directory and link them from the note. Reuse existing artifacts in the project when their location survives the anticipated interruption. Do not make competing copies. For a worktree that will be removed, place the requested material in the common checkpoint store instead. Check exact wording, completeness, and order where required.
+3. Publish with `node <scripts>/resume.mjs publish --project <worktree> --note <resume.md> --artifact <file> ...`. Register every local note link as an artifact, including existing project files. Link each local file with an inline Markdown link whose destination is the path, written bare or as `<path>`, with no square brackets in the link text and no title after the path. Reference-style links are not read. The path is relative to the note or absolute, and it is percent-decoded, so write a literal `%` as `%25`. Wrap a path that contains spaces or parentheses in angle brackets, or percent-encode it. Links inside code spans and fenced code blocks are ignored. Each rejected link reports this rule. The command verifies file ownership, links, and contents before atomically replacing `latest.json`. A failed publication must not be treated as a ready checkpoint.
+4. Run `node <scripts>/resume.mjs read --project <worktree>` and open its note and artifacts. Treat published checkpoint files as immutable. Use a new checkpoint directory for a later pause. If an existing project artifact changes, pickup reports that difference rather than silently treating it as the saved material.
+
+`begin` separates concurrent writers' files. Publishing replaces one shared latest pointer atomically; the last complete publication wins. Keep the returned checkpoint paths when multiple tasks must remain separately resumable. The pointer is a locator, not a task scheduler or execution lock.
+
+## Read a checkpoint
+
+Session pickup starts with `node <scripts>/resume.mjs read --project <worktree>` using only the project directory. Exit 0 with `kind: checkpoint` provides the saved note and all registered artifacts. Open them before searching transcripts. The command validates hashes and links again, including reuse of project artifacts.
+
+Exit 2 with `kind: missing` means there is no pointer, so use the transcript, cloud URL, or branch fallback. Exit 1 with `kind: unavailable` means a checkpoint is malformed, unreadable, changed, or incomplete. Diagnose that concrete gap; do not silently ignore the checkpoint or claim the material was never saved. None of these commands causes a running task to pause.

package/plugins/pstack/skills/poteto-mode/scripts/.prettierignore

@@ -0,0 +1,23 @@
+# Upstream's copies are not Prettier output, so formatting the port's copies
+# would add lines to the fork.
+bootstrap.ts
+
+# The port added lines here that run past 80 columns; wrapping them grows the
+# forked-line count.
+watch-pr/policy.test.ts
+watch-pr/types.compile.ts
+
+# The check covers TypeScript. Upstream's check-plan.mjs uses tabs, and the
+# port-only .mjs files follow no shared style.
+*.mjs
+
+# Upstream's check-plan.test.ts uses tabs like the checker it drives.
+check-plan.test.ts
+
+# Upstream stopped formatting fakes.test-helper.ts with Prettier at 997ffc7;
+# keeping its wrapping keeps the fork small.
+watch-pr/fakes.test-helper.ts
+
+# Upstream stopped formatting github.test.ts with Prettier at 96dec8e;
+# keeping its wrapping keeps the fork small.
+watch-pr/github.test.ts

package/plugins/pstack/skills/poteto-mode/scripts/.prettierrc.json

@@ -0,0 +1,3 @@
+{
+  "trailingComma": "es5"
+}

package/plugins/pstack/skills/poteto-mode/scripts/bootstrap.ts

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+// This tooling is bun-only (import.meta.dir, Bun.spawnSync, bun.lock). Fail with a
+// clear message instead of an opaque `import.meta.dir is undefined` crash under node.
+if (typeof Bun === "undefined") {
+  console.error(
+    "pstack poteto-mode tooling requires bun (https://bun.sh). Install bun, then re-run."
+  );
+  process.exit(1);
+}
+
+const scriptsDirectory = import.meta.dir;
+const nodeModulesDirectory = join(scriptsDirectory, "node_modules");
+const commanderPackagePath = join(
+  nodeModulesDirectory,
+  "commander",
+  "package.json"
+);
+const installKeyPath = join(
+  nodeModulesDirectory,
+  ".poteto-mode-tools-install-key"
+);
+
+function currentInstallKey(): string {
+  return createHash("sha256")
+    .update(readFileSync(join(scriptsDirectory, "package.json")))
+    .update("\0")
+    .update(readFileSync(join(scriptsDirectory, "bun.lock")))
+    .digest("hex");
+}
+
+export function ensureDependenciesInstalled(): void {
+  const installKey = currentInstallKey();
+  if (
+    existsSync(commanderPackagePath) &&
+    existsSync(installKeyPath) &&
+    readFileSync(installKeyPath, "utf8").trim() === installKey
+  ) {
+    return;
+  }
+
+  const result = Bun.spawnSync(
+    [process.execPath, "install", "--frozen-lockfile", "--production"],
+    { cwd: scriptsDirectory }
+  );
+  if (result.exitCode !== 0) {
+    process.stdout.write(result.stdout);
+    process.stderr.write(result.stderr);
+    throw new Error(
+      `bun install --frozen-lockfile exited with status ${result.exitCode}`
+    );
+  }
+  if (!existsSync(commanderPackagePath)) {
+    throw new Error(
+      "bun install --frozen-lockfile completed without installing commander"
+    );
+  }
+
+  writeFileSync(installKeyPath, `${installKey}\n`);
+
+  const restarted = Bun.spawnSync([process.execPath, ...process.argv.slice(1)], {
+    cwd: process.cwd(),
+    env: process.env,
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  process.exit(restarted.exitCode ?? 1);
+}