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 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 turns independent Pi sessions into a coordinated agent system, from
13
- one background Agent to parallel branch-based project work. Pi owns each
14
- coding-agent conversation; herdr owns processes, panes, workspaces, and worktree
15
- placement; Herdsman connects them through delegation, ownership, supervision,
16
- and project orchestration.
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
- _Realtime live demo of a manager > lead > agent workflow._
21
+ _Advanced orchestration: a live Manager → Lead → Agent workflow._
21
22
 
22
23
  [![Live demo](https://github.com/user-attachments/assets/e1355ace-aaba-418e-a1d0-1246f1840fc6)](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
- On Linux or macOS, install the released Pi, herdr, and Pi Herdsman stack:
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
- See [Getting started](docs/getting-started.md) for the tested runtime baselines
42
- and how the bootstrap handles newer Pi and herdr versions.
43
+ **Windows (PowerShell):**
44
+
45
+ ```powershell
46
+ irm https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.ps1 | iex
47
+ ```
43
48
 
44
- If you already manage Pi and herdr yourself:
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
- Start herdr in your project, then start Pi inside its pane:
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
- Delegate naturally:
63
+ If Pi needs model authentication, use `/login`. Then try a read-only first task:
59
64
 
60
65
  ```text
61
- Use scout to inspect the authentication flow.
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 runs asynchronously while the Lead conversation stays available.
65
- Open the human Agent-management surface at any time with:
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
- /agents
74
+ /herdsman
69
75
  ```
70
76
 
71
- It also exposes `Session stats` for the current Pi session and its owned Agent sessions; in active Manager mode, it includes current assigned project Leads and their owned Agent trees.
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
- 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
+ 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
- Use `delegate_agent` to start one bounded fresh assignment from an agent definition.
74
- Use `continue_agent` to start one bounded assignment from an exact historical
75
- managed-agent Pi session.
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. 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.
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 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.
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. 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;
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 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.
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.