pi-pstack

Rigorous engineering workflows for the Pi coding agent.

This package is a Pi-native reinterpretation of Lauren Tan's pstack. It keeps the central idea: go deep before going fast, make small coherent changes, and prove the result on the real artifact.

This is an independent port. It is not an official pstack package.

What it includes

• A sticky pstack mode for Pi sessions.
• A router with 12 task playbooks.
• Architecture, arena, swarm, adversarial review, explanation, rationale, blast-radius, TDD, comment review, writing, and decision-log skills.
• The 21 focused engineering principles from the original pstack package.
• Optional model-role configuration.
• Optional integration with active Pi delegation tools. Plain Pi uses sequential review passes.

Install

From npm:

pi install npm:@kevinpita/pi-pstack

From this checkout:

pi install .

Install it only for the current project:

pi install -l .

Try it without installation:

pi -e .

Pi packages execute with your system permissions. Review extensions/index.ts and the skills before installation.

Start

Enable the sticky mode and give it a task:

/pstack fix the cache invalidation bug and prove the stale value is gone

Enable it without starting a task:

/pstack

The mode stays active in the current session branch. Disable it with:

/pstack-off

Use one skill without sticky mode:

/skill:pstack-mode review this refactor
/skill:architect design the new cache boundary
/skill:interrogate review the current branch
/skill:how explain the request path

Start Pi with the mode already active:

pi --pstack

Commands

| Command | Purpose | | --- | --- | | /pstack [task] | Enable the mode. Start the optional task. | | /pstack-mode [task] | Alias for /pstack. | | /pstack-off | Disable the mode on the current session branch. | | /pstack-status | Show mode state and model roles. | | /pstack-setup | Select model roles and write user configuration. |

Playbooks

The pstack-mode skill selects one primary playbook.

| Playbook | Use | | --- | --- | | General | Small scoped work. | | Investigation | Read-only explanation or confidence check. | | Bug fix | Reproduce, isolate, fix, and prove a defect. | | Performance | Measure a slow path and compare with a baseline. | | Feature | Add or change observable behavior. | | Refactor | Preserve behavior while changing structure. | | Prototype | Compare throwaway alternatives. | | Review | Inspect a diff and issue a lead verdict. | | Autonomous run | Drive one task to a defined predicate. | | Session pickup | Resume from a Pi session or repository checkpoint. | | Pause safely | Leave a cold-start handoff at a safe boundary. | | Open a PR | Prepare and prove a reviewable branch. |

Delegation

Delegation is not required.

When a compatible subagent tool is active and current system instructions allow it, the arena, swarm, architect, and interrogate skills can use isolated workers. They keep one writer per worktree and use fresh contexts for review.

When only a workflow tool is active, these skills use it only after explicit user opt-in. Invoking arena, swarm, or interrogate is an explicit request for that fan-out.

Without a delegation tool, the same work runs as separate sequential passes. The parent agent always owns the diff and final verdict.

Model roles

Run /pstack-setup or edit ~/.pi/agent/pstack.json. Setup shows only models from saved logins and explicit models.json credentials. It hides providers that Pi discovered only from the environment, such as ambient AWS credentials. If model scoping is active, setup also limits the list to logged-in models in the current scope.

{
  "defaultOn": false,
  "models": {
    "analysis": "openai-codex/gpt-5.6-sol:xhigh",
    "implementation": "openai-codex/gpt-5.6-sol:xhigh",
    "review": ["openai-codex/gpt-5.6-sol:xhigh"]
  }
}

Project overrides can go in .pi/pstack.json after the project is trusted. See configuration.

Role values guide a compatible delegation tool. They do not change the current Pi model. Use provider/model-id, an optional thinking suffix such as :xhigh, or inherit-parent. /pstack-setup shows only the thinking levels that the selected model supports.

Differences from Cursor pstack

• Pi package discovery replaces Cursor plugin metadata.
• A Pi extension implements sticky mode and session-branch persistence.
• Pi Agent Skills replace Cursor skill and agent registration.
• The package has no fixed frontier-model slugs.
• The package has no hard dependency on a subagent runtime.
• Cursor cloud agents, MCP discovery, Graphite-specific automation, Bugbot automation, and the Benny pack are not ported.
• Externally visible or destructive actions require authority from the user or current system instructions.
• The playbooks are smaller and portable across repositories.

See architecture for the package design.

Development

Requirements are Node.js 22.19 or newer.

npm install
npm run check

Test the package in a clean Pi process:

pi --no-extensions --no-skills -e . --pstack

Attribution

The original pstack package is Copyright (c) 2026 Lauren Tan and is available under the MIT License. This package includes adapted material. See NOTICE.

License

MIT. See LICENSE.