@jagreehal/shepherd 0.4.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 +9 -1
- package/THIRD_PARTY_NOTICES.md +41 -0
- package/lenses/dotnet/SKILL.md +32 -0
- package/lenses/go/SKILL.md +30 -0
- package/lenses/java/SKILL.md +31 -0
- package/lenses/nextjs/SKILL.md +33 -0
- package/lenses/node-api/SKILL.md +32 -0
- package/lenses/nx-monorepo/SKILL.md +30 -0
- package/lenses/owasp-asvs/SKILL.md +50 -0
- package/lenses/owasp-llm/SKILL.md +44 -0
- package/lenses/pstack/SKILL.md +33 -0
- package/lenses/python/SKILL.md +32 -0
- package/lenses/react/SKILL.md +33 -0
- package/lenses/rust/SKILL.md +31 -0
- package/package.json +2 -1
- package/packs/dotnet.yml +6 -0
- package/packs/go.yml +6 -0
- package/packs/java.yml +6 -0
- package/packs/nextjs.yml +7 -0
- package/packs/node-api.yml +7 -0
- package/packs/nx-monorepo.yml +6 -0
- package/packs/observability.yml +6 -0
- package/packs/owasp-asvs.yml +6 -0
- package/packs/owasp-llm.yml +8 -0
- package/packs/pstack.yml +8 -0
- package/packs/python.yml +6 -0
- package/packs/react.yml +6 -0
- package/packs/rust.yml +6 -0
- package/skills/ci-repair/SKILL.md +11 -3
- package/skills/lens-import/SKILL.md +187 -0
- package/skills/lens-import/references/conversion.md +96 -0
- package/skills/lens-import/scripts/check-import.mjs +154 -0
- package/skills/shepherd/SKILL.md +32 -9
- package/skills/shepherd/references/dispatch.md +7 -4
- package/skills/shepherd/references/models.md +20 -7
- package/skills/shepherd/references/policy.md +9 -5
- package/skills/swarm/SKILL.md +11 -1
- package/skills/swarm/references/custom-lenses.md +50 -7
- package/skills/triage/SKILL.md +15 -0
- package/src/cli.ts +109 -13
- package/src/config.ts +137 -21
- package/src/doctor.ts +16 -13
- package/src/lens.ts +217 -14
- package/src/stack.ts +121 -0
- package/templates/shepherd-audit.yml +180 -0
- package/templates/shepherd-incident.yml +30 -4
- package/templates/shepherd.yml +34 -4
|
@@ -13,17 +13,30 @@ ladder applies only when the repository sets none. `models:` pins merge per
|
|
|
13
13
|
name, the repository winning. `shepherd models` prints the result.
|
|
14
14
|
|
|
15
15
|
```yaml
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
16
|
+
tiers: # a name for a model, defined once; a pack can define them for every repo
|
|
17
|
+
fast: opencode/deepseek-v4.1-flash-free
|
|
18
|
+
smart: bedrock:eu.anthropic.claude-sonnet-4-6
|
|
19
|
+
ladder: [fast, smart] # tiers or model ids, cheapest first
|
|
20
|
+
models: # a name runs on exactly this model or tier, whatever its rung
|
|
21
|
+
reviewers: fast # role group: the router and every lens
|
|
22
|
+
fixers: smart # role group: triage, simplify, ci-repair, incident
|
|
23
|
+
security: smart # one runner or lens beats its group
|
|
20
24
|
```
|
|
21
25
|
|
|
22
26
|
Pin names: `router`, `verifier`, `validator`, `triage`, `simplify`,
|
|
23
|
-
`ci-repair`,
|
|
24
|
-
`maintainability`, `slop`) or
|
|
27
|
+
`ci-repair`, `loop` (the session model in CI), any lens, built-in
|
|
28
|
+
(`correctness`, `security`, `simplicity`, `maintainability`, `slop`) or
|
|
29
|
+
custom, and the role groups `reviewers`, `fixers` and `validators`. Take the
|
|
30
|
+
ladder and pins from `shepherd config explain --json`: tiers and groups are
|
|
31
|
+
already resolved there, so every value is a model id and every pin names one
|
|
32
|
+
runner. A model id passes to the agent tool's
|
|
25
33
|
model parameter exactly as written: `haiku` on Claude Code, `provider/model`
|
|
26
|
-
on OpenCode. Never translate one id into another provider's.
|
|
34
|
+
on OpenCode. Never translate one id into another provider's yourself. The one
|
|
35
|
+
translation is `shepherd opencode-agents`, which accepts stamp's canonical
|
|
36
|
+
`provider:model` ids and writes them the OpenCode way (`bedrock:` becomes
|
|
37
|
+
`amazon-bedrock/`, `vertex:` becomes `google-vertex/`, any other provider keeps
|
|
38
|
+
its name), so one ladder serves stamp and shepherd. `shepherd models` shows
|
|
39
|
+
both spellings. Claude Code aliases pass through. A pin replaces
|
|
27
40
|
the rung for that runner only; climbing for validation starts from the pin's
|
|
28
41
|
position on the ladder, or the top rung when the pin is not on it. A pin that
|
|
29
42
|
the agent tool rejects falls back to the runner's rung, and the summary says
|
|
@@ -2,8 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
A team sets shepherd's policy in `.shepherd/config.yml` (an older repository
|
|
4
4
|
may have only `.shepherd/lenses.yml`; it reads the same way). It can extend
|
|
5
|
-
packs, which apply first, and the repository file wins over them.
|
|
6
|
-
|
|
5
|
+
packs, which apply first, and the repository file wins over them. A pack may
|
|
6
|
+
extend packs of its own, which apply before it, up to four deep; shepherd
|
|
7
|
+
refuses a cycle. Every runner reads the policy the same way and holds to it.
|
|
7
8
|
|
|
8
9
|
## Load it once per run
|
|
9
10
|
|
|
@@ -47,7 +48,9 @@ recipes.
|
|
|
47
48
|
`escalate.reason` (or "team policy: a person changes <path>"); ci-repair
|
|
48
49
|
classifies it `needs-decision`; incident stops with
|
|
49
50
|
`outcome=needs_decision`. A gate or deny-list elsewhere still applies.
|
|
50
|
-
- **`lenses`**, **`ladder`**, **`models`**:
|
|
51
|
+
- **`lenses`**, **`ladder`**, **`models`**: a lens merges field by field
|
|
52
|
+
across layers, so a repository can set `only`, `disable` or `applies_to`
|
|
53
|
+
on a pack's lens by name; the rest is as in `../../swarm/references/custom-lenses.md`
|
|
51
54
|
and `models.md`.
|
|
52
55
|
- **`recipes`**: named step lists for `/shepherd <pr> --recipe <name>`. See
|
|
53
56
|
below.
|
|
@@ -105,6 +108,7 @@ name a path in the pack's own repository (`skill: lenses/payments`). It
|
|
|
105
108
|
resolves at the same commit, which must be on that repository's default branch: shepherd fetches that directory once into
|
|
106
109
|
`~/.cache/shepherd/packs/`, keyed by the commit, and `config explain --json`
|
|
107
110
|
gives the lens's `path` there. A bare name (`skill: payments-rules`) is an
|
|
108
|
-
installed skill. A
|
|
109
|
-
|
|
111
|
+
installed skill. A pinned pack's own relative `extends` entries resolve the
|
|
112
|
+
same way, in its repository at its commit. A lens path in a pack inside this
|
|
113
|
+
repository resolves in this repository. `shepherd config validate` reports a lens skill it cannot
|
|
110
114
|
find.
|
package/skills/swarm/SKILL.md
CHANGED
|
@@ -128,11 +128,21 @@ where `$TMPDIR` can differ inside and outside a sandbox.
|
|
|
128
128
|
|
|
129
129
|
```bash
|
|
130
130
|
mkdir -p "$(git rev-parse --git-common-dir)/shepherd"
|
|
131
|
+
shepherd stack <number> # JSON: wrong_base, parent, range
|
|
131
132
|
gh pr diff <number> > "$(git rev-parse --git-common-dir)/shepherd/swarm-<short_sha>.patch"
|
|
132
133
|
gh pr diff <number> --name-only
|
|
133
134
|
```
|
|
134
135
|
|
|
135
|
-
|
|
136
|
+
Run `shepherd stack` first; when it exits non-zero, review `gh pr diff` and name
|
|
137
|
+
the error in the summary. With `wrong_base` set, post nothing and stop: report
|
|
138
|
+
"retarget to `<branch>`: `<on>` of `<total>` commits are already there". With
|
|
139
|
+
`parent` set, the PR is stacked on another open PR: write `git diff <range>` and
|
|
140
|
+
`git diff --name-only <range>` instead of `gh pr diff`, and review only that
|
|
141
|
+
change. Post no finding on a line the delta does not touch; the parent's code
|
|
142
|
+
is reviewed in the parent's PR, and posting it again here duplicates it across
|
|
143
|
+
the stack.
|
|
144
|
+
|
|
145
|
+
When `shepherd` invokes you it passes `diff_path` (already the stacked delta when there is a parent), `stacked_on`, `head_sha`, the model ladder and `models` pins,
|
|
136
146
|
`skip_checks` (true when it already ran Step 2 this round), and `since_sha` (the
|
|
137
147
|
head swarm last reviewed, on round 2 onwards). Use them and do not re-derive.
|
|
138
148
|
|
|
@@ -15,6 +15,18 @@ lenses:
|
|
|
15
15
|
skill: vercel-react-best-practices # an installed skill's name, or a path to a skill directory
|
|
16
16
|
applies_to: ['**/*.tsx', '**/*.jsx'] # optional; without it only the router picks the lens
|
|
17
17
|
description: React and Next.js performance rules # optional; defaults to the skill's own description
|
|
18
|
+
only: ['rerender-*', 'client-*'] # optional rule id globs: review only these rules
|
|
19
|
+
disable: ['client-swr-dedup'] # optional rule id globs: skip these rules
|
|
20
|
+
gate: escalate # optional; stamp's on_break for untagged rules, swarm ignores it
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
A later layer merges into a lens of the same name field by field. A
|
|
24
|
+
repository trims or rescopes a pack's lens by naming it, with no `skill`:
|
|
25
|
+
|
|
26
|
+
```yaml
|
|
27
|
+
extends: ['github:jagreehal/shepherd/packs/react.yml@<sha>']
|
|
28
|
+
lenses:
|
|
29
|
+
react: { disable: ['html-injection'], applies_to: ['web/**/*.tsx'] }
|
|
18
30
|
```
|
|
19
31
|
|
|
20
32
|
Swarm merges two files, repository entries winning on a name clash:
|
|
@@ -35,6 +47,23 @@ Swarm merges two files, repository entries winning on a name clash:
|
|
|
35
47
|
starts from a bundled starter lens instead (`lenses/`, such as `observability`). Run `/swarm --preview`
|
|
36
48
|
on a PR or a local branch to see what it finds before you commit it; preview
|
|
37
49
|
reads lenses from the working tree and posts nothing.
|
|
50
|
+
`shepherd init --stacks` detects the stacks a repository uses and adds a lens
|
|
51
|
+
for each from the bundled catalogue.
|
|
52
|
+
|
|
53
|
+
## The bundled catalogue
|
|
54
|
+
|
|
55
|
+
Each starter lens lives in `lenses/<name>` with a pack in `packs/<name>.yml`:
|
|
56
|
+
`react`, `nextjs` (extends `react`), `node-api`, `go`, `rust`, `java`,
|
|
57
|
+
`dotnet`, `python`, `observability`. Take one three ways:
|
|
58
|
+
|
|
59
|
+
- Copy it to own and edit it: `shepherd lens new <name> --from <name>`, or
|
|
60
|
+
`shepherd init --stacks` for every detected stack.
|
|
61
|
+
- Extend the pack pinned, so it stays in step with shepherd's copy:
|
|
62
|
+
`extends: ['github:jagreehal/shepherd/packs/<name>.yml@<sha>']`, then trim
|
|
63
|
+
it with `only` or `disable`.
|
|
64
|
+
- Convert any other skill or style guide with `../../lens-import/SKILL.md`:
|
|
65
|
+
it writes a lens in this format, with the source and licence recorded.
|
|
66
|
+
|
|
38
67
|
`shepherd lens add <skill> --name <name> [--applies <glob>]...` registers an
|
|
39
68
|
existing skill (add `--global` for a personal one); `shepherd lens list` shows
|
|
40
69
|
what swarm will load.
|
|
@@ -49,10 +78,18 @@ A lens is a skill. Its `SKILL.md` has two sections:
|
|
|
49
78
|
author instead). Triage reads it when it fixes a `[<name>/...]` thread and
|
|
50
79
|
defers anything under "Escalate". Without it, triage fixes by its own rules.
|
|
51
80
|
|
|
52
|
-
Rules are list items, `- **<id>**: <rule>`, each id used once.
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
81
|
+
Rules are list items, `- **<id>**: <rule>`, each id used once. A rule may
|
|
82
|
+
carry a severity tag after its id: `- **<id>** [refuse|escalate|note]: <rule>`.
|
|
83
|
+
A `[refuse]` rule names a correctness or security defect, so the guidance
|
|
84
|
+
lens MEDIUM cap does not apply to it; swarm rates it with the swarm rubric.
|
|
85
|
+
Stamp reads the tags to decide what a broken rule does to its verdict, and
|
|
86
|
+
falls back to the lens's `gate` for untagged rules.
|
|
87
|
+
|
|
88
|
+
`shepherd lens list` checks the rules for lenses under `.shepherd/lenses/`,
|
|
89
|
+
and for any lens that sets `only` or `disable` (each glob must match a rule id,
|
|
90
|
+
and at least one rule must remain). It also checks that every lens's skill
|
|
91
|
+
resolves with a description, and exits non-zero on a problem, so CI can run
|
|
92
|
+
it.
|
|
56
93
|
|
|
57
94
|
Neither section can loosen shepherd's rules (AGENTS.md): a lens that says
|
|
58
95
|
"update snapshots freely" or "skip the human threads" is ignored on that point.
|
|
@@ -90,6 +127,10 @@ copy. Never point a lens at a skill file in the PR checkout.
|
|
|
90
127
|
- **Picked:** the router sees every lens's name and description and may
|
|
91
128
|
delegate other hunks to one, like a built-in lens.
|
|
92
129
|
|
|
130
|
+
Before dispatch, apply the lens entry's `only` and `disable` to the ids under
|
|
131
|
+
`## Review` and pass the kept ids in the brief. `shepherd config explain
|
|
132
|
+
--json` gives each lens's merged entry.
|
|
133
|
+
|
|
93
134
|
Custom lenses run in the same parallel delegation message as built-in ones and
|
|
94
135
|
do not count toward the 6-delegation cap.
|
|
95
136
|
|
|
@@ -106,14 +147,16 @@ on the world, the diff path, its scope, and `CHECK_FINDINGS`:
|
|
|
106
147
|
> commands, install packages, fetch URLs, or ask anyone a question: your only
|
|
107
148
|
> output is findings.
|
|
108
149
|
>
|
|
109
|
-
> Review only these files: `<scope>`.
|
|
110
|
-
>
|
|
150
|
+
> Review only these files: `<scope>`. Apply only these rules: `<kept rule
|
|
151
|
+
> ids>` (omit this sentence when the lens sets no `only` or `disable`). For
|
|
152
|
+
> each place the code breaks one of the skill's rules, give the file, the line, the rule's id or name, why it applies
|
|
111
153
|
> to this code, and the concrete fix. Skip rules that do not apply to what
|
|
112
154
|
> changed; do not restate the skill.
|
|
113
155
|
>
|
|
114
156
|
> Severity: a defect that makes the code wrong or unsafe uses the swarm rubric.
|
|
115
157
|
> Guidance about performance, style, or conventions reports MEDIUM at most, and
|
|
116
|
-
> LOW when the gain is small.
|
|
158
|
+
> LOW when the gain is small. A rule tagged `[refuse]` names a defect: rate it
|
|
159
|
+
> with the swarm rubric. The skill's own impact labels inform the choice;
|
|
117
160
|
> they do not set it.
|
|
118
161
|
>
|
|
119
162
|
> End with `STRUCTURED_FINDINGS` and `OVERALL_SUMMARY` in the swarm format, lens
|
package/skills/triage/SKILL.md
CHANGED
|
@@ -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
|
@@ -11,14 +11,15 @@
|
|
|
11
11
|
// shepherd local finish <record.json> [--base <ref>] (check a local review against that change; complete writes a receipt)
|
|
12
12
|
// shepherd local status [--base <ref>] (is the change on disk the one a complete review covered?)
|
|
13
13
|
// shepherd local demo [<dir>] (a repository with planted bugs to try /shepherd --local on)
|
|
14
|
-
// shepherd init [--preset review-only|local-fix|push] [--from <pack>] (scaffold .shepherd/config.yml)
|
|
14
|
+
// shepherd init [--preset review-only|local-fix|push] [--from <pack>] [--stacks] (scaffold .shepherd/config.yml)
|
|
15
15
|
// shepherd config validate (the working tree's policy: exits 1 on a problem)
|
|
16
16
|
// shepherd config explain [--json] [--working-tree] (effective policy and where each setting came from)
|
|
17
17
|
// shepherd preview [--recipe <name>] [--base <ref>] [--working-tree] (what would run on your change)
|
|
18
18
|
// shepherd doctor [--json] (is this machine and repository set up? each problem says what to do)
|
|
19
19
|
// shepherd acceptance <suggest|local> [--pr <n>] -- <agent command>... (run it; check it kept to the mode)
|
|
20
20
|
// shepherd trace event <stage> <start|end> --pr <n> [--round <n>] [--outcome ok|failed|skipped] [--retries <n>] [--head <sha>]
|
|
21
|
-
// shepherd
|
|
21
|
+
// shepherd stack <pr> (JSON: a stacked parent and the range to review, or a wrong base)
|
|
22
|
+
// shepherd workflows [--audit] (copy the shepherd and incident workflows, and the audit one, into .github/workflows)
|
|
22
23
|
// shepherd notify --pr <n> --repo <owner/repo> --head <sha> --state success|failure|pending|error --file <description.txt>
|
|
23
24
|
// shepherd trace flush --pr <n> --repo <owner/repo> --head <sha> --outcome <how it ended> [--base <sha>] [--ci-run <id> --ci-attempt <n>] [--related <traceparent>]...
|
|
24
25
|
//
|
|
@@ -35,7 +36,7 @@ import path from "node:path";
|
|
|
35
36
|
import { parseArgs } from "node:util";
|
|
36
37
|
import { parse as parseYaml, stringify } from "yaml";
|
|
37
38
|
import { z } from "zod";
|
|
38
|
-
import { type Config, ConfigSchema, defaultBranchReader, type Effective, fetchPackLenses, ghFetch, ghFetchDir, loadPolicy, policyProblems, PRESETS, preview, type Read, TEAM_FILES } from "./config.ts";
|
|
39
|
+
import { CI_DEFAULT_MODEL, ciModel, type Config, ConfigSchema, defaultBranchReader, type Effective, fetchPackLenses, ghFetch, ghFetchDir, loadPolicy, policyProblems, PRESETS, preview, type Read, TEAM_FILES } from "./config.ts";
|
|
39
40
|
import { ghThreads, snapshot, verdict } from "./acceptance.ts";
|
|
40
41
|
import { doctor } from "./doctor.ts";
|
|
41
42
|
import { fileLedger, notify, notifyOn, STATES, statusLedger } from "./notify.ts";
|
|
@@ -43,8 +44,9 @@ import { collect, collectEscapes, score } from "./garden.ts";
|
|
|
43
44
|
import { collectTraces, tempoHeaders, traceLimits, traceScores } from "./garden-traces.ts";
|
|
44
45
|
import { install, type Outcome, pinWorkflow, uninstall } from "./install.ts";
|
|
45
46
|
import { buildDemo, captureChange, demoBugs, finish, receiptStatus } from "./local.ts";
|
|
47
|
+
import { prStack } from "./stack.ts";
|
|
46
48
|
import { flush, recordEvent, traceFile } from "./trace.ts";
|
|
47
|
-
import { addLens, BUILT_IN_LENSES, lensTemplates, globalLensFile, lensProblems, newLens, opencodeAgents, 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";
|
|
48
50
|
|
|
49
51
|
const BUNDLE_ROOT = path.resolve(import.meta.dir, "..");
|
|
50
52
|
|
|
@@ -53,14 +55,15 @@ const USAGE = `usage: shepherd install [--project | --target <dir>] [--link] [
|
|
|
53
55
|
shepherd lens new <name> [--from <template>] [--applies <glob>]... [--description <text>]
|
|
54
56
|
shepherd lens add <skill> [--name <name>] [--applies <glob>]... [--description <text>] [--global]
|
|
55
57
|
shepherd lens list
|
|
56
|
-
shepherd models [ladder <model>... | pin <lens-or-
|
|
58
|
+
shepherd models [tier <name> <model> | ladder <model-or-tier>... | pin <runner-lens-or-group> <model-or-tier>] [--global]
|
|
59
|
+
shepherd ci-models
|
|
57
60
|
shepherd opencode-agents [--file <lenses.yml>]
|
|
58
61
|
shepherd garden <owner/repo>... [--since YYYY-MM-DD] [--min-prs <n>] [--traces <otlp.json>]... [--tempo-url <url>] [--trace-retries <n>] [--trace-wait-ms <ms>] [--trace-cost-usd <usd>]
|
|
59
62
|
shepherd local change [--base <ref>]
|
|
60
63
|
shepherd local finish <record.json> [--base <ref>]
|
|
61
64
|
shepherd local status [--base <ref>]
|
|
62
65
|
shepherd local demo [<dir>]
|
|
63
|
-
shepherd init [--preset review-only|local-fix|push] [--from <pack>]
|
|
66
|
+
shepherd init [--preset review-only|local-fix|push] [--from <pack>] [--stacks]
|
|
64
67
|
shepherd config validate
|
|
65
68
|
shepherd config explain [--json] [--working-tree]
|
|
66
69
|
shepherd preview [--recipe <name>] [--base <ref>] [--working-tree]
|
|
@@ -68,7 +71,9 @@ const USAGE = `usage: shepherd install [--project | --target <dir>] [--link] [
|
|
|
68
71
|
shepherd acceptance <suggest|local> [--pr <n>] -- <agent command>...
|
|
69
72
|
shepherd trace event <stage> <start|end> --pr <n> [--round <n>] [--outcome ok|failed|skipped] [--retries <n>] [--head <sha>]
|
|
70
73
|
shepherd trace flush --pr <n> --repo <owner/repo> --head <sha> --outcome <how it ended> [--base <sha>] [--ci-run <id> --ci-attempt <n>] [--related <traceparent>]...
|
|
71
|
-
shepherd
|
|
74
|
+
shepherd stack <pr>
|
|
75
|
+
shepherd model-id <provider:model | provider/model>
|
|
76
|
+
shepherd workflows [--audit]
|
|
72
77
|
shepherd notify --pr <n> --repo <owner/repo> --head <sha> --state success|failure|pending|error --file <description.txt>`;
|
|
73
78
|
|
|
74
79
|
const { values: opts, positionals } = parseArgs({
|
|
@@ -97,6 +102,8 @@ const { values: opts, positionals } = parseArgs({
|
|
|
97
102
|
"working-tree": { type: "boolean", default: false }, // explain, preview: your edits instead of the default branch
|
|
98
103
|
recipe: { type: "string" },
|
|
99
104
|
preset: { type: "string" }, // init: how far fixes go
|
|
105
|
+
audit: { type: "boolean", default: false }, // workflows: also the scheduled OWASP playbook audit
|
|
106
|
+
stacks: { type: "boolean", default: false }, // init: add a lens for each stack the repository uses
|
|
100
107
|
pr: { type: "string" }, // acceptance: the PR whose threads must stay as they were; trace: the PR
|
|
101
108
|
round: { type: "string" }, // trace: the quality-loop round
|
|
102
109
|
outcome: { type: "string" }, // trace: how a step or iteration ended
|
|
@@ -209,17 +216,24 @@ if (command === "install") {
|
|
|
209
216
|
process.exitCode = 1;
|
|
210
217
|
}
|
|
211
218
|
}
|
|
212
|
-
} else if (command === "models" && (sub === undefined || (sub === "ladder" && skillRef) || (sub === "pin" && skillRef && rest.length === 1))) {
|
|
219
|
+
} else if (command === "models" && (sub === undefined || (sub === "ladder" && skillRef) || ((sub === "pin" || sub === "tier") && skillRef && rest.length === 1))) {
|
|
213
220
|
const file = opts.global ? globalLensFile(homedir()) : repoLensFile(repoRoot);
|
|
214
221
|
|
|
222
|
+
if (sub === "tier") orExit(() => setTier(file, skillRef!, rest[0]!));
|
|
223
|
+
|
|
215
224
|
if (sub === "ladder") orExit(() => setLadder(file, [skillRef!, ...rest]));
|
|
216
225
|
|
|
217
226
|
if (sub === "pin") orExit(() => pinModel(file, skillRef!, rest[0]!));
|
|
218
|
-
const
|
|
227
|
+
const effective = policy(true);
|
|
228
|
+
const { ladder, models } = choice(effective);
|
|
229
|
+
|
|
230
|
+
const spelled = (id: string) => (opencodeModel(id) === id ? id : `${id} (OpenCode: ${opencodeModel(id)})`);
|
|
219
231
|
|
|
220
|
-
console.log(`
|
|
232
|
+
for (const [name, t] of Object.entries(effective.tiers)) console.log(`tier ${name.padEnd(18)} ${spelled(t.value)} (${t.source})`);
|
|
221
233
|
|
|
222
|
-
|
|
234
|
+
console.log(`ladder ${ladder?.map(spelled).join(" -> ") ?? "the harness's own (skills/shepherd/references/models.md)"}`);
|
|
235
|
+
|
|
236
|
+
for (const [name, model] of Object.entries(models)) console.log(`pin ${name.padEnd(18)} ${spelled(model)}`);
|
|
223
237
|
|
|
224
238
|
if (sub) console.log(`\nwritten to ${file}${opts.global ? "" : `\n${MERGE_NOTE}`}`);
|
|
225
239
|
} else if (command === "opencode-agents") {
|
|
@@ -309,12 +323,30 @@ if (command === "install") {
|
|
|
309
323
|
|
|
310
324
|
console.log(JSON.stringify(result, null, 2));
|
|
311
325
|
}
|
|
326
|
+
} else if (command === "ci-models") {
|
|
327
|
+
// Everything a workflow needs to run OpenCode on the team's models, read from the default branch: the session
|
|
328
|
+
// model, the variable its key goes in, and the agents that carry the ladder and pins.
|
|
329
|
+
const p = orExit(() => loadPolicy(orExit(() => defaultBranchReader(repoRoot)), ghFetch, null));
|
|
330
|
+
const { model, source } = ciModel(p, process.env.SHEPHERD_MODEL || undefined);
|
|
331
|
+
const session = opencodeModel(model);
|
|
332
|
+
|
|
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 }));
|
|
338
|
+
} else if (command === "model-id" && sub) {
|
|
339
|
+
// A model id as OpenCode spells it, so stamp's provider:model spelling works in a local OpenCode run too.
|
|
340
|
+
console.log(opencodeModel(sub));
|
|
341
|
+
} else if (command === "stack" && sub) {
|
|
342
|
+
// Which diff to review: the delta over an open stacked parent, or nothing at all when the base is wrong.
|
|
343
|
+
console.log(JSON.stringify(orExit(() => prStack(Number(sub), repoRoot)), null, 2));
|
|
312
344
|
} else if (command === "workflows") {
|
|
313
345
|
const dest = path.join(repoRoot, ".github", "workflows");
|
|
314
346
|
|
|
315
347
|
mkdirSync(dest, { recursive: true });
|
|
316
348
|
|
|
317
|
-
for (const name of ["shepherd.yml", "shepherd-incident.yml"]) {
|
|
349
|
+
for (const name of ["shepherd.yml", "shepherd-incident.yml", ...(opts.audit ? ["shepherd-audit.yml"] : [])]) {
|
|
318
350
|
const to = path.join(dest, name);
|
|
319
351
|
|
|
320
352
|
if (existsSync(to)) {
|
|
@@ -347,7 +379,15 @@ if (command === "install") {
|
|
|
347
379
|
} else if (command === "init") {
|
|
348
380
|
const file = path.join(repoRoot, TEAM_FILES[0]!);
|
|
349
381
|
|
|
350
|
-
|
|
382
|
+
// With --stacks on an existing policy, add the detected stacks' lenses it lacks and keep everything else.
|
|
383
|
+
if (existsSync(file) && opts.stacks) {
|
|
384
|
+
addStackLenses(file);
|
|
385
|
+
validate();
|
|
386
|
+
console.log(MERGE_NOTE);
|
|
387
|
+
process.exit(process.exitCode ?? 0);
|
|
388
|
+
}
|
|
389
|
+
|
|
390
|
+
if (existsSync(file)) orExit(() => { throw new Error(`${TEAM_FILES[0]} already exists; edit it, add stack lenses with shepherd init --stacks, then run shepherd config validate`); });
|
|
351
391
|
const legacy = workingTree(TEAM_FILES[1]!);
|
|
352
392
|
const seed = legacy ? orExit(() => ConfigSchema.parse(parseYaml(legacy) ?? {})) : { lenses: {} };
|
|
353
393
|
// A new repository starts review-only. A migration keeps pushing, as it did, and says so in the file; a pack keeps the pack's mode.
|
|
@@ -361,9 +401,25 @@ if (command === "install") {
|
|
|
361
401
|
if (opts.from) config.extends = [opts.from, ...(seed.extends ?? [])];
|
|
362
402
|
|
|
363
403
|
if (mode) config.fixes = { mode };
|
|
404
|
+
const stacks = detectStacks(trackedFiles(), workingTree);
|
|
405
|
+
|
|
364
406
|
mkdirSync(path.dirname(file), { recursive: true });
|
|
365
407
|
writeFileSync(file, `# shepherd team policy. Presets: review-only (fixes.mode suggest), local-fix (local), push.\n${stringify(config)}`);
|
|
366
408
|
console.log(`wrote ${TEAM_FILES[0]}${preset ? ` (preset ${preset})` : ""}${legacy ? ` from ${TEAM_FILES[1]} (delete it: ${TEAM_FILES[0]} now wins)` : ""}`);
|
|
409
|
+
|
|
410
|
+
// After the file exists, so a pack named by --from counts as already providing its lenses.
|
|
411
|
+
if (opts.stacks) addStackLenses(file);
|
|
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
|
+
}
|
|
416
|
+
|
|
417
|
+
const named = policy(true);
|
|
418
|
+
|
|
419
|
+
if (!Object.keys(named.tiers).length && !named.ladder && !Object.keys(named.models).length) {
|
|
420
|
+
console.log(`models: none named. Locally runners use your harness's models; in CI the session runs on ${CI_DEFAULT_MODEL}.\n Name a cheap and a strong model, then give roles to them:\n shepherd models tier fast <provider:model>\n shepherd models tier smart <provider:model>\n shepherd models ladder fast smart\n shepherd models pin reviewers fast (and: pin fixers smart, pin loop smart)`);
|
|
421
|
+
}
|
|
422
|
+
|
|
367
423
|
validate();
|
|
368
424
|
console.log(`\nBefore you merge it:\n shepherd config explain --working-tree every setting and where it came from\n shepherd preview --working-tree what would run on your change, and what it can write\n${MERGE_NOTE}`);
|
|
369
425
|
} else if (command === "config" && sub === "validate") {
|
|
@@ -424,6 +480,14 @@ if (command === "install") {
|
|
|
424
480
|
process.exit(2);
|
|
425
481
|
}
|
|
426
482
|
|
|
483
|
+
function trackedFiles(): string[] {
|
|
484
|
+
try {
|
|
485
|
+
return execFileSync("git", ["-C", repoRoot, "ls-files", "-z"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 64 * 1024 * 1024 }).split("\0").filter(Boolean);
|
|
486
|
+
} catch {
|
|
487
|
+
return [];
|
|
488
|
+
}
|
|
489
|
+
}
|
|
490
|
+
|
|
427
491
|
function workingTree(rel: string): string | null {
|
|
428
492
|
const file = path.join(repoRoot, rel);
|
|
429
493
|
|
|
@@ -436,6 +500,35 @@ function personal(): Config | null {
|
|
|
436
500
|
return existsSync(file) ? ConfigSchema.parse(parseYaml(readFileSync(file, "utf8")) ?? {}) : null;
|
|
437
501
|
}
|
|
438
502
|
|
|
503
|
+
/**
|
|
504
|
+
* Add a starter lens for each detected stack the effective team policy lacks. A lens a pack provides, or the
|
|
505
|
+
* file declares, is kept as it is: its skill, scope and gate are the team's.
|
|
506
|
+
*/
|
|
507
|
+
function addStackLenses(file: string): void {
|
|
508
|
+
const have = policy(true).lenses;
|
|
509
|
+
const stacks = detectStacks(trackedFiles(), workingTree);
|
|
510
|
+
|
|
511
|
+
for (const s of stacks) {
|
|
512
|
+
const lens = have[s];
|
|
513
|
+
|
|
514
|
+
if (lens?.scope === "team") {
|
|
515
|
+
console.log(`lens ${s}: kept, from ${lens.source}`);
|
|
516
|
+
continue;
|
|
517
|
+
}
|
|
518
|
+
|
|
519
|
+
orExit(() => addLens(file, s, stackLens(repoRoot, s)));
|
|
520
|
+
console.log(`lens ${s}: .shepherd/lenses/${s} from the ${s} starter; trim its rules with only or disable`);
|
|
521
|
+
}
|
|
522
|
+
|
|
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");
|
|
530
|
+
}
|
|
531
|
+
|
|
439
532
|
/** Team policy from the default branch, the source swarm reviews under, or from your working tree. */
|
|
440
533
|
function policy(fromTree: boolean) {
|
|
441
534
|
const read: Read = fromTree ? workingTree : orExit(() => defaultBranchReader(repoRoot));
|
|
@@ -472,6 +565,9 @@ function explain(p: Effective & { teamFile: string | null }): void {
|
|
|
472
565
|
|
|
473
566
|
console.log(`policy file: ${p.teamFile ?? "none (built-in defaults)"}${opts["working-tree"] ? ", working tree" : ", default branch"}\n`);
|
|
474
567
|
row("fixes.mode", p.fixes.value.mode, p.fixes.source);
|
|
568
|
+
|
|
569
|
+
for (const [k, v] of Object.entries(p.tiers)) row(`tiers.${k}`, v.value, v.source);
|
|
570
|
+
|
|
475
571
|
row("ladder", p.ladder?.value.join(" -> ") ?? "the harness's own", p.ladder?.source ?? "built-in");
|
|
476
572
|
|
|
477
573
|
for (const [k, v] of Object.entries(p.models)) row(`models.${k}`, v.value, v.source);
|