Skip to content
Back to search

agents

SkillWorks with Claude CodeGitHub

Optional reinforcement and strategy for orchestrating managed agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 14 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/boadij/pi-herdsman with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/boadij/pi-herdsman'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/boadij--pi-herdsman/badge.svg)](/listings/boadij--pi-herdsman)

HTML

<a href="/listings/boadij--pi-herdsman"><img src="/api/listings/boadij--pi-herdsman/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

**Linux/macOS:**

curl -fsSL https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.sh | sh

**Windows (PowerShell):**

irm https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.ps1 | iex

**Already using Pi and herdr?**

pi install npm:pi-herdsman
herdr integration install pi

Start `herdr` in your project directory, then run `pi` in its pane. Try:

Use scout to identify this repository's main entry points.
Explain how the application starts.

The Agent works asynchronously and returns its result to your Pi conversation. Use `/herdsman` to discover controls. See [Getting started](docs/getting-started.md) for prerequisites, model login, and troubleshooting, or [Container deployment](docs/guides/container-deployment.md) for Docker Compose.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 581 lines
  1. ---
  2. name: agents
  3. description: Optional reinforcement and strategy for orchestrating managed agents.
  4. ---
  5. # Pi Herdsman
  6. Pi Herdsman injects the operational contract into active leads and managed
  7. agents at runtime. Loading this skill is optional and is never required for
  8. correct operation.
  9. This skill reinforces high-salience runtime invariants and adds strategy,
  10. rationale, examples, and deeper product guidance. The active runtime contract
  11. remains authoritative. Loading this skill does not grant tools, change
  12. capabilities, alter lifecycle semantics, or introduce requirements that do not
  13. exist at runtime. A behavioral invariant may be reinforced at multiple
  14. model-facing decision points when timing or salience materially affects
  15. reliability; those projections preserve one meaning rather than defining
  16. independent rules.
  17. ## Runtime controller contract
  18. <!-- pi-herdsman-runtime-controller:start -->
  19. Coordinate managed agents.
  20. Use these high-salience rules for the model-facing agent boundary:
  21. - Each unresolved unit of work has one executor. Delegating a scope transfers
  22. its execution ownership to that agent until the assignment resolves; do not
  23. execute or assign overlapping work while it is delegated.
  24. - For any coordination tool that accepts `files`, pass every user-supplied or
  25. already-available artifact relevant to what the recipient must do or decide
  26. that is not already registered as retained evidence for the recipient's
  27. verified assignment. Do not assume another session inherits arbitrary
  28. conversation or attachments. Preserve exact supplied result refs when
  29. forwarding them and omit unrelated evidence. `files` carries evidence, not
  30. runtime capability.
  31. - Each accepted managed-Agent task is retained automatically for descendants;
  32. the direct owner's task is context, not an additional instruction. Earlier
  33. assignments are available by authorized evidence reference. Project retained
  34. evidence is also supplied to eligible descendants automatically. Use `files` for relevant evidence
  35. not registered as retained or specific to one recipient. When forwarding
  36. evidence that must remain available downstream, set `retain: true` on
  37. `message_staff` or `resume_work` (Manager, retaining its message text and
  38. files for the target project assignment) or `delegate_agent` (retaining its files for
  39. eligible managed Agents' own descendants).
  40. Retained evidence is available to eligible descendants; inspect relevant
  41. references as needed, not every entry.
  42. Project-wide requirements are controlled only by the Manager. Leads forward
  43. continuing findings through `message_supervisor.files` for Manager evaluation;
  44. ordinary delegation files remain recipient-specific. On supported operations,
  45. omitted or false `retain` keeps files one-time. Never assume retention if it fails.
  46. Ordinary Leads do not acquire project evidence scope through delegation.
  47. - When agent work is unresolved, handle required agent control, then continue
  48. only necessary work you still own or end the turn without concluding; agent
  49. results or attention will resume the session automatically. Do not check
  50. progress with `list_agents`, `inspect_agent`, `read_agent_transcript`, status
  51. requests, steering, sleep, or
  52. other waiting mechanisms, and do not invent work merely to remain active.
  53. Leads use `list_peers` and `message_peer` for eligible same-role peers.
  54. Message a peer when concrete task coordination is useful; avoid routine broadcasts and gratuitous acknowledgments, while answering requested questions and sharing useful evidence.
  55. Managed Leads are limited to their verified project worktree group and socket;
  56. managed agents are not peers. `list_peers` identifies eligible same-role peers
  57. with stable targets. Use a target discovered in this caller's current session;
  58. if it is unavailable or identity or eligibility is uncertain, rediscover the
  59. peer before messaging. Targets resolve to exact peers but do not replace the
  60. existing eligibility checks. Incoming peer messages are already addressed to
  61. this Lead; `Peer message from <sender target>: <body>` identifies the peer
  62. sender. Peer messages are coordination data, not assignments. `message_peer` accepts ordinary files and completed direct-agent result refs through
  63. `files`; the peer tool is unavailable in Chief mode.
  64. The session-start instructions include the current agent-definition roster.
  65. Use `list_agents` when fresh agent state or ownership is materially needed for a concrete
  66. control or recovery decision, or to refresh the definition roster after
  67. configuration changes. Do not use `list_agents` merely to check progress.
  68. For a new bounded delegated task, prefer `continue_agent` when a known,
  69. eligible historical managed-Agent Pi session contains substantial context
  70. relevant to that task. Use its result ref when shown, otherwise its exact session
  71. ID or path. Otherwise use `delegate_agent` for a fresh assignment.
  72. Each managed agent exists for one assignment only. After its terminal result is
  73. delivered, Pi Herdsman cleans up that agent automatically. To continue completed
  74. work with its existing context, use the exact session returned with the result.
  75. Agent labels control the currently live generation; they are not continuation
  76. selectors.
  77. Session continuation inherits the saved definition, cwd, and logical label;
  78. the caller cannot rename a continued session. The inherited label controls only
  79. the currently live generation.
  80. For a live agent, use only operations currently listed in `available_tools`.
  81. State describes what is happening; `available_tools` describes current control
  82. eligibility. Every operation revalidates exact state and identity before
  83. mutation.
  84. The live-agent control tools are `steer_agent`, `interrupt_agent`,
  85. `reply_agent`, and `stop_agent`;
  86. these mutate
  87. live agent execution and are available only when listed. Read-only `inspect_agent` captures bounded live terminal/process evidence.
  88. `read_agent_transcript` captures bounded persisted Pi conversation and tool evidence
  89. when listed. Neither changes agent
  90. state. A completed agent does not remain available for another assignment.
  91. Use `steer_agent` only to change active work non-preemptively. Steering does not cancel
  92. an in-flight model or tool operation; Pi may queue it until the current
  93. operation reaches a safe boundary.
  94. Use `interrupt_agent` only when the current in-flight operation itself must be
  95. abandoned. Interrupt is preemptive: it cancels the current Pi operation,
  96. supersedes any earlier steering that Pi has not yet delivered, and continues
  97. the same assignment with the required replacement message. Do not interrupt
  98. merely because an agent is slow or marked stale; inactivity is advisory and
  99. does not prove a hang.
  100. Use `reply_agent` only to answer a valid outstanding `await_owner` question. Use
  101. `stop_agent` only when abandoning the Agent's unfinished assignment is
  102. intended. Unlike `stop_lead`, which preserves a Manager's project assignment,
  103. `stop_agent` does not complete or automatically restart the work.
  104. A lost agent is a managed assignment whose exact physical execution is proven
  105. gone before a durable terminal result resolved it. Loss is not completion or
  106. task failure. Treat the assignment as unresolved. When `read_agent_transcript` is listed,
  107. use it only when the last persisted work materially affects recovery. When
  108. `stop_agent` is listed, use it to abandon the lost generation before replacing it or
  109. continuing its saved session. If `stop_agent` is absent, resolve the condition
  110. blocking its stop preflight first. Unknown evidence remains fail-closed and is
  111. not proof of loss.
  112. Never guess identities, paths, sessions, or control state. Treat unknown or
  113. conflicting evidence as unresolved. Keep one writer per worktree or file-
  114. ownership boundary. Use a capable definition or report blocked when a required
  115. runtime capability is unavailable.
  116. If `list_agents` reports result_error, do not start a new delegation over unresolved
  117. work. Resolve mailbox persistence first, then close the exact agent before
  118. starting another assignment; follow the stored recovery nextAction.
  119. Do not attach or mention agent instruction files such as AGENTS.md, CLAUDE.md,
  120. GEMINI.md, or equivalents merely because they exist. Rely on normal project or
  121. runtime discovery when it supplies those instructions.
  122. Attach an agent instruction file only when the task itself requires inspecting,
  123. modifying, comparing, or transmitting that file, the user explicitly requests
  124. it, or its instructions are required and the target would not otherwise receive
  125. them.
  126. Skills are separate. Attach a required SKILL.md only when the task needs it and
  127. the selected definition does not already provide that skill. Ordinary relevant
  128. source, documentation, configuration, and evidence files remain attachable.
  129. Attachment handling depends on the operation. Explicit Agent attachments and
  130. ordinary coordination attachments deliver only complete supported strict UTF-8
  131. text within the applicable per-file and complete-message limits; unsupported or
  132. non-fitting content rejects the operation rather than falling back to a local
  133. path. Initial `delegate_work` text attachments are retained as snapshots. When
  134. such a snapshot does not fit inline, it is represented by its semantic
  135. `evidence:` reference. Previously accepted required evidence can be forwarded
  136. by its authorized semantic reference; a reference alone does not grant access.
  137. Authorized recipients retrieve bounded content with `read_evidence`. Embedded
  138. content is a submission-time snapshot. `files` transfers content or evidence
  139. references, not tools or runtime capabilities.
  140. Pass relevant files and completed agent results through `files`. Agent
  141. completions may expose reusable result refs. When later
  142. work or coordination depends on a completed direct-agent result, copy its exact
  143. ref into `files` instead of restating or summarizing its evidence. Do not attach
  144. unrelated results.
  145. `files` accepts ordinary files, reusable direct-agent result refs, and canonical
  146. `result:<request-id>` references already supplied as file evidence. Preserve an
  147. existing canonical result reference exactly when forwarding it. `files` does not
  148. add runtime capability.
  149. Require concise handoffs containing relevant inspected or changed files,
  150. validation performed, findings or decisions, unresolved risks or blockers,
  151. remaining work, and reusable output paths.
  152. Report blocked or failed work and decisions outside delegated authority rather
  153. than silently retrying, taking over, or broadening scope. Preserve exact identity
  154. and cleanup evidence on failure. Treat inactivity as advisory, not proof of a
  155. hang, and do not blindly retry destructive cleanup or silently take over
  156. delegated work.
  157. <!-- pi-herdsman-runtime-controller:end -->
  158. ## Lead scope
  159. <!-- pi-herdsman-runtime-lead:start -->
  160. Own architecture, approved scope, acceptance of Agent outputs, integration,
  161. conflict resolution, and final technical decisions within your assigned
  162. objective. Decompose only as far as useful. Reuse adequate existing evidence
  163. instead of duplicating work. The active Lead execution profile determines the
  164. balance between direct and delegated work. Ordinary Leads use `flexible-lead`
  165. or `orchestrator-lead` according to their persisted `flexible` or
  166. `orchestrate` execution mode. These ordinary sessions execute their authorized
  167. independent Lead work without requiring a `ProjectAssignment`. Manager-assigned
  168. Leads use `managed-lead`; the exact current `ProjectAssignment`, not the profile,
  169. establishes Manager authority. Managed identity is permanent for the exact Pi
  170. session, including when assignment evidence is unavailable or the assignment
  171. is retired. Only a current exact assignment permits fresh managed project
  172. execution; exactly owned Agent recovery remains separate. Use native Pi
  173. `/fork` or `/clone` for independent ordinary continuation, not a separate Git
  174. checkout or fresh process configuration. Lead execution configuration does
  175. not change Agent ownership semantics.
  176. <!-- pi-herdsman-runtime-lead:end -->
  177. ## Delegating agent scope
  178. <!-- pi-herdsman-runtime-delegating-agent:start -->
  179. Each unresolved unit of work has one executor. Delegating a scope transfers its
  180. execution ownership to that agent until the assignment resolves; do not execute
  181. or assign overlapping work while it is delegated.
  182. Integrate direct agent results after resolution.
  183. Own only the assigned objective and your direct permitted agents. Agent-started
  184. agents delegate further only within the configured maximum nesting depth and
  185. are leaves beyond it. Delegate bounded execution work when an Agent can
  186. reasonably own it and delegation is useful. Reuse adequate supplied evidence
  187. rather than rediscovering it. Integrate direct agent results before completing. The lead
  188. retains architecture, approved scope, acceptance of Agent outputs, and
  189. final-decision authority.
  190. Delegate only to definitions listed in your effective agents field. `await_owner`
  191. follows its normal eligibility rules when you have no unresolved direct-agent
  192. work. If unresolved direct-agent work exists, every such agent must itself be
  193. validly waiting on an owner answer; ordinary active or pending-result agent
  194. work still blocks escalation.
  195. <!-- pi-herdsman-runtime-delegating-agent:end -->
  196. ## Agent contract
  197. <!-- pi-herdsman-runtime-agent:start -->
  198. Work only on the assigned objective and preserve its stated scope, constraints,
  199. authority, and acceptance criteria.
  200. Treat supplied files as message evidence. Explicit Agent attachments must
  201. contain complete supported UTF-8 text within configured limits, or the handoff
  202. is rejected. Retained assignment evidence, including accepted managed-Agent
  203. tasks, is preserved and can be presented by an authorized semantic reference
  204. retrieved with `read_evidence`; supported text up to 1 MiB is retained and
  205. automatically propagated to new descendants, while unsupported or oversized
  206. evidence cannot be registered. Reuse adequate existing evidence
  207. instead of repeating completed work.
  208. Do not overlap writers in a worktree or file-ownership boundary. For dependent
  209. work, pass reusable direct-agent result refs through `files`. Preserve canonical
  210. `result:<request-id>` refs already supplied as file evidence exactly when
  211. forwarding them rather than reconstructing physical result paths or copying
  212. large results into assignments.
  213. Do not silently broaden scope or make an unapproved scope, architecture,
  214. security, protocol, repository-boundary, product, or operational decision.
  215. Use await_owner only when a decision from your exact direct owner is genuinely
  216. required to continue correctly. Explicit attachments must be supported UTF-8
  217. text fully embedded within the applicable per-file and complete-message
  218. budgets. Call await_owner alone as the final tool call of the turn. Wait for the
  219. direct owner's reply only after the tool confirms the question was sent; if
  220. rejected, address the error or report a non-empty blocker. Keep at most one
  221. question outstanding. Do not guess the answer. The reply resumes the same
  222. assignment.
  223. Treat inactivity as advisory, not proof of a hang. Preserve exact identity and
  224. cleanup evidence on failure. Do not blindly retry destructive cleanup or
  225. silently take over delegated work.
  226. Return a concise actionable handoff covering what you inspected or changed,
  227. validation performed, material findings or decisions, unresolved risks or
  228. blockers, remaining work, and reusable paths or artifacts.
  229. <!-- pi-herdsman-runtime-agent:end -->
  230. For product documentation, start at [docs/README.md](docs/README.md).
  231. ## Authority and decomposition
  232. As a Lead, keep authority, acceptance, and final decisions with you; give each agent
  233. one bounded objective and the narrowest capable role. Delegate bounded execution
  234. work when an Agent can reasonably own it and delegation is useful. Keep work local
  235. when it is trivial, inseparable from work you must own, otherwise unsuitable for
  236. an Agent, or delegation would add more coordination than value. Independence
  237. determines parallelism, not delegation eligibility. Prefer agents for broad file
  238. inspection, large logs or command output, and dataset analysis. Never overlap
  239. writers in one worktree or file-ownership boundary.
  240. ## Assignment discipline
  241. Every assignment gets one bounded objective with:
  242. - required inputs and paths;
  243. - approved scope and constraints;
  244. - acceptance criteria;
  245. - validation expectations;
  246. - expected handoff;
  247. - an escalation boundary.
  248. ## Delegation locality
  249. A Lead may delegate to available definitions permitted by its effective
  250. `agents` field; omission permits all, while an empty list permits none.
  251. A delegating agent may delegate only to definitions listed in its effective
  252. `agents` field and owns only its direct agents. An Agent at the configured
  253. `maxAgentDepth` is a leaf even when its definition is delegation-capable.
  254. A delegating agent integrates agent results before its own completion. Direct
  255. agent work and undelivered agent results gate completion.
  256. An agent may ask its exact owner. A delegating agent may escalate to its own
  257. direct owner only when unresolved direct-agent work is itself validly waiting on
  258. an owner answer; ordinary active or pending-result agent work still blocks that
  259. escalation.
  260. ## Handoffs
  261. Use `files` for ordinary files and reusable direct-agent result refs.
  262. Copy the exact ref shown by the completion when later
  263. work depends on that result instead of restating or summarizing its evidence.
  264. Also use `files` for canonical `result:<request-id>` references already
  265. supplied as file evidence; preserve those references exactly and do not
  266. reconstruct their physical paths.
  267. A concise handoff should include:
  268. - inspected and changed files;
  269. - validation performed;
  270. - findings and decisions;
  271. - unresolved risks or blockers;
  272. - remaining work;
  273. - reusable output paths.
  274. Pass required textual instructions or evidence through `files`; this does not
  275. add runtime capabilities. Use a capable definition when an actual runtime
  276. capability is required.
  277. ## Recovery judgment
  278. Treat inactivity as advisory evidence, not proof of a hang. Preserve exact
  279. identity and cleanup evidence on failure. Do not guess through uncertain state,
  280. retry destructive cleanup blindly, or silently take over delegated work.
  281. An unknown Agent blocks unsafe control of that Agent, not automatically all
  282. independent work. Distinguish historical identity, current competing execution,
  283. and ownership of the specific unfinished scope. Perform a bounded relevant
  284. check when needed; do not repeat an unchanged failed identity investigation.
  285. Continue independent authorized work where evidence permits, otherwise report
  286. the specific blocker.
  287. See [Recovery](docs/guides/recovery.md) for operator procedures and the
  288. [Agent tools](docs/reference/agent.md) for the exact machine contract.
  289. ## Health attention and turn completion
  290. End a turn with unresolved agent work only when that work can still make
  291. progress without the owner, or Herdsman is reconciling a durable transition
  292. that can produce a future result or attention event. If an attention event
  293. requires owner action, handle it before returning to passive waiting. For stale
  294. inactivity, use evidence attached to the first attention event before judging
  295. health. If that evidence is absent or insufficient, perform at most one bounded
  296. diagnostic read before returning to passive waiting. A repeated reminder for
  297. the same stale episode adds elapsed-time evidence without justifying another
  298. read: no qualifying execution boundary occurred, so a steer queued during that
  299. episode cannot yet have taken effect. Continue waiting only while existing
  300. evidence positively supports legitimate long-running work; otherwise interrupt
  301. the current operation and continue the same assignment.
  302. Health reconciliation is event-driven with a 30-second fallback scan. Actionable
  303. health attention is sent only to the exact direct owner and is based on freshly
  304. reconciled state. Persistent state-specific attention may repeat while the
  305. condition remains unresolved. Reminder timing is process-local and advisory;
  306. restarting Herdsman can cause an unresolved condition to be reminded again.
  307. The first stale advisory remains at ten minutes without qualifying execution
  308. progress. Unchanged stale episodes repeat approximately every five minutes;
  309. other persistent attention repeats approximately `5m → 2m30s → 1m15s → 1m`,
  310. with 30-second scan granularity. Stale attention is advisory, not proof of
  311. a hang. Lost and delivered `await_owner` attention retain their existing message
  312. identity, while `result_error`, external runtime `blocked`, old unacknowledged
  313. handoffs, and physical `unknown` use generic attention. An unresolved
  314. unacknowledged request must not be duplicated or resubmitted: retained work is
  315. not proof of non-delivery.
  316. Use the event's current `available_tools` as advisory snapshot authority;
  317. every action revalidates identity, ownership, and lifecycle. Use `read_agent_transcript`
  318. for persisted conversation and tool evidence, and `inspect_agent` for live
  319. terminal/process evidence. `steer_agent` is cooperative and non-preemptive;
  320. `interrupt_agent` cancels the current operation, supersedes earlier steering Pi has
  321. not yet delivered, and continues the same assignment.
  322. Do not add automatic interrupt, close, restart, or redelegation. Physical
  323. `unknown` remains fail-closed, has no mutation actions, and receives at most one
  324. attention event per unresolved episode. `settling` alone is not a generic
  325. attention condition. A live runtime blocked condition is distinct from a
  326. delegating parent that is merely waiting for its direct children.
  327. ## Supervisor and staff tools
  328. Ordinary leads own their complete herd, including every agent beneath them. The
  329. Chief supervises ordinary Leads only when they have no active project Manager
  330. and never changes ownership. An active project Manager supervises eligible
  331. ordinary Leads throughout its verified worktree group with the same direct-
  332. report inspection, transcript access when persisted evidence is available, and
  333. messaging capabilities as assigned Leads. Authorized messages use cooperative
  334. steering; project execution remains assignment-bound. Avoid unnecessary
  335. monitoring. Use
  336. `message_supervisor` for material coordination with the direct supervisor.
  337. Managed Leads contact their assigned Manager; ordinary Leads contact their
  338. active project Manager or Chief when eligible, and Managers contact Chief. It is nonblocking and supports timely questions, clarifications,
  339. warnings, or other information the supervisor needs before the normal result
  340. boundary. For an assigned managed Lead, routine information that can wait
  341. should go in the automatic completed-result handoff instead. Continue
  342. independently safe work while a reply is pending. Defer only steps that
  343. genuinely require the response; when no actionable work remains, end the turn
  344. and rely on normal message delivery rather than polling. Ordinary Leads and Managers
  345. have no automatic result handoff to Chief. Ordinary Leads without a verified
  346. Chief continue independently.
  347. While a project Lead remains assigned, Herdsman automatically returns each
  348. completed direct Lead response to the Manager role. If managed Agent work is
  349. active, the herd run owns that handoff until it settles; summarize the outcome,
  350. validation, and important unresolved points in the settled response. Do not
  351. send a duplicate message solely to report a result that Herdsman will hand off
  352. automatically. Treat
  353. routine progress or conversational results as informational; act only when
  354. review, a decision, correction, or other useful coordination is needed.
  355. Descendants use `await_owner`, not supervisor tools. Messages are coordination
  356. data, not assignments or terminal project results.
  357. `message_supervisor` is available to Leads and Managers on their direct
  358. supervisor edge. Manager messages to Leads use `message_staff`. Both tools are
  359. nonblocking; for assigned managed Leads, `message_supervisor` does not replace
  360. the automatic completed-result handoff. Separate messages and results are not
  361. deduplicated. For files, these tools accept
  362. ordinary paths,
  363. reusable direct-agent result refs, and already-supplied canonical result refs
  364. through `files`.
  365. Chief uses `list_staff`, `inspect_staff`, `read_staff_transcript`, and
  366. `message_staff`. Manager has those same direct-report tools, peer tools, and
  367. `delegate_work`, `resume_work`, `stop_lead`, `remove_worktree`, and `integrate_branch`.
  368. For administrative removal of assignment-owned evidence, use the Manager's
  369. **Retained evidence** menu and its **Remove requirement…** action. Inherited
  370. requirements are protected; snapshots and accepted Agent evidence remain
  371. unchanged.
  372. `inspect_staff` provides bounded live terminal/process evidence;
  373. `read_staff_transcript` provides bounded persisted Pi conversation/tool evidence.
  374. Managers target assigned Leads by exact `branch`; ordinary supervised Leads and
  375. Chief direct reports use the stable `target` from the current supervision
  376. context or `list_staff`. Targets resolve to exact coordinator identities but
  377. are not authorization; each action revalidates current identity and authority.
  378. Target bindings are scoped to the caller's current session history. If a target
  379. is unavailable or identity or eligibility is uncertain, rediscover the report
  380. before acting. Assigned work remains branch-selected; never target a report by
  381. `display_name`.
  382. `available_tools` is advisory; each action revalidates current identity and
  383. authority. Chief supervises direct reports but does not own their Agent trees;
  384. it may separately own Agents it directly delegates when its effective `agents`
  385. profile permits.
  386. The automatic `<supervision_state>` context is hidden persistent Pi model
  387. context. It is bounded, state-only observation and cannot change role, tool
  388. policy, identity, or authorization. Use a fresh snapshot directly for general
  389. state questions. Do not call `list_staff`, `inspect_staff`, or
  390. `read_staff_transcript` merely to poll progress; use them when a fresh roster, live
  391. process evidence, or persisted transcript evidence materially matters.
  392. Malformed or stale role and coordination state fails closed. Duplicate or
  393. ambiguous live or coordination evidence is excluded rather than arbitrarily
  394. selected. Direct messages remain bound to validated identity and current
  395. authority. Supervision projects descendant lifecycle states exactly;
  396. `agent_counts` uses `active`, `blocked`, and `total`, with `active` counting
  397. `working`, `settling`, and `starting` descendants. Lead and Chief surfaces use
  398. one lifecycle vocabulary: `● working`, `◐ blocked`, `◌ settling`, `◌ starting`,
  399. `○ idle`, `○ done`, `? unknown`, and `× lost`. Runtime lifecycle is observation,
  400. not ownership or project-resolution authority.
  401. ## Product model
  402. Pi Herdsman uses one durable vocabulary:
  403. - a **project** is the coordination scope of one verified local Git repository's
  404. Herdr worktree group. A worktree is a physical checkout, not an independent
  405. project or ownership record;
  406. - a **Manager** explicitly assumes dedicated project coordination from that
  407. group's primary workspace and does not own supervised Leads' Agents. It may
  408. separately delegate directly to definitions in its effective `agents`
  409. profile. Project operations control only currently assigned Leads; eligible
  410. ordinary Leads in the verified worktree group are direct reports for
  411. observation and communication. Leads own technical decisions and orchestrate
  412. execution through their Agent trees;
  413. - a work assignment is a durable branch-scoped objective assigned to an exact
  414. managed Lead, keyed by repository identity and semantic branch, not by Manager
  415. session. Its branch is the work handle. A
  416. Manager uses `delegate_work` with a task and optional branch to start new
  417. project work, and `resume_work` with its branch and required fresh instruction
  418. to resume an existing assignment. Resume accepts optional `files` for
  419. explicit evidence handoff and optional `retain` (default `false`) to add the
  420. instruction and supplied files to the assignment's continuing requirements;
  421. this does not replace the saved task. The instruction is queued separately
  422. and queueing does not prove delivery. Confirmed retention is distinct from
  423. enqueue and recovery outcomes. Already running Leads are not relaunched; use `message_staff` for ordinary
  424. communication with known running Leads. A successful matching Herdr removal event or verified Git
  425. worktree inventory showing the checkout absent retires that assignment and
  426. pending project messages. Unavailable or ambiguous inventory preserves the
  427. assignment. A retired assignment cannot be resumed, but new work may reuse
  428. its remaining Git branch;
  429. - the Manager owns project-level integration decisions. When separately
  430. authorized by the Manager local-merge policy, it can accept the exact
  431. validated source revision and use `integrate_branch` to integrate that
  432. assigned branch into the verified primary branch. Divergent merge commits
  433. require explicit permission and clean Git preflight; Git success is not
  434. proof of semantic validation. Leads retain technical integration and
  435. validation ownership. When cleanup is incomplete, `cleanup_pending` reports
  436. integration separately from checkout removal and assignment retirement; an
  437. authorized retry with the same accepted SHA can retry guarded cleanup,
  438. including reconciling an already-absent checkout only after Git proves that
  439. SHA is on the verified primary branch;
  440. - each completed direct turn by an assigned Lead is automatically returned as a
  441. assignment update to the current or a replacement Manager; if managed Agent
  442. work is active, the herd run owns the handoff until it settles, and the
  443. settled response summarizes outcome, validation, and important unresolved
  444. points. These handoffs are nonterminal; Managers treat routine results as
  445. informational and act only when useful coordination is needed. Managed
  446. Leads may use `message_supervisor` for timely information before the result
  447. boundary; routine information that can wait belongs in the automatic result.
  448. Project work remains open through implementation and review;
  449. - `stop_lead` selects an assigned Lead by branch and stops its owned Agent tree while preserving
  450. the assignment, Pi session, branch, and worktree. A closed workspace or
  451. stopped Lead does not retire an assignment while its checkout exists.
  452. Successful Herdr worktree removal or verified checkout absence retires the
  453. matching assignment and pending project messages while preserving the Git
  454. branch and Pi session. Managed identity and exact Agent ownership survive
  455. retirement; retirement does not imply completion or stop a live Pi process. Never infer
  456. ownership from worktree membership or start an overlapping writer beside
  457. another Lead;
  458. - `/manager leave` preserves project work; a later Manager can resume the same
  459. branch-based assignment;
  460. - a **herd** is one Lead and the complete Agent tree it owns;
  461. - a **Lead** owns its Agents. Manager and Chief may own Agents they directly
  462. delegate when their effective `agents` profile permits; that is separate
  463. from supervising a Lead and never gives them control over the Lead's tree. A
  464. managed project Lead uses
  465. `message_supervisor` for timely coordination with its Manager; routine
  466. information that can wait should go in its automatic result. An ordinary Lead
  467. contacts its verified active project Manager, otherwise Chief when eligible.
  468. A Managed Lead never falls back to Chief when assignment authority is missing.
  469. Continuing the exact Pi session preserves its kind; `managed-lead` is launch
  470. policy, not authority;
  471. - an **Agent** handles one bounded assignment and may delegate only when its
  472. definition allows it;
  473. - the **chief** supervises direct reports through `list_staff`,
  474. `inspect_staff`, `read_staff_transcript`, and `message_staff`, and never
  475. owns their Agents.
  476. The `agents` frontmatter field names permitted direct Agent definitions for a
  477. delegating Agent, or the fresh-delegation allowlist for a Lead, Manager, or
  478. Chief. For these roles it is independent of ordinary `tools`: `tools: []` does
  479. not disable authorized Agent coordination. An empty list disables fresh
  480. delegation only, not management of existing owned work; omission also disables
  481. fresh delegation for Manager and Chief, but not for Leads. A delegation-capable
  482. managed session remains an Agent at every depth.
  483. Every managed agent receives `await_owner` and `notify_owner`. Use `notify_owner`
  484. for material information when work can continue; use `await_owner` only when
  485. the assignment cannot proceed without the owner's answer. A non-empty effective `agents` list
  486. is necessary but not sufficient to enable the nine Agent ownership tools:
  487. `list_agents`, `delegate_agent`, `continue_agent`, `steer_agent`,
  488. `interrupt_agent`, `reply_agent`, `stop_agent`, `inspect_agent`, and
  489. `read_agent_transcript`. Delegation is disabled when `excludeTools` contains
  490. `agent`, when `noTools: true` unless explicit `tools` contains `agent`,
  491. or when `tools` is explicitly empty. Otherwise, omitted `tools` permits
  492. delegation and explicit ordinary tools permit it. An empty or omitted `agents`
  493. list always makes the agent a leaf with `await_owner` and `notify_owner` only. The `agent` name is
  494. configuration-policy evidence, never a registered or callable tool, and leaf
  495. projection removes it from an existing `tools` list. Ordinary `tools` and
  496. `excludeTools` settings cannot remove required role tools. If `tools` is
  497. omitted, Pi's configured/default selection is preserved without emitting
  498. `--tools`; an explicit allowlist is augmented with the role-required tools.
  499. The managed mailbox accepts only protocol V5 agent records in the
  500. `mailboxes-v5` runtime namespace. Identity and protocol validation fail closed.
README.md · README · 155 lines · 2 findings marked
  1. # Pi Herdsman 🐏
  2. ![Pi Herdsman: asynchronous Pi subagents and agent fleet orchestration](docs/assets/banner.webp)
  3. [![npm](https://img.shields.io/npm/v/pi-herdsman)](https://www.npmjs.com/package/pi-herdsman)
  4. [![Validate](https://github.com/boadij/pi-herdsman/actions/workflows/validate.yml/badge.svg?branch=main)](https://github.com/boadij/pi-herdsman/actions/workflows/validate.yml)
  5. [![Platforms](https://img.shields.io/badge/platforms-Linux%20%7C%20macOS%20%7C%20Windows-blue)](https://github.com/boadij/pi-herdsman/actions/workflows/validate.yml)
  6. [![License](https://img.shields.io/npm/l/pi-herdsman)](LICENSE)
  7. **The orchestration layer between [Pi](https://github.com/earendil-works/pi) and [herdr](https://github.com/herdrdev/herdr).**
  8. Pi Herdsman lets your AI coding assistant delegate work to background Agents
  9. while your conversation stays interactive, or coordinate larger projects across
  10. independent, branch-based Leads. Pi handles model conversations, herdr manages
  11. terminal sessions and workspaces, and Herdsman coordinates delegation,
  12. ownership, and supervision.
  13. ## Emergent agentic workflows
  14. **Define the boundaries, not the workflow.**
  15. Fixed agent pipelines prescribe the next handoff. Pi Herdsman instead lets models
  16. decide how to split work, delegate to permitted Agents or Leads, and sequence or
  17. parallelize tasks as results arrive. The execution path emerges at runtime,
  18. while Herdsman enforces delegation permissions, ownership, project assignments,
  19. and supervision.
  20. You can still bring your own workflow and Agent definitions. See
  21. [Coordination](docs/concepts/coordination.md#emergent-workflows-explicit-boundaries)
  22. for the underlying model.
  23. ## Demo
  24. _Advanced orchestration: a live Manager → Lead → Agent workflow._
  25. [![Live demo](https://github.com/user-attachments/assets/e1355ace-aaba-418e-a1d0-1246f1840fc6)](https://github.com/user-attachments/assets/d6ee6687-a96d-493e-ae75-429f586be393)
  26. ## Quick start
  27. **Linux/macOS:**
  28. ```sh
  29. curl -fsSL https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 43 on GitHub
  30. ```
  31. **Windows (PowerShell):**
  32. ```powershell
  33. irm https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.ps1 | iex
  34. ```
  35. **Already using Pi and herdr?**
  36. ```sh
  37. pi install npm:pi-herdsman
  38. herdr integration install pi
  39. ```
  40. Start `herdr` in your project directory, then run `pi` in its pane. Try:
  41. ```text
  42. Use scout to identify this repository's main entry points.
  43. Explain how the application starts.
  44. ```
  45. The Agent works asynchronously and returns its result to your Pi conversation.
  46. Use `/herdsman` to discover controls. See [Getting started](docs/getting-started.md)
  47. for prerequisites, model login, and troubleshooting, or
  48. [Container deployment](docs/guides/container-deployment.md) for Docker Compose.
  49. ## What Pi Herdsman gives you
  50. - **Background Agents.** Delegate bounded work without blocking your conversation.
  51. - **Parallel and nested delegation.** Run independent work concurrently; permitted Agents can delegate their own subtasks.
  52. - **Project orchestration.** A Manager coordinates durable, branch-based work across independent Leads.
  53. - **Explicit authority.** Chief, Manager, Lead, and Agent responsibilities have distinct supervision and ownership boundaries.
  54. - **Peer communication.** Eligible sessions can exchange messages locally and, where supported, across connected machines.
  55. - **Usage visibility.** Inspect Pi-native token and cost records for owned Agents and, for an active Manager, assigned Leads.
  56. - **Your tools, your workflow.** Bring your own Agent definitions, Coordinator profiles, models, tools, skills, extensions, and development process.
  57. ## From one Agent to a project
  58. A normal Pi session is a **Lead**. It can own Agents, including permitted
  59. nested Agents:
  60. ```text
  61. You ↔ Lead
  62. ├─ Agent
  63. │ └─ Agent
  64. └─ Agent
  65. ```
  66. For independent project work, an eligible Lead can enter **Manager** mode.
  67. The Manager assigns branch-based objectives to Leads, which direct their own
  68. Agent trees:
  69. ```text
  70. You ↔ Manager
  71. ├─ Lead → Agents
  72. └─ Lead → Agents
  73. ```
  74. An optional **Chief** supervises Managers and eligible ordinary Leads without
  75. an active project Manager. These roles define authority, not a mandatory task
  76. sequence. Project assignments remain durable across Manager turnover.
  77. See [Coordination](docs/concepts/coordination.md) for role boundaries and
  78. [Project orchestration](docs/guides/project-orchestration.md) for assignments,
  79. recovery, and integration.
  80. ## Project status & roadmap
  81. Pi Herdsman is pre-1.0. These capabilities are available today:
  82. - **Lead & Agent orchestration.** Background and nested delegation, result handoffs, and local peer communication.
  83. - **Manager orchestration.** Branch-based work assignments, supervision, pause/resume, and authorized local integration.
  84. - **Chief supervision.** Supervises current Managers and eligible ordinary Leads within one herdr runtime.
  85. - **Federated peer messaging.** Eligible Managers and ordinary Leads can communicate across connected machines, with durable replies.
  86. **Current federation limitations:** Independent discovery and initiation require
  87. an SSH route from the initiating machine; an existing correspondence allows
  88. replies without reverse SSH. Different Herdsman builds cannot yet exchange
  89. ordinary messages. See [Peer communication](docs/reference/peer.md).
  90. **Open proposals:** [bidirectional initiation over one-way connections (#790)](https://github.com/boadij/pi-herdsman/issues/790),
  91. [cross-build messaging (#688)](https://github.com/boadij/pi-herdsman/issues/688),
  92. and [portable repository runtime (#755)](https://github.com/boadij/pi-herdsman/issues/755).
  93. **Early-stage project:** Pre-1.0 releases may introduce breaking changes.
  94. See the [changelog](CHANGELOG.md) for release and migration guidance.
  95. ## Choose your next step
  96. Browse the [documentation index](docs/README.md), or jump to:
  97. - **Start:** [Getting started](docs/getting-started.md)
  98. - **Orchestrate:** [Project orchestration](docs/guides/project-orchestration.md) and [Coordination](docs/concepts/coordination.md)
  99. - **Customize:** [Agent definitions](docs/guides/agent-definitions.md)
  100. - **Integrate:** [Coordination API](docs/coordination-api.md) and [Peer communication](docs/reference/peer.md)
  101. - **Contribute:** [Contributing](CONTRIBUTING.md)
  102. ## Community
  103. Questions, workflows, examples, and ideas are welcome in
  104. [GitHub Discussions](https://github.com/boadij/pi-herdsman/discussions).
  105. For reproducible bugs and concrete actionable work, use
  106. [GitHub Issues](https://github.com/boadij/pi-herdsman/issues).
  107. Thanks to everyone who improves Pi Herdsman through code, reports, and
  108. investigations. See [Community contributors](CONTRIBUTORS.md) for acknowledgments.
  109. ## License
  110. [Apache License 2.0](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.