pi-herdsman 0.44.0 → 0.46.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 +79 -0
- package/README.md +64 -104
- package/SKILL.md +10 -8
- package/dist/index.js +2164 -751
- package/dist/index.js.map +4 -4
- package/docs/README.md +2 -1
- package/docs/concepts/coordination.md +28 -8
- package/docs/concepts/delegation.md +7 -5
- package/docs/concepts/lifecycle.md +6 -1
- package/docs/coordination-api.md +7 -6
- package/docs/development/documentation.md +3 -2
- package/docs/development/instruction-interface-design.md +11 -0
- package/docs/development/product-philosophy.md +7 -0
- package/docs/development/smoke-testing.md +35 -14
- package/docs/development/validation.md +19 -16
- package/docs/getting-started.md +1 -1
- package/docs/guides/agent-definitions.md +1 -1
- package/docs/guides/container-deployment.md +34 -1
- package/docs/guides/customizing-agents.md +26 -39
- package/docs/guides/handoffs.md +5 -5
- package/docs/guides/recovery.md +8 -3
- package/docs/reference/agent-definition-schema.md +33 -8
- package/docs/reference/agent-states.md +4 -4
- package/docs/reference/agent.md +61 -33
- package/docs/reference/{ask-owner.md → await-owner.md} +8 -8
- package/docs/reference/commands.md +26 -0
- package/docs/reference/notify-owner.md +51 -0
- package/docs/reference/supervisor.md +2 -1
- package/package.json +11 -16
- package/skills/agent-definitions/SKILL.md +7 -3
- package/dist/integrations/pi-codex-context-sharing.js +0 -42
- package/dist/integrations/pi-codex-context-sharing.js.map +0 -7
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,84 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [0.46.0](https://github.com/boadij/pi-herdsman/compare/v0.45.0...v0.46.0) (2026-11-13)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Features
|
|
7
|
+
|
|
8
|
+
* **agents:** extend generic bootstrap and remove PCC integration ([#951](https://github.com/boadij/pi-herdsman/issues/951)) ([da8ade3](https://github.com/boadij/pi-herdsman/commit/da8ade376656599e7186cb38b8a6ab2db0855364)), closes [#637](https://github.com/boadij/pi-herdsman/issues/637)
|
|
9
|
+
* **config:** support array modifiers in definition overlays ([#941](https://github.com/boadij/pi-herdsman/issues/941)) ([53b5df9](https://github.com/boadij/pi-herdsman/commit/53b5df946216c5c2d793cd03c399d3758dcf648e))
|
|
10
|
+
* **container:** support persistent native Pi self-updates ([#945](https://github.com/boadij/pi-herdsman/issues/945)) ([c95877a](https://github.com/boadij/pi-herdsman/commit/c95877a5a02cb81d7820c502bdd6188409bb37de))
|
|
11
|
+
* **dev:** add one-command setup for worktree hooks ([#947](https://github.com/boadij/pi-herdsman/issues/947)) ([6af00b4](https://github.com/boadij/pi-herdsman/commit/6af00b4b7ecd20a0f1d157768d34b6c9e8ffdd51))
|
|
12
|
+
* **ui:** inspect effective instruction composition in Details ([#946](https://github.com/boadij/pi-herdsman/issues/946)) ([ec84045](https://github.com/boadij/pi-herdsman/commit/ec840458c57c09b4469f54f4f1cf89ef8636ad73)), closes [#942](https://github.com/boadij/pi-herdsman/issues/942)
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
### Fixes
|
|
16
|
+
|
|
17
|
+
* **dev:** repair hook setup in copied repositories ([#957](https://github.com/boadij/pi-herdsman/issues/957)) ([9bf4466](https://github.com/boadij/pi-herdsman/commit/9bf4466d8782dcc819f4973e462f6d74ced0f60b))
|
|
18
|
+
* **ui:** present effective instructions as sequential Markdown sections ([#956](https://github.com/boadij/pi-herdsman/issues/956)) ([0519349](https://github.com/boadij/pi-herdsman/commit/0519349e4998bed90cfc2e6435f22c16bf26a82a))
|
|
19
|
+
* **ui:** restore chat scrolling for effective instruction details ([#953](https://github.com/boadij/pi-herdsman/issues/953)) ([556e9c2](https://github.com/boadij/pi-herdsman/commit/556e9c2df47f82963d56f10315e16c790ad7e961))
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
### Documentation
|
|
23
|
+
|
|
24
|
+
* introduce emergent agentic workflows ([#959](https://github.com/boadij/pi-herdsman/issues/959)) ([9d1b078](https://github.com/boadij/pi-herdsman/commit/9d1b078a29604ac04f59d28214865a914d97b701))
|
|
25
|
+
* refresh community contributor acknowledgments ([#964](https://github.com/boadij/pi-herdsman/issues/964)) ([8e9f371](https://github.com/boadij/pi-herdsman/commit/8e9f3713543452399924b1125c6462b1a4a86927))
|
|
26
|
+
* streamline README onboarding and mobile layout ([#960](https://github.com/boadij/pi-herdsman/issues/960)) ([278d5d2](https://github.com/boadij/pi-herdsman/commit/278d5d2ba6fe82b0e156952a4fd4c6f382168d80))
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
### Tests
|
|
30
|
+
|
|
31
|
+
* **ci:** require minimal ordinary Lead federation acceptance ([#954](https://github.com/boadij/pi-herdsman/issues/954)) ([35418b4](https://github.com/boadij/pi-herdsman/commit/35418b452731f8433bb4dbc92a5ad2e618ce4d06))
|
|
32
|
+
* **ci:** use minimal Manager federation acceptance ([#948](https://github.com/boadij/pi-herdsman/issues/948)) ([57c5a4f](https://github.com/boadij/pi-herdsman/commit/57c5a4f6f304df2aec791c144f8a1dae7b190774)), closes [#588](https://github.com/boadij/pi-herdsman/issues/588)
|
|
33
|
+
* **ci:** verify Manager activation through live authority ([#962](https://github.com/boadij/pi-herdsman/issues/962)) ([534aea1](https://github.com/boadij/pi-herdsman/commit/534aea13bde5d27c2241da91d3baa4682ec031e0)), closes [#934](https://github.com/boadij/pi-herdsman/issues/934)
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
### Other Changes
|
|
37
|
+
|
|
38
|
+
* **deps:** update ghcr.io/jdx/mise docker tag to v2026.11.8 ([#958](https://github.com/boadij/pi-herdsman/issues/958)) ([17e680b](https://github.com/boadij/pi-herdsman/commit/17e680b175a6449d8b1d8a3976279a370b0b33dc))
|
|
39
|
+
* **deps:** update npm non-major updates ([#935](https://github.com/boadij/pi-herdsman/issues/935)) ([6193198](https://github.com/boadij/pi-herdsman/commit/6193198849f37049e9038dc6bbe159ef10ed5aed))
|
|
40
|
+
* **deps:** update tailscale/tailscale docker tag to v1.104.7 ([#949](https://github.com/boadij/pi-herdsman/issues/949)) ([f6e8ff9](https://github.com/boadij/pi-herdsman/commit/f6e8ff953acc993dde4945fb08d3e5042868068b))
|
|
41
|
+
* **types:** enforce strict checking across all TypeScript sources ([#961](https://github.com/boadij/pi-herdsman/issues/961)) ([1955406](https://github.com/boadij/pi-herdsman/commit/1955406254edc2f0b8b6158fb75c2afd3c1e22ee))
|
|
42
|
+
|
|
43
|
+
## [0.45.0](https://github.com/boadij/pi-herdsman/compare/v0.44.0...v0.45.0) (2026-11-12)
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
### Features
|
|
47
|
+
|
|
48
|
+
* **agent:** distinguish owner notifications from blocking requests ([#917](https://github.com/boadij/pi-herdsman/issues/917)) ([1b96b23](https://github.com/boadij/pi-herdsman/commit/1b96b239b821517f4cb2c4e5f70392e37076d87f))
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
### Fixes
|
|
52
|
+
|
|
53
|
+
* **agent:** prevent duplicate owner notifications and improve presentation ([#926](https://github.com/boadij/pi-herdsman/issues/926)) ([6933cb5](https://github.com/boadij/pi-herdsman/commit/6933cb5871c6e9dcacaf619c513138153b71b689))
|
|
54
|
+
* **supervision:** restore Chief access to non-Git ordinary Leads ([#937](https://github.com/boadij/pi-herdsman/issues/937)) ([b0e3fa5](https://github.com/boadij/pi-herdsman/commit/b0e3fa5b4850ccd86f9448d6e1bbf1a42512afaf)), closes [#918](https://github.com/boadij/pi-herdsman/issues/918)
|
|
55
|
+
* **ui:** restore live tool metadata in managed Agent status headers ([#929](https://github.com/boadij/pi-herdsman/issues/929)) ([56b1f37](https://github.com/boadij/pi-herdsman/commit/56b1f37b46b45acc9b4906154711ab9aaadd3a59))
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
### Performance
|
|
59
|
+
|
|
60
|
+
* **agent:** batch concurrent health attention into one owner turn ([#924](https://github.com/boadij/pi-herdsman/issues/924)) ([8a26269](https://github.com/boadij/pi-herdsman/commit/8a26269c52c1da48bae312b877a1b2017a59ad8e))
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
### Documentation
|
|
64
|
+
|
|
65
|
+
* prefer Code Mode-compatible tool interfaces ([#921](https://github.com/boadij/pi-herdsman/issues/921)) ([eb9ad4d](https://github.com/boadij/pi-herdsman/commit/eb9ad4da6ac946d880ec6d479b9af3bf077e0950))
|
|
66
|
+
* prefer recipient-side fan-in at existing boundaries ([#920](https://github.com/boadij/pi-herdsman/issues/920)) ([2e27a6b](https://github.com/boadij/pi-herdsman/commit/2e27a6bfc97f378d9fd7e6ed5ecd83c20a7e4a6f))
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
### Tests
|
|
70
|
+
|
|
71
|
+
* **ci:** stabilize supervision and peer federation waits ([#936](https://github.com/boadij/pi-herdsman/issues/936)) ([23b29e1](https://github.com/boadij/pi-herdsman/commit/23b29e181c6eb85bed02c6c4a1b3042bae39af73))
|
|
72
|
+
* stabilize Windows-sensitive test waits ([#931](https://github.com/boadij/pi-herdsman/issues/931)) ([ce0142f](https://github.com/boadij/pi-herdsman/commit/ce0142fd18675f9ee5ba1417219bf0ebe8bc4ebd))
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
### Other Changes
|
|
76
|
+
|
|
77
|
+
* **deps:** update ghcr.io/jdx/mise docker tag to v2026.11.7 ([#938](https://github.com/boadij/pi-herdsman/issues/938)) ([24722dd](https://github.com/boadij/pi-herdsman/commit/24722dd70ba6e64a763a67371bd62519a9b24370))
|
|
78
|
+
* **deps:** update node.js to v26.13.1 ([#932](https://github.com/boadij/pi-herdsman/issues/932)) ([64f94f2](https://github.com/boadij/pi-herdsman/commit/64f94f2a9d21f692076a994d3df14109282f349e))
|
|
79
|
+
* **runtime:** adopt Pi 1.5.1 ([#923](https://github.com/boadij/pi-herdsman/issues/923)) ([ab069a4](https://github.com/boadij/pi-herdsman/commit/ab069a4e3f485427f7b8210c904a9bd2e1609d81))
|
|
80
|
+
* **runtime:** adopt Pi 1.5.2 ([#939](https://github.com/boadij/pi-herdsman/issues/939)) ([de8e9d2](https://github.com/boadij/pi-herdsman/commit/de8e9d297f3b11eefcd7793872cf699d12063844))
|
|
81
|
+
|
|
3
82
|
## [0.44.0](https://github.com/boadij/pi-herdsman/compare/v0.43.0...v0.44.0) (2026-11-11)
|
|
4
83
|
|
|
5
84
|
|
package/README.md
CHANGED
|
@@ -9,12 +9,25 @@
|
|
|
9
9
|
|
|
10
10
|
**The orchestration layer between [Pi](https://github.com/earendil-works/pi) and [herdr](https://github.com/herdrdev/herdr).**
|
|
11
11
|
|
|
12
|
-
Pi Herdsman lets your AI coding assistant delegate
|
|
13
|
-
while your
|
|
14
|
-
|
|
12
|
+
Pi Herdsman lets your AI coding assistant delegate work to background Agents
|
|
13
|
+
while your conversation stays interactive, or coordinate larger projects across
|
|
14
|
+
independent, branch-based Leads. Pi handles model conversations, herdr manages
|
|
15
|
+
terminal sessions and workspaces, and Herdsman coordinates delegation,
|
|
16
|
+
ownership, and supervision.
|
|
15
17
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
+
## Emergent agentic workflows
|
|
19
|
+
|
|
20
|
+
**Define the boundaries, not the workflow.**
|
|
21
|
+
|
|
22
|
+
Fixed agent pipelines prescribe the next handoff. Pi Herdsman instead lets models
|
|
23
|
+
decide how to split work, delegate to permitted Agents or Leads, and sequence or
|
|
24
|
+
parallelize tasks as results arrive. The execution path emerges at runtime,
|
|
25
|
+
while Herdsman enforces delegation permissions, ownership, project assignments,
|
|
26
|
+
and supervision.
|
|
27
|
+
|
|
28
|
+
You can still bring your own workflow and Agent definitions. See
|
|
29
|
+
[Coordination](docs/concepts/coordination.md#emergent-workflows-explicit-boundaries)
|
|
30
|
+
for the underlying model.
|
|
18
31
|
|
|
19
32
|
## Demo
|
|
20
33
|
|
|
@@ -22,16 +35,6 @@ _Advanced orchestration: a live Manager → Lead → Agent workflow._
|
|
|
22
35
|
|
|
23
36
|
[](https://github.com/user-attachments/assets/d6ee6687-a96d-493e-ae75-429f586be393)
|
|
24
37
|
|
|
25
|
-
## What Pi Herdsman gives you
|
|
26
|
-
|
|
27
|
-
- **Background Agents.** Delegate bounded work without blocking the Lead conversation.
|
|
28
|
-
- **Parallel and nested delegation.** Run independent work concurrently and let explicitly enabled Agents delegate their own bounded subtasks.
|
|
29
|
-
- **Project orchestration.** A Manager coordinates durable branch-based work across independent Leads and their Agent trees.
|
|
30
|
-
- **Direct supervision.** Chief, Manager, Lead, and Agent responsibilities stay explicit instead of collapsing into one global controller.
|
|
31
|
-
- **Peer communication.** Leads can message eligible peers locally; unassigned ordinary Leads and Managers can also collaborate across connected machines.
|
|
32
|
-
- **Owned usage visibility.** Inspect Pi-native token usage and cost for the current session and its transitively owned managed Agents. An active Manager also sees the Leads in its current durable project assignments and their owned Agent trees.
|
|
33
|
-
- **Your workflow stays yours.** Bring your own Agent definitions, models, tools, skills, extensions, and development process.
|
|
34
|
-
|
|
35
38
|
## Quick start
|
|
36
39
|
|
|
37
40
|
**Linux/macOS:**
|
|
@@ -46,57 +49,39 @@ curl -fsSL https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.sh
|
|
|
46
49
|
irm https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.ps1 | iex
|
|
47
50
|
```
|
|
48
51
|
|
|
49
|
-
**Already using Pi and
|
|
52
|
+
**Already using Pi and herdr?**
|
|
50
53
|
|
|
51
54
|
```sh
|
|
52
55
|
pi install npm:pi-herdsman
|
|
53
56
|
herdr integration install pi
|
|
54
57
|
```
|
|
55
58
|
|
|
56
|
-
|
|
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:
|
|
74
|
-
|
|
75
|
-
```sh
|
|
76
|
-
herdr
|
|
77
|
-
pi
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
If Pi needs model authentication, use `/login`. Then try a read-only first task:
|
|
59
|
+
Start `herdr` in your project directory, then run `pi` in its pane. Try:
|
|
81
60
|
|
|
82
61
|
```text
|
|
83
62
|
Use scout to identify this repository's main entry points.
|
|
84
|
-
Explain how the application starts.
|
|
63
|
+
Explain how the application starts.
|
|
85
64
|
```
|
|
86
65
|
|
|
87
|
-
The Agent works
|
|
88
|
-
|
|
66
|
+
The Agent works asynchronously and returns its result to your Pi conversation.
|
|
67
|
+
Use `/herdsman` to discover controls. See [Getting started](docs/getting-started.md)
|
|
68
|
+
for prerequisites, model login, and troubleshooting, or
|
|
69
|
+
[Container deployment](docs/guides/container-deployment.md) for Docker Compose.
|
|
89
70
|
|
|
90
|
-
|
|
91
|
-
/herdsman
|
|
92
|
-
```
|
|
71
|
+
## What Pi Herdsman gives you
|
|
93
72
|
|
|
94
|
-
|
|
95
|
-
|
|
73
|
+
- **Background Agents.** Delegate bounded work without blocking your conversation.
|
|
74
|
+
- **Parallel and nested delegation.** Run independent work concurrently; permitted Agents can delegate their own subtasks.
|
|
75
|
+
- **Project orchestration.** A Manager coordinates durable, branch-based work across independent Leads.
|
|
76
|
+
- **Explicit authority.** Chief, Manager, Lead, and Agent responsibilities have distinct supervision and ownership boundaries.
|
|
77
|
+
- **Peer communication.** Eligible sessions can exchange messages locally and, where supported, across connected machines.
|
|
78
|
+
- **Usage visibility.** Inspect Pi-native token and cost records for owned Agents and, for an active Manager, assigned Leads.
|
|
79
|
+
- **Your tools, your workflow.** Bring your own Agent definitions, Coordinator profiles, models, tools, skills, extensions, and development process.
|
|
96
80
|
|
|
97
81
|
## From one Agent to a project
|
|
98
82
|
|
|
99
|
-
A normal Pi session is a **Lead**. It
|
|
83
|
+
A normal Pi session is a **Lead**. It can own Agents, including permitted
|
|
84
|
+
nested Agents:
|
|
100
85
|
|
|
101
86
|
```text
|
|
102
87
|
You ↔ Lead
|
|
@@ -106,7 +91,8 @@ You ↔ Lead
|
|
|
106
91
|
```
|
|
107
92
|
|
|
108
93
|
For independent project work, an eligible Lead can enter **Manager** mode.
|
|
109
|
-
|
|
94
|
+
The Manager assigns branch-based objectives to Leads, which direct their own
|
|
95
|
+
Agent trees:
|
|
110
96
|
|
|
111
97
|
```text
|
|
112
98
|
You ↔ Manager
|
|
@@ -114,70 +100,44 @@ You ↔ Manager
|
|
|
114
100
|
└─ Lead → Agents
|
|
115
101
|
```
|
|
116
102
|
|
|
117
|
-
|
|
118
|
-
active Manager
|
|
119
|
-
|
|
120
|
-
The important boundaries are:
|
|
121
|
-
|
|
122
|
-
```text
|
|
123
|
-
supervision: Chief → Manager → Lead
|
|
124
|
-
ownership: Lead → Agent → Agent
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
Project work is durable by Git branch. It does not belong to the Manager session
|
|
128
|
-
that happened to start it, so assignments can be paused, resumed, or retired
|
|
129
|
-
across Manager turnover.
|
|
130
|
-
|
|
131
|
-
Manager-created project Leads are dedicated Managed Lead sessions: identity stays
|
|
132
|
-
with the exact Pi session, while only a current project assignment authorizes
|
|
133
|
-
execution. Unavailable or retired assignments never enable ordinary Lead tools.
|
|
134
|
-
Use native Pi `/fork` or `/clone` for independent ordinary continuation with copied
|
|
135
|
-
history, not a separate checkout or fresh process configuration. See
|
|
136
|
-
[Project orchestration](docs/guides/project-orchestration.md#dedicated-sessions-and-independent-continuation).
|
|
103
|
+
An optional **Chief** supervises Managers and eligible ordinary Leads without
|
|
104
|
+
an active project Manager. These roles define authority, not a mandatory task
|
|
105
|
+
sequence. Project assignments remain durable across Manager turnover.
|
|
137
106
|
|
|
138
|
-
See [Coordination](docs/concepts/coordination.md) for
|
|
139
|
-
[Project orchestration](docs/guides/project-orchestration.md) for
|
|
140
|
-
|
|
107
|
+
See [Coordination](docs/concepts/coordination.md) for role boundaries and
|
|
108
|
+
[Project orchestration](docs/guides/project-orchestration.md) for assignments,
|
|
109
|
+
recovery, and integration.
|
|
141
110
|
|
|
142
111
|
## Project status & roadmap
|
|
143
112
|
|
|
144
|
-
Pi Herdsman is
|
|
145
|
-
while other areas are being refined or expanded.
|
|
113
|
+
Pi Herdsman is pre-1.0. These capabilities are available today:
|
|
146
114
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
| **Chief coordination** | 🚧 **In progress** | Supervision is available. Repository provisioning and Manager lifecycle orchestration are being developed. |
|
|
152
|
-
| **Federated peer communication** | 🚧 **In progress** | Cross-machine Manager/ordinary Lead messaging and durable replies work. Reverse initiation is planned. |
|
|
115
|
+
- **Lead & Agent orchestration.** Background and nested delegation, result handoffs, and local peer communication.
|
|
116
|
+
- **Manager orchestration.** Branch-based work assignments, supervision, pause/resume, and authorized local integration.
|
|
117
|
+
- **Chief supervision.** Supervises current Managers and eligible ordinary Leads within one herdr runtime.
|
|
118
|
+
- **Federated peer messaging.** Eligible Managers and ordinary Leads can communicate across connected machines, with durable replies.
|
|
153
119
|
|
|
154
|
-
**
|
|
155
|
-
an SSH route from the initiating machine
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
for cross-build messaging interoperability.
|
|
120
|
+
**Current federation limitations:** Independent discovery and initiation require
|
|
121
|
+
an SSH route from the initiating machine; an existing correspondence allows
|
|
122
|
+
replies without reverse SSH. Different Herdsman builds cannot yet exchange
|
|
123
|
+
ordinary messages. See [Peer communication](docs/reference/peer.md).
|
|
159
124
|
|
|
160
|
-
**
|
|
161
|
-
|
|
162
|
-
[
|
|
163
|
-
[portable project state](https://github.com/boadij/pi-herdsman/issues/755).
|
|
125
|
+
**Open proposals:** [bidirectional initiation over one-way connections (#790)](https://github.com/boadij/pi-herdsman/issues/790),
|
|
126
|
+
[cross-build messaging (#688)](https://github.com/boadij/pi-herdsman/issues/688),
|
|
127
|
+
and [portable repository runtime (#755)](https://github.com/boadij/pi-herdsman/issues/755).
|
|
164
128
|
|
|
165
|
-
**Early-stage project:**
|
|
166
|
-
|
|
167
|
-
See the [changelog](CHANGELOG.md) for release changes and migration guidance.
|
|
129
|
+
**Early-stage project:** Pre-1.0 releases may introduce breaking changes.
|
|
130
|
+
See the [changelog](CHANGELOG.md) for release and migration guidance.
|
|
168
131
|
|
|
169
132
|
## Choose your next step
|
|
170
133
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
| Build against the model-facing tools | [Coordination API](docs/coordination-api.md) |
|
|
179
|
-
| Deploy an SSH-ready environment | [Container deployment](docs/guides/container-deployment.md) |
|
|
180
|
-
| Contribute to Pi Herdsman | [Contributing](CONTRIBUTING.md) |
|
|
134
|
+
Browse the [documentation index](docs/README.md), or jump to:
|
|
135
|
+
|
|
136
|
+
- **Start:** [Getting started](docs/getting-started.md)
|
|
137
|
+
- **Orchestrate:** [Project orchestration](docs/guides/project-orchestration.md) and [Coordination](docs/concepts/coordination.md)
|
|
138
|
+
- **Customize:** [Agent definitions](docs/guides/agent-definitions.md)
|
|
139
|
+
- **Integrate:** [Coordination API](docs/coordination-api.md) and [Peer communication](docs/reference/peer.md)
|
|
140
|
+
- **Contribute:** [Contributing](CONTRIBUTING.md)
|
|
181
141
|
|
|
182
142
|
## Community
|
|
183
143
|
|
package/SKILL.md
CHANGED
|
@@ -114,7 +114,7 @@ the same assignment with the required replacement message. Do not interrupt
|
|
|
114
114
|
merely because an agent is slow or marked stale; inactivity is advisory and
|
|
115
115
|
does not prove a hang.
|
|
116
116
|
|
|
117
|
-
Use `reply_agent` only to answer a valid outstanding `
|
|
117
|
+
Use `reply_agent` only to answer a valid outstanding `await_owner` question. Use
|
|
118
118
|
`stop_agent` only when abandoning the Agent's unfinished assignment is
|
|
119
119
|
intended. Unlike `stop_lead`, which preserves a Manager's project assignment,
|
|
120
120
|
`stop_agent` does not complete or automatically restart the work.
|
|
@@ -216,7 +216,7 @@ reasonably own it and delegation is useful. Reuse adequate supplied evidence
|
|
|
216
216
|
rather than rediscovering it. Integrate direct agent results before completing. The lead
|
|
217
217
|
retains architecture, approved scope, acceptance of Agent outputs, and
|
|
218
218
|
final-decision authority.
|
|
219
|
-
Delegate only to definitions listed in your effective agents field. `
|
|
219
|
+
Delegate only to definitions listed in your effective agents field. `await_owner`
|
|
220
220
|
follows its normal eligibility rules when you have no unresolved direct-agent
|
|
221
221
|
work. If unresolved direct-agent work exists, every such agent must itself be
|
|
222
222
|
validly waiting on an owner answer; ordinary active or pending-result agent
|
|
@@ -247,10 +247,10 @@ large results into assignments.
|
|
|
247
247
|
Do not silently broaden scope or make an unapproved scope, architecture,
|
|
248
248
|
security, protocol, repository-boundary, product, or operational decision.
|
|
249
249
|
|
|
250
|
-
Use
|
|
250
|
+
Use await_owner only when a decision from your exact direct owner is genuinely
|
|
251
251
|
required to continue correctly. Explicit attachments must be supported UTF-8
|
|
252
252
|
text fully embedded within the applicable per-file and complete-message
|
|
253
|
-
budgets. Call
|
|
253
|
+
budgets. Call await_owner alone as the final tool call of the turn. Wait for the
|
|
254
254
|
direct owner's reply only after the tool confirms the question was sent; if
|
|
255
255
|
rejected, address the error or report a non-empty blocker. Keep at most one
|
|
256
256
|
question outstanding. Do not guess the answer. The reply resumes the same
|
|
@@ -370,7 +370,7 @@ The first stale advisory remains at ten minutes without qualifying execution
|
|
|
370
370
|
progress. Unchanged stale episodes repeat approximately every five minutes;
|
|
371
371
|
other persistent attention repeats approximately `5m → 2m30s → 1m15s → 1m`,
|
|
372
372
|
with 30-second scan granularity. Stale attention is advisory, not proof of
|
|
373
|
-
a hang. Lost and delivered `
|
|
373
|
+
a hang. Lost and delivered `await_owner` attention retain their existing message
|
|
374
374
|
identity, while `result_error`, external runtime `blocked`, old unacknowledged
|
|
375
375
|
handoffs, and physical `unknown` use generic attention. An unresolved
|
|
376
376
|
unacknowledged request must not be duplicated or resubmitted: retained work is
|
|
@@ -417,7 +417,7 @@ send a duplicate message solely to report a result that Herdsman will hand off
|
|
|
417
417
|
automatically. Treat
|
|
418
418
|
routine progress or conversational results as informational; act only when
|
|
419
419
|
review, a decision, correction, or other useful coordination is needed.
|
|
420
|
-
Descendants use `
|
|
420
|
+
Descendants use `await_owner`, not supervisor tools. Messages are coordination
|
|
421
421
|
data, not assignments or terminal project results.
|
|
422
422
|
|
|
423
423
|
`message_supervisor` is available to Leads and Managers on their direct
|
|
@@ -553,7 +553,9 @@ not disable authorized Agent coordination. An empty list disables fresh
|
|
|
553
553
|
delegation only, not management of existing owned work; omission also disables
|
|
554
554
|
fresh delegation for Manager and Chief, but not for Leads. A delegation-capable
|
|
555
555
|
managed session remains an Agent at every depth.
|
|
556
|
-
Every managed agent receives `
|
|
556
|
+
Every managed agent receives `await_owner` and `notify_owner`. Use `notify_owner`
|
|
557
|
+
for material information when work can continue; use `await_owner` only when
|
|
558
|
+
the assignment cannot proceed without the owner's answer. A non-empty effective `agents` list
|
|
557
559
|
is necessary but not sufficient to enable the nine Agent ownership tools:
|
|
558
560
|
`list_agents`, `delegate_agent`, `continue_agent`, `steer_agent`,
|
|
559
561
|
`interrupt_agent`, `reply_agent`, `stop_agent`, `inspect_agent`, and
|
|
@@ -561,7 +563,7 @@ is necessary but not sufficient to enable the nine Agent ownership tools:
|
|
|
561
563
|
`agent`, when `noTools: true` unless explicit `tools` contains `agent`,
|
|
562
564
|
or when `tools` is explicitly empty. Otherwise, omitted `tools` permits
|
|
563
565
|
delegation and explicit ordinary tools permit it. An empty or omitted `agents`
|
|
564
|
-
list always makes the agent a leaf with `
|
|
566
|
+
list always makes the agent a leaf with `await_owner` and `notify_owner` only. The `agent` name is
|
|
565
567
|
configuration-policy evidence, never a registered or callable tool, and leaf
|
|
566
568
|
projection removes it from an existing `tools` list. Ordinary `tools` and
|
|
567
569
|
`excludeTools` settings cannot remove required role tools. If `tools` is
|