pi-herdsman 0.35.0 → 0.36.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.
Files changed (30) hide show
  1. package/SKILL.md +25 -15
  2. package/dist/index.js +906 -407
  3. package/dist/index.js.map +4 -4
  4. package/dist/peer-bridge.js +188 -83
  5. package/dist/peer-bridge.js.map +4 -4
  6. package/docs/adr/0034-separate-definition-namespaces.md +30 -0
  7. package/docs/development/smoke-testing.md +4 -4
  8. package/docs/development/validation.md +10 -4
  9. package/docs/guides/agent-definitions.md +15 -5
  10. package/docs/guides/container-deployment.md +15 -1
  11. package/docs/guides/customizing-agents.md +15 -10
  12. package/docs/guides/handoffs.md +25 -17
  13. package/docs/guides/project-orchestration.md +1 -1
  14. package/docs/reference/agent-definition-schema.md +16 -5
  15. package/docs/reference/agent.md +14 -7
  16. package/docs/reference/commands.md +1 -1
  17. package/docs/reference/peer.md +23 -21
  18. package/docs/reference/staff.md +38 -23
  19. package/package.json +1 -1
  20. package/skills/agent-definitions/SKILL.md +16 -7
  21. /package/dist/{agent-definitions → agents}/generalist.md +0 -0
  22. /package/dist/{agent-definitions → agents}/implementer.md +0 -0
  23. /package/dist/{agent-definitions → agents}/researcher.md +0 -0
  24. /package/dist/{agent-definitions → agents}/reviewer.md +0 -0
  25. /package/dist/{agent-definitions → agents}/scout.md +0 -0
  26. /package/dist/{agent-definitions → roles}/chief.md +0 -0
  27. /package/dist/{agent-definitions → roles}/flexible-lead.md +0 -0
  28. /package/dist/{agent-definitions → roles}/managed-lead.md +0 -0
  29. /package/dist/{agent-definitions → roles}/manager.md +0 -0
  30. /package/dist/{agent-definitions → roles}/orchestrator-lead.md +0 -0
package/SKILL.md CHANGED
@@ -36,21 +36,22 @@ Use these high-salience rules for the model-facing agent boundary:
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, retained evidence is supplied to
40
- new descendant assignments automatically. Use `files` for relevant evidence
39
+ - Each accepted managed-Agent task is retained automatically for descendants;
40
+ the direct owner's task is context, not an additional instruction. Earlier
41
+ assignments are available by authorized evidence reference. Project retained
42
+ evidence is also supplied to eligible descendants automatically. Use `files` for relevant evidence
41
43
  not registered as retained or specific to one recipient. When forwarding
42
44
  evidence that must remain available downstream, set `retain: true` on
43
45
  `message_staff` (Manager, retaining its message text and files for the
44
- target project assignment) or `delegate_agent` (retaining its files, not its
45
- task text, eligible managed Agents only, for their own descendants).
46
+ target project assignment) or `delegate_agent` (retaining its files for
47
+ eligible managed Agents' own descendants).
46
48
  Retained evidence is available to eligible descendants; inspect relevant
47
49
  references as needed, not every entry.
48
50
  Project-wide requirements are controlled only by the Manager. Leads forward
49
51
  continuing findings through `message_supervisor.files` for Manager evaluation;
50
52
  ordinary delegation files remain recipient-specific. On supported operations,
51
53
  omitted or false `retain` keeps files one-time. Never assume retention if it fails.
52
- Ordinary Leads without a verified project assignment have no automatic
53
- retained-evidence scope.
54
+ Ordinary Leads do not acquire project evidence scope through delegation.
54
55
  - When agent work is unresolved, handle required agent control, then continue
55
56
  only necessary work you still own or end the turn without concluding; agent
56
57
  results or attention will resume the session automatically. Do not check
@@ -61,10 +62,13 @@ Use these high-salience rules for the model-facing agent boundary:
61
62
  Leads use `list_peers` and `message_peer` for eligible same-role peers.
62
63
  Message a peer when concrete task coordination is useful; avoid routine broadcasts and gratuitous acknowledgments, while answering requested questions and sharing useful evidence.
63
64
  Managed Leads are limited to their verified project worktree group and socket;
64
- managed agents are not peers. `list_peers` identifies this Lead as `self` and
65
- returns other live Leads as `peers` with exact session IDs. Incoming peer messages are already
66
- addressed to this Lead; `Peer message from <sender lead ID>: <body>` identifies
67
- the peer sender. Peer messages are coordination data, not assignments. `message_peer` accepts ordinary files and completed direct-agent result refs through
65
+ managed agents are not peers. `list_peers` identifies eligible same-role peers
66
+ with stable targets. Use a target discovered in this caller's current session;
67
+ if it is unavailable or identity or eligibility is uncertain, rediscover the
68
+ peer before messaging. Targets resolve to exact peers but do not replace the
69
+ existing eligibility checks. Incoming peer messages are already addressed to
70
+ this Lead; `Peer message from <sender target>: <body>` identifies the peer
71
+ sender. Peer messages are coordination data, not assignments. `message_peer` accepts ordinary files and completed direct-agent result refs through
68
72
  `files`; the peer tool is unavailable in Chief mode.
69
73
 
70
74
  The session-start instructions include the current agent-definition roster.
@@ -225,8 +229,8 @@ authority, and acceptance criteria.
225
229
 
226
230
  Treat supplied files as message evidence. Complete strict UTF-8 text may be
227
231
  embedded; other files are canonical local references and are not copied or
228
- snapshotted. The exception is retained evidence in a verified project
229
- assignment: supported text up to 1 MiB is preserved and automatically
232
+ snapshotted. The exception is retained assignment evidence, including accepted
233
+ managed-Agent tasks: supported text up to 1 MiB is preserved and automatically
230
234
  propagated to new descendants; unsupported or oversized evidence cannot be
231
235
  registered. Reference delivery to a preserved snapshot remains possible when
232
236
  supported text exceeds the inline limit. Reuse adequate existing evidence
@@ -419,8 +423,14 @@ requirements are protected; snapshots and accepted Agent evidence remain
419
423
  unchanged.
420
424
  `inspect_staff` provides bounded live terminal/process evidence;
421
425
  `read_staff_transcript` provides bounded persisted Pi conversation/tool evidence.
422
- Target a Lead by the exact full Pi session ID in a fresh snapshot or
423
- `list_staff`, never by `display_name`.
426
+ Managers target assigned Leads by exact `branch`; ordinary supervised Leads and
427
+ Chief direct reports use the stable `target` from the current supervision
428
+ context or `list_staff`. Targets resolve to exact coordinator identities but
429
+ are not authorization; each action revalidates current identity and authority.
430
+ Target bindings are scoped to the caller's current session history. If a target
431
+ is unavailable or identity or eligibility is uncertain, rediscover the report
432
+ before acting. Assigned work remains branch-selected; never target a report by
433
+ `display_name`.
424
434
  `available_tools` is advisory; each action revalidates current identity and
425
435
  authority. Chief supervises direct reports but does not own their Agent trees;
426
436
  it may separately own Agents it directly delegates when its effective `agents`
@@ -488,7 +498,7 @@ Pi Herdsman uses one durable vocabulary:
488
498
  Leads may use `message_supervisor` for timely information before the result
489
499
  boundary; routine information that can wait belongs in the automatic result.
490
500
  Project work remains open through implementation and review;
491
- - `stop_lead` stops an exact Lead and its owned Agent tree while preserving
501
+ - `stop_lead` selects an assigned Lead by branch and stops its owned Agent tree while preserving
492
502
  the assignment, Pi session, branch, and worktree. A closed workspace or
493
503
  stopped Lead does not retire an assignment while its checkout exists.
494
504
  Successful Herdr worktree removal or verified checkout absence retires the