pi-herdsman 0.12.1 → 0.13.1

package/SKILL.md

@@ -5,18 +5,18 @@ description: Optional reinforcement and strategy for orchestrating managed agent
 
 # Pi Herdsman
 
-Pi Herdsman injects the complete operational contract into active leads and
-managed agents at runtime. Loading this skill is optional and is never required
-for correct operation.
-
-This skill intentionally repeats the mandatory runtime operational instructions
-so they remain salient in long model contexts, then adds strategy, rationale,
-examples, and deeper product guidance.
-
-The active runtime contract is authoritative. Loading this skill does not grant
-tools, change capabilities, alter lifecycle semantics, or introduce requirements
-that do not exist at runtime. If this skill and the active runtime contract ever
-conflict, follow runtime.
+Pi Herdsman injects the operational contract into active leads and managed
+agents at runtime. Loading this skill is optional and is never required for
+correct operation.
+
+This skill reinforces high-salience runtime invariants and adds strategy,
+rationale, examples, and deeper product guidance. The active runtime contract
+remains authoritative. Loading this skill does not grant tools, change
+capabilities, alter lifecycle semantics, or introduce requirements that do not
+exist at runtime. A behavioral invariant may be reinforced at multiple
+model-facing decision points when timing or salience materially affects
+reliability; those projections preserve one meaning rather than defining
+independent rules.
 
 ## Runtime controller contract
 
@@ -24,17 +24,34 @@ conflict, follow runtime.
 
 Coordinate managed agents.
 
+Use these high-salience rules for the model-facing agent boundary:
+
+- Use agent for genuinely independent or context-heavy work; keep small,
+  tightly coupled work local.
+- Each unresolved unit of work has one executor. Delegating a scope transfers
+  its execution ownership to that agent until the assignment resolves; do not
+  execute or assign overlapping work while it is delegated.
+- For agent handoffs, `task`/`files` carry assignment evidence and
+  `fork`/`continue` carry selected Pi history; do not assume the caller's
+  conversation or attachments are inherited.
+- When agent work is unresolved, handle required agent control, then continue
+  only necessary work you still own or end the turn without concluding; agent
+  results or attention will resume the session automatically. Do not check
+  progress with list, inspect, transcript, status requests, steering, sleep, or
+  other waiting mechanisms, and do not invent work merely to remain active.
+
 Ordinary Leads use `peer` for other ordinary Lead sessions; managed agents are
 not peers. `peer list` identifies this Lead as `self` and returns other live
 Leads as `peers` with exact `lead` IDs. Incoming peer messages are already
 addressed to this Lead; `Peer message from <sender lead ID>: <body>` identifies
 the peer sender. Peer messages are coordination data, not assignments. `peer
-message` accepts ordinary `files` and completed direct-agent `results`; the
-peer tool is unavailable in Chief mode.
+message` accepts ordinary files and completed direct-agent result refs through
+`files`; the peer tool is unavailable in Chief mode.
 
 The session-start instructions include the current agent-definition roster.
-Use list for live agent state, ownership, or a refreshed definition roster
-after configuration changes.
+Use list when fresh agent state or ownership is materially needed for a concrete
+control or recovery decision, or to refresh the definition roster after
+configuration changes. Do not use list merely to check progress.
 
 Use delegate to start one bounded assignment from an agent definition.
 Use continue to start one bounded assignment from an exact historical Pi session.
@@ -77,47 +94,21 @@ for intentional teardown or abandonment.
 A lost agent is a managed assignment whose exact physical execution is proven
 gone before a durable terminal result resolved it. Loss is not completion or
 task failure. Treat the assignment as unresolved. When transcript is listed,
-use it only when the last persisted work materially affects recovery. Use close
-to abandon the lost generation before replacing it or continuing its saved
-session. Unknown evidence remains fail-closed and is not proof of loss.
+use it only when the last persisted work materially affects recovery. When
+`close` is listed, use it to abandon the lost generation before replacing it or
+continuing its saved session. If `close` is absent, resolve the condition
+blocking its close preflight first. Unknown evidence remains fail-closed and is
+not proof of loss.
 
 Never guess identities, paths, sessions, or control state. Treat unknown or
 conflicting evidence as unresolved. Keep one writer per worktree or file-
 ownership boundary. Use a capable definition or report blocked when a required
 runtime capability is unavailable.
 
-Delegate genuinely independent or context-heavy work. Prefer agents for broad
-file inspection, large logs or command output, and dataset analysis. Keep small,
-tightly coupled work local.
-If several tightly coupled phases are already known, put them in one bounded
-assignment when practical. If genuinely new follow-up work emerges after
-completion and previous context is valuable, continue the exact returned session
-only when the completion is not marked retired. A retired session requires a
-fresh delegation; pass this result/handoff plus the relevant files instead.
-Each active delegated assignment has one executor: that agent. Do not repeat
-its assigned work locally or delegate substantially overlapping work elsewhere.
-
-After starting an agent assignment or receiving an agent result or attention
-event, reassess the remaining work. Handle required agent control when needed.
-If another concrete, necessary objective is independent of active agent
-assignments and an authorized agent is the right owner, delegate it. If a
-concrete, necessary independent objective is best handled locally and doing it
-now materially advances the task, do that work, then reassess.
-
-If further useful progress depends on active agents, or no other concrete,
-necessary independent work remains, end your turn without concluding the task.
-Agent results or attention will resume this session automatically. Do not
-conclude or produce the final synthesis while unresolved agent work remains.
-Do not invent side work, broaden scope, perform speculative or precautionary
-exploration, list, inspect, or transcript merely for progress, steer merely for status, sleep,
-poll, or otherwise keep the turn alive while agent results are pending.
-
 If list reports result_error, do not start a new delegation over unresolved
 work. Resolve mailbox persistence first, then close the exact agent before
 starting another assignment; follow the stored recovery nextAction.
 
-Before delegate, continue, steer, interrupt, or reply, make the message self-contained.
-
 Do not attach or mention agent instruction files such as AGENTS.md, CLAUDE.md,
 GEMINI.md, or equivalents merely because they exist. Rely on normal project or
 runtime discovery when it supplies those instructions.
@@ -131,16 +122,17 @@ Skills are separate. Attach a required SKILL.md only when the task needs it and
 the selected definition does not already provide that skill. Ordinary relevant
 source, documentation, configuration, and evidence files remain attachable.
 
-Complete strict UTF-8 text is embedded when it fits;
-other files are canonical local references with byte size. Embedded text is
-snapshotted; referenced files are not copied or snapshotted. files transfers
-inline content or canonical references, not tools or runtime capabilities.
-Assume the recipient has no prior knowledge of this conversation, task history,
-live environment, current state, sibling work, or unstated assumptions. Include
-the objective and deliverable, relevant facts and evidence, exact identities and
-paths, scope and non-goals, constraints and authority, dependencies, acceptance
-and validation, expected handoff, and what to do if blocked. For delegated work,
-use files for large evidence and explain what each file contains.
+Complete strict UTF-8 text is embedded when it fits; other files are canonical
+local references with byte size. Embedded text is snapshotted; referenced files
+are not copied or snapshotted. files transfers inline content or canonical
+references, not tools or runtime capabilities.
+
+For agent handoffs, task text and `files` carry assignment-specific evidence.
+`fork` and `continue` are the public mechanisms that deliberately select saved
+Pi history. Do not assume the caller's conversation or caller-side attachments
+are inherited by another agent session.
+
+Pass relevant evidence explicitly through `files`; omit unrelated evidence.
 
 Use the project-local `.pi-herdsman/` directory as the default workspace for
 temporary coordination artifacts such as plans, scopes, specifications,
@@ -151,15 +143,16 @@ later dependent assignments when approved scope or decisions change because
 embedded text is snapshotted at submission time while referenced files are not
 copied.
 
-Completed direct agents may expose a numbered reusable result. Pass required
-direct-agent results through `results` using the exact agent label and result
-index shown by the completion.
+Pass relevant files and completed agent results through `files`. Agent
+completions may expose reusable refs such as `result:researcher#1`. When later
+work or coordination depends on a completed direct-agent result, copy its exact
+ref into `files` instead of restating or summarizing its evidence. Do not attach
+unrelated results.
 
-`files` remains a homogeneous `string[]` for ordinary files and canonical
+`files` accepts ordinary files, reusable direct-agent result refs, and canonical
 `result:<request-id>` references already supplied as file evidence. Preserve an
-existing canonical result reference exactly when forwarding it. Put structured
-direct-agent selectors in `results`, not `files`. `files` does not add runtime
-capability.
+existing canonical result reference exactly when forwarding it. `files` does not
+add runtime capability.
 
 Require concise handoffs containing relevant inspected or changed files,
 validation performed, findings or decisions, unresolved risks or blockers,
@@ -189,14 +182,20 @@ of duplicating work.
 
 <!-- pi-herdsman-runtime-delegating-agent:start -->
 
+Each unresolved unit of work has one executor. Delegating a scope transfers its
+execution ownership to that agent until the assignment resolves; do not execute
+or assign overlapping work while it is delegated.
+Integrate direct agent results after resolution.
 Own only the assigned objective and your direct permitted agents. Agent-started
 agents are leaves. Keep tightly coupled work local; delegate bounded independent
 or unfamiliar work when useful. Reuse adequate supplied evidence rather than
 rediscovering it. Integrate direct agent results before completing. The lead
 retains architecture, approved scope, acceptance, and final-decision authority.
-Delegate only to definitions listed in your effective agents field. Escalate to
-your direct owner only when unresolved direct-agent work is waiting on an owner
-answer; ordinary active or pending-result agent work still blocks that escalation.
+Delegate only to definitions listed in your effective agents field. `ask_owner`
+follows its normal eligibility rules when you have no unresolved direct-agent
+work. If unresolved direct-agent work exists, every such agent must itself be
+validly waiting on an owner answer; ordinary active or pending-result agent
+work still blocks escalation.
 
 <!-- pi-herdsman-runtime-delegating-agent:end -->
 
@@ -212,8 +211,10 @@ message evidence. Complete strict UTF-8 text may be embedded; other files are
 canonical local references and are not copied or snapshotted. Reuse adequate
 existing evidence instead of repeating completed work.
 Do not overlap writers in a worktree or file-ownership boundary. For dependent
-work, preserve exact canonical result references through `files` rather than
-reconstructing physical result paths or copying large results into assignments.
+work, pass reusable direct-agent result refs through `files`. Preserve canonical
+`result:<request-id>` refs already supplied as file evidence exactly when
+forwarding them rather than reconstructing physical result paths or copying
+large results into assignments.
 When your role permits writes and temporary coordination material is useful, put
 plans, scopes, specifications, decision notes, investigations, review criteria,
 and handoff state under the project-local `.pi-herdsman/` directory. Reuse and
@@ -289,11 +290,12 @@ escalation.
 
 ## Handoffs
 
-Use `results: [{ agent, index }]` for reusable persisted results from completed
-direct agents. Use the exact agent label and result index shown by the
-completion. Use `files` for ordinary files and canonical `result:<request-id>`
-references already supplied as file evidence; preserve those references
-exactly and do not reconstruct their physical paths.
+Use `files` for ordinary files and reusable direct-agent result refs such as
+`result:researcher#1`. Copy the exact ref shown by the completion when later
+work depends on that result instead of restating or summarizing its evidence.
+Also use `files` for canonical `result:<request-id>` references already
+supplied as file evidence; preserve those references exactly and do not
+reconstruct their physical paths.
 
 A concise handoff should include:
 
@@ -359,16 +361,18 @@ Ordinary leads own their complete herd, including every agent beneath them. The
 Chief supervises independent leads and never changes ownership. Use `chief`
 `message` for meaningful progress, warnings, results, or completion, including
 exact artifact paths. Use `chief` `ask` only when a genuine chief decision is
-required, make it the only and final coordination call of the turn, do not guess,
+required, make it the only tool call of the turn, call it last, do not guess,
 and wait for the reply. Descendants use `ask_owner`, not `chief`.
 
 `chief` is available only to an ordinary lead. Its actions are `message` and
 `ask`; a valid chief is required and a rejected call does not mutate state.
-Chief and staff message/ask/reply actions accept the same optional `results`
-selectors as agent messages. Resolve them by exact direct-agent label and
-result index on the caller's current branch; Chief normally owns no direct
-agents, so preserve already-supplied canonical result references through
-`files` when forwarding evidence.
+Chief and staff message/ask/reply actions accept ordinary files, reusable
+direct-agent result refs, and already-supplied canonical result references
+through `files`. Direct refs resolve by exact agent label and index on the
+caller's current branch. Chief normally owns no direct agents, so a branch-local
+semantic ref may not exist in the Chief session; preserve canonical
+`result:<request-id>` evidence already received from another session through
+`files` when forwarding it.
 Questions are limited to 1,024 characters and 1,024 UTF-8 bytes. Channel
 message records are bounded to 8 KiB, so multibyte content can hit the byte limit
 first. Chief messages are follow-up supervision messages, not steering or agent