@justjoshn/pi-pstack 0.0.0-stage → 0.15.36-pi.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# pstack for Pi (pi-pstack)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+pi-pstack is pstack 0.15.36 for Pi 1.4.0: rigorous agent workflows (`/poteto-mode` and its playbooks), the principle skills, and the review, research, and verification skills, plus `deslop`, `control-cli`, and `control-ui`. A small extension provides the host features the skills call by name: `/name` skill commands, `/mode`, `/plan`, the `Task` subagent tool with isolated workers, forks, and `agent_status`, `TodoWrite`, `AskQuestion`, the model rule, `/loop`, subscriptions and webhook routines, and `visualize`.
+
+## Get set up
+
+1. Clone the repository and install the package from the checkout. Pi loads a local package in place, so keep the checkout where it is.
+
+   ```sh
+   git clone https://github.com/just-joshn/pi-customizations.git
+   cd pi-customizations
+   bun install
+   pi install ./extensions/pi-pstack
+   ```
+
+   Pi does not install dependencies for a local package, so `bun install` (or `npm install` in `extensions/pi-pstack`) fetches the one runtime dependency, `@anthropic-ai/sandbox-runtime`, which the read-only shell loads (readonly subagents and `/plan`). Without it everything else works, and a read-only shell command fails instead of running unsandboxed. To try it for one session without installing, run `pi -e ./extensions/pi-pstack`. To install the published package instead, run `pi install npm:@justjoshn/pi-pstack`.
+   Installing loads pi-pstack's tools and system-prompt sections at once, but no skill runs until you invoke it. 57 pstack skills stay out of the model's automatic skill list; only `/setup-pstack`, `create-skill`, `deslop`, `control-cli`, and `control-ui` can load from your words alone.
+2. Run `/setup-pstack`. It lists the models the `Task` tool can use, asks for a reasoning budget, maps a model to each role, and writes the model rule. A new rule applies from the next request.
+3. Start real work with `/poteto-mode`, a goal, and a check that can pass or fail.
+
+The guide in [`docs/guide/`](docs/guide/01-setup.md) walks through setup, `/poteto-mode`, understanding code, building, verifying, overnight runs, and making pstack yours.
+
+Remove the package with `pi remove ./extensions/pi-pstack`. Its state lives in `~/.pi/agent/pstack/`, or `$PI_CODING_AGENT_DIR/pstack/` when that variable is set (written `<pstack dir>` below): the model rule, routine credential files under `routines/`, and one folder per workspace under `workspaces/` with subagent transcripts, agent stores, projects, artifacts, and isolated-worker worktrees. Delete that directory to remove the state too.
+
+## Use it
+
+| You type | What happens |
+|---|---|
+| `/poteto-mode <task>` | The skill attaches to that one message. Every skill Pi loaded works this way: pstack's (`/how`, `/why`, `/arena`, `/interrogate`, `/principle-prove-it-works`, `/deslop`) and your own, such as a `/<handle>-mode` skill from `/automate-me`. `/skill:<name>` works too. |
+| `/mode poteto-mode [task]` | Keeps the skill in context on every turn. The footer shows a badge with the skill's `icon` and `color` metadata, such as a yellow `♛ mode: poteto-mode` (other skills get `⚡`). `/mode off` exits and `/mode` reports. Any loaded skill can back a mode. |
+| `/plan [task]` | Plan mode: the agent gets read-only tools (`read`, `grep`, `find`, `ls`, the sandboxed `bash_readonly`, `AskQuestion`, `TodoWrite`, `agent_status`, and `Task`, whose launches run readonly: a fresh one runs here with no worktree, and a resume or fork stays where its agent ran), investigates, and writes a plan with goal, verified steps, and risks. Writes are blocked. `/plan off` restores your tools so the agent can execute; `/plan` reports. The footer shows `plan`. |
+| `/loop 30m <prompt>` | Runs the prompt now and again 30 minutes after each run settles. Without an interval the agent picks each wake with the `Loop` tool, and the loop ends when it picks none and no background subagent is still running. `/loop stop` or Escape during a run ends it. The prompt can be a skill command, such as `/loop 1h /poteto-mode run the audit tick`. When a playbook says to arm `/loop`, the agent starts it with the `Loop` tool. Intervals go up to 24 days. |
+| `/routines` | Lists webhook routines with their URL, credential file, and status. |
+| `/setup-pstack` | Configures the per-role models. |
+| `/poteto-help <question>` | Answers a question about pstack and hands you a prompt to send. |
+
+`/mode`, `/plan`, `/loop`, and subscriptions need an interactive or RPC session. In the interactive `/` menu, skills appear under their own names next to Pi's `/skill:<name>` entries. Aliases work even with `enableSkillCommands` off. If you have a prompt template or extension command with a skill's name, yours keeps the name; Pi's built-in commands are handled before any alias.
+
+## Host features
+
+| Feature | Behavior |
+|---|---|
+| `Task` (`description`, `prompt`, `subagent_type`, `model`, `run_in_background`, `resume`, `fork`, `fork_turns`, `readonly`, `file_attachments`, `environment`, `cloud_base_branch`) | Starts a separate `pi --mode rpc` process per subagent, so this Pi process can steer and abort it. Foreground calls return the response and an agent ID. Background calls return at once, and a `<task>` notification arrives after your turn ends; print and JSON runs wait for pending notifications before exiting, unless aborted. Several calls in one message run in parallel. A subagent's own subagents cannot spawn more. A run lock per agent ID keeps out a second writer, even from another Pi process (Limits notes the stale-lock race). Children inherit the parent's project-trust decision. Foreground usage counts toward the session totals. The Task card leads with the call's `description`, then the agent type and the model that ran. |
+| `resume` | Sends a follow-up to an idle agent with its context, model, type, and directory. On an agent running in this Pi process, it delivers the prompt as a steer and returns at once. A readonly or plan-mode call cannot steer a writable agent. An agent running in another Pi process is refused. This is how a playbook "messages" a worker. Pi's own `/resume` command reopens a chat session instead. |
+| `fork` | Starts a new agent whose transcript begins as a copy of an idle agent's transcript, in that agent's directory (its worktree for an isolated worker), so it sees the built checkout and uncommitted changes. Type, model, and readonly default from the source; readonly can be added, never lifted. `fork_turns: N` (only with `fork`) copies just the first N user turns. `fork` excludes `resume`, `environment`, and `cloud_base_branch`. Pi's own `/fork` command branches the chat session instead. |
+| `stop_agent` | `agent_id`. Stops a running subagent. One this Pi process owns gets an RPC abort, then a kill after a grace period. One another of your Pi processes owns gets a signal to the live pid in its run lock. An idle or finished agent is left alone, and the result says so. |
+| `agent_status` | Reads a subagent's state (`running` while its run lock names a live pid, `idle`, or `missing`), type, model, directory, branch, times, and last reply, without waking it. It also shows whether the agent is readonly, the agent it was forked from, its pid while running, and its transcript. Without `agent_id` it lists the workspace's 20 newest agents. In the root chat that includes every descendant, isolated workers too. |
+| Subagent types | `generalPurpose` (default), `poteto-agent` (a background delegate that reads poteto-mode first), and `comment-sicko`, read from `agents/*.md`. Unknown types fail with the list. |
+| Models | A Pi model spec such as `claude-opus-5-5:xhigh` or `xai/grok-4.7:high`, model parameters such as `claude-opus-5-5[effort=high]` or `grok-4.7[fast=true]` (picks a listed `-fast` id of that model), or `inherit`, `inherit-parent`, `auto`, or nothing for the parent model. A model Pi does not list, or a thinking level the model does not support, fails with the allowed list. A bare model id that several providers offer resolves to the parent chat's provider when it offers that id, and otherwise fails with the choices. Older rules that wrote `claude-opus-5-5-xhigh` still resolve. The system prompt's `pstack_subagents` section lists the types, the parent model, and the models with their levels. |
+| Isolated workers (`environment: "cloud"`) | The subagent runs in a new git worktree at `<pstack dir>/workspaces/<workspace folder>/worktrees/<agent id>` on branch `pstack/<agent id>`, from `cloud_base_branch` (a local ref, else `origin/<branch>`) or your HEAD commit, so uncommitted changes do not reach it. The result and the card name the branch to merge, and `resume` and `fork` run in the same worktree. It fails clearly outside a git repository, in a repository with no commits, or when the base does not resolve. The worker shares the root chat's workspace state, so it sees the same projects, stores, and subagent transcripts. `swarm` and `orchestrate` spawn isolated workers by default. |
+| `readonly: true` | The child gets `read`, `grep`, `find`, `ls`, `TodoWrite`, and a read-only `bash`, and no MCP. That shell runs each command in an OS sandbox ([`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime): `sandbox-exec` on macOS, bubblewrap on Linux) that blocks every file write and all network access, so `git log` works and `touch` or `curl` fail. Where no sandbox can start, the command fails rather than running unsandboxed. |
+| `TodoWrite` | `todos` with `id`, `content`, `status`, and `merge`. The list follows the session branch and shows above the editor. |
+| `AskQuestion` | `title`, and per question `id`, `prompt`, `options` (`id`, `label`, optional `description`), and `allow_multiple`, through Pi's select dialog. Every question ends with `Other: (type to answer)`; a typed answer comes back as `other` with its text. In print and JSON runs, including subagents, each question comes back skipped. |
+| The model rule | `<pstack dir>/pstack-models.md`, plain Markdown with one line per role, added to every request's system prompt. A `pstack-models.mdc` from an earlier version is moved there once, without its frontmatter, and kept as `pstack-models.mdc.migrated`. |
+| Subscriptions | `subscribe_github_pr` (`scope` `pr` with `prUrl`, `repo` with `repo`, or `author` with `author` and `repo`) polls with `gh` every 60 seconds and wakes the chat when a PR's state, head, mergeability, review decision, reviews, or comments change, or when a check concludes or its conclusion changes; the first poll is a baseline. `subscribe_timer` takes a `name`, a `prompt`, and a 5-field `cron` or `delaySeconds`, either with `once`; `sessionStrategy` `wake_self` wakes this chat, and `new_session` runs each fire in a fresh background subagent. Re-subscribing an existing timer name returns `created: false`. `list_subscriptions` and `unsubscribe` manage them. Subscriptions persist in the session, restore on reload and resume, expire after 7 days unless `expiresInHours` says otherwise (at most 30 days), and stop with the Pi process. |
+| Webhook routines | `subscribe_webhook` (`name`, `prompt`) serves `http://127.0.0.1:<port>/routines/<slug>` (port `PSTACK_ROUTINES_PORT`, default 47913, where `0` picks a free port) and keeps a random sender key in `<pstack dir>/routines/<slug>/credentials.json` (mode 0600). The result names the URL and the file, never the key. A JSON POST with `X-Automation-Key` or `Authorization: Bearer` returns 200 and wakes the chat with a `[routine]` turn holding the prompt and a `<webhook_event>` block (`headers`, `body_digest`, `body`, `timestamp_ms`). A wrong key gets 401, an unknown routine 404, a method other than POST 405, a body over 64 KiB 413, and a body that is not a JSON object 400. `make-bot-ui` builds a page on top of this. |
+| Stores and projects | The system prompt names "the current agent's store" (per session), "the root agent's store" (the main chat's, named to every subagent however deep), and the workspace's `projects/` folder, where a program's Project is `<slug>/notes.md` (its tracker) and `<slug>/store/`. |
+| `visualize` | `title`, `kind` (`bar` or `line`), `labels`, `series` (`name`, `values`), and `unit` render a Unicode chart in the result and write a standalone SVG to the session's artifacts folder. |
+| Transcripts | The system prompt names this workspace's Pi session directory, the current session file, and this workspace's subagent transcripts. |
+| Image generation | Pi's codemode `models.generateImages()`, when codemode is on and an image model is configured; otherwise skills fall back to a Mermaid diagram. |
+
+Subagent transcripts are Pi sessions in `<pstack dir>/workspaces/<workspace folder>/subagents/`, with the agent ID in each file name, next to a small record that `resume`, `fork`, and `agent_status` read. Agent IDs belong to the workspace that started them. Children inherit your installed extensions and MCP servers, and local ones run in your working directory. Give each local subagent that writes its own git worktree, or launch it with `environment: "cloud"`, because a child process does not isolate the filesystem. A child exits on its own if its parent Pi process dies.
+
+## Limits
+
+- Isolated workers run on this machine. They start from committed code only and share your installed extensions, MCP servers, and network, except that a readonly worker gets no MCP servers and no network. pi-pstack never pushes their branches, though a worker can push its own. Worktrees and branches stay until you or the worktree-cleanup playbook remove them.
+- Subscriptions and routines live in the Pi process that created them. Keep that session running (for example in tmux) while they matter. A GitHub subscription restored after a restart takes a new baseline, so changes made while Pi was down do not wake it. Only one Pi process can hold the routine port; set `PSTACK_ROUTINES_PORT` for a second one. The routine listener binds `127.0.0.1`, so a page served to other machines forwards through a local server, as `make-bot-ui` describes.
+- The Benny automation pack under `automations/benny/` runs on pi-pstack subscriptions in a long-lived Pi session and needs a Slack MCP server for its Slack steps.
+- `/plan` uses `bash_readonly` for its shell rather than replacing `bash`, so your shell settings stay as they are outside plan mode.
+- Background subagent token usage is recorded in the child's transcript and in the `usage` field of the notification's details, but does not enter the parent session's totals: Pi 1.4.0 gives extensions no way to add usage outside a tool result.
+- `/reload`, `/new`, and Pi's `/resume` and `/fork` commands stop running background subagents, with a warning that names how many. Continue one later with `Task` `resume` and its agent ID.
+- A print or JSON run waits for its background subagents before it exits, with no timeout of its own, unless it is aborted.
+- Subagents start the same Pi script that runs the parent (`process.argv[1]`), or `pi` from `PATH`. Embedding the package through the SDK in another host is not supported.
+- Depth limits apply to `Task`. A writable subagent can still start `pi` through `bash`, and that process is outside the depth limit and parent watchdog.
+- A child loads your installed extensions plus this package. If you run one checkout with `-e` while a different checkout of pi-pstack is installed, the child loads both and fails on duplicate tools; use one copy, or a separate `PI_CODING_AGENT_DIR`, as `live:e2e` does.
+- Subagents run headless in RPC mode, so an extension that asks for permission through a dialog cannot ask there.
+- The read-only shell sandboxes shell subprocesses only, and is verified on macOS and on the Ubuntu CI runner. On Linux it needs `bubblewrap`, `socat`, and `ripgrep`. Ubuntu 24.04 and later restrict unprivileged user namespaces: either add an AppArmor profile that grants `userns` to `bwrap`, or run `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`, which lifts the restriction for every program on the machine. The policy sets `allowAllUnixSockets: true` so Linux skips `apply-seccomp`, whose nested userns fails on GitHub-hosted runners; filesystem write denial and network denial still come from bubblewrap.
+- Whether a model follows a playbook is the model's call.
+- Workspace folders follow Pi's session-folder naming, so two paths that differ only by `/` versus `-` share a folder; resume and fork refuse an agent whose record names the other directory.
+- The run lock that keeps one writer per agent ID names the process writing the transcript. A lock file without a readable pid counts as held; the error names the file to delete. `agent_status` shows such an agent as `idle`. A lock whose pid is dead is taken over, and two processes that take over the same stale lock at the same moment can both succeed.
+- `skills/poteto-mode/scripts/watch-pr` needs Bun and installs its one dependency on first run. `check-plan.mjs` needs only Node. `worktree-audit.sh` needs `rg` and `jq`, and works with BSD (macOS) or GNU `stat` and `date`.
+- `statechart` runs `skills/statechart/scripts/statechart` on Node 22.18 to 22.x, Node 23.6 or later, Bun 1.1.5 or later, or Deno 2.0 or later. The first run installs TLC and Java through [mise](https://mise.jdx.dev/) and needs the network. Without a SPEC it prints `Give one SPEC.tla.` and its usage, then exits 2.
+
+## Maintain it
+
+The skills, agents, guide, and automation pack are this package's own files; edit them in place. They track pstack 0.15.36 in behavior. The record of the move to Pi-native text and the host features added for it is at the repository root, in `parity/pi-pstack-0.15.36/` (design and decisions); earlier records are in the root's `parity/pi-pstack-*`. Four mechanisms Pi 1.4.0 does not export keep a hand-written implementation here: [`docs/native-gaps.md`](docs/native-gaps.md) names each one, the evidence, and the public API that would replace it.
+
+```sh
+bun run typecheck
+bun run test
+bun run live:e2e -- --model deepseek/deepseek-flash      # real-model scenarios; needs credentials and gives the model under test your real auth.json (see the script header)
+```
+
+## Licenses
+
+The port's own code is MIT (`LICENSE`). pstack's files keep their MIT notice in `licenses/pstack.LICENSE` (© 2026 Lauren Tan), and the `deslop`, `control-cli`, and `control-ui` skills keep theirs in `licenses/cursor-team-kit.LICENSE`.

package/agents/comment-sicko.md

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

package/agents/poteto-agent.md

@@ -0,0 +1,9 @@
+---
+name: poteto-agent
+description: 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 `generalPurpose` skips that read and drifts.
+is_background: true
+---
+
+# 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 Task 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, read `skills/poteto-mode/SKILL.md` in the pi-pstack package directory the system prompt names. 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/automations/benny/FOR_AGENTS.md

@@ -0,0 +1,82 @@
+# benny automation intent
+
+## what i want to automate
+
+i want two pi automations that work together in one slack issue channel. each one is a pi-pstack subscription in a long-running pi session rooted in the target repository.
+
+### automation 1: triage issue reports
+
+- trigger: when someone posts a new top-level report in my configured source slack channel, i want this automation to start on that report and keep its original thread coordinates. by default a `subscribe_timer` sweep on a cron schedule finds the report; a `subscribe_webhook` routine fed by my slack app or relay is the push alternative.
+- behavior: i want it to read the thread and attachments, classify the report as a bug or performance issue, feature request, question or feedback, or reroute, and trace the likely owning layer before routing.
+- tracker: i want it to search my configured tracker for duplicates, update a confident duplicate, and create a ticket only for a clear net-new bug.
+- tools: i want slack thread read and reply access through my slack mcp server, my configured tracker integration, and my optional routing map.
+- outcome: i want exactly one reply in the source thread with a short verdict and `[benny:bug]`, `[benny:performance]`, or `[benny:other]`. a bug or performance marker may include the tracker url.
+- boundary: i never want this automation to post a root message in the source channel.
+
+### automation 2: reproduce and fix confirmed bugs
+
+- trigger: i want this automation to start from the same new top-level report, or another supported trigger chosen during setup, then wait for the trusted triage marker in the original thread.
+- gates: i want it to stop when someone clearly owns the fix. if an existing pull request or merged commit may fix the report, i want verification instead of a competing change.
+- behavior: i want it to use my configured control adapter and feature map, reproduce the exact symptom twice through the real ui, and capture screenshots, video, and a read-only state cross-check.
+- fix: i want it to verify existing pull requests without authoring over them. after a confirmed repro, it may attempt one bounded root-cause fix, use tdd when the test is cheap, smoke the blast radius, and open a draft pull request only when before-and-after proof passes.
+- tools: i want slack thread read and reply access through my slack mcp server, repository and history access, draft pull request creation with `gh`, my configured tracker, and my control adapter.
+- outcome: i want evidence and a verified result in the source or optional operations threads, plus an optional draft pull request. updates should be concise.
+- boundary: i never want this automation to post a root message in the source channel.
+
+### shared rules
+
+- i want the source channel and root thread coordinates to stay immutable for the whole run.
+- i treat utility and debug bots as evidence, not delegation or fix ownership.
+- i allow subagents to help, but they cannot post to slack or receive slack credentials. analysis subagents run as `Task` with `readonly: true`, which gives them no mcp servers and no network.
+- i want this entire pack committed at `.pi/automations/benny/` in the target repository. its `SKILL.md` files are direct automation instructions, not skills pi discovers.
+- i want pi-pstack installed in pi for shared dependencies such as `how`, `why`, `tdd`, `unslop`, and the required principle skills.
+- i want each subscription prompt to read its operational file directly from the target repository. i do not want pi-pstack package paths, copied excerpts, or slash-skill discovery.
+- i keep user-owned configuration, feature maps, routing maps, memory, and secrets outside `.pi/automations/benny/` so pack refreshes cannot overwrite them.
+- i want durable memory as files in one directory setup names, such as `~/.pi/agent/pstack/automations/benny/memories/`: a claim ledger so no report runs twice, and short operating notes.
+- i want both automations to fail closed when channel coordinates, tracker access, the control adapter, or the feature map are missing or uncertain.
+- i want draft pull requests only. do not merge or deploy.
+
+### my configuration
+
+- source slack channel: `<channel>`
+- optional operations channel: `<channel or none>`
+- repository and default branch: `<repo>`, `<branch>`
+- tracker: `<type, team, project, labels, intake status>`
+- routing map: `<path or none>`
+- triage identity: `<slack identity>`
+- control skill: `<configured skill or adapter>`
+- feature map: `<committed same-repo path outside the copied pack, or behavior to paraphrase>`
+- trigger mode: `<timer with cron schedules, or webhook with my relay>`
+- memory directory: `<path>`
+- models: `<triage, reproduce, code, media review, as pi model specs>`
+- status emoji strings: `<seen, reproducing, reproduced, blocked, fixing, failed, pull request opened>`
+- budgets: `<polling, verdict wait, follow-up, repro, rejection, fix>`
+- optional bot token capability: `<none, file download, or editable operations status>`
+
+start from [`configuration.example.yaml`](./templates/configuration.example.yaml) and [`feature-map.example.md`](./skills/reproduce-and-fix-issues/references/feature-map.example.md). copy and fill them outside this pack, for example under `.pi/benny/`. keep secret values in a secret manager or environment.
+
+## for the agent
+
+the human enters setup by pointing pi at this file. do not look for or invoke a discovered benny slash skill.
+
+1. ask which repository will run the automations.
+2. treat the directory containing this `FOR_AGENTS.md` as the source pack.
+3. merge the entire source pack into `<target-repository>/.pi/automations/benny/`.
+4. preserve every destination-only file. never delete unrelated files or overwrite user-owned configuration, feature maps, routing maps, or memory.
+5. when an existing destination file at a source-managed path differs, review the diff and merge without discarding local edits. if ownership is ambiguous, stop and ask before replacing it.
+6. verify that the copied `FOR_AGENTS.md` and `skills/setup-benny/SKILL.md` exist in the target repository.
+7. read and follow `.pi/automations/benny/skills/setup-benny/SKILL.md` directly from the target repository.
+
+i want pi-pstack installed in pi, either for me (`pi install <path-to-pi-pstack>`) or for the target repository (`pi install -l <path-to-pi-pstack>`, which writes `.pi/settings.json`). preserve every unrelated setting and package when that file already exists.
+
+i want this setup session to run in the target repository, so a fresh subagent it starts runs there too, and i want verification from that subagent. confirm that pi-pstack's `how`, `why`, `tdd`, `unslop`, and the principle skills used by benny are installed there. do not count a skill this session loaded by hand.
+
+if pi-pstack or any shared dependency does not resolve, stop and explain what failed. do not move `.pi/automations/benny/skills/` into `.pi/skills/` or expect its files to appear in the slash-skill list.
+
+tell me that subscriptions live in the pi process: the session that creates them must keep running, for example in tmux, and they expire after seven days unless renewed. do not create or update a subscription until i explicitly ask.
+
+for first-time creation, create the triage subscription first, check it with `list_subscriptions`, and confirm one harmless fire before creating the repro subscription.
+
+fill each prompt template from the finished configuration. the triage prompt must read and follow `<target-repository>/.pi/automations/benny/skills/triage-issue-reports/SKILL.md`. the repro prompt must read and follow `<target-repository>/.pi/automations/benny/skills/reproduce-and-fix-issues/SKILL.md`.
+
+for existing subscriptions, check them with `list_subscriptions`. a subscription keeps its prompt when you subscribe again with the same name, so changing one means `unsubscribe`, then subscribing again. do not create duplicates under new names.

package/automations/benny/README.md

@@ -0,0 +1,20 @@
+# benny
+
+benny gives you two pi automations for slack issue reports. one triages each report. the other reproduces confirmed bugs and may prepare a small draft fix.
+
+a pi automation is a pi-pstack subscription in a long-running pi session rooted in the target repository. a scheduled sweep is `subscribe_timer` with a cron schedule. each fire wakes that session, which hands one report to a background subagent on the automation's model. a push trigger is `subscribe_webhook`: a slack app or relay you run posts each new report to the local routine url. slack reads and writes go through a slack mcp server configured in pi (`pi mcp list`). durable memory is plain files in a directory setup names, such as `~/.pi/agent/pstack/automations/benny/memories/`.
+
+the files in this directory are dormant setup and automation sources. they do not appear as slash skills.
+
+## set it up
+
+1. install pi-pstack (`pi install <path-to-pi-pstack>`) and configure a slack mcp server in pi. `pi mcp list` must show it.
+2. start pi in the target repository and point it at [`FOR_AGENTS.md`](./FOR_AGENTS.md).
+3. let setup merge this whole directory into the target at `.pi/automations/benny/`. it must preserve destination-only files and review conflicts instead of overwriting local edits.
+4. keep user-owned configuration outside the copied pack, for example in `.pi/benny/`. adapt [`configuration.example.yaml`](./templates/configuration.example.yaml) and [`feature-map.example.md`](./skills/reproduce-and-fix-issues/references/feature-map.example.md).
+5. commit `.pi/automations/benny/` and any secret-free configuration, so pack refreshes stay reviewable.
+6. when you ask, setup creates the two subscriptions and checks them with `list_subscriptions`. then send a harmless test report and verify every source-channel post stays in the original thread.
+
+## what differs from hosted automations
+
+subscriptions live in the pi process. they run only while the session that created them runs, so keep it open, for example in tmux, and keep the machine awake. they come back when you resume that session after a restart. they expire after seven days by default: `list_subscriptions` shows `expiresAt`, and renewing one means `unsubscribe`, then subscribing again with the same name. a webhook routine listens on `127.0.0.1` only, so slack cannot reach it directly. a push trigger needs a relay you run.

package/automations/benny/skills/reproduce-and-fix-issues/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: reproduce-and-fix-issues
+description: Reproduce triaged Slack bugs through a configured app-control adapter, verify existing fixes, and open a bounded draft pull request only after before-and-after proof. Use only from the configured Benny repro automation.
+disable-model-invocation: true
+---
+
+# Reproduce and fix issues
+
+Wait for a trusted triage marker in the source thread. Reproduce the exact symptom through the target app's real UI. Verify an existing fix when one exists. Attempt a bounded fix only after a confirmed repro.
+
+Load the external Benny configuration supplied by the automation. If the config, required actions, control adapter, or completed feature map is missing, fail closed.
+
+## Hard safety rules
+
+- Freeze the source channel and root thread coordinates before doing any work.
+- Never post a root message in the source channel.
+- Preflight the source parent before every source-thread post.
+- The coordinator is the only Slack poster.
+- Delegated analysis workers are read-only and return findings or media notes. In Pi, start each one with `Task` and `readonly: true`, which gives it no MCP servers and a shell with no network.
+- A fix-phase code worker may edit only when its environment provably excludes Slack credentials and every Slack write action. Otherwise the coordinator edits. A writable Pi subagent inherits the session's MCP servers and environment, so it qualifies only when the Pi process that owns the subscriptions loads no Slack MCP server with write tools and has no Slack token in its environment.
+- Every child prompt must explicitly forbid every Slack MCP write tool (`mcp__<slack-server>__*` tools that post, edit, react, or upload), `chat.postMessage`, and all other Slack writes.
+- Never give a child a Slack token, posting instructions, source coordinates for posting, or permission to report externally.
+- If a child needs Slack write access to run, do not launch it.
+- Utility bots are evidence sources. They do not own the fix unless a person explicitly delegated the fix to them.
+- The exact discriminating symptom must appear twice through real UI interaction.
+- State inspection may confirm an observation. It must not inject or force the symptom.
+- No confirmed repro means no authored fix.
+- Existing pull requests or commits switch the run to verify mode. Do not author over them.
+- Use `github.com` pull request links.
+- Keep captures, recordings, logs, and tokens out of source control.
+- Use pstack's `principle-guard-the-context-window` for delegated analysis.
+- Apply pstack's `principle-sequence-verifiable-units`, `principle-fix-root-causes`, and `principle-prove-it-works` through repro, fix, and verification.
+
+## 1. Freeze source coordinates
+
+Before making a work list or delegating:
+
+1. Require the trigger channel to equal the configured source channel.
+2. Set `SOURCE_THREAD_TS` to `trigger.thread_ts` when present. Otherwise use `trigger.ts`.
+3. Require a nonempty `SOURCE_THREAD_TS`.
+4. Store `SOURCE_CHANNEL_ID` and `SOURCE_THREAD_TS` as immutable values.
+5. Read the source thread and verify its root has those exact coordinates.
+6. Fetch the source permalink.
+
+Never replace these values with a reply timestamp, operations timestamp, or status-message timestamp.
+
+Before every source-channel post:
+
+1. Read the thread by the immutable coordinates.
+2. Confirm the parent exists, is not deleted, and still belongs to the source channel.
+3. Send only with `channel=SOURCE_CHANNEL_ID` and `thread_ts=SOURCE_THREAD_TS`.
+4. Read the thread again and verify the new message is a reply.
+
+If any check fails, post nothing. Never retry at the root or in a fallback channel.
+
+## 2. Wait for the triage contract
+
+Watch the source thread for the configured verdict budget. Stay silent while waiting.
+
+Accept a verdict only when:
+
+- Its author matches `slack.triage_identity_user_id`.
+- It is a reply under `SOURCE_THREAD_TS`.
+- It contains exactly one configured marker.
+
+Public marker forms:
+
+```text
+[benny:bug]
+[benny:bug] tracker=https://tracker.example/issue/123
+[benny:performance]
+[benny:performance] tracker=https://tracker.example/issue/123
+[benny:other]
+```
+
+Proceed only for `bug` or `performance`. Capture the optional tracker URL. Stop silently for `other`, a missing verdict, an untrusted author, conflicting markers, or a timeout.
+
+This marker replaces private bot identities and free-form verdict matching.
+
+## 3. Apply ownership and fix-artifact gates
+
+Re-read the thread immediately before starting work.
+
+### Someone is explicitly fixing it
+
+Stop when a person clearly claims the fix, gives a concrete implementation plan, or asks another agent to implement, patch, fix, or open a pull request.
+
+Do not treat these as fix ownership:
+
+- A bot summarizes evidence.
+- A tool looks up logs or tickets.
+- Someone asks a bot to diagnose, explain, inspect, or reproduce.
+- A bot posts a cause hypothesis without agreeing to implement it.
+
+Judge the requested action, not the presence of a bot.
+
+### A fix artifact already exists
+
+If an open pull request or merged commit plausibly fixes this report, switch to `references/verify-existing-fix.md`.
+
+An artifact may come from the thread, tracker issue, repository history, or pull request search. A claim without a commit or pull request is not a fix artifact.
+
+If a person owns the work but has not produced an artifact, stop. Do not race them.
+
+## 4. Open an optional operations thread
+
+If `slack.operations_channel_id` is configured, the coordinator may create one root status message there. This is the only allowed root post in the repro workflow.
+
+Store its coordinates as `OPERATIONS_CHANNEL_ID` and `OPERATIONS_THREAD_TS`. Never confuse them with the source coordinates.
+
+Use the configured plain Unicode status strings. Keep status text short:
+
+- Reproducing
+- Could not reproduce
+- Blocked
+- Reproduced
+- Verifying existing fix
+- Attempting bounded fix
+- Draft pull request opened
+- Fix did not land
+
+Prefer the configured Slack MCP tools. Use `BENNY_SLACK_BOT_TOKEN` only when the user configured it for a narrow missing capability such as editing this one status message. Never expose the token to a worker.
+
+If no operations channel is configured, keep detailed status in the run's final message (its Task notification). Do not substitute a source-channel root message.
+
+## 5. Load and check the control adapter
+
+Read `references/control-adapter.md` and the completed map at `control.feature_map_path`, then invoke the skill named by `control.skill_name`.
+
+Find the feature-map section that matches the reported user path. Read it before driving the app. If no section covers the feature, mark the run blocked instead of inventing a path or selector.
+
+Require all seven capabilities:
+
+1. Bring up the configured target app and test environment.
+2. Navigate the mapped feature and exercise its documented states.
+3. Drive the real UI with clicks, typing, keys, scrolling, drag, resize, or navigation.
+4. Inspect state without mutating it.
+5. Capture screenshots.
+6. Start and stop a screen recording.
+7. Clean up processes, sessions, profiles, and temporary data.
+
+If the adapter is absent or any required capability is missing, mark the operations status as blocked and stop. Do not pretend a screenshot, unit test, state mutation, or source reading is a UI repro.
+
+## 6. Study the report
+
+Read the full source thread and tracker issue when present.
+
+Collect:
+
+- Exact action path
+- Expected behavior
+- Observed behavior
+- Discriminating state where they diverge
+- Frequency
+- Version, environment, and platform
+- Attachments and error signatures
+- Candidate code area
+
+Inspect screenshots and video. Use read-only parallel workers for code history, test ideas, blast-radius mapping, and media review when useful. Each worker gets a narrow question and the Slack-write prohibition.
+
+Use pstack's `how` skill to trace the action through the repository. Use `why` for regression history and defensive code. Form competing cause hypotheses and identify evidence that would separate them.
+
+## 7. Reproduce
+
+Bring up the target app through the control adapter.
+
+Confirm the correct app, workspace, account, data set, and feature state before acting. Use stable app markers. Do not rely on window order or a familiar title alone.
+
+Drive the reported path through real UI actions.
+
+Before calling it reproduced:
+
+1. Name the correct final state.
+2. Name the broken final state.
+3. Reach the point where they diverge.
+4. Observe the broken state.
+5. Reset enough state to make the second attempt independent.
+6. Repeat the same path and observe the same broken state again.
+7. Cross-check a real state value when possible.
+
+An expected dialog, loading state, or setup step is not the bug. Capture the final state that distinguishes correct from broken behavior.
+
+Use the configured repro budget. If the symptom does not reproduce within it, report a clean `Could not reproduce` outcome. If the environment cannot provide a required capability, report `Blocked` and state what was missing.
+
+## 8. Capture and review evidence
+
+For a successful repro:
+
+- Record the full path through the symptom.
+- Capture a screenshot of the broken final state.
+- Save a short note with the exact steps and observed state.
+- Keep artifacts in the configured temporary artifact directory.
+
+Have a read-only media reviewer answer one question: does the evidence visibly show the discriminating broken state?
+
+If the answer is no or uncertain, the repro is not confirmed. Capture better evidence or use `Could not reproduce`.
+
+Post detailed evidence only in the operations thread when configured. Keep the source update concise.
+
+## 9. Report the repro outcome
+
+Update the operations status first.
+
+For `Could not reproduce` or `Blocked`, post nothing in the source thread. The operations thread or the run's final message (its Task notification) carries the result.
+
+For a confirmed repro, run the source preflight and post at most one unprompted source reply:
+
+- Say the issue reproduced.
+- Link the operations evidence thread when one exists.
+- Include at most three short findings.
+- Link the tracker issue when one exists.
+- Do not ping an owner by default.
+
+Attach evidence only when the configured Slack action keeps it inside the same source thread and the organization's retention policy allows it.
+
+Wait for the configured rejection window. If a person shows that the setup or interpretation was wrong, correct the repro once. Do not start the fix phase until the window closes without a valid rejection.
+
+## 10. Verify an existing fix
+
+When a fix artifact exists, follow `references/verify-existing-fix.md`.
+
+Verification must show the symptom on the baseline and its absence on the patched build. Both paths use the real UI twice.
+
+Do not edit the existing fix, add a competing patch, or open a replacement pull request.
+
+## 11. Qualify a bounded fix
+
+Attempt a fix only when all of these hold:
+
+- The outcome is a plain confirmed repro.
+- Media review confirmed the broken final state.
+- No existing fix artifact appeared.
+- No person claimed the fix during the rejection window.
+- Runtime evidence identifies the root cause.
+- The likely change fits the configured fix budget and repository scope.
+- The control adapter can run both baseline and patched builds.
+
+If any condition fails, keep the repro report and stop without a pull request.
+
+When the gate passes, update operations status to `Attempting bounded fix`.
+
+## 12. Root-cause and implement
+
+The coordinator owns every Slack post, the final diff review, commits, and the pull request.
+
+Read-only workers may:
+
+- Trace code and history
+- Propose tests
+- Map blast radius
+- Review a diff
+- Review media
+
+They do not edit, run external writes, post status, or own the fix.
+
+A tightly scoped code edit may be delegated during this phase only when tool isolation removes Slack credentials and every Slack write action from that worker. Its prompt must still carry the explicit Slack-write ban. The coordinator reviews the edit and runs or verifies the required tests. If tool isolation is uncertain, keep the edit in the coordinator.
+
+Confirm the mechanism with runtime evidence. Eliminate competing hypotheses before editing.
+
+Fix the root cause with the smallest justified change.
+
+- Invoke pstack's `tdd` skill when there is a cheap local test target, and write the failing test before the fix.
+- State why TDD was skipped when the path is expensive, unclear, or integration-heavy.
+- Keep unrelated cleanup out.
+- Stop if the change grows beyond the configured effort or risk budget.
+
+## 13. Prove the fix
+
+Keep the original baseline evidence.
+
+On the patched build:
+
+1. Run the same real UI path.
+2. Repeat it twice.
+3. Show that the broken state is gone.
+4. Show the expected state in its place.
+5. Capture an after recording and screenshot.
+6. Cross-check the same real state value used for the baseline.
+
+A compile, unit test, code review, or plausible diff is not after evidence.
+
+Run focused tests, then smoke the blast radius around the changed behavior. Cover nearby states, inputs, permissions, platforms, and failure paths that the change could affect. Stop without a pull request if a regression remains.
+
+## 14. Open a draft pull request
+
+Only after before-and-after proof:
+
+- Review the final diff for unrelated changes and secrets.
+- Run the repository's required checks.
+- Create small ordered commits when the repository workflow allows it.
+- Open a draft pull request. Never merge or deploy from this workflow.
+- Link the configured tracker issue using the tracker's supported pull request syntax.
+- Use the configured public URL form, normally `https://github.com/{owner}/{repo}/pull/{number}`.
+- Include the repro steps, root cause, test result, before and after evidence, and blast-radius checks.
+- Run the pull request text and all Slack updates through pstack's `unslop` skill.
+
+If pull request creation fails, do not claim success. Keep the commit or branch state in the run's final message (its Task notification) and mark operations status `Fix did not land`.
+
+On success, mark operations status `Draft pull request opened` and post one concise reply in the operations thread with the linked pull request. Do not create a second source-channel root or unprompted source reply.
+
+## 15. Follow-ups and cleanup
+
+Watch the configured operations thread for one follow-up window.
+
+- Answer a direct question from evidence already gathered.
+- Apply one concrete correction and rerun the repro once when it invalidates the setup.
+- Stay out of human coordination and side chatter.
+- Stop when asked.
+
+Always call the control adapter's cleanup capability. Keep artifacts only as long as the configured retention policy allows.