@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.
- package/commands/shepherd.md +3 -2
- package/package.json +5 -2
- package/schema/config.json +340 -0
- package/skills/incident/SKILL.md +4 -2
- package/skills/shepherd/SKILL.md +38 -14
- package/skills/shepherd/references/dispatch.md +5 -3
- package/skills/shepherd/references/models.md +1 -1
- package/skills/swarm/SKILL.md +108 -72
- package/skills/swarm/references/custom-lenses.md +12 -4
- package/skills/swarm/references/formats.md +3 -3
- package/skills/triage/SKILL.md +1 -1
- package/src/cli.ts +175 -22
- package/src/config.ts +169 -2
- package/src/install.ts +52 -0
- package/src/lens.ts +33 -1
- package/templates/shepherd-audit.yml +39 -8
- package/templates/shepherd-incident.yml +36 -5
- package/templates/shepherd.yml +144 -23
package/commands/shepherd.md
CHANGED
|
@@ -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.
|
|
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
|
+
}
|
package/skills/incident/SKILL.md
CHANGED
|
@@ -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
|
-
|
|
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
|
package/skills/shepherd/SKILL.md
CHANGED
|
@@ -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`
|
|
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
|
|
69
|
-
|
|
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
|
|
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
|
|
110
|
-
`shepherd notify
|
|
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
|
|
222
|
-
|
|
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`)
|
|
280
|
-
|
|
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
|
-
|
|
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 |
|
|
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
|
|
20
|
-
|
|
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
|
-
>
|
|
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:
|
|
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
|
|