Add artifact vault contents

projects/dotfiles/004-pi-subagents-pi-extension-ecosystem-research.md

@@ -0,0 +1,77 @@
+---
+status: resolved
+parent: "[[002-pi-subagents-map]]"
+blocked-by: []
+tags:
+  - ticket/research
+---
+
+# Pi extension ecosystem research
+
+## Question
+
+What Pi extension APIs, official examples, pi-fork work, and discoverable third-party Pi subagent or popular extensions exist, and do any provide neutral subagent spawning primitives suitable for Herdr-compatible use?
+
+## Resolution
+
+## Findings
+
+Pi extensions can register tools, commands, shortcuts, flags, event handlers, UI components, message renderers, providers, and resource paths.
+They are TypeScript modules auto-discovered from `~/.pi/agent/extensions` and project-local `.pi/extensions`, with package distribution through npm or git.
+Citation: `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md`.
+
+Pi extension commands have session-control APIs that can create, fork, switch, and message Pi sessions, but the official subagent example instead spawns separate Pi processes.
+The docs warn that background processes should not be started from the extension factory, and should instead be scoped to session events, commands, tools, or other needful hooks.
+Citation: Pi `docs/extensions.md`, especially `ExtensionCommandContext`, `ctx.newSession`, `ctx.fork`, `ctx.switchSession`, and long-lived resource guidance.
+
+The official Pi examples include `examples/extensions/subagent/`.
+It registers a `subagent` tool, discovers user and project Markdown agent definitions, supports single, parallel, and chained modes, and launches a separate `pi --mode json -p --no-session` process for each subagent invocation.
+It also ships sample agents named `scout`, `planner`, `reviewer`, and `worker` plus workflow prompts.
+Citation: Pi `examples/extensions/subagent/README.md`, `index.ts`, and `agents.ts`.
+
+The official subagent example is useful mechanism, but it violates the desired policy boundary if adopted as-is because it ships opinionated sample agent definitions and workflow prompts.
+The core code separates discovery from execution well enough to be mined or adapted, but an adopted extension should not bundle named roles unless those files are excluded from installation.
+Citation: Pi `examples/extensions/subagent/README.md` structure and sample-agent table.
+
+A targeted GitHub search found several third-party Pi extensions, including `mjakl/pi-subagent`, `nicobailon/pi-messenger`, `nicobailon/pi-intercom`, `owainlewis/pi-extensions`, and others.
+`mjakl/pi-subagent` is the closest off-the-shelf subagent extension: it supports Markdown-defined agents, fresh or persistent child sessions, parallel calls, parent-context seeding, depth/cycle guards, streaming updates, rich rendering, and Pi 0.80.5 or newer.
+Citation: GitHub search API result for `"pi-coding-agent" extension` and `/tmp/pi-ext-research/pi-subagent/README.md` cloned from `github.com/mjakl/pi-subagent`.
+
+`mjakl/pi-subagent` is not purely neutral as packaged.
+Its README says that if no agents exist, it creates a starter `explore` agent automatically, and it documents example `explore` and `review` definitions.
+It is closer to the desired boundary than extensions that ship full crews, but automatic starter creation is still opinionated configuration unless it can be disabled or patched.
+Citation: `/tmp/pi-ext-research/pi-subagent/README.md`.
+
+`mjakl/pi-subagent` spawns separate Pi child processes in headless RPC mode, sets `PI_OFFLINE=1`, and inherits relevant parent CLI configuration.
+That design is good for frequent context-isolation and latency, but the README does not claim Herdr integration.
+Citation: `/tmp/pi-ext-research/pi-subagent/README.md`, technical reference section.
+
+`nicobailon/pi-messenger` is a broader multi-agent coordination and crew orchestration extension.
+It ships crew agents, a crew skill, planner/worker/reviewer flows, team roles, approval gates, shared presence, messaging, file reservations, and project-local crew state.
+It is therefore too opinionated for the requested subagent primitive, though pieces such as presence and orchestration may be informative.
+Citation: `/tmp/pi-ext-research/pi-messenger/README.md`.
+
+`nicobailon/pi-intercom` is a same-machine session-to-session messaging extension, not a subagent spawner.
+It can integrate with a subagent extension by giving delegated child agents a `contact_supervisor` tool when bridge metadata is supplied.
+It could complement a subagent solution, but it does not satisfy spawning or Herdr visibility by itself.
+Citation: `/tmp/pi-ext-research/pi-intercom/README.md`.
+
+`owainlewis/pi-extensions` contains experimental workflow automation and status-message extensions rather than a neutral subagent primitive.
+Its context-isolated workflow focuses on compaction, testing, review, and iteration inside a workflow command.
+Citation: `/tmp/pi-ext-research/pi-extensions/README.md`.
+
+## Implications
+
+No researched off-the-shelf Pi subagent extension clearly satisfies all stated criteria today.
+The best candidate for adaptation is `mjakl/pi-subagent`, because it already solves repeated isolated child Pi invocations, persistent child sessions, parallelism, and context control.
+Its likely gaps are Herdr visibility and automatic starter/opinionated agent behavior.
+
+The official Pi subagent example is a strong reference implementation but not a direct adoption target.
+It is useful for understanding Pi's supported APIs and minimal spawning mechanics.
+
+A new or adapted extension should keep subagent type definitions out of the extension package, avoid automatic starter-agent creation unless explicitly configured, and add a Herdr-aware spawning mode or bridge.
+
+## Limitations
+
+GitHub discovery was targeted rather than exhaustive.
+The `pi-fork` term did not resolve to a clearly authoritative source during this pass, so it remains an evidence gap unless a specific repository or package name is provided.