pi-herdsman 0.32.1 → 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 +26 -21
- package/SKILL.md +15 -3
- package/dist/agent-definitions/manager.md +10 -0
- package/dist/index.js +3050 -491
- package/dist/index.js.map +4 -4
- package/dist/peer-bridge.js +2022 -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 +11 -3
- package/docs/development/smoke-testing.md +22 -2
- package/docs/development/validation.md +9 -0
- package/docs/getting-started.md +24 -113
- package/docs/guides/container-deployment.md +7 -0
- package/docs/guides/project-orchestration.md +23 -0
- 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 +59 -2
- package/docs/reference/staff.md +44 -1
- package/docs/reference/status-widget.md +8 -1
- package/package.json +4 -1
package/README.md
CHANGED
|
@@ -7,17 +7,18 @@
|
|
|
7
7
|
[](https://github.com/boadij/pi-herdsman/actions/workflows/validate.yml)
|
|
8
8
|
[](LICENSE)
|
|
9
9
|
|
|
10
|
-
|
|
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
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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
|
-
|
|
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 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
|
-
|
|
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
|
-
and how the bootstrap handles newer Pi and herdr versions.
|
|
43
|
+
**Windows (PowerShell):**
|
|
43
44
|
|
|
44
|
-
|
|
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
|
-
|
|
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
|
@@ -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
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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.
|