pi-compound-engineering

Compound Engineering for Pi: brainstorm, plan, work, review, and compound.

pi-compound-engineering brings Every Inc.'s compound-engineering-plugin to Pi. It mirrors the upstream plugin's ce-* skills and agents so you can use the same compound engineering workflow in Pi that the CE team uses in Claude Code and Codex.

[!WARNING] Pi packages can execute arbitrary code through extensions. Review package source before installing any third-party Pi package.

Features

• ce-* skills — the full set of upstream CE skills: planning, code review, work execution, brainstorming, debugging, sessions, worktrees, and more.
• ce-* agents — the full set of upstream CE reviewer and analyst personas, registered as first-class Pi subagents (visible in subagent action:list). Conditional personas (those an orchestrating skill selects based on diff context) are included; invoking one outside its trigger produces a no-op review rather than corruption, so the ce- prefix and the persona description are the only guards.
• /ce-status — a slash command that reports the synced CE version, skill/agent counts, and which peer packages are detected.
• One-shot dependency warnings — gentle notifications on first session start when peer packages are missing.
• Skipped-postinstall warning — fires when the skills/ and agents/ directories are empty (the --ignore-scripts failure mode) and tells you exactly how to recover.
• Skill resource paths — bundled CE skill resources like scripts/, references/, and assets/ are rewritten at conversion time to resolve under skills/<skill-name>/..., matching the package-root base path Pi injects for package-sourced skills. No runtime guidance is needed.

The exact skill and agent list is visible in Pi's startup [Skills] list after install.

Installation

Install from npm:

pi install npm:pi-compound-engineering
pi install npm:pi-subagents    # required for full functionality
pi install npm:pi-ask-user     # recommended for interactive skills

Install project-locally with Pi's -l flag:

pi install -l npm:pi-compound-engineering
pi install -l npm:pi-subagents
pi install -l npm:pi-ask-user

During local development from this monorepo:

pi install /path/to/pi-mono/packages/pi-compound-engineering

For a one-off test run without installing:

pi -e /path/to/pi-mono/packages/pi-compound-engineering

The install runs two lifecycle scripts:

1. preinstall (scripts/stage.mjs) downloads the pinned CE release tarball, verifies its SHA256, extracts it, runs the pure-Node converter, and stages the result in $TMP/.
2. postinstall (scripts/commit.mjs) moves the staged content into the install directory.

Skills are available on the next Pi launch. The tar binary is required (universally available on macOS, Linux, and WSL; not native Windows). A working network connection is required at install time.

Usage

The ce-* skills and agents are available in any Pi session after install. The exact list is visible in the startup [Skills] list.

Run /ce-status to see the synced CE version, skill/agent counts, and peer-package detection.

If pi-subagents or pi-ask-user is missing, the extension emits a one-shot warning on first session start telling you how to install it. The package is fully usable without them; the skill bodies already contain fallback text (inline execution, numbered options in chat).

Peer packages

This package uses two optional Pi extensions, which are not bundled. Install them separately:

• pi-subagents — provides the subagent tool. Required by skills that dispatch parallel agents. Without it, those skills fall back to inline execution.
• pi-ask-user — provides the ask_user tool. Used by interactive skills. Without it, those skills fall back to numbered options in chat.

Both are first-class Pi packages with their own release cadence. The package is fully usable without them.

How it works

This package is a recipe-only loader. The skills/ and agents/ directories are not in the npm tarball; they are produced at install time from the upstream CE release.

pi-mono repo (this package)
  ├── src/                         # TypeScript: extension, telemetry, etc.
  ├── scripts/
  │   ├── stage.mjs                # preinstall: download + verify + convert to staging
  │   ├── commit.mjs               # postinstall: move staging to final install dir
  │   ├── converter.mjs            # pure-Node port of CE's claude-to-pi.ts
  │   ├── verify.mjs               # structure check (counts + representative content)
  │   └── expected-sha256.txt      # SHA256 of the pinned CE release tarball
  ├── package.json                 # "preinstall" + "postinstall" lifecycle
  └── (no committed skills/ or agents/ — generated at install time)

  User machine, at `pi install` time
  ├── ~/.pi/agent/npm/pi-compound-engineering/   # the install dir
  │   ├── src/, scripts/, package.json           # what was in the tarball
  │   ├── skills/                                # GENERATED by postinstall
  │   ├── agents/                                # GENERATED by postinstall
  │   └── THIRD-PARTY-NOTICES                    # GENERATED by postinstall

The two-phase preinstall + postinstall design gives npm-native update safety: if preinstall fails (network, SHA, converter bug, structure check), npm aborts the install/update and the previous version remains untouched.

The converter (scripts/converter.mjs) is a pure-Node ESM port of the upstream CE-to-Pi converter. It has no npm dependencies — it runs with node alone, which is critical because the install-time scripts cannot rely on a working node_modules/.

At conversion time, the converter rewrites each skill's backtick-wrapped references/, scripts/, and assets/ paths to skills/<skill-name>/... so they resolve against the package-root base path Pi injects for package-sourced skills. npm run verify asserts every rewritten ref resolves on disk. The package manifest also declares a subagents.agents entry so the ce-* personas register as first-class Pi subagents.

Troubleshooting

skills/ and agents/ are empty after install

If you used npm install --ignore-scripts, the postinstall is skipped. Re-run the install without the flag:

pi install npm:pi-compound-engineering

The lifecycle is idempotent — re-running is safe and will populate the install dir.

Behind a corporate proxy or offline

Set the CE_TARBALL_PATH environment variable to a local path of the upstream tarball (the pinned version is in scripts/expected-sha256.txt), then re-run the install:

CE_TARBALL_PATH=/path/to/compound-engineering-plugin.tar.gz pi install npm:pi-compound-engineering

CI / air-gapped installs

The preinstall is a no-op when no CE_TARBALL_PATH is set and the environment looks like CI (CI, GITHUB_ACTIONS, GITLAB_CI, CIRCLECI, TRAVIS, JENKINS_URL, BUILDKITE, APPVEYOR, DRONE, TEAMCITY_VERSION, NETLIFY, VERCEL, CODESPACES, BITBUCKET_BUILD_NUMBER, TF_BUILD) or PI_OFFLINE=1 is set. In that case the lifecycle completes successfully with an empty skills/ + agents/ dir, the install no longer aborts the whole workspace npm ci, and the skipped-postinstall warning fires on the next Pi launch with the recovery instruction. Force a network attempt by unsetting the relevant env var and reinstalling.

Development

This package is source-distributed. Pi loads the TypeScript extensions directly.

Requirements:

• Node.js >= 20.6.0
• npm
• tar binary (macOS, Linux, WSL)

Windows is not supported out of the box. The preinstall shells out to tar to extract the upstream tarball, and Node 20's tar shim has different flag behavior on Windows. Use WSL or a Linux VM.

npm install
npm run check
npm run pack:dry-run

The structure check (npm run verify) downloads the pinned CE release and asserts the converter output is correct (counts + representative content). It runs in CI and on demand.

Contributing

Contributions are welcome. See CONTRIBUTING.md for development workflow and pull request guidelines.

Security

Please report security issues privately. See SECURITY.md.

License

MIT. See LICENSE.

The synced content from compound-engineering-plugin is also MIT. See NOTICE and the generated THIRD-PARTY-NOTICES in the install directory for the full attribution inventory.