@luminascale/shepherd 0.0.0-stage → 0.6.0
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 +424 -2
- package/docs/README.md +25 -0
- package/docs/guides/agent-definitions.md +42 -0
- package/docs/guides/diagnostics.md +199 -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 +599 -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 +259 -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 +35 -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 +69 -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
|
@@ -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.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Tool reference
|
|
2
|
+
|
|
3
|
+
pi-shepherd exposes these structured tools to the Shepherd. Lifecycle IDs are opaque, session-scoped handles; do not substitute Herdr pane IDs.
|
|
4
|
+
|
|
5
|
+
## Discovery and inspection
|
|
6
|
+
|
|
7
|
+
| Tool | Arguments | Purpose |
|
|
8
|
+
| --- | --- | --- |
|
|
9
|
+
| `shepherd` | `action`: `agents`, `herd`, or `prune`; optional `agentScope`: `user`, `project`, or `both` | Discover definitions, list active agents, or remove stale registrations. |
|
|
10
|
+
| `shepherd_status` | `id`: agent ID | Inspect an agent without focusing its pane. For an open task the result carries the task ID, state, waiting age, pending request, recipient, and stale flag. |
|
|
11
|
+
| `shepherd_read` | `name`: agent name, agent ID, or pane ID; optional `lines`, `source` | Read recent terminal output for diagnostics. |
|
|
12
|
+
|
|
13
|
+
## Lifecycle
|
|
14
|
+
|
|
15
|
+
| Tool | Arguments | Purpose |
|
|
16
|
+
| --- | --- | --- |
|
|
17
|
+
| `shepherd_spawn` | `agent`, `label`; optional `placement`, `cwd` | Create an idle persistent agent. Placement is `pane_right`, `pane_down`, `tab`, or `workspace`; the default is a background tab. The model and requested thinking level come from the agent definition Markdown frontmatter. |
|
|
18
|
+
| `shepherd_delegate` | `target`: agent ID, `task`: description; optional `timeout` | Start a tracked task and return a task ID without waiting. One active task per agent. |
|
|
19
|
+
| `shepherd_message` | `target`: agent ID, `message`; optional `taskId`, `threadId`, `replyTo`, `expectsReply`, `delivery` | Send an asynchronous message (parent or peer). `expectsReply` opens a tracked reply request; the sender's task enters `waiting` until the reply. |
|
|
20
|
+
| `shepherd_prompt` | `id`: agent ID, `message`: one-turn message | **Deprecated** compatibility path. Ties completion to one child turn; prefer `shepherd_delegate` for tracked work. |
|
|
21
|
+
| `shepherd_watch` | `id`: task ID(s) (preferred) or legacy prompt ID(s) | Register a non-blocking completion watcher; completions arrive as steered notifications. An unwatched settlement surfaces at the next settle boundary or as one coalesced idle wake (identical wording on Herdr and hc; only opaque ids differ). |
|
|
22
|
+
| `shepherd_close` | `id`: agent ID | Close an owned agent, cancel its active task (and unresolved prompt), and clear pending requests. |
|
|
23
|
+
|
|
24
|
+
`shepherd_watch` is the explicit observation point: watching an already-settled task returns its result synchronously, and a pending watch delivers steered notifications as tasks settle. An unwatched settlement is still surfaced at the next settle boundary (one extra model request) while the Shepherd is busy, or as one coalesced idle wake; the notice names the `shepherd_watch` call that retrieves the full results. This holds on both backends: Herdr pane settles and hc terminal settles use identical notice wording. On hc, `shepherd_watch` registration and the status view drain first, and a 250 ms background poll keeps the registry fresh while work is open.
|
|
25
|
+
|
|
26
|
+
Example:
|
|
27
|
+
|
|
28
|
+
```text
|
|
29
|
+
shepherd_spawn({
|
|
30
|
+
agent: "worker",
|
|
31
|
+
label: "implementation",
|
|
32
|
+
placement: "pane_right",
|
|
33
|
+
cwd: "/path/to/project"
|
|
34
|
+
})
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`cwd` defaults to the Shepherd session. The model and requested thinking level come from the discovered agent definition; omission, `null`, or `default` inherit the Shepherd session's corresponding settings. Agent scope, project approval, and prompt-shaping options come from settings and the discovered definition rather than spawn arguments. Only panes created and recorded by pi-shepherd can be closed by the extension.
|
|
38
|
+
|
|
39
|
+
## Child-side tools
|
|
40
|
+
|
|
41
|
+
| Tool | Arguments | Purpose |
|
|
42
|
+
| --- | --- | --- |
|
|
43
|
+
| `shepherd_message` | `target`: `parent` or an owned agent ID, `message`; optional `taskId`, `threadId`, `replyTo`, `expectsReply`, `delivery` | A child sends an asynchronous message to the parent or a peer. `expectsReply` (to a parent task) opens the tracked reply request. |
|
|
44
|
+
| `shepherd_done` | `taskId`, `summary`; optional `ok`, `returnCode`, `error` | The only normal successful completion for a tracked task. Repeated calls are idempotent. |
|
|
45
|
+
|
|
46
|
+
A child that ends a turn with its tracked task still open feeds itself one reminder turn asking for `shepherd_done` (budget: one per task, `PI_SHEPHERD_DONE_NUDGES` overrides, `0` disables). Aborted or errored turns and turns waiting on an `expectsReply` request are never nudged; a task that survives every reminder is reported to the parent as a stalled completion.
|
|
47
|
+
|
|
48
|
+
## IDs at a glance
|
|
49
|
+
|
|
50
|
+
- **Agent id** – from `shepherd_spawn`; accepted by `delegate`, `message`, `status`, `close`.
|
|
51
|
+
- **Task id** – from `shepherd_delegate`; the tracked unit of work; accepted by `wait`, `watch`, `message` (`taskId`), and `shepherd_done`.
|
|
52
|
+
- **Prompt id** – from the deprecated `shepherd_prompt`; accepted by `wait` and `watch` (legacy path).
|
|
53
|
+
- **Message id** – returned by `shepherd_message`; used as `replyTo` by the agent answering the request.
|
|
54
|
+
|
|
55
|
+
None of these can be substituted with a Herdr pane ID; pane IDs are diagnostic targets for `shepherd_read` only.
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
# Manual test: ping-pong peer messaging
|
|
2
|
+
|
|
3
|
+
Use this smoke test to verify that two live Shepherd children can exchange a
|
|
4
|
+
correlated request and reply, resume the requester, and complete through
|
|
5
|
+
`shepherd_done`.
|
|
6
|
+
|
|
7
|
+
## Preconditions
|
|
8
|
+
|
|
9
|
+
- Run inside a live Herdr-managed Shepherd session.
|
|
10
|
+
- Reload the extension after changing the implementation.
|
|
11
|
+
- Use visible child panes (`pane_right` and `pane_down`) when possible.
|
|
12
|
+
- Use generous task deadlines; provider startup can take more than a minute.
|
|
13
|
+
- Do **not** use the removed blocking `shepherd_wait` operation.
|
|
14
|
+
|
|
15
|
+
## Procedure
|
|
16
|
+
|
|
17
|
+
### 1. Spawn the children
|
|
18
|
+
|
|
19
|
+
Spawn a planner and a worker, recording the opaque agent IDs returned by each
|
|
20
|
+
call:
|
|
21
|
+
|
|
22
|
+
```json
|
|
23
|
+
{"agent":"planner","label":"manual planner","placement":"pane_right"}
|
|
24
|
+
{"agent":"worker","label":"manual worker","placement":"pane_down"}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Do not substitute display names, Herdr pane IDs, or agent-kind names for the
|
|
28
|
+
returned lifecycle IDs.
|
|
29
|
+
|
|
30
|
+
### 2. Delegate the planner task
|
|
31
|
+
|
|
32
|
+
Use the planner's returned agent ID and a deadline of at least 10 minutes:
|
|
33
|
+
|
|
34
|
+
> Watch for one incoming peer request. When you receive it, reply to the exact
|
|
35
|
+
> `replyTo` using `shepherd_message`, omit `taskId` so it is inferred, then call
|
|
36
|
+
> `shepherd_done` with text `planner replied`. Do not use `shepherd_wait`.
|
|
37
|
+
|
|
38
|
+
Record the returned planner task ID.
|
|
39
|
+
|
|
40
|
+
### 3. Delegate the worker task
|
|
41
|
+
|
|
42
|
+
Use the worker's returned agent ID and put the planner's **actual opaque ID**
|
|
43
|
+
from Step 1 into the task text. Do not pass the planner's definition name,
|
|
44
|
+
display label, Herdr pane ID, or angle-bracket placeholder.
|
|
45
|
+
|
|
46
|
+
> Send planner a peer request using `shepherd_message`: set `target` to the
|
|
47
|
+
> planner spawn result's `id` field (the full opaque `shepherd-agent-...` string),
|
|
48
|
+
> message `Reply with exactly pong`, `expectsReply: true`. Wait for the reply
|
|
49
|
+
> using normal turns (never `shepherd_wait`), then call `shepherd_done` with text
|
|
50
|
+
> containing the reply. Do not call `shepherd_wait`.
|
|
51
|
+
|
|
52
|
+
Do not copy a documentation placeholder into the worker task. Before calling
|
|
53
|
+
`shepherd_delegate`, interpolate the exact ID copied from the planner's spawn
|
|
54
|
+
result into the task text. `planner`, `manual planner`, Herdr pane IDs, and
|
|
55
|
+
angle-bracket placeholders are invalid targets; the child tool rejects them.
|
|
56
|
+
|
|
57
|
+
Record the returned worker task ID.
|
|
58
|
+
|
|
59
|
+
### 4. Register non-blocking watchers
|
|
60
|
+
|
|
61
|
+
Register a watcher for both task IDs:
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{"id":["<planner task ID>","<worker task ID>"]}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The call must return immediately with both tasks in `pending`. Use
|
|
68
|
+
`shepherd_status` periodically to inspect intermediate state; do not block the
|
|
69
|
+
Shepherd turn waiting for completion.
|
|
70
|
+
|
|
71
|
+
Expected intermediate behavior:
|
|
72
|
+
|
|
73
|
+
- Planner may become idle while its task remains active until it receives the
|
|
74
|
+
request.
|
|
75
|
+
- Worker enters `waiting` after sending the request.
|
|
76
|
+
- Planner replies with `pong` using the request's exact `replyTo`; omitting
|
|
77
|
+
`taskId` exercises child-side task-ID inference.
|
|
78
|
+
- Worker resumes and calls `shepherd_done`.
|
|
79
|
+
|
|
80
|
+
If a watcher was already consumed or completed, register a fresh watcher using
|
|
81
|
+
the task ID. A watcher ID itself is not a valid `shepherd_watch` target.
|
|
82
|
+
|
|
83
|
+
### 5. Verify terminal results
|
|
84
|
+
|
|
85
|
+
Watch each task ID again, or use the follow-up completion notification. Both
|
|
86
|
+
results must contain:
|
|
87
|
+
|
|
88
|
+
```text
|
|
89
|
+
status: completed
|
|
90
|
+
ok: true
|
|
91
|
+
returnCode: 0
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
The worker result text should contain:
|
|
95
|
+
|
|
96
|
+
```text
|
|
97
|
+
Planner reply: pong
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The planner result should contain:
|
|
101
|
+
|
|
102
|
+
```text
|
|
103
|
+
planner replied
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### 6. Clean up
|
|
107
|
+
|
|
108
|
+
Only after both tasks are terminal, close both agents using their opaque agent
|
|
109
|
+
IDs. Do not close an agent while its watcher is still pending.
|
|
110
|
+
|
|
111
|
+
## Pass criteria
|
|
112
|
+
|
|
113
|
+
The test passes when:
|
|
114
|
+
|
|
115
|
+
1. Both children launch in visible panes.
|
|
116
|
+
2. The worker request reaches the planner.
|
|
117
|
+
3. The planner's correlated reply reaches the worker.
|
|
118
|
+
4. The worker resumes without a redundant acknowledgment step.
|
|
119
|
+
5. Both tasks settle as `completed` with return code `0`.
|
|
120
|
+
6. `shepherd_watch` reports both terminal results.
|
|
121
|
+
7. Both agents close cleanly afterward.
|
|
122
|
+
|
|
123
|
+
## Failure notes
|
|
124
|
+
|
|
125
|
+
- `Agent pane disappeared before the task completed` means the live lifecycle
|
|
126
|
+
test failed; do not count it as a pass even if a response later appears.
|
|
127
|
+
- A short deadline may expire during provider startup. Retry with 10 minutes or
|
|
128
|
+
more before diagnosing messaging behavior.
|
|
129
|
+
- If the child appears idle, inspect `shepherd_status`: idle process state does
|
|
130
|
+
not necessarily mean the tracked task is complete.
|
|
131
|
+
- If a reply is rejected, verify that `replyTo` is the exact incoming request
|
|
132
|
+
message ID and that any explicit `taskId` is the requester's task ID, not the
|
|
133
|
+
responder's task ID.
|
|
134
|
+
- The large `artifactSession` object in a watcher result includes historical
|
|
135
|
+
session artifacts. Use the top-level task result for current status.
|
|
136
|
+
|
|
137
|
+
## Recorded successful run
|
|
138
|
+
|
|
139
|
+
The reloaded-extension run on 2026-09-01 (steered watcher delivery, issue #10
|
|
140
|
+
fix) succeeded with:
|
|
141
|
+
|
|
142
|
+
- Planner result: `completed`, `ok: true`, `returnCode: 0`, `planner replied`
|
|
143
|
+
- Worker result: `completed`, `ok: true`, `returnCode: 0`, `received reply: pong`
|
|
144
|
+
- Completion observation: both watcher completions were delivered as steered
|
|
145
|
+
follow-ups **mid-turn**, before any cleanup; the combined watcher settled
|
|
146
|
+
both tasks before the agents were closed
|
|
147
|
+
- Cleanup: both agents closed after terminal completion
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
# pi-shepherd — Task-Specific Agent Labels Plan
|
|
2
|
+
|
|
3
|
+
## Goal
|
|
4
|
+
|
|
5
|
+
Give each spawned agent an optional, human-facing task label while retaining the
|
|
6
|
+
opaque lifecycle ID as the authoritative identifier used by code and lifecycle
|
|
7
|
+
calls.
|
|
8
|
+
|
|
9
|
+
Example:
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
shepherd_spawn({ agent: "reviewer", label: "code review" })
|
|
13
|
+
→ reviewer: code review
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Proposed semantics
|
|
17
|
+
|
|
18
|
+
- `agent` remains the discovered agent definition name, such as `reviewer`.
|
|
19
|
+
- `label` is a short, task-specific instance label selected by the calling
|
|
20
|
+
agent.
|
|
21
|
+
- `id` remains the unique lifecycle handle used by `prompt`, `wait`, `status`,
|
|
22
|
+
and `close`.
|
|
23
|
+
- No automatic numbering scheme is introduced.
|
|
24
|
+
- An unlabeled spawn has an empty label and is displayed using its agent type
|
|
25
|
+
alone everywhere, including the Herdr tab, pane, or workspace name:
|
|
26
|
+
|
|
27
|
+
```text
|
|
28
|
+
/shepherd spawn reviewer
|
|
29
|
+
→ reviewer
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
The display-name rule is intentionally simple: use `<agent>: <label>` when a
|
|
33
|
+
non-empty label is present; otherwise use `<agent>` unchanged. In other words,
|
|
34
|
+
an unlabeled user-created reviewer should produce a Herdr name of `reviewer`,
|
|
35
|
+
not `reviewer:`, `reviewer-`, or an automatically numbered variant.
|
|
36
|
+
|
|
37
|
+
- A labeled spawn combines the agent name and label for human-facing output:
|
|
38
|
+
|
|
39
|
+
```text
|
|
40
|
+
reviewer + code review → reviewer: code review
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The model-facing `shepherd_spawn` input requires a label so every spawned
|
|
44
|
+
instance has a short, task-specific human identifier. Tool guidance should make
|
|
45
|
+
providing that label explicit. The label is separate from the discovered agent
|
|
46
|
+
name and is validated for safe display. The human `/shepherd spawn reviewer`
|
|
47
|
+
command remains valid without a label and passes an empty label through
|
|
48
|
+
unchanged. A human can provide one explicitly with:
|
|
49
|
+
|
|
50
|
+
```text
|
|
51
|
+
/shepherd spawn reviewer --label "code review"
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Handle shape
|
|
55
|
+
|
|
56
|
+
The resolved handle may represent an empty label explicitly:
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
{
|
|
60
|
+
id: "shepherd-agent-...",
|
|
61
|
+
agent: "reviewer",
|
|
62
|
+
label: ""
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The friendly display name is derived rather than stored separately:
|
|
67
|
+
|
|
68
|
+
```text
|
|
69
|
+
label present → reviewer: code review
|
|
70
|
+
label empty → reviewer
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
This can be implemented conceptually as a presence check: if `label` is null,
|
|
74
|
+
undefined, or empty after trimming, return the agent type; otherwise return the
|
|
75
|
+
agent type, separator, and label.
|
|
76
|
+
|
|
77
|
+
Use the same representation for the user-visible tool call/result, the herd
|
|
78
|
+
widget, and the Herdr pane, tab, or workspace label. The recommended format is
|
|
79
|
+
`<agent>: <label>` because the colon clearly separates the role from the
|
|
80
|
+
human-readable task description. A hyphenated form such as
|
|
81
|
+
`reviewer-code-review` is more compact but looks like a machine slug and makes
|
|
82
|
+
the boundary less obvious.
|
|
83
|
+
|
|
84
|
+
This avoids storing redundant `displayName` state and keeps the definition name,
|
|
85
|
+
instance label, and lifecycle identity distinct.
|
|
86
|
+
|
|
87
|
+
## Identity and lookup
|
|
88
|
+
|
|
89
|
+
The label is for recognition and presentation in the user-facing tool call and
|
|
90
|
+
result, the herd widget, Herdr labels, status, and diagnostics. The TUI should
|
|
91
|
+
show the derived representation instead of exposing the long opaque ID in those
|
|
92
|
+
places.
|
|
93
|
+
|
|
94
|
+
This is a presentation change, not a protocol change. The underlying tool
|
|
95
|
+
arguments and lifecycle registry continue to use the opaque ID so `prompt`,
|
|
96
|
+
`wait`, `status`, and `close` remain unambiguous. Tool results may retain the ID
|
|
97
|
+
for the parent model while `renderCall`/`renderResult` hide it from the user.
|
|
98
|
+
Changing the actual tool protocol to accept only labels is out of scope.
|
|
99
|
+
|
|
100
|
+
Duplicate labels do not change lifecycle identity. Empty labels may be
|
|
101
|
+
repeated, so multiple unlabeled agents can exist as `reviewer`. Non-empty labels
|
|
102
|
+
must be unique for the complete display name within the parent session; reject a
|
|
103
|
+
duplicate rather than silently suffixing it. A label shared by different agent
|
|
104
|
+
types is valid because the complete display names differ:
|
|
105
|
+
|
|
106
|
+
```text
|
|
107
|
+
reviewer: code review ✅
|
|
108
|
+
reviewer: api review ✅
|
|
109
|
+
reviewer: code review ❌ duplicate
|
|
110
|
+
scout: code review ✅
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Labels are not accepted as lifecycle IDs. Lifecycle operations continue to
|
|
114
|
+
resolve agents exclusively by opaque ID.
|
|
115
|
+
|
|
116
|
+
## Validation
|
|
117
|
+
|
|
118
|
+
Because `label` is a human-facing label rather than a machine slug, preserve
|
|
119
|
+
readable spaces instead of forcing a hyphenated form. Apply these rules:
|
|
120
|
+
|
|
121
|
+
- trim leading and trailing whitespace;
|
|
122
|
+
- treat an empty-after-trimming value as no label;
|
|
123
|
+
- reject control characters and newlines;
|
|
124
|
+
- allow letters, numbers, spaces, `_`, `-`, and `.`;
|
|
125
|
+
- reject `:` because it is the role/label separator;
|
|
126
|
+
- preserve the user's casing; and
|
|
127
|
+
- limit the label to 64 characters.
|
|
128
|
+
|
|
129
|
+
The label must not be confused with the discovered agent name or a Herdr pane
|
|
130
|
+
ID. Any machine-safe value needed for temporary files or launch arguments should
|
|
131
|
+
be derived separately and should not become the user-facing label.
|
|
132
|
+
|
|
133
|
+
## Implementation areas
|
|
134
|
+
|
|
135
|
+
- Extend spawn arguments and `AgentHandle` with `label`, keeping it separate
|
|
136
|
+
from the discovered agent name.
|
|
137
|
+
- Resolve the optional input to an empty label when omitted; do not maintain a
|
|
138
|
+
per-agent counter or generate labels such as `reviewer-01`.
|
|
139
|
+
- Propagate the label to the user-facing tool call/result, herd widget, and
|
|
140
|
+
Herdr tab/pane/workspace presentation without changing agent discovery or
|
|
141
|
+
launch semantics.
|
|
142
|
+
- Derive the friendly display name at presentation boundaries instead of adding
|
|
143
|
+
a stored `displayName` field.
|
|
144
|
+
- Keep the opaque ID in the underlying model-facing lifecycle protocol even when
|
|
145
|
+
the TUI renders the label instead.
|
|
146
|
+
- Update tool descriptions and prompt guidance so calling agents normally
|
|
147
|
+
provide a short task-specific label.
|
|
148
|
+
- Update `/shepherd` parsing and help text while preserving unlabeled human
|
|
149
|
+
commands.
|
|
150
|
+
- Update README examples and documentation.
|
|
151
|
+
|
|
152
|
+
## Phased implementation plan
|
|
153
|
+
|
|
154
|
+
### Phase 1 — Lock down the contract
|
|
155
|
+
|
|
156
|
+
- Use `label` as the public field name; it is optional at the spawn boundary.
|
|
157
|
+
- Use the resolved representation where `agent` is the agent definition name,
|
|
158
|
+
`label` is an empty or non-empty task label, and `id` remains the opaque
|
|
159
|
+
lifecycle identifier.
|
|
160
|
+
- Define the display formatter once:
|
|
161
|
+
|
|
162
|
+
```text
|
|
163
|
+
non-empty label → <agent>: <label>
|
|
164
|
+
empty label → <agent>
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
- Apply the decided validation rules: trim whitespace, reject control
|
|
168
|
+
characters/newlines and `:`, allow letters, numbers, spaces, `_`, `-`, and `.`,
|
|
169
|
+
preserve case, and limit labels to 64 characters.
|
|
170
|
+
- Permit repeated empty labels, but reject duplicate non-empty complete display
|
|
171
|
+
names within the parent session. Do not add automatic numbering.
|
|
172
|
+
- Use `/shepherd spawn reviewer --label "code review"` as the documented human
|
|
173
|
+
command syntax; the label remains optional.
|
|
174
|
+
|
|
175
|
+
### Phase 2 — Extend the lifecycle data model
|
|
176
|
+
|
|
177
|
+
- Add `label` to the spawn input and resolved `AgentHandle`.
|
|
178
|
+
- Resolve omitted, null, or whitespace-only input to an empty label.
|
|
179
|
+
- Preserve the existing opaque-ID registry and lookup behavior.
|
|
180
|
+
- Ensure labels are assigned consistently before the handle is returned and are
|
|
181
|
+
available to status, prompt results, and close-related output.
|
|
182
|
+
- Add registry-level tests for labeled and unlabeled handles.
|
|
183
|
+
|
|
184
|
+
### Phase 3 — Add shared presentation formatting
|
|
185
|
+
|
|
186
|
+
- Add one shared formatter for the friendly agent name rather than duplicating
|
|
187
|
+
string concatenation across adapters.
|
|
188
|
+
- Verify that an empty label returns exactly the agent type, with no separator,
|
|
189
|
+
suffix, or generated number.
|
|
190
|
+
- Verify that a labeled instance returns the chosen `<agent>: <label>` form.
|
|
191
|
+
- Keep the formatter presentation-only; it must not become a lifecycle lookup
|
|
192
|
+
key or replace the opaque ID.
|
|
193
|
+
|
|
194
|
+
### Phase 4 — Update spawn surfaces and Herdr presentation
|
|
195
|
+
|
|
196
|
+
- Extend model-facing `shepherd_spawn` schema, descriptions, and guidance so
|
|
197
|
+
calling agents normally provide a short task-specific label.
|
|
198
|
+
- Keep `/shepherd spawn reviewer` valid without a label and pass the empty label
|
|
199
|
+
through unchanged.
|
|
200
|
+
- Use the derived friendly name for Herdr tab, pane, and workspace labels.
|
|
201
|
+
- Use the agent type alone for an unlabeled user-created instance, such as a tab
|
|
202
|
+
named `reviewer`.
|
|
203
|
+
- Preserve the discovered agent name for discovery and launch semantics; do not
|
|
204
|
+
use the composite display name to resolve agent definitions.
|
|
205
|
+
- Ensure background placement and pane ownership behavior remain unchanged.
|
|
206
|
+
|
|
207
|
+
### Phase 5 — Update user-facing tool and widget rendering
|
|
208
|
+
|
|
209
|
+
- Render the friendly name instead of the long opaque ID in user-facing tool
|
|
210
|
+
calls and results.
|
|
211
|
+
- Update the herd/status widget to show the same friendly name consistently.
|
|
212
|
+
- Retain the opaque ID in the underlying tool result data or model-facing text
|
|
213
|
+
wherever it is needed for follow-up lifecycle calls.
|
|
214
|
+
- Verify that user-facing rendering does not make labels usable accidentally as
|
|
215
|
+
lifecycle IDs.
|
|
216
|
+
|
|
217
|
+
### Phase 6 — Documentation and compatibility
|
|
218
|
+
|
|
219
|
+
- Update the README, lifecycle examples, command help, and tool guidance.
|
|
220
|
+
- Document labeled and unlabeled spawn behavior, including the exact Herdr name
|
|
221
|
+
for an unlabeled spawn.
|
|
222
|
+
- Document that labels are for human recognition while IDs remain authoritative.
|
|
223
|
+
- Review diagnostics, fieldnotes, and persisted metadata for places where the
|
|
224
|
+
friendly name should be shown without changing stored identity semantics.
|
|
225
|
+
|
|
226
|
+
### Phase 7 — Verification and live smoke testing
|
|
227
|
+
|
|
228
|
+
- Run all automated schema, CLI, registry, launch, widget, and lifecycle tests.
|
|
229
|
+
- Run a live Herdr check for a labeled spawn and verify the tab/pane/workspace
|
|
230
|
+
name.
|
|
231
|
+
- Run a live Herdr check for `/shepherd spawn reviewer` and verify the name is
|
|
232
|
+
exactly `reviewer`.
|
|
233
|
+
- Verify prompt, wait, status, and close still work using the opaque ID.
|
|
234
|
+
- Verify multiple labels, repeated empty labels, and rejection of duplicate
|
|
235
|
+
non-empty complete display names.
|
|
236
|
+
- Verify no numbering state or generated labels exist.
|
|
237
|
+
|
|
238
|
+
## Verification
|
|
239
|
+
|
|
240
|
+
Add coverage for:
|
|
241
|
+
|
|
242
|
+
- schema acceptance of labeled and unlabeled spawns;
|
|
243
|
+
- `/shepherd spawn reviewer` producing an empty label;
|
|
244
|
+
- a supplied label producing the expected friendly name (`reviewer: code review`);
|
|
245
|
+
- no automatic numbering or counter state;
|
|
246
|
+
- label normalization and validation;
|
|
247
|
+
- repeated empty labels and duplicate non-empty display-name rejection;
|
|
248
|
+
- propagation to tool-call rendering, the herd widget, and Herdr presentation;
|
|
249
|
+
- user-facing rendering hiding the opaque ID while model-facing results retain
|
|
250
|
+
whatever ID data is required for follow-up calls; and
|
|
251
|
+
- lifecycle calls continuing to use the opaque ID.
|
|
252
|
+
|
|
253
|
+
Run the existing test suite with:
|
|
254
|
+
|
|
255
|
+
```bash
|
|
256
|
+
npm test
|
|
257
|
+
```
|