pi-pstack-adapter 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project are documented here. release-please writes new entries from Conventional Commit PR titles.
+
+## [0.3.0](https://github.com/elderfo/pi-pstack-adapter/compare/v0.2.0...v0.3.0) (2026-10-05)
+
+
+### Features
+
+* certify native Windows support ([#5](https://github.com/elderfo/pi-pstack-adapter/issues/5)) ([0ebcd76](https://github.com/elderfo/pi-pstack-adapter/commit/0ebcd76d0c24e8918ac16bdf2bda8672fe154e30))
+
+## [0.2.0] - 2026-10-05
+
+### Added
+
+- Certify pstack `0.15.9` at commit `e43c7ee26e0038c6c1fa8380dd34ce86ff94cb2a`. The adapter now registers 50 upstream skills.
+- Classify the three skills new in this revision. `principle-explain-the-number` is `native`. `correct` is `dependency-gated` on `git`. `benchmark-checklist` is `dependency-gated` on `uptime` and `nproc`, because macOS has no `nproc` without GNU coreutils.
+- Map the role values `auto` and `inherit-parent` in the host mapping. Both mean the subagent runs on the parent model. The mapping now names which upstream role lines correspond to adapter roles, such as `hardest tasks` to `strongest-judgment`. The model slug examples now name the current upstream defaults.
+
+### Fixed
+
+- Regenerate cached wrappers when the host mapping text changes. Before this fix, an edit to the mapping did not change the cache key, so a cached revision kept serving the old mapping.
+- Derive the skill count in `npm run test:isolated` from the certified revision instead of a literal.
+
+## [0.1.0] - 2026-09-24
+
+### Added
+
+- Run Cursor's official pstack plugin in Pi from an unmodified upstream checkout. The adapter downloads a pinned pstack revision, never edits it, and generates Pi skill wrappers and agent definitions from it. This release certifies pstack `0.15.2` at commit `6ed0f7a9504f577d7529064103cecce9be7dfc5e`.
+- 47 upstream skills plus an adapter-owned status workflow, registered under the configurable `pistack` namespace as `/skill:pistack-*`.
+- Both upstream pstack agents, registered with the installed delegation provider as `pistack-comment-sicko` and `pistack-poteto-agent`.
+- Support tiers (`native`, `adapted`, `dependency-gated`, `experimental`, `unsupported`) published in each generated skill's frontmatter and in the status report, so no workflow claims verification it does not have.
+- `/pistack-status`, `/pistack-check <skill>`, and `/pistack-mode on|off|status` commands, plus a `pstack_adapter` tool the agent can call for status, prerequisite checks, model listing, role assignment, and upstream source selection.
+- Automatic activation of the `subagent` tool when a delegating pstack workflow starts. The adapter makes the same tool selection as `subagents_enable`. It does this for a `/skill:` command, for a model-initiated read of the skill's `SKILL.md`, and on each prompt while Poteto Mode is on. Delegating wrappers also tell the model to call `subagents_enable` if `subagent` is still missing.
+- Capability detection for delegation and structured questions by tool shape rather than package name, with `pi-subagents` and `pi-ask-user` as the recommended providers and an actionable report when either is absent.
+- Upstream source overrides by ref, repository, or local checkout, through config files or `PISTACK_*` environment variables. Untested refs warn, custom repositories warn harder, and a moving ref resolves to a recorded commit that startup reuses rather than advances.
+- Offline operation after the first bootstrap. A noninteractive run with an empty cache refuses network access until `PISTACK_ALLOW_BOOTSTRAP=1` permits it.
+- `pi-sandbox.sh`, which launches Pi against a throwaway config root holding only this adapter and its capability providers, optionally in a chosen project directory.
+- `npm run test:isolated`, which clones, packs, and installs the package into an isolated Pi environment and asserts what Pi actually loaded.
+
+### Security
+
+- Reject git remote strings that name an executing transport such as `ext::`, cleartext or credential-bearing remotes, and refs git would parse as options.
+- Require interactive user confirmation before `set_source` changes the upstream source or reaches the network, and refuse it outright without an interactive session. The tool is model-callable, so an untrusted upstream skill body could otherwise repoint the adapter at attacker-authored skills or use it as an outbound request channel.
+- Accept only model ids the local Pi installation actually offers in `set_model`.
+- Bracket every upstream skill body between explicit markers and repeat the host-precedence statement after it, so a body cannot close with an instruction to disregard the adapter notes. The body between the markers is still reproduced exactly.
+- State host precedence above every upstream skill body and at the top of every converted agent's system prompt: Pi policy, host safety rules, and explicit user instructions override conflicting upstream autonomy instructions. The upstream text is preserved rather than deleted, so it stays auditable.
+- Refuse upstream manifest paths and configured plugin paths that resolve outside the checkout, so a fetched repository cannot make the adapter read files elsewhere on disk.
+- Ignore `__proto__`, `constructor`, and `prototype` keys when merging configuration files.

package/LICENSE

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

package/README.md

@@ -0,0 +1,198 @@
+# pi-pstack-adapter
+
+[![npm](https://img.shields.io/npm/v/pi-pstack-adapter)](https://www.npmjs.com/package/pi-pstack-adapter)
+[![CI](https://github.com/elderfo/pi-pstack-adapter/actions/workflows/ci.yml/badge.svg)](https://github.com/elderfo/pi-pstack-adapter/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Use Cursor's [pstack](https://github.com/cursor/plugins/tree/main/pstack) skills and agents in
+[Pi](https://pi.dev).
+
+pstack is Cursor's collection of engineering workflows: design reviews (`how`), prose cleanup
+(`unslop`), test-driven development (`tdd`), parallel fan-out (`swarm`), and the full Poteto Mode
+working style. This package downloads a tested pstack release and exposes every workflow as a
+Pi skill named `pistack-*`. The upstream files stay unmodified, so you can audit exactly what
+the agent reads.
+
+## Quick start
+
+1. Install the package:
+
+   ```bash
+   pi install npm:pi-pstack-adapter
+   ```
+
+2. Start Pi. On the first interactive start, the adapter asks before it downloads pstack. Answer
+   yes.
+
+3. Run a workflow. `unslop` needs no other packages:
+
+   ```text
+   /skill:pistack-unslop
+   ```
+
+To see everything the adapter loaded, run `/pistack-status`.
+
+## Requirements
+
+- [Pi](https://pi.dev)
+- Git on your `PATH`
+- Linux, macOS, or Windows
+
+On native Windows, install [Git for Windows](https://git-scm.com/download/win). It provides both
+Git and the Git Bash shell that Pi's `bash` tool uses. pstack skills are written as Bash
+commands, so keep the `bash` tool active rather than switching to Pi's `powershell` tool.
+`/pistack-status` warns when Bash is missing or the `bash` tool is inactive. Pi inside WSL
+counts as Linux.
+
+### Add optional providers for delegating workflows
+
+Some workflows hand work to subagents or ask you multiple-choice questions. Install these two
+packages to enable them:
+
+```bash
+pi install npm:pi-subagents
+pi install npm:pi-ask-user
+```
+
+With `pi-subagents` installed, the upstream agents register as `pistack-comment-sicko` and
+`pistack-poteto-agent`. The adapter turns on the `subagent` tool when a delegating workflow
+starts, whether you run its `/skill:` command or the agent opens the skill itself. While Poteto
+Mode is on, the adapter turns it on for every prompt.
+
+To find missing providers or executables before you start a workflow, run
+`/pistack-check <skill>`.
+
+## Install from Git instead of npm
+
+To track the repository directly, install from GitHub:
+
+```bash
+pi install git:github.com/elderfo/pi-pstack-adapter
+```
+
+To pin a release, add its tag, for example `git:github.com/elderfo/pi-pstack-adapter@v0.3.0`.
+For a pinned npm release, use `npm:pi-pstack-adapter@0.3.0`.
+
+## Run pstack workflows
+
+Each pstack skill appears as a `/skill:pistack-*` command:
+
+```text
+/skill:pistack-how
+/skill:pistack-unslop
+/skill:pistack-poteto-mode
+```
+
+Before you run a workflow, check what it needs:
+
+```text
+/pistack-check how
+```
+
+The check reports the workflow's support tier and any missing capabilities or executables.
+
+The adapter also adds these commands:
+
+| Command | What it does |
+| --- | --- |
+| `/pistack-status` | Shows versions, the resolved commit, trust, capabilities, support tiers, and diagnostics. |
+| `/pistack-check <skill>` | Checks one workflow's requirements. |
+| `/pistack-mode on\|off\|status` | Turns Poteto Mode on or off for the current session. |
+| `/skill:pistack-setup` | Assigns Pi models to pstack roles or changes the upstream source. |
+| `/skill:pistack-status` | Asks the agent to produce the status report. |
+
+## Check how well a workflow is supported
+
+`/pistack-status` lists a support tier for each skill:
+
+| Tier | Meaning |
+| --- | --- |
+| `native` | The skill needs no Pi-specific changes, or the adapter supplies a Pi version. |
+| `adapted` | The upstream body works with the host mappings in its wrapper. |
+| `dependency-gated` | The workflow needs a capability or executable that may be missing. |
+| `experimental` | Part of the workflow has no direct Pi equivalent. |
+| `unsupported` | Pi cannot provide a required host feature. |
+
+The [compatibility registry](docs/compatibility.md) lists the tier and requirements of every
+skill.
+
+## Choose models for pstack roles
+
+pstack assigns work to named model roles such as `feature`, `bug-fix`, and `judgment`. A role you
+leave unset uses the current Pi session model.
+
+To list the models in your Pi installation and assign them to roles, run the setup skill:
+
+```text
+/skill:pistack-setup
+```
+
+In a noninteractive session, set roles with `PISTACK_MODELS`:
+
+```bash
+PISTACK_MODELS='feature=provider/model,bug-fix=provider/other-model' pi
+```
+
+## Run Pi noninteractively
+
+A noninteractive session, such as `pi --print`, cannot answer the download question. To allow
+the first download, set `PISTACK_ALLOW_BOOTSTRAP=1`:
+
+```bash
+PISTACK_ALLOW_BOOTSTRAP=1 pi --print "Summarize this repository"
+```
+
+The adapter caches pstack in `~/.pi/agent/cache/pi-pstack-adapter/`. Later sessions reuse the
+cached commit without network access.
+
+## Use a different pstack version
+
+Each adapter release certifies one pstack version and commit. `/pistack-status` shows both the
+certified commit and the commit in use.
+
+To select a branch, tag, commit, repository, or local checkout, run `/skill:pistack-setup`. The
+adapter asks you to confirm before it changes the source. Restart Pi or run `/reload` afterward.
+
+A branch or tag resolves to one commit when you select it. The adapter records that commit and
+does not move it on later starts. `/pistack-status` warns when you use a custom repository or a
+revision the adapter has not certified.
+
+## Configuration reference
+
+The setup skill writes user settings to `~/.pi/agent/pi-pstack-adapter.json` and project
+settings to `.pi/pi-pstack-adapter.json`. Environment variables override both files:
+
+| Variable | Effect |
+| --- | --- |
+| `PISTACK_NAMESPACE` | Replaces `pistack` in generated skill and command names. |
+| `PISTACK_UPSTREAM_REPO` | Selects another Git repository. |
+| `PISTACK_UPSTREAM_REF` | Selects a branch, tag, or commit. |
+| `PISTACK_UPSTREAM_PATH` | Uses a local pstack checkout. |
+| `PISTACK_UPSTREAM_PLUGIN_PATH` | Selects the plugin directory inside the checkout. |
+| `PISTACK_ALLOW_BOOTSTRAP` | Allows a noninteractive first download. |
+| `PISTACK_CACHE_DIR` | Changes the cache directory. |
+| `PISTACK_MODELS` | Assigns models as comma-separated `role=provider/model` pairs. |
+
+## Security and trust
+
+Pi skills run with your user permissions, and a skill can tell the agent to run programs. The
+adapter asks before it downloads pstack or changes the source. Review a custom repository before
+you select it.
+
+The adapter keeps each upstream skill body byte-for-byte so you can inspect it. Every generated
+wrapper states that Pi policy, host safety rules, and your instructions override conflicting text
+in a pstack skill.
+
+## Uninstall
+
+```bash
+pi remove npm:pi-pstack-adapter
+```
+
+To reclaim disk space, delete `~/.pi/agent/cache/pi-pstack-adapter/` and, if you created it,
+`~/.pi/agent/pi-pstack-adapter.json`.
+
+## License
+
+This adapter is available under the [MIT License](LICENSE). Upstream pstack is also MIT-licensed
+and remains copyright its authors.

package/VERSION

@@ -0,0 +1 @@
+0.3.0

package/adapter-skills/setup.md

@@ -0,0 +1,67 @@
+# Set up the pstack adapter
+
+Upstream pstack ships a `setup-pstack` skill that writes `~/.cursor/rules/pstack-models.mdc`,
+a Cursor-only always-applied rule full of Cursor model slugs. Pi has neither that file nor
+those models, so this adapter replaces the body with the Pi equivalent.
+
+Two things are configurable. Model roles, and the upstream source.
+
+## Model roles
+
+pstack skills name a model per role. In Pi those names mean nothing, so each role maps to a
+model in your own catalogue. A role you never configure inherits the parent session model,
+which is a working default, not a failure.
+
+Roles used by pstack workflows.
+
+| role | used by |
+| --- | --- |
+| `feature` | feature playbook |
+| `refactoring` | refactoring playbook |
+| `bug-fix` | bug-fix playbook |
+| `perf-issue` | perf playbook |
+| `hillclimb` | sustained metric improvement |
+| `judgment` | prose, review, and judgment delegates |
+| `strongest-judgment` | the hardest cross-cutting changes |
+
+The status report lists the same roles, so read it back rather than trusting this table if the
+adapter has been upgraded.
+
+Steps.
+
+1. Call the adapter tool with `action: "models"` to list the provider and model ids this Pi
+   installation can actually reach. Do not invent ids.
+2. Ask the user which model each role should use. Offer the listed ids, and offer
+   `inherit` for any role they do not care about. Use the structured question tool when it is
+   available; otherwise ask in plain text. Only ids from step 1 are accepted.
+3. For each answered role, call the adapter tool with `action: "set_model"`, the role, and the
+   chosen `provider/model` id. Pass `scope: "project"` when the user wants the choice to apply
+   only to this repository.
+4. Read back `action: "status"` and show the user what was written.
+
+For a scripted environment, set `PISTACK_MODELS` instead, for example
+`PISTACK_MODELS=feature=anthropic/claude-sonnet-4-5,bug-fix=openai/gpt-5`. The environment wins
+over both config files, so CI never needs this dialog.
+
+## Upstream source
+
+By default the adapter uses the pstack revision this release was tested against. Change it only
+when you are deliberately testing another revision.
+
+Call the adapter tool with `action: "set_source"` and one of these.
+
+- `ref` with a branch, tag, or commit. A branch or tag is resolved to a commit once, here, and
+  recorded. Later sessions keep that commit. The adapter never advances it on its own.
+- `repo` with another repository. This is outside the tested trust boundary.
+- `localPath` with a directory holding a pstack checkout. Use this when developing pstack itself.
+
+The adapter asks the user to confirm every source change itself and refuses without an
+interactive session, so a change cannot happen on your say-so alone. Explain the consequence in
+plain words before you call it, and report a refusal as a refusal.
+
+Regeneration happens on the next Pi start. Tell the user to restart Pi, or run `/reload`.
+
+## Finish
+
+End by reporting, in your own words, which roles were set, which still inherit, the resolved
+upstream commit, and the trust level from the status output.

package/adapter-skills/status.md

@@ -0,0 +1,28 @@
+# pstack adapter status
+
+Report what the adapter is actually running, so nobody has to guess whether a pstack workflow
+is verified here.
+
+1. Call the adapter tool with `action: "status"`.
+2. Show the user the full report. Do not summarize away the trust line, the resolved commit, or
+   any `error` diagnostic.
+3. If a capability is missing, name the capability, name the workflows it gates, and give the
+   install command from the report.
+4. If any diagnostic is an `error`, say which upstream resource failed and that the adapter
+   skipped it.
+
+To check one workflow before starting it, call the tool with `action: "check"` and the skill
+name. That reports the capabilities and executables that workflow needs and whether this
+environment has them, before the workflow does any work.
+
+Support tiers mean this.
+
+| tier | meaning |
+| --- | --- |
+| `native` | adapter-owned content, written for Pi |
+| `adapted` | upstream body works once you apply the host mapping |
+| `dependency-gated` | needs a capability or an executable that may be absent |
+| `experimental` | depends on host behavior with no clean Pi equivalent, may partly work |
+| `unsupported` | needs something Pi cannot provide; the workflow cannot reach its purpose |
+
+A tier is a claim about what the adapter verified, not a promise about a given run.

package/docs/compatibility.md

@@ -0,0 +1,164 @@
+# Compatibility
+
+The compatibility registry in `src/registry.ts` assigns one support tier to every skill in the
+certified pstack revision. Generation reads it, the wrapper frontmatter publishes it, and
+`/pistack-status` reports it.
+
+Certified revision: pstack `0.15.9` at `e43c7ee26e0038c6c1fa8380dd34ce86ff94cb2a` in
+`https://github.com/cursor/plugins`.
+
+## Platforms
+
+| platform | status | shell the skills run in |
+| --- | --- | --- |
+| Linux, including Pi inside WSL | supported | Bash |
+| macOS | supported | Bash |
+| Windows, native | supported | Git Bash, Pi's default `bash` tool shell |
+| anything else | experimental | whatever Pi resolves |
+
+The tiers below apply on every supported platform. `/pistack-check` looks for per-skill
+executables in the shell the skills run in, with Pi's `shellCommandPrefix` applied. On Windows
+that matters most, because Git Bash adds `/usr/bin` and `/mingw64/bin` to the `PATH` Pi
+started with. A shell that is missing, inactive, or cannot run a command blocks every workflow.
+
+Windows evidence at the certified revision, on Windows 11 with Git for Windows 2.53, Node 22,
+and Pi 1.0.2:
+
+- The unit suite passes, and `npm run test:isolated` passes against the adapter commit that
+  introduced Windows support. Pi registers all 51 skills, and a later run reuses the cache
+  without the network. CI runs the unit suite on Windows for every change.
+- Every upstream helper script ran in Git Bash: `show-me-your-work/scripts/log.sh`,
+  `poteto-mode/scripts/check-plan.mjs`, `worktree-audit.sh`, `watch-pr`, and `orch.ts`.
+- Git for Windows bundles `git`, `curl`, `nproc`, and the POSIX tools the skill bodies call,
+  but not `uptime`, so `benchmark-checklist` reports it missing. `gh`, `tailscale`, and `sudo`
+  are separate installs on Windows, as on the other platforms.
+- The adapter checks out upstream with `core.autocrlf=false`. Git for Windows enables
+  `autocrlf` system-wide, which would otherwise rewrite every upstream file to CRLF. A cache
+  written before that setting existed is repaired on the next start, or refused with a recovery
+  step when it cannot be written.
+
+A session that replaces the `bash` tool with `powershell` cannot run the skills.
+`/pistack-status` reports it, and `/pistack-check` refuses to clear any workflow.
+
+## Tiers
+
+| tier | meaning |
+| --- | --- |
+| `native` | adapter-owned content, or a body with no host-specific machinery at all |
+| `adapted` | works once the reader applies the host mapping the wrapper links to |
+| `dependency-gated` | needs a host capability or an executable that may be absent |
+| `experimental` | depends on host behavior with no clean Pi equivalent, may partly work |
+| `unsupported` | needs something Pi cannot provide, so the workflow cannot reach its purpose |
+
+## Changing a tier
+
+A tier is a claim about what was verified, so raising one needs evidence, not optimism.
+
+1. Run the workflow end to end in Pi against the certified revision.
+2. Record what the workflow produced, not that it started. A `dependency-gated` skill rises to
+   `adapted` only when its delegation or question steps completed against a real provider.
+3. An `experimental` skill rises only when every Cursor-specific step has a Pi equivalent that
+   was exercised, not merely described in the host mapping.
+4. An `unsupported` skill rises only when the missing host feature exists in Pi.
+5. Add or update a test that fails if the claim regresses.
+
+Lowering a tier needs one reproduction of the failure and a note saying what broke.
+
+## Registry
+
+### native (30)
+
+| upstream skill | Pi skill | capabilities | executables | why |
+| --- | --- | --- | --- | --- |
+| `bro` | `/skill:pistack-bro` | - | - | - |
+| `principle-attack-the-premise` | `/skill:pistack-principle-attack-the-premise` | - | - | - |
+| `principle-boundary-discipline` | `/skill:pistack-principle-boundary-discipline` | - | - | - |
+| `principle-build-the-lever` | `/skill:pistack-principle-build-the-lever` | - | - | - |
+| `principle-encode-lessons-in-structure` | `/skill:pistack-principle-encode-lessons-in-structure` | - | - | - |
+| `principle-exhaust-the-design-space` | `/skill:pistack-principle-exhaust-the-design-space` | - | - | - |
+| `principle-experience-first` | `/skill:pistack-principle-experience-first` | - | - | - |
+| `principle-explain-the-number` | `/skill:pistack-principle-explain-the-number` | - | - | For a performance number it hands off to benchmark-checklist, which needs uptime and nproc. Check that skill first. |
+| `principle-fix-root-causes` | `/skill:pistack-principle-fix-root-causes` | - | - | - |
+| `principle-foundational-thinking` | `/skill:pistack-principle-foundational-thinking` | - | - | - |
+| `principle-guard-the-context-window` | `/skill:pistack-principle-guard-the-context-window` | - | - | - |
+| `principle-laziness-protocol` | `/skill:pistack-principle-laziness-protocol` | - | - | - |
+| `principle-make-operations-idempotent` | `/skill:pistack-principle-make-operations-idempotent` | - | - | - |
+| `principle-migrate-callers-then-delete-legacy-apis` | `/skill:pistack-principle-migrate-callers-then-delete-legacy-apis` | - | - | - |
+| `principle-minimize-reader-load` | `/skill:pistack-principle-minimize-reader-load` | - | - | - |
+| `principle-model-the-domain` | `/skill:pistack-principle-model-the-domain` | - | - | - |
+| `principle-never-block-on-the-human` | `/skill:pistack-principle-never-block-on-the-human` | - | - | - |
+| `principle-outcome-oriented-execution` | `/skill:pistack-principle-outcome-oriented-execution` | - | - | - |
+| `principle-prove-it-works` | `/skill:pistack-principle-prove-it-works` | - | - | - |
+| `principle-redesign-from-first-principles` | `/skill:pistack-principle-redesign-from-first-principles` | - | - | - |
+| `principle-separate-before-serializing-shared-state` | `/skill:pistack-principle-separate-before-serializing-shared-state` | - | - | - |
+| `principle-sequence-verifiable-units` | `/skill:pistack-principle-sequence-verifiable-units` | - | - | - |
+| `principle-subtract-before-you-add` | `/skill:pistack-principle-subtract-before-you-add` | - | - | - |
+| `principle-test-behavior-not-implementation` | `/skill:pistack-principle-test-behavior-not-implementation` | - | - | - |
+| `principle-type-system-discipline` | `/skill:pistack-principle-type-system-discipline` | - | - | - |
+| `setup-pstack` | `/skill:pistack-setup` | - | - | The upstream body only writes a Cursor .mdc rule, so the adapter replaces it with a Pi setup workflow. |
+| `tdd` | `/skill:pistack-tdd` | - | - | - |
+| `technical-writing` | `/skill:pistack-technical-writing` | - | - | - |
+| `typescript-best-practices` | `/skill:pistack-typescript-best-practices` | - | - | - |
+| `unslop` | `/skill:pistack-unslop` | - | - | - |
+
+### adapted (1)
+
+| upstream skill | Pi skill | capabilities | executables | why |
+| --- | --- | --- | --- | --- |
+| `create-verification-skill` | `/skill:pistack-create-verification-skill` | - | - | Only the generated skill's output path needs remapping to Pi's skill directory. |
+
+### dependency-gated (13)
+
+| upstream skill | Pi skill | capabilities | executables | why |
+| --- | --- | --- | --- | --- |
+| `architect` | `/skill:pistack-architect` | `delegation` | - | Phase B delegates to arena runners, so it cannot run without parallel subagents. |
+| `arena` | `/skill:pistack-arena` | `delegation` | `git` | The whole skill is spawning N candidate subagents plus a judge. |
+| `benchmark-checklist` | `/skill:pistack-benchmark-checklist` | - | `uptime`, `nproc` | Its setup step checks load with `uptime` and cores with `nproc`. macOS has no `nproc` without GNU coreutils, and Git Bash on Windows has no `uptime`. |
+| `blast-radius` | `/skill:pistack-blast-radius` | - | `git`, `gh` | Needs git and gh to read the diff, commits, and PR before any analysis. |
+| `correct` | `/skill:pistack-correct` | - | `git` | Mines commit history, then commits fixes and edits lint, CI, and agent instruction files. Run it on a branch you will review. |
+| `figure-it-out` | `/skill:pistack-figure-it-out` | `delegation` | - | Phase B fan-out and the architect/arena routing require parallel subagents. |
+| `how` | `/skill:pistack-how` | `delegation` | - | Every path spawns explorer or explainer subagents; nothing runs inline. |
+| `interrogate` | `/skill:pistack-interrogate` | `delegation` | `git` | Multi-model adversarial review is entirely one subagent per configured model. |
+| `maintain-verification-skill` | `/skill:pistack-maintain-verification-skill` | `delegation` | - | Source wave launches one read-only subagent per feature file. |
+| `no-comments` | `/skill:pistack-no-comments` | `delegation` | `git` | Step 1 must spawn the named Comment Sicko agent; the skill only triages its report. |
+| `show-me-your-work` | `/skill:pistack-show-me-your-work` | `delegation` | - | The mandatory cross-model review of the trail requires spawning a different-family subagent. |
+| `teach` | `/skill:pistack-teach` | `delegation` | - | It runs the how and why skills, both of which need subagents. |
+| `why` | `/skill:pistack-why` | `delegation` | `git`, `gh` | Default posture spawns one investigator subagent per evidence category plus a synthesizer. |
+
+### experimental (5)
+
+| upstream skill | Pi skill | capabilities | executables | why |
+| --- | --- | --- | --- | --- |
+| `automate-me` | `/skill:pistack-automate-me` | `delegation`, `structured-question` | `git`, `gh` | Mining step depends on Cursor transcript files and the built-in create-skill skill, with no Pi equivalent. |
+| `poteto-mode` | `/skill:pistack-poteto-mode` | `delegation`, `structured-question` | `git`, `gh` | Sticky-mode hosting plus references to Cursor built-in and plugin skills only partially map to Pi. |
+| `recall` | `/skill:pistack-recall` | `delegation` | `git`, `gh` | Core corpus is Cursor's on-disk transcript JSONL, so only the git/gh and shared-record half survives. |
+| `reflect` | `/skill:pistack-reflect` | `delegation` | - | Transcript mining and create-skill routing are Cursor-specific, though the digest fallback partly works. |
+| `swarm` | `/skill:pistack-swarm` | `delegation` | - | Cloud background workers and cloud_base_branch have no Pi mapping; only local fan-out approximates it. |
+
+### unsupported (1)
+
+| upstream skill | Pi skill | capabilities | executables | why |
+| --- | --- | --- | --- | --- |
+| `make-bot-ui` | `/skill:pistack-make-bot-ui` | - | `curl`, `tailscale`, `sudo` | Built entirely on Cursor Automations webhook routines and the secret-request card. |
+
+## Agents
+
+| upstream agent | Pi agent | notes |
+| --- | --- | --- |
+| `comment-sicko` | `pistack-comment-sicko` | Display name `Comment Sicko` is preserved in the description. Needs `git` to scope a diff. |
+| `poteto-agent` | `pistack-poteto-agent` | Upstream `is_background: true` has no runtime equivalent; the caller chooses `async` on the `subagent` call. |
+
+Both register through the `pi-subagents:runtime-agent-register:v1` contract. Without an owner for
+that event, the status report says so rather than dropping them silently.
+
+## Skills the adapter replaces
+
+`setup-pstack` writes a Cursor `.mdc` rule and nothing else, so the adapter substitutes its own
+body and publishes it as `/skill:pistack-setup`. The upstream skill stays represented, and the
+wrapper frontmatter records `pistack-upstream-skill: setup-pstack`.
+
+## Unknown skills
+
+A skill present upstream but absent from the registry is generated as `experimental` and reported
+in diagnostics. A skill in the registry but absent upstream is reported as removed. Neither case
+is silent.