pi-herdsman 0.32.1 → 0.33.1
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/README.md +25 -20
- package/SKILL.md +35 -19
- package/dist/agent-definitions/chief.md +4 -0
- package/dist/agent-definitions/manager.md +15 -2
- package/dist/index.js +3190 -542
- package/dist/index.js.map +4 -4
- package/dist/peer-bridge.js +2040 -0
- package/dist/peer-bridge.js.map +7 -0
- package/docs/adr/0032-authorize-manager-integration-and-finalization.md +68 -0
- package/docs/concepts/agents.md +4 -0
- package/docs/concepts/coordination.md +16 -7
- package/docs/coordination-api.md +1 -1
- package/docs/development/smoke-testing.md +22 -2
- package/docs/development/validation.md +16 -6
- package/docs/getting-started.md +24 -113
- package/docs/guides/container-deployment.md +7 -0
- package/docs/guides/customizing-agents.md +6 -6
- package/docs/guides/handoffs.md +6 -7
- package/docs/guides/project-orchestration.md +33 -10
- package/docs/reference/agent.md +12 -1
- package/docs/reference/commands.md +9 -0
- package/docs/reference/configuration.md +29 -1
- package/docs/reference/peer.md +60 -3
- package/docs/reference/staff.md +52 -11
- package/docs/reference/status-widget.md +9 -2
- package/package.json +4 -1
package/README.md
CHANGED
|
@@ -9,15 +9,16 @@
|
|
|
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
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
12
|
+
Pi Herdsman lets your AI coding assistant delegate tasks to background Agents
|
|
13
|
+
while your main conversation stays interactive. Start with one Agent, or
|
|
14
|
+
coordinate parallel, branch-based project work across independent Leads.
|
|
15
|
+
|
|
16
|
+
Pi runs the coding-agent conversations; herdr manages their terminal sessions
|
|
17
|
+
and workspaces; Herdsman coordinates delegation, ownership, and supervision.
|
|
17
18
|
|
|
18
19
|
## Demo
|
|
19
20
|
|
|
20
|
-
|
|
21
|
+
_Advanced orchestration: a live Manager → Lead → Agent workflow._
|
|
21
22
|
|
|
22
23
|
[](https://github.com/user-attachments/assets/d6ee6687-a96d-493e-ae75-429f586be393)
|
|
23
24
|
|
|
@@ -27,51 +28,54 @@ _Realtime live demo of a manager > lead > agent workflow._
|
|
|
27
28
|
- **Parallel and nested delegation.** Run independent work concurrently and let explicitly enabled Agents delegate their own bounded subtasks.
|
|
28
29
|
- **Project orchestration.** A Manager coordinates durable branch-based work across independent Leads and their Agent trees.
|
|
29
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.
|
|
30
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.
|
|
31
33
|
- **Your workflow stays yours.** Bring your own Agent definitions, models, tools, skills, extensions, and development process.
|
|
32
34
|
|
|
33
35
|
## Quick start
|
|
34
36
|
|
|
35
|
-
|
|
37
|
+
**Linux/macOS:**
|
|
36
38
|
|
|
37
39
|
```sh
|
|
38
40
|
curl -fsSL https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.sh | sh
|
|
39
41
|
```
|
|
40
42
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
+
**Windows (PowerShell):**
|
|
44
|
+
|
|
45
|
+
```powershell
|
|
46
|
+
irm https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.ps1 | iex
|
|
47
|
+
```
|
|
43
48
|
|
|
44
|
-
|
|
49
|
+
**Already using Pi and Herdr?**
|
|
45
50
|
|
|
46
51
|
```sh
|
|
47
52
|
pi install npm:pi-herdsman
|
|
48
53
|
herdr integration install pi
|
|
49
54
|
```
|
|
50
55
|
|
|
51
|
-
|
|
56
|
+
In your project directory, start herdr and then Pi inside its pane:
|
|
52
57
|
|
|
53
58
|
```sh
|
|
54
59
|
herdr
|
|
55
60
|
pi
|
|
56
61
|
```
|
|
57
62
|
|
|
58
|
-
|
|
63
|
+
If Pi needs model authentication, use `/login`. Then try a read-only first task:
|
|
59
64
|
|
|
60
65
|
```text
|
|
61
|
-
Use scout to
|
|
66
|
+
Use scout to identify this repository's main entry points.
|
|
67
|
+
Explain how the application starts. Don't change any files.
|
|
62
68
|
```
|
|
63
69
|
|
|
64
|
-
The Agent
|
|
65
|
-
|
|
70
|
+
The Agent works independently and sends its result back to the conversation
|
|
71
|
+
that delegated the task. Discover Agent management and other capabilities with:
|
|
66
72
|
|
|
67
73
|
```text
|
|
68
|
-
/
|
|
74
|
+
/herdsman
|
|
69
75
|
```
|
|
70
76
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
See [Getting started](docs/getting-started.md) for prerequisites, configuration,
|
|
74
|
-
observability, and the complete first-use path.
|
|
77
|
+
See [Getting started](docs/getting-started.md) for prerequisites and
|
|
78
|
+
troubleshooting.
|
|
75
79
|
|
|
76
80
|
## From one Agent to a project
|
|
77
81
|
|
|
@@ -124,6 +128,7 @@ workflow.
|
|
|
124
128
|
| ------------------------------------------ | ------------------------------------------------------------- |
|
|
125
129
|
| Install and delegate your first task | [Getting started](docs/getting-started.md) |
|
|
126
130
|
| Run independent branch-based project work | [Project orchestration](docs/guides/project-orchestration.md) |
|
|
131
|
+
| Communicate with other Pi sessions | [Peer communication](docs/reference/peer.md) |
|
|
127
132
|
| Understand roles, ownership, and authority | [Coordination](docs/concepts/coordination.md) |
|
|
128
133
|
| Customize Agents | [Agent definitions](docs/guides/agent-definitions.md) |
|
|
129
134
|
| Build against the model-facing tools | [Coordination API](docs/coordination-api.md) |
|
package/SKILL.md
CHANGED
|
@@ -58,7 +58,8 @@ Use these high-salience rules for the model-facing agent boundary:
|
|
|
58
58
|
requests, steering, sleep, or
|
|
59
59
|
other waiting mechanisms, and do not invent work merely to remain active.
|
|
60
60
|
|
|
61
|
-
|
|
61
|
+
Leads use `list_peers` and `message_peer` for eligible same-role peers.
|
|
62
|
+
Managed Leads are limited to their verified project worktree group and socket;
|
|
62
63
|
managed agents are not peers. `list_peers` identifies this Lead as `self` and
|
|
63
64
|
returns other live Leads as `peers` with exact session IDs. Incoming peer messages are already
|
|
64
65
|
addressed to this Lead; `Peer message from <sender lead ID>: <body>` identifies
|
|
@@ -70,9 +71,9 @@ Use `list_agents` when fresh agent state or ownership is materially needed for a
|
|
|
70
71
|
control or recovery decision, or to refresh the definition roster after
|
|
71
72
|
configuration changes. Do not use `list_agents` merely to check progress.
|
|
72
73
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
74
|
+
For a new bounded delegated task, prefer `continue_agent` when a known,
|
|
75
|
+
eligible historical managed-Agent Pi session contains substantial context
|
|
76
|
+
relevant to that task. Otherwise use `delegate_agent` for a fresh assignment.
|
|
76
77
|
|
|
77
78
|
Each managed agent exists for one assignment only. After its terminal result is
|
|
78
79
|
delivered, Pi Herdsman cleans up that agent automatically. To continue completed
|
|
@@ -179,14 +180,16 @@ objective. Decompose only as far as useful. Reuse adequate existing evidence
|
|
|
179
180
|
instead of duplicating work. The active Lead execution profile determines the
|
|
180
181
|
balance between direct and delegated work. Ordinary Leads use `flexible-lead`
|
|
181
182
|
or `orchestrator-lead` according to their persisted `flexible` or
|
|
182
|
-
`orchestrate` execution mode.
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
183
|
+
`orchestrate` execution mode. These ordinary sessions execute their authorized
|
|
184
|
+
independent Lead work without requiring a `ProjectAssignment`. Manager-assigned
|
|
185
|
+
Leads use `managed-lead`; the exact current `ProjectAssignment`, not the profile,
|
|
186
|
+
establishes Manager authority. Managed identity is permanent for the exact Pi
|
|
187
|
+
session, including when assignment evidence is unavailable or the assignment
|
|
188
|
+
is retired. Only a current exact assignment permits fresh managed project
|
|
189
|
+
execution; exactly owned Agent recovery remains separate. Use native Pi
|
|
190
|
+
`/fork` or `/clone` for independent ordinary continuation, not a separate Git
|
|
191
|
+
checkout or fresh process configuration. Lead execution configuration does
|
|
192
|
+
not change Agent ownership semantics.
|
|
190
193
|
|
|
191
194
|
<!-- pi-herdsman-runtime-lead:end -->
|
|
192
195
|
|
|
@@ -409,10 +412,10 @@ through `files`.
|
|
|
409
412
|
Chief uses `list_staff`, `inspect_staff`, `read_staff_transcript`, and
|
|
410
413
|
`message_staff`. Manager has those same direct-report tools, peer tools, and
|
|
411
414
|
`delegate_project`, `resume_project`, and `stop_lead`.
|
|
412
|
-
For administrative removal of
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
415
|
+
For administrative removal of project-owned evidence, use the Manager's
|
|
416
|
+
**Retained evidence** menu and its **Remove requirement…** action. Inherited
|
|
417
|
+
requirements are protected; snapshots and accepted Agent evidence remain
|
|
418
|
+
unchanged.
|
|
416
419
|
`inspect_staff` provides bounded live terminal/process evidence;
|
|
417
420
|
`read_staff_transcript` provides bounded persisted Pi conversation/tool evidence.
|
|
418
421
|
Target a Lead by the exact full Pi session ID in a fresh snapshot or
|
|
@@ -448,9 +451,10 @@ Pi Herdsman uses one durable vocabulary:
|
|
|
448
451
|
- a **Manager** explicitly assumes dedicated project coordination from that
|
|
449
452
|
group's primary workspace and does not own supervised Leads' Agents. It may
|
|
450
453
|
separately delegate directly to definitions in its effective `agents`
|
|
451
|
-
profile.
|
|
452
|
-
|
|
453
|
-
|
|
454
|
+
profile. Project operations control only currently assigned Leads; eligible
|
|
455
|
+
ordinary Leads in the verified worktree group are direct reports for
|
|
456
|
+
observation and communication. Leads own technical decisions and orchestrate
|
|
457
|
+
execution through their Agent trees;
|
|
454
458
|
- project work belongs to the project, not a Manager session. The project
|
|
455
459
|
assignment represents open work and its Git branch is the work handle. A
|
|
456
460
|
Manager uses `delegate_project` with a task and optional branch to start new
|
|
@@ -460,6 +464,18 @@ Pi Herdsman uses one durable vocabulary:
|
|
|
460
464
|
pending project messages. Unavailable or ambiguous inventory preserves the
|
|
461
465
|
assignment. A retired assignment cannot be resumed, but new work may reuse
|
|
462
466
|
its remaining Git branch;
|
|
467
|
+
- the Manager owns project-level integration decisions. When separately
|
|
468
|
+
authorized by the Manager local-merge policy, it can accept the exact
|
|
469
|
+
validated source revision and use `merge_project` to fast-forward that
|
|
470
|
+
assigned branch into the verified primary branch. A `needs_update` result
|
|
471
|
+
means ask the responsible Lead to incorporate the reported target revision,
|
|
472
|
+
resolve actual conflicts, validate, and report the new exact HEAD; it does
|
|
473
|
+
not itself prove a content conflict. Leads retain technical integration and
|
|
474
|
+
validation ownership. When cleanup is incomplete, `cleanup_pending` reports
|
|
475
|
+
integration separately from checkout removal and assignment retirement; an
|
|
476
|
+
authorized retry with the same accepted SHA can retry guarded cleanup,
|
|
477
|
+
including reconciling an already-absent checkout only after Git proves that
|
|
478
|
+
SHA is on the verified primary branch;
|
|
463
479
|
- each completed direct turn by an assigned Lead is automatically returned as a
|
|
464
480
|
project message to the current or a replacement Manager; if managed Agent
|
|
465
481
|
work is active, the herd run owns the handoff until it settles, and the
|
|
@@ -12,5 +12,9 @@ human's objectives.
|
|
|
12
12
|
Interpret reports, resolve cross-project priorities and decisions, and
|
|
13
13
|
synthesize useful outcomes for the human.
|
|
14
14
|
|
|
15
|
+
When eligible same-role direct reports need technical coordination, prefer
|
|
16
|
+
having them communicate directly rather than relaying their messages.
|
|
17
|
+
Retain cross-project priorities, decisions, and synthesis.
|
|
18
|
+
|
|
15
19
|
Prefer focused coordination over unnecessary intervention. Treat routine
|
|
16
20
|
progress as informational.
|
|
@@ -8,11 +8,24 @@ tools: []
|
|
|
8
8
|
|
|
9
9
|
Coordinate assigned project work through Leads.
|
|
10
10
|
|
|
11
|
-
Set priorities, resolve project-level decisions and
|
|
12
|
-
outcomes, and request corrections through the responsible Lead.
|
|
11
|
+
Set priorities, resolve project-level decisions and dependency sequencing,
|
|
12
|
+
review outcomes, and request corrections through the responsible Lead.
|
|
13
|
+
When assigned Leads need to exchange technical information, prefer having
|
|
14
|
+
them coordinate directly when eligible; mediate when project-level decisions
|
|
15
|
+
or unavailable peer communication require it.
|
|
13
16
|
Leave technical investigation, implementation, review, validation, and
|
|
14
17
|
integration to that Lead and its Agents rather than doing or delegating
|
|
15
18
|
the work yourself.
|
|
16
19
|
|
|
20
|
+
When local Manager merge permission is enabled, you may use `merge_project`
|
|
21
|
+
only for an exact assigned branch after accepting its validated full source
|
|
22
|
+
SHA. It fast-forwards the verified primary branch only. If the target has
|
|
23
|
+
advanced, ask the responsible Lead to incorporate the target, preserve prior
|
|
24
|
+
integrated changes, rerun relevant checks, and report the exact validated
|
|
25
|
+
source SHA; a non-fast-forward result alone does not establish a conflict.
|
|
26
|
+
Successful integration can automatically remove that exact source worktree
|
|
27
|
+
and retire its assignment. You retain project-level acceptance authority;
|
|
28
|
+
the Lead retains technical resolution and validation ownership.
|
|
29
|
+
|
|
17
30
|
Treat routine progress as informational. Intervene when a project-level
|
|
18
31
|
decision or meaningful coordination is needed.
|