@jagreehal/shepherd 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -22,7 +22,13 @@ shepherd config validate
22
22
  shepherd preview --working-tree
23
23
  ```
24
24
 
25
- The default install targets Claude Code. For another harness, use `shepherd install --target <skills-directory>`. Commit and merge the generated review-only policy before you run it against a PR: PR reviews read policy from the default branch. Without policy, the built-in fix mode is `push`.
25
+ Or install it as a Claude Code plugin, beside pstack or any other plugin:
26
+
27
+ ```text
28
+ /plugin install shepherd --marketplace jagreehal/shepherd
29
+ ```
30
+
31
+ The default `shepherd install` targets Claude Code. For another harness, use `shepherd install --target <skills-directory>`; Cursor reads the plugin manifest in `.cursor-plugin/`. Commit and merge the generated review-only policy before you run it against a PR: PR reviews read policy from the default branch. Without policy, the built-in fix mode is `push`.
26
32
 
27
33
  In your coding agent:
28
34
 
@@ -51,6 +57,7 @@ Replace `42` with your PR number. Expect findings on the PR and a `reviewed` res
51
57
  | Share organisation policy | [Team examples](docs/src/content/docs/configuration/examples.md) |
52
58
  | Add domain-specific reviewers | [Lenses](docs/src/content/docs/configuration/lenses.md) |
53
59
  | Review React, Next.js, Node, Go, Rust, Java, .NET or Python code, or import any skill as a lens | [Stack packs](docs/src/content/docs/configuration/stacks.md) |
60
+ | Use with pstack, or any plugin's skills as lenses | [pstack](docs/src/content/docs/integrations/pstack.md) |
54
61
  | Select models by role | [Model routing](docs/src/content/docs/configuration/models.md) |
55
62
  | Run without your laptop | [GitHub Actions](docs/src/content/docs/integrations/github-actions.md) |
56
63
  | Get told when a PR needs you | [Notifications](docs/src/content/docs/integrations/notifications.md) |
@@ -50,3 +50,33 @@ These lenses adapt material from the [OWASP Secure Agent Playbook](https://githu
50
50
  | `lenses/owasp-llm/` | `plugins/ai-security-skills/` plays and skills for the OWASP LLM Top 10 2025, the Agentic Top 10 2026 and MCP server review |
51
51
 
52
52
  The source is licensed under the [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/) (CC-BY-4.0). The adapted lenses carry the same licence and name their source commit in their frontmatter.
53
+
54
+ ## pstack
55
+
56
+ `lenses/pstack/` adapts the principle skills of [pstack](https://github.com/cursor/plugins/tree/main/pstack) by Lauren Tan, version 0.15.29 (`skills/principle-*`). Each rule condenses one or more principles into a review line, cut to what a diff can show.
57
+
58
+ It is used under the MIT License:
59
+
60
+ ```
61
+ MIT License
62
+
63
+ Copyright (c) 2026 Lauren Tan
64
+
65
+ Permission is hereby granted, free of charge, to any person obtaining a copy
66
+ of this software and associated documentation files (the "Software"), to deal
67
+ in the Software without restriction, including without limitation the rights
68
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
69
+ copies of the Software, and to permit persons to whom the Software is
70
+ furnished to do so, subject to the following conditions:
71
+
72
+ The above copyright notice and this permission notice shall be included in all
73
+ copies or substantial portions of the Software.
74
+
75
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
76
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
77
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
78
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
79
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
80
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
81
+ SOFTWARE.
82
+ ```
@@ -0,0 +1,33 @@
1
+ ---
2
+ name: pstack
3
+ description: pstack's engineering principles as code review rules. Flags changes that work against the principles pstack-driven agents are told to follow. Covers a symptom patched where the fault surfaced, guards that hide a state that should never exist, validation scattered past the boundary, raw external data trusted without a parse, interchangeable primitives, domain rules spread across conditionals, one-caller layers and wider mutable state, old APIs kept beside their replacement, steps that break when run twice, shared write targets, tests that cannot fail or are pinned to internals, and numbers or claims the PR states without evidence. Use as a review lens or as a stamp rule pack.
4
+ ---
5
+
6
+ # pstack
7
+
8
+ These rules come from the principles in
9
+ [pstack](https://github.com/cursor/plugins/tree/main/pstack) by Lauren Tan
10
+ (MIT). A team whose agents work through pstack's `poteto-mode` gets reviews
11
+ that check the same principles. Review whether the change fixes faults where
12
+ they start, keeps checks at the boundary, lets the types and data structures
13
+ carry the domain, and proves what it claims.
14
+
15
+ ## Review
16
+
17
+ - **fix-root-cause**: A fix changes the first place the system went wrong, not the place the symptom showed. Flag: a guard, retry, clamp, default value or swallowed error added where a bad state surfaced, when nothing shows that state is legitimate; the same fault left in sibling code the fix did not touch; a workaround justified by a long comment. Why: a symptom fix hides the evidence and the fault surfaces somewhere else.
18
+ - **boundary-checks**: Input is validated and parsed into typed values where it enters (CLI arguments, config, environment, network, files, database rows, model output), and trusted inside. Flag: external data used without a parse at the point it enters; the same value re-checked deep in a call chain the boundary already checked; a transport, storage or framework type exposed through the module's public surface. Why: scattered checks are noisy, and the one that matters is missing.
19
+ - **types-carry-meaning**: Two values that share a primitive but mean different things cannot be swapped, and a union is handled exhaustively. Flag: two same-typed parameters that are easy to pass in the wrong order (`userId, orderId: string`); a switch over a union with no exhaustiveness check; a hand-written type that duplicates one a schema, migration or spec already owns. Why: the compiler can catch these and a reviewer often cannot.
20
+ - **model-the-domain**: The domain lives in one structure: a state machine, discriminated union, lookup table or typed model. Flag: a new branch added to an existing if/else chain over the same kind of value; a second boolean that must stay in sync with a first; the same domain rule repeated across phase-named modules. Why: every new case adds another place to forget.
21
+ - **reader-load**: Each layer the change adds hides a real decision, and state lives in the smallest scope. Flag: a wrapper or adapter with one caller and no second implementation; a layer that repeats the methods and arguments of the one below; a new module-level or shared mutable field where a local or a return value would do; a value kept in sync by hand where it could be derived. Why: readers trace every layer and hold every piece of state.
22
+ - **subtract-first**: The change adds no code for needs nobody has shown. Flag: a validator, option, parameter or extension point with no caller; a stub, placeholder or reference with no content; new code beside dead code it could have replaced. Why: speculative code costs every future reader and is rarely the shape the real need takes.
23
+ - **delete-legacy**: A replaced API is removed in the same change once its callers move. Flag: an old function, flag or code path kept beside its replacement with no external user named; a compatibility shim inside one repository; tests that only protect the old implementation. Why: two ways to do one thing become two things to maintain, and agents copy the old one.
24
+ - **idempotent-steps**: A step that changes state converges when it runs twice or after a crash partway through. Flag: a migration, job, command or handler that inserts, appends or sends without checking what already exists; a lock, temp file or claim marker the next run cannot recognise as stale; a write to a final path that a crash can leave half written. Why: retries and restarts are normal, and each one becomes a debugging session.
25
+ - **separate-shared-state**: Concurrent actors do not share a mutable target unless one shared target is a real invariant, and then access is serialised by structure. Flag: two workers, requests or agents writing the same file, key, row or branch; a race handled by a comment or convention; a lock added where separate owned targets would remove the sharing. Why: races are intermittent and expensive to find.
26
+ - **tests-catch-breaks**: A test fails when the behaviour it covers breaks and survives a refactor that keeps that behaviour. Flag: an expected value computed by the code under test; an assertion looser than the contract; a test that only checks data it built itself; an assertion on private helpers or call order where the user-visible result is the contract. Why: a test that cannot fail proves nothing, and one pinned to internals breaks on every refactor.
27
+ - **prove-the-claim**: What the PR description claims about behaviour or performance has evidence in the PR. Flag: a stated speedup, fix or "verified" with no test, script, run output or measurement behind it; a benchmark number with no run count, spread or named limiter. Why: an unverified claim reads the same as a true one.
28
+
29
+ ## Fix
30
+
31
+ - Prefer: the repository's existing parse functions, branded types, state structures and test helpers, found in code next to the change.
32
+ - Never touch: tests that the change did not add, to make a rule pass.
33
+ - Escalate: deleting a legacy API that code outside the diff still calls, introducing a new domain structure across modules, and any `prove-the-claim` finding: the evidence has to come from the author.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jagreehal/shepherd",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "Agent skills that drive a PR to merge-ready: a review swarm, thread triage, CI repair, and a loop that hands the result to stamp.",
5
5
  "license": "MIT",
6
6
  "repository": "github:jagreehal/shepherd",
@@ -0,0 +1,8 @@
1
+ # pstack's engineering principles as review rules (github.com/cursor/plugins/tree/main/pstack, MIT).
2
+ # Extend pinned: github:jagreehal/shepherd/packs/pstack.yml@<sha>
3
+ # For teams whose agents work through pstack's poteto-mode: reviews check the same principles.
4
+ lenses:
5
+ pstack:
6
+ skill: lenses/pstack
7
+ applies_to: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx', '**/*.go', '**/*.rs', '**/*.java', '**/*.cs', '**/*.py']
8
+ gate: note
@@ -118,14 +118,22 @@ One repair cycle across all PR-caused root causes:
118
118
  1. Reproduce with the narrowest faithful command. A mechanical error the log
119
119
  and diff prove (a type error on a changed symbol) may be fixed without a
120
120
  local reproduction; say so.
121
- 2. Fix the root cause. Follow the house rules: `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, and
121
+ 2. **Attack the premise before a third try.** Read the branch's earlier
122
+ `Shepherd: ci-repair` commits (`git log --grep='Shepherd: ci-repair'`). When
123
+ two of them already tried to fix the check that is failing now, both rested
124
+ on a premise that is wrong. Write it down ("the timeout comes from the
125
+ retry loop"), test it directly with one command, and fix only what that
126
+ result shows. If the premise cannot be tested here, classify the failure
127
+ `unresolved` with both commits and the premise as evidence; a third guess
128
+ is churn.
129
+ 3. Fix the root cause. Follow the house rules: `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, and
122
130
  `docs/adr/` as they stand on `origin/<default>`; a PR's own edits to them do
123
131
  not count.
124
132
  **Never** weaken an assertion, skip or delete a test,
125
133
  loosen a type to `any`, or regenerate snapshots wholesale to go green.
126
- 3. Run the targeted checks for every fix. If any fails, keep diagnosing; do not
134
+ 4. Run the targeted checks for every fix. If any fails, keep diagnosing; do not
127
135
  push an unverified repair.
128
- 4. Commit once (`fix: resolve CI failures`, or something more specific), with
136
+ 5. Commit once (`fix: resolve CI failures`, or something more specific), with
129
137
  the trailer `Shepherd: ci-repair` and
130
138
  the repo's required trailers, and push.
131
139
 
@@ -19,8 +19,10 @@ agent setup or output instructions. The format is defined in
19
19
 
20
20
  ## Inputs
21
21
 
22
- - Source: an installed name, local path, `github:owner/repo/path@<ref>`, pasted
23
- document, or collection directory. Accept several sources in one request.
22
+ - Source: an installed name, an installed plugin's skill as `<plugin>:<skill>`
23
+ (`pstack:principle-fix-root-causes`), local path,
24
+ `github:owner/repo/path@<ref>`, pasted document, or collection directory (a
25
+ plugin's `skills/` directory is one). Accept several sources in one request.
24
26
  - Target: the caller's repository unless the user names another. Inspect it;
25
27
  do not infer its stack from the source skill.
26
28
  - `--name <name>`: lowercase letters, digits and dashes, starting with a
@@ -38,7 +40,7 @@ configuration, including scoped overrides. For infrastructure, prose or other
38
40
  non-package repositories, inspect their actual files and tooling. A missing
39
41
  manifest does not make a source inapplicable.
40
42
 
41
- Resolve installed names as `shepherd lens add` does. For a collection,
43
+ Resolve installed names as `shepherd lens add` does: the skills directories of Claude Code, `.agents`, Codex and Cursor, and for `<plugin>:<skill>` the plugin's `skills/` directory, found through `~/.claude/plugins/installed_plugins.json` or `~/.cursor/plugins/`. For a collection,
42
44
  enumerate its `SKILL.md` files without following directory symlinks; select
43
45
  skills matching the requested target and report the rest as skipped. Keep
44
46
  sources separate unless their rules substantially overlap. Work one source
@@ -271,10 +271,12 @@ it; stop at 1 and say so.
271
271
  **a. swarm, when warranted.** Run it when `swarm_marker_sha` is `null`, or
272
272
  HEAD moved and `swarm_marker_sha..HEAD` changes something besides `*.md`,
273
273
  `*.txt`, whitespace, or comments. A head reached only by merging the base
274
- changes nothing to review: when the PR's diff (`gh pr diff`) is byte-identical
275
- to the one swarm last reviewed, skip swarm and move `swarm_marker_sha` to HEAD.
276
- Keep each round's patch under the git directory so the comparison is a file
277
- compare. Without a stored patch to compare, run swarm. Swarm runs **in this loop** (via `Skill`), not
274
+ changes nothing to review: when the PR's diff (`gh pr diff`) has the same
275
+ `git patch-id --verbatim < <patch>` as the one swarm last reviewed, skip swarm
276
+ and move `swarm_marker_sha` to HEAD. The patch id ignores the line numbers and
277
+ blob ids a base merge shifts, and keeps whitespace. Keep each round's patch
278
+ under the git directory so the comparison needs no fetch. Without a stored
279
+ patch to compare, or when either id is empty, run swarm. Swarm runs **in this loop** (from `../swarm/SKILL.md`), not
278
280
  inside a runner, so its reviewer agents are not nested. Pass the PR number, the
279
281
  diff path, the resolved ladder and `models` pins, HEAD, and `since_sha = swarm_marker_sha` when it
280
282
  is set. Set `swarm_marker_sha = HEAD` after.
@@ -6,19 +6,22 @@ How shepherd finds a sub-skill, starts its runner, and briefs it.
6
6
 
7
7
  Sub-skills are installed next to this one: `../swarm/SKILL.md`,
8
8
  `../triage/SKILL.md`, `../ci-repair/SKILL.md`, `../pair/SKILL.md`, and the
9
- `../review-*` lenses. Prefer `Skill("<name>")` when the harness exposes it.
9
+ `../review-*` lenses. Load each by that path, never by name: other skill packs
10
+ ship skills under the same names (pstack has a `swarm` that fans out workers,
11
+ not reviewers), Cursor does not namespace plugin skills, and a plugin install
12
+ prefixes the names (`shepherd:swarm`). The path always finds shepherd's own.
10
13
 
11
14
  A skill you could only read in part is missing. Its stop conditions and
12
15
  degradation rules sit at the end; running a fragment runs without them.
13
16
 
14
17
  ## Starting a runner
15
18
 
16
- - **swarm** runs in the main loop through `Skill("swarm")`. It starts its own
19
+ - **swarm** runs in the main loop: read `../swarm/SKILL.md` and follow it here. It starts its own
17
20
  reviewer agents, and nesting those inside a runner costs a layer of context.
18
21
  - **triage**, **simplify**, and **ci-repair**: one `Agent` each at the second
19
22
  rung (see `models.md`). Tell the
20
- runner the skill name and let it load its own body; loading it here first pays
21
- for it twice.
23
+ runner the skill's absolute path (`<this skill's directory>/../triage/SKILL.md`)
24
+ and let it load its own body; loading it here first pays for it twice.
22
25
  - **simplify**: one `Agent` that applies `../review-simplicity/SKILL.md` in fix
23
26
  mode itself: make the LOW-and-above changes the lens would report, touching
24
27
  only lines the PR changed. It never invokes another skill or starts agents of
@@ -216,6 +216,21 @@ unless the PR's own change depends on the broken code.
216
216
  the commit, or the commit's message) is proof the fix did not hold. Before
217
217
  fixing again, say why it did not (it fixed a sibling path, the wrong root cause,
218
218
  or was reverted), and never resolve it as already fixed on the same evidence.
219
+ When two `Shepherd:` commits have already tried to fix the same concern, both
220
+ rested on a premise that is wrong: write the premise down, test it directly
221
+ (one command, one read of the code it names), and fix only what that shows. If
222
+ you cannot test it, defer the thread with both commits and the premise.
223
+
224
+ **Bots that keep coming back.** Count each review bot's passes on this PR (its
225
+ reviews, by head). From its third pass on, a finding that repeats a concern
226
+ already dismissed on this PR with a reason from the code is resolved as a nit
227
+ with that same reason, once you have checked the reason still holds on the
228
+ current head: re-read the code it cites. A later commit can remove what made
229
+ the concern harmless (validation, a guard, the only caller); when the reason
230
+ no longer holds, classify the finding afresh. Re-litigating a reason that
231
+ still holds is churn. Findings that touch security,
232
+ auth, billing, data or migrations are the exception: defer those rather than
233
+ dismiss them. Never change code only to quiet a bot.
219
234
 
220
235
  **Outdated threads.** GitHub marks a thread outdated when its line changed, not
221
236
  when its concern was met, so an outdated thread is never skipped. Read its
package/src/cli.ts CHANGED
@@ -46,7 +46,7 @@ import { install, type Outcome, pinWorkflow, uninstall } from "./install.ts";
46
46
  import { buildDemo, captureChange, demoBugs, finish, receiptStatus } from "./local.ts";
47
47
  import { prStack } from "./stack.ts";
48
48
  import { flush, recordEvent, traceFile } from "./trace.ts";
49
- import { addLens, BUILT_IN_LENSES, lensTemplates, globalLensFile, lensProblems, newLens, opencodeAgents, opencodeModel, providerKeyEnv, setTier, detectStacks, stackLens, pinModel, repoLensFile, resolveSkill, setLadder, skillDescription, type Lens } from "./lens.ts";
49
+ import { addLens, BUILT_IN_LENSES, pluginRoots, lensTemplates, globalLensFile, lensProblems, newLens, opencodeAgents, opencodeModel, providerKeyEnv, setTier, detectStacks, stackLens, pinModel, repoLensFile, resolveSkill, setLadder, skillDescription, type Lens } from "./lens.ts";
50
50
 
51
51
  const BUNDLE_ROOT = path.resolve(import.meta.dir, "..");
52
52
 
@@ -330,7 +330,11 @@ if (command === "install") {
330
330
  const { model, source } = ciModel(p, process.env.SHEPHERD_MODEL || undefined);
331
331
  const session = opencodeModel(model);
332
332
 
333
- console.log(JSON.stringify({ model: session, source, key_env: providerKeyEnv(session), opencode: opencodeAgents(choice(p)) }));
333
+ const opencode = opencodeAgents(choice(p));
334
+ // Every key the plan's models read, so the workflow can drop the rest before the model runs.
335
+ const keyEnvs = [...new Set([session, ...Object.values(opencode.agent).map((a) => a.model)].flatMap((m) => providerKeyEnv(m) ?? []))].sort();
336
+
337
+ console.log(JSON.stringify({ model: session, source, key_env: providerKeyEnv(session), key_envs: keyEnvs, opencode }));
334
338
  } else if (command === "model-id" && sub) {
335
339
  // A model id as OpenCode spells it, so stamp's provider:model spelling works in a local OpenCode run too.
336
340
  console.log(opencodeModel(sub));
@@ -405,7 +409,10 @@ if (command === "install") {
405
409
 
406
410
  // After the file exists, so a pack named by --from counts as already providing its lenses.
407
411
  if (opts.stacks) addStackLenses(file);
408
- else if (stacks.length) console.log(`detected ${stacks.join(", ")}: run shepherd init --stacks to add their lenses, or extend github:jagreehal/shepherd/packs/<stack>.yml@<sha>`);
412
+ else {
413
+ if (stacks.length) console.log(`detected ${stacks.join(", ")}: run shepherd init --stacks to add their lenses, or extend github:jagreehal/shepherd/packs/<stack>.yml@<sha>`);
414
+ pstackHint("pstack" in policy(true).lenses);
415
+ }
409
416
 
410
417
  const named = policy(true);
411
418
 
@@ -514,6 +521,12 @@ function addStackLenses(file: string): void {
514
521
  }
515
522
 
516
523
  if (!stacks.length) console.log("no stack detected");
524
+ pstackHint("pstack" in have);
525
+ }
526
+
527
+ /** pstack installed here: its principles are a lens away, so reviews check what its agents are told to do. */
528
+ function pstackHint(declared: boolean): void {
529
+ if (!declared && pluginRoots(homedir()).has("pstack")) console.log("pstack is installed: review against its principles with shepherd lens new pstack --from pstack");
517
530
  }
518
531
 
519
532
  /** Team policy from the default branch, the source swarm reviews under, or from your working tree. */
package/src/doctor.ts CHANGED
@@ -6,7 +6,7 @@ import { parse } from "yaml";
6
6
  import { z } from "zod";
7
7
  import { defaultBranchReader, defaultBranchRef, fetchPackLenses, ghFetch, ghFetchDir, loadPolicy, type Config } from "./config.ts";
8
8
  import { bundledSkills } from "./install.ts";
9
- import { lensProblems } from "./lens.ts";
9
+ import { lensProblems, pluginRoots, skillDirs } from "./lens.ts";
10
10
 
11
11
  export type Check = { check: string; status: "ok" | "warn" | "fail"; detail: string; fix?: string };
12
12
 
@@ -20,15 +20,8 @@ const attempt = <T>(f: () => T): T | Error => {
20
20
  }
21
21
  };
22
22
 
23
- // Where a harness looks for skills: Claude Code, the shared .agents layout, Codex, OpenCode.
24
- const SKILL_DIRS = (home: string, repo: string) => [
25
- path.join(home, ".claude/skills"),
26
- path.join(repo, ".claude/skills"),
27
- path.join(home, ".agents/skills"),
28
- path.join(repo, ".agents/skills"),
29
- path.join(home, ".codex/skills"),
30
- path.join(home, ".config/opencode/skills"),
31
- ];
23
+ // Where a harness looks for skills: the bare-name directories, plus OpenCode's.
24
+ const SKILL_DIRS = (home: string, repo: string) => [...skillDirs(home, repo), path.join(home, ".config/opencode/skills")];
32
25
 
33
26
  /**
34
27
  * True when a workflow runs stamp on pull requests: a step that uses stamp's action, runs its package, or
@@ -80,10 +73,20 @@ export function doctor(bundleRoot: string, home: string, repo: string, personal:
80
73
  if (read instanceof Error) add("default branch", "fail", read.message, "git fetch origin <default branch>: policy and lenses are read from it");
81
74
  else add("default branch", "ok", "fetched");
82
75
 
83
- const missing = bundledSkills(path.join(bundleRoot, "skills")).filter((s) => !SKILL_DIRS(home, repo).some((d) => existsSync(path.join(d, s, "SKILL.md"))));
76
+ const bundled = bundledSkills(path.join(bundleRoot, "skills"));
77
+ const plugins = pluginRoots(home);
78
+ const asPlugin = plugins.get("shepherd");
79
+ const dirs = [...SKILL_DIRS(home, repo), ...(asPlugin ? [path.join(asPlugin, "skills")] : [])];
80
+ const missing = bundled.filter((s) => !dirs.some((d) => existsSync(path.join(d, s, "SKILL.md"))));
84
81
 
85
- if (missing.length) add("skills", "fail", `not installed: ${missing.join(", ")}`, "bunx @jagreehal/shepherd install (or --project, or --target <your agent's skills dir>)");
86
- else add("skills", "ok", "every bundled skill is installed");
82
+ if (missing.length) add("skills", "fail", `not installed: ${missing.join(", ")}`, "bunx @jagreehal/shepherd install (or --project, or --target <your agent's skills dir>), or install the shepherd plugin");
83
+ else add("skills", "ok", `every bundled skill is installed${asPlugin ? " (as a plugin)" : ""}`);
84
+
85
+ // Another plugin's skill under one of shepherd's names (pstack ships a `swarm`): Cursor does not namespace
86
+ // plugin skills, so `/swarm` there may load either. Shepherd's own loop loads its sub-skills by path.
87
+ const shared = [...plugins].filter(([name]) => name !== "shepherd").flatMap(([name, root]) => bundled.filter((s) => existsSync(path.join(root, "skills", s, "SKILL.md"))).map((s) => `${name}:${s}`));
88
+
89
+ if (shared.length) add("skill names", "warn", `other plugins ship skills under shepherd's names: ${shared.join(", ")}. /shepherd is unaffected; typed on its own, the name may load either`, "in Claude Code type the plugin prefix (/pstack:swarm); in Cursor, pick the skill from the / menu by its description");
87
90
 
88
91
  if (read instanceof Error) return checks;
89
92
 
package/src/lens.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  // Custom lenses: any skill, wrapped by swarm as a review-only reviewer whose `## Fix` section steers
2
2
  // triage. This file reads and writes the lens files and finds skills on disk; swarm itself reads the
3
3
  // repository's file from the default branch at review time (skills/swarm/references/custom-lenses.md).
4
- import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
4
+ import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
5
5
  import path from "node:path";
6
6
  import { parse, stringify } from "yaml";
7
7
  import { z } from "zod";
@@ -288,16 +288,68 @@ export function detectStacks(files: string[], read: (rel: string) => string | nu
288
288
  return lensTemplates().filter((t) => found.has(t));
289
289
  }
290
290
 
291
- /** The directory holding the skill's SKILL.md: a path against the repository, or a name in the usual skills directories. */
291
+ // Claude Code's record of installed plugins, keyed `<plugin>@<marketplace>`.
292
+ const InstallRecord = z.object({ plugins: z.record(z.string(), z.array(z.object({ installPath: z.string() }))) });
293
+
294
+ // A skill an installed plugin ships, as Claude Code names it: `<plugin>:<skill>`, e.g. `pstack:principle-fix-root-causes`.
295
+ const PLUGIN_SKILL = /^([\w.-]+):([\w.-]+)$/;
296
+
297
+ const subdirs = (dir: string) => (existsSync(dir) ? readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => path.join(dir, d.name)) : []);
298
+
299
+ /** The newest of a plugin's cached versions: harnesses keep old ones beside it until they prune. */
300
+ const newest = (dirs: string[]) => dirs.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
301
+
302
+ /**
303
+ * Each installed plugin's root, by plugin name: Claude Code's from its install record, Cursor's from its
304
+ * plugin cache (`<marketplace>/<plugin>/<version>`) and local plugins. A plugin keeps its skills in `skills/`.
305
+ */
306
+ export function pluginRoots(home: string): Map<string, string> {
307
+ const roots = new Map<string, string>();
308
+ const file = path.join(home, ".claude", "plugins", "installed_plugins.json");
309
+ const record = InstallRecord.safeParse(existsSync(file) ? parseJson(readFileSync(file, "utf8")) : null);
310
+
311
+ for (const [key, installs] of Object.entries(record.success ? record.data.plugins : {})) {
312
+ const root = installs.at(-1)?.installPath;
313
+
314
+ if (root) roots.set(key.split("@")[0]!, root);
315
+ }
316
+
317
+ const cursor = path.join(home, ".cursor", "plugins");
318
+
319
+ for (const plugin of subdirs(path.join(cursor, "cache")).flatMap(subdirs)) {
320
+ const root = newest(subdirs(plugin));
321
+
322
+ if (root && !roots.has(path.basename(plugin))) roots.set(path.basename(plugin), root);
323
+ }
324
+
325
+ for (const root of subdirs(path.join(cursor, "local"))) if (!roots.has(path.basename(root))) roots.set(path.basename(root), root);
326
+
327
+ return roots;
328
+ }
329
+
330
+ /** Where a harness looks for skills by bare name: Claude Code, the shared .agents layout, Codex, Cursor. */
331
+ export const skillDirs = (home: string, repoRoot: string) =>
332
+ [".claude/skills", ".agents/skills", ".codex/skills", ".cursor/skills"].map((d) => path.join(home, d)).concat([".claude/skills", ".agents/skills", ".cursor/skills"].map((d) => path.join(repoRoot, d)));
333
+
334
+ /**
335
+ * The directory holding the skill's SKILL.md: a pinned pack lens, a path against the repository, an
336
+ * installed plugin's skill (`<plugin>:<skill>`), or a name in the usual skills directories.
337
+ */
292
338
  export function resolveSkill(ref: string, home: string, repoRoot: string): string | null {
293
339
  const pinned = lensCache(home, ref);
294
340
 
295
341
  if (pinned) return existsSync(path.join(pinned, "SKILL.md")) ? pinned : null;
296
- const expanded = ref.startsWith("~/") ? path.join(home, ref.slice(2)) : ref;
342
+ const plugin = PLUGIN_SKILL.exec(ref);
343
+
344
+ if (plugin) {
345
+ const root = pluginRoots(home).get(plugin[1]!);
346
+ const dir = root && path.join(root, "skills", plugin[2]!);
297
347
 
298
- const candidates = expanded.includes("/")
299
- ? [path.resolve(repoRoot, expanded)]
300
- : [".claude/skills", ".agents/skills", ".codex/skills"].map((d) => path.join(home, d, expanded)).concat([".claude/skills", ".agents/skills"].map((d) => path.join(repoRoot, d, expanded)));
348
+ return dir && existsSync(path.join(dir, "SKILL.md")) ? dir : null;
349
+ }
350
+
351
+ const expanded = ref.startsWith("~/") ? path.join(home, ref.slice(2)) : ref;
352
+ const candidates = expanded.includes("/") ? [path.resolve(repoRoot, expanded)] : skillDirs(home, repoRoot).map((d) => path.join(d, expanded));
301
353
 
302
354
  return candidates.find((dir) => existsSync(path.join(dir, "SKILL.md"))) ?? null;
303
355
  }
@@ -112,8 +112,10 @@ jobs:
112
112
  key_env=$(jq -r '.key_env // empty' <<<"$plan")
113
113
  if [ -n "${SHEPHERD_API_KEY:-}" ] && [ -n "$key_env" ] && [ -z "${!key_env:-}" ]; then export "$key_env=$SHEPHERD_API_KEY"; fi
114
114
  unset SHEPHERD_API_KEY
115
- # An unset secret arrives as "": a blank key would hide the provider's other credentials.
116
- for k in OPENCODE_API_KEY ANTHROPIC_API_KEY OPENAI_API_KEY OPENROUTER_API_KEY DEEPSEEK_API_KEY GROQ_API_KEY MISTRAL_API_KEY GOOGLE_GENERATIVE_AI_API_KEY XAI_API_KEY AWS_BEARER_TOKEN_BEDROCK; do [ -n "${!k:-}" ] || unset "$k"; done
115
+ # Only the keys the plan's models read reach the model, and a blank one (an unset secret) would hide the
116
+ # provider's other credentials.
117
+ keys=" $(jq -r '.key_envs | join(" ")' <<<"$plan") "
118
+ for k in OPENCODE_API_KEY ANTHROPIC_API_KEY OPENAI_API_KEY OPENROUTER_API_KEY DEEPSEEK_API_KEY GROQ_API_KEY MISTRAL_API_KEY GOOGLE_GENERATIVE_AI_API_KEY XAI_API_KEY AWS_BEARER_TOKEN_BEDROCK; do { [ -n "${!k:-}" ] && [[ "$keys" == *" $k "* ]]; } || unset "$k"; done
117
119
  OPENCODE_CONFIG_CONTENT=$(jq -c .opencode <<<"$plan") && export OPENCODE_CONFIG_CONTENT
118
120
  opencode run --auto -m "$model" --title "shepherd audit" "Run a security audit of this repository (the current directory, its default branch).
119
121
  For each play name in: $PLAYS
@@ -147,7 +149,7 @@ jobs:
147
149
  - uses: actions/upload-artifact@v4
148
150
  with:
149
151
  name: shepherd-audit
150
- path: ${{ runner.temp }}/audit
152
+ path: ${{ runner.temp }}/audit/report.md # the checked file only, never scanner output beside it
151
153
  retention-days: 30
152
154
 
153
155
  report:
@@ -114,8 +114,10 @@ jobs:
114
114
  key_env=$(jq -r '.key_env // empty' <<<"$plan")
115
115
  if [ -n "${SHEPHERD_API_KEY:-}" ] && [ -n "$key_env" ] && [ -z "${!key_env:-}" ]; then export "$key_env=$SHEPHERD_API_KEY"; fi
116
116
  unset SHEPHERD_API_KEY
117
- # An unset secret arrives as "": a blank key would hide the provider's other credentials.
118
- for k in OPENCODE_API_KEY ANTHROPIC_API_KEY OPENAI_API_KEY OPENROUTER_API_KEY DEEPSEEK_API_KEY GROQ_API_KEY MISTRAL_API_KEY GOOGLE_GENERATIVE_AI_API_KEY XAI_API_KEY AWS_BEARER_TOKEN_BEDROCK; do [ -n "${!k:-}" ] || unset "$k"; done
117
+ # Only the keys the plan's models read reach the model, and a blank one (an unset secret) would hide the
118
+ # provider's other credentials.
119
+ keys=" $(jq -r '.key_envs | join(" ")' <<<"$plan") "
120
+ for k in OPENCODE_API_KEY ANTHROPIC_API_KEY OPENAI_API_KEY OPENROUTER_API_KEY DEEPSEEK_API_KEY GROQ_API_KEY MISTRAL_API_KEY GOOGLE_GENERATIVE_AI_API_KEY XAI_API_KEY AWS_BEARER_TOKEN_BEDROCK; do { [ -n "${!k:-}" ] && [[ "$keys" == *" $k "* ]]; } || unset "$k"; done
119
121
  OPENCODE_CONFIG_CONTENT=$(jq -c .opencode <<<"$plan") && export OPENCODE_CONFIG_CONTENT
120
122
  opencode run --auto -m "$model" --title "incident" "Load the incident skill and run it on the signal in $RUNNER_TEMP/signal.txt
121
123
  (a run URL, or an error or alert text).
@@ -249,8 +249,10 @@ jobs:
249
249
  key_env=$(jq -r '.key_env // empty' <<<"$plan")
250
250
  if [ -n "${SHEPHERD_API_KEY:-}" ] && [ -n "$key_env" ] && [ -z "${!key_env:-}" ]; then export "$key_env=$SHEPHERD_API_KEY"; fi
251
251
  unset SHEPHERD_API_KEY
252
- # An unset secret arrives as "": a blank key would hide the provider's other credentials.
253
- for k in OPENCODE_API_KEY ANTHROPIC_API_KEY OPENAI_API_KEY OPENROUTER_API_KEY DEEPSEEK_API_KEY GROQ_API_KEY MISTRAL_API_KEY GOOGLE_GENERATIVE_AI_API_KEY XAI_API_KEY AWS_BEARER_TOKEN_BEDROCK; do [ -n "${!k:-}" ] || unset "$k"; done
252
+ # Only the keys the plan's models read reach the model, and a blank one (an unset secret) would hide the
253
+ # provider's other credentials.
254
+ keys=" $(jq -r '.key_envs | join(" ")' <<<"$plan") "
255
+ for k in OPENCODE_API_KEY ANTHROPIC_API_KEY OPENAI_API_KEY OPENROUTER_API_KEY DEEPSEEK_API_KEY GROQ_API_KEY MISTRAL_API_KEY GOOGLE_GENERATIVE_AI_API_KEY XAI_API_KEY AWS_BEARER_TOKEN_BEDROCK; do { [ -n "${!k:-}" ] && [[ "$keys" == *" $k "* ]]; } || unset "$k"; done
254
256
  OPENCODE_CONFIG_CONTENT=$(jq -c .opencode <<<"$plan") && export OPENCODE_CONFIG_CONTENT
255
257
  opencode run --auto -m "$model" --title "shepherd #$PR" "Load the shepherd skill and run exactly one iteration on PR $PR in handoff mode:
256
258
  SHEPHERD_HANDOFF is set, so follow the skill's Handoff mode. You are running in GitHub Actions on the PR branch,