@jagreehal/shepherd 0.3.0 → 0.4.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/AGENTS.md +5 -0
- package/README.md +40 -419
- package/lenses/observability/SKILL.md +18 -11
- package/package.json +16 -8
- package/skills/ci-repair/SKILL.md +6 -1
- package/skills/garden/SKILL.md +28 -3
- package/skills/garden/references/telemetry.md +50 -0
- package/skills/incident/SKILL.md +6 -1
- package/skills/shepherd/SKILL.md +95 -1
- package/skills/shepherd/references/dispatch.md +12 -0
- package/skills/shepherd/references/stories.md +102 -0
- package/skills/swarm/SKILL.md +5 -0
- package/skills/triage/SKILL.md +19 -0
- package/src/cli.ts +117 -6
- package/src/garden-traces.ts +461 -0
- package/src/garden.ts +2 -1
- package/src/install.ts +3 -0
- package/src/notify.ts +138 -0
- package/src/trace.ts +180 -0
- package/templates/shepherd-incident.yml +156 -0
- package/templates/shepherd.yml +399 -0
package/AGENTS.md
CHANGED
|
@@ -48,6 +48,11 @@ to all of them.
|
|
|
48
48
|
short must never be possible. This is shepherd's only status write.
|
|
49
49
|
- **Behaviour changes made during review are disclosed** in one marked section
|
|
50
50
|
of the PR description; the rest of the body is the author's.
|
|
51
|
+
- **In CI the model holds no write credential.** Handoff mode commits and
|
|
52
|
+
never pushes; a job with no model pushes the bundle after its fast-forward
|
|
53
|
+
and path checks. Never name `SHEPHERD_TOKEN` anywhere in the model's job (a secret any
|
|
54
|
+
step uses sits in the job's runner memory), persist a checkout token, or
|
|
55
|
+
grant `contents: write`; `src/workflow.test.ts` pins this.
|
|
51
56
|
- **Local mode touches nothing on GitHub.** `--local` never pushes, posts,
|
|
52
57
|
resolves, sets a status, or commits: fixes stay in the working tree for the
|
|
53
58
|
developer. It reports "local checks passed", never merge-ready.
|
package/README.md
CHANGED
|
@@ -1,446 +1,67 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Shepherd
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Shepherd reviews changes, fixes findings and repairs CI through skills in your coding agent. Use it before you open a PR, on an existing PR, or through GitHub Actions.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Use Shepherd to work through review comments and failing CI logs under your team's policy. It leaves human decisions for you. [Stamp](https://github.com/jagreehal/stamp) supplies the approval verdict; you decide when to merge.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
flowchart LR
|
|
9
|
-
PR[You open a PR] --> SH[shepherd loop<br/>in your coding agent]
|
|
10
|
-
SH --> R[Review, fix,<br/>repair CI]
|
|
11
|
-
R --> SH
|
|
12
|
-
SH --> ST[stamp in CI<br/>decides approval]
|
|
13
|
-
ST --> M[You merge]
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
shepherd gets the PR ready; stamp decides whether it gets approved. shepherd works on GitHub only and reads and writes through `gh`.
|
|
7
|
+
## Start here
|
|
17
8
|
|
|
18
|
-
|
|
9
|
+
- [Run your first review](docs/src/content/docs/start/quickstart.md)
|
|
10
|
+
- [Choose local review, a PR loop, or CI](docs/src/content/docs/start/choose-a-setup.md)
|
|
11
|
+
- [Browse the documentation](docs/src/content/docs/index.md)
|
|
19
12
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
```mermaid
|
|
23
|
-
flowchart TD
|
|
24
|
-
subgraph Without["Without shepherd"]
|
|
25
|
-
A1[Read bot comments] --> A2[Paste into agent]
|
|
26
|
-
A2 --> A3[Push fix]
|
|
27
|
-
A3 --> A4[CI fails]
|
|
28
|
-
A4 --> A5[Paste log into agent]
|
|
29
|
-
A5 --> A3
|
|
30
|
-
end
|
|
31
|
-
subgraph With["With shepherd"]
|
|
32
|
-
B1["/loop 5m /shepherd 42"] --> B2[Review, triage,<br/>CI repair, verdict]
|
|
33
|
-
B2 --> B3{Needs you?}
|
|
34
|
-
B3 -- no --> B2
|
|
35
|
-
B3 -- yes --> B4[Commit status names<br/>what you need to do]
|
|
36
|
-
end
|
|
37
|
-
```
|
|
13
|
+
You need Bun 1.2 or later, Git, an authenticated GitHub CLI and a coding agent that can load skills and run subagents.
|
|
38
14
|
|
|
39
|
-
|
|
40
|
-
- A second model verifies each serious finding before it posts, so you read fewer false alarms.
|
|
41
|
-
- shepherd never replies to people and never approves. Those stay yours.
|
|
42
|
-
- A `shepherd` commit status shows where the loop got to, and a branch rule can require it.
|
|
43
|
-
|
|
44
|
-
## Install
|
|
15
|
+
In your terminal, from the repository clone:
|
|
45
16
|
|
|
46
17
|
```bash
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
18
|
+
bun add -g @jagreehal/shepherd
|
|
19
|
+
shepherd install
|
|
20
|
+
shepherd init --preset review-only
|
|
21
|
+
shepherd config validate
|
|
22
|
+
shepherd preview --working-tree
|
|
50
23
|
```
|
|
51
24
|
|
|
52
|
-
The
|
|
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`.
|
|
53
26
|
|
|
54
|
-
|
|
27
|
+
In your coding agent:
|
|
55
28
|
|
|
56
29
|
```text
|
|
57
|
-
/shepherd 42
|
|
58
|
-
/loop 5m /shepherd 42 # hands-off: an iteration every five minutes
|
|
59
|
-
/swarm 42 # the review on its own
|
|
60
|
-
/triage 42 # thread triage on its own
|
|
61
|
-
/ci-repair 42 # CI on its own
|
|
62
|
-
/review-security # one lens on the current diff
|
|
63
|
-
/shepherd --local # before a PR: review and fix your change on this machine
|
|
64
|
-
/swarm --local # before a PR: review only, print the findings
|
|
65
|
-
/incident <run-url|issue|error.txt> # after merge: a failure becomes an issue, a reproducing test and a fix PR
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
## Before you open a PR
|
|
69
|
-
|
|
70
|
-
`/shepherd --local` reviews and fixes your change before it reaches GitHub. It uses the same lenses, verification and fix rules as the PR loop, and it never pushes, comments, commits or sets a status. You commit the fixes.
|
|
71
|
-
|
|
72
|
-
```mermaid
|
|
73
|
-
flowchart TD
|
|
74
|
-
C[shepherd local change<br/>unpushed commits, staged,<br/>unstaged, untracked] --> S[swarm --local<br/>checks, router, lenses, verify]
|
|
75
|
-
S --> F{shepherd local finish}
|
|
76
|
-
F -- incomplete --> I[Review incomplete:<br/>what was not reviewed]
|
|
77
|
-
F -- complete --> T[triage, local:<br/>fix in the working tree]
|
|
78
|
-
T --> SI[simplify]
|
|
79
|
-
SI --> Q{Clean round?}
|
|
80
|
-
Q -- no --> C
|
|
81
|
-
Q -- "a decision is yours" --> Y[Needs you:<br/>each option listed]
|
|
82
|
-
Q -- yes --> P[Local checks passed]
|
|
83
|
-
P --> PR[Open the PR,<br/>then /shepherd <pr>]
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
The change covers the commits your branch has that its upstream (or the remote's default branch) lacks, staged and unstaged edits, and untracked files `.gitignore` does not exclude. shepherd reads untracked files through a copy of the index, so your own staging stays as you left it.
|
|
87
|
-
|
|
88
|
-
`shepherd local finish` checks each review against the change before anyone reads it as clean:
|
|
89
|
-
|
|
90
|
-
- every stage ran, and every lens ended `ok`;
|
|
91
|
-
- every changed line range reached at least one reviewer;
|
|
92
|
-
- each finding names a line its file has;
|
|
93
|
-
- each check finding was raised or dropped with a reason;
|
|
94
|
-
- the files did not change while the review ran.
|
|
95
|
-
|
|
96
|
-
Anything short of that reports **review incomplete** with what is missing. It proves each line was put in front of a reviewer, which is less than proof that the reviewer understood it.
|
|
97
|
-
|
|
98
|
-
A complete review writes a receipt keyed to a fingerprint of the exact content. `shepherd local status` tells you whether the files on disk still match a reviewed change; any edit since makes it `changed`. Wire it into a pre-push hook if you want one.
|
|
99
|
-
|
|
100
|
-
Local mode ends with **local checks passed**, **needs you**, **review incomplete**, or the round cap. Merge readiness still belongs to the PR loop and stamp.
|
|
101
|
-
|
|
102
|
-
Try it on planted bugs:
|
|
103
|
-
|
|
104
|
-
```bash
|
|
105
|
-
bunx @jagreehal/shepherd local demo # prints the repository path and the bugs to expect
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
The demo repository carries seven bugs, one per way a change reaches the review: an unpushed commit, a staged edit, an unstaged edit, an untracked file and a deleted check. `examples/local-demo/expected.json` lists each one with its lines.
|
|
109
|
-
|
|
110
|
-
## How it works
|
|
111
|
-
|
|
112
|
-
### One iteration
|
|
113
|
-
|
|
114
|
-
```mermaid
|
|
115
|
-
flowchart TD
|
|
116
|
-
S[Resolve the PR] --> Q[Quality round]
|
|
117
|
-
subgraph Round["Quality loop, up to 4 rounds"]
|
|
118
|
-
Q --> SW[swarm: review]
|
|
119
|
-
SW --> TR[triage: work every thread]
|
|
120
|
-
TR --> SI[simplify]
|
|
121
|
-
SI --> DRY{Dry round?}
|
|
122
|
-
DRY -- no --> Q
|
|
123
|
-
end
|
|
124
|
-
DRY -- yes --> CI[ci-repair]
|
|
125
|
-
CI --> V[stamp verdict]
|
|
126
|
-
V --> SUM[Summary and<br/>commit status]
|
|
127
|
-
```
|
|
128
|
-
|
|
129
|
-
A round is dry when triage fixed, resolved and promoted nothing, simplify changed nothing, and no bot review is still on its way. Round 1's fixes always get a second review round.
|
|
130
|
-
|
|
131
|
-
### The review swarm
|
|
132
|
-
|
|
133
|
-
```mermaid
|
|
134
|
-
flowchart LR
|
|
135
|
-
D[Diff] --> CK[Repo checks and installed scanners:<br/>lint, typecheck, nearby tests,<br/>gitleaks, semgrep, osv-scanner and more]
|
|
136
|
-
CK --> RT[Cheap router review]
|
|
137
|
-
RT --> L1[review-correctness]
|
|
138
|
-
RT --> L2[review-security]
|
|
139
|
-
RT --> L3[review-simplicity]
|
|
140
|
-
RT --> L4[review-maintainability]
|
|
141
|
-
RT --> L5[review-slop]
|
|
142
|
-
RT --> L6[review-spec<br/>when an issue or spec is linked]
|
|
143
|
-
RT --> LT[Your team's lenses]
|
|
144
|
-
L1 & L2 & L3 & L4 & L5 & L6 & LT --> VF{HIGH or CRITICAL?}
|
|
145
|
-
VF -- yes --> V2[Second model quotes<br/>the code or drops it]
|
|
146
|
-
VF -- no --> P
|
|
147
|
-
V2 --> P[Inline comments<br/>and one summary comment]
|
|
30
|
+
/shepherd 42
|
|
148
31
|
```
|
|
149
32
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
### Triage
|
|
153
|
-
|
|
154
|
-
```mermaid
|
|
155
|
-
flowchart TD
|
|
156
|
-
T[Open review thread] --> H{A human has joined?}
|
|
157
|
-
H -- yes --> W[Leave it for you]
|
|
158
|
-
H -- no --> J{Judgement}
|
|
159
|
-
J --> F[Fixed, with a commit]
|
|
160
|
-
J --> R[Resolved]
|
|
161
|
-
J --> DF[Deferred]
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
Triage ends each thread fixed, resolved or deferred. It never replies and never touches a thread a person is in.
|
|
165
|
-
|
|
166
|
-
## The skills
|
|
167
|
-
|
|
168
|
-
| Skill | Does |
|
|
169
|
-
|---|---|
|
|
170
|
-
| `shepherd` | Runs the loop: review rounds until dry, then CI, then the stamp verdict. Owns state, model choice, and when to ask you. |
|
|
171
|
-
| `swarm` | Runs the repo's own checks, then a cheap router review that hands risky hunks to the lenses in parallel, verifies serious findings, and posts inline comments plus one summary comment. |
|
|
172
|
-
| `triage` | Ends every review thread fixed, resolved, or deferred. Never replies, never touches a thread a human is in. |
|
|
173
|
-
| `ci-repair` | Updates a stale branch, diagnoses failing checks to the leaf job, makes one verified fix, reruns flaky jobs once. |
|
|
174
|
-
| `incident` | After merge: turns a red default-branch run or a production error into an `incident` issue, a reproducing test, the PR that caused it (by bisecting with that test), and a fix PR the loop then takes over. |
|
|
175
|
-
| `pair` | The act / act-and-say / stop-and-ask ladder that decides when to ask you. |
|
|
176
|
-
| `review-correctness` | Bugs: data, concurrency, performance, API contracts, frontend state, tests. |
|
|
177
|
-
| `review-security` | Exploitable source-to-sink paths, each with its data flow and fix. |
|
|
178
|
-
| `review-simplicity` | The four rules of simple design; what to delete and what replaces it. |
|
|
179
|
-
| `review-maintainability` | Coupling, rollout safety, observability, naming, and the repo's own written rules. |
|
|
180
|
-
| `review-slop` | Low-signal code and prose: thrown-away types, defensive noise, tests that cannot fail, padded PR text. |
|
|
181
|
-
| `review-spec` | The change against its issue or spec: requirements missing, built wrong, or not asked for. |
|
|
182
|
-
| `code-review`, `diagnosing-bugs`, `pr`, `retro`, `writing-for-agents` | [Matt Pocock's skills](https://github.com/mattpocock/skills), copied unchanged. `review-spec` runs code-review's Spec axis, `review-simplicity` adds its smell baseline, ci-repair diagnoses with diagnosing-bugs, shepherd writes PR bodies with pr when the repo has no PR skill, and garden sorts causes with retro and writes skill text by writing-for-agents. |
|
|
183
|
-
| `garden` | The outer loop: scores shepherd's recent runs from GitHub and opens PRs with skill edits and lint rules for findings that keep recurring. |
|
|
184
|
-
|
|
185
|
-
### When it asks you
|
|
186
|
-
|
|
187
|
-
```mermaid
|
|
188
|
-
flowchart LR
|
|
189
|
-
X[Something to do] --> P{pair ladder}
|
|
190
|
-
P -- clearly better,<br/>one sensible way --> A[Just do it]
|
|
191
|
-
P -- more than one<br/>reasonable answer --> AS[Do it, then say so]
|
|
192
|
-
P -- breaks simple design, unclear,<br/>or changes relied-on behaviour --> SA[Stop and ask]
|
|
193
|
-
```
|
|
194
|
-
|
|
195
|
-
## Add your own reviewers
|
|
196
|
-
|
|
197
|
-
Any skill can review code as a swarm lens: React performance rules, your design system, your API conventions. Point shepherd at the skill and the files it cares about:
|
|
198
|
-
|
|
199
|
-
```bash
|
|
200
|
-
bunx @jagreehal/shepherd lens new react --applies '**/*.tsx' # scaffolds .shepherd/lenses/react/SKILL.md
|
|
201
|
-
bunx @jagreehal/shepherd lens add vercel-react-best-practices --name react-perf \
|
|
202
|
-
--applies '**/*.tsx' --applies '**/*.jsx' # an existing skill, into .shepherd/lenses.yml
|
|
203
|
-
bunx @jagreehal/shepherd lens add ~/skills/house-style --name house --global # personal preview
|
|
204
|
-
bunx @jagreehal/shepherd lens list
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
```yaml
|
|
208
|
-
# .shepherd/lenses.yml
|
|
209
|
-
lenses:
|
|
210
|
-
react:
|
|
211
|
-
skill: vercel-react-best-practices # an installed skill, or a path to one in the repo
|
|
212
|
-
applies_to: ['**/*.tsx', '**/*.jsx'] # runs whenever a matching file changes
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
```mermaid
|
|
216
|
-
flowchart TD
|
|
217
|
-
L[Lens in .shepherd/lenses.yml<br/>read from the default branch] --> A{applies_to set?}
|
|
218
|
-
A -- yes --> M[Runs on each PR that<br/>touches a matching file]
|
|
219
|
-
A -- no --> R[Router calls it when<br/>its description fits]
|
|
220
|
-
M & R --> RV["Skill's ## Review section<br/>is the checklist"]
|
|
221
|
-
RV --> P["Findings post as [lens/rule-id]"]
|
|
222
|
-
P --> T["Triage fixes them,<br/>following the skill's ## Fix"]
|
|
223
|
-
```
|
|
224
|
-
|
|
225
|
-
Swarm wraps the skill in a review-only brief. The skill's `## Review` section is the checklist, and its findings post like any other lens's (`[react/async-parallel]`). Triage fixes them, following the skill's `## Fix` section when it has one. Nothing in a lens can loosen shepherd's own rules.
|
|
226
|
-
|
|
227
|
-
shepherd reads the repository's lens file from the default branch, so a PR cannot pick its own reviewers. Run `/swarm --preview` to try a lens from your working tree before you merge it: it reports which files each lens matched and what it found, and posts nothing. `lens list` checks each lens (a description, a `## Review` with unique rule ids) and exits non-zero on a problem.
|
|
228
|
-
|
|
229
|
-
A `--global` lens is a personal preview. Swarm prints its findings locally and never posts them, so you can try a lens on real PRs before you commit it for the team.
|
|
230
|
-
|
|
231
|
-
### Starter lenses
|
|
232
|
-
|
|
233
|
-
A team that wants every change checked for observability can start from the bundled pack instead of a blank file:
|
|
234
|
-
|
|
235
|
-
```bash
|
|
236
|
-
bunx @jagreehal/shepherd lens new observability --from observability --applies 'src/**'
|
|
237
|
-
```
|
|
238
|
-
|
|
239
|
-
That copies `lenses/observability/SKILL.md` into `.shepherd/lenses/observability/` and registers it. Its seven rules flag outbound calls with no span or log, errors that lose their cause, unstructured logs, secrets or personal data in telemetry, silent data drops, unbounded labels, and user-facing changes with no signal. Its `## Fix` section has triage reach for the repository's existing logger and tracer, and send anything that adds a telemetry dependency to you. Edit the rules to fit; `shepherd lens list` shows the templates.
|
|
240
|
-
|
|
241
|
-
### The same pack in stamp
|
|
33
|
+
Replace `42` with your PR number. Expect findings on the PR and a `reviewed` result under review-only policy. Read the [first-run guide](docs/src/content/docs/start/quickstart.md) for setup checks and expected results.
|
|
242
34
|
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
```mermaid
|
|
246
|
-
flowchart LR
|
|
247
|
-
P[.shepherd/lenses/observability/SKILL.md] --> L[shepherd lens:<br/>findings, then triage fixes<br/>following its Fix section]
|
|
248
|
-
P --> R[stamp rule pack:<br/>the reviewer refuses, escalates<br/>or notes a broken rule]
|
|
249
|
-
```
|
|
250
|
-
|
|
251
|
-
```yaml
|
|
252
|
-
# .stamp/policy.yml
|
|
253
|
-
rules:
|
|
254
|
-
observability:
|
|
255
|
-
skill: .shepherd/lenses/observability
|
|
256
|
-
applies_to: ['src/**']
|
|
257
|
-
on_break: escalate
|
|
258
|
-
```
|
|
259
|
-
|
|
260
|
-
Both read the pack from the default branch, so a PR cannot change the rules it is judged by. stamp also sends any PR that edits a configured pack to a human, since the pack's rules are trusted context for every later review.
|
|
261
|
-
|
|
262
|
-
## Team policy
|
|
263
|
-
|
|
264
|
-
`.shepherd/config.yml` holds a team's policy: its lenses and models, plus the checks to run, how far fixes go, what a person must decide, and named recipes. An organisation keeps a pack, and each repository extends it and overrides what it needs.
|
|
265
|
-
|
|
266
|
-
```yaml
|
|
267
|
-
# .shepherd/config.yml
|
|
268
|
-
extends:
|
|
269
|
-
- .shepherd/packs/acme.yml # in this repository
|
|
270
|
-
- github:acme/policy/shepherd.yml@0123456789abcdef0123456789abcdef01234567 # another, pinned to a commit
|
|
271
|
-
|
|
272
|
-
lenses:
|
|
273
|
-
payments:
|
|
274
|
-
skill: .shepherd/lenses/payments
|
|
275
|
-
applies_to: ["src/payments/**"]
|
|
276
|
-
|
|
277
|
-
checks: # swarm runs exactly these; ci-repair and incident use them too
|
|
278
|
-
unit: { command: bun test }
|
|
279
|
-
types: { command: bun run typecheck }
|
|
280
|
-
|
|
281
|
-
fixes:
|
|
282
|
-
mode: local # suggest: change nothing | local: fix, never commit | push (default)
|
|
283
|
-
|
|
284
|
-
escalate:
|
|
285
|
-
paths: ["migrations/**", "src/public-api/**"]
|
|
286
|
-
reason: a person decides schema and public API changes
|
|
287
|
-
|
|
288
|
-
recipes: # /shepherd 42 --recipe quick
|
|
289
|
-
quick: { steps: [swarm, triage, swarm] }
|
|
290
|
-
```
|
|
291
|
-
|
|
292
|
-
Settings apply in one order: built-in defaults, then each pack in the order listed, then the repository file. A later layer replaces a setting, and merges `lenses`, `checks`, `models` and `recipes` by name. A pack cannot extend another pack. A pack from another repository must name a full commit, since a branch or tag can move under you. shepherd reads the file and its packs from the default branch, so a PR cannot change the policy it is reviewed under. Personal settings in `~/.config/shepherd/lenses.yml` stay a preview: their lenses print locally and never post, their ladder and pins fill in only where the team set none, and they cannot touch checks, fixes, escalation or recipes. A repository with only `.shepherd/lenses.yml` keeps working; it is read the same way.
|
|
293
|
-
|
|
294
|
-
A recipe composes shepherd's own steps: `swarm`, `triage`, `simplify`, `ci-repair`, `stamp`, `incident`. They run one at a time, and a recipe reports success only when a review ran after its last change. Validation rejects an order that cannot hold: triage before any swarm, stamp anywhere but last, a change nothing reviews afterwards, a fixing step under `fixes.mode: suggest`, or, under `local`, a fix only stamp reviews (stamp sees the pushed head, which local fixes never reach). The built-in `review`, `fix`, `pr` and `incident` recipes are listed by `config explain`; one the fix mode rules out shows as blocked in `preview`. Custom runners come later, once their contracts are defined.
|
|
295
|
-
|
|
296
|
-
```bash
|
|
297
|
-
bunx @jagreehal/shepherd init # review-only: shepherd posts findings and changes no code
|
|
298
|
-
bunx @jagreehal/shepherd init --preset local-fix # fixes land in your working tree, never committed
|
|
299
|
-
bunx @jagreehal/shepherd init --preset push # fixes are committed and pushed to the PR branch
|
|
300
|
-
bunx @jagreehal/shepherd init --from .shepherd/packs/acme.yml # extend a pack and keep its fix mode
|
|
301
|
-
bunx @jagreehal/shepherd config validate # your edits: exits 1 on a problem, so CI can run it
|
|
302
|
-
bunx @jagreehal/shepherd config explain # effective policy on the default branch, and each setting's source
|
|
303
|
-
bunx @jagreehal/shepherd preview --recipe pr # on your change: the full plan (see below)
|
|
304
|
-
```
|
|
305
|
-
|
|
306
|
-
Run `preview --working-tree` before you merge a policy change. It lists every reviewer, built-in and custom, with the model each one runs on and where that model came from; the checks; what each step can write, locally or to GitHub; anything escalated to a person; and how the recipe finishes. A finished `review` recipe means findings were posted, not that the PR is ready. Under `local-fix` the result is fixes left uncommitted. A PR is ready only when stamp approves its head, CI is green and no review thread is open. Running `init` in a repository that has only `.shepherd/lenses.yml` carries its settings over and keeps push mode.
|
|
307
|
-
|
|
308
|
-
A lens can travel with a pinned pack: a path in the pack (`skill: lenses/payments`) names a directory in the pack's repository at the pinned commit, and shepherd fetches it into a cache keyed by that commit. [docs/onboarding.md](docs/onboarding.md) shows the layout and how CI reads a private pack. `config validate` and `doctor` report a lens skill they cannot find.
|
|
309
|
-
|
|
310
|
-
New to shepherd? [docs/onboarding.md](docs/onboarding.md) walks through install, `doctor`, `init`, validate, preview, merging the policy and the first review.
|
|
311
|
-
|
|
312
|
-
`config explain --working-tree` and `preview --working-tree` read your uncommitted edits instead of the default branch. The skills load the policy with `config explain --json` (`skills/shepherd/references/policy.md`).
|
|
313
|
-
|
|
314
|
-
## Choose the models
|
|
315
|
-
|
|
316
|
-
Use any provider your harness can reach. Model ids pass straight to its agent tool: `haiku` on Claude Code, `provider/model` on OpenCode.
|
|
317
|
-
|
|
318
|
-
```bash
|
|
319
|
-
shepherd models ladder opencode-go/deepseek-v4-flash opencode-go/glm-5.3 opencode-go/kimi-k3 # cheapest first
|
|
320
|
-
shepherd models pin security opencode-go/qwen3.8-max # a lens or runner always on this model
|
|
321
|
-
shepherd lens add react-rules --applies '**/*.tsx' --model opencode-go/kimi-k2.7-code
|
|
322
|
-
shepherd models # what will run
|
|
323
|
-
shepherd opencode-agents # agents per rung and pin, for OpenCode 1.x
|
|
324
|
-
```
|
|
325
|
-
|
|
326
|
-
```mermaid
|
|
327
|
-
flowchart LR
|
|
328
|
-
subgraph Ladder["Model ladder, cheapest first"]
|
|
329
|
-
R1[rung 1] --> R2[rung 2] --> R3[rung 3] --> R4[rung 4]
|
|
330
|
-
end
|
|
331
|
-
RD[Reading work:<br/>router, simplify] --> R1
|
|
332
|
-
WR[Runners that push commits<br/>or resolve threads] --> R2
|
|
333
|
-
VF[Validating risky changes<br/>and serious findings] -- a stronger model --> R4
|
|
334
|
-
PIN[Pinned lens or runner] --> PM[Its pinned model]
|
|
335
|
-
```
|
|
336
|
-
|
|
337
|
-
Both settings land in `.shepherd/lenses.yml` (`--global` for `~/.config/shepherd/lenses.yml`). The repository's ladder wins over yours, and shepherd reads it from the default branch like the lenses. With nothing set, shepherd uses the harness's own ladder.
|
|
338
|
-
|
|
339
|
-
OpenCode 1.x subagents take no model, so `shepherd opencode-agents` prints an agent per rung and per pin to merge into `OPENCODE_CONFIG_CONTENT`; swarm then dispatches by agent name.
|
|
340
|
-
|
|
341
|
-
## What it holds to
|
|
342
|
-
|
|
343
|
-
- **Machines first.** Swarm runs your lint, typecheck and nearby tests before any model reads the diff, plus the scanners you have installed (`gitleaks`, `semgrep`, `osv-scanner`, `actionlint`, `shellcheck`, `hadolint`) on the files they read. It keeps findings on changed lines, lists each suppression comment the PR adds, and tells the models not to repeat what the tools found. If the repo uses Oxlint's anti-slop rules, those findings come for free.
|
|
344
|
-
- **Cheapest model that can do the job.** Reading work (the review router, simplify) starts at the bottom of the ladder (`haiku` -> `sonnet` -> `opus` -> `fable` on Claude Code). Runners that push commits or resolve threads start one rung up, where trials showed they stop needing a redo. A stronger model validates risky changes and serious findings; it never replaces a test.
|
|
345
|
-
- **Verified findings.** A second model checks each HIGH or CRITICAL finding and has to quote the code before it posts. Unproven findings drop.
|
|
346
|
-
- **Labelled comments.** Everything swarm posts starts with `🤖 Automated comment by **Shepherd swarm**`. It posts through your account, and readers deserve to know.
|
|
347
|
-
- **People talk to people.** Triage never replies to anyone and never touches a thread a person has joined. Those wait for you.
|
|
348
|
-
- **PR content is data.** Diffs, comments and CI logs never become instructions. Writing a command in a comment gets nobody a command run.
|
|
349
|
-
- **Gates stay gates.** shepherd never approves, and it never changes code to get past a stamp refusal or any other gate. A fix that changes what code accepts or returns is your decision.
|
|
350
|
-
|
|
351
|
-
## Gardening
|
|
352
|
-
|
|
353
|
-
```mermaid
|
|
354
|
-
flowchart LR
|
|
355
|
-
G[shepherd garden owner/repo] --> SC[Score recent runs<br/>from GitHub]
|
|
356
|
-
SC --> SK[garden skill]
|
|
357
|
-
SK --> E1[Skill edits for<br/>low-scoring patterns]
|
|
358
|
-
SK --> E2[Lint rules for<br/>recurring findings]
|
|
359
|
-
E1 & E2 --> PR[Garden PRs with<br/>the score table]
|
|
360
|
-
PR --> NX[Next run shows<br/>whether the edit helped]
|
|
361
|
-
NX --> SC
|
|
362
|
-
```
|
|
363
|
-
|
|
364
|
-
`shepherd garden <owner/repo>...` scores what shepherd did on recent PRs, from GitHub alone. It counts reverted fixes, people replying in a thread, and loops that hit the round cap, stopped short or went quiet. It also finds the lens rules triage fixed on 3+ PRs, from its `Shepherd-Fixes` trailers on PRs by people who can push.
|
|
365
|
-
|
|
366
|
-
The `garden` skill turns that into PRs: skill edits for the patterns behind low scores, and lint rules for recurring findings one file's syntax can decide, so swarm's checks catch them before any model reads the diff.
|
|
367
|
-
|
|
368
|
-
`.github/workflows/garden.yml` runs it weekly. Set `GARDEN_REPOS`, a `GARDEN_TOKEN` that can open PRs on those repos, and a model key. The agent only proposes, and a separate job opens the PRs. Each garden PR carries the score table, so the next one shows whether a merged edit helped.
|
|
369
|
-
|
|
370
|
-
## Where the loop got to
|
|
371
|
-
|
|
372
|
-
Every iteration sets a `shepherd` commit status on the head.
|
|
373
|
-
|
|
374
|
-
```mermaid
|
|
375
|
-
stateDiagram-v2
|
|
376
|
-
[*] --> pending: iteration starts
|
|
377
|
-
pending --> pending: work left, or waiting on a verdict
|
|
378
|
-
pending --> failure: only you can move it
|
|
379
|
-
pending --> success: stamp approved, nothing open
|
|
380
|
-
failure --> pending: you act, next iteration
|
|
381
|
-
success --> pending: new push
|
|
382
|
-
```
|
|
383
|
-
|
|
384
|
-
- `pending` while there is work or a verdict to wait for.
|
|
385
|
-
- `failure` names what you need to do when only you can move it (`stamp refused: ...`, `3 threads need you`).
|
|
386
|
-
- `success` only when stamp approved and nothing is left open.
|
|
387
|
-
|
|
388
|
-
Require the status in a branch rule, and a PR cannot merge while shepherd is mid-loop, stopped short, or behind a push it has not seen.
|
|
389
|
-
|
|
390
|
-
## After merge
|
|
391
|
-
|
|
392
|
-
shepherd needs no spec. A failure after merge is the requirement, and the test that reproduces it is the acceptance check. `/incident` takes a red run on the default branch, an error or stack trace, an alert payload, or an issue labelled `incident`, and:
|
|
393
|
-
|
|
394
|
-
```mermaid
|
|
395
|
-
flowchart LR
|
|
396
|
-
S[Signal: red main,<br/>production error] --> I[incident issue<br/>with evidence]
|
|
397
|
-
I --> T[Reproducing test]
|
|
398
|
-
T --> B[Bisect with the test:<br/>which PR caused it,<br/>did stamp approve it]
|
|
399
|
-
T --> F[Fix PR<br/>Fixes #issue]
|
|
400
|
-
F --> SH[shepherd loop]
|
|
401
|
-
SH --> ST[stamp: incident flag,<br/>needs the reproducing test]
|
|
402
|
-
ST --> M[You merge]
|
|
403
|
-
B --> G[garden tunes<br/>lenses and policy]
|
|
404
|
-
```
|
|
405
|
-
|
|
406
|
-
It dedupes on a fingerprint of the error, never pushes to the default branch, and stops without a fix when it cannot reproduce the failure. stamp refuses an incident fix that has no reproducing test or that hides the symptom.
|
|
407
|
-
|
|
408
|
-
To run it when the default branch goes red, add a workflow on `workflow_run` of your CI with `conclusion == 'failure'` and `head_branch` set to the default branch, and run one `/incident <run url>` the same way the `shepherd` workflow runs an iteration. An alerting tool can call the same workflow through `repository_dispatch` with the error in the payload.
|
|
409
|
-
|
|
410
|
-
## With stamp
|
|
411
|
-
|
|
412
|
-
```mermaid
|
|
413
|
-
sequenceDiagram
|
|
414
|
-
participant SH as shepherd
|
|
415
|
-
participant GH as GitHub
|
|
416
|
-
participant ST as stamp (CI)
|
|
417
|
-
participant You
|
|
418
|
-
SH->>GH: push fixes, apply label in label mode
|
|
419
|
-
GH->>ST: workflow runs on the head
|
|
420
|
-
ST->>GH: verdict review
|
|
421
|
-
SH->>GH: read the verdict
|
|
422
|
-
alt APPROVED
|
|
423
|
-
SH->>GH: status success
|
|
424
|
-
else REFUSED
|
|
425
|
-
SH->>SH: triage the refusal's issues
|
|
426
|
-
else ESCALATE
|
|
427
|
-
SH->>You: leave it for you
|
|
428
|
-
end
|
|
429
|
-
```
|
|
35
|
+
## Choose what the agent may change
|
|
430
36
|
|
|
431
|
-
|
|
37
|
+
| Mode | Result |
|
|
38
|
+
| --- | --- |
|
|
39
|
+
| `suggest` | Findings posted; no code edits |
|
|
40
|
+
| `local` | Fixes left in your working tree; you commit and push |
|
|
41
|
+
| `push` | Fixes committed and pushed under the skill rules |
|
|
432
42
|
|
|
433
|
-
|
|
43
|
+
`/shepherd --local` provides a pre-PR review-and-fix path with no GitHub writes. A completed review does not establish merge readiness. The PR loop reports ready only when Stamp approves the current head, CI passes and no review thread remains open.
|
|
434
44
|
|
|
435
|
-
##
|
|
45
|
+
## Configure it for your team
|
|
436
46
|
|
|
437
|
-
|
|
47
|
+
| Task | Guide |
|
|
48
|
+
| --- | --- |
|
|
49
|
+
| Review before opening a PR | [Local review](docs/src/content/docs/guides/local-review.md) |
|
|
50
|
+
| Compose checks, modes and recipes | [Configuration reference](docs/src/content/docs/reference/configuration.md) |
|
|
51
|
+
| Share organisation policy | [Team examples](docs/src/content/docs/configuration/examples.md) |
|
|
52
|
+
| Add domain-specific reviewers | [Lenses](docs/src/content/docs/configuration/lenses.md) |
|
|
53
|
+
| Select models by role | [Model routing](docs/src/content/docs/configuration/models.md) |
|
|
54
|
+
| Run without your laptop | [GitHub Actions](docs/src/content/docs/integrations/github-actions.md) |
|
|
55
|
+
| Get told when a PR needs you | [Notifications](docs/src/content/docs/integrations/notifications.md) |
|
|
56
|
+
| Investigate a failure after merge | [Incidents](docs/src/content/docs/guides/incidents.md) |
|
|
57
|
+
| Improve recurring findings | [Gardening](docs/src/content/docs/operations/gardening.md) |
|
|
58
|
+
| Diagnose a stopped loop | [Troubleshooting](docs/src/content/docs/operations/troubleshooting.md) |
|
|
438
59
|
|
|
439
60
|
## Development
|
|
440
61
|
|
|
441
62
|
```bash
|
|
442
63
|
bun install
|
|
443
|
-
bun run check
|
|
64
|
+
bun run check
|
|
444
65
|
```
|
|
445
66
|
|
|
446
|
-
|
|
67
|
+
For the docs site, run `bun install --cwd docs --frozen-lockfile`, then `bun run docs:dev`. Run `bun run docs:build` to validate and build it. Read [documentation maintenance](docs/src/content/docs/contributing/docs.md), [contributor rules](AGENTS.md) and [third-party credits](THIRD_PARTY_NOTICES.md).
|
|
@@ -1,26 +1,33 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: observability
|
|
3
|
-
description: Observability rules for a code review. Flags new code that production cannot see or that leaks through telemetry. Covers outbound calls without a span
|
|
3
|
+
description: Observability rules for a code review. Flags new code that production cannot see, debug or alert on, or that leaks through telemetry. Covers entry points and outbound calls without a span, trace context lost across services, queues and background work, errors that lose their cause, logs that are unstructured or not tied to the trace, requests that carry no identifiers, secrets or personal data in telemetry, silent data drops, unbounded names and labels, metrics no alert can use, renamed telemetry, telemetry setup that can crash the app or lose data on exit, and user-facing changes with no signal. Use as a review lens or as a stamp rule pack.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# observability
|
|
7
7
|
|
|
8
|
-
Production is where this code will fail. Review whether an on-call engineer
|
|
9
|
-
could see it fail, find the request,
|
|
10
|
-
|
|
8
|
+
Production is where this code will fail. Review whether an on-call engineer who
|
|
9
|
+
has never seen this code could see it fail, find the one request, follow it
|
|
10
|
+
across services and know why, from the telemetry alone, without the telemetry
|
|
11
|
+
itself leaking data, costing too much or taking the app down.
|
|
11
12
|
|
|
12
13
|
## Review
|
|
13
14
|
|
|
14
|
-
- **boundary-signal**:
|
|
15
|
-
- **
|
|
16
|
-
- **
|
|
17
|
-
- **
|
|
18
|
-
- **
|
|
19
|
-
- **
|
|
15
|
+
- **boundary-signal**: Every new entry point (HTTP route, queue or event consumer, scheduled job, worker, CLI command) and every call that leaves the process (HTTP, database, cache, queue, model API, file or shell) runs inside a span, from framework instrumentation or the repository's tracing helper. Flag: a new route, consumer, job or outbound call outside any span. Why: an outage there is invisible.
|
|
16
|
+
- **context-propagation**: Trace context crosses every boundary the work does. Outbound HTTP goes through an instrumented client, a published message carries the context in its headers and its consumer continues or links it, and deferred work (a timer, an in-process queue, a fire-and-forget promise, `waitUntil`) runs inside the span that started it. Flag: a hand-built client that bypasses instrumentation, a message published without context, a consumer that starts a fresh root, a detached promise. Why: the trace breaks at the boundary, and so does the investigation.
|
|
17
|
+
- **error-context**: A caught or rethrown error keeps its cause (`new Error(msg, { cause })`), is recorded on the active span with status ERROR, and is logged once with the identifiers that find the request: ids, never payloads. Flag: an empty `catch`, a rethrow of a bare message, a log of `error.message` without the error, an error turned into a success response with no record, the same error logged at every layer. Why: the trail ends at the catch.
|
|
18
|
+
- **structured-logs**: Server code logs through the repository's structured logger with fields, at a level that matches what happened, and every line carries the trace and span id. Flag: interpolated log strings, `console.log` in server code, a second logger, a logger not wired to the trace, an error logged at info. Why: nobody can search, alert on or jump from a line of prose.
|
|
19
|
+
- **request-context**: A handler or job puts the bounded identifiers that find one request on its span or request-scoped logger (the wide event): tenant, user, order or job id, the outcome. A change that adds a decision to existing code (a branch, fallback, retry, cache hit or miss, flag variant, or a choice between providers or rules) records which way it went there, as a bounded value. Flag: a new handler whose span carries nothing beyond its route, or a new path through existing code that leaves no trace of having been taken. Why: the trace says what failed, not for whom or which way the code went.
|
|
20
|
+
- **no-sensitive-data**: Logs, span attributes, events and metric labels carry no secrets, tokens, passwords, cookies, whole request bodies or headers, or personal data beyond the ids the team has agreed to keep. Flag: logging a whole object built from user input, headers or credentials; an email, name, address or card field as an attribute. Why: telemetry becomes the leak.
|
|
21
|
+
- **silent-drop**: Code that skips, filters or discards records, gives up on a retry, times out, or falls back counts or logs what it dropped and why. Flag: a `continue`, default branch, swallowed timeout or fallback value that loses data without a trace. Why: data loss nobody notices.
|
|
22
|
+
- **bounded-attributes**: Span names, metric names and metric labels take bounded values: route templates, not URLs; an enum reason, not an error message. Ids belong on span attributes and logs, never in a span name or metric label. Flag: user ids, ids inside URLs, free text or raw input as a metric label or span name. Why: cardinality blows up cost and queries.
|
|
23
|
+
- **alertable-signal**: A new dependency, queue, job or money or auth path emits what an alert needs to isolate it: outcomes counted by a bounded result or reason, a duration histogram, and for queues and jobs the lag or last success. Flag: a new integration whose failures show up only as a generic 500, a job nobody would notice had stopped. Why: no one can page on it, so no one is paged.
|
|
20
24
|
- **feature-signal**: A change meant to move a user outcome emits the event or metric that shows whether it did. Flag: a new user-facing flow with no event or metric. Why: no one can tell it works.
|
|
25
|
+
- **telemetry-contract**: Span names, attribute keys, metric names and labels, and event names are a contract that dashboards, alerts and queries read. Flag: a renamed or removed name or key with no note of what reads it, a unit changed under the same metric name. Why: the dashboard goes quiet and nobody notices until the incident.
|
|
26
|
+
- **safe-telemetry**: Telemetry can neither take the app down nor lose what it buffered. Initialisation runs once, at startup, before the code it instruments, and an exporter or backend failure never throws into a request. The process flushes on shutdown, and short-lived work (serverless handlers, workers, CLIs, scripts) flushes before it exits. Every deployable sets its service name, version and environment from configuration. Flag: telemetry initialised inside a request or module that loads late, `process.exit` with no flush, a signal handler that does not wait for shutdown, a new deployable with no service name or version, an environment hard-coded per build. Why: the telemetry is missing exactly when the process is dying.
|
|
27
|
+
- **telemetry-config**: A change to sampling, exporters, redaction or log level keeps errors and slow requests sampled, keeps redaction on and keeps production at its agreed level. Flag: sampling that can drop error traces, redaction switched off, debug logging enabled in production, an exporter endpoint or key hard-coded. Why: the telemetry a team relied on is gone and nothing says so.
|
|
21
28
|
|
|
22
29
|
## Fix
|
|
23
30
|
|
|
24
31
|
- Prefer: the repository's existing logger, tracer and metrics helpers, found in code next to the change.
|
|
25
32
|
- Never touch: telemetry configuration, exporters, sampling or vendor setup.
|
|
26
|
-
- Escalate: adding a logging, tracing or metrics dependency or vendor,
|
|
33
|
+
- Escalate: adding a logging, tracing or metrics dependency or vendor, any rule where the repository has no logger or tracer yet, and `telemetry-config` and `telemetry-contract` breaks: they are the team's calls.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jagreehal/shepherd",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.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",
|
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
"commands",
|
|
16
16
|
"examples",
|
|
17
17
|
"lenses",
|
|
18
|
+
"templates",
|
|
18
19
|
"AGENTS.md",
|
|
19
20
|
"THIRD_PARTY_NOTICES.md"
|
|
20
21
|
],
|
|
@@ -32,17 +33,24 @@
|
|
|
32
33
|
"lint": "oxlint src",
|
|
33
34
|
"changeset": "changeset",
|
|
34
35
|
"version-packages": "changeset version",
|
|
35
|
-
"release": "changeset publish"
|
|
36
|
+
"release": "changeset publish",
|
|
37
|
+
"docs:dev": "bun run --cwd docs dev",
|
|
38
|
+
"docs:build": "bun run docs:check && bun run --cwd docs build && bun docs/scripts/check-built.ts",
|
|
39
|
+
"docs:check": "bun docs/scripts/check.ts",
|
|
40
|
+
"docs:preview": "bun run --cwd docs preview"
|
|
36
41
|
},
|
|
37
42
|
"devDependencies": {
|
|
38
43
|
"@changesets/cli": "^3.0.3",
|
|
39
|
-
"@oxlint/plugins": "1.
|
|
40
|
-
"@types/bun": "^1.
|
|
41
|
-
"
|
|
42
|
-
"
|
|
44
|
+
"@oxlint/plugins": "1.88.0",
|
|
45
|
+
"@types/bun": "^1.4.3",
|
|
46
|
+
"executable-stories-bun": "^0.1.0",
|
|
47
|
+
"executable-stories-formatters": "^1.27.0",
|
|
48
|
+
"oxlint": "1.88.0",
|
|
49
|
+
"typescript": "^7.0.2"
|
|
43
50
|
},
|
|
44
51
|
"dependencies": {
|
|
45
|
-
"
|
|
46
|
-
"
|
|
52
|
+
"autotel": "8.2.1",
|
|
53
|
+
"yaml": "^2.9.1",
|
|
54
|
+
"zod": "^4.6.7"
|
|
47
55
|
}
|
|
48
56
|
}
|
|
@@ -79,6 +79,11 @@ For each failure:
|
|
|
79
79
|
a child failure; diagnose the leaves.
|
|
80
80
|
2. Fetch each leaf's failed-step log once: `gh run view --job <id> --log-failed`.
|
|
81
81
|
Keep the error, the command, and the file location; trim setup noise.
|
|
82
|
+
When the job uploads an executable-stories raw run or report, download it
|
|
83
|
+
(`gh run download <run_id>`) and read it as
|
|
84
|
+
`../shepherd/references/stories.md` says: the failing scenario, its failed
|
|
85
|
+
step, expected and actual values, and `covers` name the cause faster than
|
|
86
|
+
the log.
|
|
82
87
|
3. Find the real local command: the team policy's `checks` first
|
|
83
88
|
(`../shepherd/references/policy.md`), then the repo's config. Under
|
|
84
89
|
`fixes.mode: suggest` or `local`, and for a file under `escalate.paths`,
|
|
@@ -156,7 +161,7 @@ As a sub-step, end with exactly this and nothing after it:
|
|
|
156
161
|
"committed": false,
|
|
157
162
|
"commit_sha": null,
|
|
158
163
|
"fixed": [{"root_cause": "", "checks": [""], "validation": [""]}],
|
|
159
|
-
"rerun": [{"name": "", "job_id": "", "status": "queued|already-retried"}],
|
|
164
|
+
"rerun": [{"name": "", "job_id": "", "status": "queued|already-retried|requested"}],
|
|
160
165
|
"unresolved": [{"name": "", "classification": "gate|unrelated|needs-decision|unresolved", "reason": ""}]
|
|
161
166
|
},
|
|
162
167
|
"narration": ["[ci] ..."]
|