@luminascale/shepherd 0.0.0-stage → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (204) 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 +397 -2
  16. package/docs/README.md +26 -0
  17. package/docs/guides/agent-definitions.md +42 -0
  18. package/docs/guides/diagnostics.md +199 -0
  19. package/docs/guides/installation.md +61 -0
  20. package/docs/guides/tool-reference.md +55 -0
  21. package/docs/manual-tests/ping-pong-peer-messaging.md +147 -0
  22. package/docs/plans/agent-labels.md +257 -0
  23. package/docs/plans/architecture.md +110 -0
  24. package/docs/plans/settings-scope.md +163 -0
  25. package/docs/plans/tool-surface-split.md +278 -0
  26. package/docs/reference/dictionary +26 -0
  27. package/docs/releasing.md +47 -0
  28. package/docs/specs/005-agent-messaging-and-task-lifecycle/baseline.md +115 -0
  29. package/docs/specs/005-agent-messaging-and-task-lifecycle/handoff.md +564 -0
  30. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase10-notes.md +109 -0
  31. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase6-notes.md +69 -0
  32. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase7-notes.md +100 -0
  33. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase8-notes.md +127 -0
  34. package/docs/specs/005-agent-messaging-and-task-lifecycle/phase9-notes.md +104 -0
  35. package/docs/specs/005-agent-messaging-and-task-lifecycle/plan.md +1093 -0
  36. package/docs/specs/005-agent-messaging-and-task-lifecycle/spec.md +583 -0
  37. package/docs/specs/005-agent-messaging-and-task-lifecycle/tasks.md +838 -0
  38. package/docs/specs/006-shepherd-tool-rendering/plan.md +175 -0
  39. package/docs/specs/006-shepherd-tool-rendering/spec.md +469 -0
  40. package/index.ts +602 -0
  41. package/package.json +112 -4
  42. package/scripts/capture-system-prompt.mjs +45 -0
  43. package/scripts/extract-pi-system-prompt.mjs +277 -0
  44. package/scripts/host-impact.mjs +74 -0
  45. package/scripts/resolve-agent.mjs +43 -0
  46. package/scripts/show-shepherd-orchestrator.mjs +58 -0
  47. package/scripts/show-shepherd-prompt.mjs +96 -0
  48. package/scripts/verify-suites.mjs +67 -0
  49. package/specs/001-artifacts/spec.md +436 -0
  50. package/specs/002-simplify-agent-orchestration/plan.md +287 -0
  51. package/specs/002-simplify-agent-orchestration/spec.md +323 -0
  52. package/specs/002-simplify-agent-orchestration/tasks.md +212 -0
  53. package/specs/003-orchestrator-session-artifacts/plan.md +396 -0
  54. package/specs/003-orchestrator-session-artifacts/spec.md +453 -0
  55. package/specs/003-orchestrator-session-artifacts/tasks.md +141 -0
  56. package/specs/004-asynchronous-prompt-watchers/plan.md +139 -0
  57. package/specs/004-asynchronous-prompt-watchers/spec.md +202 -0
  58. package/specs/004-asynchronous-prompt-watchers/tasks.md +126 -0
  59. package/specs/005-per-workspace-settings/plan.md +230 -0
  60. package/specs/005-per-workspace-settings/spec.md +368 -0
  61. package/specs/005-per-workspace-settings/tasks.md +178 -0
  62. package/specs/006-dual-runtime-herdr-durable/intent.md +86 -0
  63. package/specs/006-dual-runtime-herdr-durable/journal.md +80 -0
  64. package/specs/006-dual-runtime-herdr-durable/plan.md +242 -0
  65. package/specs/006-dual-runtime-herdr-durable/spec.md +389 -0
  66. package/specs/006-dual-runtime-herdr-durable/tasks.md +199 -0
  67. package/specs/007-unwatched-completion-notice/journal.md +145 -0
  68. package/specs/007-unwatched-completion-notice/plan.md +186 -0
  69. package/specs/007-unwatched-completion-notice/spec.md +284 -0
  70. package/specs/007-unwatched-completion-notice/tasks.md +147 -0
  71. package/specs/008-remote-machine-sheep/intent.md +174 -0
  72. package/specs/008-remote-machine-sheep/journal.md +57 -0
  73. package/specs/008-remote-machine-sheep/prerequisites.md +219 -0
  74. package/specs/009-hc-runtime/intent.md +44 -0
  75. package/specs/009-hc-runtime/plan.md +49 -0
  76. package/specs/009-hc-runtime/spec.md +118 -0
  77. package/specs/009-hc-runtime/tasks.md +62 -0
  78. package/specs/010-unseen-watch-parity/intent.md +57 -0
  79. package/specs/010-unseen-watch-parity/journal.md +172 -0
  80. package/specs/010-unseen-watch-parity/plan.md +74 -0
  81. package/specs/010-unseen-watch-parity/spec.md +191 -0
  82. package/specs/010-unseen-watch-parity/tasks.md +119 -0
  83. package/specs/011-hc-background-poll/intent.md +57 -0
  84. package/specs/011-hc-background-poll/journal.md +95 -0
  85. package/specs/011-hc-background-poll/plan.md +87 -0
  86. package/specs/011-hc-background-poll/spec.md +141 -0
  87. package/specs/011-hc-background-poll/tasks.md +83 -0
  88. package/specs/012-steer-default/intent.md +12 -0
  89. package/specs/012-steer-default/journal.md +40 -0
  90. package/specs/012-steer-default/plan.md +7 -0
  91. package/specs/012-steer-default/spec.md +42 -0
  92. package/specs/012-steer-default/tasks.md +6 -0
  93. package/specs/013-opencode-shepherd/handoff-t011.md +94 -0
  94. package/specs/013-opencode-shepherd/intent.md +59 -0
  95. package/specs/013-opencode-shepherd/plan.md +204 -0
  96. package/specs/013-opencode-shepherd/spec.md +258 -0
  97. package/specs/013-opencode-shepherd/tasks.md +263 -0
  98. package/src/core/artifact-sessions.ts +835 -0
  99. package/src/core/config.ts +329 -0
  100. package/src/core/discovery.ts +342 -0
  101. package/src/core/herdr.ts +1 -0
  102. package/src/core/host.ts +77 -0
  103. package/src/core/ids.ts +78 -0
  104. package/src/core/lifecycle.ts +1 -0
  105. package/src/core/messaging.ts +1 -0
  106. package/src/core/migration.ts +55 -0
  107. package/src/core/orchestration.ts +1 -0
  108. package/src/core/types.ts +143 -0
  109. package/src/core/unseen-completions.ts +114 -0
  110. package/src/extension/cli.ts +417 -0
  111. package/src/extension/config.ts +1 -0
  112. package/src/extension/settings-ui.ts +296 -0
  113. package/src/extension/shepherd-done.ts +768 -0
  114. package/src/extension/shepherd.ts +2548 -0
  115. package/src/extension/system-prompt.ts +38 -0
  116. package/src/extension/unseen-completions.ts +237 -0
  117. package/src/opencode/actions.ts +794 -0
  118. package/src/opencode/bridge.ts +777 -0
  119. package/src/opencode/display.ts +36 -0
  120. package/src/opencode/fieldnotes.ts +60 -0
  121. package/src/opencode/host.ts +62 -0
  122. package/src/opencode/orphans.ts +162 -0
  123. package/src/opencode/server.ts +458 -0
  124. package/src/runtimes/backend.ts +119 -0
  125. package/src/runtimes/detect.ts +102 -0
  126. package/src/runtimes/hc/hc.ts +527 -0
  127. package/src/runtimes/hc/runtime.ts +1898 -0
  128. package/src/runtimes/herdr/herdr.ts +912 -0
  129. package/src/runtimes/herdr/lifecycle.ts +1712 -0
  130. package/src/runtimes/herdr/messaging.ts +703 -0
  131. package/src/runtimes/herdr/orchestration.ts +1583 -0
  132. package/src/runtimes/herdr/runtime.ts +224 -0
  133. package/src/runtimes/runtime.ts +133 -0
  134. package/src/runtimes/settle-observations.ts +114 -0
  135. package/test/fixtures/context-project/AGENTS.md +2 -0
  136. package/test/fixtures/home/.agents/agents/same.md +6 -0
  137. package/test/fixtures/home/.agents/agents/shared-only.md +6 -0
  138. package/test/fixtures/home/.pi/agent/agents/invalid-thinking.md +6 -0
  139. package/test/fixtures/home/.pi/agent/agents/model-empty.md +7 -0
  140. package/test/fixtures/home/.pi/agent/agents/model-explicit.md +7 -0
  141. package/test/fixtures/home/.pi/agent/agents/omit-context-absent.md +5 -0
  142. package/test/fixtures/home/.pi/agent/agents/omit-context-false.md +6 -0
  143. package/test/fixtures/home/.pi/agent/agents/omit-context-invalid.md +6 -0
  144. package/test/fixtures/home/.pi/agent/agents/omit-context-true.md +6 -0
  145. package/test/fixtures/home/.pi/agent/agents/omit-false.md +6 -0
  146. package/test/fixtures/home/.pi/agent/agents/omit-invalid.md +6 -0
  147. package/test/fixtures/home/.pi/agent/agents/omit-pi-docs.md +7 -0
  148. package/test/fixtures/home/.pi/agent/agents/omit-true.md +6 -0
  149. package/test/fixtures/home/.pi/agent/agents/only-user.md +9 -0
  150. package/test/fixtures/home/.pi/agent/agents/same.md +6 -0
  151. package/test/fixtures/proj/.agents/agents/proj-shared.md +6 -0
  152. package/test/fixtures/proj/.pi/agents/project-pi.md +6 -0
  153. package/test/fixtures/proj/.pi/agents/same.md +6 -0
  154. package/test/helpers/fake-clock.mjs +39 -0
  155. package/test/helpers/feature-contracts.mjs +44 -0
  156. package/test/helpers/test-utils.mjs +44 -0
  157. package/test/verify-artifact-sessions.mjs +258 -0
  158. package/test/verify-backend.mjs +297 -0
  159. package/test/verify-child-mislabel.mjs +135 -0
  160. package/test/verify-child-surface.mjs +321 -0
  161. package/test/verify-cli.mjs +197 -0
  162. package/test/verify-command-ux.mjs +100 -0
  163. package/test/verify-compat.mjs +32 -0
  164. package/test/verify-cross-host-notes.mjs +128 -0
  165. package/test/verify-delegate.mjs +161 -0
  166. package/test/verify-detect.mjs +151 -0
  167. package/test/verify-discovery.mjs +239 -0
  168. package/test/verify-done-nudge.mjs +238 -0
  169. package/test/verify-effective-prompt.mjs +98 -0
  170. package/test/verify-hc-matrix.mjs +246 -0
  171. package/test/verify-hc-poll.mjs +260 -0
  172. package/test/verify-host-docs.mjs +66 -0
  173. package/test/verify-host-impact.mjs +49 -0
  174. package/test/verify-ids.mjs +141 -0
  175. package/test/verify-launch.mjs +183 -0
  176. package/test/verify-message-routing.mjs +560 -0
  177. package/test/verify-messaging.mjs +303 -0
  178. package/test/verify-migration-notice.mjs +74 -0
  179. package/test/verify-multi-wait.mjs +42 -0
  180. package/test/verify-opencode-display.mjs +47 -0
  181. package/test/verify-opencode-fieldnotes.mjs +121 -0
  182. package/test/verify-opencode-notice.mjs +77 -0
  183. package/test/verify-opencode-nudge.mjs +116 -0
  184. package/test/verify-opencode-orphans.mjs +160 -0
  185. package/test/verify-opencode-surface.mjs +107 -0
  186. package/test/verify-packaging.mjs +82 -0
  187. package/test/verify-parent-surface.mjs +118 -0
  188. package/test/verify-phase0.mjs +95 -0
  189. package/test/verify-registry.mjs +124 -0
  190. package/test/verify-rename-migration.mjs +111 -0
  191. package/test/verify-rendering.mjs +379 -0
  192. package/test/verify-session-boundary.mjs +146 -0
  193. package/test/verify-settings.mjs +260 -0
  194. package/test/verify-stale-wait.mjs +339 -0
  195. package/test/verify-status-widget.mjs +377 -0
  196. package/test/verify-status.mjs +172 -0
  197. package/test/verify-task-completion.mjs +156 -0
  198. package/test/verify-task-failures.mjs +201 -0
  199. package/test/verify-task-mislabel.mjs +143 -0
  200. package/test/verify-task-registry.mjs +194 -0
  201. package/test/verify-task-watchers.mjs +217 -0
  202. package/test/verify-tool-schemas.mjs +120 -0
  203. package/test/verify-unseen-completions.mjs +1211 -0
  204. package/test/verify-watchers.mjs +181 -0
@@ -0,0 +1,204 @@
1
+ # Plan — Shepherd for OpenCode
2
+
3
+ `specs/013-opencode-shepherd` · draft · 2026-11-17 · spec: `spec.md`
4
+
5
+ ## Summary
6
+
7
+ Satisfy FR-001–FR-012 with Path A: keep the Herdr/hc pane runtimes, the
8
+ file broker, and the orchestration registries untouched, and add an OpenCode
9
+ server-plugin adapter beside the existing Pi adapter in one package. The Pi
10
+ import surface in today's `src/core` is decoupled behind injected
11
+ directories/parsers so both adapters share one engine; OpenCode children boot
12
+ as interactive sessions in panes (the `opencode run` subcommand is one-shot
13
+ and unsuitable for persistent sheep) and get their `shepherd_message` /
14
+ `shepherd_done` tools from the same installed plugin.
15
+
16
+ ## Requirement coverage
17
+
18
+ - **FR-001** (OpenCode parity: spawn/delegate/message/watch/status/read/close)
19
+ → new OpenCode server-plugin adapter exposing one tool per operation with
20
+ the same lifecycle semantics as the Pi tools; all calls route through the
21
+ shared runtime resolver.
22
+ - **FR-002** (sheep run in visible Herdr panes/terminals) → reuse of the two
23
+ existing pane runtimes unchanged; only the child boot command is
24
+ parameterized (boot `opencode` instead of `pi`).
25
+ - **FR-003** (explicit-completion settlement) → reuse of the broker's
26
+ `task_done` envelope + `shepherd_done` as the single settlement signal;
27
+ new OpenCode child tool publishes the same envelope shape.
28
+ - **FR-004** (results retrievable, delivered once) → reuse of the task
29
+ registries, watcher services, and unseen-completion ledger unchanged.
30
+ - **FR-005** (shared definitions/config) → discovery and config move to
31
+ directory-injected helpers shared by both adapters; project
32
+ `.shepherd/config.json` stays the single project source.
33
+ - **FR-006** (cross-host fieldnotes) → artifact sessions are host-neutral
34
+ files; the OpenCode adapter resolves/creates the same parent session
35
+ layout the Pi adapter uses. The OpenCode session id is the opaque parent
36
+ identity and the session cwd is the project root — the same
37
+ `(parent identity, effective project root)` binding key Pi uses — passed
38
+ to the shared resolver. Spawn stores the session on the agent record and
39
+ delegate re-resolves it, so both runtimes reserve notes in that collection.
40
+ - **FR-007** (no Pi regression) → zero behavior change in the Pi adapter;
41
+ the full existing `verify-*` suites stay green and run on every change.
42
+ - **FR-008** (no cross-host code paths) → layout rule: shared engine
43
+ imports nothing host-specific; each adapter imports the engine, never the
44
+ other adapter. New modules, no edits to Pi-owned behavior.
45
+ - **FR-009** (both suites green, per-host release notes) → a mirrored
46
+ OpenCode verification harness plus a release checklist entry.
47
+ - **FR-010** (one package, clear docs) → single manifest carrying both a Pi
48
+ extension entry and an OpenCode plugin entry; README splits into
49
+ per-host tracks on the first screen.
50
+ - **FR-011** (clean failure when Herdr is unreachable) → the existing
51
+ backend resolver and setup-hint errors are reused verbatim by the
52
+ OpenCode adapter.
53
+ - **FR-012** (deadlines, bounded waits, nudges) → reuse of the timeout,
54
+ stale-wait, and done-nudge machinery; OpenCode child turn-end maps onto
55
+ the same nudge boundary the Pi child uses.
56
+
57
+ ## Technical context
58
+
59
+ - **Language / runtime**: TypeScript run directly by both hosts, no build
60
+ step (matches the current repo: no bundler, no compiled output).
61
+ - **Dependencies**: host SDKs stay peer/optional and adapter-local — the Pi
62
+ SDK inside the Pi adapter only, `@opencode/plugin` inside the OpenCode
63
+ adapter only. The shared engine depends on neither.
64
+ - **Storage**: today's file layout is kept — created-pane/terminal
65
+ registries, parent-owned mailbox broker directories, artifact session
66
+ files, per-host user config plus shared project `.shepherd/config.json`.
67
+ - **Platform**: any machine with Herdr (or `hc`) plus the host CLI
68
+ installed; Node 22+.
69
+ - **Constraints**: opaque lifecycle ids stay opaque on both hosts (native
70
+ pane/terminal/session ids never cross tool boundaries); backend choice
71
+ stays app-side (the model never selects it).
72
+
73
+ ## Architecture
74
+
75
+ One engine, two thin adapters:
76
+
77
+ ```text
78
+ +------------------ shared engine ------------------+
79
+ | discovery · config · ids · broker/messaging |
80
+ | orchestration registries · artifacts · runtimes |
81
+ | (herdr panes · hc terminals · backend resolver) |
82
+ +-----------+------------------+--------------------+
83
+ | |
84
+ Pi adapter (today) OpenCode adapter (new)
85
+ tools · /shepherd server tools · commands
86
+ settings UI · widget (settings UI deferred, see Q2)
87
+ child extension child plugin tools
88
+ ```
89
+
90
+ - The engine gains no host concepts: today's Pi imports in discovery/config
91
+ (agent directory, frontmatter parser, config-dir name) become injected
92
+ parameters with each adapter supplying its host's values.
93
+ - The launch-file builder is parameterized by child binary, child entry,
94
+ env prefix, and — because the opencode CLI has no equivalent of pi's
95
+ session/extension flags — a full-command override (`command: 'opencode'`),
96
+ which skips Pi arg construction and runs verbatim. Pi callers omit all
97
+ four and get byte-identical scripts. `opencode run`
98
+ is deliberately *not* used for sheep: it executes one message and exits,
99
+ while sheep must stay alive across turns.
100
+ - Children obtain Shepherd tools from the normally installed plugin (global
101
+ install recommended, mirroring `pi install`, so any child cwd inherits
102
+ it); no per-spawn plugin injection.
103
+ - Parent→sheep delivery uses terminal input (Herdr `agent prompt` with a
104
+ `pane send-text` fallback; `hc send`), because the opencode TUI ignores
105
+ `--session` attach and creates its server session lazily on first input.
106
+ `session.prompt` is used only for parent-session notices, where the
107
+ session id is exactly known; human `/shepherd` command output instead uses
108
+ `session.prompt(..., resume: false)` so it renders in full without waking
109
+ the model.
110
+ - Operational limits (see tasks.md Later): one active parent session per
111
+ OpenCode server process is a deliberate, engine-wide boundary (broker
112
+ singletons, session-keyed registry rotation, one drain timer/poll key),
113
+ not a broker-only limitation; sheep of one parent never collide. Phase 3
114
+ verifies single-parent flows only. A plugin reload/server restart resets
115
+ in-memory orchestration state while panes/terminals survive; the adapter
116
+ detects those orphans from the ownership registries, notifies once, and
117
+ offers an ownership-checked `reap` action. Tracked tasks and watchers do
118
+ not survive a restart.
119
+ Completion notices are delivered only to sessions that were recorded as
120
+ task parents (never to sheep sessions), with bounded retry when the parent
121
+ session is busy. Sheep session binding wins over a stale parent mark so a
122
+ child that called a parent tool before binding can still reply to peers.
123
+ - The capability handoff (broker directory, session/broker/agent ids,
124
+ token, inbox path) keeps its file+environment-variable shape so the
125
+ shared builder stays single-sourced; each host's surface reads it under
126
+ its own variable prefix (today's prefix keeps working for Pi).
127
+
128
+ ## Data model
129
+
130
+ - Unchanged: opaque agent/task/message/watcher ids with per-process
131
+ namespaces; broker envelopes (`task`, `message`, `reply`, `runtime`,
132
+ `task_done`) with the same required fields; artifact reservations with
133
+ terminal statuses (completed/blocked/failed/cancelled/timed-out).
134
+ - Config: per-host user files (Pi's agent dir; OpenCode's config dir) plus
135
+ the one shared project file. `backend` and the project-agent trust gate
136
+ stay user-owned on both hosts: a repository config can never force them.
137
+ - Ownership: created panes/terminals remain tagged by parent session, so
138
+ the herd views on both hosts show only their own sheep while sharing the
139
+ underlying registry files.
140
+
141
+ ## Interfaces
142
+
143
+ | interface | behavior |
144
+ |---|---|
145
+ | OpenCode `shepherd_spawn` (+ `delegate`, `message`, `watch`, `status`, `read`, `close`, umbrella) | Same lifecycle semantics as the Pi tools; same opaque-id discipline; same setup-hint failures. |
146
+ | OpenCode command (e.g. `/shepherd`) | Same human surface as Pi's: list agents/herd, spawn, status, read; settings entry point when decided (see Q2). |
147
+ | Child `shepherd_message` / `shepherd_done` (OpenCode) | Same validation as the Pi child: task inference, reply→task match, broker-unavailable error when no capability was handed down. |
148
+ | Env capability contract | Same fields as today (root dir, session/broker/agent ids, token, inbox); per-host variable prefix. |
149
+ | Package manifest | One manifest named `@luminascale/shepherd` with two entries: Pi extension entry + OpenCode plugin entry (server part; TUI/GUI parts only if needed). |
150
+
151
+ ## Invariants
152
+
153
+ - No adapter imports the other adapter; the engine imports neither.
154
+ - Native ids (pane, terminal, OpenCode session) never appear in tool
155
+ inputs, outputs, or results — diagnostics only.
156
+ - One outstanding tracked reply per task; completion only via the
157
+ explicit done signal, cancellation/close, or deadline.
158
+ - Watcher delivery exactly-once per settlement; late watchers still get
159
+ already-settled results synchronously.
160
+ - A pinned backend that is unreachable fails with its setup hint; never a
161
+ silent cross-spawn to the other runtime.
162
+ - Functional identifiers stay frozen across the rename: `shepherd_*` tool
163
+ names, the env-capability prefix and fields, and the user config/registry
164
+ paths. Only the npm package name changes.
165
+ - Release ordering around the rename: the old name still gets one final
166
+ notice-bearing release (`@luminascale/pi-shepherd@0.5.2`) and is then
167
+ deprecated with a pointer. The renamed package
168
+ (`@luminascale/shepherd@0.6.0`) is published **first**, so the pointer in
169
+ the notice and the deprecation warning resolves to a real install target.
170
+ The one-time notice is marker-gated, human-sessions-only, and never emitted
171
+ in a child sheep pane.
172
+
173
+ ## Failure behavior
174
+
175
+ - Herdr/hc unreachable ⇒ setup-hint error naming the missing runtime; no
176
+ fallback spawn (FR-011).
177
+ - Child never becomes ready ⇒ spawn fails with the child's output tail and
178
+ temporary resources are removed; no orphan registration.
179
+ - Broker capability missing in a child ⇒ child tools return a structured
180
+ unavailable error; the parent task still settles by deadline (FR-012).
181
+ - Turn ends with an open tracked task ⇒ one bounded reminder turn, then a
182
+ visible stall escalation; the task itself stays open until done,
183
+ cancelled, or timed out.
184
+ - Rejected/duplicate completions ⇒ written to the broker's rejected store
185
+ and surfaced, never silently applied or lost.
186
+
187
+ ## Recovery
188
+
189
+ - Stale pane/terminal registrations are pruned; only owned panes/terminals
190
+ may be closed.
191
+ - Orphaned launch directories are removed once their pane/terminal is
192
+ confirmed gone.
193
+ - Background inbox drains are idempotent: re-polling never double-settles,
194
+ and one bad envelope never stops the drain.
195
+
196
+ ## Open questions
197
+
198
+ 1. Package name — decided: `@luminascale/shepherd` (bare `shepherd` is
199
+ taken on npm; the scoped name is free). Functional identifiers stay
200
+ frozen per the invariant above.
201
+ 2. OpenCode settings surface on day one vs file-based config first?
202
+ Proposed default stands (files first) unless the spec review overturns it.
203
+ 3. OpenCode plugin `id` and whether the child tool names need namespacing
204
+ to avoid collisions in sessions that install other plugins.
@@ -0,0 +1,258 @@
1
+ # Spec — Shepherd for OpenCode
2
+
3
+ `specs/013-opencode-shepherd` · agreed · 2026-11-17 · From: `intent.md` (Mikkel)
4
+
5
+ ## Summary
6
+
7
+ Shepherd becomes usable from OpenCode as well as Pi: the same herding of
8
+ visible Herdr sheep, tracked task delegation, agent messaging, and shared
9
+ fieldnotes — shipped as one package with a Pi entry and an OpenCode entry,
10
+ with Herdr remaining the execution substrate.
11
+
12
+ ## User Scenarios & Testing
13
+
14
+ ### User Story 1 — Spawn a sheep from OpenCode (Priority: P1)
15
+
16
+ An OpenCode user asks for a specialist (e.g. a planner). A sheep starts in a
17
+ visible Herdr pane, owned by that OpenCode session, and the user can see and
18
+ inspect it the same way a Pi user can today.
19
+
20
+ **Why this priority**: without spawning there is no product; this is the
21
+ entry point everything else builds on.
22
+
23
+ **Independent test**: from OpenCode, request a named agent; confirm a live,
24
+ visible sheep exists and is owned by the session, then close it.
25
+
26
+ **Acceptance scenarios**:
27
+
28
+ 1. **Given** Herdr is reachable and an agent named `planner` exists, **when**
29
+ the user asks OpenCode for a planner, **then** a visible sheep running
30
+ that agent appears and reports back as ready.
31
+ 2. **Given** Herdr is not reachable, **when** the user asks for a sheep,
32
+ **then** they get a clear setup hint instead of a hang or a cryptic
33
+ error.
34
+ 3. **Given** an unknown agent name, **when** the user asks for it, **then**
35
+ they are told the name is unknown and how to list exact names.
36
+
37
+ ### User Story 2 — Delegate tracked work and get the result (Priority: P1)
38
+
39
+ An OpenCode user delegates a task to a sheep and continues working; when the
40
+ sheep finishes, the result is delivered and nothing is lost even if nobody
41
+ was watching at the moment of completion.
42
+
43
+ **Why this priority**: this is Shepherd's core loop; spawning without
44
+ delegation has no value.
45
+
46
+ **Independent test**: delegate a small task, do other work, receive the
47
+ completion and verify its content matches what the sheep did.
48
+
49
+ **Acceptance scenarios**:
50
+
51
+ 1. **Given** a spawned sheep, **when** the user delegates a task, **then**
52
+ delegation returns immediately with a task reference and the sheep starts
53
+ working.
54
+ 2. **Given** a delegated task finishes while no watcher is attached, **when**
55
+ the user next checks, **then** the result is still retrievable exactly
56
+ once — never lost, never delivered twice.
57
+ 3. **Given** a sheep that never finishes, **when** its deadline passes,
58
+ **then** the task settles as timed-out/blocked with an explanation
59
+ instead of hanging forever.
60
+
61
+ ### User Story 3 — Agents talk to each other (Priority: P2)
62
+
63
+ A sheep working a task can ask the user-side session or a peer sheep a
64
+ question and wait for the answer; replies resume the waiting work.
65
+
66
+ **Why this priority**: real tasks need clarification; without messaging,
67
+ delegated work stalls or guesses.
68
+
69
+ **Independent test**: have a sheep ask a question mid-task, answer it, and
70
+ confirm the sheep resumes and completes.
71
+
72
+ **Acceptance scenarios**:
73
+
74
+ 1. **Given** a sheep needs input, **when** it asks a question expecting a
75
+ reply, **then** its task is visibly marked as waiting and the question
76
+ reaches the right recipient.
77
+ 2. **Given** a waiting task, **when** the reply arrives, **then** the task
78
+ resumes and the reply is correlated to the original question.
79
+
80
+ ### User Story 4 — Sheep share fieldnotes (Priority: P2)
81
+
82
+ Delegated work in OpenCode leaves durable notes in the same shared place Pi
83
+ sheep use, so a later agent (from either host) can pick up the context.
84
+
85
+ **Why this priority**: continuity across agents and across hosts is the
86
+ multiplier; without it every delegation starts from zero.
87
+
88
+ **Independent test**: delegate two sequential tasks and confirm the second
89
+ sheep can see what the first one left behind.
90
+
91
+ **Acceptance scenarios**:
92
+
93
+ 1. **Given** a completed delegation with notes enabled, **when** a new
94
+ sheep is delegated follow-up work, **then** it can read the earlier
95
+ sheep's notes.
96
+ 2. **Given** notes from a Pi delegation, **when** an OpenCode sheep does
97
+ follow-up work, **then** the Pi notes are visible to it (and vice
98
+ versa).
99
+
100
+ ### User Story 5 — Pi users notice nothing (Priority: P1)
101
+
102
+ A Pi user who never touches OpenCode experiences zero regression: same
103
+ commands, same tools, same behavior, same install.
104
+
105
+ **Why this priority**: the installed base must not pay for a host they
106
+ don't use; this constraint gates the whole effort.
107
+
108
+ **Independent test**: run the existing Pi verification suites unchanged and
109
+ green, and walk the core Pi flows manually.
110
+
111
+ **Acceptance scenarios**:
112
+
113
+ 1. **Given** the combined package installed in Pi, **when** the user herds
114
+ sheep as before, **then** every flow behaves exactly as it did before
115
+ the OpenCode work.
116
+ 2. **Given** a Pi-only change, **when** it ships, **then** it requires no
117
+ OpenCode-side change (and vice versa).
118
+ 3. **Given** an existing `@luminascale/pi-shepherd` install, **when** the
119
+ farewell release runs, **then** the user sees a one-time migration
120
+ notice pointing at the new name; **and when** they remove-then-install
121
+ the new package, **then** settings and herd registrations are intact.
122
+
123
+ ### User Story 6 — One package, two homes (Priority: P2)
124
+
125
+ A new user finds one Shepherd package, installs it in their host (Pi or
126
+ OpenCode), and gets host-appropriate guidance without confusion about which
127
+ host the docs describe.
128
+
129
+ **Why this priority**: the packaging decision only pays off if discovery
130
+ and install are genuinely unified.
131
+
132
+ **Independent test**: fresh install in each host following only the docs;
133
+ confirm working sheep in both.
134
+
135
+ **Acceptance scenarios**:
136
+
137
+ 1. **Given** a Pi user, **when** they install the package, **then** no
138
+ OpenCode-specific setup is required of them (and vice versa).
139
+ 2. **Given** the documentation, **when** a user of either host reads it,
140
+ **then** they can tell within seconds which instructions apply to them.
141
+
142
+ ### Edge cases
143
+
144
+ - Herdr reachable but the child agent never becomes ready: the user gets
145
+ the failure plus whatever the child produced, not a silent timeout.
146
+ - Two sheep given the same display label: the second spawn is rejected
147
+ clearly instead of creating an ambiguous herd.
148
+ - A sheep's turn ends without reporting its task done: it gets a bounded
149
+ reminder, then the stall is escalated visibly instead of looping forever.
150
+ - A project-local agent definition the user hasn't approved: OpenCode asks
151
+ first, same trust gate as Pi.
152
+ - Human `/shepherd …` command results are display-only: listing agents (or
153
+ herd/status/read) via the command shows the result and returns control to
154
+ the user, without starting an assistant turn. Command output is delivered
155
+ as a normal session message with `resume: false` (full TUI rendering, but no
156
+ model wake); parent-session notices omit `resume: false` because those are
157
+ meant to wake the model.
158
+ - Fieldnotes are keyed by `(host parent session identity, effective project
159
+ root)` on both hosts. The OpenCode session id is that opaque identity;
160
+ neither a pane/terminal id nor an agent/task id is used. The fieldnotes
161
+ setting is snapshotted per parent session, so disabling it never changes
162
+ the contract of agents already running in that session.
163
+
164
+ ## Requirements
165
+
166
+ - **FR-001**: OpenCode users MUST be able to spawn, delegate to, message,
167
+ check on, read output from, watch, and close sheep with the same semantics
168
+ Pi users have.
169
+ - **FR-002**: Sheep delegated from OpenCode MUST run in visible Herdr
170
+ panes/terminals (Path A); no hidden or host-native-only execution in this
171
+ effort.
172
+ - **FR-003**: A tracked task MUST settle only through an explicit completion
173
+ signal from the working sheep, a cancellation/close, or its deadline —
174
+ never through a turn ending, idleness, or silence.
175
+ - **FR-004**: Settled task results MUST remain retrievable after settlement
176
+ and MUST be delivered exactly once to watchers. Automatic completion notices
177
+ MUST go only to human parent sessions, never to a sheep pane, and MUST be
178
+ retried when the parent session is temporarily busy.
179
+ - **FR-015**: A delegated sheep session MUST remain recognised as a sheep even
180
+ if it called a parent-only tool before its session was lazily bound. Such an
181
+ early call MUST NOT permanently classify it as a parent, which would block
182
+ the sheep form of `shepherd_message` for peer replies.
183
+ - **FR-005**: Agent definitions and project configuration MUST be shared
184
+ between hosts, not forked; a definition written for Pi MUST work from
185
+ OpenCode unchanged.
186
+ - **FR-006**: Fieldnotes written from one host MUST be readable from the
187
+ other.
188
+ - **FR-007**: The Pi experience MUST NOT regress: existing Pi verification
189
+ suites stay green and Pi-only flows behave identically.
190
+ - **FR-008**: A change to one host's adapter MUST NOT require a change to
191
+ the other; the two adapters MUST share no code paths that can couple
192
+ their releases.
193
+ - **FR-009**: Every change MUST be verified against both hosts' suites
194
+ before shipping, and releases MUST call out per-host impact.
195
+ - **FR-010**: One installable package MUST serve both hosts, with
196
+ documentation that lets each host's users identify their instructions
197
+ immediately.
198
+ - **FR-011**: When the Herdr runtime is unreachable, the system MUST fail
199
+ with a setup hint and MUST NOT silently fall back to a different
200
+ execution substrate.
201
+ - **FR-012**: Stuck tracked work MUST settle by deadline with an explanation,
202
+ and messages awaiting replies MUST have a bounded wait after which the
203
+ waiter is reminded or the task settles as blocked.
204
+ - **FR-013**: The package MUST ship as `@luminascale/shepherd` with both
205
+ host entries, while tool names, env vars, and config/registry paths MUST
206
+ stay unchanged so existing installs migrate without loss.
207
+ - **FR-014**: The final `@luminascale/pi-shepherd` release MUST show
208
+ existing users a one-time migration notice (human sessions only, never
209
+ repeated, never in child sheep panes) and MUST ship before the rename.
210
+
211
+ ## Key entities
212
+
213
+ - **Sheep**: a persistent specialist agent running in a visible Herdr
214
+ pane/terminal, owned by exactly one parent session; has a definition name
215
+ and an optional label.
216
+ - **Tracked task**: one unit of delegated work on a sheep; has a lifecycle
217
+ (running → waiting → settled) and exactly one terminal outcome.
218
+ - **Message / reply**: asynchronous communication between sheep, or between
219
+ sheep and the parent session; a reply is correlated to the question it
220
+ answers.
221
+ - **Fieldnote session**: durable shared notes for one parent session's
222
+ delegations, readable by later sheep from either host.
223
+ - **Package**: the single installable unit exposing a Pi entry and an
224
+ OpenCode entry.
225
+
226
+ ## Success criteria
227
+
228
+ - **SC-001**: An OpenCode user completes spawn → delegate → watch → close
229
+ end-to-end with a visible sheep, following only the docs.
230
+ - **SC-002**: All pre-existing Pi verification suites pass unchanged, and a
231
+ mirrored OpenCode verification suite covering FR-001–FR-004 passes.
232
+ - **SC-003**: Fresh installs in Pi and in OpenCode (each following only
233
+ their host's instructions) both yield working sheep, with no steps from
234
+ the other host required.
235
+ - **SC-004**: A Pi-only change ships with zero OpenCode-side edits, and the
236
+ release notes state per-host impact.
237
+ - **SC-005**: An existing `@luminascale/pi-shepherd` user sees the
238
+ migration notice exactly once and completes remove-then-install with
239
+ settings and herd intact.
240
+
241
+ ## Assumptions
242
+
243
+ - Herdr (or `hc`) is installed and reachable wherever sheep are herded;
244
+ Shepherd does not install or manage Herdr itself.
245
+ - The OpenCode plugin interface used is the current (v2) one; tracking its
246
+ future breaking changes is maintenance, not part of this effort.
247
+ - One maintainer ships both sides, so release gating across both suites is
248
+ acceptable overhead.
249
+ - Agent frontmatter conventions (Markdown + YAML) stay host-agnostic.
250
+
251
+ ## Open questions from intent
252
+
253
+ - What is the package called, and does `pi-shepherd` get renamed? —
254
+ answered: `@luminascale/shepherd`; only the package name changes,
255
+ functional identifiers stay frozen (see FR-013).
256
+ - Does the OpenCode side need its own settings surface from day one, or is
257
+ file-based config enough for the first slice? — carried forward (owner:
258
+ Mikkel; proposed default: file-based config first, settings UI later).