Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ Tell operators plugin-link only:

- Install host via https://omp.sh/install if needed.
- From this package root: `omp plugin link ./`
- Later sessions, any cwd: type `/` (`/skill:ps-…`, sticky `/poteto-mode`)
- Later sessions, any cwd: type `/` (`/skill:do-…`, sticky `/poteto-mode`)
- Do not marketplace. Do not copy `pstack.ts` into `~/.omp/agent/extensions/`.
- Do not keep a repo `.omp/skills` symlink. Sibling `skills/` is what plugin-link discovers.

Expand Down
16 changes: 8 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# pstack

This package is an installable omp **plugin**. From the package root, one-time `omp plugin link ./`. Later sessions (any cwd): start `omp`, type `/` (`/skill:ps-…`, sticky `/poteto-mode`). Sibling `skills/` at the package root is what omp auto-discovers after link.
This package is an installable omp **plugin**. From the package root, one-time `omp plugin link ./`. Later sessions (any cwd): start `omp`, type `/` (`/skill:do-…`, sticky `/poteto-mode`). Sibling `skills/` at the package root is what omp auto-discovers after link.

It is not the Cursor plugin and not an official Cursor port.

Expand All @@ -16,7 +16,7 @@ Those pages are the Cursor product. This README does not retell them.

## Docs

- [The pstack guide](./docs/guide/README.md) — original numbered product tutorial (setup through recipes, plus images). On-disk skill links use `skills/ps-*`; slash skills are `/skill:ps-…`. `/poteto-mode` stays unprefixed.
- [The pstack guide](./docs/guide/README.md) — original numbered product tutorial (setup through recipes, plus images). On-disk skill links use `skills/do-*`; slash skills are `/skill:do-…`. `/poteto-mode` stays unprefixed.

## Automations

Expand Down Expand Up @@ -45,15 +45,15 @@ cd pstack
omp plugin link ./
```

That one-time link is how later sessions (any cwd) type `/` (`/skill:ps-…`, sticky `/poteto-mode`). Confirm with `omp plugin list`.
That one-time link is how later sessions (any cwd) type `/` (`/skill:do-…`, sticky `/poteto-mode`). Confirm with `omp plugin list`.

Do not copy only `pstack.ts` into `~/.omp/agent/extensions/`.

## First steps

1. Install omp from https://omp.sh (`curl -fsSL https://omp.sh/install | sh`).
2. Clone this repository and, from the package root, `omp plugin link ./` (see Load this plugin). Later sessions (any cwd): `omp`, then type `/`.
3. `/poteto-mode` — enable sticky Poteto Mode for this conversation. Optional task arguments are passed through; this also sends `/skill:ps-poteto-mode`.
3. `/poteto-mode` — enable sticky Poteto Mode for this conversation. Optional task arguments are passed through; this also sends `/skill:do-poteto-mode`.
4. Work as usual. Resume an on conversation and it stays on. `/new` starts off.
5. `/poteto-mode off` (aliases: `disable`, `stop`) — disable this conversation.

Expand All @@ -65,14 +65,14 @@ The TUI status reads `pstack: poteto mode` when on. Other omp surfaces may not s

| Command | What it does |
|---|---|
| `/poteto-mode` | Enable sticky Poteto Mode for this conversation. Also sends `/skill:ps-poteto-mode`. |
| `/poteto-mode` | Enable sticky Poteto Mode for this conversation. Also sends `/skill:do-poteto-mode`. |
| `/poteto-mode off` | Disable this conversation. Aliases: `disable`, `stop`. |

That is the live extension command. It stays unprefixed. There is no worktree command. No `hooks/` tree. No `src/` tree. No Cursor marketplace APIs.

## Poteto Mode (this extension)

- Enable sends `/skill:ps-poteto-mode`. The `/skill:ps-poteto-mode` input hook also persists enabled.
- Enable sends `/skill:do-poteto-mode`. The `/skill:do-poteto-mode` input hook also persists enabled.
- Stored as a custom `pstack-mode` entry on that conversation’s session jsonl. Last `{enabled}` wins. Missing means off.
- `session_start` re-reads the jsonl. `new_session` / `/new` starts off. Resume of an on conversation stays on.
- When on, a prompt needle prepends “Pstack Poteto Mode is on…”
Expand All @@ -82,9 +82,9 @@ That is the live extension command. It stays unprefixed. There is no worktree co

## Skills

Files under `skills/` are markdown prompts. Invoke them with `/skill:ps-<name>`. They are live after `omp plugin link ./` (sibling tree auto-discovered). They are not live omp functions or CLIs.
Files under `skills/` are markdown prompts. Invoke them with `/skill:do-<name>`. They are live after `omp plugin link ./` (sibling tree auto-discovered). They are not live omp functions or CLIs.

Examples: `/skill:ps-create-verification-skill`, `/skill:ps-swarm`, `/skill:ps-principle-build-the-lever`. Feature Map is a section in `ps-create-verification-skill`, not a runner. Do not treat Feature Map, swarm, or Build the Lever as functions or CLIs.
Examples: `/skill:do-create-verification-skill`, `/skill:do-swarm`, `/skill:do-principle-build-the-lever`. Feature Map is a section in `do-create-verification-skill`, not a runner. Do not treat Feature Map, swarm, or Build the Lever as functions or CLIs.

## License

Expand Down
4 changes: 2 additions & 2 deletions automations/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ Dormant Benny pack: Slack issue triage plus reproduce/fix. Not a slash-skill tre

## Local Contracts

- `SKILL.md` files here are automation instructions. Do not add this directory to `package.json` `omp.skills`. Do not prefix them as `ps-*` slash skills.
- `SKILL.md` files here are automation instructions. Do not add this directory to `package.json` `omp.skills`. Do not prefix them as `do-*` slash skills.
- Cursor host: copy to `.cursor/automations/benny/`, enable pstack in `.cursor/settings.json`, create live automations with `/automate`.
- omp host: copy or run in-repo after `omp plugin link ./`; shared skills are `/skill:ps-…`. omp has no Slack-triggered Cursor Automations equivalent (HOST GAP in `benny/README.md`).
- omp host: copy or run in-repo after `omp plugin link ./`; shared skills are `/skill:do-…`. omp has no Slack-triggered Cursor Automations equivalent (HOST GAP in `benny/README.md`).

## Work Guidance

Expand Down
2 changes: 1 addition & 1 deletion automations/benny/FOR_AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ if the host is **omp**:

- there is no slack-triggered cursor automations equivalent: no `/automate`, no automations editor, no platform-managed slack event that starts an agent on a new top-level report.
- copy this pack into the target repository at `.cursor/automations/benny/` (same destination so a later cursor host can pick it up), or run it from this in-repo `automations/benny/` tree.
- shared dependencies on omp are `/skill:ps-how`, `/skill:ps-why`, `/skill:ps-tdd`, `/skill:ps-unslop`, and the `ps-principle-*` skills after `omp plugin link ./`. do not add this pack to `package.json` `omp.skills`.
- shared dependencies on omp are `/skill:do-how`, `/skill:do-why`, `/skill:do-tdd`, `/skill:do-unslop`, and the `do-principle-*` skills after `omp plugin link ./`. do not add this pack to `package.json` `omp.skills`.
- when a report arrives, read and follow the committed operational files directly in an omp session. unattended slack-triggered runs need cursor automations or an operator-hosted slack listener. do not invent a slack poller in the pstack factory.

## what i want to automate
Expand Down
4 changes: 2 additions & 2 deletions automations/benny/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

benny gives you two automations for slack issue reports. one triages each report. the other reproduces confirmed bugs and may prepare a small draft fix.

the files in this directory are dormant setup and automation sources. they do not appear as slash skills. do not add them to `package.json` `omp.skills` or expect `/skill:ps-setup-benny`.
the files in this directory are dormant setup and automation sources. they do not appear as slash skills. do not add them to `package.json` `omp.skills` or expect `/skill:do-setup-benny`.

## HOST GAP

Expand Down Expand Up @@ -38,5 +38,5 @@ keep this path when the consuming repo still uses Cursor:
2. point the agent at [`FOR_AGENTS.md`](./FOR_AGENTS.md) and name the target repository.
3. merge this whole directory into the target at `.cursor/automations/benny/` (same destination as Cursor, so a later Cursor Automations host can pick it up) or keep using this in-repo pack.
4. preserve destination-only files and review conflicts. keep user-owned configuration outside the pack, for example `.cursor/benny/` or `.omp/benny/`.
5. shared pstack skills on omp are `/skill:ps-how`, `/skill:ps-why`, `/skill:ps-tdd`, `/skill:ps-unslop`, and the `ps-principle-*` skills. they load from this clone after `omp plugin link ./`. do not register benny `SKILL.md` files as slash skills.
5. shared pstack skills on omp are `/skill:do-how`, `/skill:do-why`, `/skill:do-tdd`, `/skill:do-unslop`, and the `do-principle-*` skills. they load from this clone after `omp plugin link ./`. do not register benny `SKILL.md` files as slash skills.
6. there is no `/automate` and no Automations editor. after the pack and secret-free config are committed, run `skills/triage-issue-reports/SKILL.md` and `skills/reproduce-and-fix-issues/SKILL.md` directly in an omp session when a report arrives.
22 changes: 11 additions & 11 deletions automations/benny/skills/setup-benny/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ disable-model-invocation: true

Benny ships as a dormant automation pack inside pstack. The plugin manifest exposes only pstack's normal skill root; this file and the two operational files are not slash skills.

On this omp fork, `/skill:ps-…` is the slash surface. Do not add this directory to `package.json` `omp.skills`. Shared dependencies resolve as `ps-how`, `ps-why`, `ps-tdd`, `ps-unslop`, and the `ps-principle-*` skills.
On this omp fork, `/skill:do-…` is the slash surface. Do not add this directory to `package.json` `omp.skills`. Shared dependencies resolve as `do-how`, `do-why`, `do-tdd`, `do-unslop`, and the `do-principle-*` skills.

## HOST GAP (omp)

Expand Down Expand Up @@ -53,16 +53,16 @@ Preserve every unrelated top-level setting and every other plugin entry. If `plu

Reload the target project or start a fresh agent rooted there. Verify that these shared pstack skills resolve from project scope:

- `how` (omp: `/skill:ps-how`)
- `why` (omp: `/skill:ps-why`)
- `tdd` (omp: `/skill:ps-tdd`)
- `unslop` (omp: `/skill:ps-unslop`)
- `principle-separate-before-serializing-shared-state` (omp: `/skill:ps-principle-separate-before-serializing-shared-state`)
- `principle-minimize-reader-load` (omp: `/skill:ps-principle-minimize-reader-load`)
- `principle-guard-the-context-window` (omp: `/skill:ps-principle-guard-the-context-window`)
- `principle-sequence-verifiable-units` (omp: `/skill:ps-principle-sequence-verifiable-units`)
- `principle-fix-root-causes` (omp: `/skill:ps-principle-fix-root-causes`)
- `principle-prove-it-works` (omp: `/skill:ps-principle-prove-it-works`)
- `how` (omp: `/skill:do-how`)
- `why` (omp: `/skill:do-why`)
- `tdd` (omp: `/skill:do-tdd`)
- `unslop` (omp: `/skill:do-unslop`)
- `principle-separate-before-serializing-shared-state` (omp: `/skill:do-principle-separate-before-serializing-shared-state`)
- `principle-minimize-reader-load` (omp: `/skill:do-principle-minimize-reader-load`)
- `principle-guard-the-context-window` (omp: `/skill:do-principle-guard-the-context-window`)
- `principle-sequence-verifiable-units` (omp: `/skill:do-principle-sequence-verifiable-units`)
- `principle-fix-root-causes` (omp: `/skill:do-principle-fix-root-causes`)
- `principle-prove-it-works` (omp: `/skill:do-principle-prove-it-works`)

Do not count a skill loaded from the current session or a user-scoped plugin. The check must show that a fresh agent in the target repository receives pstack through project settings.

Expand Down
4 changes: 2 additions & 2 deletions docs/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,12 @@ Human docs for this omp plugin. First-run is the README (`omp plugin link ./`).

- README owns first-run: `omp plugin link ./`. Do not add `docs/getting-started.md` or teach `omp -e` as an install path.
- README may link the numbered guide.
- Guide on-disk skill links use `skills/ps-*` so they resolve in this tree. Slash names in guide prose may still say `/how`; the live surface is `/skill:ps-how`. `/poteto-mode` stays unprefixed.
- Guide on-disk skill links use `skills/do-*` so they resolve in this tree. Slash names in guide prose may still say `/how`; the live surface is `/skill:do-how`. `/poteto-mode` stays unprefixed.
- Operator install matches the root rail Native omp contract.

## Work Guidance

Port guide pages and images from upstream. Remap `../../skills/<name>/` to `../../skills/ps-<name>/`. Agents tell operators plugin-link.
Port guide pages and images from upstream. Remap `../../skills/<name>/` to `../../skills/do-<name>/`. Agents tell operators plugin-link.

## Verification

Expand Down
4 changes: 2 additions & 2 deletions docs/guide/01-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,15 +20,15 @@ Run:
/setup-pstack
```

[`/setup-pstack`](../../skills/ps-setup-pstack/SKILL.md) detects the models you have access to, shows you each role (code delegates, judgment, the review panels), and asks what you want. Answer the questions. It writes `~/.cursor/rules/pstack-models.mdc`, a small rule every pstack skill reads.
[`/setup-pstack`](../../skills/do-setup-pstack/SKILL.md) detects the models you have access to, shows you each role (code delegates, judgment, the review panels), and asks what you want. Answer the questions. It writes `~/.cursor/rules/pstack-models.mdc`, a small rule every pstack skill reads.

You only override what you care about. A role with no line in the rule keeps the skill's default. To restore a default later, delete that role's line, or just run `/setup-pstack` again.

You might be wondering what happens if you use Auto. Set a role to `inherit-parent` or `auto` and pstack omits the subagent `model` field, so the subagent inherits your parent chat model. Both values mean the same thing, and neither is a model slug. For a panel role the value is a list, and one subagent runs per entry, so the list length sets the panel size. Setup also configures `swarm workers`, the default model for every `/swarm` worker unless a race names a model for each arm.

## Accept the verification offer, or don't

At the end of setup, `/setup-pstack` looks for a way to prove app behavior in your project, either a `verify-*` skill or an existing harness. If it finds neither, it offers once to generate one with [`/create-verification-skill`](../../skills/ps-create-verification-skill/SKILL.md).
At the end of setup, `/setup-pstack` looks for a way to prove app behavior in your project, either a `verify-*` skill or an existing harness. If it finds neither, it offers once to generate one with [`/create-verification-skill`](../../skills/do-create-verification-skill/SKILL.md).

Say yes and it writes `.cursor/skills/verify-<app>/`, a project-local skill that teaches agents to drive your app the way a user does. It proves the skill works once before handing it over. Say no and setup moves on. You can run `/create-verification-skill` yourself any time. [Verify and ship](./06-verify-and-ship.md#create-a-project-verification-skill) covers when it earns its place.

Expand Down
10 changes: 5 additions & 5 deletions docs/guide/02-poteto-mode.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ flowchart TD
J --> K
```

The diagram shows the common routes. There are also playbooks for hillclimbing a metric, diagnosing runtime symptoms and captured traces, prototypes, visual parity, authoring and evaluating skills, autonomous runs, babysitting a PR or stack to merge-ready, shipping a verified stack, running a PR queue on autopilot, orchestrating project-scale programs, session pickup, pausing safely, multi-phase plans, and worktree cleanup. The [playbook directory](../../skills/ps-poteto-mode/playbooks/) has the full set.
The diagram shows the common routes. There are also playbooks for hillclimbing a metric, diagnosing runtime symptoms and captured traces, prototypes, visual parity, authoring and evaluating skills, autonomous runs, babysitting a PR or stack to merge-ready, shipping a verified stack, running a PR queue on autopilot, orchestrating project-scale programs, session pickup, pausing safely, multi-phase plans, and worktree cleanup. The [playbook directory](../../skills/do-poteto-mode/playbooks/) has the full set.

## Say the goal, not the ceremony

Expand Down Expand Up @@ -71,15 +71,15 @@ If you run several agents against one repository, they will fight over the worki
/poteto-mode new task. branch off <base> in a fresh worktree, then port the parser change there.
```

Each task in its own branch and worktree means no agent stomps another's files. The [Opening a PR playbook](../../skills/ps-poteto-mode/playbooks/opening-a-pr.md) already works from a worktree for code changes, so mostly you only say this when a specific base or location matters.
Each task in its own branch and worktree means no agent stomps another's files. The [Opening a PR playbook](../../skills/do-poteto-mode/playbooks/opening-a-pr.md) already works from a worktree for code changes, so mostly you only say this when a specific base or location matters.

Worktrees accumulate. When disk gets tight, ask:

```text
/poteto-mode what's eating my disk? prune the worktrees that are safe to prune.
```

The [Worktree cleanup playbook](../../skills/ps-poteto-mode/playbooks/worktree-cleanup.md) classifies every worktree by merge state, uncommitted work, and which chats still touch it. It deletes only what that evidence clears and pauses for your call on anything holding uncommitted work.
The [Worktree cleanup playbook](../../skills/do-poteto-mode/playbooks/worktree-cleanup.md) classifies every worktree by merge state, uncommitted work, and which chats still touch it. It deletes only what that evidence clears and pauses for your call on anything holding uncommitted work.

## Leave it running

Expand All @@ -89,10 +89,10 @@ When you step away, say what done means and go:
/poteto-mode im stepping away. keep going until the migration check reports zero old callers. log your decisions.
```

Work you'll review later routes through [`/figure-it-out`](../../skills/ps-figure-it-out/SKILL.md), which designs the run's phases and keeps a [`/show-me-your-work`](../../skills/ps-show-me-your-work/SKILL.md) decision log. [Run work while you sleep](./07-overnight.md) covers the full overnight contract.
Work you'll review later routes through [`/figure-it-out`](../../skills/do-figure-it-out/SKILL.md), which designs the run's phases and keeps a [`/show-me-your-work`](../../skills/do-show-me-your-work/SKILL.md) decision log. [Run work while you sleep](./07-overnight.md) covers the full overnight contract.

**Pitfall:** don't enumerate skills in your prompt ("use /how, then /architect, then /arena..."). The playbook already sequences them, and a hand-written sequence usually reorders or drops steps the playbook would have kept. Name a skill only when you want to override a specific choice.

Read [`poteto-mode`](../../skills/ps-poteto-mode/SKILL.md) itself for the full routing rules.
Read [`poteto-mode`](../../skills/do-poteto-mode/SKILL.md) itself for the full routing rules.

Next: [Understand the code](./03-understand.md).
Loading
Loading