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 CHANGED
@@ -7,14 +7,14 @@
7
7
  [![Platforms](https://img.shields.io/badge/platforms-Linux%20%7C%20macOS%20%7C%20Windows-blue)](https://github.com/boadij/pi-herdsman/actions/workflows/validate.yml)
8
8
  [![License](https://img.shields.io/npm/l/pi-herdsman)](LICENSE)
9
9
 
10
- Pi Herdsman lets your AI coding assistant delegate tasks to other assistants
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
- [Pi](https://github.com/earendil-works/pi) runs the coding assistants,
15
- [herdr](https://github.com/herdrdev/herdr)
16
- manages their terminal sessions and workspaces, and Herdsman coordinates their
17
- work.
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 exchange messages locally; Managers can also collaborate across connected machines.
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
- Ordinary Leads use `list_peers` and `message_peer` for other ordinary Lead sessions;
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. Manager-assigned Leads use `managed-lead`; the
183
- exact current `ProjectAssignment`, not the profile, establishes Manager
184
- authority. Managed identity is permanent for the exact Pi session, including
185
- when assignment evidence is unavailable or the assignment is retired. Only a
186
- current exact assignment permits fresh project execution; exactly owned Agent
187
- recovery remains separate. Use native Pi `/fork` or `/clone` for independent
188
- ordinary continuation, not a separate Git checkout or fresh process configuration.
189
- Lead execution configuration does not change Agent ownership semantics.
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 a project-owned evidence requirement, use the
413
- Manager project-assignment action menu: **Retained evidence**, inspect the
414
- entry, then **Remove** and confirm. Inherited requirements are protected; this
415
- does not delete snapshots or change evidence already accepted by Agents.
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. Manager controls only Leads named by current project assignments;
452
- project scope alone does not make a Lead a Manager report. Leads own technical
453
- decisions and orchestrate execution through their Agent trees;
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 agent for bounded tasks requiring broad capabilities
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 dependencies, review
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.