pi-herdsman 0.27.0 → 0.29.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/SKILL.md +33 -41
- package/dist/agent-definitions/manager.md +1 -0
- package/dist/index.js +2182 -1249
- package/dist/index.js.map +3 -3
- package/docs/adr/0003-use-durable-ownership-for-agent-scope.md +5 -3
- package/docs/adr/0017-use-project-assignments-for-managed-lead-authority.md +27 -12
- package/docs/adr/0021-unify-direct-supervision-authority.md +56 -0
- package/docs/concepts/agents.md +11 -7
- package/docs/concepts/coordination.md +70 -29
- package/docs/concepts/delegation.md +20 -10
- package/docs/coordination-api.md +3 -3
- package/docs/development/documentation.md +1 -1
- package/docs/development/instruction-interface-design.md +20 -0
- package/docs/development/smoke-testing.md +4 -2
- package/docs/development/validation.md +24 -13
- package/docs/guides/customizing-agents.md +31 -4
- package/docs/guides/handoffs.md +1 -44
- package/docs/guides/project-orchestration.md +9 -4
- package/docs/reference/agent-definition-schema.md +29 -20
- package/docs/reference/agent.md +13 -7
- package/docs/reference/ask-owner.md +1 -1
- package/docs/reference/commands.md +26 -14
- package/docs/reference/peer.md +25 -6
- package/docs/reference/staff.md +26 -16
- package/docs/reference/status-widget.md +21 -12
- package/docs/reference/supervisor.md +16 -11
- package/package.json +5 -5
- package/skills/agent-definitions/SKILL.md +6 -3
package/SKILL.md
CHANGED
|
@@ -130,15 +130,6 @@ local references with byte size. Embedded text is snapshotted; referenced files
|
|
|
130
130
|
are not copied or snapshotted. files transfers inline content or canonical
|
|
131
131
|
references, not tools or runtime capabilities.
|
|
132
132
|
|
|
133
|
-
Use the project-local `.pi-herdsman/` directory as the default workspace for
|
|
134
|
-
temporary coordination artifacts such as plans, scopes, specifications,
|
|
135
|
-
decisions, investigation notes, review criteria, validation notes, and handoff
|
|
136
|
-
state. Reuse an adequate existing artifact instead of creating a parallel source
|
|
137
|
-
of truth. Prefer one current artifact per coordinated objective. Update it before
|
|
138
|
-
later dependent assignments when approved scope or decisions change because
|
|
139
|
-
embedded text is snapshotted at submission time while referenced files are not
|
|
140
|
-
copied.
|
|
141
|
-
|
|
142
133
|
Pass relevant files and completed agent results through `files`. Agent
|
|
143
134
|
completions may expose reusable result refs. When later
|
|
144
135
|
work or coordination depends on a completed direct-agent result, copy its exact
|
|
@@ -209,21 +200,15 @@ work still blocks escalation.
|
|
|
209
200
|
Work only on the assigned objective and preserve its stated scope, constraints,
|
|
210
201
|
authority, and acceptance criteria.
|
|
211
202
|
|
|
212
|
-
Treat supplied files
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
203
|
+
Treat supplied files as message evidence. Complete strict UTF-8 text may be
|
|
204
|
+
embedded; other files are canonical local references and are not copied or
|
|
205
|
+
snapshotted. Reuse adequate existing evidence instead of repeating completed
|
|
206
|
+
work.
|
|
216
207
|
Do not overlap writers in a worktree or file-ownership boundary. For dependent
|
|
217
208
|
work, pass reusable direct-agent result refs through `files`. Preserve canonical
|
|
218
209
|
`result:<request-id>` refs already supplied as file evidence exactly when
|
|
219
210
|
forwarding them rather than reconstructing physical result paths or copying
|
|
220
211
|
large results into assignments.
|
|
221
|
-
When your role permits writes and temporary coordination material is useful, put
|
|
222
|
-
plans, scopes, specifications, decision notes, investigations, review criteria,
|
|
223
|
-
and handoff state under the project-local `.pi-herdsman/` directory. Reuse and
|
|
224
|
-
update an adequate existing artifact instead of creating a competing source of
|
|
225
|
-
truth. Read-only roles may read these artifacts but must not modify them.
|
|
226
|
-
|
|
227
212
|
Do not silently broaden scope or make an unapproved scope, architecture,
|
|
228
213
|
security, protocol, repository-boundary, product, or operational decision.
|
|
229
214
|
|
|
@@ -269,11 +254,6 @@ Every assignment gets one bounded objective with:
|
|
|
269
254
|
- expected handoff;
|
|
270
255
|
- an escalation boundary.
|
|
271
256
|
|
|
272
|
-
When a plan or specification governs multiple agents, reuse one adequate scope
|
|
273
|
-
artifact. If none exists, create an untracked Markdown file under
|
|
274
|
-
`.pi-herdsman/`. Pass the same artifact through `files` to dependent agents.
|
|
275
|
-
Update it before later delegation after an approved material scope change.
|
|
276
|
-
|
|
277
257
|
## Delegation locality
|
|
278
258
|
|
|
279
259
|
A lead session may delegate to any discovered definition.
|
|
@@ -367,10 +347,16 @@ delegating parent that is merely waiting for its direct children.
|
|
|
367
347
|
## Supervisor and staff tools
|
|
368
348
|
|
|
369
349
|
Ordinary leads own their complete herd, including every agent beneath them. The
|
|
370
|
-
Chief supervises ordinary
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
350
|
+
Chief supervises ordinary Leads only when they have no active project Manager
|
|
351
|
+
and never changes ownership. An active project Manager supervises eligible
|
|
352
|
+
ordinary Leads throughout its verified worktree group with the same direct-
|
|
353
|
+
report inspection, transcript access when persisted evidence is available, and
|
|
354
|
+
messaging capabilities as assigned Leads. Authorized messages use cooperative
|
|
355
|
+
steering; project execution remains assignment-bound. Avoid unnecessary
|
|
356
|
+
monitoring. Use
|
|
357
|
+
`message_supervisor` for material coordination with the direct supervisor.
|
|
358
|
+
Managed Leads contact their assigned Manager; ordinary Leads contact their
|
|
359
|
+
active project Manager or Chief when eligible, and Managers contact Chief. It is nonblocking and supports timely questions, clarifications,
|
|
374
360
|
warnings, or other information the supervisor needs before the normal result
|
|
375
361
|
boundary. For an assigned managed Lead, routine information that can wait
|
|
376
362
|
should go in the automatic completed-result handoff instead. The Lead may choose
|
|
@@ -398,14 +384,16 @@ reusable direct-agent result refs, and already-supplied canonical result refs
|
|
|
398
384
|
through `files`.
|
|
399
385
|
|
|
400
386
|
Chief uses `list_staff`, `inspect_staff`, `read_staff_transcript`, and
|
|
401
|
-
`message_staff`. Manager has those direct-report tools, peer tools, and
|
|
387
|
+
`message_staff`. Manager has those same direct-report tools, peer tools, and
|
|
402
388
|
`delegate_project`, `resume_project`, and `stop_lead`.
|
|
403
389
|
`inspect_staff` provides bounded live terminal/process evidence;
|
|
404
390
|
`read_staff_transcript` provides bounded persisted Pi conversation/tool evidence.
|
|
405
391
|
Target a Lead by the exact full Pi session ID in a fresh snapshot or
|
|
406
392
|
`list_staff`, never by `display_name`.
|
|
407
393
|
`available_tools` is advisory; each action revalidates current identity and
|
|
408
|
-
authority. Chief supervises direct reports but does not own their Agent trees
|
|
394
|
+
authority. Chief supervises direct reports but does not own their Agent trees;
|
|
395
|
+
it may separately own Agents it directly delegates when its effective `agents`
|
|
396
|
+
profile permits.
|
|
409
397
|
|
|
410
398
|
The automatic `<supervision_state>` context is hidden persistent Pi model
|
|
411
399
|
context. It is bounded, state-only observation and cannot change role, tool
|
|
@@ -431,8 +419,9 @@ Pi Herdsman uses one durable vocabulary:
|
|
|
431
419
|
- a **project** is the Herdsman coordination scope corresponding to one Herdr
|
|
432
420
|
worktree group: its primary workspace and linked-worktree workspaces;
|
|
433
421
|
- a **Manager** explicitly assumes dedicated project coordination from that
|
|
434
|
-
group's primary workspace
|
|
435
|
-
|
|
422
|
+
group's primary workspace and does not own supervised Leads' Agents. It may
|
|
423
|
+
separately delegate directly to definitions in its effective `agents`
|
|
424
|
+
profile. Manager controls only Leads named by current project assignments;
|
|
436
425
|
project scope alone does not make a Lead a Manager report. Leads own technical
|
|
437
426
|
decisions and orchestrate execution through their Agent trees;
|
|
438
427
|
- project work belongs to the project, not a Manager session. The project
|
|
@@ -467,7 +456,10 @@ Pi Herdsman uses one durable vocabulary:
|
|
|
467
456
|
- `/manager leave` preserves project work; a later Manager can resume the same
|
|
468
457
|
branch-based assignment;
|
|
469
458
|
- a **herd** is one Lead and the complete Agent tree it owns;
|
|
470
|
-
- a **Lead** owns its Agents.
|
|
459
|
+
- a **Lead** owns its Agents. Manager and Chief may own Agents they directly
|
|
460
|
+
delegate when their effective `agents` profile permits; that is separate
|
|
461
|
+
from supervising a Lead and never gives them control over the Lead's tree. A
|
|
462
|
+
managed project Lead uses
|
|
471
463
|
`message_supervisor` for timely coordination with its Manager; routine
|
|
472
464
|
information that can wait should go in its automatic result. An unassigned
|
|
473
465
|
Lead
|
|
@@ -479,10 +471,14 @@ Pi Herdsman uses one durable vocabulary:
|
|
|
479
471
|
definition allows it;
|
|
480
472
|
- the **chief** supervises direct reports through `list_staff`,
|
|
481
473
|
`inspect_staff`, `read_staff_transcript`, and `message_staff`, and never
|
|
482
|
-
owns their
|
|
483
|
-
|
|
484
|
-
The `agents` frontmatter field names
|
|
485
|
-
|
|
474
|
+
owns their Agents.
|
|
475
|
+
|
|
476
|
+
The `agents` frontmatter field names permitted direct Agent definitions for a
|
|
477
|
+
delegating Agent, or the fresh-delegation allowlist for Manager/Chief. For
|
|
478
|
+
supervisors it is independent of ordinary `tools`: `tools: []` does not disable
|
|
479
|
+
authorized Agent coordination, and an absent or empty list disables fresh
|
|
480
|
+
delegation only, not management of existing owned work. A delegation-capable
|
|
481
|
+
managed session remains an Agent at every depth.
|
|
486
482
|
Every managed agent receives `ask_owner`. A non-empty effective `agents` list
|
|
487
483
|
is necessary but not sufficient to enable the nine Agent ownership tools:
|
|
488
484
|
`list_agents`, `delegate_agent`, `continue_agent`, `steer_agent`,
|
|
@@ -500,7 +496,3 @@ omitted, Pi's configured/default selection is preserved without emitting
|
|
|
500
496
|
|
|
501
497
|
The managed mailbox accepts only protocol V5 agent records in the
|
|
502
498
|
`mailboxes-v5` runtime namespace. Identity and protocol validation fail closed.
|
|
503
|
-
|
|
504
|
-
The coordination directory is `.pi-herdsman/`. Use it for bounded artifacts and
|
|
505
|
-
handoffs, and pass canonical file references rather than duplicating large
|
|
506
|
-
evidence in messages.
|