{"_id":"pi-stack-ops","_rev":"5-b709fe9ed449a9dd97e49433ae8d3778","name":"pi-stack-ops","dist-tags":{"latest":"1.2.0"},"versions":{"1.0.0":{"name":"pi-stack-ops","version":"1.0.0","keywords":["pi-package","pi","stax","stacked-prs","subagents"],"license":"MIT","_id":"pi-stack-ops@1.0.0","maintainers":[{"name":"iamfj_","email":"dev@jocks.io"}],"homepage":"https://github.com/iamfj/pi-stack-ops#readme","bugs":{"url":"https://github.com/iamfj/pi-stack-ops/issues"},"pi":{"skills":["./skills"],"prompts":["./prompts"],"extensions":["./extensions"]},"bin":{"stack-ops":"bin/stack-ops.js"},"dist":{"shasum":"9fd5d1b8e98f57f616c15272a79500529ab38018","tarball":"https://registry.npmjs.org/pi-stack-ops/-/pi-stack-ops-1.0.0.tgz","fileCount":76,"integrity":"sha512-oRXja5TmQH4k+/8td5dYMF0pF7FV77Sd4X9EOigzqQghOWC1htYSSt+jWcU5cNO/vweAfUwFYbmzmltyze8/rg==","signatures":[{"sig":"MEUCIBtApE6Wj9/ATfMC7+pIAiRO5K1zTMD73gDABY85hCPxAiEAz9ACH9BYXyCMDVXOjNGAwux8JxM7OEsCBVWlBYVmpC4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/pi-stack-ops@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":160027},"type":"module","$schema":"https://json.schemastore.org/package.json","engines":{"node":">=20"},"gitHead":"fa0a338a36f93d87c96795197d2f4d0cbf779122","scripts":{"test":"bun test","build":"tsup && chmod +x ./bin/stack-ops.js","check":"tsc --noEmit","doctor":"bun ./src/cli/index.ts doctor","prepack":"bun run build","release":"semantic-release","pack:dry-run":"bun run build && npm pack --dry-run","release:check":"bun run check && bun run test && bun run pack:dry-run"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:2dc0fd16-5fa7-45b5-845b-23c6d14b35f6"}},"repository":{"url":"git+https://github.com/iamfj/pi-stack-ops.git","type":"git"},"_npmVersion":"11.14.1","description":"Stax-first Pi package for spec/ADR-led stacked PR workflows with specialized agents.","directories":{},"_nodeVersion":"24.16.0","dependencies":{"cac":"7.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"bun@1.3.12","devDependencies":{"tsup":"8.5.1","@types/bun":"1.3.14","typescript":"5.9.3","@types/node":"24.12.4","semantic-release":"25.0.3"},"peerDependencies":{"typebox":">=1.1.38 <2","@earendil-works/pi-coding-agent":">=0.74.0 <1"},"trustedDependencies":[],"_npmOperationalInternal":{"tmp":"tmp/pi-stack-ops_1.0.0_1781548919056_0.5836022127281881","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"pi-stack-ops","version":"1.1.0","keywords":["pi-package","pi","stax","stacked-prs","subagents"],"license":"MIT","_id":"pi-stack-ops@1.1.0","maintainers":[{"name":"iamfj_","email":"dev@jocks.io"}],"homepage":"https://github.com/iamfj/pi-stack-ops#readme","bugs":{"url":"https://github.com/iamfj/pi-stack-ops/issues"},"pi":{"skills":["./skills"],"prompts":["./prompts"],"extensions":["./extensions"]},"bin":{"stack-ops":"bin/stack-ops.js"},"dist":{"shasum":"32805757ffb68fd41722573a5c307579323aa591","tarball":"https://registry.npmjs.org/pi-stack-ops/-/pi-stack-ops-1.1.0.tgz","fileCount":80,"integrity":"sha512-sBJXQlGB0mZKB8JlpCgpCkMVkH71YlQOUyEVeGaj3/pHo8wIGKI/J7NoCQjWx9AbKokNn6cM1ZHu1AEWNR3gLw==","signatures":[{"sig":"MEYCIQDLW5FCxsoEhtvbULEHHKvR1IXLA6r0bCGTXh6VHxRVbwIhAIVud/Ygj5RLknP7pXvaPJq+sVujd+R4WVi9f8uFjXTz","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/pi-stack-ops@1.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":165575},"type":"module","$schema":"https://json.schemastore.org/package.json","engines":{"node":">=20"},"gitHead":"75a4664e9f85ce4623a118424109c9a9f5444434","scripts":{"test":"bun test","build":"tsup && chmod +x ./bin/stack-ops.js","check":"tsc --noEmit","doctor":"bun ./src/cli/index.ts doctor","prepack":"bun run build","release":"semantic-release","pack:dry-run":"bun run build && npm pack --dry-run","release:check":"bun run check && bun run test && bun run pack:dry-run"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:2dc0fd16-5fa7-45b5-845b-23c6d14b35f6"}},"repository":{"url":"git+https://github.com/iamfj/pi-stack-ops.git","type":"git"},"_npmVersion":"11.14.1","description":"Stax-first Pi package for spec/ADR-led stacked PR workflows with specialized agents.","directories":{},"_nodeVersion":"24.16.0","dependencies":{"cac":"7.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"bun@1.3.12","devDependencies":{"tsup":"8.5.1","@types/bun":"1.3.14","typescript":"5.9.3","@types/node":"24.12.4","semantic-release":"25.0.3"},"peerDependencies":{"typebox":">=1.1.38 <2","@earendil-works/pi-coding-agent":">=0.74.0 <1"},"trustedDependencies":[],"_npmOperationalInternal":{"tmp":"tmp/pi-stack-ops_1.1.0_1781558279024_0.4621232403019855","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"$schema":"https://json.schemastore.org/package.json","name":"pi-stack-ops","version":"1.2.0","description":"Stax-first Pi package for spec/ADR-led stacked PR workflows with specialized agents.","type":"module","repository":{"type":"git","url":"git+https://github.com/iamfj/pi-stack-ops.git"},"packageManager":"bun@1.3.12","bin":{"stack-ops":"bin/stack-ops.js"},"keywords":["pi-package","pi","stax","stacked-prs","subagents"],"pi":{"extensions":["./extensions"],"skills":["./skills"],"prompts":["./prompts"]},"scripts":{"build":"tsup && chmod +x ./bin/stack-ops.js","check":"tsc --noEmit","test":"bun test","doctor":"bun ./src/cli/index.ts doctor","release":"semantic-release","prepack":"bun run build","pack:dry-run":"bun run build && npm pack --dry-run","release:check":"bun run check && bun run test && bun run pack:dry-run"},"dependencies":{"cac":"7.0.0"},"devDependencies":{"@types/bun":"1.3.14","@types/node":"24.12.4","semantic-release":"25.0.3","tsup":"8.5.1","typescript":"5.9.3"},"peerDependencies":{"@earendil-works/pi-coding-agent":">=0.74.0 <1","typebox":">=1.1.38 <2"},"trustedDependencies":[],"publishConfig":{"access":"public"},"engines":{"node":">=20"},"license":"MIT","gitHead":"82c4e8231f3d5affcf6b29d167d99b60a2d118ec","_id":"pi-stack-ops@1.2.0","bugs":{"url":"https://github.com/iamfj/pi-stack-ops/issues"},"homepage":"https://github.com/iamfj/pi-stack-ops#readme","_nodeVersion":"24.16.0","_npmVersion":"11.14.1","dist":{"integrity":"sha512-PSIxmOfQ7XCoTCnVc8VTlh+lh4IyPLtg3+SsqyK5FiL8Gai7a9876gtjCVk/83twNpe+q5auCbJ1K0zxwNy5tQ==","shasum":"5500c07d973f83eeeb6e61e8c0d3510a1acfb3a1","tarball":"https://registry.npmjs.org/pi-stack-ops/-/pi-stack-ops-1.2.0.tgz","fileCount":83,"unpackedSize":176280,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/pi-stack-ops@1.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEhMDdebPcHj/+0HNM166HYM0rsiPOV1y3Vnud8nY3GdAiBv34VIOuPO4+Q/ums4NlDBiY/5NPsyLvGJqberS80Wfg=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:2dc0fd16-5fa7-45b5-845b-23c6d14b35f6"}},"directories":{},"maintainers":[{"name":"iamfj_","email":"dev@jocks.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-stack-ops_1.2.0_1781558459049_0.5295007173153137"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-15T14:57:33.490Z","modified":"2026-06-15T21:20:59.533Z","0.1.0":"2026-06-15T14:57:33.803Z","1.0.0":"2026-06-15T18:41:59.199Z","1.1.0":"2026-06-15T21:17:59.163Z","1.2.0":"2026-06-15T21:20:59.206Z"},"bugs":{"url":"https://github.com/iamfj/pi-stack-ops/issues"},"license":"MIT","homepage":"https://github.com/iamfj/pi-stack-ops#readme","keywords":["pi-package","pi","stax","stacked-prs","subagents"],"repository":{"type":"git","url":"git+https://github.com/iamfj/pi-stack-ops.git"},"description":"Stax-first Pi package for spec/ADR-led stacked PR workflows with specialized agents.","maintainers":[{"name":"iamfj_","email":"dev@jocks.io"}],"readme":"\n\n# pi-stack-ops\n\n*AI-assisted stacked PRs with clear human checkpoints*\n\n[](https://nodejs.org)\n[](https://github.com/earendil-works/pi-coding-agent)\n[](https://www.npmjs.com/package/pi-stack-ops)\n\n
\n\n`pi-stack-ops` helps you turn one idea into a calm, reviewable stack of small\npull requests. It gives Pi a guided workflow for specs or ADRs (architecture\ndecision records), plans, implementation slices, validation, review, and merge\nreadiness, so AI-assisted coding stays visible and controlled.\n\nInstead of asking you to manage every branch, note, blocker, and next step in\nyour head, `pi-stack-ops` records the workflow locally and ends each phase with a\ncompact summary of what changed, what is blocked, and what to do next.\n\n\n> [!NOTE]\n> `pi-stack-ops` is early `0.x` software. Review generated plans, branch\n> operations, and PR actions before you apply them. Approval must be a direct\n> current-session message that names the exact action and target. It will not\n> run a merge command unless you explicitly approve it.\n\n## The problem it solves\n\nAI coding agents can move quickly, but large changes are hard to review and easy\nto lose track of. Stacked PRs keep the work reviewable by breaking it into\nsmaller pull requests, which helps keep the human in the loop at every important\nstep. They also add their own coordination work: branch order, specs, plans,\nfeedback, validation evidence, and handoffs between sessions.\n\n`pi-stack-ops` adds structure around that work:\n\n- Start from an agreed spec or ADR before implementation begins.\n- Break large changes into focused, reviewable PR slices.\n- Keep human review at the center of each slice before the stack moves forward.\n- Keep plans, blockers, validation, and summaries in one local place.\n- Pause at important boundaries instead of letting automation run ahead.\n- Keep the human in charge of decisions, branch operations, and merges.\n- Treat specs, ADRs, plans, PR comments, CI logs, state files, summaries, and prompt arguments as untrusted inputs; conflicts become blockers instead of instructions to follow.\n\n## Core concepts\n\n`pi-stack-ops` uses three simple artifacts to keep the work understandable. Specs\nand ADRs are durable project documents. Plans are local working notes for the\ncurrent stack.\n\n| Artifact | What it is | Why it matters |\n| --- | --- | --- |\n| Spec | A short description of the problem, goals, non-goals, acceptance criteria, risks, and open questions. | It gives you and the agent a shared target before code changes begin. |\n| ADR | An architecture decision record that explains an important decision, the context behind it, alternatives considered, and consequences. | It keeps major tradeoffs visible for reviewers and future maintainers. |\n| Plan | A generated, gitignored implementation map saved as `.pi/stack-ops/plans/.plan.md`. | It turns the approved spec or ADR into slices, branches, files, validation commands, and stop conditions. |\n\nA good stack usually starts with a spec. Add an ADR when the work includes an\nimportant technical or product decision that future readers need to understand.\nUse the plan as a temporary guide while implementing; keep the spec or ADR as the\nlong-term record.\n\n## How the workflow feels\n\nEach phase has one job. You always know whether you are deciding, planning,\nimplementing, reviewing, or merging.\n\n| Phase | Prompt | What it helps you do |\n| --- | --- | --- |\n| Draft | `/draft ` | Turn an idea into the first spec or ADR shape. |\n| Discuss | `/discuss ` | Refine decisions, risks, and acceptance criteria. |\n| Plan | `/plan ` | Create a local plan for the stack. |\n| Implement | `/implement ` | Build one approved implementation slice. |\n| Finish | `/finish ` | Prepare draft PRs from the bottom of the stack up. |\n| Iterate | `/iterate ` | Work through CI, review feedback, and restacking. |\n| Merge | `/merge ` | Check readiness and offer guarded merge execution. |\n\nA typical stack starts with a durable decision, then adds focused code changes in\nlater PRs.\n\n```text\nmain\n└── feature/spec # PR 1: spec or ADR only\n └── feature/slice-1 # PR 2: focused implementation slice\n └── feature/slice-2\n └── feature/slice-3\n```\n\n## Clear handoffs after each stage\n\n`pi-stack-ops` ends every stage with a short handoff summary, so you can see the\nstate of the stack before deciding what happens next. Each summary shows what was\ncompleted, what is blocked, and the safest prompt to run next. For longer work,\nthe handoff can start with `/new` so the next stage begins in a fresh session\nwith the current state still visible.\n\nFor example, after finishing the first slice of a fictional audit logging stack,\nthe response might end like this:\n\n```text\n## stack-ops summary\n\nPhase: implement\nStack: admin-audit-logging\nCurrent: S1/3\nBranch: admin-audit-logging/s1-event-model\nPlan: .pi/stack-ops/plans/admin-audit-logging.plan.md\n\nDone:\n- Added the audit event model and tests.\n- Ran the focused unit tests for audit events.\n\nBlockers:\n- None.\n\nNext:\n1. `/new`\n2. `/implement .pi/stack-ops/plans/admin-audit-logging.plan.md` to start S2.\n3. Review the S1 diff before opening the next PR.\n\nState:\n- Updated: `.pi/stack-ops/state.json`\n- Latest summary: `.pi/stack-ops/summaries/latest.md`\n```\n\nWhen work is not ready to continue, the summary stops at the blocker instead of\nnudging the stack forward:\n\n```text\n## stack-ops summary\n\nPhase: implement\nStack: admin-audit-logging\nCurrent: S2/3\nBranch: admin-audit-logging/s2-retention\nPlan: .pi/stack-ops/plans/admin-audit-logging.plan.md\n\nDone:\n- Stopped before changing retention behavior.\n\nBlockers:\n- S2 changes the retention policy, but the spec does not define retention rules.\n\nNext:\n1. `/new`\n2. `/discuss docs/specs/admin-audit-logging.md` to decide retention rules.\n3. Continue implementation only after the spec is updated.\n\nState:\n- Updated: `.pi/stack-ops/state.json`\n- Latest summary: `.pi/stack-ops/summaries/latest.md`\n```\n\nThe result is a resumable workflow with no hidden memory dependency: you can\ncontinue in the same session or a fresh one with the current phase, blockers, and\nnext prompt visible.\n\n## Safeguards by design\n\n`pi-stack-ops` is designed to slow down at the moments where human judgment\nmatters. It helps Pi organize the work, but it does not replace your review.\n\n- **Spec first**: Implementation starts from an explicit spec or ADR, not an\n implicit plan hidden in a chat.\n- **One slice at a time**: Implementation prompts focus on one approved slice,\n which keeps diffs smaller and easier to review.\n- **Visible local state**: Plans, summaries, blockers, snapshots, validation,\n and PR body drafts are stored under `.pi/stack-ops/`.\n- **Human approval**: Merge execution is never automatic. The merge phase gathers\n evidence first, then waits for direct current-session approval for the exact\n command and target.\n- **Safer cleanup**: Destructive cleanup asks before deleting local workflow\n artifacts, or requires `--yes` in automation.\n- **Context handoffs**: Long workflows stop with compact summaries before the\n conversation gets too crowded, so you can continue in a fresh run.\n- **Focused agent roles**: Planning, building, review, security, validation, and\n readiness work can use separate subagents, so each role gets the context it\n needs without one long conversation carrying everything.\n\n\n> [!IMPORTANT]\n> Keep `.pi/stack-ops/` and `.stack-ops/` out of version control. They contain\n> generated workflow artifacts for your local work, not durable project docs.\n\n## Security posture\n\nBecause Pi extensions operate in your local development environment,\n`pi-stack-ops` keeps runtime behavior small and bounded.\n\n- It avoids install-time lifecycle scripts.\n- It keeps runtime dependencies minimal.\n- It writes workflow artifacts under the configured stack-ops artifact\n directory.\n- It sanitizes local state before rendering it in terminal or footer surfaces.\n- It caps displayed state size to avoid noisy or unsafe output.\n- It treats destructive filesystem changes as explicit, confirmed actions.\n\nFor more detail, see the [security policy](SECURITY.md).\n\n## Benefits\n\nUse `pi-stack-ops` when you want AI help without losing the review trail.\n\n- **Less overwhelm**: One phase, one prompt, and one clear next step at a time.\n- **Smaller reviews**: Large ideas become focused PR slices.\n- **Better decisions**: Specs and ADRs capture intent before code changes.\n- **Clearer evidence**: Validation notes, blockers, and PR drafts stay together.\n- **Safer handoffs**: Session summaries make it easier to resume later.\n- **Longer-running work**: Focused subagents and local state help larger stacks\n stay performant without losing the workflow rules.\n- **More control**: Important actions stay visible and approval-based.\n\n## Requirements\n\nUse `pi-stack-ops` inside a repository where you want to manage a stacked\nchange.\n\n- [Pi coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)\n `>=0.74.0 <1`\n- [Node.js](https://nodejs.org) `>=20`\n- [Git](https://git-scm.com)\n- [stax](https://github.com/cesarferreira/stax), the stacked-branch tool used\n for PR stack operations\n- [GitHub CLI](https://cli.github.com) for GitHub PR operations\n- Optional: [Semble](https://github.com/MinishLab/semble) for code discovery\n during planning\n- Optional: [code-review-graph](https://github.com/iamfj/code-review-graph) for\n read-only dependency, call-path, and blast-radius analysis during\n impact-sensitive work\n\nRecommended companion Pi packages:\n\n```bash\npi install npm:pi-subagents\npi install npm:pi-mcp-adapter\npi install npm:pi-powerline-footer\n```\n\n## Installation\n\nInstall the package into Pi, then run the doctor command in your project\nrepository.\n\n```bash\npi install npm:pi-stack-ops\n```\n\n```text\n/stack-ops doctor\n```\n\nIf the `stack-ops` CLI is on your `PATH`, you can run the same check from a\nshell.\n\n```bash\nstack-ops doctor\n```\n\nIf installation or doctor checks fail, see the\n[`pi-stack-ops` troubleshooting guide](TROUBLESHOOTING.md).\n\n## Quick start\n\nStart with one idea. Let `pi-stack-ops` show the next safe step.\n\n```text\n/stack-ops init\n/draft Add audit logging for admin actions\n```\n\nWhen the spec or ADR is ready, continue through discussion, planning, and one\nimplementation slice.\n\n```text\n/discuss docs/specs/admin-audit-logging.md\n/plan docs/specs/admin-audit-logging.md\n/implement .pi/stack-ops/plans/admin-audit-logging.plan.md\n```\n\nUse `/stack-ops status` whenever you need the current phase, active plan,\nblockers, gates, and next prompts.\n\n## Local workflow state\n\n`pi-stack-ops` separates durable repository documentation from disposable local\nworkflow artifacts.\n\nDurable artifacts belong in your repository:\n\n- Specs\n- ADRs\n- Intentional project documentation changes\n\nDisposable artifacts stay local:\n\n```text\n.pi/stack-ops/\n state.json\n plans/\n summaries/\n validation/\n snapshots/\n blockers/\n pr-bodies/\n logs/\n context-budget/\n```\n\nThese files are working artifacts for your local workflow. Review them when\nneeded, and only copy content into durable documentation when you mean to keep\nit.\n\n## Commands\n\nUse `/stack-ops` inside Pi for local workflow state and hygiene. The standalone\nCLI exposes the same actions as `stack-ops `.\n\n| Command | Description |\n| --- | --- |\n| `/stack-ops init` | Create `.pi/stack-ops/` and initialize `state.json`. |\n| `/stack-ops status` | Show phase, stack, slice, blockers, gates, and next prompts. |\n| `/stack-ops doctor` | Check required directories and local tools. |\n| `/stack-ops context-budget` | Check whether the recorded Pi session is below the context guard. |\n| `/stack-ops clean` | Remove stack-ops logs and recreate required directories. |\n| `/stack-ops clean --all` | Remove all stack-ops artifacts after confirmation. |\n\nUse `--yes` with `clean --all` only for non-interactive automation.\n\n## Agent support\n\nThe package includes namespaced Pi agents that help with the workflow. You do not\nneed to manage them directly in normal use; the prompts call on the right roles\nfor planning, writing, review, security checks, validation, readiness, and stack\noperations.\n\nThis role-based setup helps with long-running work. Instead of asking one agent\nto hold every detail in one crowded context window, `pi-stack-ops` can hand a\nfocused task to the right subagent, collect the result, update local state, and\nreturn to the next workflow step. The workflow guidance stays the same: follow\nthe spec, work one slice at a time, validate, summarize, and stop for blockers or\napproval.\n\nExamples include:\n\n- `stack-ops.spec-writer` for specs and ADRs.\n- `stack-ops.planner` for local implementation plans.\n- `stack-ops.slice-builder` for one approved slice at a time.\n- `stack-ops.security-reviewer` for security, privacy, auth, secrets, and\n dependency risk.\n- `stack-ops.bug-hunter` for regressions, failing tests, stack traces, and\n unexplained behavior.\n- `stack-ops.test-strategist` for coverage gaps, regression cases, edge cases,\n and flake triage.\n- `stack-ops.contract-reviewer` for public APIs, CLIs, schemas, configs, package\n exports, and observable behavior.\n- `stack-ops.delivery-engineer` for CI, build, packaging, versioning, and\n distribution failures.\n- `stack-ops.data-reliability-engineer`, `stack-ops.performance-engineer`, and\n `stack-ops.search-rag-engineer` for data, performance, and AI/search slices\n when the repository needs those domains.\n- `stack-ops.readiness` for deciding whether a phase, PR, slice, or stack can\n advance.\n- `stack-ops.stack-operator` for stax and GitHub mechanics after readiness.\n\n## Next steps\n\nInstall the package, run `/stack-ops doctor`, and start with `/draft` in the\nrepository where you want to create a stacked change.\n","readmeFilename":"README.md"}