pi-herdsman 0.39.0 → 0.41.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +91 -0
- package/README.md +18 -1
- package/SKILL.md +10 -7
- package/dist/agents/generalist.md +1 -1
- package/dist/agents/implementer.md +1 -1
- package/dist/agents/validator.md +31 -0
- package/dist/{roles → coordinators}/manager.md +5 -6
- package/dist/index.js +2675 -1805
- package/dist/index.js.map +4 -4
- package/dist/peer-bridge.js +23 -13
- package/dist/peer-bridge.js.map +3 -3
- package/docs/README.md +2 -2
- package/docs/adr/0034-separate-definition-namespaces.md +4 -0
- package/docs/adr/0037-prioritize-project-definition-overlays.md +3 -0
- package/docs/adr/0038-private-repository-definition-overlays.md +43 -0
- package/docs/adr/0039-use-coordinator-profile-directories.md +55 -0
- package/docs/concepts/agents.md +9 -5
- package/docs/concepts/lifecycle.md +6 -4
- package/docs/coordination-api.md +3 -2
- package/docs/development/smoke-testing.md +12 -10
- package/docs/development/validation.md +12 -8
- package/docs/getting-started.md +9 -2
- package/docs/guides/agent-definitions.md +67 -24
- package/docs/guides/container-deployment.md +126 -38
- package/docs/guides/customizing-agents.md +47 -25
- package/docs/guides/project-orchestration.md +12 -1
- package/docs/guides/recovery.md +18 -12
- package/docs/reference/agent-definition-schema.md +43 -18
- package/docs/reference/agent-states.md +10 -10
- package/docs/reference/agent.md +52 -38
- package/docs/reference/commands.md +19 -14
- package/docs/reference/staff.md +21 -6
- package/package.json +3 -2
- package/skills/agent-definitions/SKILL.md +48 -15
- /package/dist/{roles → coordinators}/chief.md +0 -0
- /package/dist/{roles → coordinators}/flexible-lead.md +0 -0
- /package/dist/{roles → coordinators}/managed-lead.md +0 -0
- /package/dist/{roles → coordinators}/orchestrator-lead.md +0 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
## Unreleased
|
|
4
4
|
|
|
5
|
+
### Features
|
|
6
|
+
|
|
7
|
+
* **config:** Edit Agent settings in the most specific existing definition
|
|
8
|
+
source, with explicit scope selection and source-local reset behavior.
|
|
9
|
+
* **config:** Add a private repository definition overlay shared by trusted
|
|
10
|
+
linked worktrees in one clone (`bundled < global < trusted project < private
|
|
11
|
+
repository`).
|
|
12
|
+
|
|
5
13
|
### Breaking changes
|
|
6
14
|
|
|
7
15
|
* **config:** Trusted project Agent and role-profile definitions now override global definitions (`bundled < global < trusted project`). Projects may override global `enabled`, `tools`, `agents`, and `permission` values; review trusted project files accordingly.
|
|
@@ -10,6 +18,89 @@
|
|
|
10
18
|
Move existing role overrides from `agents/` to `pi-herdsman/roles/` in the
|
|
11
19
|
same scope. Reserved role names in `agents/` are rejected.
|
|
12
20
|
|
|
21
|
+
## [0.41.0](https://github.com/boadij/pi-herdsman/compare/v0.40.0...v0.41.0) (2026-11-07)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
### ⚠ BREAKING CHANGES
|
|
25
|
+
|
|
26
|
+
* **agent:** rename close_agent to stop_agent ([#860](https://github.com/boadij/pi-herdsman/issues/860))
|
|
27
|
+
|
|
28
|
+
### Fixes
|
|
29
|
+
|
|
30
|
+
* **agent:** allow continuation after empty mailbox cleanup ([#847](https://github.com/boadij/pi-herdsman/issues/847)) ([83670d9](https://github.com/boadij/pi-herdsman/commit/83670d9eaa4e3f0da3d8e994d026ff49a79dc1f6)), closes [#842](https://github.com/boadij/pi-herdsman/issues/842)
|
|
31
|
+
* **ci:** align test suite deadline across platforms ([#851](https://github.com/boadij/pi-herdsman/issues/851)) ([2c37524](https://github.com/boadij/pi-herdsman/commit/2c37524eacdeaafa263b9ffd2778291adead2956))
|
|
32
|
+
* **container:** persist optional Compose deployment selections ([#863](https://github.com/boadij/pi-herdsman/issues/863)) ([330dac4](https://github.com/boadij/pi-herdsman/commit/330dac42155fe02601c178f6139839115b81e995))
|
|
33
|
+
* detect non-repository folders on non-English locales ([#835](https://github.com/boadij/pi-herdsman/issues/835)) ([c34719b](https://github.com/boadij/pi-herdsman/commit/c34719b7cb511ca0082613908a3efa6e9b96930a))
|
|
34
|
+
* **manager:** avoid speculative cross-lead coordination ([#859](https://github.com/boadij/pi-herdsman/issues/859)) ([ae49f01](https://github.com/boadij/pi-herdsman/commit/ae49f017353671be04f141f5696c3ca17829aecb)), closes [#858](https://github.com/boadij/pi-herdsman/issues/858)
|
|
35
|
+
* **manager:** reject submodule-blocked removal before Lead shutdown ([#844](https://github.com/boadij/pi-herdsman/issues/844)) ([69ddb22](https://github.com/boadij/pi-herdsman/commit/69ddb220ce71c30d2bb54f66b9f029b567d8231f))
|
|
36
|
+
* **manager:** remove verified worktrees without Pi session-file provenance ([#855](https://github.com/boadij/pi-herdsman/issues/855)) ([3886f89](https://github.com/boadij/pi-herdsman/commit/3886f89c3e17e6527e580a81f0a607a1655bf961)), closes [#854](https://github.com/boadij/pi-herdsman/issues/854)
|
|
37
|
+
* **manager:** wait for assignment authority during delegation ([#848](https://github.com/boadij/pi-herdsman/issues/848)) ([b524e40](https://github.com/boadij/pi-herdsman/commit/b524e406201366fa58a352524a49c1dd53afb003)), closes [#845](https://github.com/boadij/pi-herdsman/issues/845)
|
|
38
|
+
* **supervision:** consolidate managed Lead reporting guidance ([#856](https://github.com/boadij/pi-herdsman/issues/856)) ([3edf381](https://github.com/boadij/pi-herdsman/commit/3edf3813999a19dfba0f441db001ee2121eb91ca))
|
|
39
|
+
* **trust:** preserve managed worktree trust through nested agents ([#852](https://github.com/boadij/pi-herdsman/issues/852)) ([68a04c0](https://github.com/boadij/pi-herdsman/commit/68a04c08c3676b1e0525a11732a0a869012b4ae6))
|
|
40
|
+
* **types:** eliminate TypeScript and Oxlint diagnostics ([#836](https://github.com/boadij/pi-herdsman/issues/836)) ([833369d](https://github.com/boadij/pi-herdsman/commit/833369db84c82b1f1fc6e06f964bfec1b37860f6))
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
### Refactoring
|
|
44
|
+
|
|
45
|
+
* **agent:** rename close_agent to stop_agent ([#860](https://github.com/boadij/pi-herdsman/issues/860)) ([e04a708](https://github.com/boadij/pi-herdsman/commit/e04a708c1075d4bf62fc4dc5fdc72a4aea424e49))
|
|
46
|
+
* **test:** remove verified Oxlint warnings ([#833](https://github.com/boadij/pi-herdsman/issues/833)) ([c83163b](https://github.com/boadij/pi-herdsman/commit/c83163b99ebd41a50c743944dc9a8c69f2eeb42a))
|
|
47
|
+
* **trust:** inherit Manager trust for managed worktrees ([#857](https://github.com/boadij/pi-herdsman/issues/857)) ([0a4a233](https://github.com/boadij/pi-herdsman/commit/0a4a233d500cb023c57285a10462fadffc2a76ea))
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
### Documentation
|
|
51
|
+
|
|
52
|
+
* **agents:** include static quality in local validation gate ([#849](https://github.com/boadij/pi-herdsman/issues/849)) ([0060b7f](https://github.com/boadij/pi-herdsman/commit/0060b7f0f81d2dbaa7757754c9d722306d84f997))
|
|
53
|
+
* showcase the simple Docker Compose deployment ([#862](https://github.com/boadij/pi-herdsman/issues/862)) ([1b4232f](https://github.com/boadij/pi-herdsman/commit/1b4232f0c093f7f335f6f85a73fe64f48b5bacef))
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
### CI
|
|
57
|
+
|
|
58
|
+
* enforce TypeScript and warning-free lint ([#837](https://github.com/boadij/pi-herdsman/issues/837)) ([062c09c](https://github.com/boadij/pi-herdsman/commit/062c09cd2c0cb9db74b2c50448be9f4094608825))
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
### Other Changes
|
|
62
|
+
|
|
63
|
+
* **deps:** update ghcr.io/jdx/mise docker tag to v2026.11.3 ([#839](https://github.com/boadij/pi-herdsman/issues/839)) ([25786f2](https://github.com/boadij/pi-herdsman/commit/25786f277a72abe59085a717b62d78f079040b8c))
|
|
64
|
+
|
|
65
|
+
## [0.40.0](https://github.com/boadij/pi-herdsman/compare/v0.39.0...v0.40.0) (2026-11-05)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
### ⚠ BREAKING CHANGES
|
|
69
|
+
|
|
70
|
+
* **config:** standardize coordinator profile directories ([#821](https://github.com/boadij/pi-herdsman/issues/821))
|
|
71
|
+
|
|
72
|
+
### Features
|
|
73
|
+
|
|
74
|
+
* **agents:** bundle validator and enable PowerShell for executors ([#817](https://github.com/boadij/pi-herdsman/issues/817)) ([a04e7a4](https://github.com/boadij/pi-herdsman/commit/a04e7a496906371616910d9a83950a813292bd63))
|
|
75
|
+
* **agent:** support semantic result continuation ([#824](https://github.com/boadij/pi-herdsman/issues/824)) ([eaa13e7](https://github.com/boadij/pi-herdsman/commit/eaa13e7864074fbb4ce4116578f87b4bc9731319))
|
|
76
|
+
* **config:** edit settings in their owning definition scope ([#820](https://github.com/boadij/pi-herdsman/issues/820)) ([32da2ed](https://github.com/boadij/pi-herdsman/commit/32da2ed8c4b66c0b7c433a9192155d18871a7d71))
|
|
77
|
+
* **config:** support private repository definitions across worktrees ([#815](https://github.com/boadij/pi-herdsman/issues/815)) ([9b3fe4e](https://github.com/boadij/pi-herdsman/commit/9b3fe4e799ed8a8e59e7098d95a09198c1618d8d))
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
### Fixes
|
|
81
|
+
|
|
82
|
+
* **ci:** temporarily extend Windows suite deadline ([#827](https://github.com/boadij/pi-herdsman/issues/827)) ([499cda1](https://github.com/boadij/pi-herdsman/commit/499cda13ec82a4aff3927e13eb1e37cb1bdf2044))
|
|
83
|
+
* **lifecycle:** make hierarchical shutdown reliable ([#823](https://github.com/boadij/pi-herdsman/issues/823)) ([3892336](https://github.com/boadij/pi-herdsman/commit/38923363359fe109cf0803d6b852a100484ea097))
|
|
84
|
+
* **manager:** prevent redundant resume instructions ([#828](https://github.com/boadij/pi-herdsman/issues/828)) ([4a82f12](https://github.com/boadij/pi-herdsman/commit/4a82f122c606c86ebd16a2e0219b4bc18330ad90))
|
|
85
|
+
* **manager:** scope resume topology revalidation to verified checkout ([#831](https://github.com/boadij/pi-herdsman/issues/831)) ([03f3c53](https://github.com/boadij/pi-herdsman/commit/03f3c5367c85dc02a579d172eb840a33d6dbdc55)), closes [#830](https://github.com/boadij/pi-herdsman/issues/830)
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
### Refactoring
|
|
89
|
+
|
|
90
|
+
* **config:** standardize coordinator profile directories ([#821](https://github.com/boadij/pi-herdsman/issues/821)) ([08a140c](https://github.com/boadij/pi-herdsman/commit/08a140c1789a075a2bbf8a5a5f90a3423115014d)), closes [#734](https://github.com/boadij/pi-herdsman/issues/734)
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
### Tests
|
|
94
|
+
|
|
95
|
+
* **ci:** add Windows startup timing diagnostics ([#825](https://github.com/boadij/pi-herdsman/issues/825)) ([53c8af4](https://github.com/boadij/pi-herdsman/commit/53c8af415f6ddfd5e1b9548f2061d5f235fc26b0))
|
|
96
|
+
* **supervision:** release deferred Git sample on abort ([#829](https://github.com/boadij/pi-herdsman/issues/829)) ([bcab33e](https://github.com/boadij/pi-herdsman/commit/bcab33e02a9035453287ffbaae2d39f977060062))
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
### Other Changes
|
|
100
|
+
|
|
101
|
+
* **deps:** update ghcr.io/jdx/mise docker tag to v2026.11.1 ([#818](https://github.com/boadij/pi-herdsman/issues/818)) ([8ad2a66](https://github.com/boadij/pi-herdsman/commit/8ad2a662e36e9fad7e69c61768a6933f7a352177))
|
|
102
|
+
* **deps:** update ghcr.io/jdx/mise docker tag to v2026.11.2 ([#826](https://github.com/boadij/pi-herdsman/issues/826)) ([cb0057b](https://github.com/boadij/pi-herdsman/commit/cb0057b9ffe624bab918f680a6ce699d3fa49be6))
|
|
103
|
+
|
|
13
104
|
## [0.39.0](https://github.com/boadij/pi-herdsman/compare/v0.38.1...v0.39.0) (2026-11-04)
|
|
14
105
|
|
|
15
106
|
|
package/README.md
CHANGED
|
@@ -53,7 +53,24 @@ pi install npm:pi-herdsman
|
|
|
53
53
|
herdr integration install pi
|
|
54
54
|
```
|
|
55
55
|
|
|
56
|
-
|
|
56
|
+
**Docker Compose (prebuilt SSH environment):** Requires Docker Compose and an
|
|
57
|
+
SSH public key.
|
|
58
|
+
|
|
59
|
+
```sh
|
|
60
|
+
mkdir -p pi-herdsman && cd pi-herdsman
|
|
61
|
+
curl -fsSLO https://raw.githubusercontent.com/boadij/pi-herdsman/main/compose.yaml
|
|
62
|
+
SSH_AUTHORIZED_KEYS="$(cat ~/.ssh/id_ed25519.pub)" docker compose up -d
|
|
63
|
+
ssh -p 2222 herdsman@localhost
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The included [Compose file](compose.yaml) uses a prebuilt image and persistent
|
|
67
|
+
Docker volumes. Herdr opens on SSH login; select a workspace and run `pi`.
|
|
68
|
+
Replace `localhost` with the Docker host address for remote access. SSH port
|
|
69
|
+
2222 is published on host interfaces by default; see
|
|
70
|
+
[Container deployment](docs/guides/container-deployment.md) for networking,
|
|
71
|
+
storage, and update options.
|
|
72
|
+
|
|
73
|
+
For a native installation, start herdr in your project directory, then Pi in its pane:
|
|
57
74
|
|
|
58
75
|
```sh
|
|
59
76
|
herdr
|
package/SKILL.md
CHANGED
|
@@ -78,7 +78,8 @@ configuration changes. Do not use `list_agents` merely to check progress.
|
|
|
78
78
|
|
|
79
79
|
For a new bounded delegated task, prefer `continue_agent` when a known,
|
|
80
80
|
eligible historical managed-Agent Pi session contains substantial context
|
|
81
|
-
relevant to that task.
|
|
81
|
+
relevant to that task. Use its result ref when shown, otherwise its exact session
|
|
82
|
+
ID or path. Otherwise use `delegate_agent` for a fresh assignment.
|
|
82
83
|
|
|
83
84
|
Each managed agent exists for one assignment only. After its terminal result is
|
|
84
85
|
delivered, Pi Herdsman cleans up that agent automatically. To continue completed
|
|
@@ -95,7 +96,7 @@ eligibility. Every operation revalidates exact state and identity before
|
|
|
95
96
|
mutation.
|
|
96
97
|
|
|
97
98
|
The live-agent control tools are `steer_agent`, `interrupt_agent`,
|
|
98
|
-
`reply_agent`, and `
|
|
99
|
+
`reply_agent`, and `stop_agent`;
|
|
99
100
|
these mutate
|
|
100
101
|
live agent execution and are available only when listed. Read-only `inspect_agent` captures bounded live terminal/process evidence.
|
|
101
102
|
`read_agent_transcript` captures bounded persisted Pi conversation and tool evidence
|
|
@@ -114,15 +115,17 @@ merely because an agent is slow or marked stale; inactivity is advisory and
|
|
|
114
115
|
does not prove a hang.
|
|
115
116
|
|
|
116
117
|
Use `reply_agent` only to answer a valid outstanding `ask_owner` question. Use
|
|
117
|
-
`
|
|
118
|
+
`stop_agent` only when abandoning the Agent's unfinished assignment is
|
|
119
|
+
intended. Unlike `stop_lead`, which preserves a Manager's project assignment,
|
|
120
|
+
`stop_agent` does not complete or automatically restart the work.
|
|
118
121
|
|
|
119
122
|
A lost agent is a managed assignment whose exact physical execution is proven
|
|
120
123
|
gone before a durable terminal result resolved it. Loss is not completion or
|
|
121
124
|
task failure. Treat the assignment as unresolved. When `read_agent_transcript` is listed,
|
|
122
125
|
use it only when the last persisted work materially affects recovery. When
|
|
123
|
-
`
|
|
124
|
-
continuing its saved session. If `
|
|
125
|
-
blocking its
|
|
126
|
+
`stop_agent` is listed, use it to abandon the lost generation before replacing it or
|
|
127
|
+
continuing its saved session. If `stop_agent` is absent, resolve the condition
|
|
128
|
+
blocking its stop preflight first. Unknown evidence remains fail-closed and is
|
|
126
129
|
not proof of loss.
|
|
127
130
|
|
|
128
131
|
Never guess identities, paths, sessions, or control state. Treat unknown or
|
|
@@ -552,7 +555,7 @@ managed session remains an Agent at every depth.
|
|
|
552
555
|
Every managed agent receives `ask_owner`. A non-empty effective `agents` list
|
|
553
556
|
is necessary but not sufficient to enable the nine Agent ownership tools:
|
|
554
557
|
`list_agents`, `delegate_agent`, `continue_agent`, `steer_agent`,
|
|
555
|
-
`interrupt_agent`, `reply_agent`, `
|
|
558
|
+
`interrupt_agent`, `reply_agent`, `stop_agent`, `inspect_agent`, and
|
|
556
559
|
`read_agent_transcript`. Delegation is disabled when `excludeTools` contains
|
|
557
560
|
`agent`, when `noTools: true` unless explicit `tools` contains `agent`,
|
|
558
561
|
or when `tools` is explicitly empty. Otherwise, omitted `tools` permits
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Focused verification agent for running tests, checks, and smoke scenarios against existing changes; use to report observed evidence, not implement fixes or review design
|
|
3
|
+
extensions: []
|
|
4
|
+
inheritGlobalContext: false
|
|
5
|
+
inheritProjectContext: true
|
|
6
|
+
name: validator
|
|
7
|
+
noExtensions: true
|
|
8
|
+
noSkills: true
|
|
9
|
+
skills: []
|
|
10
|
+
systemPromptMode: append
|
|
11
|
+
tools: [read, bash, powershell]
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
You are validator, a verification-only agent for one explicitly assigned
|
|
15
|
+
existing change.
|
|
16
|
+
|
|
17
|
+
Read relevant instructions and validation guidance first. Choose the smallest
|
|
18
|
+
appropriate checks: focused tests for behavior, documented static/build checks,
|
|
19
|
+
and isolated smoke scenarios for integration. Treat test and smoke results as
|
|
20
|
+
distinct evidence; neither substitutes for the other.
|
|
21
|
+
|
|
22
|
+
Run only checks whose expected side effects are within the authorized scope.
|
|
23
|
+
Temporary artifacts and disposable processes are acceptable only when the check
|
|
24
|
+
isolates and cleans them up. Do not edit source, format, install dependencies,
|
|
25
|
+
stage, commit, change configuration, or modify shared systems or services.
|
|
26
|
+
If a check requires unauthorized changes, report it as blocked instead.
|
|
27
|
+
|
|
28
|
+
For each check, report the exact command, whether it completed, its exit status,
|
|
29
|
+
and relevant observed results. Distinguish passed, failed, skipped, and blocked
|
|
30
|
+
checks. Report unexpected working-tree changes or incomplete cleanup. Never
|
|
31
|
+
claim success without observing the result.
|
|
@@ -10,12 +10,11 @@ Coordinate assigned project work through Leads.
|
|
|
10
10
|
|
|
11
11
|
Set priorities, resolve project-level decisions and dependency sequencing,
|
|
12
12
|
review outcomes, and request corrections through the responsible Lead.
|
|
13
|
-
When
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
unaffected work continues.
|
|
13
|
+
When cross-assignment coordination is requested by the user or needed to
|
|
14
|
+
carry out an already established direction, prefer direct technical
|
|
15
|
+
exchange between eligible Leads over relaying messages yourself.
|
|
16
|
+
Mediate when peer communication is unavailable or a project-level decision
|
|
17
|
+
requires Manager action. Keep coordination limited to the concrete need.
|
|
19
18
|
Leave technical investigation, implementation, review, validation, and
|
|
20
19
|
integration to that Lead and its Agents rather than doing or delegating
|
|
21
20
|
the work yourself.
|