Evaluate optional Herdr plugin wrapper for Pi Herd bootstrap

[nodnarbnitram]

This was generated by AI during triage.

Context

Herdr has released v1 plugin support: https://herdr.dev/docs/plugins/

Plugins are out-of-process executable workflow packages declared with herdr-plugin.toml. Herdr owns installation, manifest validation, keybindings, terminal panes, event hooks, invocation context, and socket access. The plugin command can call back into Herdr through the CLI/socket API.

This repo currently publishes Pi extensions:

• @weshipwork/pi-herdr — registers the in-Pi herdr tool when running inside Herdr.
• @weshipwork/pi-herd — starts the Delegator-side read-only Transcript mirror bridge and launches pi-herd-viewer panes.
• @weshipwork/pi-subagents — forked Subagent runtime with the read-only mirror seam exposed through globalThis.__piSubagentsMirrorService.

Current recommendation

Do not migrate Mirror mode or the Pi extensions into Herdr plugins. Mirror mode depends on Pi in-process extension state and the globalThis.__piSubagentsMirrorService observation seam. Herdr plugins are better suited as an additive launcher/bootstrap surface.

Proposed follow-up

Investigate and, if still useful, add a small optional Herdr plugin wrapper that bootstraps the existing Pi extension workflow.

Potential plugin responsibilities:

• Launch a Delegator Pi session with the recommended extension set:
  • npm:@weshipwork/pi-subagents
  • npm:@weshipwork/pi-herd
  • npm:@weshipwork/pi-herdr
• Open or prepare a Herdr workspace/tab layout for Herd work.
• Provide a command/action such as “Start Pi Herd Mirror mode”.
• Use HERDR_BIN_PATH when calling Herdr from plugin commands.

Potential repo shape:

plugins/pi-herd-bootstrap/
├─ herdr-plugin.toml
├─ README.md
└─ scripts/...

Non-goals

• Do not move Subagent execution out of the Delegator Pi process.
• Do not make mirror panes interactive control surfaces.
• Do not replace the Pi extension packages with a Herdr plugin.
• Do not store durable state or credentials in the plugin root; use Herdr plugin config/state directories if needed.

Documentation/architecture work

• Add docs explaining the difference between:
  • Pi extensions = runtime/control surface.
  • Herdr plugin = optional bootstrap/launcher surface.
• Add an ADR before changing distribution architecture. The repo instructions mention docs/adr/, but this checkout currently has no docs/adr directory.
• Consider a small hardening change in existing code: invoke Herdr through process.env.HERDR_BIN_PATH ?? "herdr" where we currently call pi.exec("herdr", ...).

Acceptance criteria

• A short design note or ADR decides whether to ship a Herdr plugin wrapper.
• If accepted, the wrapper has a minimal herdr-plugin.toml, README, and bootstrap command.
• Existing Pi extension behavior remains unchanged.
• Docs make the install paths explicit:
  • Pi extension packages via pi install npm:@weshipwork/...
  • optional Herdr plugin via herdr plugin install WeShipWork/threeonefour/plugins/...