Summary

Pi becomes a first-class CE target on par with Claude Code and Codex: native parallel subagent dispatch, a polished blocking user-question UX, and Pi-native agent resolution. The install now delegates these primitives to two well-maintained community extensions instead of shipping our own bridge. Issue #449 (the subagent tool collision at Pi startup) resolves as a consequence of the architectural shift, not the primary work.

Before this PR, Pi users got a bundled compat extension that collided with the most popular community subagent plugin and blocked the whole install from loading. Even when it did load, dispatch ran through our homegrown subagent tool that shelled out to pi --no-session -p per call — no real parallelism, a thin question-prompt UX, and an awkward mismatch with how Pi itself expects agents to be structured.

After this PR, a standard Pi install plus two one-line extension installs unlocks the same multi-agent workflows CE users already get on Claude Code and Codex. Dispatch runs as Pi-native parallel sessions. Blocking questions render through an overlay that mirrors Claude's AskUserQuestion UX rather than a prose fallback. Our converter ships zero Pi-specific runtime TypeScript — the install is skills, agents, and a README.

What Pi users get

Why delegate to community extensions

The Pi ecosystem has matured since we shipped our compat extension. nicobailon/pi-subagents is the dominant community subagent plugin — actively maintained, and its tool surface is a strict superset of what we shipped (adds worktree isolation, count: N fan-out, chain with {previous} templating, async runs with status inspection). edlsh/pi-ask-user ships a richer blocking-question UX than our thin wrapper (per-option descriptions, multi-select, optional comments, timeout).

Rolling our own means competing with their maintenance, risking collisions indefinitely, and shipping a worse experience. Adopting them means Pi users get the same compound-engineering workflows backed by community-grade infrastructure instead of our homegrown bridge, and we stop maintaining duplicate code we never had the budget to make excellent.

Install contract

pi install npm:pi-subagents    # required — provides `subagent` for parallel agent dispatch
pi install npm:pi-ask-user     # recommended — provides `ask_user`; skills fall back to numbered prose when absent
bunx @every-env/compound-plugin install compound-engineering --to pi

The pi-subagents prereq is genuinely required — skills that dispatch parallel agents (every review workflow, ce-plan, ce-brainstorm, ce-compound, ce-agent-native-audit) rely on the subagent tool existing. The pi-ask-user prereq is recommended — skills with blocking questions degrade gracefully to numbered-list prose when the tool isn't installed, but the overlay UX is meaningfully better.

Install layout

On upgrade from v2.x, the install-manifest diff sweeps the old agents-as-skills directories and the compat extension automatically. A belt-and-suspenders sweep in cleanupKnownLegacyPiArtifacts covers pre-manifest installs and stale compound-engineering mcporter.json files.

Source-side enumeration replaces the token regex

With the token-rewrite safety net gone (AskUserQuestion → ask_user_question dropped from claude-to-pi.ts), every skill that asks a blocking question or dispatches a subagent now enumerates the Pi tool inline alongside Claude, Codex, and Gemini. The pattern matches how Codex and Gemini conversion already worked: source-side enumeration, no runtime token swap.

• Every AskUserQuestion enumeration across 40 skill files gained `ask_user` in Pi (requires the `pi-ask-user` extension).
• ce-doc-review/SKILL.md:124 now lists Agent / spawn_agent / subagent for subagent dispatch, and fixes a pre-existing spawn in Codex → spawn_agent typo along the way.
• ce-agent-native-audit/SKILL.md:37 now enumerates per-platform equivalents (Agent with subagent_type: Explore in Claude Code, spawn_agent with agent_type: "explorer" in Codex, subagent with agent: "scout" in Pi) instead of hardcoding the Claude-only form.
• plugins/compound-engineering/AGENTS.md (plugin authoring guide) gains a new Cross-Platform Sub-Agent Dispatch section that formalizes the enumeration pattern and the "prefer ce-shipped agents over platform built-ins" rule, with an exception for built-ins worth keeping (like Claude's Explore).

Backward compatibility

The install-manifest schema gained an agents: string[] field. Older v2.x manifests do not have it; the reader defaults missing or invalid values to [] so the writer still validates old manifests cleanly. On upgrade, the diff-based cleanup tracks both old and new shapes without a migration step.

Users on pre-manifest installs (very early CE-on-Pi adopters) get both the legacy compound-engineering-compat.ts extension and any stale compound-engineering/mcporter.json swept via hardcoded allowlists in src/targets/pi.ts. Generic plugins that declare mcpServers still produce a Pi mcporter.json via the preserved convertMcpToMcporter path — only the plugin-specific cleanup runs on the compound-engineering namespace.

Frontmatter guard for issue #449's second bug

Issue #449 also reported name "ce:brainstorm" does not match parent directory "ce-brainstorm". Our current source is clean (all ce-* names), but a new test in tests/frontmatter.test.ts asserts every skills/*/SKILL.md has a name: that matches its parent directory and contains only [a-z0-9-]. Any regression to a namespaced form fails at CI rather than at a user's Pi startup.

Verification

Verified end-to-end against a local Pi install at ~/.pi/agent.

Post-install file layout (after upgrading from v2.68.x with 5 unrelated user skills already in place):

• ~/.pi/agent/agents/ — 51 CE agents (ce-correctness-reviewer.md, ce-adversarial-reviewer.md, ce-repo-research-analyst.md, …).
• ~/.pi/agent/skills/ — 35 CE skills (34 ce-* + lfg), down from 85 as agents-as-skills got swept.
• ~/.pi/agent/extensions/ — empty. Community pi-subagents and pi-ask-user live at Pi's own extension registry, not our plugin install path.
• Install manifest reports skills: 35, agents: 51, extensions: 0.
• 5 user-owned symlinked skills (agent-browser, agentcore, dogfood, electron, find-skills) not touched.

Pi startup is clean. No Failed to load extension "compound-engineering-compat.ts" error. Extensions on startup:

[Extensions]
  pi-ask-user, pi-subagents, pi-subagents:notify.ts

Parallel subagent dispatch works end-to-end. Asked Pi to run subagent(agent="ce-repo-research-analyst", task="Scope: technology. Summarize what tech stack this project uses.") three times in parallel. All three resolved to ~/.pi/agent/agents/ce-repo-research-analyst.md, ran 25 to 33 seconds each with 5 to 6 tool calls each as Pi-native concurrent sessions, and produced consistent accurate repo-research output. This validates three things at once: (a) pi-subagents resolves our agent files by filename, (b) the agent's Scope: scoped-invocation pattern survives the Pi conversion, (c) parallel fan-out runs as real concurrent sessions, not serialized subprocesses.

ask_user dispatch via pi-ask-user also fires correctly for blocking questions.

Test plan

• bun test — 902 tests pass.
• bun run release:validate — clean.
• End-to-end verification on a real Pi install is captured above.