pi-herdr-agents 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -7,10 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
-## [v3.0.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v2.0.5...v3.0.0)
+## [v3.0.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.0.0...v3.0.1)
 
 ### Merged
 
+- docs: README accuracy and install confidence for 3.0.0 [`#75`](https://github.com/giuseppecrj/pi-herdr-agents/pull/75)
+
+### Commits
+
+- docs: README for 3.0.0: pstack ships poteto-mode not a role, safety and uninstall, contents, agent pointer [`7ed9969`](https://github.com/giuseppecrj/pi-herdr-agents/commit/7ed99693b1a2d25137d4ba2430f23255923ce3ea)
+- docs: hero image uses generic agent labels instead of removed role names [`70ad6f0`](https://github.com/giuseppecrj/pi-herdr-agents/commit/70ad6f04d492f58e04062e01c1a529ddd1708431)
+- docs: address review: full write footprint, worktree cleanup before uninstall, skill table delimiter [`ababee3`](https://github.com/giuseppecrj/pi-herdr-agents/commit/ababee3a3f18d2112ec8959303986e1a08e3dc2a)
+
+## [v3.0.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v2.0.5...v3.0.0) - 2026-10-06
+
+### Merged
+
+- Release 3.0.0 [`#74`](https://github.com/giuseppecrj/pi-herdr-agents/pull/74)
 - Add subagent_cancel for ordinary managed subagents [`#73`](https://github.com/giuseppecrj/pi-herdr-agents/pull/73)
 - Add the pi-herdr-agents operating skill [`#72`](https://github.com/giuseppecrj/pi-herdr-agents/pull/72)
 - Conditional task-model writes with expectedConfigRevision [`#71`](https://github.com/giuseppecrj/pi-herdr-agents/pull/71)
@@ -36,7 +49,9 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - docs: add subagent-lifecycle host skill [`bfce217`](https://github.com/giuseppecrj/pi-herdr-agents/commit/bfce2177984a7b5fededc2b3a7fe255cc966e46c)
 - fix: keep a failed SIGTERM to a live identity unconfirmed and drop overdue provider answers [`4a3992d`](https://github.com/giuseppecrj/pi-herdr-agents/commit/4a3992d865eeb0a11a23350ff4de92dd892e30c2)
 - docs: fix host operating skill review findings and packaging wording [`bbeb580`](https://github.com/giuseppecrj/pi-herdr-agents/commit/bbeb580a5fb38d780209babcd8b5f7848b8543e2)
+- docs: add 3.0.0 release notes and clarify bare-spawn systemPrompt delivery [`b8b23a0`](https://github.com/giuseppecrj/pi-herdr-agents/commit/b8b23a0893d5d9e6176703305838e24bc91391e8)
 - docs(skill): document subagent_cancel in host operating guide [`7a3508c`](https://github.com/giuseppecrj/pi-herdr-agents/commit/7a3508cfe886b5f7932bdf77d3d3a516d2a7dfcd)
+- chore: release v3.0.0 [`b383574`](https://github.com/giuseppecrj/pi-herdr-agents/commit/b383574778aad1498c12ddeb48af6dd32f383856)
 - test(integration): scope the untouched-pane check to the runner's own workspace [`fa483ea`](https://github.com/giuseppecrj/pi-herdr-agents/commit/fa483ea918f862da35162ca4d73ae6191288fa99)
 - docs: scope the pack-neutral claim to roles and workflows [`e75bea8`](https://github.com/giuseppecrj/pi-herdr-agents/commit/e75bea84a79218c9367ea5a165cbab161e2fb217)
 - fix: declare pi.skills so the lifecycle skill actually loads [`5b45e7f`](https://github.com/giuseppecrj/pi-herdr-agents/commit/5b45e7fb17080fe7b5d1d7e675d234fc140ed144)

package/README.md

@@ -1,6 +1,8 @@
 # Pi Herdr Agents
 
-![Pi Herdr Agents: parallel Pi agents running asynchronously in dedicated Herdr panes and managed worktrees.](https://raw.githubusercontent.com/giuseppecrj/pi-herdr-agents/main/docs/assets/pi-herdr-agents-gallery.png)
+![Pi Herdr Agents: a parent Pi session delegating to parallel child agents in dedicated Herdr panes, an isolated worktree and a retained session, with a live status widget.](https://raw.githubusercontent.com/giuseppecrj/pi-herdr-agents/main/docs/assets/pi-herdr-agents-gallery.png)
+
+> **Agents:** the tool list is in [What's Included](#whats-included) and the operating guide is [`skills/pi-herdr-agents/SKILL.md`](skills/pi-herdr-agents/SKILL.md). Contributors: read [`AGENTS.md`](AGENTS.md).
 
 Asynchronous subagents for [Pi](https://github.com/earendil-works/pi), running exclusively in [Herdr](https://herdr.dev).
 
@@ -48,36 +50,24 @@ pi
 
 Restart or `/reload` Pi after installation. Review package source before installing any Pi package.
 
-## Release notes
+> **Upgrading from 2.x?** Bundled roles and several commands moved out. See [3.0.0 release notes](#300).
 
-[`CHANGELOG.md`](CHANGELOG.md) is generated from Git history on each release.
-Hand-written upgrade notes for breaking releases live here.
+## Contents
 
-### 3.0.0
+- [Requirements](#requirements), [Install](#install), [Safety and uninstall](#safety-and-uninstall)
+- [Quick start](#quick-start), [Release notes](#release-notes), [How it works](#how-it-works)
+- [What's Included](#whats-included): tools, commands, the operating skill, role packs
+- [Async Subagent Flow](#async-subagent-flow): status, configuration, model routing
+- [Spawning Subagents](#spawning-subagents), [Persistent specialists](#persistent-specialists), [Interrupting](#interrupting-a-running-subagent), [Cancelling](#cancelling-a-running-subagent)
+- [The `/worktree` Workflow](#the-worktree-workflow), [Custom Agents](#custom-agents), [Tool Access Control](#tool-access-control)
+- [Development](#development), [License](#license)
 
-3.0.0 makes the host pack-neutral. It also adds conditional task-model writes
-(`expectedConfigRevision`, an advisory lock, and the reported `configRevision`),
-the `pi-herdr-agents` operating skill, and `subagent_cancel`.
+## Safety and uninstall
 
-**Breaking changes.** The package no longer ships the seven former bundled roles,
-`/plan` and its plan skill, or `/skill:orchestrate`; these moved to optional role
-packs. `/iterate`, `/btw`, and `/btw-close` were removed without replacement.
-`roles.bundled` is now a deprecated no-op. A named launch of a role that no
-definition or installed pack supplies now fails before Herdr creates a pane or
-worktree.
-
-**Migration.**
-
-- Install `pi-herdr-roles` for the six generic roles (`scout`, `planner`,
-  `worker`, `reviewer`, `adversarial-reviewer`, `visual-tester`), `/plan`, and
-  `/skill:orchestrate`.
-- Install `pi-herdr-pstack` for the `poteto` role.
-- Remove `roles.bundled` from `$PI_CODING_AGENT_DIR/herdr-agents/config.json`.
-- Alternatively, copy a former role's definition into `.pi/agents/` or the
-  global agents directory to keep it without a pack.
-
-See [Migrating from bundled roles](#migrating-from-bundled-roles) for the full
-mapping and pack-compatibility notes.
+- Child agents are real Pi processes running with your user account's permissions, inside Herdr panes. Worktrees isolate Git checkouts, not processes or permissions.
+- The extension creates Herdr panes, tabs and managed worktrees only when a launch asks for them. It never pushes, merges, opens pull requests, deletes branches or removes worktrees on its own; cleanup is an explicit parent action ([worktree cleanup](#explicit-worktree-cleanup)).
+- What it writes: `$PI_CODING_AGENT_DIR/herdr-agents/config.json` (only through `/subagents-init` or the writer tool, never on startup); per-launch artifacts under the parent session's `artifacts/<session-id>/` directory beside Pi's session store, which hold the child's full task text and any `systemPrompt` as Markdown files, activity snapshots and worktree manifests; and the child's own Pi session file. A managed worktree that carries its own `.pi/agent` directory receives that child's session inside the checkout. Treat task text as potentially sensitive when you share or inspect those files.
+- To uninstall: first list and remove any retained worktrees while the extension is still loaded (`/worktree list`, then `/worktree remove <target>`), because those commands leave with the package. Then run `pi remove npm:pi-herdr-agents`, and delete `$PI_CODING_AGENT_DIR/herdr-agents/` and the `artifacts/` directories above if you no longer want the configuration and launch records.
 
 ## Quick start
 
@@ -117,6 +107,38 @@ subagent({ name: "Auth summary", model: "<provider>/<fast-tier-id>", thinking: "
 
 Use ordinary panes for read-only agents. A single or sequential writer can work in the parent checkout; give each parallel independent writing agent a unique managed worktree. The parent acts as coordinator: decompose work, give each child one bounded outcome with its goal, allowed files, verification, and commit instruction, and keep dependent writes sequential. Children are leaves by default; the parent owns integration and final verification. See [Worktree subagents](docs/worktree-subagents.md).
 
+## Release notes
+
+[`CHANGELOG.md`](CHANGELOG.md) is generated from Git history on each release.
+Hand-written upgrade notes for breaking releases live here.
+
+### 3.0.0
+
+3.0.0 makes the host pack-neutral. It also adds conditional task-model writes
+(`expectedConfigRevision`, an advisory lock, and the reported `configRevision`),
+the `pi-herdr-agents` operating skill, and `subagent_cancel`.
+
+**Breaking changes.** The package no longer ships the seven former bundled roles,
+`/plan` and its plan skill, or `/skill:orchestrate`; these moved to optional role
+packs. `/iterate`, `/btw`, and `/btw-close` were removed without replacement.
+`roles.bundled` is now a deprecated no-op. A named launch of a role that no
+definition or installed pack supplies now fails before Herdr creates a pane or
+worktree.
+
+**Migration.**
+
+- Install `pi-herdr-roles` for the six generic roles (`scout`, `planner`,
+  `worker`, `reviewer`, `adversarial-reviewer`, `visual-tester`), `/plan`, and
+  `/skill:orchestrate`.
+- Install `pi-herdr-pstack` for the `poteto-mode` methodology skill and command.
+  It ships no named roles; its delegates are bare.
+- Remove `roles.bundled` from `$PI_CODING_AGENT_DIR/herdr-agents/config.json`.
+- Alternatively, copy a former role's definition into `.pi/agents/` or the
+  global agents directory to keep it without a pack.
+
+See [Migrating from bundled roles](#migrating-from-bundled-roles) for the full
+mapping and pack-compatibility notes.
+
 ## How it works
 
 ![Pi Herdr Agents lifecycle: spawn a child, run it in Herdr, supervise live state, and deliver one bounded result to the parent.](https://raw.githubusercontent.com/giuseppecrj/pi-herdr-agents/main/docs/assets/async-subagent-lifecycle.png)
@@ -172,6 +194,10 @@ Subagent tabs, panes, and worktree workspaces are created without stealing keybo
 | `subagent_resume`    | Resume a previous Pi-backed sub-agent session in a new ordinary pane (async)                          |
 | `subagents_write_task_models` | Parent-only internal tool that validates and atomically writes `models.tasks` preferences, optionally conditional on `expectedConfigRevision` |
 
+| Skill | Description |
+| ----- | ----------- |
+| `pi-herdr-agents` | Operating guide for this host: launching, supervising, interrupting, cancelling and resuming children, worktrees, persistent specialists, model routing and configuration. Loaded by agents on demand; see `skills/pi-herdr-agents/SKILL.md` |
+
 | Pi child-only tool | Description |
 | ---------------- | ------------------------------------------------------------------------- |
 | `caller_ping` | Ask the parent for help; ordinary children exit, persistent specialists stay alive |
@@ -233,7 +259,7 @@ modified.
 | `scout`, `planner`, `worker`, `reviewer`, `adversarial-reviewer`, `visual-tester` roles | Moved | `pi-herdr-roles` role pack |
 | `/plan` command and its plan skill | Moved | `pi-herdr-roles` |
 | `/skill:orchestrate` and its adversarial-review resources | Moved | `pi-herdr-roles` |
-| `poteto` role | Moved | `pi-herdr-pstack` role pack |
+| `poteto` role | Removed; replaced by the `poteto-mode` skill and `/poteto-mode` command | `pi-herdr-pstack` |
 | `/iterate` | Removed, not relocated | Call `subagent({ name, task, fork: true, interactive: true })` directly |
 | `/btw`, `/btw-close` | Removed, not relocated | None |
 | `roles.bundled` setting | Deprecated no-op | Remove it from `config.json` |
@@ -1250,4 +1276,4 @@ This package builds on earlier open-source work by [HazAT/pi-interactive-subagen
 
 ## License
 
-MIT. Copyright notice retained from the upstream lineage (`HazAT`).
+MIT, see [LICENSE](LICENSE). Copyright notice retained from the upstream lineage (`HazAT`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-agents",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Asynchronous Pi subagents in Herdr, with optional isolated Git worktrees",
   "keywords": [
     "pi-package",