omp packages

pi-herdr-roles0.1.0

Optional general-purpose role pack and planning/review workflows for pi-herdr-agents

GitHub Actions Published 28 days ago MIT ~237 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Did it work for you?

Result

One report per person. A new report replaces your old one.

Reports 0

No reports yet.

Readme

pi-herdr-roles

Version 0.1.0. Requires pi-herdr-agents >=3.0.0, the first published role-free host, installed and enabled through Pi separately. See compatibility for the tested revisions.

An optional Pi role pack for pi-herdr-agents. It supplies six general-purpose subagent roles plus the /plan and /skill:orchestrate workflows that pi-herdr-agents previously bundled. It has no privileged status: it registers through the same public role-pack protocol as any other pack, and project or global role definitions still override it.

Contents

Resource Kind Notes
scout role Read-oriented codebase reconnaissance leaf.
planner role Interactive planner; may spawn scout.
worker role Implements one complete task; commits only when asked.
reviewer role Evidence-backed leaf reviewer.
adversarial-reviewer role Multi-wave review coordinator that launches reviewer children.
visual-tester role Optional visual QA; needs the external chrome-cdp skill.
/plan <what to build> command Scout → planner → workers → review workflow.
plan skill The same workflow as a native Pi skill (/skill:plan).
orchestrate skill Bounded fan-out review with parent synthesis, plus its adversarial procedure and helper.

Every role a workflow launches ships in this pack. The pack has no dependency on pi-herdr-pstack.

Prerequisites and installation

pi-herdr-agents is the execution host. It is declared as a peer dependency, but a peer declaration does not activate an extension: install and enable both packages through Pi. After the 0.1.0 release lands on npm, install the host first and then this pack:

pi install npm:pi-herdr-agents   # >=3.0.0
pi install npm:pi-herdr-roles

Until then, install from the GitHub repository or a local path instead (for example pi install git:github.com/giuseppecrj/pi-herdr-roles).

Do not install this beside a pi-herdr-agents version that still bundles these roles or its own /plan and orchestrate; see compatibility.

Without pi-herdr-agents loaded, /plan refuses to start and explains the missing subagent tool. It never falls back to a bare agent or installs anything.

Optional chrome-cdp

visual-tester declares skills: chrome-cdp and expects a project-provided scripts/cdp.mjs. Neither this pack nor pi-herdr-agents ships or installs them. Without them, the role reports a blocked visual test instead of guessing.

/plan delivery

/plan <task> reads skills/plan/SKILL.md from the installed package, strips its frontmatter and sends one literal user message:

<skill name="plan" location="/installed/path/skills/plan/SKILL.md">
…skill body…
</skill>

<task>

This preserves the former host wrapper exactly. It does not rely on slash-text expansion. /skill:plan uses Pi's native skill expansion instead.

Worktree guidance

pi-herdr-agents no longer warns about specific role names. The equivalent recommendations now live with the roles:

  • scout and reviewer are read-oriented and normally do not need a new worktree. Use an ordinary pane; to inspect an existing worker result, start them in the retained worktree path.
  • adversarial-reviewer coordinates read-oriented reviewers and does not write artifacts in the reviewed checkout. It normally uses an ordinary pane.
  • Herdr worktree workspaces persist until explicitly removed.

A read, bash allowlist is not read-only: Bash can modify files. These are role conventions, not a sandbox.

Development

npm install          # .npmrc disables automatic peer installation
npm run check        # typecheck, lint, format:check, test

Tests use only test-owned temporary agent, home and project directories, the pinned @earendil-works/pi-coding-agent@1.0.3 dev dependency CLI, and a deterministic offline faux provider. They never edit your Pi settings.

Variable Effect
PI_HERDR_AGENTS_HOST Role-free host package root for combined-host RPC checks; role-free expectations always apply, so a legacy bundled host fails. Skipped when unset.
PI_HERDR_AGENTS_LEGACY_HOST Opt-in pre-extraction host root for separate legacy bundled-role characterization; skipped when unset.
PI_HERDR_AGENTS_SOURCE pi-herdr-agents Git checkout for byte-level provenance reconstruction. Defaults to a sibling ../pi-herdr-agents when it contains the source commit; skipped otherwise.
PI_BIN Alternative Pi executable for RPC tests.

The faux provider only drives tool calls deterministically. Passing tests are not evidence that a live model follows the role or skill prose.

The review evaluation corpus moved with the workflow; see review evaluation.

Release

0.1.0 is the first public release. A GitHub Actions workflow publishes each stable version bump on main to npm with trusted publishing. See RELEASING.md and CHANGELOG.md.

Provenance and license

Moved files and their exact source revision are listed in provenance. MIT; see LICENSE and third-party notices.