pi-herdsman 0.32.0 → 0.33.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,17 +7,18 @@
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
- **The orchestration layer between [Pi](https://github.com/earendil-works/pi) and [herdr](https://github.com/herdrdev/herdr).**
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.
11
13
 
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.
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.
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 exchange messages locally; 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):**
43
44
 
44
- If you already manage Pi and herdr yourself:
45
+ ```powershell
46
+ irm https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.ps1 | iex
47
+ ```
48
+
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
@@ -70,9 +70,9 @@ Use `list_agents` when fresh agent state or ownership is materially needed for a
70
70
  control or recovery decision, or to refresh the definition roster after
71
71
  configuration changes. Do not use `list_agents` merely to check progress.
72
72
 
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.
73
+ For a new bounded delegated task, prefer `continue_agent` when a known,
74
+ eligible historical managed-Agent Pi session contains substantial context
75
+ relevant to that task. Otherwise use `delegate_agent` for a fresh assignment.
76
76
 
77
77
  Each managed agent exists for one assignment only. After its terminal result is
78
78
  delivered, Pi Herdsman cleans up that agent automatically. To continue completed
@@ -460,6 +460,18 @@ Pi Herdsman uses one durable vocabulary:
460
460
  pending project messages. Unavailable or ambiguous inventory preserves the
461
461
  assignment. A retired assignment cannot be resumed, but new work may reuse
462
462
  its remaining Git branch;
463
+ - the Manager owns project-level integration decisions. When separately
464
+ authorized by the Manager local-merge policy, it can accept the exact
465
+ validated source revision and use `merge_project` to fast-forward that
466
+ assigned branch into the verified primary branch. A `needs_update` result
467
+ means ask the responsible Lead to incorporate the reported target revision,
468
+ resolve actual conflicts, validate, and report the new exact HEAD; it does
469
+ not itself prove a content conflict. Leads retain technical integration and
470
+ validation ownership. When cleanup is incomplete, `cleanup_pending` reports
471
+ integration separately from checkout removal and assignment retirement; an
472
+ authorized retry with the same accepted SHA can retry guarded cleanup,
473
+ including reconciling an already-absent checkout only after Git proves that
474
+ SHA is on the verified primary branch;
463
475
  - each completed direct turn by an assigned Lead is automatically returned as a
464
476
  project message to the current or a replacement Manager; if managed Agent
465
477
  work is active, the herd run owns the handoff until it settles, and the
@@ -14,5 +14,15 @@ Leave technical investigation, implementation, review, validation, and
14
14
  integration to that Lead and its Agents rather than doing or delegating
15
15
  the work yourself.
16
16
 
17
+ When local Manager merge permission is enabled, you may use `merge_project`
18
+ only for an exact assigned branch after accepting its validated full source
19
+ SHA. It fast-forwards the verified primary branch only. If the target has
20
+ advanced, ask the responsible Lead to incorporate the target, preserve prior
21
+ integrated changes, rerun relevant checks, and report the exact validated
22
+ source SHA; a non-fast-forward result alone does not establish a conflict.
23
+ Successful integration can automatically remove that exact source worktree
24
+ and retire its assignment. You retain project-level acceptance authority;
25
+ the Lead retains technical resolution and validation ownership.
26
+
17
27
  Treat routine progress as informational. Intervene when a project-level
18
28
  decision or meaningful coordination is needed.