Skip to content
Open
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 .devin-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "pstack",
"version": "0.9.2",
"version": "0.10.0",
"platforms": ["local"],
"description": "Rigorous agent workflows for Devin CLI. Write less, higher quality code.",
"homepage": "https://github.com/athul-ramesh/ptstack-devin",
Expand Down
8 changes: 7 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,12 @@ The 0.2.0 release was verified against Devin CLI 3000.11.3 (9c803229faa4), local

Avoid installing two copies with the same plugin name. Devin may source-qualify inventory names while loading skills from an older copy; verify the path returned by the skill tool.

## Using 0.10.0

`/pstack:why` is a short cited read of commits and PR discussion. `/pstack:how` is one read-only `subagent_explore` pass. Poteto-mode traces the code itself. Teach and poteto-help still offer both skills. Recall starts one investigator per git or `gh` source.

`/pstack:setup-pstack` writes `# defaults: 2`. An older sheet drops the retired how and why roles. A `bug-fix` or `hillclimb` row that is still the old `pstack:poteto-agent-sonnet` default moves to `pstack:poteto-agent-opus` when `opus` is available. Any other choice stays. Profile `model:` pins are unchanged. Devin's docs do not publish the Cursor slugs `claude-fable-5-2-*`, `claude-opus-5-5-*`, or `gemini-4-carbon-*`, so those pins were not added. See the [0.15.42 port audit](docs/pstack-0.15.42-port-audit.md).

## Using 0.9.2

Ask `/pstack:poteto-help` with a setup or workflow question. This explicit-user skill answers with one suggested prompt and a source link. It does not start a task for a help question. A request to do work follows poteto-mode instead.
Expand All @@ -30,7 +36,7 @@ Invoke [`/pstack:ketchup`](skills/ketchup/SKILL.md) to catch up on this chat sin

The [usage guide](docs/usage-guide.md) covers prompting, investigation, prototypes before plans, real behavior verification, benchmark evidence, repeated-mistake enforcement, and bounded in-session delivery. The help skill includes [prompting guidance](skills/poteto-help/references/prompting.md) and [copyable recipes](skills/poteto-help/references/recipes.md).

Invoke [`/pstack:sharpen`](skills/sharpen/SKILL.md) on a prompt before you send it. The agent says what a top professional would add, the raw material and methods they would use, and an outside check, then hands back the rewritten prompt with your choices left open. It does not do the task. It runs only when requested.
Invoke [`/pstack:sharpen`](skills/sharpen/SKILL.md) on a prompt before you send it. The agent says what a top professional would add, the raw material and methods they would use, and an outside check, then hands back the rewritten prompt. The rewrite asks the agent to prototype a choice an experiment can settle and recommend from what it observed. Product and preference choices stay with you. It does not do the task. It runs only when requested.

Invoke [`/pstack:create-formal-verification-skill`](skills/create-formal-verification-skill/SKILL.md) when tests cannot reach the case that breaks a race, retry, state machine, parser, or unsafe code. It verifies one property with a tool that fits and runs on your machine, shows the check failing on a broken variant, and writes a project skill under `.devin/skills/` to recheck it. [`/pstack:maintain-formal-verification-skill`](skills/maintain-formal-verification-skill/SKILL.md) brings that verification back in line after the covered code changes. This plugin bundles no verifier; the agent asks before installing one.

Expand Down
2 changes: 1 addition & 1 deletion agents/comment-sicko/AGENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ That list is my only leash. When I am not sure a keep clause applies, the commen

`eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar suppressions stink. Read the surrounding code. If the rule 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. 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.
`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If the claim is not obvious there, I trace the named symbol with `read` and `grep`. I have no `exec`, so I do not claim to have read the PR. 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.

Expand Down
48 changes: 48 additions & 0 deletions docs/pstack-0.15.42-port-audit.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# Port pstack 0.15.42 to Devin

Audited on 2026-11-15 on top of `main` at `6e060b5`. PRs #11 (`ab1f702`, 0.8.0) and #13 (`c742dd6`, 0.9.1) are merged. Plugin version is 0.10.0.

## Source and coverage

Upstream range: [`c742dd6...bf0c7cd`](https://github.com/cursor/plugins/compare/c742dd61706fbacc1b95f1a20b7b988cf096ce6c...bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7) (`pstack/`, 0.15.36 to 0.15.42). The squash is [bf0c7cd](https://github.com/cursor/plugins/commit/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7) (PR #1236). `harness/pstack/claude-code` is the Claude Code mirror and was not ported.

| Upstream change | Devin disposition |
| --- | --- |
| Sharpen's last line asks the agent to prototype a choice an experiment can settle and recommend from what it observed. Product and preference choices stay with the user. | Already present in 0.9.2. README and the usage guide now describe that line. |
| Reflect synthesizer drift example is a function rename. | Adapted. The example is `readConfig` to `loadSettings` in `config.ts`. |
| Why is one short file. Investigators, synthesizer, model routing, output format, and `references/` are deleted. | Adapted. The body is one paragraph plus a Devin line to use `exec` for git and `gh`. It names no source catalog. The reference files are deleted. |
| Recall starts its own investigator per source. | Adapted. One `pstack:panel-opus` investigator each for git history and, when `gh` is authenticated, pull requests and issues. `subagent_explore` is not used, because that profile cannot run `gh`. `run_subagent` has no readonly flag, so the brief forbids writes. |
| Blast radius and teach stop pointing at removed why parts. | Adapted. Blast radius pulls the PR with git and `gh` and cites `file:line` itself. Teach still runs how and why, and no longer asks to narrow a sweep why no longer has. |
| How is one file that starts one read-only subagent. | Adapted. The profile is the documented built-in `subagent_explore`. Explorer, explainer, and critic prompts are deleted. |
| Poteto-mode no longer routes to how. Investigation, Feature, Bug fix, Hillclimb, Perf issue, Refactoring, architect, no-comments, and comment-sicko trace the code. | Adapted in those files. Comment-sicko traces with `read` and `grep` only. Its `allowed-tools` list has no `exec`, so it does not claim to have read the PR. |
| Teach and poteto-help keep how. | Kept. Help, prompting, and the usage guide describe the shorter skills. |
| Setup drops the two why roles and the two how roles. | Adapted. `how explorer`, `how explainer`, `why investigators`, and `why synthesizer` are dropped. `how critics` is dropped with them because the one-file how has no critic panel. |
| New default models, Fable as its own family and the same vendor as Claude, Grok 4.7 no longer a default, and a `# defaults: 2` marker that migrates old defaults. | Partial. See Models below. The marker is written. An unmarked sheet migrates `bug-fix` and `hillclimb` only when the row is still exactly `pstack:poteto-agent-sonnet` and `opus` is available. Other values stay. |
| Statechart SANY error text and parent-border Mermaid arrows. | Ported onto the checker this repo already ships. The drawing and the 40-line SANY section follow the upstream tests. |
| Benny automation tweaks. | Skipped. Benny is not part of this port. |

## Models

Checked [Devin CLI models](https://docs.devin.ai/cli/models), [Desktop models](https://docs.devin.ai/desktop/models) (pricing text dated 2026-11-09), and [Subagents](https://docs.devin.ai/cli/subagents) on 2026-11-15.

The CLI documents short aliases `opus`, `sonnet`, `swe`, `codex`, and `gemini`. A profile `model:` field takes an alias or an id the account allows. Desktop pricing names Claude Fable 5.2 with Low, Medium, High, XHigh, Max, and Fast Mode, and it names Gemini 4 Argon. It does not publish `claude-fable-5-2-max`, `claude-opus-5-5-xhigh`, `claude-opus-5-5-high-fast`, or `gemini-4-carbon-high`. The CLI page does not list `fable` as a short alias. Opus 5.5 is not named.

Shipped pins stay `gpt-6-1-sol-medium` (`opus` and `codex`), `glm-5-3-flash-high` (`sonnet`), and `swe`. No new profile was added.

Role routing that maps onto those pins:

- Feature, refactoring, bug-fix, perf-issue, and hillclimb use `pstack:poteto-agent-opus`. Bug-fix and hillclimb used to default to `sonnet`.
- Strongest judgment stays `pstack:panel-opus`. There is no documented Fable pin to put above it.
- Swarm workers and reflect tooling stay `pstack:panel-sonnet`. Upstream moved them to `claude-opus-5-5-high-fast`. This port has no second opus pin for that speed.
- Arena runners, architect runners, and interrogate reviewers stay `opus`, `swe`, and `sonnet`. The cross-judge pool stays `opus` and `swe`, compared by `model:` pin. Upstream's vendor rule (Fable and other Claude models are one vendor) is not applied, because no shipped pin is a documented Fable id or a Claude Opus 5.5 id.
- The setup budget ladder, `inherit-parent`, and `auto` stay out. `run_subagent` takes a profile, not an effort or a speed.

Grok 4.7 was never a default in this repo. The migration recognizes the old Devin profile rows, not a `grok-*` slug.

## Checks

- `node --test tests/*.test.mjs`: 56 passed.
- `git diff --check`: passes.
- `npm test --prefix skills/statechart/scripts` with TLC 1.7.4 on `TLA2TOOLS`: 373 passed, none skipped. That run includes the SANY line-and-column cases and the parent-border chart tests.

Native Devin activation of 0.10.0 is untested. `subagent_explore` as the how profile is taken from the subagents page and has not been run in this session.
6 changes: 6 additions & 0 deletions docs/release-notes.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
# Release notes

## 0.10.0

- Port upstream 0.15.37 through 0.15.42 (`bf0c7cd`). `/pstack:why` is one short file. `/pstack:how` is one read-only `subagent_explore` pass. Poteto-mode, the code playbooks, architect, no-comments, and comment-sicko trace the code. Teach and poteto-help still offer how. Recall starts its own investigator per git or `gh` source. Reflect's drift example is a function rename. Sharpen's prototype line was already on main in 0.9.2. The docs now say so.
- Setup writes `# defaults: 2`. An older sheet drops the retired how and why roles. Old default `bug-fix` and `hillclimb` rows move from `pstack:poteto-agent-sonnet` to `pstack:poteto-agent-opus` when `opus` is available. Other choices stay. Profile pins stay `gpt-6-1-sol-medium`, `glm-5-3-flash-high`, and `swe`. Cursor slugs for Fable 5.2, Opus 5.5, and Gemini 4 Carbon are not written. Swarm workers and reflect tooling stay on `sonnet`.
- Statechart reports SANY's own error section, capped at 40 lines, and draws an outside arrow to a parent state's border. Benny is not shipped. Native activation remains untested. See the [port audit](pstack-0.15.42-port-audit.md).

## 0.9.2

- Local drift fixes: declare `platforms: ["local"]` in `.devin-plugin/plugin.json` so the plugin loads only in Devin CLI and Devin Desktop. README and AGENTS.md say so explicitly. Restore sharpen prototype wording, obligatory `/pstack:unslop` and `/pstack:technical-writing` routing in poteto-mode, and ketchup `permissions.deny: [edit]`. Native activation remains untested.
Expand Down
4 changes: 2 additions & 2 deletions docs/usage-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Workers and review panels spend extra tokens. Choose suitable registered profile

For a noisy report, ask the agent to restate the underlying issue before sharing your theory of the cause. For an unclear cause, request evidence and hypotheses without code changes.

[`/pstack:how`](../skills/how/SKILL.md) traces mechanics. [`/pstack:why`](../skills/why/SKILL.md) finds reasons and history. [`/pstack:teach`](../skills/teach/SKILL.md) explains choices and tradeoffs in plain language. [`/pstack:recall`](../skills/recall/SKILL.md) uses this conversation, named Devin exports, and the shared record. Unavailable history stays an evidence gap.
[`/pstack:how`](../skills/how/SKILL.md) is one read-only explanation of how code works. During a change, poteto-mode traces the code itself. [`/pstack:why`](../skills/why/SKILL.md) cites the commits and PR discussion. [`/pstack:teach`](../skills/teach/SKILL.md) explains choices and tradeoffs in plain language. [`/pstack:recall`](../skills/recall/SKILL.md) uses this conversation, named Devin exports, and one investigator per git or `gh` source. Unavailable history stays an evidence gap.

For a captured profile, use [Trace forensics](../skills/poteto-mode/playbooks/trace-forensics.md). For a live leak, CPU spin, or glitch, use [Runtime forensics](../skills/poteto-mode/playbooks/runtime-forensics.md). Both produce diagnosis before a fix.

Expand Down Expand Up @@ -72,7 +72,7 @@ The help skill's [prompting reference](../skills/poteto-help/references/promptin

Use `/pstack:in-your-own-words` to hear the goals and problem the agent understood. This explicit-user skill restates them without starting a workflow or adding a confirmation gate.

Use `/pstack:sharpen <the prompt you're about to send>` when you are unsure a prompt is aimed right. It hands back the prompt rewritten deeper, not bigger, with an outside check and your choices left open. It does not do the task. Send the rewrite yourself.
Use `/pstack:sharpen <the prompt you're about to send>` when you are unsure a prompt is aimed right. It hands back the prompt rewritten deeper, not bigger, with an outside check. The rewrite asks the agent to prototype a choice an experiment can settle and recommend from what it observed. Product and preference choices stay with you. It does not do the task. Send the rewrite yourself.

Use `/pstack:ketchup` to catch up since your previous message. The story stays under 100 words. Every call waiting on you gets its own bullet with its link, what it changes, the evidence, the risk, and a pick, including older unresolved decisions, so a large batch makes a long reply instead of a cut list. Existing captures and available diagrams show status and before/after options. When the Devin host cannot render them, compact text includes the same facts and unknowns. The skill does not start an app, install a renderer, or post anything to produce a visual.

Expand Down
4 changes: 2 additions & 2 deletions skills/architect/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Open a todolist with one entry per phase.

## Phase A: Ground

Build a real model of every system the new code touches. Invoke `/pstack:how` over those subsystems. Critique mode when existing structure is the constraint. Naming a file is not grounding. Produce the architectural explanation how prescribes. If the design redefines ownership or layering, also invoke `/pstack:why` so the rationale is a constraint.
Build a real model of every system the new code touches. Trace those subsystems with `read`, `grep`, and `glob`. Naming a file is not grounding. Write what the system is, how the pieces move, where they live, and the traps. If the design redefines ownership or layering, also invoke `/pstack:why` so the rationale is a constraint.

Skip Phase A only for genuine greenfield work.

Expand Down Expand Up @@ -70,7 +70,7 @@ A few edge cases do not condemn a design.

When you scrap:

1. Invoke `/pstack:how` over what was built.
1. Trace what was built.
2. Redesign as if the new constraints were day-one assumptions. Read `skills/principle-redesign-from-first-principles/SKILL.md`.
3. Subtract first. Read `skills/principle-subtract-before-you-add/SKILL.md`. The new sketch starts smaller.
4. Return to Phase B.
Expand Down
4 changes: 2 additions & 2 deletions skills/blast-radius/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,10 @@ Any safety fact you can't get to step 4, say so out loud. Don't write it up as s

## Steps

1. Read the change. The diff, the symbols it adds, changes, and deletes, and what it now does differently, including the part the diff doesn't spell out. Invoke `/pstack:why` when you need PR and commit evidence.
1. Read the change. The diff, the symbols it adds, changes, and deletes, and what it now does differently, including the part the diff doesn't spell out. Pull the PR and its commits with `exec` git and `gh` when that record matters.
2. Find the one fact it's safe because of. Most changes that look scary are safe because of a single fact, like "this call only drops already-dead cache entries and does nothing else". Find that fact. If it holds, most of the scary cases die at once. Spend your time here, not on a long list of maybes.
3. Look where grep stops. Read the source of the library you call, and check its pinned version and any local patch. Work out when things run: microtasks, unmount and teardown, Solid versus React. Follow what a symbol search misses: the JSON an API returns, a DB column, a wire format, another language reading the same bytes, a feature flag, code three hops downstream.
4. Be honest about each risk. Give it a real chance of happening and a real cost if it does. Keep the risks you confirmed. List the ones you checked and cleared separately. Same citation rules as `/pstack:why`. Cite a real `file:line`. A search that finds nothing is still an answer. Never make up a caller or an API.
4. Be honest about each risk. Give it a real chance of happening and a real cost if it does. Keep the risks you confirmed. List the ones you checked and cleared separately. Cite a real `file:line`. A search that finds nothing is still an answer. Never make up a caller or an API.
5. Prove the one fact. Write a script or test that runs the real code. `exec` it. Paste what happened. If you can't prove it cheaply, mark it unproven. Don't round up.
6. For a big or wide change, invoke `/pstack:arena`. Ask several profiles the same question and merge the answers. Sequential when distinct profiles are fewer than needed. Say so.

Expand Down
Loading