compound-engineering-pi 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Every
+
+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,124 @@
+# Compound Engineering for Pi
+
+[![Build Status](https://github.com/gvkhosla/compound-engineering-pi/actions/workflows/ci.yml/badge.svg)](https://github.com/gvkhosla/compound-engineering-pi/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/compound-engineering-pi)](https://www.npmjs.com/package/compound-engineering-pi)
+
+Pi-first extension that takes the original Compound Engineering approach and makes it work smoothly in **Pi**.
+
+## 🙌 Credit to the original creators
+
+This project builds directly on the original work by **Every** and **Kieran**.
+
+- Upstream plugin (source of truth): https://github.com/EveryInc/compound-engineering-plugin
+- Compound engineering writeup: https://every.to/chain-of-thought/compound-engineering-how-every-codes-with-agents
+
+If you’re using Claude Code, Codex, OpenCode, or anything non-Pi-focused, use the upstream repo above.
+
+---
+
+## Why this exists
+
+The Every plugin is excellent, but Pi has different runtime semantics. This extension adapts the workflow for Pi so it feels native and works out of the box.
+
+### What this Pi extension adds
+
+- Native Pi package install
+- Prebuilt Pi resources (`prompts/`, `skills/`, `extensions/`)
+- Compatibility tool layer for Claude-style workflows
+- Subagent orchestration in Pi (`single`, `parallel`, `chain`)
+- MCP compatibility through **MCPorter** (`mcporter_list`, `mcporter_call`)
+
+---
+
+## Install (recommended)
+
+### 1) Install Pi
+
+- Pi project: https://github.com/mariozechner/pi-coding-agent
+- Pi package gallery: https://shittycodingagent.ai/packages
+- Discovery request opened with Pi maintainers: https://github.com/badlogic/pi-mono/issues/1480
+
+### 2) Install MCPorter
+
+```bash
+npm i -g mcporter
+```
+
+### 3) Install this extension in Pi
+
+```bash
+# after npm publish:
+pi install npm:compound-engineering-pi -l
+# fallback (works now):
+pi install git:github.com/gvkhosla/compound-engineering-pi@v0.2.3 -l
+```
+
+### 4) Reload and test
+
+```bash
+/reload
+pi -p "/workflows-plan Build a todo app"
+```
+
+Maintainer publish shortcut (first run `npm login` once):
+
+```bash
+npm run release:ship
+```
+
+---
+
+## What you get immediately in Pi
+
+- Workflow prompts like `/workflows-plan`, `/workflows-work`, `/workflows-review`, `/workflows-compound`
+- Converted skills and reviewer agents
+- Pi compatibility extension with tools:
+  - `ask_user_question`
+  - `subagent`
+  - `mcporter_list`
+  - `mcporter_call`
+
+This keeps the same compounding loop in Pi:
+
+**Plan → Work → Review → Compound**
+
+---
+
+## How MCP works here
+
+This extension uses **MCPorter** for MCP interoperability in Pi.
+
+- No assumption of Claude-native MCP runtime behavior
+- Uses `mcporter` CLI under the hood
+- Supports project/global config and bundled fallback config
+
+MCPorter project: https://github.com/steipete/mcporter
+
+---
+
+## Advanced (Pi generation workflow)
+
+If you want to regenerate Pi output from the upstream plugin manually:
+
+```bash
+bunx compound-engineering-pi install compound-engineering --to pi --pi-home ~/.pi/agent
+```
+
+---
+
+## Non-Pi usage (upstream)
+
+For all non-Pi usage and canonical plugin docs, use:
+
+- https://github.com/EveryInc/compound-engineering-plugin
+
+That includes Claude Code-native setup, canonical command/skill design, and upstream issues/roadmap.
+
+---
+
+## Learn more
+
+- Pi guide for this extension: [docs/pi.md](docs/pi.md)
+- Validation report: [VALIDATION.md](VALIDATION.md)
+- npm release checklist: [NPM_PUBLISH.md](NPM_PUBLISH.md)
+- Upstream canonical component docs: https://github.com/EveryInc/compound-engineering-plugin/blob/main/plugins/compound-engineering/README.md

package/bin/compound-engineering-pi

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "Error: Bun is required to run compound-engineering-pi. Install from https://bun.sh" >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+exec bun run "${ROOT_DIR}/src/index.ts" "$@"

package/bin/compound-plugin

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "Error: Bun is required to run compound-plugin. Install from https://bun.sh" >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+exec bun run "${ROOT_DIR}/src/index.ts" "$@"

package/compound-engineering-pi

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "Error: Bun is required to run compound-engineering-pi. Install from https://bun.sh" >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="${SCRIPT_DIR}"
+
+exec bun run "${ROOT_DIR}/src/index.ts" "$@"

package/compound-plugin

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec "${SCRIPT_DIR}/compound-engineering-pi" "$@"

package/docs/pi.md

@@ -0,0 +1,152 @@
+# Compound Engineering for Pi
+
+This guide explains how to use the Compound Engineering plugin in **Pi** with the new `--to pi` target.
+
+## TL;DR
+
+### Fast path (just works)
+
+```bash
+# 1) Install as a Pi package
+# after npm publish:
+pi install npm:compound-engineering-pi
+# fallback (works now):
+pi install git:github.com/gvkhosla/compound-engineering-pi@v0.2.3
+
+# 2) Install MCPorter (for MCP-style tool access in Pi)
+npm i -g mcporter
+
+# 3) Reload Pi resources
+/reload
+```
+
+### Converter path (advanced/custom)
+
+```bash
+bunx compound-engineering-pi install compound-engineering --to pi
+```
+
+You will get generated resources under your Pi directory:
+
+- `prompts/` (converted slash commands)
+- `skills/` (plugin skills + generated reviewer skills)
+- `extensions/compound-engineering-compat.ts` (compat tools)
+- `compound-engineering/mcporter.json` (MCPorter server config)
+
+The published package already includes prebuilt `extensions/`, `skills/`, and `prompts/` for Pi package installs.
+
+For package installs, `mcporter_list`/`mcporter_call` also fall back to a bundled config at `pi-resources/compound-engineering/mcporter.json` if no project/global config exists yet.
+
+---
+
+## Why this exists
+
+Claude Code plugins are not directly runnable in Pi.
+
+The `pi` target translates Claude plugin concepts into native Pi resources so teams can keep the same compounding workflow:
+
+**Plan → Work → Review → Compound**
+
+---
+
+## Concept mapping (easy to explain)
+
+| Claude concept | Pi equivalent |
+|---|---|
+| `commands/*.md` | `.pi/prompts/*.md` |
+| `skills/*/SKILL.md` | `.pi/skills/*/SKILL.md` |
+| `agents/*.md` | generated Pi skills in `.pi/skills/*/SKILL.md` |
+| `Task agent(args)` | `subagent` tool call (generated compat extension) |
+| `AskUserQuestion` | `ask_user_question` tool |
+| MCP server config | MCPorter config in `.pi/compound-engineering/mcporter.json` |
+
+---
+
+## Generated Pi compatibility tools
+
+The generated extension provides these tools:
+
+### `ask_user_question`
+Interactive question/choice tool for workflows that need explicit user decisions.
+
+### `subagent`
+Runs skill-based subagents through nested Pi sessions.
+
+Supports:
+- **single**: `{ agent, task }`
+- **parallel**: `{ tasks: [...] }`
+- **chain**: `{ chain: [...] }` with `{previous}` placeholder support
+
+### `mcporter_list`
+Lists tools for an MCP server via MCPorter.
+
+### `mcporter_call`
+Calls a specific MCP tool via MCPorter.
+
+---
+
+## MCP via MCPorter (instead of native MCP)
+
+Pi itself does not include native MCP runtime behavior identical to Claude Code. This target uses MCPorter as the compatibility layer.
+
+Generated config path:
+
+- Project: `.pi/compound-engineering/mcporter.json`
+- Global: `~/.pi/agent/compound-engineering/mcporter.json`
+
+You can extend this file with your own server definitions and auth headers as needed.
+
+---
+
+## Sync your personal Claude setup into Pi
+
+```bash
+bunx compound-engineering-pi sync --target pi
+```
+
+This syncs:
+- personal skills from `~/.claude/skills` (symlinked)
+- MCP servers from `~/.claude/settings.json` into Pi MCPorter config
+
+---
+
+## Recommended OSS adoption flow
+
+1. Start with side-by-side generation:
+   ```bash
+   bunx compound-engineering-pi install compound-engineering --to opencode --also pi
+   ```
+2. Validate one real workflow (`/workflows-plan` + review loop).
+3. Keep generated resources in version control for team reproducibility.
+4. Add project-specific skills gradually (don’t fork everything at once).
+5. Publish your own package presets once stable.
+
+---
+
+## Troubleshooting
+
+### `mcporter` not found
+Install globally:
+
+```bash
+npm i -g mcporter
+```
+
+### Prompts/skills not visible in Pi
+Run:
+
+```bash
+/reload
+```
+
+### Subagent calls fail
+Check:
+- target skill exists in `.pi/skills/<name>/SKILL.md`
+- nested Pi call works: `pi --no-session -p "/skill:<name> ..."`
+- permissions/sandbox rules in your environment
+
+---
+
+## One-paragraph explanation for others
+
+> We added a `--to pi` converter target that ports Compound Engineering Claude plugins into native Pi resources (prompts, skills, extension tools). Claude-only behaviors like `Task(...)` and `AskUserQuestion` are mapped to Pi compatibility tools (`subagent`, `ask_user_question`), and MCP integrations are handled through MCPorter config instead of native MCP runtime assumptions. This keeps the same compounding workflow in Pi while making it easy for open-source teams to share a reproducible setup.