# Shepherd Concept Dictionary

- **Shepherd**: The main orchestrator agent. The main pi session running the pi-shepherd extension. The shepherd is responsible for managing the lifecycle of his herd of sheep.
- **Sheep**: Are agents created by the shepherd. Also called a subagent in other contexts. Sheep are the workers that perform tasks assigned by the shepherd. Each with a unique role defined by their markdown file.
- **Herd**: The collection of sheep managed by the shepherd. The herd can consist of multiple sheep, each with their own unique role and responsibilities. A herd is tied to the shepherd's pi session.
- **Fieldnotes**: A collection of notes tied to the session. in other frameworks this are sometimes called artifacts.
- **Note**: A single note in the fieldnotes. Each note belongs to a specific sheep or shepherd. Notes are used to by its owner to track and convey information about their work, progress, and observations. The Shepherd´s notes are used to track the overall progress of the herd and to provide guidance and feedback to future sheep. Notes can be created, updated, and deleted by their owner. Notes can be shared with other sheep or the shepherd for collaboration and feedback.
- **Sheep's note**: A note created by a sheep to track its work, observations, and progress, and to provide information for the shepherd and other sheep.
- **Shepherd's note**: A note created by the shepherd to track the overall progress of the herd and to provide guidance, feedback, and a map to all present and future sheep.
- **Session**: A session is tied to the shepherd's pi session and is used to track the state of the herd and its sheep.
- **Control-plane tool**: The model-facing `shepherd` tool. It handles cheap meta-actions: `agents`, `herd`, and `prune`, and serves as the guidance hub for the Shepherd tool family.
- **Lifecycle tools**: The separate model-facing tools `shepherd_spawn`, `shepherd_delegate`, `shepherd_message`, `shepherd_watch`, `shepherd_status`, `shepherd_close`, and `shepherd_read`, plus the deprecated `shepherd_prompt`. Each has a flat object schema and delegates to the shared `doAction()` core.
- **Model-facing surface**: The structured `shepherd` control tool plus the six `shepherd_<verb>` lifecycle tools. Lifecycle tools accept opaque scalar ids; the provider may wrap their argument object in its own transport envelope.
- **Command surface**: The human `/shepherd` command. It supports `agents`, `herd`, `spawn`, `status`, `read`, and `settings`; prompt/close remain model-only for now.
- **Agent id**: An opaque, session-scoped id returned by `shepherd_spawn` that identifies an owned agent. It is distinct from any Herdr pane id and is accepted by `shepherd_prompt`, `shepherd_status`, and `shepherd_close`.
- **Prompt id**: An opaque, session-scoped id returned by the deprecated `shepherd_prompt` that identifies one submitted child turn. It is accepted by `shepherd_watch` on the legacy path.
- **Task**: The tracked unit of delegated work. A task has a state (`created`, `running`, `waiting`, `completed`, `blocked`, `failed`, `cancelled`, `timed_out`) that is independent of the Herdr process state. Only `shepherd_done` or an explicit failure/cancel/timeout settles a task; an idle or ended child process never does.
- **Task id**: An opaque, session-scoped id returned by `shepherd_delegate`. It is the correlation key for task watchers, tracked replies, and `shepherd_done`.
- **Message**: An asynchronous, parent-mediated envelope between Shepherd and owned agents (or between agents in a shared project). A message is not a task and does not allocate a fieldnote on its own.
- **Message id**: An opaque, session-scoped id returned when a message is accepted. The agent answering a tracked request echoes it as `replyTo` so the reply correlates with the request.
- **Tracked reply request**: The state opened when a message with `expectsReply` is delivered to a task-owned agent. The sender's task enters `waiting` until a matching reply, a `shepherd_done`, close, or the reply deadline (which settles the task to `blocked`).
- **Waiting task (idle child)**: A task in `waiting` whose Herdr process is `idle` because its pi turn ended. Status and the TUI widget keep it visible, render the elapsed wait and the expected recipient, and flag it `stale` after a stale-wait reminder.
- **Stale-wait reminder**: An informational-only follow-up (no turn trigger) sent at most once per waiting episode after `staleWaitThreshold` minutes with no reply. It never settles the task; the reply deadline remains the only settlement path.
- **`followUp` / `steer` delivery**: `followUp` queues a message for the next child turn (default); `steer` injects it as urgent input into the agent's active turn.
- **Internal AgentHandle/PromptHandle/TaskHandle**: Full objects retained inside the lifecycle registry and TypeScript implementation. They are not part of the recommended model-facing protocol.
- **Parent broker**: The in-parent message channel that routes envelopes between the Shepherd and owned agents, delivers follow-ups, and enforces provenance. It is parent-scoped: children receive a child capability and can only talk through the broker.