pi-herdsman 0.33.0 → 0.34.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/README.md +8 -8
- package/SKILL.md +21 -16
- package/dist/agent-definitions/chief.md +4 -0
- package/dist/agent-definitions/generalist.md +1 -1
- package/dist/agent-definitions/manager.md +5 -2
- package/dist/index.js +1202 -194
- package/dist/index.js.map +3 -3
- package/dist/peer-bridge.js +26 -7
- package/dist/peer-bridge.js.map +3 -3
- package/docs/adr/0033-allow-human-confirmed-legacy-assignment-release.md +40 -0
- package/docs/concepts/coordination.md +5 -4
- package/docs/concepts/lifecycle.md +19 -8
- package/docs/coordination-api.md +1 -1
- package/docs/development/instruction-interface-design.md +5 -0
- package/docs/development/smoke-testing.md +11 -1
- package/docs/development/validation.md +7 -6
- package/docs/guides/agent-definitions.md +9 -1
- package/docs/guides/customizing-agents.md +6 -6
- package/docs/guides/handoffs.md +6 -7
- package/docs/guides/project-orchestration.md +31 -10
- package/docs/guides/recovery.md +18 -2
- package/docs/reference/agent.md +14 -3
- package/docs/reference/commands.md +27 -5
- package/docs/reference/configuration.md +19 -11
- package/docs/reference/peer.md +2 -1
- package/docs/reference/staff.md +8 -10
- package/docs/reference/status-widget.md +1 -1
- package/package.json +1 -1
- package/skills/agent-definitions/SKILL.md +4 -1
package/README.md
CHANGED
|
@@ -7,14 +7,14 @@
|
|
|
7
7
|
[](https://github.com/boadij/pi-herdsman/actions/workflows/validate.yml)
|
|
8
8
|
[](LICENSE)
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
running in the background, while you continue using your main conversation.
|
|
12
|
-
Start with one Agent, or coordinate independent work across a larger project.
|
|
10
|
+
**The orchestration layer between [Pi](https://github.com/earendil-works/pi) and [herdr](https://github.com/herdrdev/herdr).**
|
|
13
11
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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.
|
|
18
18
|
|
|
19
19
|
## Demo
|
|
20
20
|
|
|
@@ -28,7 +28,7 @@ _Advanced orchestration: a live Manager → Lead → Agent workflow._
|
|
|
28
28
|
- **Parallel and nested delegation.** Run independent work concurrently and let explicitly enabled Agents delegate their own bounded subtasks.
|
|
29
29
|
- **Project orchestration.** A Manager coordinates durable branch-based work across independent Leads and their Agent trees.
|
|
30
30
|
- **Direct supervision.** Chief, Manager, Lead, and Agent responsibilities stay explicit instead of collapsing into one global controller.
|
|
31
|
-
- **Peer communication.** Leads can
|
|
31
|
+
- **Peer communication.** Leads can message eligible peers locally; unassigned ordinary Leads and Managers can also collaborate across connected machines.
|
|
32
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
33
|
- **Your workflow stays yours.** Bring your own Agent definitions, models, tools, skills, extensions, and development process.
|
|
34
34
|
|
package/SKILL.md
CHANGED
|
@@ -58,7 +58,9 @@ 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
|
+
Message a peer when concrete task coordination is useful; avoid routine broadcasts and gratuitous acknowledgments, while answering requested questions and sharing useful evidence.
|
|
63
|
+
Managed Leads are limited to their verified project worktree group and socket;
|
|
62
64
|
managed agents are not peers. `list_peers` identifies this Lead as `self` and
|
|
63
65
|
returns other live Leads as `peers` with exact session IDs. Incoming peer messages are already
|
|
64
66
|
addressed to this Lead; `Peer message from <sender lead ID>: <body>` identifies
|
|
@@ -179,14 +181,16 @@ objective. Decompose only as far as useful. Reuse adequate existing evidence
|
|
|
179
181
|
instead of duplicating work. The active Lead execution profile determines the
|
|
180
182
|
balance between direct and delegated work. Ordinary Leads use `flexible-lead`
|
|
181
183
|
or `orchestrator-lead` according to their persisted `flexible` or
|
|
182
|
-
`orchestrate` execution mode.
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
184
|
+
`orchestrate` execution mode. These ordinary sessions execute their authorized
|
|
185
|
+
independent Lead work without requiring a `ProjectAssignment`. Manager-assigned
|
|
186
|
+
Leads use `managed-lead`; the exact current `ProjectAssignment`, not the profile,
|
|
187
|
+
establishes Manager authority. Managed identity is permanent for the exact Pi
|
|
188
|
+
session, including when assignment evidence is unavailable or the assignment
|
|
189
|
+
is retired. Only a current exact assignment permits fresh managed project
|
|
190
|
+
execution; exactly owned Agent recovery remains separate. Use native Pi
|
|
191
|
+
`/fork` or `/clone` for independent ordinary continuation, not a separate Git
|
|
192
|
+
checkout or fresh process configuration. Lead execution configuration does
|
|
193
|
+
not change Agent ownership semantics.
|
|
190
194
|
|
|
191
195
|
<!-- pi-herdsman-runtime-lead:end -->
|
|
192
196
|
|
|
@@ -409,10 +413,10 @@ through `files`.
|
|
|
409
413
|
Chief uses `list_staff`, `inspect_staff`, `read_staff_transcript`, and
|
|
410
414
|
`message_staff`. Manager has those same direct-report tools, peer tools, and
|
|
411
415
|
`delegate_project`, `resume_project`, and `stop_lead`.
|
|
412
|
-
For administrative removal of
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
+
For administrative removal of project-owned evidence, use the Manager's
|
|
417
|
+
**Retained evidence** menu and its **Remove requirement…** action. Inherited
|
|
418
|
+
requirements are protected; snapshots and accepted Agent evidence remain
|
|
419
|
+
unchanged.
|
|
416
420
|
`inspect_staff` provides bounded live terminal/process evidence;
|
|
417
421
|
`read_staff_transcript` provides bounded persisted Pi conversation/tool evidence.
|
|
418
422
|
Target a Lead by the exact full Pi session ID in a fresh snapshot or
|
|
@@ -448,9 +452,10 @@ Pi Herdsman uses one durable vocabulary:
|
|
|
448
452
|
- a **Manager** explicitly assumes dedicated project coordination from that
|
|
449
453
|
group's primary workspace and does not own supervised Leads' Agents. It may
|
|
450
454
|
separately delegate directly to definitions in its effective `agents`
|
|
451
|
-
profile.
|
|
452
|
-
|
|
453
|
-
|
|
455
|
+
profile. Project operations control only currently assigned Leads; eligible
|
|
456
|
+
ordinary Leads in the verified worktree group are direct reports for
|
|
457
|
+
observation and communication. Leads own technical decisions and orchestrate
|
|
458
|
+
execution through their Agent trees;
|
|
454
459
|
- project work belongs to the project, not a Manager session. The project
|
|
455
460
|
assignment represents open work and its Git branch is the work handle. A
|
|
456
461
|
Manager uses `delegate_project` with a task and optional branch to start new
|
|
@@ -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.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
agents: [scout, researcher]
|
|
3
|
-
description: General-purpose execution
|
|
3
|
+
description: General-purpose execution for bounded investigation, editing, and validation; use when work spans capabilities; prefer focused specialists for narrow tasks
|
|
4
4
|
extensions: []
|
|
5
5
|
inheritGlobalContext: false
|
|
6
6
|
inheritProjectContext: true
|
|
@@ -8,8 +8,11 @@ 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.
|