@luminascale/shepherd 0.0.0-stage → 0.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/agents/README.md +12 -0
- package/.agents/agents/planner.md +38 -0
- package/.agents/agents/reviewer.md +38 -0
- package/.agents/agents/scout.md +43 -0
- package/.agents/agents/worker.md +33 -0
- package/.agents/skills/smoke-test/SKILL.md +155 -0
- package/.agents/skills/smoke-test/references/forensics.md +46 -0
- package/.agents/skills/smoke-test/scripts/live-smoke-poll.mjs +130 -0
- package/.github/workflows/publish.yml +77 -0
- package/.pi/prompts/release.md +21 -0
- package/.prettierrc +10 -0
- package/AGENTS.md +88 -0
- package/CONTRIBUTING.md +177 -0
- package/LICENSE +201 -0
- package/README.md +397 -2
- package/docs/README.md +26 -0
- package/docs/guides/agent-definitions.md +42 -0
- package/docs/guides/diagnostics.md +199 -0
- package/docs/guides/installation.md +61 -0
- package/docs/guides/tool-reference.md +55 -0
- package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
- package/docs/plans/agent-labels.md +257 -0
- package/docs/plans/architecture.md +110 -0
- package/docs/plans/settings-scope.md +163 -0
- package/docs/plans/tool-surface-split.md +278 -0
- package/docs/reference/dictionary +26 -0
- package/docs/releasing.md +47 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
- package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
- package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
- package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
- package/index.ts +602 -0
- package/package.json +112 -4
- package/scripts/capture-system-prompt.mjs +45 -0
- package/scripts/extract-pi-system-prompt.mjs +277 -0
- package/scripts/host-impact.mjs +74 -0
- package/scripts/resolve-agent.mjs +43 -0
- package/scripts/show-shepherd-orchestrator.mjs +58 -0
- package/scripts/show-shepherd-prompt.mjs +96 -0
- package/scripts/verify-suites.mjs +67 -0
- package/specs/001-artifacts/spec.md +436 -0
- package/specs/002-simplify-agent-orchestration/plan.md +287 -0
- package/specs/002-simplify-agent-orchestration/spec.md +323 -0
- package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
- package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
- package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
- package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
- package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
- package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
- package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
- package/specs/005-per-workspace-settings/plan.md +230 -0
- package/specs/005-per-workspace-settings/spec.md +368 -0
- package/specs/005-per-workspace-settings/tasks.md +178 -0
- package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
- package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
- package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
- package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
- package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
- package/specs/007-unwatched-completion-notice/journal.md +145 -0
- package/specs/007-unwatched-completion-notice/plan.md +186 -0
- package/specs/007-unwatched-completion-notice/spec.md +284 -0
- package/specs/007-unwatched-completion-notice/tasks.md +147 -0
- package/specs/008-remote-machine-sheep/intent.md +174 -0
- package/specs/008-remote-machine-sheep/journal.md +57 -0
- package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
- package/specs/009-hc-runtime/intent.md +44 -0
- package/specs/009-hc-runtime/plan.md +49 -0
- package/specs/009-hc-runtime/spec.md +118 -0
- package/specs/009-hc-runtime/tasks.md +62 -0
- package/specs/010-unseen-watch-parity/intent.md +57 -0
- package/specs/010-unseen-watch-parity/journal.md +172 -0
- package/specs/010-unseen-watch-parity/plan.md +74 -0
- package/specs/010-unseen-watch-parity/spec.md +191 -0
- package/specs/010-unseen-watch-parity/tasks.md +119 -0
- package/specs/011-hc-background-poll/intent.md +57 -0
- package/specs/011-hc-background-poll/journal.md +95 -0
- package/specs/011-hc-background-poll/plan.md +87 -0
- package/specs/011-hc-background-poll/spec.md +141 -0
- package/specs/011-hc-background-poll/tasks.md +83 -0
- package/specs/012-steer-default/intent.md +12 -0
- package/specs/012-steer-default/journal.md +40 -0
- package/specs/012-steer-default/plan.md +7 -0
- package/specs/012-steer-default/spec.md +42 -0
- package/specs/012-steer-default/tasks.md +6 -0
- package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
- package/specs/013-opencode-shepherd/intent.md +59 -0
- package/specs/013-opencode-shepherd/plan.md +204 -0
- package/specs/013-opencode-shepherd/spec.md +258 -0
- package/specs/013-opencode-shepherd/tasks.md +263 -0
- package/src/core/artifact-sessions.ts +835 -0
- package/src/core/config.ts +329 -0
- package/src/core/discovery.ts +342 -0
- package/src/core/herdr.ts +1 -0
- package/src/core/host.ts +77 -0
- package/src/core/ids.ts +78 -0
- package/src/core/lifecycle.ts +1 -0
- package/src/core/messaging.ts +1 -0
- package/src/core/migration.ts +55 -0
- package/src/core/orchestration.ts +1 -0
- package/src/core/types.ts +143 -0
- package/src/core/unseen-completions.ts +114 -0
- package/src/extension/cli.ts +417 -0
- package/src/extension/config.ts +1 -0
- package/src/extension/settings-ui.ts +296 -0
- package/src/extension/shepherd-done.ts +768 -0
- package/src/extension/shepherd.ts +2548 -0
- package/src/extension/system-prompt.ts +38 -0
- package/src/extension/unseen-completions.ts +237 -0
- package/src/opencode/actions.ts +794 -0
- package/src/opencode/bridge.ts +777 -0
- package/src/opencode/display.ts +36 -0
- package/src/opencode/fieldnotes.ts +60 -0
- package/src/opencode/host.ts +62 -0
- package/src/opencode/orphans.ts +162 -0
- package/src/opencode/server.ts +458 -0
- package/src/runtimes/backend.ts +119 -0
- package/src/runtimes/detect.ts +102 -0
- package/src/runtimes/hc/hc.ts +527 -0
- package/src/runtimes/hc/runtime.ts +1898 -0
- package/src/runtimes/herdr/herdr.ts +912 -0
- package/src/runtimes/herdr/lifecycle.ts +1712 -0
- package/src/runtimes/herdr/messaging.ts +703 -0
- package/src/runtimes/herdr/orchestration.ts +1583 -0
- package/src/runtimes/herdr/runtime.ts +224 -0
- package/src/runtimes/runtime.ts +133 -0
- package/src/runtimes/settle-observations.ts +114 -0
- package/test/fixtures/context-project/AGENTS.md +2 -0
- package/test/fixtures/home/.agents/agents/same.md +6 -0
- package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
- package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
- package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
- package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
- package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
- package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
- package/test/fixtures/proj/.pi/agents/same.md +6 -0
- package/test/helpers/fake-clock.mjs +39 -0
- package/test/helpers/feature-contracts.mjs +44 -0
- package/test/helpers/test-utils.mjs +44 -0
- package/test/verify-artifact-sessions.mjs +258 -0
- package/test/verify-backend.mjs +297 -0
- package/test/verify-child-mislabel.mjs +135 -0
- package/test/verify-child-surface.mjs +321 -0
- package/test/verify-cli.mjs +197 -0
- package/test/verify-command-ux.mjs +100 -0
- package/test/verify-compat.mjs +32 -0
- package/test/verify-cross-host-notes.mjs +128 -0
- package/test/verify-delegate.mjs +161 -0
- package/test/verify-detect.mjs +151 -0
- package/test/verify-discovery.mjs +239 -0
- package/test/verify-done-nudge.mjs +238 -0
- package/test/verify-effective-prompt.mjs +98 -0
- package/test/verify-hc-matrix.mjs +246 -0
- package/test/verify-hc-poll.mjs +260 -0
- package/test/verify-host-docs.mjs +66 -0
- package/test/verify-host-impact.mjs +49 -0
- package/test/verify-ids.mjs +141 -0
- package/test/verify-launch.mjs +183 -0
- package/test/verify-message-routing.mjs +560 -0
- package/test/verify-messaging.mjs +303 -0
- package/test/verify-migration-notice.mjs +74 -0
- package/test/verify-multi-wait.mjs +42 -0
- package/test/verify-opencode-display.mjs +47 -0
- package/test/verify-opencode-fieldnotes.mjs +121 -0
- package/test/verify-opencode-notice.mjs +77 -0
- package/test/verify-opencode-nudge.mjs +116 -0
- package/test/verify-opencode-orphans.mjs +160 -0
- package/test/verify-opencode-surface.mjs +107 -0
- package/test/verify-packaging.mjs +82 -0
- package/test/verify-parent-surface.mjs +118 -0
- package/test/verify-phase0.mjs +95 -0
- package/test/verify-registry.mjs +124 -0
- package/test/verify-rename-migration.mjs +111 -0
- package/test/verify-rendering.mjs +379 -0
- package/test/verify-session-boundary.mjs +146 -0
- package/test/verify-settings.mjs +260 -0
- package/test/verify-stale-wait.mjs +339 -0
- package/test/verify-status-widget.mjs +377 -0
- package/test/verify-status.mjs +172 -0
- package/test/verify-task-completion.mjs +156 -0
- package/test/verify-task-failures.mjs +201 -0
- package/test/verify-task-mislabel.mjs +143 -0
- package/test/verify-task-registry.mjs +194 -0
- package/test/verify-task-watchers.mjs +217 -0
- package/test/verify-tool-schemas.mjs +120 -0
- package/test/verify-unseen-completions.mjs +1211 -0
- package/test/verify-watchers.mjs +181 -0
package/README.md
CHANGED
|
@@ -1,3 +1,398 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<strong>SHEPHERD</strong><br />
|
|
3
|
+
<em>Native Herdr agent orchestration for Pi and OpenCode</em>
|
|
4
|
+
</p>
|
|
2
5
|
|
|
3
|
-
|
|
6
|
+
<p align="center">
|
|
7
|
+
<a href="#install">Install</a> · <a href="#key-features">Features</a> · <a href="#available-tools">Tools</a> · <a href="#settings">Settings</a> · <a href="#fieldnotes">Fieldnotes</a>
|
|
8
|
+
</p>
|
|
9
|
+
|
|
10
|
+
<p align="center">
|
|
11
|
+
<a href="LICENSE"><img src="https://img.shields.io/npm/l/%40luminascale%2Fshepherd" alt="Apache-2.0 license" /></a>
|
|
12
|
+
<a href="https://github.com/MikkelKappelPersson/shepherd/stargazers"><img src="https://img.shields.io/github/stars/MikkelKappelPersson/shepherd?logo=github" alt="GitHub stars" /></a>
|
|
13
|
+
<a href="https://github.com/MikkelKappelPersson/shepherd/releases/latest"><img src="https://img.shields.io/github/v/release/MikkelKappelPersson/shepherd?label=release" alt="latest stable release" /></a>
|
|
14
|
+
<a href="https://www.npmjs.com/package/@luminascale/shepherd"><img src="https://img.shields.io/npm/v/%40luminascale%2Fshepherd?label=npm&logo=npm" alt="npm version" /></a>
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
Shepherd is a no-fuss extension for native, low-level Herdr agent orchestration. The **Shepherd**—your main session can launch and coordinate specialized agents in visible Herdr panes, while shared session fieldnotes (artifacts) let agents share context across delegated work.
|
|
18
|
+
|
|
19
|
+
## Install
|
|
20
|
+
|
|
21
|
+
| Harness | Installation | Quick install | Verify after restart |
|
|
22
|
+
| --- | --- | --- | --- |
|
|
23
|
+
| Pi | [Pi setup guide](docs/guides/installation.md#pi) | `pi install npm:@luminascale/shepherd` | `/shepherd agents` |
|
|
24
|
+
| OpenCode | [OpenCode setup guide](docs/guides/installation.md#opencode) | add `@luminascale/shepherd` to `plugins` in `opencode.json` | `/shepherd agents` |
|
|
25
|
+
|
|
26
|
+
The tools, opaque ids, agent definitions, and fieldnotes layout are shared across both hosts.
|
|
27
|
+
|
|
28
|
+
## Key Features
|
|
29
|
+
|
|
30
|
+
- **Native, no-fuss, low-level Herdr agent orchestration** — Shepherd uses native Herdr panes for all agents and simple, open primitives for agent orchestration. Everything is visible and inspectable. Shepherd does not impose a workflow; it gives you the tools to build your own.
|
|
31
|
+
- **Herdr and hc support** — run inside the [Herdr](https://github.com/herdrdev/herdr) TUI or an [hc](https://github.com/herdrdev/herdr-core) terminal in [herdr-app](https://github.com/herdrdev/herdr-app); launched agents stay visible and inspectable in their panes or terminals. `backend: auto` runs where you called from, or pin `herdr` / `hc`.
|
|
32
|
+
- **Granular system-prompt and agent-context support** — Shepherd goes beyond standard definitions and utilises pi's open system-prompt. Shepherd agents can be defined with granular control over context for very specific and narrow agent and context control.
|
|
33
|
+
- **Manual agent launch** — start an interactive specialist directly with `/shepherd spawn` and chat with it in its own host session.
|
|
34
|
+
- **Shared session fieldnotes (artifacts)** — give agents a durable shared place to leave notes and share context across delegated work, on the same layout in both hosts.
|
|
35
|
+
|
|
36
|
+
## Requirements
|
|
37
|
+
|
|
38
|
+
- [Pi](https://github.com/earendil-works/pi) **or** [OpenCode](https://opencode.ai) (see [Install](#install))
|
|
39
|
+
- [Herdr](https://github.com/herdrdev/herdr) (TUI panes) **or** [herdr-app](https://github.com/herdrdev/herdr-app) / [herdr-core](https://github.com/herdrdev/herdr-core) (desktop-app terminals)
|
|
40
|
+
- Node.js 22 or newer
|
|
41
|
+
|
|
42
|
+
## Available tools
|
|
43
|
+
|
|
44
|
+
pi-shepherd exposes these tools to the Shepherd. You can use them explicitly when you need precise control, but ordinary natural-language requests are the recommended starting point:
|
|
45
|
+
|
|
46
|
+
| Tool | Purpose |
|
|
47
|
+
| --- | --- |
|
|
48
|
+
| `shepherd` | List definitions (`agents`), list active agents (`herd`), or remove stale pane registrations (`prune`) |
|
|
49
|
+
| `shepherd_spawn` | Create an idle persistent agent |
|
|
50
|
+
| `shepherd_delegate` | Start a tracked task; returns immediately with a task ID |
|
|
51
|
+
| `shepherd_message` | Send an asynchronous message (parent or peer); `expectsReply` opens a tracked reply request |
|
|
52
|
+
| `shepherd_watch` | Receive task completion without blocking the current turn (task IDs preferred, legacy prompt IDs still work) |
|
|
53
|
+
| `shepherd_status` | Inspect an agent without focusing its pane; reports process and task state independently |
|
|
54
|
+
| `shepherd_close` | Close an owned agent, cancel its active task, and clear pending requests |
|
|
55
|
+
| `shepherd_read` | Read recent terminal output for diagnostics |
|
|
56
|
+
|
|
57
|
+
Child agents additionally see `shepherd_message` (talk to the parent or a peer) and `shepherd_done` (the only normal successful completion of their tracked task).
|
|
58
|
+
|
|
59
|
+
## Your first delegation
|
|
60
|
+
|
|
61
|
+
You do not need to call Shepherd’s tools yourself. After restarting pi, describe the work you want done in your normal conversation, or nudge the Shepherd to delegate it explicitly. Phrases such as “use Shepherd,” “ask the herd,” “ask a sheep,” “delegate this,” “orchestrate a review,” or “use a subagent” are all natural-language requests; no special syntax is required. For example:
|
|
62
|
+
|
|
63
|
+
> Ask a planner to create an implementation plan for adding authentication, including the relevant files and recommended steps.
|
|
64
|
+
|
|
65
|
+
The Shepherd starts the planner in a visible Herdr tab, gives it the task, collects its result, and reports back to you. This is the recommended one-shot workflow. Shepherd’s structured tools are still available when you need explicit lifecycle control, parallel work, or want to inspect what the Shepherd is doing; see [Placement and lifecycle](#placement-and-lifecycle) below.
|
|
66
|
+
|
|
67
|
+
### Work directly with a specialist agent
|
|
68
|
+
|
|
69
|
+
If you would rather work with a specialist directly, use the human command surface described in the [Command reference](#command-reference). Switch to the new Herdr tab to chat with the planner. Spawning creates an idle, persistent agent; it does not submit a task. Close interactive agents when you are finished so your Herdr session does not accumulate unnecessary panes.
|
|
70
|
+
|
|
71
|
+
## Common workflows
|
|
72
|
+
|
|
73
|
+
### Sequential work
|
|
74
|
+
|
|
75
|
+
Use sequential delegation when one agent’s result should inform the next agent’s task. Describe the handoff in your request:
|
|
76
|
+
|
|
77
|
+
> Ask a planner to create an implementation plan for adding authentication. Once it has finished, give its plan to a worker and ask the worker to implement the feature. Return the implementation result when it is complete.
|
|
78
|
+
|
|
79
|
+
The Shepherd waits for the planner before starting the worker and passes the planner’s result along as context. This is useful for plan-then-implement, research-then-review, or any workflow with a clear handoff.
|
|
80
|
+
|
|
81
|
+
### Parallel work
|
|
82
|
+
|
|
83
|
+
Use parallel delegation when tasks are independent. Ask the Shepherd to delegate them together:
|
|
84
|
+
|
|
85
|
+
> Ask two scouts to work in parallel: have one research how authentication is implemented and the other research authorization. Wait for both results, then summarize the findings and explain any relevant connections.
|
|
86
|
+
|
|
87
|
+
The Shepherd runs the independent tasks concurrently and combines their results. This is useful for comparing approaches, investigating separate parts of a codebase, or getting multiple reviews of the same change.
|
|
88
|
+
|
|
89
|
+
### Delegate, then watch
|
|
90
|
+
|
|
91
|
+
The tracked-task workflow is: spawn, delegate, watch, close. `shepherd_delegate` starts the work and returns immediately with a **task ID**; nothing is settled until the child calls `shepherd_done` (or the task fails, is cancelled, or times out).
|
|
92
|
+
|
|
93
|
+
```text
|
|
94
|
+
shepherd_spawn({ agent: "worker", label: "auth" })
|
|
95
|
+
shepherd_delegate({ target: "<agent ID>", task: "Implement the auth middleware from the plan." })
|
|
96
|
+
shepherd_watch({ id: "<task ID>" })
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
When the task settles, the watcher delivers a completion notification containing the result. Delivery uses pi's steer mode: if the Shepherd is mid-turn, the notification is injected between tool rounds (before cleanup calls such as `shepherd_close`); if the Shepherd is idle, it triggers a new turn immediately. Watchers finish automatically after all their tasks settle; they do not close agents. Use `shepherd_watch` for non-blocking completion notifications and `shepherd_status` to inspect intermediate task state.
|
|
100
|
+
|
|
101
|
+
Watching is optional, but completion is never silent: a tracked task that settles while no watcher is attached produces one notice. When the Shepherd is mid-turn, the notice is appended at the next settle boundary (one extra model request, never a mid-turn interruption); when the Shepherd is idle, it arrives as a single coalesced wake covering the whole batch. The notice names the settled tasks and the `shepherd_watch({ id: [ … ] })` call that retrieves their full results. It never claims a result is lost — a watcher registered after settlement still receives the result synchronously. `shepherd_watch` on a settled task clears its pending notice, and `shepherd_close` reports any notices it drops for that agent. The notice holds on both backends: an hc terminal settle produces the same wording as a Herdr pane settle (only the opaque task/agent ids differ). On hc, a 250 ms background poll settles queued completions even with no watcher and no messages, and `shepherd_watch` / `shepherd_status` drain first so they never report stale pending/running for an already-settled task.
|
|
102
|
+
|
|
103
|
+
### Forgotten completion nudges
|
|
104
|
+
|
|
105
|
+
If a child ends its turn while its tracked task is still open — the common slip being finished work with no `shepherd_done` — the child extension notices at that exact boundary and feeds itself one reminder turn asking for a terminal `shepherd_done`. The nudge is deliberately narrow: it only fires for a tracked task the child still holds, never after an aborted or errored turn, and never while a tracked request (`expectsReply`) is outstanding, because ending the turn is how a child waits for an answer.
|
|
106
|
+
|
|
107
|
+
The reminder budget is one turn per task by default (`PI_SHEPHERD_DONE_NUDGES`, `0` disables it). If the task is still open afterwards, the child reports the stall to the parent as a normal Shepherd message instead of inventing a status — the parent then blocks, cancels, or waits for the task deadline. Legacy `shepherd_prompt` runs are unaffected: they settle through the completion sidecar at turn end.
|
|
108
|
+
|
|
109
|
+
### Messaging between agents
|
|
110
|
+
|
|
111
|
+
Agents in the same project can message each other through the parent broker. The child's `shepherd_message` tool can target `parent` or an owned agent ID. A peer question that requires an answer is sent with `expectsReply: true`:
|
|
112
|
+
|
|
113
|
+
```text
|
|
114
|
+
shepherd_message({
|
|
115
|
+
target: "<planner agent ID>",
|
|
116
|
+
message: "Which retry backoff should the middleware use?",
|
|
117
|
+
taskId: "<own task ID>",
|
|
118
|
+
expectsReply: true
|
|
119
|
+
})
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
The angle-bracket values above are documentation placeholders only. At runtime,
|
|
123
|
+
copy the planner's exact `id` from `shepherd_spawn` into `target`; do not use
|
|
124
|
+
`planner`, a display label, or a Herdr pane ID. Invalid targets are rejected.
|
|
125
|
+
|
|
126
|
+
While the answer is outstanding, the sender's task is `waiting` — even though its pi process is `idle` and the child's turn has ended. The reply (correlated by `replyTo`) returns the task to `running`; a `shepherd_done`, cancellation, or the reply deadline settle it. Delivery modes: `followUp` (default) queues the message for the recipient's next turn; `steer` injects it urgently into an active turn. Child requests (`expectsReply: true`) and replies wake the parent at the next safe boundary (between tool rounds when the Shepherd is mid-turn, immediately when it is idle); ordinary informational messages remain passive. A wake-up never interrupts an active tool call.
|
|
127
|
+
|
|
128
|
+
### Continue working while an agent runs
|
|
129
|
+
|
|
130
|
+
`shepherd_watch({ id: prompt.id })` is also non-blocking for the legacy prompt path; completion arrives as a steered notification.
|
|
131
|
+
|
|
132
|
+
### Compatibility
|
|
133
|
+
|
|
134
|
+
`shepherd_prompt` is a **deprecated** one-turn compatibility path: each prompt still completes at the end of that child turn (that semantics is unchanged and documented, not silently altered). Use `shepherd_delegate` instead for any work that may need to answer or receive a reply. `shepherd_watch` accepts task IDs (`shepherd_delegate`) and legacy prompt IDs (`shepherd_prompt`) and returns immediately; completions arrive as steered notifications. Use `shepherd_status` to inspect running or waiting tasks.
|
|
135
|
+
|
|
136
|
+
## Agent definitions
|
|
137
|
+
|
|
138
|
+
Agent definitions are Markdown files, so you can tune an agent’s behavior with granular system-prompt engineering. Define its role, workflow, tools, model, and prompt options in YAML frontmatter and the Markdown body. The supported frontmatter fields are:
|
|
139
|
+
|
|
140
|
+
| Field | Values | Default | Description |
|
|
141
|
+
| --- | --- | --- | --- |
|
|
142
|
+
| **`name`** | String | — | The agent’s name. **Required.** |
|
|
143
|
+
| **`description`** | String | — | A short description shown during discovery. **Required.** |
|
|
144
|
+
| **`tools`** | Comma-separated string or YAML list | pi’s default tools | Tools available to the agent. |
|
|
145
|
+
| **`model`** | Provider-qualified model, `null`, or `default` | Shepherd’s model | Select the model, for example `anthropic/claude-sonnet-4-5`. `null`, `default`, or omission inherits the Shepherd’s model. |
|
|
146
|
+
| **`thinking`** | `default`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` | Shepherd’s level | Select the requested Pi thinking level. `null`, `default`, empty, or omission inherits the Shepherd’s current level. Unsupported levels are clamped by Pi to the child model’s capabilities. |
|
|
147
|
+
| **`omit-system-prompt`** | `true`, `false` | `false` | Omit pi’s built-in system prompt when `true`. |
|
|
148
|
+
| **`omit-pi-documentation`** | `true`, `false` | `false` | Omit pi’s built-in documentation guidance when `true`. |
|
|
149
|
+
| **`omit-context-files`** | `true`, `false` | `false` | Omit automatic `AGENTS.md` and `CLAUDE.md` context-file loading when `true`. |
|
|
150
|
+
| **`user-invocable`** | `true`, `false` | `true` | Indicate whether the agent is intended to be directly invoked by a user. |
|
|
151
|
+
|
|
152
|
+
For example:
|
|
153
|
+
|
|
154
|
+
```markdown
|
|
155
|
+
---
|
|
156
|
+
name: tester
|
|
157
|
+
description: Runs and evaluates GUI tests
|
|
158
|
+
tools: read, grep, find
|
|
159
|
+
model: anthropic/claude-sonnet-4-5
|
|
160
|
+
thinking: high
|
|
161
|
+
omit-system-prompt: false
|
|
162
|
+
omit-pi-documentation: true
|
|
163
|
+
omit-context-files: true
|
|
164
|
+
user-invocable: true
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
You are a focused GUI testing specialist. Report reproducible failures
|
|
168
|
+
with exact steps and useful evidence.
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
`thinking` is a requested level. Pi clamps it to a level supported by the
|
|
172
|
+
child model, so `xhigh` may become `high`, and a model that cannot
|
|
173
|
+
disable reasoning may not honor `off`. `none` is invalid; use `off` for an
|
|
174
|
+
explicit no-reasoning request. Invalid `thinking` or `model` values cause that definition to be skipped during discovery rather than preventing other agents from loading.
|
|
175
|
+
|
|
176
|
+
### Bundled definitions and discovery
|
|
177
|
+
|
|
178
|
+
The bundled agent definitions are:
|
|
179
|
+
|
|
180
|
+
- `scout` — fast codebase investigation
|
|
181
|
+
- `planner` — planning and decomposition
|
|
182
|
+
- `worker` — implementation work
|
|
183
|
+
- `reviewer` — review and verification
|
|
184
|
+
|
|
185
|
+
User and project definitions can add or override these names. Discovery precedence is:
|
|
186
|
+
|
|
187
|
+
1. `~/.pi/agent/agents/`
|
|
188
|
+
2. `~/.agents/agents/`
|
|
189
|
+
3. nearest project `.pi/agents/`
|
|
190
|
+
4. nearest project `.agents/agents/`
|
|
191
|
+
5. bundled `.pi/agents/`
|
|
192
|
+
6. bundled `.agents/agents/`
|
|
193
|
+
|
|
194
|
+
Discovery defaults to `both` scope, so repository-controlled definitions are listed alongside user definitions. The confirmation gate (`confirmProjectAgents`) is user-owned and off by default; enable it in `/shepherd settings` when working in untrusted repositories — a project file can never change it. The bundled definitions can be disabled from settings. Agents retain the host user’s normal pi tool permissions.
|
|
195
|
+
|
|
196
|
+
## Placement and lifecycle
|
|
197
|
+
|
|
198
|
+
By default, `shepherd_spawn` creates a background Herdr tab. You can request a pane or workspace placement:
|
|
199
|
+
|
|
200
|
+
```text
|
|
201
|
+
shepherd_spawn({
|
|
202
|
+
agent: "worker",
|
|
203
|
+
label: "implementation",
|
|
204
|
+
placement: "pane_right", // pane_right, pane_down, tab, or workspace
|
|
205
|
+
})
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
The working directory defaults to the Shepherd session and `cwd` can be supplied when spawning. The child model and requested thinking level come from the discovered agent definition; omission, `null`, or `default` inherits the Shepherd session's corresponding setting. Agent scope, project approval, and prompt-shaping options come from Shepherd settings and the discovered definition; they are not spawn overrides.
|
|
209
|
+
|
|
210
|
+
Lifecycle tools use short, opaque, session-scoped IDs:
|
|
211
|
+
|
|
212
|
+
```text
|
|
213
|
+
shepherd_spawn -> agent ID (for delegate, message, status, close)
|
|
214
|
+
shepherd_delegate -> task ID (for watch, wait, message taskId, shepherd_done)
|
|
215
|
+
shepherd_message -> message ID (answer it with replyTo)
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Task IDs identify the unit of work; message IDs identify individual envelopes and only matter when correlating a reply (the answering participant sets the request's message ID as `replyTo`). When the Shepherd answers a child-originated request, the parent resolves its own pending request as soon as that reply is queued, so the child does not need to send a redundant acknowledgment before calling `shepherd_done`. Do not substitute a Herdr pane ID for any of these. Pane IDs are only diagnostic targets for `shepherd_read`.
|
|
219
|
+
|
|
220
|
+
## Command reference
|
|
221
|
+
|
|
222
|
+
The slash command is useful when you want to manage an agent directly rather than ask the Shepherd to orchestrate a task:
|
|
223
|
+
|
|
224
|
+
```text
|
|
225
|
+
/shepherd agents # list available definitions
|
|
226
|
+
/shepherd agents both # include project definitions
|
|
227
|
+
/shepherd herd # list active agents
|
|
228
|
+
/shepherd spawn worker # spawn an interactive agent
|
|
229
|
+
/shepherd status worker # inspect an agent
|
|
230
|
+
/shepherd read worker --lines=20
|
|
231
|
+
/shepherd settings
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Supported actions are `agents`, `herd`, `prune`, `spawn`, `status`, `read`, and `settings`. `/shepherd list` remains a compatibility alias for `/shepherd agents`. Optional spawn flags include: `--placement pane_right|pane_down|tab|workspace` and `--cwd <path>`.
|
|
235
|
+
|
|
236
|
+
For one-shot delegation, prompting, waiting, parallel work, and opaque-ID lifecycle control, use the structured `shepherd_*` tools instead of manual commands. The old single-tool form such as `shepherd({ action: "prompt", ... })` is no longer supported.
|
|
237
|
+
|
|
238
|
+
## Settings
|
|
239
|
+
|
|
240
|
+
Open `/shepherd` or `/shepherd settings` to configure pi-shepherd. The menu
|
|
241
|
+
shows the effective values for the current workspace; use the arrow keys and
|
|
242
|
+
Enter to cycle values, `/` to fuzzy-search, and `Esc` to close it.
|
|
243
|
+
|
|
244
|
+
| Option | Values | Default | Description |
|
|
245
|
+
| --- | --- | --- | --- |
|
|
246
|
+
| **Settings scope** (`projectScope`) | `user`, `project` | `user` | Select the settings source for this workspace. A dormant project file is shown as `user (project file dormant)`. |
|
|
247
|
+
| **Agent scope** (`agentScope`) | `user`, `project`, `both` | `both` | Select which agent definition directories are searched. Project agents are repository-controlled; choose `user` to ignore them entirely. |
|
|
248
|
+
| **Include bundled agents** (`includeBundledAgents`) | on, off | on | Include the built-in `scout`, `planner`, `worker`, and `reviewer` definitions in discovery. |
|
|
249
|
+
| **Confirm project agents** (`confirmProjectAgents`) | on, off | off | User-only security gate for project-local agent definitions. A project config cannot change it. Enable it when working in untrusted repositories. |
|
|
250
|
+
| **Keep tab open after done** (`keepOpen`) | on, off | on | Leave the Herdr tab open after an agent completes so its output can be inspected. |
|
|
251
|
+
| **Keep agent alive after done** (`stayOpen`) | on, off | on | Keep the agent's pi process alive after completion so you can continue driving it in its tab. |
|
|
252
|
+
| **Enable fieldnotes** (`fieldnotes`) | on, off | on | Create durable shared session notes for delegated prompts. Changes take effect when the next pi session starts. |
|
|
253
|
+
| **Use sheep emoji** (`emojiSheep`) | on, off | on | Show the animated `🐑` marker beside actively working agents; off uses a plain marker instead. |
|
|
254
|
+
| **Default run timeout** (`timeout`) | `1`, `2`, `5`, `10`, `20`, `30`, or `60` minutes | `60` minutes | Set the default time limit before a Herdr run is reported as timed out. |
|
|
255
|
+
| **Stale wait reminder** (`staleWaitThreshold`) | `off`, `1`, `2`, `5`, `10`, `15`, or `30` minutes | `30` minutes | A task waiting longer than this on a required reply raises one stale-wait reminder. `off` disables reminders; reminders never cancel or block the task. |
|
|
256
|
+
| **Execution backend** (`backend`) | `auto`, `herdr`, `hc` | `auto` | Run where called from — Herdr TUI or hc app. A pin that can't be reached fails cleanly with a setup hint, never a silent fallback. App-side only; the model never decides. |
|
|
257
|
+
|
|
258
|
+
The user layer is stored in `pi-shepherd/config.json` inside the active pi
|
|
259
|
+
agent directory (`~/.pi/agent` by default, or `PI_CODING_AGENT_DIR`). It stores
|
|
260
|
+
personal values only. The project layer is `.shepherd/config.json` in the
|
|
261
|
+
current working directory, with no walk-up. A project file is active only when
|
|
262
|
+
it contains `"projectScope": true`; when active, it is self-contained and
|
|
263
|
+
missing project-owned fields fall back to built-in defaults rather than private
|
|
264
|
+
user values. A project file with `projectScope: false` or no flag is dormant.
|
|
265
|
+
|
|
266
|
+
`confirmProjectAgents` is intentionally user-owned. A committed project file
|
|
267
|
+
may select repository-controlled agent definitions through `agentScope`, but it
|
|
268
|
+
cannot change the confirmation gate in either direction. The gate is off by
|
|
269
|
+
default; a user who wants an approval prompt before a project-local agent runs
|
|
270
|
+
must enable it in the user layer.
|
|
271
|
+
|
|
272
|
+
For example:
|
|
273
|
+
|
|
274
|
+
```jsonc
|
|
275
|
+
// ~/.pi/agent/pi-shepherd/config.json — personal values
|
|
276
|
+
{
|
|
277
|
+
"agentScope": "both",
|
|
278
|
+
"includeBundledAgents": true,
|
|
279
|
+
"confirmProjectAgents": false,
|
|
280
|
+
"keepOpen": true,
|
|
281
|
+
"stayOpen": true,
|
|
282
|
+
"fieldnotes": true,
|
|
283
|
+
"emojiSheep": true,
|
|
284
|
+
"timeout": 60,
|
|
285
|
+
"staleWaitThreshold": 30
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
// .shepherd/config.json — optional, self-contained project values
|
|
289
|
+
{
|
|
290
|
+
"agentScope": "project",
|
|
291
|
+
"includeBundledAgents": true,
|
|
292
|
+
"keepOpen": true,
|
|
293
|
+
"stayOpen": false,
|
|
294
|
+
"fieldnotes": true,
|
|
295
|
+
"emojiSheep": true,
|
|
296
|
+
"timeout": 30,
|
|
297
|
+
"staleWaitThreshold": 5,
|
|
298
|
+
"projectScope": true
|
|
299
|
+
}
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
Project settings are intended to be optionally committed. Since `.shepherd/`
|
|
303
|
+
also contains runtime fieldnote sessions, use this pattern when sharing only
|
|
304
|
+
the config:
|
|
305
|
+
|
|
306
|
+
```gitignore
|
|
307
|
+
.shepherd/*
|
|
308
|
+
!.shepherd/config.json
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
When a delegated task is **waiting** on a required reply (set with
|
|
312
|
+
`shepherd_message` + `expectsReply`, or set by the child asking another
|
|
313
|
+
participant), it can sit there for a while if the target is busy.
|
|
314
|
+
`staleWaitThreshold` controls how long a task may wait before the parent
|
|
315
|
+
receives a **single** stale-wait reminder naming the task, the question, the
|
|
316
|
+
target, and how long it has been waiting. The reminder is informational: it
|
|
317
|
+
never cancels, times out, or blocks the task. The task's own reply deadline
|
|
318
|
+
(`timeout`) remains the authoritative bound and settles the task as `blocked`
|
|
319
|
+
if the reply never comes. A reply (or the task resuming/completing) clears the
|
|
320
|
+
episode, so the same wait never re-notifies while open.
|
|
321
|
+
|
|
322
|
+
## Diagnostic tools
|
|
323
|
+
|
|
324
|
+
These commands are primarily useful for contributors and local development checkouts. Use the diagnostic extractor when you need to see the fully assembled prompt that pi will give the Shepherd or a discovered agent:
|
|
325
|
+
|
|
326
|
+
```bash
|
|
327
|
+
npm run extract:system-prompt -- shepherd
|
|
328
|
+
npm run extract:system-prompt -- agent scout --scope both --cwd /path/to/project
|
|
329
|
+
npm run extract:system-prompt -- agent scout --output /tmp/scout-system.md
|
|
330
|
+
npm run extract:system-prompt -- shepherd --json
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
This captures the prompt at pi’s `before_agent_start` hook without making a provider request. For the full prompt-composition workflow and troubleshooting, see the [Diagnostics guide](docs/diagnostics.md).
|
|
334
|
+
|
|
335
|
+
### Inspect active agents
|
|
336
|
+
|
|
337
|
+
```text
|
|
338
|
+
/shepherd herd
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
The command lists all active agents currently detected in Herdr. For one agent, use `/shepherd status` or `/shepherd read`.
|
|
342
|
+
|
|
343
|
+
### Reading status
|
|
344
|
+
|
|
345
|
+
`shepherd_status` reports **process state and task state independently**. A process can be `idle` while its delegated task is still `waiting` on a required reply, and one can be `working` while its task is `running`. When an agent owns an open task the status also includes the task ID, how long it has been `waiting`, the pending request (message) ID, the agent the reply is expected from, and a `stale` flag once a stale-wait reminder has fired.
|
|
346
|
+
|
|
347
|
+
The persistent "below the editor" widget tracks the same two dimensions: it lists agents that are `working` **or** that are idle-but-`waiting` on a required reply (so an idle child parked on a peer reply is never hidden as done). Waiting rows render distinctly, show how long the wait has lasted, and name the agent being waited on; a `stale` wait is flagged. Pane and task IDs never leak into the display — rows use only display names.
|
|
348
|
+
|
|
349
|
+
## Fieldnotes
|
|
350
|
+
|
|
351
|
+
When fieldnotes are enabled, all agents orchestrated by one Shepherd session in the same project share a durable note session:
|
|
352
|
+
|
|
353
|
+
```text
|
|
354
|
+
.shepherd/sessions/NNNN-orchestrator-<id>/
|
|
355
|
+
├── session.json
|
|
356
|
+
├── shepherd.md
|
|
357
|
+
└── <agent>-NN.md
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
`shepherd.md` is the shared index, and each delegated prompt receives its own note. Notes are retained after waiting, closing, timeout, or extension restart; pi-shepherd does not automatically delete, archive, commit, or check them out. The fieldnotes setting is session-scoped, so start a new Shepherd session after changing it. Existing agents retain the current session’s behavior.
|
|
361
|
+
|
|
362
|
+
## Troubleshooting
|
|
363
|
+
|
|
364
|
+
### An agent is not responding
|
|
365
|
+
|
|
366
|
+
Inspect its state and terminal output:
|
|
367
|
+
|
|
368
|
+
```text
|
|
369
|
+
/shepherd status <agent>
|
|
370
|
+
/shepherd read <agent>
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
### There are too many Herdr panes
|
|
374
|
+
|
|
375
|
+
The slash command does not close lifecycle-managed agents. Use `shepherd_close` with the agent ID returned by `shepherd_spawn`:
|
|
376
|
+
|
|
377
|
+
```text
|
|
378
|
+
shepherd_close({ id: agent.id })
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
### There are stale pane registrations
|
|
382
|
+
|
|
383
|
+
Remove registrations for panes that no longer exist:
|
|
384
|
+
|
|
385
|
+
```text
|
|
386
|
+
/shepherd prune
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
## Herdr runtime and safety
|
|
390
|
+
|
|
391
|
+
pi-shepherd uses the `herdr` CLI and never uses an invisible subprocess fallback. It works inside Herdr or from a plain terminal by ensuring a headless Herdr server is available. Background tabs use `--no-focus`, preserve the requested working directory, and remain visible for inspection.
|
|
392
|
+
|
|
393
|
+
Only panes recorded in pi-shepherd’s created-pane registry may be closed by the extension. Temporary launch and session resources are cleaned only after the child pane is confirmed gone.
|
|
394
|
+
|
|
395
|
+
## Contributing
|
|
396
|
+
|
|
397
|
+
For development setup, testing instructions, and contribution guidelines, see
|
|
398
|
+
[CONTRIBUTING.md](CONTRIBUTING.md).
|
package/docs/README.md
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Documentation
|
|
2
|
+
|
|
3
|
+
## Guides
|
|
4
|
+
|
|
5
|
+
User-facing documentation:
|
|
6
|
+
|
|
7
|
+
- [Installation](guides/installation.md)
|
|
8
|
+
- [Agent definitions](guides/agent-definitions.md)
|
|
9
|
+
- [Tool reference](guides/tool-reference.md)
|
|
10
|
+
- [Diagnostics](guides/diagnostics.md)
|
|
11
|
+
|
|
12
|
+
## Reference
|
|
13
|
+
|
|
14
|
+
- [Dictionary](reference/dictionary)
|
|
15
|
+
|
|
16
|
+
## Plans
|
|
17
|
+
|
|
18
|
+
Implementation plans and design notes are kept separately from stable user documentation:
|
|
19
|
+
|
|
20
|
+
- [Architecture](plans/architecture.md)
|
|
21
|
+
- [Agent labels](plans/agent-labels.md)
|
|
22
|
+
- [Settings scope (historical)](plans/settings-scope.md)
|
|
23
|
+
- [Per-workspace settings specification](../specs/005-per-workspace-settings/spec.md)
|
|
24
|
+
- [Remote machine sheep — intent](../specs/008-remote-machine-sheep/intent.md)
|
|
25
|
+
- [Remote machine sheep — remote prerequisites](../specs/008-remote-machine-sheep/prerequisites.md)
|
|
26
|
+
- [Tool surface split](plans/tool-surface-split.md)
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Agent definitions
|
|
2
|
+
|
|
3
|
+
Agent definitions are Markdown files with YAML frontmatter followed by the agent's instructions. They control an agent's role, tools, model, and prompt composition.
|
|
4
|
+
|
|
5
|
+
| Field | Values | Default | Description |
|
|
6
|
+
| --- | --- | --- | --- |
|
|
7
|
+
| `name` | String | — | Agent name. **Required.** |
|
|
8
|
+
| `description` | String | — | Description shown during discovery. **Required.** |
|
|
9
|
+
| `tools` | Comma-separated string or YAML list | pi's default tools | Tools available to the agent. |
|
|
10
|
+
| `model` | Provider-qualified model, `null`, or `default` | Shepherd's model | For example, `anthropic/claude-sonnet-4-5`. Omission, `null`, and `default` inherit the Shepherd's model. |
|
|
11
|
+
| `thinking` | `default`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` | Shepherd's level | Omission, `null`, empty, and `default` inherit the Shepherd's current thinking level. Pi clamps unsupported levels to the child model's capabilities. |
|
|
12
|
+
| `omit-system-prompt` | `true`, `false` | `false` | Omit pi's built-in system prompt. |
|
|
13
|
+
| `omit-pi-documentation` | `true`, `false` | `false` | Omit pi's built-in documentation guidance. |
|
|
14
|
+
| `omit-context-files` | `true`, `false` | `false` | Omit automatic `AGENTS.md` and `CLAUDE.md` loading. |
|
|
15
|
+
| `user-invocable` | `true`, `false` | `true` | Whether the agent is intended for direct user invocation. |
|
|
16
|
+
|
|
17
|
+
Example:
|
|
18
|
+
|
|
19
|
+
```markdown
|
|
20
|
+
---
|
|
21
|
+
name: tester
|
|
22
|
+
description: Runs and evaluates GUI tests
|
|
23
|
+
tools: read, grep, find
|
|
24
|
+
model: anthropic/claude-sonnet-4-5
|
|
25
|
+
thinking: high
|
|
26
|
+
omit-system-prompt: false
|
|
27
|
+
omit-pi-documentation: true
|
|
28
|
+
omit-context-files: true
|
|
29
|
+
user-invocable: true
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
You are a focused GUI testing specialist. Report reproducible failures
|
|
33
|
+
with exact steps and useful evidence.
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
`thinking` is a requested level. Pi clamps it to a level supported by the
|
|
37
|
+
child model, so `xhigh` may become `high`, and a model that cannot
|
|
38
|
+
disable reasoning may not honor `off`. `none` is invalid; use `off` for an
|
|
39
|
+
explicit no-reasoning request. Invalid `thinking` or `model` values cause that definition to be skipped during discovery rather than preventing other agents from loading.
|
|
40
|
+
|
|
41
|
+
See the [README](../../README.md) for discovery precedence, bundled agents,
|
|
42
|
+
and project-agent approval behavior.
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
# Diagnostics
|
|
2
|
+
|
|
3
|
+
This guide explains how to inspect the system prompts assembled by Pi and
|
|
4
|
+
pi-shepherd. It is useful when checking agent discovery, prompt composition,
|
|
5
|
+
Pi documentation guidance, project instructions, or an agent's configured
|
|
6
|
+
model and tools.
|
|
7
|
+
|
|
8
|
+
## Quick start
|
|
9
|
+
|
|
10
|
+
Run these commands from the pi-shepherd repository root:
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
# Inspect the parent Pi session (the Shepherd)
|
|
14
|
+
npm run extract:system-prompt -- shepherd
|
|
15
|
+
|
|
16
|
+
# Inspect a discovered child agent (also called a sheep)
|
|
17
|
+
npm run extract:system-prompt -- agent scout
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
The prompt is written to standard output. To save the raw prompt instead:
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm run extract:system-prompt -- agent scout \
|
|
24
|
+
--output /tmp/scout-system-prompt.md
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
To receive metadata together with the prompt as JSON:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npm run extract:system-prompt -- shepherd --json
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## What is captured
|
|
34
|
+
|
|
35
|
+
The extractor starts an ephemeral `pi --mode json` process and captures the
|
|
36
|
+
fully assembled prompt from Pi's `before_agent_start` hook. It stops the
|
|
37
|
+
process immediately after capture, before the first provider request, so this
|
|
38
|
+
diagnostic does not require a model response or an API call.
|
|
39
|
+
|
|
40
|
+
There are two modes:
|
|
41
|
+
|
|
42
|
+
- `shepherd` loads the pi-shepherd parent extension and captures the parent
|
|
43
|
+
session's assembled prompt.
|
|
44
|
+
- `agent <agent>` resolves the named agent using pi-shepherd discovery, then
|
|
45
|
+
captures a child session using that agent's prompt, model, and tools.
|
|
46
|
+
|
|
47
|
+
Only the extension required by the selected mode is loaded explicitly. This
|
|
48
|
+
keeps the diagnostic deterministic and avoids accidentally loading a second
|
|
49
|
+
copy of pi-shepherd from the installed Pi extensions.
|
|
50
|
+
|
|
51
|
+
The captured prompt can include more than the Markdown body of an agent
|
|
52
|
+
file—for example Pi's built-in instructions, project context, skills, tool
|
|
53
|
+
guidance, and pi-shepherd's prompt adjustments.
|
|
54
|
+
|
|
55
|
+
## Agent discovery options
|
|
56
|
+
|
|
57
|
+
By default, agents are discovered from the user scope. Use `--scope project` or
|
|
58
|
+
`--scope both` when you need project-controlled definitions:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
npm run extract:system-prompt -- agent scout --scope both
|
|
62
|
+
npm run extract:system-prompt -- agent scout --scope project \
|
|
63
|
+
--cwd /path/to/project
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`--cwd` controls discovery and the project context used by the diagnostic
|
|
67
|
+
session. The default is the current working directory.
|
|
68
|
+
|
|
69
|
+
The regular discovery precedence is preserved: user definitions take
|
|
70
|
+
precedence over project definitions, followed by bundled definitions. If the
|
|
71
|
+
agent cannot be found, the command reports an error and exits without
|
|
72
|
+
capturing a prompt.
|
|
73
|
+
|
|
74
|
+
## Inspecting only the Shepherd contribution
|
|
75
|
+
|
|
76
|
+
If the fully assembled prompt is more detail than you need, use the narrower
|
|
77
|
+
agent-prompt diagnostic:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
npm run show:shepherd-prompt -- scout
|
|
81
|
+
npm run show:shepherd-prompt -- scout --scope both --cwd /path/to/project
|
|
82
|
+
npm run show:shepherd-prompt -- scout --raw
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
This command reads the discovered agent definition directly. It shows the
|
|
86
|
+
Markdown system-prompt body and launch mode, but not Pi's built-in prompt,
|
|
87
|
+
project context, skills, or tool instructions.
|
|
88
|
+
|
|
89
|
+
Use this command to answer questions such as:
|
|
90
|
+
|
|
91
|
+
- Which agent definition was selected?
|
|
92
|
+
- Where did it come from?
|
|
93
|
+
- Is it being appended or used as a replacement?
|
|
94
|
+
- What exact Markdown body is being passed to the child?
|
|
95
|
+
|
|
96
|
+
Use `extract:system-prompt` when you need to answer how that body combines
|
|
97
|
+
with the rest of the child session's prompt.
|
|
98
|
+
|
|
99
|
+
## Useful extractor options
|
|
100
|
+
|
|
101
|
+
```text
|
|
102
|
+
--cwd <path> Working directory for discovery and Pi (default: current)
|
|
103
|
+
--scope <scope> user, project, or both (agent mode; default: user)
|
|
104
|
+
--output <path> Save raw prompt to this path as well as stdout
|
|
105
|
+
--json Print metadata and prompt as JSON
|
|
106
|
+
--model <model> Override the diagnostic model
|
|
107
|
+
--prompt <text> Use a custom harmless diagnostic user message
|
|
108
|
+
--timeout <sec> Startup timeout in seconds (default: 20)
|
|
109
|
+
--pi <command> Pi executable to run (default: pi)
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
For example, to compare a project prompt with a user prompt and record the
|
|
113
|
+
source metadata:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
npm run extract:system-prompt -- agent scout \
|
|
117
|
+
--scope both \
|
|
118
|
+
--cwd /path/to/project \
|
|
119
|
+
--json > /tmp/scout-system-prompt.json
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
The `--output` file contains only the raw prompt and is written with
|
|
123
|
+
restrictive permissions. JSON output is intended for inspection or automation;
|
|
124
|
+
its `systemPrompt` field contains the same captured prompt.
|
|
125
|
+
|
|
126
|
+
## Prompt composition details
|
|
127
|
+
|
|
128
|
+
When pi-shepherd launches an agent, the agent Markdown body replaces Pi's
|
|
129
|
+
generic leading identity paragraph unless the agent opts into a different
|
|
130
|
+
configuration. The remaining Pi instructions and context stay available.
|
|
131
|
+
|
|
132
|
+
An agent can omit only Pi's documentation guidance with frontmatter such as:
|
|
133
|
+
|
|
134
|
+
```markdown
|
|
135
|
+
---
|
|
136
|
+
name: scout
|
|
137
|
+
description: Fast codebase recon
|
|
138
|
+
omit-pi-documentation: true
|
|
139
|
+
---
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
This does not remove project instructions, skills, tools, or the agent body.
|
|
143
|
+
|
|
144
|
+
To inspect a child without Pi’s automatic project context files, set the
|
|
145
|
+
kebab-case frontmatter property to a YAML boolean:
|
|
146
|
+
|
|
147
|
+
```markdown
|
|
148
|
+
---
|
|
149
|
+
name: tester
|
|
150
|
+
description: Runs and evaluates GUI tests
|
|
151
|
+
omit-context-files: true
|
|
152
|
+
---
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
This makes both a normal Shepherd launch and this diagnostic pass
|
|
156
|
+
`--no-context-files`, disabling automatic `AGENTS.md` and `CLAUDE.md` loading
|
|
157
|
+
for the child Pi session. The agent Markdown body, task/user prompt, Shepherd
|
|
158
|
+
fieldnotes context (when fieldnotes are enabled), configured tools, and model are unchanged. The property is `false` by default; `omit-context-files: false` leaves normal
|
|
159
|
+
loading enabled, and quoted values such as `"true"` are ignored.
|
|
160
|
+
|
|
161
|
+
The extractor is the easiest way to verify the effective result rather than
|
|
162
|
+
inferring it from the agent file alone.
|
|
163
|
+
|
|
164
|
+
## Troubleshooting
|
|
165
|
+
|
|
166
|
+
### Agent not found
|
|
167
|
+
|
|
168
|
+
Try listing available agents and check the scope and working directory:
|
|
169
|
+
|
|
170
|
+
```text
|
|
171
|
+
/shepherd agents
|
|
172
|
+
/shepherd agents both
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Then rerun the extractor with `--scope both` and, if needed, `--cwd` pointing
|
|
176
|
+
to the project containing the definition.
|
|
177
|
+
|
|
178
|
+
### Timeout waiting for capture
|
|
179
|
+
|
|
180
|
+
Confirm that the `pi` executable is available and increase the timeout:
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
npm run extract:system-prompt -- shepherd --timeout 60
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Use `--pi <command>` if Pi is not available as `pi` on `PATH`. Any diagnostic
|
|
187
|
+
startup errors are printed by the extractor.
|
|
188
|
+
|
|
189
|
+
### Unexpected prompt contents
|
|
190
|
+
|
|
191
|
+
Compare the two diagnostics:
|
|
192
|
+
|
|
193
|
+
1. `show:shepherd-prompt` verifies the selected agent definition and its exact
|
|
194
|
+
body.
|
|
195
|
+
2. `extract:system-prompt` verifies the final assembled prompt, including Pi
|
|
196
|
+
and project context.
|
|
197
|
+
|
|
198
|
+
Also check `--cwd`, `--scope`, and whether a higher-precedence user definition
|
|
199
|
+
has the same agent name.
|