agents
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.
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
Markdown
[](/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
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
- ---
- name: agents
- description: Optional reinforcement and strategy for orchestrating managed agents.
- ---
- # Pi Herdsman
- 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
- <!-- pi-herdsman-runtime-controller:start -->
- Coordinate managed agents.
- Use these high-salience rules for the model-facing agent boundary:
- - 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 any coordination tool that accepts `files`, pass every user-supplied or
- already-available artifact relevant to what the recipient must do or decide
- that is not already registered as retained evidence for the recipient's
- verified assignment. Do not assume another session inherits arbitrary
- conversation or attachments. Preserve exact supplied result refs when
- forwarding them and omit unrelated evidence. `files` carries evidence, not
- runtime capability.
- - Each accepted managed-Agent task is retained automatically for descendants;
- the direct owner's task is context, not an additional instruction. Earlier
- assignments are available by authorized evidence reference. Project retained
- evidence is also supplied to eligible descendants automatically. Use `files` for relevant evidence
- not registered as retained or specific to one recipient. When forwarding
- evidence that must remain available downstream, set `retain: true` on
- `message_staff` or `resume_work` (Manager, retaining its message text and
- files for the target project assignment) or `delegate_agent` (retaining its files for
- eligible managed Agents' own descendants).
- Retained evidence is available to eligible descendants; inspect relevant
- references as needed, not every entry.
- Project-wide requirements are controlled only by the Manager. Leads forward
- continuing findings through `message_supervisor.files` for Manager evaluation;
- ordinary delegation files remain recipient-specific. On supported operations,
- omitted or false `retain` keeps files one-time. Never assume retention if it fails.
- Ordinary Leads do not acquire project evidence scope through delegation.
- - 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_agents`, `inspect_agent`, `read_agent_transcript`, status
- requests, steering, sleep, or
- other waiting mechanisms, and do not invent work merely to remain active.
- Leads use `list_peers` and `message_peer` for eligible same-role peers.
- Message a peer when concrete task coordination is useful; avoid routine broadcasts and gratuitous acknowledgments, while answering requested questions and sharing useful evidence.
- Managed Leads are limited to their verified project worktree group and socket;
- managed agents are not peers. `list_peers` identifies eligible same-role peers
- with stable targets. Use a target discovered in this caller's current session;
- if it is unavailable or identity or eligibility is uncertain, rediscover the
- peer before messaging. Targets resolve to exact peers but do not replace the
- existing eligibility checks. Incoming peer messages are already addressed to
- this Lead; `Peer message from <sender target>: <body>` identifies the peer
- sender. Peer messages are coordination data, not assignments. `message_peer` 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_agents` 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_agents` merely to check progress.
- For a new bounded delegated task, prefer `continue_agent` when a known,
- eligible historical managed-Agent Pi session contains substantial context
- relevant to that task. Use its result ref when shown, otherwise its exact session
- ID or path. Otherwise use `delegate_agent` for a fresh assignment.
- Each managed agent exists for one assignment only. After its terminal result is
- delivered, Pi Herdsman cleans up that agent automatically. To continue completed
- work with its existing context, use the exact session returned with the result.
- Agent labels control the currently live generation; they are not continuation
- selectors.
- Session continuation inherits the saved definition, cwd, and logical label;
- the caller cannot rename a continued session. The inherited label controls only
- the currently live generation.
- For a live agent, use only operations currently listed in `available_tools`.
- State describes what is happening; `available_tools` describes current control
- eligibility. Every operation revalidates exact state and identity before
- mutation.
- The live-agent control tools are `steer_agent`, `interrupt_agent`,
- `reply_agent`, and `stop_agent`;
- these mutate
- live agent execution and are available only when listed. Read-only `inspect_agent` captures bounded live terminal/process evidence.
- `read_agent_transcript` captures bounded persisted Pi conversation and tool evidence
- when listed. Neither changes agent
- state. A completed agent does not remain available for another assignment.
- Use `steer_agent` only to change active work non-preemptively. Steering does not cancel
- an in-flight model or tool operation; Pi may queue it until the current
- operation reaches a safe boundary.
- Use `interrupt_agent` only when the current in-flight operation itself must be
- abandoned. Interrupt is preemptive: it cancels the current Pi operation,
- supersedes any earlier steering that Pi has not yet delivered, and continues
- the same assignment with the required replacement message. Do not interrupt
- merely because an agent is slow or marked stale; inactivity is advisory and
- does not prove a hang.
- Use `reply_agent` only to answer a valid outstanding `await_owner` question. Use
- `stop_agent` only when abandoning the Agent's unfinished assignment is
- intended. Unlike `stop_lead`, which preserves a Manager's project assignment,
- `stop_agent` does not complete or automatically restart the work.
- 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 `read_agent_transcript` is listed,
- use it only when the last persisted work materially affects recovery. When
- `stop_agent` is listed, use it to abandon the lost generation before replacing it or
- continuing its saved session. If `stop_agent` is absent, resolve the condition
- blocking its stop 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.
- If `list_agents` 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.
- 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.
- Attach an agent instruction file only when the task itself requires inspecting,
- modifying, comparing, or transmitting that file, the user explicitly requests
- it, or its instructions are required and the target would not otherwise receive
- them.
- 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.
- Attachment handling depends on the operation. Explicit Agent attachments and
- ordinary coordination attachments deliver only complete supported strict UTF-8
- text within the applicable per-file and complete-message limits; unsupported or
- non-fitting content rejects the operation rather than falling back to a local
- path. Initial `delegate_work` text attachments are retained as snapshots. When
- such a snapshot does not fit inline, it is represented by its semantic
- `evidence:` reference. Previously accepted required evidence can be forwarded
- by its authorized semantic reference; a reference alone does not grant access.
- Authorized recipients retrieve bounded content with `read_evidence`. Embedded
- content is a submission-time snapshot. `files` transfers content or evidence
- references, not tools or runtime capabilities.
- Pass relevant files and completed agent results through `files`. Agent
- completions may expose reusable result refs. 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` 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. `files` does not
- add runtime capability.
- Require concise handoffs containing relevant inspected or changed files,
- validation performed, findings or decisions, unresolved risks or blockers,
- remaining work, and reusable output paths.
- Report blocked or failed work and decisions outside delegated authority rather
- than silently retrying, taking over, or broadening scope. Preserve exact identity
- and cleanup evidence on failure. Treat inactivity as advisory, not proof of a
- hang, and do not blindly retry destructive cleanup or silently take over
- delegated work.
- <!-- pi-herdsman-runtime-controller:end -->
- ## Lead scope
- <!-- pi-herdsman-runtime-lead:start -->
- Own architecture, approved scope, acceptance of Agent outputs, integration,
- conflict resolution, and final technical decisions within your assigned
- objective. Decompose only as far as useful. Reuse adequate existing evidence
- instead of duplicating work. The active Lead execution profile determines the
- balance between direct and delegated work. Ordinary Leads use `flexible-lead`
- or `orchestrator-lead` according to their persisted `flexible` or
- `orchestrate` execution mode. These ordinary sessions execute their authorized
- independent Lead work without requiring a `ProjectAssignment`. Manager-assigned
- Leads use `managed-lead`; the exact current `ProjectAssignment`, not the profile,
- establishes Manager authority. Managed identity is permanent for the exact Pi
- session, including when assignment evidence is unavailable or the assignment
- is retired. Only a current exact assignment permits fresh managed project
- execution; exactly owned Agent recovery remains separate. Use native Pi
- `/fork` or `/clone` for independent ordinary continuation, not a separate Git
- checkout or fresh process configuration. Lead execution configuration does
- not change Agent ownership semantics.
- <!-- pi-herdsman-runtime-lead:end -->
- ## Delegating agent scope
- <!-- 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 delegate further only within the configured maximum nesting depth and
- are leaves beyond it. Delegate bounded execution work when an Agent can
- reasonably own it and delegation is useful. Reuse adequate supplied evidence
- rather than rediscovering it. Integrate direct agent results before completing. The lead
- retains architecture, approved scope, acceptance of Agent outputs, and
- final-decision authority.
- Delegate only to definitions listed in your effective agents field. `await_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 -->
- ## Agent contract
- <!-- pi-herdsman-runtime-agent:start -->
- Work only on the assigned objective and preserve its stated scope, constraints,
- authority, and acceptance criteria.
- Treat supplied files as message evidence. Explicit Agent attachments must
- contain complete supported UTF-8 text within configured limits, or the handoff
- is rejected. Retained assignment evidence, including accepted managed-Agent
- tasks, is preserved and can be presented by an authorized semantic reference
- retrieved with `read_evidence`; supported text up to 1 MiB is retained and
- automatically propagated to new descendants, while unsupported or oversized
- evidence cannot be registered. Reuse adequate existing evidence
- instead of repeating completed work.
- Do not overlap writers in a worktree or file-ownership boundary. For dependent
- 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.
- Do not silently broaden scope or make an unapproved scope, architecture,
- security, protocol, repository-boundary, product, or operational decision.
- Use await_owner only when a decision from your exact direct owner is genuinely
- required to continue correctly. Explicit attachments must be supported UTF-8
- text fully embedded within the applicable per-file and complete-message
- budgets. Call await_owner alone as the final tool call of the turn. Wait for the
- direct owner's reply only after the tool confirms the question was sent; if
- rejected, address the error or report a non-empty blocker. Keep at most one
- question outstanding. Do not guess the answer. The reply resumes the same
- assignment.
- Treat inactivity as advisory, not proof of a hang. Preserve exact identity and
- cleanup evidence on failure. Do not blindly retry destructive cleanup or
- silently take over delegated work.
- Return a concise actionable handoff covering what you inspected or changed,
- validation performed, material findings or decisions, unresolved risks or
- blockers, remaining work, and reusable paths or artifacts.
- <!-- pi-herdsman-runtime-agent:end -->
- For product documentation, start at [docs/README.md](docs/README.md).
- ## Authority and decomposition
- As a Lead, keep authority, acceptance, and final decisions with you; give each agent
- one bounded objective and the narrowest capable role. Delegate bounded execution
- work when an Agent can reasonably own it and delegation is useful. Keep work local
- when it is trivial, inseparable from work you must own, otherwise unsuitable for
- an Agent, or delegation would add more coordination than value. Independence
- determines parallelism, not delegation eligibility. Prefer agents for broad file
- inspection, large logs or command output, and dataset analysis. Never overlap
- writers in one worktree or file-ownership boundary.
- ## Assignment discipline
- Every assignment gets one bounded objective with:
- - required inputs and paths;
- - approved scope and constraints;
- - acceptance criteria;
- - validation expectations;
- - expected handoff;
- - an escalation boundary.
- ## Delegation locality
- A Lead may delegate to available definitions permitted by its effective
- `agents` field; omission permits all, while an empty list permits none.
- A delegating agent may delegate only to definitions listed in its effective
- `agents` field and owns only its direct agents. An Agent at the configured
- `maxAgentDepth` is a leaf even when its definition is delegation-capable.
- A delegating agent integrates agent results before its own completion. Direct
- agent work and undelivered agent results gate completion.
- An agent may ask its exact owner. A delegating agent may escalate to its own
- direct owner only when unresolved direct-agent work is itself validly waiting on
- an owner answer; ordinary active or pending-result agent work still blocks that
- escalation.
- ## Handoffs
- Use `files` for ordinary files and reusable direct-agent result refs.
- 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:
- - inspected and changed files;
- - validation performed;
- - findings and decisions;
- - unresolved risks or blockers;
- - remaining work;
- - reusable output paths.
- Pass required textual instructions or evidence through `files`; this does not
- add runtime capabilities. Use a capable definition when an actual runtime
- capability is required.
- ## Recovery judgment
- Treat inactivity as advisory evidence, not proof of a hang. Preserve exact
- identity and cleanup evidence on failure. Do not guess through uncertain state,
- retry destructive cleanup blindly, or silently take over delegated work.
- An unknown Agent blocks unsafe control of that Agent, not automatically all
- independent work. Distinguish historical identity, current competing execution,
- and ownership of the specific unfinished scope. Perform a bounded relevant
- check when needed; do not repeat an unchanged failed identity investigation.
- Continue independent authorized work where evidence permits, otherwise report
- the specific blocker.
- See [Recovery](docs/guides/recovery.md) for operator procedures and the
- [Agent tools](docs/reference/agent.md) for the exact machine contract.
- ## Health attention and turn completion
- End a turn with unresolved agent work only when that work can still make
- progress without the owner, or Herdsman is reconciling a durable transition
- that can produce a future result or attention event. If an attention event
- requires owner action, handle it before returning to passive waiting. For stale
- inactivity, use evidence attached to the first attention event before judging
- health. If that evidence is absent or insufficient, perform at most one bounded
- diagnostic read before returning to passive waiting. A repeated reminder for
- the same stale episode adds elapsed-time evidence without justifying another
- read: no qualifying execution boundary occurred, so a steer queued during that
- episode cannot yet have taken effect. Continue waiting only while existing
- evidence positively supports legitimate long-running work; otherwise interrupt
- the current operation and continue the same assignment.
- Health reconciliation is event-driven with a 30-second fallback scan. Actionable
- health attention is sent only to the exact direct owner and is based on freshly
- reconciled state. Persistent state-specific attention may repeat while the
- condition remains unresolved. Reminder timing is process-local and advisory;
- restarting Herdsman can cause an unresolved condition to be reminded again.
- The first stale advisory remains at ten minutes without qualifying execution
- progress. Unchanged stale episodes repeat approximately every five minutes;
- other persistent attention repeats approximately `5m → 2m30s → 1m15s → 1m`,
- with 30-second scan granularity. Stale attention is advisory, not proof of
- a hang. Lost and delivered `await_owner` attention retain their existing message
- identity, while `result_error`, external runtime `blocked`, old unacknowledged
- handoffs, and physical `unknown` use generic attention. An unresolved
- unacknowledged request must not be duplicated or resubmitted: retained work is
- not proof of non-delivery.
- Use the event's current `available_tools` as advisory snapshot authority;
- every action revalidates identity, ownership, and lifecycle. Use `read_agent_transcript`
- for persisted conversation and tool evidence, and `inspect_agent` for live
- terminal/process evidence. `steer_agent` is cooperative and non-preemptive;
- `interrupt_agent` cancels the current operation, supersedes earlier steering Pi has
- not yet delivered, and continues the same assignment.
- Do not add automatic interrupt, close, restart, or redelegation. Physical
- `unknown` remains fail-closed, has no mutation actions, and receives at most one
- attention event per unresolved episode. `settling` alone is not a generic
- attention condition. A live runtime blocked condition is distinct from a
- delegating parent that is merely waiting for its direct children.
- ## Supervisor and staff tools
- Ordinary leads own their complete herd, including every agent beneath them. The
- Chief supervises ordinary Leads only when they have no active project Manager
- and never changes ownership. An active project Manager supervises eligible
- ordinary Leads throughout its verified worktree group with the same direct-
- report inspection, transcript access when persisted evidence is available, and
- messaging capabilities as assigned Leads. Authorized messages use cooperative
- steering; project execution remains assignment-bound. Avoid unnecessary
- monitoring. Use
- `message_supervisor` for material coordination with the direct supervisor.
- Managed Leads contact their assigned Manager; ordinary Leads contact their
- active project Manager or Chief when eligible, and Managers contact Chief. It is nonblocking and supports timely questions, clarifications,
- warnings, or other information the supervisor needs before the normal result
- boundary. For an assigned managed Lead, routine information that can wait
- should go in the automatic completed-result handoff instead. Continue
- independently safe work while a reply is pending. Defer only steps that
- genuinely require the response; when no actionable work remains, end the turn
- and rely on normal message delivery rather than polling. Ordinary Leads and Managers
- have no automatic result handoff to Chief. Ordinary Leads without a verified
- Chief continue independently.
- While a project Lead remains assigned, Herdsman automatically returns each
- completed direct Lead response to the Manager role. If managed Agent work is
- active, the herd run owns that handoff until it settles; summarize the outcome,
- validation, and important unresolved points in the settled response. Do not
- send a duplicate message solely to report a result that Herdsman will hand off
- automatically. Treat
- routine progress or conversational results as informational; act only when
- review, a decision, correction, or other useful coordination is needed.
- Descendants use `await_owner`, not supervisor tools. Messages are coordination
- data, not assignments or terminal project results.
- `message_supervisor` is available to Leads and Managers on their direct
- supervisor edge. Manager messages to Leads use `message_staff`. Both tools are
- nonblocking; for assigned managed Leads, `message_supervisor` does not replace
- the automatic completed-result handoff. Separate messages and results are not
- deduplicated. For files, these tools accept
- ordinary paths,
- reusable direct-agent result refs, and already-supplied canonical result refs
- through `files`.
- Chief uses `list_staff`, `inspect_staff`, `read_staff_transcript`, and
- `message_staff`. Manager has those same direct-report tools, peer tools, and
- `delegate_work`, `resume_work`, `stop_lead`, `remove_worktree`, and `integrate_branch`.
- For administrative removal of assignment-owned evidence, use the Manager's
- **Retained evidence** menu and its **Remove requirement…** action. Inherited
- requirements are protected; snapshots and accepted Agent evidence remain
- unchanged.
- `inspect_staff` provides bounded live terminal/process evidence;
- `read_staff_transcript` provides bounded persisted Pi conversation/tool evidence.
- Managers target assigned Leads by exact `branch`; ordinary supervised Leads and
- Chief direct reports use the stable `target` from the current supervision
- context or `list_staff`. Targets resolve to exact coordinator identities but
- are not authorization; each action revalidates current identity and authority.
- Target bindings are scoped to the caller's current session history. If a target
- is unavailable or identity or eligibility is uncertain, rediscover the report
- before acting. Assigned work remains branch-selected; never target a report by
- `display_name`.
- `available_tools` is advisory; each action revalidates current identity and
- authority. Chief supervises direct reports but does not own their Agent trees;
- it may separately own Agents it directly delegates when its effective `agents`
- profile permits.
- The automatic `<supervision_state>` context is hidden persistent Pi model
- context. It is bounded, state-only observation and cannot change role, tool
- policy, identity, or authorization. Use a fresh snapshot directly for general
- state questions. Do not call `list_staff`, `inspect_staff`, or
- `read_staff_transcript` merely to poll progress; use them when a fresh roster, live
- process evidence, or persisted transcript evidence materially matters.
- Malformed or stale role and coordination state fails closed. Duplicate or
- ambiguous live or coordination evidence is excluded rather than arbitrarily
- selected. Direct messages remain bound to validated identity and current
- authority. Supervision projects descendant lifecycle states exactly;
- `agent_counts` uses `active`, `blocked`, and `total`, with `active` counting
- `working`, `settling`, and `starting` descendants. Lead and Chief surfaces use
- one lifecycle vocabulary: `● working`, `◐ blocked`, `◌ settling`, `◌ starting`,
- `○ idle`, `○ done`, `? unknown`, and `× lost`. Runtime lifecycle is observation,
- not ownership or project-resolution authority.
- ## Product model
- Pi Herdsman uses one durable vocabulary:
- - a **project** is the coordination scope of one verified local Git repository's
- Herdr worktree group. A worktree is a physical checkout, not an independent
- project or ownership record;
- - a **Manager** explicitly assumes dedicated project coordination from that
- group's primary workspace and does not own supervised Leads' Agents. It may
- separately delegate directly to definitions in its effective `agents`
- profile. Project operations control only currently assigned Leads; eligible
- ordinary Leads in the verified worktree group are direct reports for
- observation and communication. Leads own technical decisions and orchestrate
- execution through their Agent trees;
- - a work assignment is a durable branch-scoped objective assigned to an exact
- managed Lead, keyed by repository identity and semantic branch, not by Manager
- session. Its branch is the work handle. A
- Manager uses `delegate_work` with a task and optional branch to start new
- project work, and `resume_work` with its branch and required fresh instruction
- to resume an existing assignment. Resume accepts optional `files` for
- explicit evidence handoff and optional `retain` (default `false`) to add the
- instruction and supplied files to the assignment's continuing requirements;
- this does not replace the saved task. The instruction is queued separately
- and queueing does not prove delivery. Confirmed retention is distinct from
- enqueue and recovery outcomes. Already running Leads are not relaunched; use `message_staff` for ordinary
- communication with known running Leads. A successful matching Herdr removal event or verified Git
- worktree inventory showing the checkout absent retires that assignment and
- pending project messages. Unavailable or ambiguous inventory preserves the
- assignment. A retired assignment cannot be resumed, but new work may reuse
- its remaining Git branch;
- - the Manager owns project-level integration decisions. When separately
- authorized by the Manager local-merge policy, it can accept the exact
- validated source revision and use `integrate_branch` to integrate that
- assigned branch into the verified primary branch. Divergent merge commits
- require explicit permission and clean Git preflight; Git success is not
- proof of semantic validation. Leads retain technical integration and
- validation ownership. When cleanup is incomplete, `cleanup_pending` reports
- integration separately from checkout removal and assignment retirement; an
- authorized retry with the same accepted SHA can retry guarded cleanup,
- including reconciling an already-absent checkout only after Git proves that
- SHA is on the verified primary branch;
- - each completed direct turn by an assigned Lead is automatically returned as a
- assignment update to the current or a replacement Manager; if managed Agent
- work is active, the herd run owns the handoff until it settles, and the
- settled response summarizes outcome, validation, and important unresolved
- points. These handoffs are nonterminal; Managers treat routine results as
- informational and act only when useful coordination is needed. Managed
- Leads may use `message_supervisor` for timely information before the result
- boundary; routine information that can wait belongs in the automatic result.
- Project work remains open through implementation and review;
- - `stop_lead` selects an assigned Lead by branch and stops its owned Agent tree while preserving
- the assignment, Pi session, branch, and worktree. A closed workspace or
- stopped Lead does not retire an assignment while its checkout exists.
- Successful Herdr worktree removal or verified checkout absence retires the
- matching assignment and pending project messages while preserving the Git
- branch and Pi session. Managed identity and exact Agent ownership survive
- retirement; retirement does not imply completion or stop a live Pi process. Never infer
- ownership from worktree membership or start an overlapping writer beside
- another Lead;
- - `/manager leave` preserves project work; a later Manager can resume the same
- branch-based assignment;
- - a **herd** is one Lead and the complete Agent tree it owns;
- - a **Lead** owns its Agents. Manager and Chief may own Agents they directly
- delegate when their effective `agents` profile permits; that is separate
- from supervising a Lead and never gives them control over the Lead's tree. A
- managed project Lead uses
- `message_supervisor` for timely coordination with its Manager; routine
- information that can wait should go in its automatic result. An ordinary Lead
- contacts its verified active project Manager, otherwise Chief when eligible.
- A Managed Lead never falls back to Chief when assignment authority is missing.
- Continuing the exact Pi session preserves its kind; `managed-lead` is launch
- policy, not authority;
- - an **Agent** handles one bounded assignment and may delegate only when its
- definition allows it;
- - the **chief** supervises direct reports through `list_staff`,
- `inspect_staff`, `read_staff_transcript`, and `message_staff`, and never
- owns their Agents.
- The `agents` frontmatter field names permitted direct Agent definitions for a
- delegating Agent, or the fresh-delegation allowlist for a Lead, Manager, or
- Chief. For these roles it is independent of ordinary `tools`: `tools: []` does
- not disable authorized Agent coordination. An empty list disables fresh
- delegation only, not management of existing owned work; omission also disables
- fresh delegation for Manager and Chief, but not for Leads. A delegation-capable
- managed session remains an Agent at every depth.
- Every managed agent receives `await_owner` and `notify_owner`. Use `notify_owner`
- for material information when work can continue; use `await_owner` only when
- the assignment cannot proceed without the owner's answer. A non-empty effective `agents` list
- is necessary but not sufficient to enable the nine Agent ownership tools:
- `list_agents`, `delegate_agent`, `continue_agent`, `steer_agent`,
- `interrupt_agent`, `reply_agent`, `stop_agent`, `inspect_agent`, and
- `read_agent_transcript`. Delegation is disabled when `excludeTools` contains
- `agent`, when `noTools: true` unless explicit `tools` contains `agent`,
- or when `tools` is explicitly empty. Otherwise, omitted `tools` permits
- delegation and explicit ordinary tools permit it. An empty or omitted `agents`
- list always makes the agent a leaf with `await_owner` and `notify_owner` only. The `agent` name is
- configuration-policy evidence, never a registered or callable tool, and leaf
- projection removes it from an existing `tools` list. Ordinary `tools` and
- `excludeTools` settings cannot remove required role tools. If `tools` is
- omitted, Pi's configured/default selection is preserved without emitting
- `--tools`; an explicit allowlist is augmented with the role-required tools.
- The managed mailbox accepts only protocol V5 agent records in the
- `mailboxes-v5` runtime namespace. Identity and protocol validation fail closed.
README.md · README · 155 lines · 2 findings marked
- # Pi Herdsman 🐏
- 
- [](https://www.npmjs.com/package/pi-herdsman)
- [](https://github.com/boadij/pi-herdsman/actions/workflows/validate.yml)
- [](https://github.com/boadij/pi-herdsman/actions/workflows/validate.yml)
- [](LICENSE)
- **The orchestration layer between [Pi](https://github.com/earendil-works/pi) and [herdr](https://github.com/herdrdev/herdr).**
- Pi Herdsman lets your AI coding assistant delegate work to background Agents
- while your conversation stays interactive, or coordinate larger projects across
- independent, branch-based Leads. Pi handles model conversations, herdr manages
- terminal sessions and workspaces, and Herdsman coordinates delegation,
- ownership, and supervision.
- ## Emergent agentic workflows
- **Define the boundaries, not the workflow.**
- Fixed agent pipelines prescribe the next handoff. Pi Herdsman instead lets models
- decide how to split work, delegate to permitted Agents or Leads, and sequence or
- parallelize tasks as results arrive. The execution path emerges at runtime,
- while Herdsman enforces delegation permissions, ownership, project assignments,
- and supervision.
- You can still bring your own workflow and Agent definitions. See
- [Coordination](docs/concepts/coordination.md#emergent-workflows-explicit-boundaries)
- for the underlying model.
- ## Demo
- _Advanced orchestration: a live Manager → Lead → Agent workflow._
- [](https://github.com/user-attachments/assets/d6ee6687-a96d-493e-ae75-429f586be393)
- ## Quick start
- **Linux/macOS:**
- ```sh
- 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
- ```
- **Windows (PowerShell):**
- ```powershell
- irm https://raw.githubusercontent.com/boadij/pi-herdsman/main/install.ps1 | iex
- Note: Runs a downloaded PowerShell script (iex / Invoke-Expression)
- Line 49 on GitHub
- ```
- **Already using Pi and herdr?**
- ```sh
- pi install npm:pi-herdsman
- herdr integration install pi
- ```
- Start `herdr` in your project directory, then run `pi` in its pane. Try:
- ```text
- 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 Pi Herdsman gives you
- - **Background Agents.** Delegate bounded work without blocking your conversation.
- - **Parallel and nested delegation.** Run independent work concurrently; permitted Agents can delegate their own subtasks.
- - **Project orchestration.** A Manager coordinates durable, branch-based work across independent Leads.
- - **Explicit authority.** Chief, Manager, Lead, and Agent responsibilities have distinct supervision and ownership boundaries.
- - **Peer communication.** Eligible sessions can exchange messages locally and, where supported, across connected machines.
- - **Usage visibility.** Inspect Pi-native token and cost records for owned Agents and, for an active Manager, assigned Leads.
- - **Your tools, your workflow.** Bring your own Agent definitions, Coordinator profiles, models, tools, skills, extensions, and development process.
- ## From one Agent to a project
- A normal Pi session is a **Lead**. It can own Agents, including permitted
- nested Agents:
- ```text
- You ↔ Lead
- ├─ Agent
- │ └─ Agent
- └─ Agent
- ```
- For independent project work, an eligible Lead can enter **Manager** mode.
- The Manager assigns branch-based objectives to Leads, which direct their own
- Agent trees:
- ```text
- You ↔ Manager
- ├─ Lead → Agents
- └─ Lead → Agents
- ```
- An optional **Chief** supervises Managers and eligible ordinary Leads without
- an active project Manager. These roles define authority, not a mandatory task
- sequence. Project assignments remain durable across Manager turnover.
- See [Coordination](docs/concepts/coordination.md) for role boundaries and
- [Project orchestration](docs/guides/project-orchestration.md) for assignments,
- recovery, and integration.
- ## Project status & roadmap
- Pi Herdsman is pre-1.0. These capabilities are available today:
- - **Lead & Agent orchestration.** Background and nested delegation, result handoffs, and local peer communication.
- - **Manager orchestration.** Branch-based work assignments, supervision, pause/resume, and authorized local integration.
- - **Chief supervision.** Supervises current Managers and eligible ordinary Leads within one herdr runtime.
- - **Federated peer messaging.** Eligible Managers and ordinary Leads can communicate across connected machines, with durable replies.
- **Current federation limitations:** Independent discovery and initiation require
- an SSH route from the initiating machine; an existing correspondence allows
- replies without reverse SSH. Different Herdsman builds cannot yet exchange
- ordinary messages. See [Peer communication](docs/reference/peer.md).
- **Open proposals:** [bidirectional initiation over one-way connections (#790)](https://github.com/boadij/pi-herdsman/issues/790),
- [cross-build messaging (#688)](https://github.com/boadij/pi-herdsman/issues/688),
- and [portable repository runtime (#755)](https://github.com/boadij/pi-herdsman/issues/755).
- **Early-stage project:** Pre-1.0 releases may introduce breaking changes.
- See the [changelog](CHANGELOG.md) for release and migration guidance.
- ## Choose your next step
- Browse the [documentation index](docs/README.md), or jump to:
- - **Start:** [Getting started](docs/getting-started.md)
- - **Orchestrate:** [Project orchestration](docs/guides/project-orchestration.md) and [Coordination](docs/concepts/coordination.md)
- - **Customize:** [Agent definitions](docs/guides/agent-definitions.md)
- - **Integrate:** [Coordination API](docs/coordination-api.md) and [Peer communication](docs/reference/peer.md)
- - **Contribute:** [Contributing](CONTRIBUTING.md)
- ## Community
- Questions, workflows, examples, and ideas are welcome in
- [GitHub Discussions](https://github.com/boadij/pi-herdsman/discussions).
- For reproducible bugs and concrete actionable work, use
- [GitHub Issues](https://github.com/boadij/pi-herdsman/issues).
- Thanks to everyone who improves Pi Herdsman through code, reports, and
- investigations. See [Community contributors](CONTRIBUTORS.md) for acknowledgments.
- ## License
- [Apache License 2.0](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.