@jagreehal/shepherd 0.6.0 → 0.7.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.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  description: Shepherd a PR to merge-ready (loop on Sonnet, reviews on their own ladder)
3
- argument-hint: [pr-number-or-url | --local]
3
+ argument-hint: [pr-number-or-url | --local [--base <ref>]]
4
4
  model: sonnet
5
5
  ---
6
6
 
@@ -13,6 +13,7 @@ ladder in `shepherd/references/models.md`.
13
13
  For hands-off cadence: `/loop 5m /shepherd <pr>`.
14
14
 
15
15
  Before a PR exists: `/shepherd --local` reviews and fixes your change on this
16
- machine and touches nothing on GitHub.
16
+ machine and touches nothing on GitHub. Add `--base <ref>` when the branch will
17
+ merge into something other than the default branch.
17
18
 
18
19
  <!-- shepherd-installed -->
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jagreehal/shepherd",
3
- "version": "0.6.0",
3
+ "version": "0.7.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",
@@ -17,6 +17,7 @@
17
17
  "lenses",
18
18
  "packs",
19
19
  "templates",
20
+ "schema",
20
21
  "AGENTS.md",
21
22
  "THIRD_PARTY_NOTICES.md"
22
23
  ],
@@ -38,12 +39,14 @@
38
39
  "docs:dev": "bun run --cwd docs dev",
39
40
  "docs:build": "bun run docs:check && bun run --cwd docs build && bun docs/scripts/check-built.ts",
40
41
  "docs:check": "bun docs/scripts/check.ts",
41
- "docs:preview": "bun run --cwd docs preview"
42
+ "docs:preview": "bun run --cwd docs preview",
43
+ "schema": "bun src/cli.ts config schema > schema/config.json"
42
44
  },
43
45
  "devDependencies": {
44
46
  "@changesets/cli": "^3.0.3",
45
47
  "@oxlint/plugins": "1.88.0",
46
48
  "@types/bun": "^1.4.3",
49
+ "ajv": "8.20.0",
47
50
  "executable-stories-bun": "^0.1.0",
48
51
  "executable-stories-formatters": "^1.27.0",
49
52
  "oxlint": "1.88.0",
@@ -0,0 +1,340 @@
1
+ {
2
+ "title": "shepherd team policy (.shepherd/config.yml)",
3
+ "$schema": "http://json-schema.org/draft-07/schema#",
4
+ "type": "object",
5
+ "properties": {
6
+ "extends": {
7
+ "type": "array",
8
+ "items": {
9
+ "type": "string",
10
+ "minLength": 1
11
+ }
12
+ },
13
+ "tiers": {
14
+ "type": "object",
15
+ "propertyNames": {
16
+ "type": "string",
17
+ "pattern": "^[a-z][a-z0-9-]*$"
18
+ },
19
+ "additionalProperties": {
20
+ "type": "string",
21
+ "minLength": 1
22
+ }
23
+ },
24
+ "ladder": {
25
+ "minItems": 1,
26
+ "type": "array",
27
+ "items": {
28
+ "type": "string",
29
+ "minLength": 1
30
+ }
31
+ },
32
+ "models": {
33
+ "type": "object",
34
+ "propertyNames": {
35
+ "type": "string",
36
+ "pattern": "^[a-z][a-z0-9-]*$"
37
+ },
38
+ "additionalProperties": {
39
+ "type": "string",
40
+ "minLength": 1
41
+ }
42
+ },
43
+ "lenses": {
44
+ "default": {},
45
+ "type": "object",
46
+ "propertyNames": {
47
+ "type": "string",
48
+ "pattern": "^[a-z][a-z0-9-]*$"
49
+ },
50
+ "additionalProperties": {
51
+ "type": "object",
52
+ "properties": {
53
+ "skill": {
54
+ "type": "string",
55
+ "minLength": 1
56
+ },
57
+ "applies_to": {
58
+ "type": "array",
59
+ "items": {
60
+ "type": "string",
61
+ "minLength": 1
62
+ }
63
+ },
64
+ "description": {
65
+ "type": "string",
66
+ "minLength": 1
67
+ },
68
+ "gate": {
69
+ "type": "string",
70
+ "enum": [
71
+ "refuse",
72
+ "escalate",
73
+ "note"
74
+ ]
75
+ },
76
+ "only": {
77
+ "minItems": 1,
78
+ "type": "array",
79
+ "items": {
80
+ "type": "string",
81
+ "minLength": 1
82
+ }
83
+ },
84
+ "disable": {
85
+ "minItems": 1,
86
+ "type": "array",
87
+ "items": {
88
+ "type": "string",
89
+ "minLength": 1
90
+ }
91
+ }
92
+ },
93
+ "additionalProperties": false
94
+ }
95
+ },
96
+ "checks": {
97
+ "type": "object",
98
+ "propertyNames": {
99
+ "type": "string",
100
+ "pattern": "^[a-z][a-z0-9-]*$"
101
+ },
102
+ "additionalProperties": {
103
+ "type": "object",
104
+ "properties": {
105
+ "command": {
106
+ "type": "string",
107
+ "minLength": 1
108
+ }
109
+ },
110
+ "required": [
111
+ "command"
112
+ ],
113
+ "additionalProperties": false
114
+ }
115
+ },
116
+ "fixes": {
117
+ "type": "object",
118
+ "properties": {
119
+ "mode": {
120
+ "type": "string",
121
+ "enum": [
122
+ "suggest",
123
+ "local",
124
+ "push"
125
+ ]
126
+ }
127
+ },
128
+ "required": [
129
+ "mode"
130
+ ],
131
+ "additionalProperties": false
132
+ },
133
+ "escalate": {
134
+ "type": "object",
135
+ "properties": {
136
+ "paths": {
137
+ "minItems": 1,
138
+ "type": "array",
139
+ "items": {
140
+ "type": "string",
141
+ "minLength": 1
142
+ }
143
+ },
144
+ "reason": {
145
+ "type": "string",
146
+ "minLength": 1
147
+ }
148
+ },
149
+ "required": [
150
+ "paths"
151
+ ],
152
+ "additionalProperties": false
153
+ },
154
+ "branding": {
155
+ "type": "object",
156
+ "properties": {
157
+ "name": {
158
+ "type": "string",
159
+ "minLength": 1,
160
+ "maxLength": 40,
161
+ "pattern": "\\S"
162
+ },
163
+ "avatar": {
164
+ "type": "string",
165
+ "maxLength": 500,
166
+ "format": "uri",
167
+ "pattern": "^https://(?:[A-Za-z0-9-]+\\.)*[A-Za-z][A-Za-z0-9-]*(?::(?:6553[0-5]|655[0-2]\\d|65[0-4]\\d{2}|6[0-4]\\d{3}|[1-5]\\d{4}|\\d{1,4}))?(?:[/?#]\\S*)?$"
168
+ },
169
+ "emoji": {
170
+ "type": "object",
171
+ "properties": {
172
+ "critical": {
173
+ "type": "string",
174
+ "minLength": 1,
175
+ "maxLength": 16,
176
+ "pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
177
+ },
178
+ "high": {
179
+ "type": "string",
180
+ "minLength": 1,
181
+ "maxLength": 16,
182
+ "pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
183
+ },
184
+ "medium": {
185
+ "type": "string",
186
+ "minLength": 1,
187
+ "maxLength": 16,
188
+ "pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
189
+ },
190
+ "low": {
191
+ "type": "string",
192
+ "minLength": 1,
193
+ "maxLength": 16,
194
+ "pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
195
+ },
196
+ "nit": {
197
+ "type": "string",
198
+ "minLength": 1,
199
+ "maxLength": 16,
200
+ "pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
201
+ },
202
+ "blocked": {
203
+ "type": "string",
204
+ "minLength": 1,
205
+ "maxLength": 16,
206
+ "pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
207
+ },
208
+ "changes_needed": {
209
+ "type": "string",
210
+ "minLength": 1,
211
+ "maxLength": 16,
212
+ "pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
213
+ },
214
+ "approve_with_nits": {
215
+ "type": "string",
216
+ "minLength": 1,
217
+ "maxLength": 16,
218
+ "pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
219
+ },
220
+ "looks_good": {
221
+ "type": "string",
222
+ "minLength": 1,
223
+ "maxLength": 16,
224
+ "pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
225
+ },
226
+ "resolved": {
227
+ "type": "string",
228
+ "minLength": 1,
229
+ "maxLength": 16,
230
+ "pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
231
+ }
232
+ },
233
+ "additionalProperties": false
234
+ }
235
+ },
236
+ "additionalProperties": false
237
+ },
238
+ "ci": {
239
+ "type": "object",
240
+ "properties": {
241
+ "label": {
242
+ "type": "string",
243
+ "minLength": 1,
244
+ "maxLength": 500,
245
+ "pattern": "^[^\\n\\r]*$"
246
+ },
247
+ "aws_region": {
248
+ "type": "string",
249
+ "minLength": 1,
250
+ "maxLength": 500,
251
+ "pattern": "^[^\\n\\r]*$"
252
+ },
253
+ "notify_on": {
254
+ "minItems": 1,
255
+ "type": "array",
256
+ "items": {
257
+ "type": "string",
258
+ "enum": [
259
+ "success",
260
+ "failure",
261
+ "pending",
262
+ "error"
263
+ ]
264
+ }
265
+ },
266
+ "max_commits": {
267
+ "type": "integer",
268
+ "minimum": 1,
269
+ "maximum": 200
270
+ },
271
+ "push_deny": {
272
+ "minItems": 1,
273
+ "type": "array",
274
+ "items": {
275
+ "type": "string",
276
+ "minLength": 1,
277
+ "maxLength": 500,
278
+ "pattern": "^[^\\n\\r]*$"
279
+ }
280
+ },
281
+ "incident_paths": {
282
+ "type": "string",
283
+ "minLength": 1,
284
+ "maxLength": 500,
285
+ "pattern": "^[^\\n\\r]*$"
286
+ },
287
+ "audit": {
288
+ "type": "object",
289
+ "properties": {
290
+ "plays": {
291
+ "minItems": 1,
292
+ "type": "array",
293
+ "items": {
294
+ "type": "string",
295
+ "pattern": "^[a-z0-9-]+$"
296
+ }
297
+ },
298
+ "public": {
299
+ "type": "boolean"
300
+ }
301
+ },
302
+ "additionalProperties": false
303
+ }
304
+ },
305
+ "additionalProperties": false
306
+ },
307
+ "recipes": {
308
+ "type": "object",
309
+ "propertyNames": {
310
+ "type": "string",
311
+ "pattern": "^[a-z][a-z0-9-]*$"
312
+ },
313
+ "additionalProperties": {
314
+ "type": "object",
315
+ "properties": {
316
+ "steps": {
317
+ "minItems": 1,
318
+ "type": "array",
319
+ "items": {
320
+ "type": "string",
321
+ "enum": [
322
+ "swarm",
323
+ "triage",
324
+ "simplify",
325
+ "ci-repair",
326
+ "stamp",
327
+ "incident"
328
+ ]
329
+ }
330
+ }
331
+ },
332
+ "required": [
333
+ "steps"
334
+ ],
335
+ "additionalProperties": false
336
+ }
337
+ }
338
+ },
339
+ "additionalProperties": false
340
+ }
@@ -34,8 +34,10 @@ secrets before quoting anything, as `../diagnosing-bugs/SKILL.md` describes.
34
34
 
35
35
  - Create the `incident` label, open one issue per failure, push one branch
36
36
  `incident/<issue>` and open one PR from it. Nothing else on GitHub.
37
- - Every issue and PR body starts with
38
- `> 🤖 Automated comment by **Shepherd incident**, not written by a human`.
37
+ - Every issue and PR body starts with `headers.incident` from
38
+ `shepherd branding` (default
39
+ `> 🤖 Automated comment by **Shepherd incident**, not written by a human`),
40
+ copied exactly.
39
41
  - Never push to the default branch, merge, approve, or comment on someone
40
42
  else's thread.
41
43
  - Never weaken a test, skip one, loosen an assertion, swallow the error, raise
@@ -60,13 +60,16 @@ L0 shepherd local change -> fingerprint, patch_path, ranges
60
60
  shepherd local change -> the next round's change
61
61
  ```
62
62
 
63
- - Pass swarm `--local` and the ladder; pass triage `findings_path` from swarm's
63
+ - Pass swarm `--local` (with `--base <ref>` when the developer gave one; pass
64
+ it to every `shepherd local` call too) and the ladder; pass triage `findings_path` from swarm's
64
65
  `local` result. Run simplify on the same gate as Step 2c, with
65
66
  `review_base_sha` set to the capture's `base_sha`.
66
67
  - **A round is clean** when swarm's `local.status` is `complete`, its checks
67
68
  ran without a failure on changed lines, triage fixed and promoted nothing,
68
- and simplify changed nothing. A finding triage dismissed with a reason does
69
- not block a clean round; a deferred one ends the loop for the developer,
69
+ and simplify changed nothing. A check the repository configures that was
70
+ skipped (`checks skipped: <tool> (<reason>)`) did not run, so its round is
71
+ not clean: report it. A finding triage dismissed with a reason does not
72
+ block a clean round; a deferred one ends the loop for the developer,
70
73
  after one more swarm whenever triage fixed anything that round. Never stop
71
74
  with fixes no review has seen: the report's `shepherd local status` must say
72
75
  `reviewed` for the files as they are now.
@@ -91,7 +94,15 @@ deferred finding with its options:
91
94
  When `SHEPHERD_HANDOFF` names a directory, this session holds no push
92
95
  credential: the CI workflow (`templates/shepherd.yml`) runs the model with a
93
96
  token that can comment and read but not write code, and a later job with no
94
- model pushes what you hand it. An iteration then differs in five places:
97
+ model pushes what you hand it. An iteration then differs in six places:
98
+
99
+ - **Swarm posts as on any PR.** Only the push credential is withheld. Swarm
100
+ posts its inline comments and summary with the job's token, which has
101
+ pull requests: write, under every fix mode. Under `suggest` posting is the
102
+ whole review: a run that ends with findings and nothing on the PR has failed.
103
+ Also write the summary body to `$SHEPHERD_HANDOFF/findings.md` with your file
104
+ tool. The publish job posts it only when no summary for this head reached the
105
+ PR, so a failed post still leaves the review on the PR.
95
106
 
96
107
  - **Commit, never push.** Commit on the PR branch as usual. Append the handoff
97
108
  addition from `references/dispatch.md` to every runner brief. After a runner,
@@ -106,8 +117,9 @@ model pushes what you hand it. An iteration then differs in five places:
106
117
  the pushed fix and resolves the thread then.
107
118
  - **Step 4 runs only when HEAD is still `H0`.** Otherwise stamp has nothing to
108
119
  judge until the push; report `pending`.
109
- - **Step 5 writes, the workflow posts.** Do not set the commit status or run
110
- `shepherd notify`. Write `$SHEPHERD_HANDOFF/status.json` with your file tool:
120
+ - **Step 5 writes the status for the workflow to set.** Never call the
121
+ statuses API or run `shepherd notify`: the job's token cannot set a status,
122
+ and the call fails with 403. Write `$SHEPHERD_HANDOFF/status.json` with your file tool:
111
123
  `{"state": "<success|pending|failure>", "description": "<the line>"}`, and
112
124
  each job id ci-repair wants rerun on its own line in
113
125
  `$SHEPHERD_HANDOFF/rerun-jobs.txt`. The publish job pushes your commits,
@@ -147,6 +159,11 @@ Read these once per iteration, when first needed:
147
159
  | `references/degradation.md` | when something is missing or failing |
148
160
  | `references/formats.md` | at Step 5, or when unsure of narration |
149
161
 
162
+ Read the policy with `shepherd config explain --json`, and any other file
163
+ under `.shepherd/` or `.github/` with `git show origin/<default>:<path>` or
164
+ `git cat-file -e`. Never glob or search for them: a glob can skip
165
+ dot-directories and report nothing there.
166
+
150
167
  Also establish how commits land. Some harnesses require signed commits and
151
168
  block `git commit` / `git push` in favour of their own tool. Find out now and
152
169
  name the working mechanism in every brief that may commit.
@@ -218,8 +235,9 @@ gh pr view --json number,url,baseRefName,headRefOid,state,isDraft,updatedAt,labe
218
235
  Take owner/repo from `url`. Merged or closed: stop with a final summary.
219
236
 
220
237
  **Fast path.** On a re-invocation where HEAD and `updatedAt` both match the
221
- carried state and stamp needs nothing, check `gh pr checks` (CI changes do not
222
- bump `updatedAt`). Skip the iteration only if nothing fails. Narrate the skip,
238
+ carried state and stamp needs nothing, check
239
+ `gh pr checks <number> --json name,state,bucket,workflow` (CI changes do not
240
+ bump `updatedAt`; `bucket` is `pass`, `fail`, `pending`, `skipping` or `cancel`). Skip the iteration only if nothing fails. Narrate the skip,
223
241
  print the state line, and hand back.
224
242
 
225
243
  **Draft.** Invoking shepherd says the PR is ready: `gh pr ready <number>`. That
@@ -276,8 +294,10 @@ changes nothing to review: when the PR's diff (`gh pr diff`) has the same
276
294
  and move `swarm_marker_sha` to HEAD. The patch id ignores the line numbers and
277
295
  blob ids a base merge shifts, and keeps whitespace. Keep each round's patch
278
296
  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
280
- inside a runner, so its reviewer agents are not nested. Pass the PR number, the
297
+ patch to compare, or when either id is empty, run swarm. Swarm runs **in this loop** (from `../swarm/SKILL.md`):
298
+ follow its steps yourself and start no agent to run it. Its first wave starts
299
+ the router and every lens in one parallel dispatch from this session; inside
300
+ a sub-agent those reviewers nest or never start. Pass the PR number, the
281
301
  diff path, the resolved ladder and `models` pins, HEAD, and `since_sha = swarm_marker_sha` when it
282
302
  is set. Set `swarm_marker_sha = HEAD` after.
283
303
  Skipping it despite qualifying changes needs an `AskUserQuestion` confirm, in
@@ -383,8 +403,10 @@ merge, not the review.
383
403
 
384
404
  ## Step 4: stamp
385
405
 
386
- Skip this step with `stamp=absent` when the repo has no stamp workflow
387
- (`.github/workflows/stamp.yml` on the default branch).
406
+ Skip this step with `stamp=absent` when the repo has no stamp workflow on the
407
+ default branch. Check with `git cat-file -e
408
+ origin/<default>:.github/workflows/stamp.yml`, never a glob or a file search:
409
+ those can skip `.github/`, and a missed stamp reads as `absent`.
388
410
 
389
411
  Guard first:
390
412
 
@@ -405,7 +427,7 @@ call also refreshes `updatedAt` for the state line:
405
427
 
406
428
  ```bash
407
429
  gh pr view <number> --json reviewDecision,latestReviews,updatedAt \
408
- --jq '{reviewDecision, updatedAt, stamp: ([.latestReviews[] | select(.body | test("^## \\S+ stamp: "))
430
+ --jq '{reviewDecision, updatedAt, stamp: ([.latestReviews[] | select(.body | contains("<!-- stamp-run:"))
409
431
  | {state, head: (.body | capture("stamp-reviewed:head=(?<h>[0-9a-f]+)").h // null), body: .body[:400]}][0])}'
410
432
  ```
411
433
 
@@ -437,7 +459,9 @@ get around a stamp gate.
437
459
 
438
460
  Set the `shepherd` commit status on `H2`, every iteration, so the PR shows
439
461
  where the loop got to even after this session ends. Green CI must never read
440
- as "done" while shepherd still has work or is waiting on the author:
462
+ as "done" while shepherd still has work or is waiting on the author. In
463
+ handoff mode, write `$SHEPHERD_HANDOFF/status.json` instead and skip this
464
+ command (Handoff mode, above):
441
465
 
442
466
  ```bash
443
467
  gh api "repos/<owner>/<repo>/statuses/<H2>" -f context=shepherd \
@@ -16,8 +16,9 @@ degradation rules sit at the end; running a fragment runs without them.
16
16
 
17
17
  ## Starting a runner
18
18
 
19
- - **swarm** runs in the main loop: read `../swarm/SKILL.md` and follow it here. It starts its own
20
- reviewer agents, and nesting those inside a runner costs a layer of context.
19
+ - **swarm** runs in the main loop: read `../swarm/SKILL.md` and follow it here,
20
+ with no agent around it. It starts its own reviewer agents in parallel, and
21
+ inside a runner they nest or never start.
21
22
  - **triage**, **simplify**, and **ci-repair**: one `Agent` each at the second
22
23
  rung (see `models.md`). Tell the
23
24
  runner the skill's absolute path (`<this skill's directory>/../triage/SKILL.md`)
@@ -94,7 +95,8 @@ Append to every brief when `SHEPHERD_HANDOFF` is set (`../SKILL.md`, Handoff
94
95
  mode):
95
96
 
96
97
  > Handoff mode: this session cannot push, and a later job pushes your commits.
97
- > Commit, never push. Resolve no thread; the next iteration does once the fix
98
+ > Post review comments as usual: only pushing is withheld. Never call the
99
+ > statuses API; the workflow sets the status. Commit, never push. Resolve no thread; the next iteration does once the fix
98
100
  > is pushed. Never run `gh pr update-branch`: to update the branch, merge
99
101
  > `origin/<base>` locally and commit the merge with your trailer. Never run
100
102
  > `gh run rerun`: put the job in your `rerun` result with status `requested`.
@@ -54,7 +54,7 @@ With nothing configured, use the harness's ladder:
54
54
  | Harness | Ladder, cheapest first |
55
55
  |---|---|
56
56
  | Claude Code | `haiku` -> `sonnet` -> `opus` -> `fable` |
57
- | OpenCode | none built in: list `opencode models` and take the operator's ladder; with none set, the session model is one rung |
57
+ | OpenCode | none built in: take the operator's ladder; with none set, the session model is the only rung. Never pick a model from `opencode models`: a free model there is a provider the team did not choose |
58
58
  | Codex | the harness's own subagent models, cheapest first; with no per-agent model choice, one rung |
59
59
  | Anything else | whatever the agent tool accepts, cheapest first |
60
60