pi-herdr-agents 0.0.2 → 0.0.4

package/CONTEXT.md

@@ -20,6 +20,22 @@ _Avoid_: Evaluated metadata, inferred policy
 A mandatory exact `provider/model` reference and thinking level declared in workflow metadata; every execution node must resolve to one of these approved runtimes. Missing values fail preparation rather than inheriting parent or role defaults. The first workflow supports Pi-backed agents only; existing public Claude subagents remain unchanged.
 _Avoid_: Runtime tiers, silent fallback, inherited runtime, v1 Claude workflow adapter
 
+**External CLI runtime adapter**:
+A runtime-specific module selected by a known local role `cli` value. The MVP dispatches `cli: claude` to the built-in Claude adapter; a future registry needs a proven second CLI.
+_Avoid_: Raw flag template, plugin system before a second CLI
+
+**Adapter permission policy**:
+The runtime adapter owns its fixed vendor flags for the MVP. A local role selects the CLI, not raw flags or a policy profile.
+_Avoid_: Implied permission bypass, raw flag values
+
+**Adapter seam**:
+`index.ts` retains pane, worktree, lifecycle, and delivery ownership. The Claude adapter owns Claude command construction, completion/result extraction, transcript copying, and workspace cleanup.
+_Avoid_: Vendor behavior in the shared lifecycle
+
+**Runtime dispatch**:
+The core validates a role's `cli` value before pane creation and dispatches each known value to its internal adapter. The MVP recognizes `claude` only; unknown values fail closed.
+_Avoid_: Silent Pi fallback, speculative runtime registry
+
 **Run journal**:
 The runner-owned append-only `run.jsonl` that starts with approval binding the workflow-script hash, canonical repository identity, and committed base, then records observed node calls and results. Exactly one terminal event contains the bounded runtime envelope; a following delivery event references it without duplicating the task result.
 _Avoid_: User-authored plan, mutable audit log, duplicated result

package/README.md

@@ -65,7 +65,7 @@ Use `pi install -l npm:pi-herdr-agents` for a project-local installation, or try
 pi -e npm:pi-herdr-agents
 ```
 
-Pi packages execute with your user account's full system access. Review the package source before installation. Claude CLI children always launch with `--dangerously-skip-permissions`, so those runs skip Claude's interactive permission prompts.
+Pi packages execute with your user account's full system access. Review the package source before installation. A locally installed Claude CLI adapter launches with `--dangerously-skip-permissions`, so those runs skip Claude's interactive permission prompts.
 
 After the one-time first-package bootstrap, changing the `package.json` version on `main` automatically publishes to npm and creates the matching Git tag and GitHub Release. For bootstrap authentication, versioning, verification, and troubleshooting, see [RELEASING.md](RELEASING.md).
 
@@ -144,7 +144,7 @@ This package uses five distinct concepts:
   dependencies of roles or workflows, not subagent definitions.
 - A **runtime** is how an invocation executes: Pi or an external CLI, plus its
   model and thinking policy.
-- An **adapter** is a hidden runtime-specific definition used by a workflow.
+- An **adapter** is a hidden runtime-specific definition supplied locally or optionally used by a workflow.
 
 See [ADR-0002](docs/adr/0002-agent-workflow-skill-runtime-taxonomy.md) for the
 accepted decision, rationale, migration boundaries, and evidence.
@@ -157,7 +157,7 @@ The current workflow inventory is:
 | Iteration | `/iterate` | Opens one interactive full-context Pi fork and returns its completion summary. |
 | Side question | `/btw`, `/btw-close` | Opens one replaceable interactive Pi side session; its answer stays outside the parent transcript. |
 | Approved review runner | `herdr_workflow` (low-level control tool) | Validates and runs exact approved project-local JavaScript with bounded read-only Pi reviewers. The bundled `orchestrate` skill authors this first-flow topology. |
-| Adversarial review | `adversarial-reviewer` | Transitional workflow implementation that runs Pi reviewer passes plus the hidden Claude CLI adapter and writes `.reviews/...` artifacts. It remains visible and launchable until a dedicated workflow surface replaces it. |
+| Adversarial review | `adversarial-reviewer` | Transitional workflow implementation that selects three distinct authenticated Pi runtimes for generic reviewer passes, preferring provider diversity; it writes `.reviews/...` artifacts. It remains visible and launchable until a dedicated workflow surface replaces it. |
 
 ### Bundled visible definitions
 
@@ -169,15 +169,20 @@ The current workflow inventory is:
 | **reviewer** | Leaf agent role | Config, then parent | Reviews changes for correctness, security, and maintainability. |
 | **visual-tester** | Leaf agent role | Config, then parent | Performs visual QA through the `chrome-cdp` skill. |
 | **poteto** | Coordinator agent role | Config, then parent | Autonomously investigates, edits minimally, delegates independent work, and verifies. |
-| **adversarial-reviewer** | Transitional workflow implementation | Grok + GPT + Claude | Runs evidence-backed Optimizer and Skeptic review passes. |
+| **adversarial-reviewer** | Transitional workflow implementation | Three distinct authenticated Pi model IDs, preferring provider diversity | Runs evidence-backed Optimizer and Skeptic review passes through generic `reviewer` children. |
 
-`claude-reviewer` is an internal Claude CLI adapter. Discovery hides it, but
-workflows can still load and invoke it by exact name. Its CLI and the Claude pass
-in adversarial review require `claude` and always add `--dangerously-skip-permissions`;
-adversarial review also requires live authenticated XAI/Grok and OpenAI Codex
-model IDs. Optional prerequisites fail closed and are not bundled:
+Bundled definitions are portable Pi roles. Vendor-specific external CLI adapters
+are local or optional definitions, not bundled roles. The existing external CLI
+path supports a local hidden Claude adapter (`cli: claude`) and always adds
+`--dangerously-skip-permissions`; it does not provide an adapter registry or
+Cursor/OpenCode support. Put an adapter in
+`$PI_CODING_AGENT_DIR/agents/` or `.pi/agents/` with
+`disable-model-invocation: true` when direct exact-name invocation needs it.
+
+Optional prerequisites fail closed and are not bundled:
 
 - `visual-tester` needs an external `chrome-cdp` skill that provides `scripts/cdp.mjs`.
+- `adversarial-reviewer` needs three distinct exact authenticated Pi model IDs; it prefers IDs from different providers when available.
 - `/plan` uses the bundled scout and planner roles and records ordered tasks in
   `plan.md`; it does not require a researcher role, todo tool, or `write-todos` skill.
 
@@ -859,7 +864,7 @@ herdr
 pi
 ```
 
-Other multiplexers and terminal backends are not supported. Worktrees provide Git checkout isolation only, not process or security isolation; child agents and installed Pi packages run with your user's filesystem and command permissions. Claude CLI children always launch with `--dangerously-skip-permissions` and therefore skip Claude's interactive permission prompts.
+Other multiplexers and terminal backends are not supported. Worktrees provide Git checkout isolation only, not process or security isolation; child agents and installed Pi packages run with your user's filesystem and command permissions. Locally configured Claude CLI adapters always launch with `--dangerously-skip-permissions` and therefore skip Claude's interactive permission prompts.
 
 ---
 

package/RELEASING.md

@@ -4,13 +4,9 @@ GitHub Actions publishes this package when the version in `package.json` changes
 
 The published version must be unique on npm.
 
-## Why the first public version is 0.2.0
+## Public versioning
 
-`0.2.0` is the initial release of the public npm package `pi-herdr-agents`.
-
-- Repository tags `v0.1.0`–`v0.1.5` belong to inherited upstream history and are not present in this clean repository.
-- Product work is already on the 0.2 feature line (async subagents, approved review workflows, bundled orchestration skill).
-- Starting the new package name at `0.1.0` would understate that feature line; reusing `0.1.x` would collide with inherited numbering.
+`0.0.1` was a manual bootstrap publication that established the npm package. `0.0.2` is the first release published through the trusted GitHub Actions workflow and is the current public baseline.
 
 Do not design a release that creates a GitHub Release without a successful npm publish for a new version. The workflow publishes first, then tags and creates the GitHub Release.
 
@@ -62,30 +58,19 @@ After the package exists on npm, steady-state releases use npm trusted publishin
 4. Confirm the workflow uses the exactly pinned Node `26.3.0`, whose bundled npm supports trusted publishing.
 5. Publish stays tokenless: `npm publish --access public --provenance`.
 
-When the repository secret `NPM_TOKEN` is absent, the publish step unsets `NODE_AUTH_TOKEN` and relies on OIDC. Once the package exists, the workflow fails if `NPM_TOKEN` is still configured, so steady-state releases cannot silently keep using the bootstrap credential.
-
-### First-package bootstrap
-
-Trusted publishers are configured on an existing npm package. The first publish of `pi-herdr-agents` therefore needs a short-lived granular npm token once, and must go through the Actions workflow so provenance is GitHub-backed:
-
-1. Create a granular access token on npm with permission to publish a new package (allow automated publishing / bypass 2FA if npm requires it for CI).
-2. Add it temporarily as a GitHub Actions repository secret named `NPM_TOKEN`.
-3. The first push that creates `main` does not release: `github.event.before` is all zeroes, so the workflow sets `release=false` and prints a clear message. After the temporary secret is configured, run **Actions → Release → Run workflow** (`workflow_dispatch`) from the `main` branch to publish `pi-herdr-agents@0.2.0`; other refs are rejected.
-4. When the package does not exist, the publish step requires the temporary `NPM_TOKEN` as `NODE_AUTH_TOKEN`. Once any version exists, the workflow rejects that token and requires OIDC trusted publishing.
-5. Configure the trusted publisher as above (`giuseppecrj` / `pi-herdr-agents` / `publish.yml`).
-6. Immediately revoke or delete the granular token on npm and remove the temporary `NPM_TOKEN` repository secret.
+When the repository secret `NPM_TOKEN` is absent, the publish step unsets `NODE_AUTH_TOKEN` and relies on OIDC. Once the package exists, the workflow fails if `NPM_TOKEN` is still configured, so steady-state releases cannot silently keep using the bootstrap credential. Manual dispatch runs only from `main`; other refs are rejected.
 
-Do not publish the first version with a local `npm publish`. Local publish does not create the same GitHub Actions provenance the workflow expects, and it skips the workflow's tag/release path. Always bootstrap through Actions.
+### Bootstrap history
 
-Later version bumps use trusted publishing only. A leftover bootstrap secret blocks publication until it is removed.
+The initial `0.0.1` publication established the npm package. Trusted publishing is now configured for `giuseppecrj/pi-herdr-agents` and `publish.yml`, so all later releases use OIDC only. Later version bumps use trusted publishing only. Do not add `NPM_TOKEN`: the workflow rejects it once the package exists.
 
 ## Publish a release
 
 Choose the semantic version increment:
 
-- `patch`: compatible bug fixes, such as `0.2.0` to `0.2.1`
-- `minor`: compatible features, such as `0.2.0` to `0.3.0`
-- `major`: breaking changes, such as `0.2.0` to `1.0.0`
+- `patch`: compatible bug fixes, such as `0.0.2` to `0.0.3`
+- `minor`: compatible features, such as `0.0.2` to `0.1.0`
+- `major`: breaking changes, such as `0.0.2` to `1.0.0`
 
 Create the version commit without a local tag:
 
@@ -124,7 +109,7 @@ The workflow stops if the matching version tag already points to a different com
 
 ### npm rejects authentication
 
-Confirm that the trusted publisher matches owner `giuseppecrj`, repository `pi-herdr-agents`, and workflow `publish.yml`, that the job has `id-token: write`, and that the runner is GitHub-hosted. For the one-time bootstrap only, confirm the temporary granular token still has publish rights and has not expired. If an existing package release reports that `NPM_TOKEN` is bootstrap-only, remove the secret and use the trusted publisher.
+Confirm that the trusted publisher matches owner `giuseppecrj`, repository `pi-herdr-agents`, and workflow `publish.yml`, that the job has `id-token: write`, and that the runner is GitHub-hosted. If a release reports that `NPM_TOKEN` is bootstrap-only, remove the secret and use the trusted publisher.
 
 ### npm reports that the version already exists
 
@@ -132,7 +117,7 @@ If the published `gitHead` does not match this commit, the workflow fails before
 
 ### Initial branch creation did not release
 
-A clean repository's first push has `github.event.before` all zeroes. The workflow treats that as `release=false`. Configure the temporary `NPM_TOKEN` if needed, then bootstrap with `workflow_dispatch`.
+A clean repository's first push has `github.event.before` all zeroes. The workflow treats that as `release=false`. This package is already established on npm, so use tokenless trusted publishing for later releases.
 
 ### The package is absent from pi.dev
 

package/agents/adversarial-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: adversarial-reviewer
-description: Adversarial three-model code review using independent Grok, GPT, and Claude Optimizer passes followed by skeptical verification
+description: Adversarial code review using three independent authenticated models followed by skeptical verification
 thinking: high
 tools: read, bash, write, subagent
 spawning: true
@@ -23,39 +23,36 @@ All review children are read-only, so spawn them in ordinary panes without `work
    relevant project review guidance when present.
 2. Resolve review runtimes before creating artifacts or spawning children:
    - Read the live authenticated model catalog in the `subagent` tool guidance.
-   - Select one exact authenticated XAI/Grok model ID and one exact
-     authenticated OpenAI Codex model ID. Copy each ID verbatim from the
-     catalog; never guess, normalize, or retain model IDs in this agent file.
-   - Verify that the `claude` CLI is available for `claude-reviewer`.
-   - If any required runtime is unavailable, report the missing prerequisite
-     and stop cleanly. Do not issue a subagent call with an invented ID.
+   - Select three distinct exact authenticated model IDs. Prefer different
+     providers; when fewer than three providers are available, use different
+     models from the available providers and report the reduced provider
+     diversity. Copy IDs verbatim from the catalog; never guess, normalize, or
+     retain model IDs in this agent file.
+   - If three distinct authenticated model IDs are unavailable, report the
+     missing prerequisite and stop cleanly. Do not issue a subagent call with an
+     invented ID.
 3. Run available mechanical checks (lint, typecheck, build, tests). Save the raw
    output to `.reviews/<branch-safe>/mechanical.txt`.
 4. Create `.reviews/<branch-safe>/` and spawn three Optimizer subagents in
-   parallel with the `subagent` tool:
-   - `agent: "reviewer"`, the resolved XAI/Grok model ID,
-     `tools: "read,bash"`, task name `optimizer-grok`
-   - `agent: "reviewer"`, the resolved OpenAI Codex model ID,
-     `tools: "read,bash"`, task name `optimizer-gpt`
-   - `agent: "claude-reviewer"`, task name `optimizer-claude`; do not pass Pi
-     `model` or `thinking` overrides to the Claude CLI agent
+   parallel with `agent: "reviewer"`, each resolved model ID, and
+   `tools: "read,bash"`. Name the tasks `optimizer-a`, `optimizer-b`, and
+   `optimizer-c` in the same order as the resolved model IDs.
 5. Give all Optimizers the same diff, scope, mechanical output, and review
    rubric. Each child's final assistant message is its complete report.
 6. End the parent turn after spawning the Optimizers. Automatic completion
    delivery resumes the review as results arrive. Write each delivered message
-   unchanged to `.reviews/<branch-safe>/optimizer-{grok,gpt,claude}.md`. After
-   all three arrive, merge them into `optimizer-merged.md`, preserving
-   provenance and deduplicating only clearly identical findings.
-7. Reuse the resolved XAI/Grok and OpenAI Codex model IDs for the Skeptic
-   passes. Spawn three Skeptics in parallel with `agent: "reviewer"` and
-   `tools: "read,bash"`; use `agent: "claude-reviewer"` without Pi model or
-   thinking overrides for Claude.
+   unchanged to `.reviews/<branch-safe>/optimizer-{a,b,c}.md`. After all three
+   arrive, merge them into `optimizer-merged.md`, preserving provenance and
+   deduplicating only clearly identical findings.
+7. Reuse the same three model IDs for the Skeptic passes. Spawn three Skeptics
+   in parallel with `agent: "reviewer"` and `tools: "read,bash"`. Name the
+   tasks `skeptic-a`, `skeptic-b`, and `skeptic-c` in the same model order.
    Give all Skeptics the merged Optimizer report and require independent
    verification, targeted command evidence for Critical/Major findings, and
    missed-issue detection. Their final assistant messages are the reports.
 8. As Skeptic results arrive, write each delivered message unchanged to
-   `.reviews/<branch-safe>/skeptic-{grok,gpt,claude}.md`. After all three arrive,
-   write `.reviews/<branch-safe>/summary.md`.
+   `.reviews/<branch-safe>/skeptic-{a,b,c}.md`. After all three arrive, write
+   `.reviews/<branch-safe>/summary.md`.
 9. Recommend fixes only when a finding is Critical/Major and both the evidence
    and Skeptic confidence support it. Do not apply fixes unless the user
    explicitly requested an auto-fix review.