# 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 (after the v0.3.0 GitHub release):
pi install git:github.com/gvkhosla/compound-engineering-pi@v0.3.0

# 2) Install MCPorter (for MCP-style tool access in Pi)
npm i -g mcporter

# 3) Reload Pi resources
/reload
```

### Converter path (advanced/custom)

Prefer the upstream converter package:

```bash
bunx @every-env/compound-plugin install compound-engineering --to pi
```

The local `compound-engineering-pi` CLI remains available for compatibility, but upstream is the canonical place for converter behavior.

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 compatibility `prompts/` for Pi package installs.

This repo now tracks the newer upstream Compound Engineering skill set while keeping the older `/workflows-*` prompts as Pi-friendly compatibility aliases.

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

Model selection in the compatibility tool:
- `model` is optional and forwarded to `pi --model`. Use a fuzzy name such as `haiku`, a `provider/modelId`, or a model with a `:thinking` suffix.
- In parallel and chain modes, a top-level `model` is the default for entries that omit their own `model`.
- An entry's explicit `model` wins over the top-level default. An empty or whitespace-only string deliberately clears that default; it does not inherit it.
- Without an override, the child Pi process uses its configured default. The parent's active session model is not automatically inherited.
- Model names are trimmed and shell-quoted. Selection and authentication are handled by the installed Pi CLI; the model must be available there.

Example tool arguments (these are JSON inputs to `subagent`, not shell commands):

```json
{ "agent": "repo-research-analyst", "task": "Find relevant code", "model": "haiku" }
```

```json
{
  "model": "haiku",
  "tasks": [
    { "agent": "repo-research-analyst", "task": "Find relevant code" },
    { "agent": "kieran-typescript-reviewer", "task": "Review correctness", "model": "sonnet" }
  ]
}
```

```json
{
  "model": "haiku",
  "chain": [
    { "agent": "repo-research-analyst", "task": "Find relevant code" },
    { "agent": "kieran-typescript-reviewer", "task": "Review these findings: {previous}", "model": "sonnet" }
  ]
}
```

If `pi-subagents` is installed, its own tool/schema handles model selection instead.

Behavior notes:
- **single mode returns the full subagent output** in the final tool result
- **chain mode returns the final step output** plus a step summary
- **parallel mode returns a compact summary by default**; pass `includeOutputs: true` to include full output for each completed subagent
- if you install a richer `pi-subagents` package, this compatibility extension will automatically step aside and let that tool handle subagents instead

### `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

---

## Keeping this package synced with upstream

```bash
bun run sync:upstream
```

By default this pulls from a sibling checkout at `../compound-engineering-plugin`, refreshes the vendored `plugins/compound-engineering` snapshot, and regenerates the bundled Pi skills/MCPorter config.

Maintainer rule: changes to conversion behavior, plugin content, or target semantics should be made upstream first. This repo is the Pi distribution layer.

## 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

### I want to see more subagent output
- single subagents now return their full output in the tool result
- chain runs return the final step output plus a step summary
- parallel runs can return all outputs with `includeOutputs: true`
- if you prefer a richer live subagent UI, install `pi-subagents`; `compound-engineering-pi` will automatically defer to it when present

---

## 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.