@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.
Files changed (203) hide show
  1. package/.agents/agents/README.md +12 -0
  2. package/.agents/agents/planner.md +38 -0
  3. package/.agents/agents/reviewer.md +38 -0
  4. package/.agents/agents/scout.md +43 -0
  5. package/.agents/agents/worker.md +33 -0
  6. package/.agents/skills/smoke-test/SKILL.md +155 -0
  7. package/.agents/skills/smoke-test/references/forensics.md +46 -0
  8. package/.agents/skills/smoke-test/scripts/live-smoke-poll.mjs +130 -0
  9. package/.github/workflows/publish.yml +77 -0
  10. package/.pi/prompts/release.md +21 -0
  11. package/.prettierrc +10 -0
  12. package/AGENTS.md +88 -0
  13. package/CONTRIBUTING.md +177 -0
  14. package/LICENSE +201 -0
  15. package/README.md +424 -2
  16. package/docs/README.md +25 -0
  17. package/docs/guides/agent-definitions.md +42 -0
  18. package/docs/guides/diagnostics.md +199 -0
  19. package/docs/guides/tool-reference.md +55 -0
  20. package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
  21. package/docs/plans/agent-labels.md +257 -0
  22. package/docs/plans/architecture.md +110 -0
  23. package/docs/plans/settings-scope.md +163 -0
  24. package/docs/plans/tool-surface-split.md +278 -0
  25. package/docs/reference/dictionary +26 -0
  26. package/docs/releasing.md +47 -0
  27. package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
  28. package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
  29. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
  30. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
  31. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
  32. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
  33. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
  34. package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
  35. package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
  36. package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
  37. package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
  38. package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
  39. package/index.ts +599 -0
  40. package/package.json +112 -4
  41. package/scripts/capture-system-prompt.mjs +45 -0
  42. package/scripts/extract-pi-system-prompt.mjs +277 -0
  43. package/scripts/host-impact.mjs +74 -0
  44. package/scripts/resolve-agent.mjs +43 -0
  45. package/scripts/show-shepherd-orchestrator.mjs +58 -0
  46. package/scripts/show-shepherd-prompt.mjs +96 -0
  47. package/scripts/verify-suites.mjs +67 -0
  48. package/specs/001-artifacts/spec.md +436 -0
  49. package/specs/002-simplify-agent-orchestration/plan.md +287 -0
  50. package/specs/002-simplify-agent-orchestration/spec.md +323 -0
  51. package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
  52. package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
  53. package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
  54. package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
  55. package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
  56. package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
  57. package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
  58. package/specs/005-per-workspace-settings/plan.md +230 -0
  59. package/specs/005-per-workspace-settings/spec.md +368 -0
  60. package/specs/005-per-workspace-settings/tasks.md +178 -0
  61. package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
  62. package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
  63. package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
  64. package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
  65. package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
  66. package/specs/007-unwatched-completion-notice/journal.md +145 -0
  67. package/specs/007-unwatched-completion-notice/plan.md +186 -0
  68. package/specs/007-unwatched-completion-notice/spec.md +284 -0
  69. package/specs/007-unwatched-completion-notice/tasks.md +147 -0
  70. package/specs/008-remote-machine-sheep/intent.md +174 -0
  71. package/specs/008-remote-machine-sheep/journal.md +57 -0
  72. package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
  73. package/specs/009-hc-runtime/intent.md +44 -0
  74. package/specs/009-hc-runtime/plan.md +49 -0
  75. package/specs/009-hc-runtime/spec.md +118 -0
  76. package/specs/009-hc-runtime/tasks.md +62 -0
  77. package/specs/010-unseen-watch-parity/intent.md +57 -0
  78. package/specs/010-unseen-watch-parity/journal.md +172 -0
  79. package/specs/010-unseen-watch-parity/plan.md +74 -0
  80. package/specs/010-unseen-watch-parity/spec.md +191 -0
  81. package/specs/010-unseen-watch-parity/tasks.md +119 -0
  82. package/specs/011-hc-background-poll/intent.md +57 -0
  83. package/specs/011-hc-background-poll/journal.md +95 -0
  84. package/specs/011-hc-background-poll/plan.md +87 -0
  85. package/specs/011-hc-background-poll/spec.md +141 -0
  86. package/specs/011-hc-background-poll/tasks.md +83 -0
  87. package/specs/012-steer-default/intent.md +12 -0
  88. package/specs/012-steer-default/journal.md +40 -0
  89. package/specs/012-steer-default/plan.md +7 -0
  90. package/specs/012-steer-default/spec.md +42 -0
  91. package/specs/012-steer-default/tasks.md +6 -0
  92. package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
  93. package/specs/013-opencode-shepherd/intent.md +59 -0
  94. package/specs/013-opencode-shepherd/plan.md +204 -0
  95. package/specs/013-opencode-shepherd/spec.md +258 -0
  96. package/specs/013-opencode-shepherd/tasks.md +259 -0
  97. package/src/core/artifact-sessions.ts +835 -0
  98. package/src/core/config.ts +329 -0
  99. package/src/core/discovery.ts +342 -0
  100. package/src/core/herdr.ts +1 -0
  101. package/src/core/host.ts +77 -0
  102. package/src/core/ids.ts +78 -0
  103. package/src/core/lifecycle.ts +1 -0
  104. package/src/core/messaging.ts +1 -0
  105. package/src/core/migration.ts +55 -0
  106. package/src/core/orchestration.ts +1 -0
  107. package/src/core/types.ts +143 -0
  108. package/src/core/unseen-completions.ts +114 -0
  109. package/src/extension/cli.ts +417 -0
  110. package/src/extension/config.ts +1 -0
  111. package/src/extension/settings-ui.ts +296 -0
  112. package/src/extension/shepherd-done.ts +768 -0
  113. package/src/extension/shepherd.ts +2548 -0
  114. package/src/extension/system-prompt.ts +38 -0
  115. package/src/extension/unseen-completions.ts +237 -0
  116. package/src/opencode/actions.ts +794 -0
  117. package/src/opencode/bridge.ts +777 -0
  118. package/src/opencode/display.ts +36 -0
  119. package/src/opencode/fieldnotes.ts +60 -0
  120. package/src/opencode/host.ts +62 -0
  121. package/src/opencode/orphans.ts +162 -0
  122. package/src/opencode/server.ts +458 -0
  123. package/src/runtimes/backend.ts +119 -0
  124. package/src/runtimes/detect.ts +102 -0
  125. package/src/runtimes/hc/hc.ts +527 -0
  126. package/src/runtimes/hc/runtime.ts +1898 -0
  127. package/src/runtimes/herdr/herdr.ts +912 -0
  128. package/src/runtimes/herdr/lifecycle.ts +1712 -0
  129. package/src/runtimes/herdr/messaging.ts +703 -0
  130. package/src/runtimes/herdr/orchestration.ts +1583 -0
  131. package/src/runtimes/herdr/runtime.ts +224 -0
  132. package/src/runtimes/runtime.ts +133 -0
  133. package/src/runtimes/settle-observations.ts +114 -0
  134. package/test/fixtures/context-project/AGENTS.md +2 -0
  135. package/test/fixtures/home/.agents/agents/same.md +6 -0
  136. package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
  137. package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
  138. package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
  139. package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
  140. package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
  141. package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
  142. package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
  143. package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
  144. package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
  145. package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
  146. package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
  147. package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
  148. package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
  149. package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
  150. package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
  151. package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
  152. package/test/fixtures/proj/.pi/agents/same.md +6 -0
  153. package/test/helpers/fake-clock.mjs +39 -0
  154. package/test/helpers/feature-contracts.mjs +44 -0
  155. package/test/helpers/test-utils.mjs +44 -0
  156. package/test/verify-artifact-sessions.mjs +258 -0
  157. package/test/verify-backend.mjs +297 -0
  158. package/test/verify-child-mislabel.mjs +135 -0
  159. package/test/verify-child-surface.mjs +321 -0
  160. package/test/verify-cli.mjs +197 -0
  161. package/test/verify-command-ux.mjs +100 -0
  162. package/test/verify-compat.mjs +32 -0
  163. package/test/verify-cross-host-notes.mjs +128 -0
  164. package/test/verify-delegate.mjs +161 -0
  165. package/test/verify-detect.mjs +151 -0
  166. package/test/verify-discovery.mjs +239 -0
  167. package/test/verify-done-nudge.mjs +238 -0
  168. package/test/verify-effective-prompt.mjs +98 -0
  169. package/test/verify-hc-matrix.mjs +246 -0
  170. package/test/verify-hc-poll.mjs +260 -0
  171. package/test/verify-host-docs.mjs +35 -0
  172. package/test/verify-host-impact.mjs +49 -0
  173. package/test/verify-ids.mjs +141 -0
  174. package/test/verify-launch.mjs +183 -0
  175. package/test/verify-message-routing.mjs +560 -0
  176. package/test/verify-messaging.mjs +303 -0
  177. package/test/verify-migration-notice.mjs +69 -0
  178. package/test/verify-multi-wait.mjs +42 -0
  179. package/test/verify-opencode-display.mjs +47 -0
  180. package/test/verify-opencode-fieldnotes.mjs +121 -0
  181. package/test/verify-opencode-notice.mjs +77 -0
  182. package/test/verify-opencode-nudge.mjs +116 -0
  183. package/test/verify-opencode-orphans.mjs +160 -0
  184. package/test/verify-opencode-surface.mjs +107 -0
  185. package/test/verify-packaging.mjs +82 -0
  186. package/test/verify-parent-surface.mjs +118 -0
  187. package/test/verify-phase0.mjs +95 -0
  188. package/test/verify-registry.mjs +124 -0
  189. package/test/verify-rename-migration.mjs +111 -0
  190. package/test/verify-rendering.mjs +379 -0
  191. package/test/verify-session-boundary.mjs +146 -0
  192. package/test/verify-settings.mjs +260 -0
  193. package/test/verify-stale-wait.mjs +339 -0
  194. package/test/verify-status-widget.mjs +377 -0
  195. package/test/verify-status.mjs +172 -0
  196. package/test/verify-task-completion.mjs +156 -0
  197. package/test/verify-task-failures.mjs +201 -0
  198. package/test/verify-task-mislabel.mjs +143 -0
  199. package/test/verify-task-registry.mjs +194 -0
  200. package/test/verify-task-watchers.mjs +217 -0
  201. package/test/verify-tool-schemas.mjs +120 -0
  202. package/test/verify-unseen-completions.mjs +1211 -0
  203. package/test/verify-watchers.mjs +181 -0
@@ -0,0 +1,110 @@
1
+ # pi-shepherd — Implementation Plan
2
+
3
+ pi-shepherd is a Herdr-native pi extension for explicit agent lifecycle
4
+ orchestration **and asynchronous tracked-task delegation**. There is no
5
+ subprocess fallback; coordination between agents happens over a parent-
6
+ mediated message broker.
7
+
8
+ ## Architecture
9
+
10
+ ```
11
+ index.ts extension entry and /shepherd command
12
+ src/core/discovery.ts fresh agent discovery and frontmatter parsing
13
+ src/core/orchestration.ts opaque serializable handles and in-memory registries
14
+ src/core/lifecycle.ts spawn, prompt, wait, status, and close primitives
15
+ src/core/herdr.ts Herdr CLI, launch, pane, and ownership helpers
16
+ src/core/artifact-sessions.ts durable parent-bound session, note, and fieldnotes persistence
17
+ src/extension/shepherd.ts umbrella control tool plus separate lifecycle tools
18
+ src/extension/shepherd-done.ts in-tab completion extension
19
+ .agents/agents/ bundled pi-format and shared-format agents
20
+ ```
21
+
22
+ ## Public lifecycle API
23
+
24
+ - `shepherd_spawn({ agent, ...options })` creates an idle persistent agent and
25
+ submits no task.
26
+ - `shepherd_delegate({ target, task, timeout? })` starts a **tracked task** on
27
+ an agent and returns a task id without waiting. Delegation is the preferred
28
+ way to assign work that may need to survive peer replies.
29
+ - `shepherd_message({ target, message, ... })` sends an asynchronous,
30
+ parent-mediated message to the parent or to an owned agent. With
31
+ `expectsReply` it opens a tracked reply request: the sender's task enters
32
+ `waiting` (its pi process may go idle) until a matching reply, a
33
+ `shepherd_done`, or the reply deadline.
34
+ - `shepherd_done` (child-side) is the only normal successful completion
35
+ signal for a tracked task; idle/`agent_end`/`agent_settled` never settle a
36
+ task.
37
+ - `shepherd_watch({ id })` compatibility wait: task ids (preferred) or legacy
38
+ prompt ids; a wait timeout bounds the wait only.
39
+ - `shepherd_watch({ id })` non-blocking task-watcher; completions arrive as
40
+ follow-ups.
41
+ - `shepherd_status({ id })` performs non-mutating inspection; reports
42
+ process state and task state independently.
43
+ - `shepherd_close({ id })` explicitly terminates an owned agent, cancels its
44
+ active tracked task (and unresolved prompt), and clears pending requests.
45
+ - `shepherd_read({ name, lines?, source? })` reads recent terminal output.
46
+ - `shepherd_prompt({ id, message })` is a **deprecated** one-turn
47
+ compatibility path (see docs/guides/tool-reference.md).
48
+
49
+ The umbrella `shepherd` control tool handles `agents`, `herd`, and `prune` and
50
+ contains the shared lifecycle and fieldnotes guidance. The `/shepherd` command
51
+ supports the human-facing `agents`, `herd`, `spawn`, `status`, `read`, and
52
+ `settings` actions.
53
+
54
+ Parallel work and chains are caller composition, not first-class workflow
55
+ modes. A one-shot tracked operation is
56
+ `shepherd_spawn + shepherd_delegate + shepherd_watch + shepherd_close`.
57
+
58
+ ## Completed implementation
59
+
60
+ - Agent, task, prompt, and message references are opaque session-scoped ids exposed in tool arguments and result text. Full handle objects remain internal registry state.
61
+ - Tracked tasks are independent of Herdr process state: `running`,
62
+ `waiting`, and the terminal states (`completed`, `blocked`, `failed`,
63
+ `cancelled`, `timed_out`) live in the lifecycle registry. Only
64
+ `shepherd_done` (or explicit failure/cancellation/timeout) settles a task;
65
+ a child's idle or `agent_end` never does.
66
+ - Cross-agent communication is parent-mediated: the parent broker routes
67
+ envelopes between owned agents with provenance (sender, thread, replyTo)
68
+ and delivers them as queued follow-ups (`followUp`) or urgent input
69
+ (`steer`). Request/reply correlation uses `replyTo` == pending reply
70
+ `messageId`; one outstanding request per task is the initial policy.
71
+ - Stale-wait reminders are informational only: at most one per waiting
72
+ episode, `triggerTurn: false`, and the reply deadline remains the only
73
+ mechanism that settles a stale wait to `blocked`.
74
+ - Registries enforce one unresolved prompt per agent, idempotent settlement, and
75
+ deterministic cancellation.
76
+ - Persistent Herdr tabs launch pi with discovered system prompt, tools, model,
77
+ cwd, and no initial user message.
78
+ - Prompt submission is non-blocking and requires Herdr detection.
79
+ - Wait ignores pre-submit idle state, tracks post-submit transitions, returns
80
+ structured per-prompt results, and supports concurrent multi-wait.
81
+ - Status and close use lifecycle ids and retain the created-pane ownership invariant.
82
+ - Project agent scope remains opt-in and trust-gated.
83
+ - Legacy `delegate`, workflow modes, and `subagent.ts` have been removed.
84
+ - When enabled, durable notes are allocated once per parent pi session/project
85
+ binding, with one fieldnotes collection and distinct per-prompt note files.
86
+ - Fieldnotes can be disabled in settings; the setting is snapshotted when a
87
+ parent pi session starts.
88
+ - README and focused registry/multi-wait tests document and verify the API.
89
+
90
+ ## Verification
91
+
92
+ Run:
93
+
94
+ ```bash
95
+ npm test
96
+ ```
97
+
98
+ Live Herdr checks cover idle spawn, non-blocking prompt, wait/result recovery,
99
+ parallel multi-wait, iterative prompting, cancellation on close, focus
100
+ preservation, and ownership protection.
101
+
102
+ ## Security invariants
103
+
104
+ - User agent discovery is the default.
105
+ - Project-controlled agent definitions require explicit scope and confirmation.
106
+ - Agents have the host user's normal pi tool permissions.
107
+ - Background placement uses `--no-focus`.
108
+ - Only panes recorded in the pi-shepherd created-pane registry may be closed.
109
+ - Launch/session resources are removed only after the child pane is gone.
110
+ - Note sessions are retained and never automatically cleaned up.
@@ -0,0 +1,163 @@
1
+ # Historical Plan: Scoped Settings — user config + project config override
2
+
3
+ Status: superseded by [Per-workspace self-contained Shepherd settings](../../specs/005-per-workspace-settings/spec.md).
4
+
5
+ This document records the implemented delta-based design that preceded the
6
+ current per-workspace model. Do not use its `settingsScope` or project-delta
7
+ semantics for new work. The active design uses a project-owned boolean
8
+ `projectScope`, self-contained project files, and a user-owned
9
+ `confirmProjectAgents` security setting.
10
+
11
+ Implementation note: the user file lives in the pi agent dir as resolved by
12
+ `getAgentDir()` (`~/.pi/agent` by default, `PI_CODING_AGENT_DIR` overridable)
13
+ rather than a hard-coded home path.
14
+
15
+ ## 1. Problem
16
+
17
+ All persisted settings live in a single user-level file
18
+ (`~/.pi/agent/pi-shepherd/settings.json`), so a project cannot carry its own
19
+ shepherd defaults (timeout, keepOpen, stayOpen, …). There is also no
20
+ project-level config surface at all, despite projects already carrying
21
+ `.pi/`/`.agents/` agent dirs and `.shepherd/sessions/` fieldnotes.
22
+
23
+ ## 2. Decisions (agreed)
24
+
25
+ 1. **Scope top-level item.** The settings menu (`/shepherd settings`) gains a
26
+ first, top-level entry: **Settings scope** — `user` (default) | `project`.
27
+ 2. **Project file path.** `.shepherd/config.json` in the current working
28
+ directory (same `.shepherd` root fieldnotes already use; anchored at cwd,
29
+ no walk-up — consistent with `artifact-sessions.ts`).
30
+ 3. **File creation.** Switching scope to `project` when
31
+ `.shepherd/config.json` does not exist creates it (as `{}` — empty delta,
32
+ no overrides) and sends a notification that the file was created.
33
+ 4. **Override semantics.** The project file is a **delta**: fields override
34
+ the user layer one by one. Only fields that actually differ from the user
35
+ layer are written to the project file ("write only changed").
36
+ 5. **Menu writes follow the current scope.** Scope is `user` → edits go to
37
+ the user file; scope is `project` → edits go to the project file.
38
+ 6. **All fields are project-overridable** — except `settingsScope` itself,
39
+ which by definition lives only in the user file (it is the pointer to
40
+ where to look; a project file cannot select its own scope).
41
+ 7. **Naming.** "Settings" is the interactive menu; the persisted artifacts are
42
+ *config*. Rename user file `settings.json` → `config.json` (one-shot
43
+ migration), module `settings.ts` → `config.ts`. Project file is
44
+ `.shepherd/config.json`.
45
+
46
+ ## 3. Design
47
+
48
+ ### 3.1 Storage core — `src/extension/settings.ts` → `src/extension/config.ts`
49
+
50
+ - New type `ConfigScope = "user" | "project"`. `ShepherdSettings` gains
51
+ `settingsScope: ConfigScope`, default `"user"` (user-file-only field).
52
+ - `userConfigFile()` → `~/.pi/agent/pi-shepherd/config.json` (same dir as
53
+ `created-panes.json`).
54
+ - `projectConfigFile(cwd)` → `path.resolve(cwd, ".shepherd", "config.json")`.
55
+ - One-time migration, same pattern as the existing timeout ms→min migration
56
+ in `loadSettings()`:
57
+ - `config.json` missing AND old `~/.pi/agent/pi-shepherd/settings.json`
58
+ exists → move the old file to `config.json`, silently.
59
+ - Both exist → `config.json` wins; old file left in place (no deletion).
60
+ - Only old file / neither / parse errors behave as today (defaults).
61
+ - `loadSettings(cwd?)`:
62
+ 1. Load user layer: file (or defaults), validated/merged, **mtime-cached
63
+ per file path** (replaces the single global cache).
64
+ 2. Resolve effective scope from the user layer's `settingsScope`.
65
+ 3. If `project` and `cwd` given: read `.shepherd/config.json`, validate each
66
+ known field, overlay over the user layer. `{}` / missing / unreadable →
67
+ pure user layer. `settingsScope` in a project file is ignored (the merge
68
+ function simply never applies it).
69
+ 4. Return merged `ShepherdSettings`.
70
+ - `saveSettings(next: ShepherdSettings, scope: ConfigScope = "user",
71
+ projectRoot?: string): { file: string, created: boolean }`:
72
+ - `user`: write the full object (today's behavior; `settingsScope`
73
+ always written).
74
+ - `project`: diff `next` against the current user layer; write only the
75
+ fields whose values differ (`{}` when all equal). Create the file (and
76
+ `.shepherd/` dir) if missing; `created` is true when a new file is born.
77
+ The `settingsScope` field is never written to the project file.
78
+ - Keep the mtime cache in sync after writes.
79
+ - `initializeSessionSettings(cwd?)` — the fieldnotes session snapshot reads
80
+ the merged, cwd-aware value (a session started inside a project sees
81
+ project-overridden fieldnotes state).
82
+
83
+ ### 3.2 Settings menu — `src/extension/settings-ui.ts`
84
+
85
+ - New first `SettingItem`: **Settings scope** (`user`/`project`, ≤ 30-char
86
+ label), description notes that project values override user values.
87
+ - Menu opens with `ctx.cwd`; displayed values are the merged ones when scope
88
+ is `project`, so the menu shows exactly what the system is using.
89
+ - Change handling on the list `onChange`:
90
+ - **scope change** → always saved to the **user** file. If the new scope is
91
+ `project` and the project file didn't exist → create it (`{}` or the
92
+ current delta) and notify: `Config created at .shepherd/config.json`.
93
+ - **any other field** → saved to the **current scope's** file (user or
94
+ project delta). Project saves reuse the same created-notification when
95
+ the file is born.
96
+ - Existing notifications for `fieldnotes` (next-session effect) and
97
+ `agentScope` (repo-controlled notice) are preserved.
98
+ - Wrap saves in try/catch → error-level notification on failure (e.g.
99
+ read-only project directory) instead of an uncaught throw inside the TUI.
100
+
101
+ ### 3.3 Thread `cwd` into every `loadSettings()` call
102
+
103
+ | Call site | cwd source |
104
+ |---|---|
105
+ | `src/core/lifecycle.ts` `startAgent` | `ctx.cwd` (already available) |
106
+ | `src/extension/shepherd.ts` `doAction` (spawn/prompt/wait/agents) | `ctx.cwd` |
107
+ | `src/extension/settings-ui.ts` `openSettings` | `ctx.cwd` |
108
+ | `src/extension/config.ts` `initializeSessionSettings` | `ctx.cwd` in `session_start` |
109
+ | `index.ts` widget render + command arg completions | `shepherdCommandCwd` |
110
+
111
+ No change to tool parameters: scope remains implicit from the config files,
112
+ exactly as `agentScope` resolution works today.
113
+
114
+ ## 4. Behavior notes (accepted)
115
+
116
+ - Stale project deltas persist: if the project file overrides `keepOpen:
117
+ true` and you later change `keepOpen` to `false` in the user scope, the
118
+ project layer still wins while scope is `project`. Inherent to override
119
+ semantics.
120
+ - The merged result, not the raw files, is what tools/lifecycle consume; a
121
+ model-facing call that passes explicit args still wins over both layers
122
+ (no change).
123
+ - Editing `.shepherd/config.json` by hand takes effect immediately (mtime
124
+ cache), like the user file today.
125
+
126
+ ## 5. Tests (`npm test`)
127
+
128
+ `test/verify-settings.mjs` (renamed expectations to the new file names):
129
+ - Project overlay: user `fieldnotes: true` + project `{ "fieldnotes": false }`
130
+ → merged `false`; untouched fields stay user values.
131
+ - Delta-only writes: saving one changed field in project scope writes only
132
+ that field; unchanged fields are absent from the file; `{}` when nothing
133
+ differs.
134
+ - Scope switch: first change with scope `project` when no file exists →
135
+ created flag set, file exists, content is the delta (initially `{}`).
136
+ - `settingsScope` in a project file is ignored.
137
+ - Migration: old `~/.pi/agent/pi-shepherd/settings.json` without `config.json`
138
+ → moved to `config.json`, values intact, old name gone. Both exist →
139
+ `config.json` wins, old name untouched.
140
+ - Fieldnotes session snapshot honors the merged (project-overridden) value.
141
+
142
+ `test/verify-command-ux.mjs`: existing `settings.json` fixture → `config.json`.
143
+
144
+ Live check (this repo): `/shepherd settings` → toggle scope `project` →
145
+ `.shepherd/config.json` appears (with the creation notification) → change a
146
+ field → file contains only the delta → toggle back + delete → user values
147
+ restore.
148
+
149
+ ## 6. Docs
150
+
151
+ - README/docs mentions of `settings.json` → user `~/.pi/agent/pi-shepherd/
152
+ config.json` + project `.shepherd/config.json`, with the override model in
153
+ one short paragraph.
154
+ - `AGENTS.md`: short note on the two-file config model (user layer + project
155
+ delta; `settingsScope` user-only).
156
+ - Module rename `settings.ts` → `config.ts`; update the file-header comment
157
+ and all imports (9 call sites listed in §3.3 plus tests).
158
+
159
+ ## 7. Out of scope
160
+
161
+ - Per-workspace (multi-root) config; config in `.pi/` instead of `.shepherd/`.
162
+ - A config "reload" command or file-watcher (mtime cache suffices).
163
+ - Restricting which fields the project layer may override (decided: all).
@@ -0,0 +1,278 @@
1
+ # Plan: Split the Shepherd Tool Surface
2
+
3
+ Status: in progress — Phases 0–5 complete (verified 2026-08-26). Next: Phase 6.
4
+ Related discussion: constrained-sampling backends drop arguments on bare-`anyOf` tool schemas
5
+
6
+ ## 1. Problem
7
+
8
+ `shepherd.ts` defines the model-facing tool parameters as a TypeBox discriminated
9
+ union:
10
+
11
+ ```ts
12
+ export const ShepherdParams = Type.Union([HerdParams, AgentsParams, StartParams, ...], {...});
13
+ ```
14
+
15
+ The emitted JSON Schema has **no root `"type": "object"`** — only `{"anyOf": [...],
16
+ "description": "..."}`. Pi passes `tool.parameters` to providers essentially unchanged.
17
+ Backends that use grammar/schema-constrained decoding of tool-call arguments (observed
18
+ with `stealth/ox-alpha` via OpenRouter) have no allowed properties at the top level and
19
+ emit `{}` for every call, unrecoverably. Models served behind soft-guidance APIs
20
+ (Claude/GPT first-party) work fine, which masks the bug.
21
+
22
+ Secondary issues surfaced by the investigation:
23
+
24
+ - Cross-field rules (`wait` requires a prompt `id`) are enforced by JSON Schema today, but
25
+ any flattening loses that unless handled explicitly.
26
+ - The unified conceptual narrative (sheep, ids, lifecycle ordering) lives inside the
27
+ single tool description, coupling "what shepherd is" to "how one tool is shaped".
28
+ - The existing `/shepherd` command duplicates logic (`agents`/`herd`/`start` re-implement
29
+ what `doAction` already does) instead of delegating to the same core.
30
+
31
+ ## 2. Goals
32
+
33
+ 1. No bare-`anyOf` root anywhere on the wire → works on constrained backends.
34
+ 2. Declarative requiredness (`id: required`) via separate flat-schema tools.
35
+ 3. Preserve user ergonomics: `/shepherd spawn worker` (renamed from `start`) keeps working, gains coverage.
36
+ 4. Single source of truth for behavior: both tools and command delegate to core.
37
+ 5. Unified meta-description ("subagent framework for native Herdr orchestration") kept
38
+ in one obvious place.
39
+
40
+ ## Non-goals
41
+
42
+ - No changes to Herdr integration, discovery precedence, or pane ownership invariants.
43
+ - No pi-core changes (schema normalization stays out of scope).
44
+ - No renaming of persisted settings or artifact-session behavior.
45
+
46
+ ## 3. Target architecture
47
+
48
+ ```
49
+ ┌──────────── core: doAction() / lifecycle.ts ────────────┐
50
+ │ single source of truth for behavior │
51
+ ▼ ▼ ▼
52
+ model surface (flat tools) user surface (/shepherd cmd) future RPC?
53
+ ├─ shepherd (herd|agents|prune) ├─ agents, herd, spawn (existing, renamed)
54
+ ├─ shepherd_spawn (agent, options…) ├─ status, read (new)
55
+ ├─ shepherd_prompt (id, message, timeout) └─ prompt/wait/close (new, see §5)
56
+ ├─ shepherd_watch (id[], timeout)
57
+ ├─ shepherd_status (id)
58
+ ├─ shepherd_close (id)
59
+ └─ shepherd_read (name, lines, source)
60
+ ```
61
+
62
+ Schema fragments shared across tools: opaque agent/prompt id schemas, timeout/lines/source optionals.
63
+
64
+ ## 4. Phases
65
+
66
+ ### Phase 0 — Baseline & guardrails
67
+
68
+ - [x] Capture current behavior: run `npm test`; record pass set. ✅ All 8 suites pass (schemas:test was added as the 8th).
69
+ - [x] Add a schema-shape regression test: assert every registered tool's root JSON Schema
70
+ has `"type": "object"` (fails today for `shepherd`; becomes the invariant).
71
+ ✅ `test/verify-tool-schemas.mjs` added as `schemas:test`; wired into the default
72
+ `test` chain (runs first) and green now that the union is gone. Phase 3 adds the
73
+ six new tools to the checked list (placeholders already in the file).
74
+ - [ ] Optional: snapshot the current serialized `ShepherdParams` for diffing. (skipped — the flat schema is small enough to verify by eye)
75
+
76
+ Files: `test/verify-tool-schemas.mjs` (new), `package.json` (wire test if needed).
77
+
78
+ ### Phase 1 — Unify the core path
79
+
80
+ Make `doAction()` the single entry so tools and command can never diverge.
81
+
82
+ - [x] Refactor `/shepherd` handler branches (`agents`, `herd`, `start`) to construct args
83
+ objects and call `doAction()`, rendering via a small result-to-notification helper,
84
+ instead of calling `discoverAgents`/`listHerdrAgents`/`startAgent` directly.
85
+ ✅ Done via `runCommandAction()` in `index.ts`; results surface as notifications.
86
+ - [x] Keep `settings` branch command-only (no model-facing equivalent needed).
87
+ - [x] Extract `parentArtifactSessionForCommand` reuse so command and tool resolve
88
+ artifact sessions identically.
89
+ ✅ Via the "explicit `artifactSession` wins" pattern: the command pre-resolves
90
+ tolerantly and passes the value, `doAction` honors an explicit value before
91
+ resolving/requiring the parent session itself.
92
+
93
+ Acceptance: `/shepherd agents|herd|start <agent>` behave identically before/after;
94
+ command tests still pass.
95
+
96
+ Files: `index.ts`, possibly new `cli.ts` for arg parsing/render helpers.
97
+
98
+ ### Phase 2 — Flatten the retained `shepherd` tool
99
+
100
+ Reduce `shepherd` to the control plane + inspection actions.
101
+
102
+ - [ ] Replace `Type.Union([...])` with one `Type.Object`: ✅
103
+ - `action`: enum `['herd','agents','prune']`, plus optional `agentScope` (shared field for `agents`).
104
+ - description: meta-narrative + compact per-action table. ✅
105
+ - No per-action fields remain (`read` moved to `shepherd_read` in Phase 3). ✅
106
+ - The old union survives internally as `AnyShepherdUnion`; `ShepherdArgs`
107
+ (= its Static type) remains the core doAction signature so command and
108
+ future tools keep full-typed access to every verb.
109
+ - [ ] Runtime validation is trivial at this point (enum-only); keep the same
110
+ friendly text-result style used elsewhere. ✅ (doAction switch unchanged)
111
+ - [x] Update `prepareShepherdArguments`: kept as-is (string-coercion recovery for
112
+ handles, booleans, integers); reused by the Phase 3 tools. ✅
113
+ - [x] Update `renderCall`/`renderResult` — they key off `args.action` and kept working.
114
+
115
+ Acceptance: schema test from Phase 0 passes ✅; `npm test` green ✅; serialized
116
+ schema confirmed flat (`type: object`, enum action) ✅.
117
+
118
+ Files: `shepherd.ts`. ✅ Done
119
+
120
+ ### Phase 3 — Extract lifecycle tools
121
+
122
+ One registration helper, six declarative tools. All roots are plain objects.
123
+
124
+ - [x] Generalize `registerShepherdTool` into `registerShepherdTools(pi)` registering:
125
+ - `shepherd_spawn`: `agent` (required), `label` (required), and optional
126
+ `placement` (`pane_right`, `pane_down`, `tab`, or `workspace`), `cwd`, and
127
+ `model`. Agent scope, project approval, and system-prompt behavior come
128
+ from settings and the discovered agent definition. ✅ (deliberately no
129
+ `timeout`: startup readiness uses fixed internal grace periods; timeout only
130
+ applies to prompts/waits — see the start-case comment in `doAction`)
131
+ - `shepherd_prompt`: `id` (required agent id), `message` (required), `timeout` ✅
132
+ - `shepherd_watch`: `id` (required prompt id or array of prompt ids), `timeout` ✅
133
+ - `shepherd_status`: `id` (required agent id) ✅
134
+ - `shepherd_close`: `id` (required agent id) ✅
135
+ - `shepherd_read`: `name` (required), `lines`?, `source`? ✅
136
+ - Note: the core action `start` was renamed to `spawn` (`SpawnParams`) to match the
137
+ tool naming scheme; the `/shepherd` command verb was renamed in Phase 4.
138
+ - [x] Share lifecycle id, timeout, and completion-state schemas across definitions.
139
+ ✅ Originally derived with `Type.Omit(<LifecycleParams>, ['action'])`; superseded by the
140
+ AGENTS.md convention that every registration spells out its fields inline, so each
141
+ tool registration now declares its full `Type.Object` directly (identical fields and
142
+ descriptions; the shared `*Params` schemas in `types.ts` remain the internal
143
+ union/`doAction` contract only).
144
+ - [x] Each tool delegates to `doAction({action: '<verb>', ...params}, ...)`.
145
+ ✅ Via a shared `executeShepherd(label, args, ctx, ...)` wrapper (Herdr gate +
146
+ try/catch to a friendly text result).
147
+ - [x] Per-tool `description`: short, operational; cross-references siblings
148
+ ("Pass the agent id returned by shepherd_spawn" etc.). ✅
149
+ - [x] `renderCall`: per-tool CLI-style call preview reusing `shepherdCallPreview`
150
+ internals (e.g. `shepherd_spawn scout --cwd …`), plus a shared `renderToolResult`. ✅
151
+ - [x] Split `promptSnippet`/`promptGuidelines`: lifecycle tools share one snippet line;
152
+ the control tool keeps the narrative + guidelines; the old `Workflow:` guideline
153
+ line was dropped (superseded by per-tool descriptions). Full narrative relocation
154
+ remains Phase 5.
155
+
156
+ Acceptance: schema test passes for all seven tools ✅; `npm test` green ✅; live
157
+ end-to-end verified under a running Herdr session: idle spawn, non-blocking prompt,
158
+ wait (status `done`), status, close, read-after-close, and prune ✅. (Full multi-wait /
159
+ close-cancellation live matrix stays in Phase 7 alongside the constrained-backend check.)
160
+
161
+ Files: `shepherd.ts`, `types.ts` (`SpawnParams`), `index.ts`. ✅ Done
162
+
163
+ ### Phase 4 — Extend the `/shepherd` command
164
+
165
+ Bring the human surface up to parity, scoped sensibly.
166
+
167
+ - [x] Decide blocking policy (recommended): allow quick actions only —
168
+ `status`, `read` join `agents|herd|spawn|settings`; keep `prompt`/`wait`/
169
+ `close` **model-only** initially (they can block minutes or mutate agent state
170
+ mid-conversation). Revisit after real-world use.
171
+ ✅ `status` + `read` are command actions; prompt/wait/close remain model-only.
172
+ - [x] Rename the command verb `start` → `spawn` everywhere (handler branch,
173
+ completions, hints); no alias retained. ✅ (/shepherd list|sheep aliases for
174
+ *agents* remain, as before.)
175
+ - [x] Factor the CLI grammar into `parseShepherdCli(args)` shared with
176
+ `shepherdCallPreview` (parser = inverse of renderer); replace
177
+ `parseStartCommand` with it.
178
+ ✅ Now `cli.ts`: one `OPTION_SPECS` table drives both `parseShepherdCli` (human)
179
+ and `formatShepherdCommand` (tool-call previews, moved out of `shepherd.ts`). A
180
+ quote-aware `tokenizeCli` makes the command split the exact inverse of the
181
+ renderer's JSON quoting, so a rendered line reparses to the same args.
182
+ Covered by the new `cli:test` suite (parses, rejections, round-trips).
183
+ - [x] Extend `getArgumentCompletions`: actions first; for `status`/`read`, complete
184
+ discovered agent names (reuse the pattern already used for `spawn`).
185
+ ✅ Action list now includes `status`/`read`; both also complete live
186
+ agent ids from the session registry; 3-char-prefix candidates
187
+ (`/shepherd spo` → `spawn <agent>`) preserved for spawn/status/read.
188
+ - [x] `status` target resolution: `statusHandleTarget` maps agent name / lifecycle id /
189
+ pane id to the opaque lifecycle id (live-registry lookup, id fallback).
190
+
191
+ Acceptance: `/shepherd status <agent>` prints summary ✅ (live: state `idle` after
192
+ spawn); unknown input prints the updated hint line ✅ (`parseShepherdCli` error +
193
+ Usage); command paths live-verified (status, read w/ quoted args). The full TUI UX
194
+ pass (completions feel, long-running guardrails) stays in Phase 7.
195
+
196
+ Files: `cli.ts` (new), `index.ts`, `shepherd.ts` (preview moved to cli.ts),
197
+ `test/verify-cli.mjs` (new), `package.json` (wire `cli:test`), plan doc.
198
+
199
+ ### Phase 5 — Consolidate the Shepherd narrative
200
+
201
+ Keep general Shepherd knowledge scoped to the umbrella `shepherd` tool rather than
202
+ injecting it into the global parent system prompt.
203
+
204
+ - [x] Make the umbrella `shepherd` tool the documentation and guidance hub for the
205
+ complete Shepherd tool family (`agents`, `herd`, `prune`, `spawn`, `prompt`,
206
+ `wait`, `status`, `close`, and `read`). ✅ Its description and prompt guidelines
207
+ now document the control-plane actions and the full lifecycle.
208
+ - [x] Put shared lifecycle guidance on the umbrella tool: wait for independent work
209
+ concurrently when possible, waiting does not close agents, pass lifecycle ids
210
+ unchanged, and follow the shared `shepherd.md` fieldnotes contract. ✅
211
+ - [x] Keep individual lifecycle tool descriptions short and operational; retain only
212
+ tool-specific usage hints and parameter expectations there. ✅ Removed duplicated
213
+ wait/close lifecycle guidance from the split tool descriptions.
214
+ - [x] Keep the meta-description ("subagent framework for native Herdr orchestration")
215
+ at the top of the umbrella `shepherd` tool description and the command description. ✅
216
+ - [x] Verify that the umbrella Shepherd tools and their guidance are exposed only in
217
+ the parent/orchestrator session, not in launched worker sessions. ✅ Added a
218
+ `PI_SHEPHERD_SESSION` guard around parent-only Shepherd tools, commands, settings,
219
+ and widget registration; the new `parent-surface:test` probes both environments.
220
+ - [x] Do not add a global `before_agent_start` lifecycle-guidance hook unless a later
221
+ use case shows that the umbrella tool's scoped guidance is insufficient. ✅
222
+
223
+ Acceptance: the umbrella `shepherd` tool explains the shared lifecycle and fieldnote
224
+ rules; each split tool explains only its own operation; worker sessions do not receive
225
+ parent orchestration tools or guidance. ✅ `npm test` green.
226
+
227
+ Files: `shepherd.ts`, `index.ts`, `test/verify-parent-surface.mjs`, `package.json`.
228
+
229
+ ### Phase 6 — Docs & conventions
230
+
231
+ - [x] AGENTS.md: replace "the model-facing tool definition is the source of truth"
232
+ with "core semantics live in `doAction()`/`lifecycle.ts`; tools and `/shepherd`
233
+ are thin adapters." ✅
234
+ - [x] `docs/dictionary`: add entries for the split tool names and note the two surfaces. ✅
235
+ - [x] README: update invocation examples (both `shepherd_watch …` and `/shepherd …`),
236
+ add a compatibility note (old `shepherd action=prompt` form is gone). ✅
237
+ - [x] Grep sweep for stale references: `shepherd action=`, `action=start` etc. in
238
+ active docs, skills, prompts, and test fixtures. ✅ Current public docs and
239
+ implementation references are clean; the archived Phase 2 design records
240
+ retain historical `start` terminology, while current Phase 3 artifact examples
241
+ use `spawn`.
242
+
243
+ ### Phase 7 — Verification
244
+
245
+ - [x] `npm test` fully green including the flat-object schema-invariant test. ✅
246
+ - [x] Live Herdr checklist (per AGENTS.md): idle spawn, non-blocking prompt,
247
+ single wait/result, concurrent multi-wait, iterative prompting, status,
248
+ close cancellation, focus preservation, ownership protection. ✅ Verified
249
+ against the running Herdr server; owned panes were closed and stale
250
+ registrations pruned.
251
+ - [x] Constrained-backend check: `stealth/ox-alpha` is no longer available
252
+ (OpenRouter returned 404), so `z-ai/glm-5.3` was used instead; it emitted
253
+ `{"action":"agents"}` and completed the call successfully. ✅
254
+ - [x] Soft-guidance sanity: GPT-style `openai/gpt-5.6-luna` selected the split
255
+ `shepherd_prompt` and `shepherd_read` tools with structured arguments. ✅
256
+ - [x] Command UX pass: added `test/verify-command-ux.mjs` covering partial and
257
+ argument completions, usage/error hints, and spawn status cleanup. ✅
258
+
259
+ ## 5. Open decisions
260
+
261
+ | Question | Decision |
262
+ |---|---|
263
+ | Tool naming scheme | **Resolved:** `shepherd_<verb>`, lifecycle verbs are `spawn`, `prompt`, `wait`, `status`, `close`, `read` |
264
+ | `start` vs `spawn` in `/shepherd` command | **Resolved:** `/shepherd spawn worker` fully replaces `/shepherd start worker`; no alias |
265
+ | `read` placement | **Resolved:** own tool `shepherd_read(name, lines?, source?)` |
266
+ | Lifecycle reference representation | **Resolved:** public tools accept opaque string ids (an array of ids for wait); full handles remain internal, with legacy nested handles migrated in `prepareShepherdArguments` |
267
+ | Old single-tool form | **Resolved:** hard remove; grep sweep covers stragglers |
268
+ | `prompt`/`wait`/`close` via command | **Resolved:** model-only initially; revisit after real-world use |
269
+ | General lifecycle guidance location | **Resolved:** umbrella `shepherd` tool guidance; do not use the global system prompt initially |
270
+
271
+ ## 6. Risk notes
272
+
273
+ - **Largest regression risk**: Phase 3 splitting — mitigated by keeping every tool a
274
+ pure `doAction` delegate and reusing verify scripts unchanged.
275
+ - **Prompt-quality risk**: models accustomed to one tool may mis-select between
276
+ `prompt`/`wait`; mitigated by cross-referencing descriptions + umbrella-tool guidance.
277
+ - **Doc drift**: two surfaces double the places to update; the grep sweep in Phase 6 is
278
+ the safety net.
@@ -0,0 +1,26 @@
1
+ # Shepherd Concept Dictionary
2
+
3
+ - **Shepherd**: The main orchestrator agent. The main pi session running the pi-shepherd extension. The shepherd is responsible for managing the lifecycle of his herd of sheep.
4
+ - **Sheep**: Are agents created by the shepherd. Also called a subagent in other contexts. Sheep are the workers that perform tasks assigned by the shepherd. Each with a unique role defined by their markdown file.
5
+ - **Herd**: The collection of sheep managed by the shepherd. The herd can consist of multiple sheep, each with their own unique role and responsibilities. A herd is tied to the shepherd's pi session.
6
+ - **Fieldnotes**: A collection of notes tied to the session. in other frameworks this are sometimes called artifacts.
7
+ - **Note**: A single note in the fieldnotes. Each note belongs to a specific sheep or shepherd. Notes are used to by its owner to track and convey information about their work, progress, and observations. The Shepherd´s notes are used to track the overall progress of the herd and to provide guidance and feedback to future sheep. Notes can be created, updated, and deleted by their owner. Notes can be shared with other sheep or the shepherd for collaboration and feedback.
8
+ - **Sheep's note**: A note created by a sheep to track its work, observations, and progress, and to provide information for the shepherd and other sheep.
9
+ - **Shepherd's note**: A note created by the shepherd to track the overall progress of the herd and to provide guidance, feedback, and a map to all present and future sheep.
10
+ - **Session**: A session is tied to the shepherd's pi session and is used to track the state of the herd and its sheep.
11
+ - **Control-plane tool**: The model-facing `shepherd` tool. It handles cheap meta-actions: `agents`, `herd`, and `prune`, and serves as the guidance hub for the Shepherd tool family.
12
+ - **Lifecycle tools**: The separate model-facing tools `shepherd_spawn`, `shepherd_delegate`, `shepherd_message`, `shepherd_watch`, `shepherd_status`, `shepherd_close`, and `shepherd_read`, plus the deprecated `shepherd_prompt`. Each has a flat object schema and delegates to the shared `doAction()` core.
13
+ - **Model-facing surface**: The structured `shepherd` control tool plus the six `shepherd_<verb>` lifecycle tools. Lifecycle tools accept opaque scalar ids; the provider may wrap their argument object in its own transport envelope.
14
+ - **Command surface**: The human `/shepherd` command. It supports `agents`, `herd`, `spawn`, `status`, `read`, and `settings`; prompt/close remain model-only for now.
15
+ - **Agent id**: An opaque, session-scoped id returned by `shepherd_spawn` that identifies an owned agent. It is distinct from any Herdr pane id and is accepted by `shepherd_prompt`, `shepherd_status`, and `shepherd_close`.
16
+ - **Prompt id**: An opaque, session-scoped id returned by the deprecated `shepherd_prompt` that identifies one submitted child turn. It is accepted by `shepherd_watch` on the legacy path.
17
+ - **Task**: The tracked unit of delegated work. A task has a state (`created`, `running`, `waiting`, `completed`, `blocked`, `failed`, `cancelled`, `timed_out`) that is independent of the Herdr process state. Only `shepherd_done` or an explicit failure/cancel/timeout settles a task; an idle or ended child process never does.
18
+ - **Task id**: An opaque, session-scoped id returned by `shepherd_delegate`. It is the correlation key for task watchers, tracked replies, and `shepherd_done`.
19
+ - **Message**: An asynchronous, parent-mediated envelope between Shepherd and owned agents (or between agents in a shared project). A message is not a task and does not allocate a fieldnote on its own.
20
+ - **Message id**: An opaque, session-scoped id returned when a message is accepted. The agent answering a tracked request echoes it as `replyTo` so the reply correlates with the request.
21
+ - **Tracked reply request**: The state opened when a message with `expectsReply` is delivered to a task-owned agent. The sender's task enters `waiting` until a matching reply, a `shepherd_done`, close, or the reply deadline (which settles the task to `blocked`).
22
+ - **Waiting task (idle child)**: A task in `waiting` whose Herdr process is `idle` because its pi turn ended. Status and the TUI widget keep it visible, render the elapsed wait and the expected recipient, and flag it `stale` after a stale-wait reminder.
23
+ - **Stale-wait reminder**: An informational-only follow-up (no turn trigger) sent at most once per waiting episode after `staleWaitThreshold` minutes with no reply. It never settles the task; the reply deadline remains the only settlement path.
24
+ - **`followUp` / `steer` delivery**: `followUp` queues a message for the next child turn (default); `steer` injects it as urgent input into the agent's active turn.
25
+ - **Internal AgentHandle/PromptHandle/TaskHandle**: Full objects retained inside the lifecycle registry and TypeScript implementation. They are not part of the recommended model-facing protocol.
26
+ - **Parent broker**: The in-parent message channel that routes envelopes between the Shepherd and owned agents, delivers follow-ups, and enforces provenance. It is parent-scoped: children receive a child capability and can only talk through the broker.
@@ -0,0 +1,47 @@
1
+ # Release checklist
2
+
3
+ Shepherd ships as one package with two independent host adapters. Every
4
+ release must say which host(s) it affects and must have run both verification
5
+ harnesses.
6
+
7
+ ## Checklist
8
+
9
+ - [ ] Run `npm test` — this runs `pi-suite:test` **and** `opencode-suite:test`.
10
+ A release with either suite red does not ship.
11
+ - [ ] Determine host impact for the release range:
12
+ `npm run host-impact -- <previous-tag>..HEAD`
13
+ (or `npm run host-impact -- --files a,b,c` for an uncommitted set).
14
+ - [ ] Write release notes with an explicit **Pi impact** and **OpenCode impact**
15
+ line. Use `none` when a host is untouched — do not leave it implicit.
16
+ - [ ] If impact is Pi-only, verify the range has zero `src/opencode/` edits;
17
+ if OpenCode-only, verify zero `src/extension/`, `index.ts`, or Pi entry
18
+ edits. Shared `src/core/`, `src/runtimes/`, packaging, and docs changes
19
+ are cross-host and must be called out for both.
20
+ - [ ] For the farewell/rename pair, publish the **new package first** so the
21
+ migration pointer is never a 404:
22
+ 1. Publish `@luminascale/shepherd@<new-version>` (`0.6.0` for the rename).
23
+ 2. Publish the final old-name release from a short-lived release branch
24
+ or worktree that restores `"name": "@luminascale/pi-shepherd"` and
25
+ sets `0.5.2`. Its notice is gated by a per-host marker file and is
26
+ never emitted in a child sheep process.
27
+ 3. Deprecate the old name with a pointer:
28
+ `npm deprecate @luminascale/pi-shepherd@0.5.2 "Moved to @luminascale/shepherd"`.
29
+ T018 still means the old name gets its final notice-bearing release and
30
+ is deprecated; T019 is the new package name. The user-facing ordering
31
+ requirement is that the pointer target exists before the pointer ships.
32
+ - [ ] Publish and confirm the install path from each host's own docs:
33
+ `pi install npm:<package>` and the OpenCode `plugins` entry.
34
+
35
+ ## Host impact notes template
36
+
37
+ ```markdown
38
+ ## <version>
39
+
40
+ - Pi impact: <none | summary>
41
+ - OpenCode impact: <none | summary>
42
+ - Shared/engine impact: <none | summary>
43
+ - Verification: npm test (Pi + OpenCode suites) — pass
44
+ ```
45
+
46
+ `npm run host-impact` classifies changed paths so the notes can be filled in
47
+ from evidence rather than memory.