@luminascale/shepherd 0.6.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,68 +1,42 @@
1
- # Shepherd
1
+ <p align="center">
2
+ <strong>SHEPHERD</strong><br />
3
+ <em>Native Herdr agent orchestration for Pi and OpenCode</em>
4
+ </p>
2
5
 
3
- > **Farewell to `@luminascale/pi-shepherd`.** This is the last release under
4
- > the old name. Shepherd is moving to **`@luminascale/shepherd`**; when you are
5
- > ready, install the new package — settings, agent definitions, registrations,
6
- > and fieldnotes carry over with no manual migration. The one-time notice you
7
- > see in your host session points to the same place.
6
+ <p align="center">
7
+ <a href="#install">Install</a> · <a href="#key-features">Features</a> · <a href="#available-tools">Tools</a> · <a href="#settings">Settings</a> · <a href="#fieldnotes">Fieldnotes</a>
8
+ </p>
8
9
 
9
- Shepherd is a no-fuss extension for native, low-level Herdr agent orchestration. The **Shepherd**—your main session in Pi or OpenCode—can launch and coordinate specialized agents in visible Herdr panes, while shared session fieldnotes (artifacts) let agents share context across delegated work. One package, two host entry points; Pi and OpenCode users never need steps from the other host.
10
+ <p align="center">
11
+ <a href="LICENSE"><img src="https://img.shields.io/npm/l/%40luminascale%2Fshepherd" alt="Apache-2.0 license" /></a>
12
+ <a href="https://github.com/MikkelKappelPersson/shepherd/stargazers"><img src="https://img.shields.io/github/stars/MikkelKappelPersson/shepherd?logo=github" alt="GitHub stars" /></a>
13
+ <a href="https://github.com/MikkelKappelPersson/shepherd/releases/latest"><img src="https://img.shields.io/github/v/release/MikkelKappelPersson/shepherd?label=release" alt="latest stable release" /></a>
14
+ <a href="https://www.npmjs.com/package/@luminascale/shepherd"><img src="https://img.shields.io/npm/v/%40luminascale%2Fshepherd?label=npm&logo=npm" alt="npm version" /></a>
15
+ </p>
10
16
 
11
- ## Choose your host
17
+ Shepherd is a no-fuss extension for native, low-level Herdr agent orchestration. The **Shepherd**—your main session can launch and coordinate specialized agents in visible Herdr panes, while shared session fieldnotes (artifacts) let agents share context across delegated work.
12
18
 
13
- | Track | Install | Verify after restart |
14
- | --- | --- | --- |
15
- | **[Pi](#pi-track)** | `pi install npm:@luminascale/shepherd` | `/shepherd agents` |
16
- | **[OpenCode](#opencode-track)** | add `@luminascale/shepherd` to `plugins` in `opencode.json` | `/shepherd agents` |
19
+ ## Install
17
20
 
18
- The tools, opaque ids, agent definitions, and fieldnotes layout are shared. Host-specific differences (install, settings surface, command output) are called out in each track below; the rest of this document applies to both.
19
-
20
- ## Pi track
21
-
22
- Install with pi's package installer:
23
-
24
- ```bash
25
- pi install npm:@luminascale/shepherd
26
- ```
27
-
28
- Reload pi, then verify the extension is available with `/shepherd agents`. You should see the bundled agent definitions, including `scout`, `planner`, `worker`, and `reviewer`.
29
-
30
- Pi uses the `/shepherd settings` menu for configuration (see [Settings](#settings)), and pi's steer mode for completion notices. No OpenCode setup is required.
31
-
32
- ## OpenCode track
33
-
34
- Add the package to your OpenCode plugin list:
35
-
36
- ```jsonc
37
- // ~/.config/opencode/opencode.json (or the project-level .opencode/opencode.json)
38
- {
39
- "$schema": "https://opencode.ai/config.json",
40
- "plugins": ["@luminascale/shepherd"]
41
- }
42
- ```
43
-
44
- Restart OpenCode, then verify with `/shepherd agents`. The `shepherd_*` tools and `/shepherd` command have the same names and semantics as in Pi. You do not need to install pi to use Shepherd from OpenCode.
45
-
46
- OpenCode differences:
21
+ | Harness | Installation | Quick install | Verify after restart |
22
+ | --- | --- | --- | --- |
23
+ | Pi | [Pi setup guide](docs/guides/installation.md#pi) | `pi install npm:@luminascale/shepherd` | `/shepherd agents` |
24
+ | OpenCode | [OpenCode setup guide](docs/guides/installation.md#opencode) | add `@luminascale/shepherd` to `plugins` in `opencode.json` | `/shepherd agents` |
47
25
 
48
- - Settings are file-based: `~/.config/opencode/pi-shepherd/config.json` (user) and `.shepherd/config.json` (project, with `"projectScope": true`). There is no settings menu yet.
49
- - Human `/shepherd …` command output is display-only — it renders in full and returns control without starting an assistant turn.
50
- - Completion notices arrive as normal parent-session messages that wake the model.
51
- - Fieldnotes are bound to the OpenCode session id and the session's working directory, on the same `.shepherd/sessions/` layout Pi uses.
52
- - After an OpenCode server restart, sheep keep running but their opaque ids are lost. You get one display-only notice listing the orphaned sheep; use `shepherd({ action: "reap" })` to close them safely (or respawn and close the old panes). Fieldnotes and queued envelopes remain on disk until reaped.
26
+ The tools, opaque ids, agent definitions, and fieldnotes layout are shared across both hosts.
53
27
 
54
28
  ## Key Features
55
29
 
56
30
  - **Native, no-fuss, low-level Herdr agent orchestration** — Shepherd uses native Herdr panes for all agents and simple, open primitives for agent orchestration. Everything is visible and inspectable. Shepherd does not impose a workflow; it gives you the tools to build your own.
57
- - **Herdr headless support** — work inside Herdr or from a plain terminal while keeping launched agents visible and inspectable in Herdr.
31
+ - **Herdr and hc support** — run inside the [Herdr](https://github.com/herdrdev/herdr) TUI or an [hc](https://github.com/herdrdev/herdr-core) terminal in [herdr-app](https://github.com/herdrdev/herdr-app); launched agents stay visible and inspectable in their panes or terminals. `backend: auto` runs where you called from, or pin `herdr` / `hc`.
58
32
  - **Granular system-prompt and agent-context support** — Shepherd goes beyond standard definitions and utilises pi's open system-prompt. Shepherd agents can be defined with granular control over context for very specific and narrow agent and context control.
59
33
  - **Manual agent launch** — start an interactive specialist directly with `/shepherd spawn` and chat with it in its own host session.
60
34
  - **Shared session fieldnotes (artifacts)** — give agents a durable shared place to leave notes and share context across delegated work, on the same layout in both hosts.
61
35
 
62
36
  ## Requirements
63
37
 
64
- - [Pi](https://github.com/earendil-works/pi) **or** [OpenCode](https://opencode.ai) (see the tracks above)
65
- - [Herdr](https://github.com/herdrdev/herdr)
38
+ - [Pi](https://github.com/earendil-works/pi) **or** [OpenCode](https://opencode.ai) (see [Install](#install))
39
+ - [Herdr](https://github.com/herdrdev/herdr) (TUI panes) **or** [herdr-app](https://github.com/herdrdev/herdr-app) / [herdr-core](https://github.com/herdrdev/herdr-core) (desktop-app terminals)
66
40
  - Node.js 22 or newer
67
41
 
68
42
  ## Available tools
@@ -79,7 +53,6 @@ pi-shepherd exposes these tools to the Shepherd. You can use them explicitly whe
79
53
  | `shepherd_status` | Inspect an agent without focusing its pane; reports process and task state independently |
80
54
  | `shepherd_close` | Close an owned agent, cancel its active task, and clear pending requests |
81
55
  | `shepherd_read` | Read recent terminal output for diagnostics |
82
- | `shepherd_prompt` | **Deprecated** one-turn compatibility path; prefer `shepherd_delegate` for tracked work |
83
56
 
84
57
  Child agents additionally see `shepherd_message` (talk to the parent or a peer) and `shepherd_done` (the only normal successful completion of their tracked task).
85
58
 
package/docs/README.md CHANGED
@@ -4,6 +4,7 @@
4
4
 
5
5
  User-facing documentation:
6
6
 
7
+ - [Installation](guides/installation.md)
7
8
  - [Agent definitions](guides/agent-definitions.md)
8
9
  - [Tool reference](guides/tool-reference.md)
9
10
  - [Diagnostics](guides/diagnostics.md)
@@ -0,0 +1,61 @@
1
+ # Installation
2
+
3
+ Shepherd is one npm package — `@luminascale/shepherd` — with two host entry
4
+ points. Install the one that matches your host; neither host needs anything
5
+ from the other. You need [Herdr](https://github.com/herdrdev/herdr) and Node.js
6
+ 22 or newer in either case.
7
+
8
+ - [Pi](#pi)
9
+ - [OpenCode](#opencode)
10
+
11
+ ## Pi
12
+
13
+ Install with pi's package installer:
14
+
15
+ ```bash
16
+ pi install npm:@luminascale/shepherd
17
+ ```
18
+
19
+ Reload pi, then verify the extension is available with `/shepherd agents`. You
20
+ should see the bundled agent definitions, including `scout`, `planner`,
21
+ `worker`, and `reviewer`.
22
+
23
+ Pi uses the `/shepherd settings` menu for configuration (see
24
+ [Settings](../README.md#settings)), and pi's steer mode for completion notices.
25
+ No OpenCode setup is required.
26
+
27
+ ## OpenCode
28
+
29
+ Add the package to your OpenCode plugin list:
30
+
31
+ ```jsonc
32
+ // ~/.config/opencode/opencode.json (or the project-level .opencode/opencode.json)
33
+ {
34
+ "$schema": "https://opencode.ai/config.json",
35
+ "plugins": ["@luminascale/shepherd"]
36
+ }
37
+ ```
38
+
39
+ Restart OpenCode, then verify with `/shepherd agents`. The `shepherd_*` tools
40
+ and `/shepherd` command have the same names and semantics as in Pi. You do not
41
+ need to install pi to use Shepherd from OpenCode.
42
+
43
+ OpenCode differences:
44
+
45
+ - Settings are file-based: `~/.config/opencode/pi-shepherd/config.json` (user)
46
+ and `.shepherd/config.json` (project, with `"projectScope": true`). There is
47
+ no settings menu yet.
48
+ - Human `/shepherd …` command output is display-only — it renders in full and
49
+ returns control without starting an assistant turn.
50
+ - Completion notices arrive as normal parent-session messages that wake the
51
+ model.
52
+ - Fieldnotes are bound to the OpenCode session id and the session's working
53
+ directory, on the same `.shepherd/sessions/` layout Pi uses.
54
+ - After an OpenCode server restart, sheep keep running but their opaque ids are
55
+ lost. You get one display-only notice listing the orphaned sheep; use
56
+ `shepherd({ action: "reap" })` to close them safely (or respawn and close the
57
+ old panes). Fieldnotes and queued envelopes remain on disk until reaped.
58
+
59
+ ---
60
+
61
+ [Back to README](../README.md)
package/index.ts CHANGED
@@ -412,7 +412,10 @@ export default function (pi: ExtensionAPI) {
412
412
  const notice = migrationNoticeOnce();
413
413
  if (notice && typeof pi.sendMessage === 'function') {
414
414
  try {
415
- pi.sendMessage({ customType: 'shepherd-migration-notice', content: notice, display: true }, { triggerTurn: false });
415
+ pi.sendMessage(
416
+ { customType: 'shepherd-migration-notice', content: notice, display: true },
417
+ { deliverAs: 'followUp', triggerTurn: false }
418
+ );
416
419
  } catch {
417
420
  /* best effort: marker is already consumed */
418
421
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@luminascale/shepherd",
3
- "version": "0.6.0",
3
+ "version": "0.6.1",
4
4
  "type": "module",
5
5
  "description": "🐑 No-fuss herdr native subagent orchestration 🐑 (Pi + OpenCode)",
6
6
  "exports": {
@@ -94,6 +94,10 @@ as before.
94
94
  OpenCode file-based config and display-only command output).
95
95
  - `test/verify-host-docs.mjs` guards the first-screen split and the OpenCode
96
96
  `plugins` config snippet. Full suite: 657 PASS (exit 0).
97
+ - Follow-up: the detailed per-host steps moved to
98
+ `docs/guides/installation.md`; the README keeps a compact host-neutral
99
+ install picker linking to it, and `verify-host-docs.mjs` now checks both
100
+ the picker and the guide.
97
101
  - [x] T016 [US5] Mirrored OpenCode verification harness covering FR-001–FR-004; both harnesses run on every change.
98
102
  - `scripts/verify-suites.mjs` derives the Pi (36 scripts) and OpenCode
99
103
  (11 scripts) suites from `package.json`; `npm test` chains both, and a new
@@ -1,35 +1,66 @@
1
1
  #!/usr/bin/env node
2
2
  /**
3
- * T015 — README splits into per-host tracks on the first screen, so a user
4
- * of either host can find their install steps without reading the other's.
3
+ * T015 — README stays streamlined: host-neutral intro plus a compact install
4
+ * picker on the first screen, with full per-host steps in a linked guide.
5
5
  */
6
6
  import assert from 'node:assert/strict';
7
7
  import fs from 'node:fs';
8
8
  import path from 'node:path';
9
9
 
10
- const readme = fs.readFileSync(path.resolve(import.meta.dirname, '../README.md'), 'utf8');
11
- const firstScreen = readme.split('\n').slice(0, 60).join('\n');
10
+ const root = path.resolve(import.meta.dirname, '..');
11
+ const readme = fs.readFileSync(path.join(root, 'README.md'), 'utf8');
12
+ const guide = fs.readFileSync(path.join(root, 'docs/guides/installation.md'), 'utf8');
13
+ const docsIndex = fs.readFileSync(path.join(root, 'docs/README.md'), 'utf8');
14
+ const sharedHeading = '## Key Features';
15
+ const firstScreen = readme.slice(0, readme.indexOf(sharedHeading) + sharedHeading.length);
12
16
 
13
- assert.match(firstScreen, /^# Shepherd$/m, 'host-neutral title');
14
- assert.match(firstScreen, /## Choose your host/, 'host picker is on the first screen');
15
- const piTrack = firstScreen.indexOf('## Pi track');
16
- const ocTrack = firstScreen.indexOf('## OpenCode track');
17
- const sharedContent = firstScreen.indexOf('## Key Features');
18
- assert.ok(piTrack > -1 && ocTrack > -1, 'both host tracks are on the first screen');
19
- assert.ok(piTrack < sharedContent && ocTrack < sharedContent, 'tracks precede shared content');
20
- assert.match(firstScreen, /\[Pi\]\(#pi-track\)/, 'Pi track is linked from the picker');
21
- assert.match(firstScreen, /\[OpenCode\]\(#opencode-track\)/, 'OpenCode track is linked from the picker');
17
+ assert.match(
18
+ firstScreen,
19
+ /<p align="center">[\s\S]{0,160}<strong>SHEPHERD<\/strong>/,
20
+ 'host-neutral centered title banner'
21
+ );
22
+ assert.match(firstScreen, /## Install/, 'compact install section is on the first screen');
22
23
  assert.match(firstScreen, /pi install npm:@luminascale\/shepherd/, 'Pi install command is shown');
24
+ assert.match(firstScreen, /`@luminascale\/shepherd` to `plugins`/, 'OpenCode plugin entry is shown');
25
+ assert.match(firstScreen, /\/shepherd agents/, 'verify command is shared by both hosts');
26
+ assert.match(firstScreen, /\| Harness \| Installation \|/, 'table has a dedicated Installation column');
27
+ assert.match(
28
+ firstScreen,
29
+ /\[Pi setup guide\]\(docs\/guides\/installation\.md#pi\)/,
30
+ 'Pi installation link points to its guide section'
31
+ );
23
32
  assert.match(
24
33
  firstScreen,
34
+ /\[OpenCode setup guide\]\(docs\/guides\/installation\.md#opencode\)/,
35
+ 'OpenCode installation link points to its guide section'
36
+ );
37
+ assert.equal((readme.match(/^## Install$/gm) ?? []).length, 1, 'one install section, no duplicate');
38
+ assert.doesNotMatch(readme, /^## (Pi|OpenCode) track$/m, 'detailed tracks moved out of the README');
39
+ console.log('PASS README first screen has a compact host-neutral install picker');
40
+
41
+ assert.match(guide, /^# Installation$/m, 'guide has its own title');
42
+ const pi = guide.indexOf('## Pi');
43
+ const oc = guide.indexOf('## OpenCode');
44
+ assert.ok(pi > -1 && oc > pi, 'guide has Pi and OpenCode sections');
45
+ const piSection = guide.slice(pi, oc);
46
+ const ocSection = guide.slice(oc);
47
+ assert.match(piSection, /pi install npm:@luminascale\/shepherd/, 'Pi install command is in the guide');
48
+ assert.match(piSection, /\/shepherd agents/, 'Pi verify command is in the guide');
49
+ assert.match(piSection, /\/shepherd settings/, 'Pi settings surface is in the guide');
50
+ assert.doesNotMatch(piSection, /You do not\s+need to install pi/);
51
+ assert.match(
52
+ ocSection,
25
53
  /"plugins": \["@luminascale\/shepherd"\]/,
26
- 'OpenCode plugin config is shown'
54
+ 'OpenCode plugin config is in the guide'
55
+ );
56
+ assert.match(
57
+ ocSection,
58
+ /You do not\s+need to install pi/,
59
+ 'OpenCode-only note stays in its section'
27
60
  );
28
- assert.equal((readme.match(/^## Install$/gm) ?? []).length, 0, 'no duplicate Pi-only Install section');
29
- const piTrackText = readme.slice(piTrack, ocTrack);
30
- const ocTrackText = readme.slice(ocTrack, sharedContent);
31
- assert.doesNotMatch(piTrackText, /You do not need to install pi/);
32
- assert.match(ocTrackText, /You do not need to install pi/, 'OpenCode-only note stays in its track');
33
- console.log('PASS README first screen splits into Pi and OpenCode tracks');
61
+ assert.match(ocSection, /display-only/, 'OpenCode command behavior is in the guide');
62
+ assert.match(ocSection, /reap/, 'OpenCode orphan recovery is in the guide');
63
+ assert.match(docsIndex, /\[Installation\]\(guides\/installation\.md\)/, 'docs index lists the guide');
64
+ console.log('PASS installation guide keeps both hosts and their differences');
34
65
 
35
66
  console.log('\nAll host-doc assertions passed.');
@@ -55,15 +55,20 @@ assert.equal(migrationNoticeOnce(), undefined);
55
55
  console.log('PASS marker is per host user, not global');
56
56
 
57
57
  const readme = fs.readFileSync(new URL('../README.md', import.meta.url), 'utf8');
58
- assert.match(readme, /Farewell to `@luminascale\/pi-shepherd`/);
59
- assert.ok(readme.includes(NEW_PACKAGE_NAME), 'README banner names the new package');
58
+ assert.doesNotMatch(readme, /Farewell to `@luminascale\/pi-shepherd`/, 'farewell banner is retired');
59
+ assert.ok(readme.includes(NEW_PACKAGE_NAME), 'README documents the new package name');
60
60
  const indexSource = fs.readFileSync(new URL('../index.ts', import.meta.url), 'utf8');
61
61
  assert.match(indexSource, /migrationNoticeOnce\(\)/);
62
+ assert.match(
63
+ indexSource,
64
+ /customType: 'shepherd-migration-notice'[\s\S]{0,180}deliverAs: 'followUp'/,
65
+ 'Pi notice uses followUp delivery so an idle session renders it without a turn'
66
+ );
62
67
  const serverSource = fs.readFileSync(new URL('../src/opencode/server.ts', import.meta.url), 'utf8');
63
68
  assert.match(serverSource, /migrationNoticeOnce\(\)/);
64
69
  assert.match(serverSource, /!isSheepSession\(sessionID\)/, 'OpenCode notice is human-only');
65
70
  const releasing = fs.readFileSync(new URL('../docs/releasing.md', import.meta.url), 'utf8');
66
71
  assert.match(releasing, /npm deprecate @luminascale\/pi-shepherd/);
67
- console.log('PASS both hosts, README banner, and release ordering are wired');
72
+ console.log('PASS both hosts, README, and release ordering are wired');
68
73
 
69
74
  console.log('\nAll migration-notice assertions passed.');