@justjoshn/pi-pstack-v2 0.1.7 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +19 -7
- package/docs/guide/01-setup.md +6 -6
- package/docs/guide/02-poteto-mode.md +1 -1
- package/docs/guide/07-overnight.md +3 -3
- package/docs/pi-mechanisms.md +35 -53
- package/package.json +5 -3
- package/skills/arena/SKILL.md +5 -5
- package/skills/automate-me/SKILL.md +2 -2
- package/skills/benchmark-checklist/SKILL.md +1 -1
- package/skills/control-cli/SKILL.md +1 -1
- package/skills/figure-it-out/SKILL.md +1 -1
- package/skills/how/SKILL.md +2 -2
- package/skills/interrogate/SKILL.md +2 -2
- package/skills/maintain-verification-skill/SKILL.md +1 -1
- package/skills/make-bot-ui/SKILL.md +2 -2
- package/skills/no-comments/SKILL.md +1 -1
- package/skills/poteto-help/SKILL.md +3 -3
- package/skills/poteto-mode/SKILL.md +9 -9
- package/skills/poteto-mode/playbooks/autopilot-full.md +5 -5
- package/skills/poteto-mode/playbooks/babysit.md +1 -1
- package/skills/poteto-mode/playbooks/bug-fix.md +1 -1
- package/skills/poteto-mode/playbooks/eval.md +3 -3
- package/skills/poteto-mode/playbooks/feature.md +2 -2
- package/skills/poteto-mode/playbooks/hillclimb.md +1 -1
- package/skills/poteto-mode/playbooks/opening-a-pr.md +1 -1
- package/skills/poteto-mode/playbooks/perf-issue.md +1 -1
- package/skills/poteto-mode/playbooks/refactoring.md +1 -1
- package/skills/poteto-mode/playbooks/shipping.md +2 -2
- package/skills/poteto-mode/playbooks/worktree-cleanup.md +1 -1
- package/skills/poteto-mode/worker.md +1 -1
- package/skills/recall/SKILL.md +3 -3
- package/skills/review-and-ship/SKILL.md +1 -1
- package/skills/setup-pstack/SKILL.md +2 -2
- package/skills/show-me-your-work/SKILL.md +2 -2
- package/skills/statechart/SKILL.md +1 -1
- package/skills/statechart/references/render.md +1 -1
- package/skills/swarm/SKILL.md +4 -4
- package/skills/workflow-from-chats/SKILL.md +1 -1
- package/src/gondolin/bash.ts +51 -0
- package/src/gondolin/fs-operations.ts +56 -0
- package/src/gondolin/grep.ts +96 -0
- package/src/gondolin/index.ts +58 -0
- package/src/gondolin/paths.ts +34 -0
- package/src/gondolin/search.ts +67 -0
- package/src/gondolin/tools.ts +40 -0
- package/src/gondolin/vm.ts +65 -0
- package/src/index.ts +31 -130
- package/src/jobs.ts +58 -315
- package/src/subagent/agents/poteto-agent.md +1 -1
- package/src/subagent/agents/worker.md +5 -0
- package/src/subagent/dispatch.ts +2 -2
- package/src/subagent/index.ts +33 -2
- package/src/subagent/render-call.ts +4 -2
- package/src/subagent/run-single.ts +9 -7
- package/src/subagent/schema.ts +28 -2
- package/src/subagent/types.ts +7 -0
- package/src/subagent/wake-jobs.ts +69 -0
- package/src/credentials.ts +0 -171
- package/src/git.ts +0 -94
- package/src/paths.ts +0 -16
- package/src/requests.ts +0 -182
- package/src/sandbox.ts +0 -284
- package/src/sweep.ts +0 -187
- package/src/transcript.ts +0 -79
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
pstack for Pi. The package ships pstack's skills, playbooks, principles, agent roles, scripts, and guide, plus the cursor-team-kit skills that pstack depends on. It is for people who want `/skill:poteto-mode` and its workflow in Pi. Each Cursor mechanism is replaced with a Pi one.
|
|
4
4
|
|
|
5
5
|
- Delegated Pi workers run through the packaged `subagent` tool, which starts each `pi` in its own tmux session.
|
|
6
|
-
-
|
|
6
|
+
- Pi's built-in tools (`read`, `write`, `edit`, `bash`, `ls`, `find`, `grep`) and `!` shell commands run inside a Gondolin micro-VM, ported from Pi's `gondolin` example extension. There are no permission prompts.
|
|
7
7
|
- Plans are files, and checklists live in `TODO.md`.
|
|
8
8
|
- Watchers, dev servers, and heartbeat ticks run through `tmux_run`, never as background shell jobs.
|
|
9
9
|
|
|
@@ -17,10 +17,16 @@ pi install npm:@justjoshn/pi-pstack-v2
|
|
|
17
17
|
|
|
18
18
|
Built and tested against Pi 1.5.2. Do not install another pstack package alongside it. Skill names collide, and Pi keeps only the first it finds.
|
|
19
19
|
|
|
20
|
+
npm 11.20 and later warn that `ssh2` and `cpu-features` have install scripts not yet covered by `allowScripts`. Both come from Gondolin, through its SSH support. Their scripts only try to compile optional native speedups, which pstack does not need. The VM boots without either build. Only the root `package.json` in Pi's npm directory can hold `allowScripts`, so this package cannot answer for you. After installing, deny both once. npm keeps the entry across `pi update`.
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
cd ~/.pi/agent/npm && npm install-scripts deny ssh2 cpu-features
|
|
24
|
+
```
|
|
25
|
+
|
|
20
26
|
## Requirements
|
|
21
27
|
|
|
22
28
|
- tmux. Pi's `docs/tmux.md` covers the extended-keys setup.
|
|
23
|
-
-
|
|
29
|
+
- QEMU, for the Gondolin VM (`brew install qemu` on macOS). Gondolin downloads its guest image on first use.
|
|
24
30
|
- bun and `gh`, for the scripts some skills run, such as `watch-pr` and `statechart`.
|
|
25
31
|
- `jq` and `rg` (ripgrep), for `worktree-audit.sh` and the `pr-review-canvas` skill.
|
|
26
32
|
|
|
@@ -36,18 +42,24 @@ Type `/skill:poteto-help` with a question if you are unsure which skill fits.
|
|
|
36
42
|
|
|
37
43
|
## What it adds
|
|
38
44
|
|
|
39
|
-
The package adds the upstream `subagent` tool (tmux-backed), `tmux_run`, `tmux_jobs`, and
|
|
45
|
+
The package adds the upstream `subagent` tool (tmux-backed), `tmux_run`, `tmux_jobs`, the Gondolin tool routing, and two slash commands. Every skill runs as `/skill:<name>`. `/pstack-mode <skill>` keeps a skill in the system prompt every turn, pstack's Custom Mode, until `/pstack-mode off`. `/gondolin` shows the session's VM.
|
|
40
46
|
|
|
41
47
|
| Tool | Does |
|
|
42
48
|
| --- | --- |
|
|
43
49
|
| `subagent` | Upstream subagent extension: delegates to specialized agents as separate `pi` processes, each started in tmux. |
|
|
44
|
-
| `tmux_run` | Runs a
|
|
50
|
+
| `tmux_run` | Runs a shell command on the host in tmux. Optionally wakes your session when it exits, or repeats it as a heartbeat. |
|
|
45
51
|
| `tmux_jobs` | Lists, tails, waits on, or stops this session's jobs. |
|
|
46
52
|
|
|
47
|
-
##
|
|
53
|
+
## Gondolin
|
|
54
|
+
|
|
55
|
+
`src/gondolin` is Pi's [`gondolin` example extension](https://github.com/earendil-works/pi/tree/main/packages/coding-agent/examples/extensions/gondolin), split into modules in this package's style. It behaves as the example does.
|
|
48
56
|
|
|
49
|
-
-
|
|
50
|
-
-
|
|
57
|
+
- Each Pi process boots one VM when its session starts and closes it when the session ends. A `subagent` worker is its own Pi process, so it gets its own VM.
|
|
58
|
+
- The directory Pi started in is mounted at `/workspace`. Writes there reach the host. Every other guest path is the VM's own filesystem, and changes there stay in the VM.
|
|
59
|
+
- The system prompt names `/workspace` as the working directory, so the model works in guest paths.
|
|
60
|
+
- A host path outside the working directory does not exist in the guest, except this package, which is mounted read-only at its host path so the model can `read` the skill files Pi names. The system prompt says so, and says which commands only the host has.
|
|
61
|
+
- The guest image ships `node` but not `git`, `gh`, `tmux`, or `bun`. Commands that need them run on the host through `tmux_run`.
|
|
62
|
+
- `tmux_run`, `tmux_jobs`, and the `pi` processes `subagent` starts run on the host, outside the VM.
|
|
51
63
|
|
|
52
64
|
## Replaces `@justjoshn/pi-pstack`
|
|
53
65
|
|
package/docs/guide/01-setup.md
CHANGED
|
@@ -14,18 +14,18 @@ The npm package `@justjoshn/pi-pstack-v2` is not published yet. Once it is, `pi
|
|
|
14
14
|
|
|
15
15
|
Add `--local` to write the declaration to the project's `.pi/settings.json` instead of your personal settings. `pi list` shows what is installed. Installing adds the skills and tools but starts no workflow. Nothing changes until you send `/skill:poteto-mode` or turn on `/pstack-mode`. Pi runs each skill as `/skill:<name>`, so every command in this guide takes that prefix.
|
|
16
16
|
|
|
17
|
-
The package adds three tools. `
|
|
17
|
+
The package adds three tools. `subagent` starts separate Pi workers, each in its own tmux session, and returns their reports when they finish. `tmux_run` runs a shell command in its own tmux session. `tmux_jobs` lists, waits on, and stops those shell jobs. Pi has no sub-agents and no detached shell, so every parallel worker in this guide is a `subagent` worker and every watcher is a `tmux_run` job.
|
|
18
18
|
|
|
19
|
-
**Watch your
|
|
19
|
+
**Watch your jobs.** `tmux_jobs` with `action: "list"` shows each job and prints a `tail -f` command that follows its output. Use `output` to read a job's log and `wait` to block until jobs finish. Use `stop` to end one. When a job exits, its report arrives in your session as a steering message after the current tool calls finish, so you can keep working or end your turn and wait.
|
|
20
20
|
|
|
21
|
-
## Check tmux and
|
|
21
|
+
## Check tmux and Gondolin
|
|
22
22
|
|
|
23
23
|
pstack needs two things on your machine.
|
|
24
24
|
|
|
25
25
|
- **tmux.** Every job runs in a tmux session, and the wake that brings a finished job's report back to your session depends on it.
|
|
26
|
-
- **
|
|
26
|
+
- **QEMU, for Gondolin.** Pi has no permission popups. Pi's built-in tools run inside a Gondolin micro-VM instead, with the directory Pi started in mounted at `/workspace`. Writes there reach your checkout, and every other guest path is the VM's own. Install QEMU (`brew install qemu` on macOS). Gondolin downloads its guest image on first use, and `/gondolin` shows the VM.
|
|
27
27
|
|
|
28
|
-
The
|
|
28
|
+
The VM covers Pi's own tools, not `tmux_run` jobs, which run on your machine. The guest has no `git` or `gh`, so commits, pushes, and PRs go through `tmux_run`. To contain everything, run Pi inside an isolated environment, as Pi's guide to isolated environments describes. Do that before you run anything unattended.
|
|
29
29
|
|
|
30
30
|
## Pick your models
|
|
31
31
|
|
|
@@ -43,7 +43,7 @@ The defaults are the same as the `large` budget. Code, prose, and judgment run a
|
|
|
43
43
|
|
|
44
44
|
You only override what you care about. A role with no line in the file keeps the skill's default. To restore a default, delete that role's line. A rerun of `/skill:setup-pstack` keeps any role whose model differs from the default. When a default changes, a file written before the change still pins the old default until you run `/skill:setup-pstack` again. That run replaces the old defaults it recognizes, tells you which, and keeps your other choices. To drop a pin it does not recognize, delete that role's line or the file first.
|
|
45
45
|
|
|
46
|
-
You might be wondering what happens if you want a role to follow whatever model you're using. Set it to `inherit-parent` or `auto` and pstack omits the model on that role's `
|
|
46
|
+
You might be wondering what happens if you want a role to follow whatever model you're using. Set it to `inherit-parent` or `auto` and pstack omits the model on that role's `subagent` call, so the worker runs on your session model. Both values mean the same thing, and neither is a model. For a panel role the value is a list, and one spawned Pi runs per entry, so the list length sets the panel size. Setup also configures `swarm workers`, the default model for every `/skill:swarm` worker unless a race names a model for each arm.
|
|
47
47
|
|
|
48
48
|
## Accept the verification offers, or don't
|
|
49
49
|
|
|
@@ -125,7 +125,7 @@ A long chat accumulates context from the last task. When you change subjects, sa
|
|
|
125
125
|
|
|
126
126
|
## Give parallel work its own worktree
|
|
127
127
|
|
|
128
|
-
If you run several agents against one repository on one computer, they will fight over the working tree, the ports, and the build output. The cleanest isolation is a git worktree per worker. A spawned Pi started with a `worktree` branch gets its own checkout, and its
|
|
128
|
+
If you run several agents against one repository on one computer, they will fight over the working tree, the ports, and the build output. The cleanest isolation is a git worktree per worker. A spawned Pi started with a `worktree` branch gets its own checkout, and its Gondolin VM mounts only that checkout, so it can install dependencies, run your app, and record video of the result without touching your working tree. A worktree does not isolate ports, so two workers that start the same dev server still collide. Give each its own port. The coordinator does this on its own for parallel code work. You can also ask for a worktree up front:
|
|
129
129
|
|
|
130
130
|
```text
|
|
131
131
|
/skill:poteto-mode new task. branch off <base> in a fresh worktree, then port the parser change there.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Run work while you sleep
|
|
2
2
|
|
|
3
|
-
This is the payoff for everything before it. An agent you can trust to verify its own work is an agent you can leave alone with a hard task. What makes that safe isn't hope. It's a checkable finish condition, an isolated worktree inside a
|
|
3
|
+
This is the payoff for everything before it. An agent you can trust to verify its own work is an agent you can leave alone with a hard task. What makes that safe isn't hope. It's a checkable finish condition, an isolated worktree inside a VM, and a decision log you audit in the morning.
|
|
4
4
|
|
|
5
5
|

|
|
6
6
|
|
|
@@ -33,7 +33,7 @@ Walk through what each line buys you:
|
|
|
33
33
|
- "fresh worktree off `<base>`" keeps the run from colliding with anything else you have open.
|
|
34
34
|
- "don't ask me before committing" pre-answers the permission the agent would otherwise block on.
|
|
35
35
|
- The heartbeat is a `tmux_run` job, not a pstack skill. A watcher runs with a `wake` message and wakes your session when it exits. A timer runs `sleep <seconds>` with `repeat: true`, and each tick wakes the session with the tick prompt. The [Autonomous run playbook](../../skills/poteto-mode/playbooks/autonomous-run.md) uses both to re-check the finish condition on events or on a timer. Stop a heartbeat with `tmux_jobs` and `action: "stop"`.
|
|
36
|
-
- The
|
|
36
|
+
- The Gondolin VM is the permission model. Pi has no permission popups, so Pi's tools reach only the directory each Pi started in. `tmux_run` jobs run on your machine, so run the main session in an isolated environment too, as the [setup page](./01-setup.md#check-tmux-and-gondolin) says.
|
|
37
37
|
- The escape hatch lets it stop at a genuine dead end and write up why, which beats eight hours of creative goal reinterpretation.
|
|
38
38
|
|
|
39
39
|
Because you'll review this work after stepping away, `/skill:poteto-mode` routes it through [`/skill:figure-it-out`](../../skills/figure-it-out/SKILL.md), which designs the run's phases before any code and wires in the decision log.
|
|
@@ -94,7 +94,7 @@ A whole program, such as a migration across many packages, has no playbook of it
|
|
|
94
94
|
|
|
95
95
|
## Run many projects in parallel
|
|
96
96
|
|
|
97
|
-
A coordinator session is the Project. It doesn't write code. It directs spawned Pis, each in its own worktree and
|
|
97
|
+
A coordinator session is the Project. It doesn't write code. It directs spawned Pis, each in its own worktree and VM, and each one wakes the coordinator with its report when it exits. Run the coordinator inside an isolated environment, as Pi's guide to isolated environments describes, so it can sit through the night. Start your prompts to the coordinator with `/skill:poteto-mode`, and the Pis it spawns follow the playbooks. Each Pi it starts reads [`worker.md`](../../skills/poteto-mode/worker.md) first, so workers hold to the kickoff's bar, decide reversible calls instead of asking you, and open PRs ready for review.
|
|
98
98
|
|
|
99
99
|
A few habits help:
|
|
100
100
|
|
package/docs/pi-mechanisms.md
CHANGED
|
@@ -9,34 +9,34 @@ Pi skips sub-agents, permission popups, plan mode, built-in to-dos, and backgrou
|
|
|
9
9
|
| Pi rule | What pstack does |
|
|
10
10
|
| --- | --- |
|
|
11
11
|
| Spawn Pi instances via tmux. | The packaged `subagent` tool starts each delegated `pi` in its own tmux session (upstream subagent example, with the process launch switched from `child_process.spawn` to tmux). |
|
|
12
|
-
| No permission popups. Run in a sandbox. |
|
|
12
|
+
| No permission popups. Run in a sandbox. | The packaged `gondolin` extension, Pi's own `gondolin` example, runs `read`, `write`, `edit`, `bash`, `ls`, `find`, `grep`, and `!` shell commands inside a Gondolin micro-VM. The directory Pi started in is mounted at `/workspace`, and writes there reach the host. Every other guest path is the VM's own. |
|
|
13
13
|
| No plan mode. Write plans to files. | A plan is a Markdown file, such as `plans/<slug>.md`. The human reviews the file. |
|
|
14
14
|
| No built-in to-dos. Use a TODO.md file. | Each checklist pstack used to keep in a todo tool lives in `TODO.md` at the root of the checkout you work in, as `- [ ]` and `- [x]` lines. It is working state, so never stage it. When the checkout already tracks a `TODO.md`, the checklist is `.pi/TODO.md`. |
|
|
15
15
|
| No background bash. Use tmux. Full observability, direct interaction. | Watchers, dev servers, long builds, and heartbeat ticks run through `tmux_run`. Nothing uses `&`, `nohup`, `setsid`, or `disown`. Every job is a tmux session you can attach to with the command `tmux_jobs` `list` prints. Its output shows there as it is written, and Ctrl-C there stops it. A job reads no input, so a command that needs an answer typed runs in the root session. |
|
|
16
16
|
|
|
17
|
-
Pi's design principle for customizing is to pick the least powerful mechanism that meets the need. Skills carry all workflow text. The
|
|
17
|
+
Pi's design principle for customizing is to pick the least powerful mechanism that meets the need. Skills carry all workflow text. The extensions exist only for what a skill cannot do. `src/index.ts` starts tmux jobs, wakes the session when they exit, and puts the model-role lines into the system prompt. `src/subagent` starts workers. `src/gondolin` runs Pi's tools in a VM.
|
|
18
18
|
|
|
19
19
|
## Vocabulary
|
|
20
20
|
|
|
21
21
|
| Cursor or Claude Code | Pi |
|
|
22
22
|
| --- | --- |
|
|
23
|
-
| Subagent, `Task` call, delegate, worker | A Pi instance started with `
|
|
24
|
-
| `subagent_type: "poteto-agent"`, `"comment-sicko"`, `"ci-watcher"`, `"thermo-nuclear-code-quality-review"` |
|
|
25
|
-
| `subagent_type: generalPurpose`, `"shell"`, `"explore"` |
|
|
26
|
-
| `readonly: true` (Ask mode) |
|
|
27
|
-
| `readonly: false` (agent mode) |
|
|
28
|
-
| `environment: "cloud"`, Cursor cloud agent, `cloud_base_branch` | `
|
|
29
|
-
| `environment: "local"` | Omit `
|
|
30
|
-
| `run_in_background: true` |
|
|
31
|
-
| Spawn N in one message |
|
|
32
|
-
| Nested subagents, launched by a subagent |
|
|
33
|
-
| `resume` an agent | `
|
|
34
|
-
| Steer or stop a running agent | `
|
|
35
|
-
| Wait for agents |
|
|
23
|
+
| Subagent, `Task` call, delegate, worker | A Pi instance started with the `subagent` tool. Call it a worker, a subagent, or by its role (explorer, reviewer, runner). |
|
|
24
|
+
| `subagent_type: "poteto-agent"`, `"comment-sicko"`, `"ci-watcher"`, `"thermo-nuclear-code-quality-review"` | A subagent call with `agent: "<name>"`. The role text comes from `agents/<name>.md`. |
|
|
25
|
+
| `subagent_type: generalPurpose`, `"shell"`, `"explore"` | A subagent call with `agent: "worker"`, which has every editing tool and no role prompt, or `agent: "scout"` for read-only work. Use `agent: "poteto-agent"` only for a poteto-mode delegate whose brief names poteto-mode's path. |
|
|
26
|
+
| `readonly: true` (Ask mode) | A subagent call with `agent: "scout"`, which has no edit or write tool. MCP and shell stay available, so a reviewer that needs MCP can still be read-only. Its `bash` can still write, and the network stays open. A scout can still change remote state with `gh`, `curl`, or an MCP tool, so the brief says what it must not change. When the role needs another agent, the brief says the worker must not edit. |
|
|
27
|
+
| `readonly: false` (agent mode) | An agent with edit and write tools, such as `poteto-agent`. |
|
|
28
|
+
| `environment: "cloud"`, Cursor cloud agent, `cloud_base_branch` | Before the call, create a worktree on the host with `tmux_run` running `git worktree add -b <branch> .pi/worktrees/<slug> <ref>`, inside the working directory so the VM can edit it. Then pass that path as the subagent call's `cwd`. Cursor cloud agents start from the repository's default branch, so name the default branch as `<ref>` to start from it. |
|
|
29
|
+
| `environment: "local"` | Omit `cwd`. The worker runs in your working directory. |
|
|
30
|
+
| `run_in_background: true` | A subagent call with a wake message. It returns a job id at once and wakes you with the message and the report when every worker finishes. Without one, the call blocks until its workers finish and returns their reports. |
|
|
31
|
+
| Spawn N in one message | One `subagent` call with `tasks`, up to 8 tasks run 4 at a time. Use a `chain` when each step needs the last one's output, and `{previous}` in a task is the prior step's output. |
|
|
32
|
+
| Nested subagents, launched by a subagent | A worker loads the same extensions, so it has `subagent`, `tmux_run`, and `tmux_jobs` too. Keep to one level, which every pstack workflow fits. |
|
|
33
|
+
| `resume` an agent | Not available. Each worker runs `pi` with no session. A fix round goes to a fresh worker, and passing the prior worker's worktree as `cwd` keeps its uncommitted state. |
|
|
34
|
+
| Steer or stop a running agent | `subagent` with `stop: "<job id>"` for a wake job, or abort a blocking call, then give a fresh worker consolidated scope. A print-mode Pi takes no mid-run input. |
|
|
35
|
+
| Wait for agents | A blocking `subagent` call returns when its workers finish. A wake job wakes you, so end your turn and let the wake arrive. `tmux_jobs` `wait` is for a short wait on named `tmux_run` jobs. A worker running in print mode waits for its own `tmux_run` jobs and wake jobs before it finishes. |
|
|
36
36
|
| `file_attachments` | List the paths in the brief. |
|
|
37
|
-
| `model` slug such as `claude-opus-5-5-xhigh` or `grok-4.7-xhigh-fast` | `
|
|
37
|
+
| `model` slug such as `claude-opus-5-5-xhigh` or `grok-4.7-xhigh-fast` | `subagent` `model: "<provider>/<id>"` and `thinking: "<level>"`. Thinking levels are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. A call's model and thinking override the agent's and the session's. Pi has no fast variant, so a "fast" choice is dropped. |
|
|
38
38
|
| `~/.cursor/rules/pstack-models.mdc`, `~/.claude/rules/pstack-models.md` | `~/.pi/agent/pstack-v2-models.md`, written by `/skill:setup-pstack`. The extension shows its role lines to the model in a `pstack-models` system-prompt section. A role with no line, or a line of `inherit-parent` or `auto`, runs on the session model, so omit `model`. |
|
|
39
|
-
| A model slug the Task tool rejects | A model
|
|
39
|
+
| A model slug the Task tool rejects | A worker that fails because its model is not valid. Only `provider/id` values that `pi --list-models` prints work, which are the models Pi holds credentials for. An omitted model runs on the session model. |
|
|
40
40
|
| Open a todolist, `TodoWrite` | Write `TODO.md`. |
|
|
41
41
|
| Custom Mode (Option+Enter on a slash skill) | `/pstack-mode <skill>`. The extension puts the skill in a `pstack-mode` system-prompt section every turn and records the choice on the session branch, so it survives `/compact`, resume, and `/tree`. `/pstack-mode off` ends it, and the footer shows the active mode. |
|
|
42
42
|
| `AskQuestion` (multiple-choice popup) | Ask in plain text with numbered options, then end your turn. Pi has no question popups. |
|
|
@@ -49,54 +49,36 @@ Pi's design principle for customizing is to pick the least powerful mechanism th
|
|
|
49
49
|
| `.cursor/skills/`, `~/.cursor/skills/` | `.pi/skills/`, `~/.pi/agent/skills/`, or the Agent Skills paths `.agents/skills/` and `~/.agents/skills/`. |
|
|
50
50
|
| `.cursor/rules/*.mdc`, always-applied rules | `AGENTS.md` (project) or `~/.pi/agent/AGENTS.md` (user). |
|
|
51
51
|
| `~/.cursor/plugins/`, `.cursor-plugin/plugin.json`, `/add-plugin` | A Pi package: `pi install <source>`, listed by `pi list`. |
|
|
52
|
-
| Cursor chat transcripts in `~/.cursor/projects/<slug>/agent-transcripts/` | Pi sessions in `~/.pi/agent/sessions/--<cwd with / as ->--/*.jsonl`.
|
|
52
|
+
| Cursor chat transcripts in `~/.cursor/projects/<slug>/agent-transcripts/` | Pi sessions in `~/.pi/agent/sessions/--<cwd with / as ->--/*.jsonl`. Workers run with no session, so they keep none. The extension names the current session's file in a `pstack-session` system-prompt section, and a brief that asks a worker to read it carries that path, because a worker cannot find it by itself. |
|
|
53
53
|
| `/create-skill` | Write `SKILL.md` to Pi's skills spec (Agent Skills format) and check it loads with `/skill:<name>`. |
|
|
54
54
|
| Cursor Automations, routines, webhook wakes, `SendToUser` | A tmux job that runs `pi -p` against a session, or Pi's RPC mode. Secrets come from environment variables the user sets, never from chat. Upstream's dormant benny pack (Slack issue triage, then reproduce-and-fix) runs only on that service, so this package does not ship it. |
|
|
55
55
|
| Cursor canvas | A self-contained HTML file opened in the browser. |
|
|
56
56
|
| Cursor Bugbot, agentic security review | Unchanged. They are GitHub reviewers whose comments any harness reads from the forge. |
|
|
57
57
|
| Cursor's built-in PR tool | `gh`. |
|
|
58
58
|
| MCP tools | Pi's built-in MCP (`pi mcp list`, `~/.pi/agent/mcp.json`, `.pi/mcp.json`) and Codemode (`"defaultTools": ["+codemode"]` in settings). Workers get a copy of your settings, so they have the same MCP servers and Codemode. |
|
|
59
|
-
| Cursor's agent store, project store, project tracker | Files in the checkout: `decisions.tsv` and `plans/`. A worker keeps its `decisions.tsv` in its
|
|
59
|
+
| Cursor's agent store, project store, project tracker | Files in the checkout: `decisions.tsv` and `plans/`. A worker keeps its `decisions.tsv` in its `cwd`, where the root reads it. |
|
|
60
60
|
| Orchestrate's `notes.md` | A file at the checkout root, never staged, like `TODO.md`. |
|
|
61
61
|
| Origin (`origin pr`) | Kept as is when `command -v origin` succeeds and Origin resolves the repository, otherwise `gh`. Graphite is never required. |
|
|
62
|
-
| Hold or stand-down order to running agents
|
|
63
|
-
| A lane that needs a simulator, `open`, a local display or socket, or auth that exists only on this machine | Run it
|
|
62
|
+
| Hold or stand-down order to running agents Each worker commits a `wip:` checkpoint, then the `subagent` call is aborted, and a fresh worker releases the hold. |
|
|
63
|
+
| A lane that needs a simulator, `open`, a local display or socket, or auth that exists only on this machine | Run it on the host through `tmux_run`, since Pi's own `bash` runs in the Gondolin VM. |
|
|
64
64
|
|
|
65
|
-
##
|
|
65
|
+
## Gondolin details
|
|
66
66
|
|
|
67
|
-
-
|
|
68
|
-
-
|
|
69
|
-
-
|
|
70
|
-
-
|
|
71
|
-
-
|
|
72
|
-
-
|
|
73
|
-
- `cwd` must be inside the session's project, which is the git top level or else the session cwd, or a linked worktree of the same repository. A checkout of another repository is refused even when it sits inside the project, since the job would be handed that repository's git directory. No writable path may contain Pi's agent directory. The model cannot widen its own sandbox by naming another directory.
|
|
74
|
-
- Paths an unsandboxed process later executes from stay read-only even inside a writable checkout. Those are the git `hooks/`, `config`, `config.worktree`, and `info/` entries, a configured `core.hooksPath`, and the code entries of every `.pi` directory in the checkout at any depth: `extensions`, `settings.json`, `mcp.json`, and installed packages in `npm` and `git`. Editor and agent-harness configuration also stays read-only at any depth, since editors and agent harnesses run its tasks, hooks, and MCP servers unsandboxed when you open the checkout: `.vscode`, `.idea`, `*.code-workspace`, `.cursorignore`, and every entry of `.cursor` and `.claude` apart from their instruction directories `rules`, `commands`, `worktrees`, `skills`, and `agents`, which a job may still write. Git finds hooks through `.git`, every `.git` pointer file such as a submodule's, every linked worktree's `commondir`, `gitdir`, and `config.worktree`, and submodule git directories, so all of those stay read-only. Every existing directory above a protected path, and `.git` itself, cannot be renamed or replaced. A protected path that is a symlink is guarded at the link as well as its target.
|
|
75
|
-
- Code can still appear where none was at launch, because a job can rename a directory it built into place or link a parent elsewhere, and bubblewrap cannot bind what does not exist. At launch the root records every protected path, `.pi` code entry, editor or harness entry, and `.git` entry in the checkout. When the job exits or is stopped, the unsandboxed wrapper sweeps the checkout and moves anything new of those kinds into the job's `quarantine/` directory, and the job's output says so. The sweep never follows a link, and a `.pi` symlink you already had is left alone. Moving, not deleting, keeps a file you created yourself during the job recoverable. On macOS, Seatbelt also denies writing those paths anywhere in the checkout.
|
|
76
|
-
- Jobs never write your Pi agent directory, your `auth.json` included. Each top-level job gets its own agent directory, through Pi's `PI_CODING_AGENT_DIR`, shared by every job it starts. It links to your configuration, holds `settings.json` with its local package paths anchored to your real agent directory, and holds a copy of your credentials. In it a job may write only the contents of that copy and Pi's lock directories, so no job can change what another job's Pi loads. On Linux it is a throwaway tmpfs view, so other writes there vanish with the job.
|
|
77
|
-
- Pi runs an `auth.json` key that starts with `!` as a command, so the credentials copy holds no command. For a worker's own provider, the root resolves the command once when it starts the worker and puts the resulting key in the copy. Every two seconds, and once more after a job ends, the root carries refreshed OAuth tokens between your `auth.json` and each copy, the later expiry winning, under Pi's lock on both. Only OAuth tokens move, so nothing a job writes as a key or a command reaches your `auth.json`, and a provider you logged out of is never brought back.
|
|
78
|
-
- A job cannot reach the services that would start a process for it. It can neither connect to nor serve a Unix socket, so every tmux server, Docker's socket, the session bus, and every other local service are out of reach. Socket pairs, which child processes use for pipes, still work. macOS denies binding and connecting Unix sockets apart from DNS's, and Linux refuses opening one through a seccomp filter, which also refuses io_uring. On macOS it also cannot use LaunchServices (`open`), Apple Events, launchd, or preference writes, and it can signal only processes in its own sandbox. On Linux `/run` and the user's runtime directory are hidden, and the job runs in its own PID namespace.
|
|
79
|
-
- When a job exits, its whole process group is killed before cleanup, so no child it left behind acts after cleanup. Stopping a job sends TERM, then KILL after three seconds. On Linux every process in its PID namespace dies with it.
|
|
80
|
-
- A Pi worker's own jobs get their own sandbox, so `readonly` holds at any depth, and a resumed worker keeps its `readonly`. On every platform a sandboxed worker writes the job as a request in its `nested/` directory, and the root Pi launches it under a profile built from the paths it validated. The root refuses any request that would write, or run, outside what it granted the top-level worker, so no worker can hand a descendant more than it was given. The root writes results only under the top-level job, never into a worker's directory, and serves requests while it runs. A worker's sandbox keeps `.git/worktrees` read-only, so when a worker passes `worktree` to `pi_spawn`, its request carries the branch and base, and the root creates the worktree from the worker's own checkout before it launches the job. The checkout lands in the job's results directory, `<top-level job>/brokered/<hash>/worktree`, which no worker can write, so no worker can swap in a link for git to check out through. The root creates it only for a worker that may write the repository and only at that path, computes the checkout's protected paths itself, keeps a `readonly` job read-only, creates nothing for a request it refuses, and removes the worktree and any branch it created when it cannot launch the job. If you quit the root Pi, nested requests wait until you resume that session.
|
|
81
|
-
- Start the main session sandboxed too when you want it contained. Pi's guide to isolated environments lists the methods, and not all of them need Docker.
|
|
67
|
+
- `src/gondolin` is Pi's `gondolin` example extension, split into modules. It behaves as the example does, and `test/gondolin.test.ts` pins that behavior without booting QEMU.
|
|
68
|
+
- Each Pi process boots one VM when its session starts and closes it at shutdown. Tool calls made while it boots wait for the same VM. A worker that `subagent` starts is its own Pi process, so it gets its own VM, mounted on its own working directory.
|
|
69
|
+
- Paths map to the guest the same way for every tool. A relative path, or a host path inside the working directory, lands under `/workspace`. Any other absolute path names that path in the guest's own filesystem.
|
|
70
|
+
- The system prompt's working-directory line names `/workspace` and the host directory it comes from.
|
|
71
|
+
- `/gondolin` shows the VM id, the host and guest workspaces, and the shell. Commands run in `bash` when the guest has it, and in `/bin/sh` otherwise.
|
|
72
|
+
- QEMU must be installed. Gondolin downloads its guest image on first use.
|
|
82
73
|
|
|
83
|
-
## What
|
|
74
|
+
## What Gondolin does not cover
|
|
84
75
|
|
|
85
|
-
-
|
|
86
|
-
- A
|
|
87
|
-
-
|
|
88
|
-
-
|
|
89
|
-
-
|
|
90
|
-
- On Linux a job takes Pi's credential lock in its own throwaway view, so a job refreshing a token and the root syncing that copy at the same moment can lose that refresh. pstack refreshes a worker's credentials just before starting it, so this needs a worker to outlive its token.
|
|
91
|
-
- A job can leave a fake rebase in progress in the git directory, whose steps run if you then run `git rebase --continue`.
|
|
92
|
-
- A print-mode run waits for every job it started with a wake message, so one that never exits keeps it running.
|
|
93
|
-
- On macOS a job cannot run `ps` or `top`, so it reads the load with `uptime`. A bash here-document fails in a checkout the job cannot write, such as a readonly worker's, so the job changes to `$TMPDIR` first or writes with `printf`.
|
|
94
|
-
- Cargo and Maven caches are not redirected to the job's private temp directory, so their downloads fail inside a job.
|
|
95
|
-
- Until a job exits, a protected path it created by rename or link still exists, and an unsandboxed process started in that checkout during the job could use it.
|
|
96
|
-
- On macOS a job process that detaches into its own session with `setsid` survives `stop` and keeps its sandbox rights, still inside its sandbox. It can keep writing what the job could write, including a protected path after cleanup ran. The credential check still reverts any command key it plants. Linux has no such gap, because the PID namespace ends every process.
|
|
97
|
-
- A job can hold the lock on its credentials copy, which pauses token sync for that job until it ends.
|
|
98
|
-
- A job's agent directory is read-only apart from its credentials copy and locks, so Pi state a worker would write there does not persist from a worker. That covers an MCP OAuth refresh in `mcp-auth.json`, a model catalog refresh, and package installs. An OAuth MCP server may need a login from the root session first, since a worker cannot save a refreshed token.
|
|
76
|
+
- `tmux_run` jobs, and the `pi` processes `subagent` starts, run on the host. Only Pi's built-in tools run in the VM. A `/workspace` path does not exist on the host, so give `tmux_run` paths relative to the working directory.
|
|
77
|
+
- A host path outside the working directory does not exist in the guest, except this package. The package root is mounted read-only at its host path, so a `SKILL.md`, playbook, or principle that Pi or a skill names by its host path can be read, and writes to it fail. The system prompt names the boundary and points at `tmux_run` and `tmux_jobs` `output` for the rest.
|
|
78
|
+
- The guest image ships `node` but not `git`, `gh`, `tmux`, or `bun`, so the model's `bash` cannot commit, push, or open a PR. Run those through `tmux_run`.
|
|
79
|
+
- A linked worktree's `.git` file points at a git directory outside the mount, so git in the guest cannot use it even after you install git there.
|
|
80
|
+
- Writes under `/workspace` reach the host as they are made. The VM keeps no copy to roll back.
|
|
99
81
|
|
|
100
82
|
## Jobs on disk
|
|
101
83
|
|
|
102
|
-
Each job lives in `~/.pi/agent/pstack-v2/jobs/<id>/`: `job.json` (the spec), `
|
|
84
|
+
Each `tmux_run` job lives in `~/.pi/agent/pstack-v2/jobs/<id>/`: `job.json` (the spec), `wrapper.sh`, `wrapper.pid`, `output.log`, and `exit`. The tmux wrapper writes `output.log` and `exit`. Each spawning session runs its own tmux server on a socket in `/tmp/pstack-v2-<uid>/`, named from a hash of the session id. `tmux_jobs` `list` prints a `tail -f` command to follow each job's output and a `tmux attach` command for each running job. A wake is claimed once through a `woken` marker file, so restarting Pi never delivers a report twice.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@justjoshn/pi-pstack-v2",
|
|
3
|
-
"version": "0.1
|
|
4
|
-
"description": "Use the pstack skills and workflow in Pi, with the upstream subagent tool spawning Pi in tmux
|
|
3
|
+
"version": "0.2.1",
|
|
4
|
+
"description": "Use the pstack skills and workflow in Pi, with the upstream subagent tool spawning Pi in tmux, shell jobs running in tmux, and Pi's tools running in a Gondolin micro-VM.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"repository": {
|
|
@@ -27,7 +27,8 @@
|
|
|
27
27
|
"pi": {
|
|
28
28
|
"extensions": [
|
|
29
29
|
"./src/index.ts",
|
|
30
|
-
"./src/subagent/index.ts"
|
|
30
|
+
"./src/subagent/index.ts",
|
|
31
|
+
"./src/gondolin/index.ts"
|
|
31
32
|
],
|
|
32
33
|
"skills": [
|
|
33
34
|
"./skills"
|
|
@@ -52,6 +53,7 @@
|
|
|
52
53
|
"vitest": "5.1.0"
|
|
53
54
|
},
|
|
54
55
|
"dependencies": {
|
|
56
|
+
"@earendil-works/gondolin": "0.14.0",
|
|
55
57
|
"zod": "^4"
|
|
56
58
|
}
|
|
57
59
|
}
|
package/skills/arena/SKILL.md
CHANGED
|
@@ -14,18 +14,18 @@ Every candidate gets the same prompt, so the prompt is the contract.
|
|
|
14
14
|
|
|
15
15
|
1. State the artifact each candidate is producing.
|
|
16
16
|
2. Derive the rubric, 3-6 concrete gradeable criteria for what success looks like on *this* task. It is the picker's tool in Phase D. Candidates only see the task.
|
|
17
|
-
3. Pick the runners from the `arena runners` line in the `pstack-models` system-prompt section. Each entry is a `provider/id` model and a thinking level. If that line is missing, every runner runs on the session model, so omit `model`, and the arena is one model sampled N times. Say so plainly and never present it as a diverse panel. An `auto` or `inherit-parent` entry is the session model, so omit `model` for it. If `
|
|
18
|
-
4. Give each candidate its own output location (a git worktree where possible, otherwise a directory inside the project that you pass as `cwd`). A worker cannot write shared `/tmp`. For a worktree,
|
|
17
|
+
3. Pick the runners from the `arena runners` line in the `pstack-models` system-prompt section. Each entry is a `provider/id` model and a thinking level. If that line is missing, every runner runs on the session model, so omit `model`, and the arena is one model sampled N times. Say so plainly and never present it as a diverse panel. An `auto` or `inherit-parent` entry is the session model, so omit `model` for it. If a runner fails because its model is not valid (`pi --list-models` prints valid ones), rerun that seat on the session model or drop it, keep at least two runners, and say so. Families go by the model id, not the provider, and the longest matching prefix wins: `claude-fable-*`, `claude-*`, and `gemini-*`. Any other model's family is its id before the first hyphen, such as `gpt` or `glm`. Spawn more runners for multiple design directions, and repeat one model when the work is generation-bound, not judgment-sensitive. Pick each worker's `thinking` level for the job, per the Spawned Pi workers section of the **poteto-mode** skill.
|
|
18
|
+
4. Give each candidate its own output location (a git worktree where possible, otherwise a directory inside the project that you pass as `cwd`). A worker cannot write shared `/tmp`. For a worktree, first run `git worktree add -b arena-<slug>-<n> .pi/worktrees/arena-<slug>-<n> <ref>` on the host with `tmux_run`, inside the working directory so the VM can edit it, and pass that path as the runner's `cwd`. The worker commits its output there, per the **separate-before-serializing-shared-state** principle skill.
|
|
19
19
|
|
|
20
20
|
## Phase B: Fan out
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
Start all N workers in one `subagent` call with one `tasks` entry per runner and `agent: "worker"`, each with the task, the path to the shared grounding, its own output path, and instructions to produce the artifact and a short rationale naming the alternatives it considered and what it rejected.
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
The call returns when every runner finishes, with their reports. If a candidate produces no output, proceed with N-1 and note the dropout.
|
|
25
25
|
|
|
26
26
|
## Phase C: Cross-judge
|
|
27
27
|
|
|
28
|
-
After all Phase B candidates complete,
|
|
28
|
+
After all Phase B candidates complete, start one judge with `subagent` and `agent: "scout"`, from the `arena cross-judge pool` line in the `pstack-models` system-prompt section. The judge is never from the session model's vendor. A vendor is a family as Phase A step 3 defines families, except that `claude-fable-*` and `claude-*` are one vendor. Use the first entry from another vendor. An `auto` or `inherit-parent` entry is the session model, so it never judges. If you do not know the session model, use the first entry and say that the vendor check did not run. If that line is missing, or every entry from another vendor fails because its model is not valid, skip the judge, pick the base alone in Phase D, and say so. While you read in Phase D, the judge scores each candidate, by path label, on each rubric criterion and recommends a base. Its brief says it must not edit any candidate.
|
|
29
29
|
|
|
30
30
|
## Phase D: Pick a base
|
|
31
31
|
|
|
@@ -26,9 +26,9 @@ Update mode changes the rest of the flow:
|
|
|
26
26
|
|
|
27
27
|
### 1. Mine their history
|
|
28
28
|
|
|
29
|
-
Locate the active workspace's sessions before fanning out. They are the `*.jsonl` files in `~/.pi/agent/sessions/--<cwd with / as ->--/` (unless `sessionDir` or `$PI_CODING_AGENT_SESSION_DIR` moves sessions)
|
|
29
|
+
Locate the active workspace's sessions before fanning out. They are the `*.jsonl` files in `~/.pi/agent/sessions/--<cwd with / as ->--/` (unless `sessionDir` or `$PI_CODING_AGENT_SESSION_DIR` moves sessions). A `subagent` worker runs with no session, so its report appears only as a tool result there. Use only that directory. Don't glob across `~/.pi/agent/sessions/*/`. That crosses workspace boundaries and reads private chats from unrelated projects.
|
|
30
30
|
|
|
31
|
-
Survey recent agent conversations within that scope for recurring patterns.
|
|
31
|
+
Survey recent agent conversations within that scope for recurring patterns. Start parallel Pi workers in one `subagent` call with `tasks` and `agent: "scout"` across slices of history (e.g. last 2-4 weeks, split into 3 slices so each has enough material). Pick each worker's model and thinking level for the job, per the Spawned Pi workers section of the **poteto-mode** skill. Each slice mining worker reads sessions from the workspace-scoped path the brief names, looks for the signals below, and returns a short structured list of patterns it saw with evidence pointers. Default signals worth hunting:
|
|
32
32
|
|
|
33
33
|
- Response preferences (length, tone, format, "dumb it down" corrections)
|
|
34
34
|
- Delegation habits (spawned workers, models, specialized workflows, parallelism)
|
|
@@ -14,7 +14,7 @@ For a quick ballpark the user asked for, one run is enough. Still check question
|
|
|
14
14
|
|
|
15
15
|
- Write down the claim you expect to make, in the words you would ship ("export is 30% faster at p50 on the 60k-row dataset"). The questions test that sentence.
|
|
16
16
|
- Read the measurement script. Note what it times, counts, and ignores.
|
|
17
|
-
- Check the load average with `uptime` and the core count with `nproc`. If the machine is busy, find out what is running. If you cannot stop it, interleave the sides so both see the same noise, and say so in the report.
|
|
17
|
+
- Check the load average with `uptime` and the core count with `nproc`. If the machine is busy, find out what is running. If you cannot stop it, interleave the sides so both see the same noise, and say so in the report. Pi's bash runs in the Gondolin VM, which sees only the guest's load and processes, so read the host's from a `tmux_run` job.
|
|
18
18
|
|
|
19
19
|
## The questions
|
|
20
20
|
|
|
@@ -105,6 +105,6 @@ If the CLI needs richer terminal control, use `pty.fork()` or an existing PTY li
|
|
|
105
105
|
|
|
106
106
|
- Prefer deterministic waits over sleeps. If you must sleep, explain why.
|
|
107
107
|
- Do not send credentials or destructive commands into a controlled session.
|
|
108
|
-
- Keep the harness in `$TMPDIR`
|
|
108
|
+
- Keep the harness in `$TMPDIR` unless the repo already has a testing/demo harness.
|
|
109
109
|
- Do not hard-code paths from another repository. Adapt commands to the current repo's scripts and runtime.
|
|
110
110
|
- Clean up tmux sessions, temp dirs, inspector processes, and demo artifacts unless the user asks to keep them.
|
|
@@ -30,7 +30,7 @@ Decompose into atomic, independently-landable units. Sequence riskiest-unknown-f
|
|
|
30
30
|
|
|
31
31
|
- Build the verification harness before the work, with the baseline captured from the pre-change state, so the check reads as "old value vs new value".
|
|
32
32
|
- For one-way-door design decisions, run the **architect** skill (it runs **arena**). Skip it for mechanical work whose shape is already concrete. A second arena over a settled design is over-engineering (the **laziness-protocol** principle skill).
|
|
33
|
-
- Decide what fans out. Parallelize only across seams, and give each worker its own worktree, with `
|
|
33
|
+
- Decide what fans out. Parallelize only across seams, and give each worker its own worktree, created on the host with `tmux_run` running `git worktree add -b <branch> .pi/worktrees/<slug> <ref>` inside the working directory and passed as `cwd` (the **separate-before-serializing-shared-state** principle skill). Don't over-fan. Start the workers with one `subagent` call with `tasks` and `agent: "poteto-agent"`, and pick its `thinking` level for the job, per the Spawned Pi workers section of the **poteto-mode** skill.
|
|
34
34
|
- Write the designed phase list down. That list is what the human reviews.
|
|
35
35
|
|
|
36
36
|
Then execute the design. Add its steps to `TODO.md` as concrete items between the Phase C and Phase D entries. Run each under the Phase C loop discipline, and weave the Phase D log through them, a row as each step lands, rather than saving the whole trail for the end.
|
package/skills/how/SKILL.md
CHANGED
|
@@ -12,10 +12,10 @@ If the scope is ambiguous, state your interpretation and explore. The user can r
|
|
|
12
12
|
|
|
13
13
|
## 1. Explain
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
Start one worker with `subagent`, `agent: "scout"`, and no `model`, so it runs on the session model and explores and explains in one pass. It must not change any file. Give it the user's question and this brief:
|
|
16
16
|
|
|
17
17
|
> You are writing an architectural explanation for a senior engineer. Explore the codebase and write an explanation that a senior engineer unfamiliar with this area could read and walk away with a solid mental model. They should understand the architecture well enough to start working in it confidently. You have read-only access to the codebase.
|
|
18
18
|
|
|
19
19
|
## 2. Present
|
|
20
20
|
|
|
21
|
-
When
|
|
21
|
+
When the call returns its report, present that report. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it.
|
|
@@ -16,13 +16,13 @@ The scope is what the user names. Otherwise it is the branch diff from its merge
|
|
|
16
16
|
|
|
17
17
|
## Fan out
|
|
18
18
|
|
|
19
|
-
Run Phase A steps 3 and 4 and Phase B of the **arena** skill, with four changes. Read the `interrogate reviewers` line in place of `arena runners`. A worktree
|
|
19
|
+
Run Phase A steps 3 and 4 and Phase B of the **arena** skill, with four changes. Read the `interrogate reviewers` line in place of `arena runners`. A new worktree holds no uncommitted changes. Write the scope's uncommitted diff to a file inside the project (for example `git diff HEAD > .interrogate/scope.patch`, left untracked), name its path in each brief, and tell the adversary to `git apply` it first. Give each adversary its own worktree from the base ref, as arena step 4 creates it, and pass it as `cwd`. Start the adversaries in one `subagent` call with `tasks` and `agent: "worker"`. In place of the arena task and rationale, give each adversary the scope, the intent, and this brief:
|
|
20
20
|
|
|
21
21
|
> Break this change. Prove each finding with a run against the real code, such as a failing test, a repro script, or command output that shows the wrong behavior. For a design or plan, run a prototype or probe the current tree. Keep repros in your own worktree. Report each finding with a title, the exact command, the output it printed, and the output the intent requires. Leave out anything you did not run. That covers style, naming, structure, and risks that need a future change to matter. No findings is a valid result.
|
|
22
22
|
|
|
23
23
|
## Verify
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
The call returns when every adversary finishes, with their reports.
|
|
26
26
|
|
|
27
27
|
Verify each finding per arena Phase F by rerunning its command. Keep a finding when the output shows the failure and the failure breaks the intent. Drop the rest. Merge findings that share a root cause.
|
|
28
28
|
|
|
@@ -26,7 +26,7 @@ Only edit the verification skill's own directory (its SKILL.md, features/, and a
|
|
|
26
26
|
|
|
27
27
|
1. **Index hygiene.** Read the feature map README and glob its sibling files. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory.
|
|
28
28
|
|
|
29
|
-
2. **Source wave.** One
|
|
29
|
+
2. **Source wave.** One `agent: "scout"` worker per feature file, all started in one `subagent` call with `tasks` so they run concurrently. Each explains "how does this user-facing feature work?" from source, flags likely doc drift with citations, and returns one concise live-verification recipe. Workers never drive the app and never edit files. The call returns when every worker finishes, with their reports. Return shape: feature summary / source entry points / likely drift or none / one recipe.
|
|
30
30
|
|
|
31
31
|
3. **Reconcile.** Every feature file has a returned summary. Merge overlapping recipes into as few app states as practical. Spot-check cited drift; don't re-prove clean claims. Sweep recent churn for user-facing surfaces missing from the map — require a concrete source path before calling one missing.
|
|
32
32
|
|
|
@@ -23,13 +23,13 @@ Write `bot.md` in that directory. It is the prompt every wake sends before the e
|
|
|
23
23
|
|
|
24
24
|
## Choose how the bot wakes
|
|
25
25
|
|
|
26
|
-
The bot is a Pi session stored in the UI's directory
|
|
26
|
+
The bot is a Pi session stored in the UI's directory. On each POST the server runs:
|
|
27
27
|
|
|
28
28
|
```
|
|
29
29
|
pi -p --session-dir <ui dir>/session --session-id <slug> @<ui dir>/bot.md "<event>"
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
-
`--session-id` opens the session if it exists and creates it otherwise, so the first wake and every later wake use the same command. The event is the JSON text the browser sent, wrapped as in the last section. Run one wake at a time, so two clicks never write the session together.
|
|
32
|
+
`--session-id` opens the session if it exists and creates it otherwise, so the first wake and every later wake use the same command. The event is the JSON text the browser sent, wrapped as in the last section. Run one wake at a time, so two clicks never write the session together.
|
|
33
33
|
|
|
34
34
|
## Request secrets
|
|
35
35
|
|
|
@@ -18,7 +18,7 @@ Use the caller's files or diff. Otherwise use the current diff against the base
|
|
|
18
18
|
|
|
19
19
|
## Steps
|
|
20
20
|
|
|
21
|
-
1.
|
|
21
|
+
1. Start a worker with `subagent` and `agent: "comment-sicko"`. Pass the scope. Pick the worker's `thinking` level for the job, per the Spawned Pi workers section of the **poteto-mode** skill. Do not restate its rules.
|
|
22
22
|
2. Inspect its report and diff. Reject application-code edits, scope escapes, exception-protected deletions, misstated `MUST KILL` reasons, and flags that treat kept intentional code as guilty. Reshape flags on our-code surprises stay actionable. Do not restore those comments. A keep survives only with proof it is about something we cannot change. Audit missed scoped lint and TypeScript suppressions. Correctness or safety suppressions stay actionable `MUST KILL`s. Restore deletions only with exact exceptions and scoped proof. Before accepting thin `IMPORTANT` or `do not remove` kills or keeps, trace their symbol or run `/skill:why` on it. If a kill is ambiguous, do not restore. If a keep is refuted or still ambiguous, delete it. Revert and rerun one rejected report with the failure named. Reject a second, report it open, and fail `/skill:no-comments`.
|
|
23
23
|
3. Fix trivial accepted flags directly by deleting a dead path, dropping a parameter, or using the real API. If any fix needs a shape, run `/skill:architect` once for the accepted set and surrounding code. Stop at the sketch. Architect shapes. Step 4 implements.
|
|
24
24
|
4. Implement the smallest root-cause fix in scope. Remove every named workaround. If the root cause is out of scope, land the smallest in-scope fix and report the rest open. The **principle-fix-root-causes** and **principle-redesign-from-first-principles** skills guide intent only. Neither authorizes widening the fence nor fixing instances outside it. Never bolt on symptom guards.
|
|
@@ -45,7 +45,7 @@ If cost is the worry, say where the tokens go and how to spend fewer. pstack spe
|
|
|
45
45
|
|
|
46
46
|
pstack was ported from Cursor and runs on Pi as a Pi package. [How pstack maps onto Pi](../../docs/pi-mechanisms.md) lists what each part uses.
|
|
47
47
|
|
|
48
|
-
Other tools can read the skills, because they use the Agent Skills format. But most workflow skills, including `/skill:poteto-mode`, `/skill:how`, and `/skill:teach`, spawn Pi workers with `
|
|
48
|
+
Other tools can read the skills, because they use the Agent Skills format. But most workflow skills, including `/skill:poteto-mode`, `/skill:how`, and `/skill:teach`, spawn Pi workers with `subagent`, some with per-role models, and watchers and heartbeats run through `tmux_run`. Those tools come from this package's extension, so those parts may not work elsewhere.
|
|
49
49
|
|
|
50
50
|
## Start a task with `/skill:poteto-mode`
|
|
51
51
|
|
|
@@ -53,7 +53,7 @@ Other tools can read the skills, because they use the Agent Skills format. But m
|
|
|
53
53
|
|
|
54
54
|
`/skill:poteto-mode` attaches the skill to one message, and it fades as the session moves on. To keep it on for the whole session, type `/pstack-mode poteto-mode` instead. That is pstack's Custom Mode. The skill rides in the system prompt every turn, survives `/compact`, and comes back when you resume the session. `/pstack-mode off` ends it. Any pstack skill works as a mode.
|
|
55
55
|
|
|
56
|
-
Point the user to Pi's skills documentation (`docs/skills.md` in the Pi package, or Pi's docs site) when this comes up. Mid-session, "new task" makes the skill match a fresh playbook. `/skill:poteto-mode` already uses `poteto-agent` for the workers its playbook steps spawn. To get the same style from a worker of your own,
|
|
56
|
+
Point the user to Pi's skills documentation (`docs/skills.md` in the Pi package, or Pi's docs site) when this comes up. Mid-session, "new task" makes the skill match a fresh playbook. `/skill:poteto-mode` already uses `poteto-agent` for the workers its playbook steps spawn. To get the same style from a worker of your own, start it with `subagent` and `agent: "poteto-agent"`.
|
|
57
57
|
|
|
58
58
|
## Pick a skill
|
|
59
59
|
|
|
@@ -138,7 +138,7 @@ Principles are one-rule skills that `/skill:poteto-mode` reads and cites in its
|
|
|
138
138
|
| A new model choice had no effect | The file from `/skill:setup-pstack` is read at the start of each turn. Send a new message, and check the role has a line in `~/.pi/agent/pstack-v2-models.md`. |
|
|
139
139
|
| Runs cost more than expected | See the cost paragraph under Get set up. |
|
|
140
140
|
| A skill didn't load on its own | Only `/skill:setup-pstack` loads from the user's words. The others load when the user types them or when `/skill:poteto-mode` runs them, and it doesn't run every skill. |
|
|
141
|
-
| Parallel workers overwrote each other | Give each worker its own worktree with
|
|
141
|
+
| Parallel workers overwrote each other | Give each worker its own worktree. Create it with `tmux_run` running `git worktree add -b <branch> .pi/worktrees/<slug> <ref>` inside the working directory, then pass that path as the worker's `cwd`. |
|
|
142
142
|
| An overnight run moved but finished nothing | A `tmux_run` heartbeat needs a check that can pass or fail, not a duration. See [guide page 7](../../docs/guide/07-overnight.md). |
|
|
143
143
|
| The reply claims success from a green build | Ask for the real command, flow, stored value, or profile. That's the prove-it-works principle. |
|
|
144
144
|
|