pi-herdsman 0.31.0 → 0.32.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 +7 -0
- package/SKILL.md +24 -22
- package/dist/agent-definitions/managed-lead.md +4 -0
- package/dist/agent-definitions/manager.md +7 -5
- package/dist/index.js +8447 -5849
- package/dist/index.js.map +4 -4
- package/docs/adr/0012-manager-owns-project-assignment-resolution.md +4 -0
- package/docs/adr/0013-use-herdr-worktree-removal-for-project-retirement.md +4 -0
- package/docs/adr/0017-use-project-assignments-for-managed-lead-authority.md +5 -2
- package/docs/adr/0018-use-standalone-lead-execution-profiles.md +4 -0
- package/docs/adr/0019-retire-project-assignments-when-worktrees-are-absent.md +4 -0
- package/docs/adr/0020-authorize-confirmed-manager-worktree-removal.md +15 -5
- package/docs/adr/0022-commit-project-retirement-before-message-cleanup.md +5 -2
- package/docs/adr/0023-deliver-worktree-retirement-through-pending-manager-context.md +4 -0
- package/docs/adr/0025-propagate-explicit-required-assignment-evidence.md +8 -0
- package/docs/adr/0026-manager-owns-project-required-evidence.md +7 -0
- package/docs/adr/0027-deliver-complete-text-in-coordination-messages.md +42 -0
- package/docs/adr/0028-reference-historical-assignment-evidence.md +54 -0
- package/docs/adr/0029-use-immutable-managed-lead-session-identity.md +44 -0
- package/docs/adr/0030-project-scoped-manager-removal-approval.md +44 -0
- package/docs/adr/0031-durable-manager-worktree-removal-approval.md +46 -0
- package/docs/concepts/coordination.md +9 -11
- package/docs/concepts/lifecycle.md +15 -3
- package/docs/coordination-api.md +2 -5
- package/docs/development/instruction-interface-design.md +39 -0
- package/docs/development/smoke-testing.md +29 -13
- package/docs/development/validation.md +2 -2
- package/docs/guides/handoffs.md +62 -18
- package/docs/guides/project-orchestration.md +37 -22
- package/docs/guides/recovery.md +4 -0
- package/docs/reference/agent-definition-schema.md +5 -1
- package/docs/reference/agent-states.md +19 -11
- package/docs/reference/agent.md +43 -7
- package/docs/reference/commands.md +38 -40
- package/docs/reference/configuration.md +25 -17
- package/docs/reference/peer.md +13 -11
- package/docs/reference/staff.md +23 -19
- package/docs/reference/status-widget.md +9 -6
- package/docs/reference/supervisor.md +9 -6
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -107,6 +107,13 @@ Project work is durable by Git branch. It does not belong to the Manager session
|
|
|
107
107
|
that happened to start it, so assignments can be paused, resumed, or retired
|
|
108
108
|
across Manager turnover.
|
|
109
109
|
|
|
110
|
+
Manager-created project Leads are dedicated Managed Lead sessions: identity stays
|
|
111
|
+
with the exact Pi session, while only a current project assignment authorizes
|
|
112
|
+
execution. Unavailable or retired assignments never enable ordinary Lead tools.
|
|
113
|
+
Use native Pi `/fork` or `/clone` for independent ordinary continuation with copied
|
|
114
|
+
history, not a separate checkout or fresh process configuration. See
|
|
115
|
+
[Project orchestration](docs/guides/project-orchestration.md#dedicated-sessions-and-independent-continuation).
|
|
116
|
+
|
|
110
117
|
See [Coordination](docs/concepts/coordination.md) for the mental model and
|
|
111
118
|
[Project orchestration](docs/guides/project-orchestration.md) for the Manager
|
|
112
119
|
workflow.
|
package/SKILL.md
CHANGED
|
@@ -31,24 +31,26 @@ Use these high-salience rules for the model-facing agent boundary:
|
|
|
31
31
|
execute or assign overlapping work while it is delegated.
|
|
32
32
|
- For any coordination tool that accepts `files`, pass every user-supplied or
|
|
33
33
|
already-available artifact relevant to what the recipient must do or decide
|
|
34
|
-
that is not already registered as
|
|
34
|
+
that is not already registered as retained evidence for the recipient's
|
|
35
35
|
verified assignment. Do not assume another session inherits arbitrary
|
|
36
36
|
conversation or attachments. Preserve exact supplied result refs when
|
|
37
37
|
forwarding them and omit unrelated evidence. `files` carries evidence, not
|
|
38
38
|
runtime capability.
|
|
39
|
-
- For a verified managed project assignment,
|
|
39
|
+
- For a verified managed project assignment, retained evidence is supplied to
|
|
40
40
|
new descendant assignments automatically. Use `files` for relevant evidence
|
|
41
|
-
not registered as
|
|
42
|
-
evidence that must remain
|
|
41
|
+
not registered as retained or specific to one recipient. When forwarding
|
|
42
|
+
evidence that must remain available downstream, set `retain: true` on
|
|
43
43
|
`message_staff` (Manager, retaining its message text and files for the
|
|
44
44
|
target project assignment) or `delegate_agent` (retaining its files, not its
|
|
45
45
|
task text, eligible managed Agents only, for their own descendants).
|
|
46
|
+
Retained evidence is available to eligible descendants; inspect relevant
|
|
47
|
+
references as needed, not every entry.
|
|
46
48
|
Project-wide requirements are controlled only by the Manager. Leads forward
|
|
47
49
|
continuing findings through `message_supervisor.files` for Manager evaluation;
|
|
48
50
|
ordinary delegation files remain recipient-specific. On supported operations,
|
|
49
51
|
omitted or false `retain` keeps files one-time. Never assume retention if it fails.
|
|
50
52
|
Ordinary Leads without a verified project assignment have no automatic
|
|
51
|
-
|
|
53
|
+
retained-evidence scope.
|
|
52
54
|
- When agent work is unresolved, handle required agent control, then continue
|
|
53
55
|
only necessary work you still own or end the turn without concluding; agent
|
|
54
56
|
results or attention will resume the session automatically. Do not check
|
|
@@ -176,12 +178,15 @@ conflict resolution, and final technical decisions within your assigned
|
|
|
176
178
|
objective. Decompose only as far as useful. Reuse adequate existing evidence
|
|
177
179
|
instead of duplicating work. The active Lead execution profile determines the
|
|
178
180
|
balance between direct and delegated work. Ordinary Leads use `flexible-lead`
|
|
179
|
-
or `orchestrator-lead` according to their persisted `
|
|
180
|
-
`
|
|
181
|
+
or `orchestrator-lead` according to their persisted `flexible` or
|
|
182
|
+
`orchestrate` execution mode. Manager-assigned Leads use `managed-lead`; the
|
|
181
183
|
exact current `ProjectAssignment`, not the profile, establishes Manager
|
|
182
|
-
authority.
|
|
183
|
-
|
|
184
|
-
|
|
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.
|
|
185
190
|
|
|
186
191
|
<!-- pi-herdsman-runtime-lead:end -->
|
|
187
192
|
|
|
@@ -216,7 +221,7 @@ authority, and acceptance criteria.
|
|
|
216
221
|
|
|
217
222
|
Treat supplied files as message evidence. Complete strict UTF-8 text may be
|
|
218
223
|
embedded; other files are canonical local references and are not copied or
|
|
219
|
-
snapshotted. The exception is
|
|
224
|
+
snapshotted. The exception is retained evidence in a verified project
|
|
220
225
|
assignment: supported text up to 1 MiB is preserved and automatically
|
|
221
226
|
propagated to new descendants; unsupported or oversized evidence cannot be
|
|
222
227
|
registered. Reference delivery to a preserved snapshot remains possible when
|
|
@@ -405,7 +410,7 @@ Chief uses `list_staff`, `inspect_staff`, `read_staff_transcript`, and
|
|
|
405
410
|
`message_staff`. Manager has those same direct-report tools, peer tools, and
|
|
406
411
|
`delegate_project`, `resume_project`, and `stop_lead`.
|
|
407
412
|
For administrative removal of a project-owned evidence requirement, use the
|
|
408
|
-
Manager project-assignment action menu: **
|
|
413
|
+
Manager project-assignment action menu: **Retained evidence**, inspect the
|
|
409
414
|
entry, then **Remove** and confirm. Inherited requirements are protected; this
|
|
410
415
|
does not delete snapshots or change evidence already accepted by Agents.
|
|
411
416
|
`inspect_staff` provides bounded live terminal/process evidence;
|
|
@@ -469,10 +474,8 @@ Pi Herdsman uses one durable vocabulary:
|
|
|
469
474
|
stopped Lead does not retire an assignment while its checkout exists.
|
|
470
475
|
Successful Herdr worktree removal or verified checkout absence retires the
|
|
471
476
|
matching assignment and pending project messages while preserving the Git
|
|
472
|
-
branch and Pi session.
|
|
473
|
-
|
|
474
|
-
pending project messages while preserving the session, worktree, branch, and
|
|
475
|
-
owned Agents. Never infer
|
|
477
|
+
branch and Pi session. Managed identity and exact Agent ownership survive
|
|
478
|
+
retirement; retirement does not imply completion or stop a live Pi process. Never infer
|
|
476
479
|
ownership from worktree membership or start an overlapping writer beside
|
|
477
480
|
another Lead;
|
|
478
481
|
- `/manager leave` preserves project work; a later Manager can resume the same
|
|
@@ -483,12 +486,11 @@ Pi Herdsman uses one durable vocabulary:
|
|
|
483
486
|
from supervising a Lead and never gives them control over the Lead's tree. A
|
|
484
487
|
managed project Lead uses
|
|
485
488
|
`message_supervisor` for timely coordination with its Manager; routine
|
|
486
|
-
information that can wait should go in its automatic result. An
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
release that assignment explicitly;
|
|
489
|
+
information that can wait should go in its automatic result. An ordinary Lead
|
|
490
|
+
contacts its verified active project Manager, otherwise Chief when eligible.
|
|
491
|
+
A Managed Lead never falls back to Chief when assignment authority is missing.
|
|
492
|
+
Continuing the exact Pi session preserves its kind; `managed-lead` is launch
|
|
493
|
+
policy, not authority;
|
|
492
494
|
- an **Agent** handles one bounded assignment and may delegate only when its
|
|
493
495
|
definition allows it;
|
|
494
496
|
- the **chief** supervises direct reports through `list_staff`,
|
|
@@ -16,5 +16,9 @@ assignments only after their prerequisites resolve.
|
|
|
16
16
|
Retain decomposition, architecture, technical direction, review, integration,
|
|
17
17
|
conflict resolution, acceptance, and final technical decisions.
|
|
18
18
|
|
|
19
|
+
Resolve technical problems within your assignment using your own reasoning,
|
|
20
|
+
available tools, and Agents. Escalate decisions or blockers outside your
|
|
21
|
+
authority or capabilities; continue independently actionable work.
|
|
22
|
+
|
|
19
23
|
Surface findings that may change continuing project requirements to the
|
|
20
24
|
Manager for evaluation.
|
|
@@ -8,9 +8,11 @@ tools: []
|
|
|
8
8
|
|
|
9
9
|
Coordinate assigned project work through Leads.
|
|
10
10
|
|
|
11
|
-
Set priorities,
|
|
12
|
-
|
|
13
|
-
implementation
|
|
11
|
+
Set priorities, resolve project-level decisions and dependencies, review
|
|
12
|
+
outcomes, and request corrections through the responsible Lead.
|
|
13
|
+
Leave technical investigation, implementation, review, validation, and
|
|
14
|
+
integration to that Lead and its Agents rather than doing or delegating
|
|
15
|
+
the work yourself.
|
|
14
16
|
|
|
15
|
-
Treat routine progress as informational.
|
|
16
|
-
|
|
17
|
+
Treat routine progress as informational. Intervene when a project-level
|
|
18
|
+
decision or meaningful coordination is needed.
|