@jagreehal/shepherd 0.14.0 → 0.16.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 +13 -5
- package/README.md +40 -27
- package/THIRD_PARTY_NOTICES.md +2 -0
- package/gate/.shepherd/gate.schema.json +647 -0
- package/gate/.shepherd/gate.yml +122 -0
- package/gate/.shepherd/review-guidance.md +95 -0
- package/gate/src/actions.ts +32 -0
- package/gate/src/cli.ts +1028 -0
- package/gate/src/config.ts +102 -0
- package/gate/src/delta.ts +29 -0
- package/gate/src/env.ts +30 -0
- package/gate/src/eval.ts +288 -0
- package/gate/src/familiarity.ts +461 -0
- package/gate/src/github.ts +761 -0
- package/gate/src/inline.ts +59 -0
- package/gate/src/isolated-cli.ts +281 -0
- package/gate/src/leads.ts +257 -0
- package/gate/src/llm.ts +606 -0
- package/gate/src/notify.ts +57 -0
- package/gate/src/policy.ts +1297 -0
- package/gate/src/provider-errors.ts +80 -0
- package/gate/src/retention.ts +86 -0
- package/gate/src/reviewer.ts +739 -0
- package/gate/src/signals.ts +105 -0
- package/gate/src/smoke-live.ts +64 -0
- package/gate/src/stack.ts +87 -0
- package/gate/src/stories.ts +297 -0
- package/gate/templates/policy-strict.yml +127 -0
- package/gate/templates/reviewer.Dockerfile +8 -0
- package/gate/templates/rules/observability/SKILL.md +33 -0
- package/gate/templates/shepherd-gate-actions.yml +35 -0
- package/gate/templates/shepherd-gate-edited.yml +29 -0
- package/gate/templates/shepherd-gate.yml +111 -0
- package/lenses/dotnet/SKILL.md +1 -1
- package/lenses/go/SKILL.md +1 -1
- package/lenses/java/SKILL.md +1 -1
- package/lenses/nextjs/SKILL.md +1 -1
- package/lenses/node-api/SKILL.md +1 -1
- package/lenses/nx-monorepo/SKILL.md +1 -1
- package/lenses/observability/SKILL.md +1 -1
- package/lenses/owasp-asvs/SKILL.md +1 -1
- package/lenses/owasp-llm/SKILL.md +1 -1
- package/lenses/pstack/SKILL.md +1 -1
- package/lenses/python/SKILL.md +1 -1
- package/lenses/react/SKILL.md +1 -1
- package/lenses/rust/SKILL.md +1 -1
- package/package.json +20 -6
- package/schema/config.json +1 -1
- package/skills/branch-review/SKILL.md +123 -0
- package/skills/ci-repair/SKILL.md +79 -35
- package/skills/garden/SKILL.md +29 -10
- package/skills/garden/references/telemetry.md +4 -4
- package/skills/incident/SKILL.md +19 -9
- package/skills/lens-import/SKILL.md +7 -7
- package/skills/review-maintainability/SKILL.md +1 -1
- package/skills/review-slop/SKILL.md +1 -1
- package/skills/shepherd/SKILL.md +59 -44
- package/skills/shepherd/references/degradation.md +3 -3
- package/skills/shepherd/references/dispatch.md +2 -2
- package/skills/shepherd/references/formats.md +5 -5
- package/skills/shepherd/references/models.md +2 -2
- package/skills/shepherd/references/policy.md +9 -9
- package/skills/swarm/SKILL.md +26 -17
- package/skills/swarm/references/custom-lenses.md +2 -2
- package/skills/swarm/references/formats.md +1 -1
- package/skills/triage/SKILL.md +11 -11
- package/src/bin.ts +10 -0
- package/src/cli.ts +283 -41
- package/src/config.ts +26 -25
- package/src/doctor.ts +31 -18
- package/src/garden-traces.ts +13 -13
- package/src/garden.ts +43 -8
- package/src/lens.ts +19 -7
- package/src/setup.ts +72 -0
- package/src/stack.ts +2 -2
- package/src/status.ts +80 -0
- package/src/summary.ts +52 -9
- package/src/trace.ts +4 -4
- package/src/working.ts +30 -0
- package/templates/shepherd-audit.yml +7 -15
- package/templates/shepherd-incident.yml +9 -12
- package/templates/shepherd.yml +39 -40
package/AGENTS.md
CHANGED
|
@@ -14,7 +14,7 @@ to all of them.
|
|
|
14
14
|
text, and any gate that weighs reviews should too; a test pins it in swarm and
|
|
15
15
|
triage.
|
|
16
16
|
- **Swarm posts reviews with `event=COMMENT` only.** Approval belongs to a
|
|
17
|
-
human or
|
|
17
|
+
human or the gate.
|
|
18
18
|
- **Triage never posts.** Its only GitHub mutations are commits and resolving
|
|
19
19
|
all-automated threads. The report is the audit trail.
|
|
20
20
|
- **A thread with any human in it is never fixed, resolved, or replied to** by a
|
|
@@ -34,7 +34,7 @@ to all of them.
|
|
|
34
34
|
moving, or renaming files, no `AGENT_APPROVALS.md`, no placeholder for a
|
|
35
35
|
flagged credential: nothing whose aim is to make a gate pass. Fixing the
|
|
36
36
|
problem a gate names is ordinary work, and a deny-listed area still gets the
|
|
37
|
-
human review
|
|
37
|
+
human review the gate asks for. ci-repair classifies a gate's failing check as
|
|
38
38
|
`gate` and never edits code for it.
|
|
39
39
|
- **Fixing is the default.** Any concrete, local finding is fixed at any
|
|
40
40
|
severity. A contract change to code the PR introduces is fixed the way the
|
|
@@ -46,7 +46,7 @@ to all of them.
|
|
|
46
46
|
everything it names is fixed.** Passing tests prove nothing about behaviour
|
|
47
47
|
no test covers.
|
|
48
48
|
- **The loop's state lives on the PR.** Every iteration sets
|
|
49
|
-
the `shepherd` commit status on the head: `success` only when
|
|
49
|
+
the `shepherd` commit status on the head: `success` only when the gate approved
|
|
50
50
|
and nothing is left open, no person's latest review requesting changes,
|
|
51
51
|
`failure` naming what the author must do when the
|
|
52
52
|
loop can do no more, `pending` otherwise. A green PR with shepherd stopped
|
|
@@ -56,7 +56,12 @@ to all of them.
|
|
|
56
56
|
nothing risky, no choice of what the product does. A resolution changes the
|
|
57
57
|
PR's diff, so it ends the iteration `pending` until swarm has read it.
|
|
58
58
|
- **Behaviour changes made during review are disclosed** in one marked section
|
|
59
|
-
of the PR description; the rest of the body is the author's.
|
|
59
|
+
of the PR description; the rest of the body is the author's. A PR `/shepherd`
|
|
60
|
+
opens says in its first line that an agent wrote it and the author has not
|
|
61
|
+
reviewed it; only the author changes that line.
|
|
62
|
+
- **A security failure on a public repository stays private.** Incident opens
|
|
63
|
+
no issue, branch or PR for one and writes no test: a reproducing test is a
|
|
64
|
+
working exploit.
|
|
60
65
|
- **In CI the model holds no write credential.** Handoff mode commits and
|
|
61
66
|
never pushes; a job with no model pushes the bundle after its fast-forward
|
|
62
67
|
and path checks. Never name `SHEPHERD_TOKEN` anywhere in the model's job (a secret any
|
|
@@ -89,7 +94,7 @@ to all of them.
|
|
|
89
94
|
style) report MEDIUM at most. Personal lenses (`~/.config/shepherd`) are a
|
|
90
95
|
local preview: their findings never post, so they are never fixed.
|
|
91
96
|
- **House rules bind fixers too.** Triage, simplify, and ci-repair read
|
|
92
|
-
`AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, and `docs/adr/` from the default
|
|
97
|
+
`AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, `REVIEW.md`, and `docs/adr/` from the default
|
|
93
98
|
branch before editing.
|
|
94
99
|
- **CI repair never weakens a test** to go green: no loosened assertions, no
|
|
95
100
|
skips, no wholesale snapshot updates, no casts to `any`.
|
|
@@ -110,6 +115,9 @@ to all of them.
|
|
|
110
115
|
post under the author's account, and a run once read shepherd's own revert
|
|
111
116
|
as the author's decision; only commits without the trailer, and threads the
|
|
112
117
|
author wrote, say what the author decided.
|
|
118
|
+
- A finding names every place its mistake repeats in the PR's added lines, so
|
|
119
|
+
one round closes the class. Each round costs a commit when an agent is the
|
|
120
|
+
author; garden tracks rounds to pass and how each rule's threads ended.
|
|
113
121
|
- Reviewers (the router, every lens) start no agents and write no files; the
|
|
114
122
|
loop checks the tree is clean after them.
|
|
115
123
|
- GitHub is the record, not the session: swarm dedupes against open threads
|
package/README.md
CHANGED
|
@@ -4,41 +4,53 @@
|
|
|
4
4
|
|
|
5
5
|
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.
|
|
6
6
|
|
|
7
|
-
Use Shepherd to work through review comments and failing CI logs under your team's policy. It leaves human decisions for you.
|
|
7
|
+
Use Shepherd to work through review comments and failing CI logs under your team's policy. It leaves human decisions for you. `shepherd gate` is the approval gate: a separate read-only job decides whether the head is safe to approve, so the agent that fixes code never approves it. You decide when to merge.
|
|
8
8
|
|
|
9
|
-
##
|
|
9
|
+
## Set it up
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
11
|
+
In your repository, with Bun and an authenticated GitHub CLI, and a model key in your environment (`OPENCODE_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` or `OPENROUTER_API_KEY`):
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
bunx @jagreehal/shepherd init
|
|
15
|
+
```
|
|
14
16
|
|
|
15
|
-
|
|
17
|
+
That picks the model from your key, writes the workflows and `.shepherd/` config, sets the key as an Actions secret and lets Actions approve PRs. Commit the files, merge, and every PR gets a review and a verdict. It starts review-only: nothing is pushed until you run `shepherd init --preset push`. Pick the model yourself with `--model provider/model` (`opencode-go/…`, `anthropic/…`, `openai/…`, `openrouter/…`, `amazon-bedrock/…`).
|
|
16
18
|
|
|
17
|
-
|
|
19
|
+
Once merged, `shepherd doctor` checks the setup. On any PR:
|
|
18
20
|
|
|
19
21
|
```bash
|
|
20
|
-
|
|
21
|
-
shepherd
|
|
22
|
-
shepherd init --preset review-only
|
|
23
|
-
shepherd config validate
|
|
24
|
-
shepherd preview --working-tree
|
|
22
|
+
shepherd review 42 # starts a review in GitHub Actions and prints the run's URL
|
|
23
|
+
shepherd status 42 # reviewing, fixing, waiting for CI, needs you or ready, and what to do next
|
|
25
24
|
```
|
|
26
25
|
|
|
27
|
-
|
|
26
|
+
To run it from your coding agent instead, `shepherd install`, then `/shepherd 42` on a PR, or `/shepherd --local` before you open one.
|
|
28
27
|
|
|
29
|
-
|
|
30
|
-
/plugin install shepherd --marketplace jagreehal/shepherd
|
|
31
|
-
```
|
|
28
|
+
## Customize it
|
|
32
29
|
|
|
33
|
-
|
|
30
|
+
Your team's rules live in `.shepherd/`. Shepherd reads them from the default branch, so a change takes effect once you merge it.
|
|
34
31
|
|
|
35
|
-
|
|
32
|
+
| I want to… | Edit |
|
|
33
|
+
| --- | --- |
|
|
34
|
+
| Add my team's review rules | `.shepherd/lenses/<name>/SKILL.md`, made by `shepherd lens new <name>` |
|
|
35
|
+
| Run those rules only on some directories | The lens's `applies_to` in `.shepherd/config.yml` |
|
|
36
|
+
| Choose what Shepherd may change | `fixes.mode` in `.shepherd/config.yml` |
|
|
37
|
+
| Keep fixes out of code a person must own | `escalate.paths` in `.shepherd/config.yml` |
|
|
38
|
+
| Stop the gate approving changes to some files | A `deny` category in `.shepherd/gate.yml` |
|
|
39
|
+
| Share all of this across repositories | A pack, named under `extends` |
|
|
36
40
|
|
|
37
|
-
|
|
38
|
-
|
|
41
|
+
`config.yml` decides what Shepherd reviews and fixes; `gate.yml` decides what the gate approves. [Customize Shepherd for your team](docs/src/content/docs/start/customize.md) walks through one rule from checklist to enforced, and how to check it before you merge:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
shepherd config validate # config.yml and its lenses
|
|
45
|
+
shepherd gate config --policy-dir .shepherd # gate.yml
|
|
46
|
+
shepherd preview --working-tree # the plan for your current change
|
|
39
47
|
```
|
|
40
48
|
|
|
41
|
-
|
|
49
|
+
## Read more
|
|
50
|
+
|
|
51
|
+
- [Run your first review](docs/src/content/docs/start/quickstart.md)
|
|
52
|
+
- [Choose local review, a PR loop, or CI](docs/src/content/docs/start/choose-a-setup.md)
|
|
53
|
+
- [Browse the documentation](docs/src/content/docs/index.md)
|
|
42
54
|
|
|
43
55
|
## Choose what the agent may change
|
|
44
56
|
|
|
@@ -48,20 +60,21 @@ Replace `42` with your PR number. Expect findings on the PR and a `reviewed` res
|
|
|
48
60
|
| `local` | Fixes left in your working tree; you commit and push |
|
|
49
61
|
| `push` | Fixes committed and pushed under the skill rules |
|
|
50
62
|
|
|
51
|
-
`/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
|
|
63
|
+
`/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 the gate approves the current head, CI passes and no review thread remains open.
|
|
64
|
+
|
|
65
|
+
## Go further
|
|
52
66
|
|
|
53
|
-
|
|
67
|
+
None of this is needed for a first run.
|
|
54
68
|
|
|
55
69
|
| Task | Guide |
|
|
56
70
|
| --- | --- |
|
|
57
71
|
| Review before opening a PR | [Local review](docs/src/content/docs/guides/local-review.md) |
|
|
58
|
-
|
|
|
59
|
-
| Share organisation policy | [Team examples](docs/src/content/docs/configuration/examples.md) |
|
|
60
|
-
| Add domain-specific reviewers | [Lenses](docs/src/content/docs/configuration/lenses.md) |
|
|
72
|
+
| Every configuration key, and team examples | [Configuration reference](docs/src/content/docs/reference/configuration.md), [Team examples](docs/src/content/docs/configuration/examples.md) |
|
|
61
73
|
| Review React, Next.js, Node, Go, Rust, Java, .NET or Python code, or import any skill as a lens | [Stack packs](docs/src/content/docs/configuration/stacks.md) |
|
|
62
74
|
| Use with pstack, or any plugin's skills as lenses | [pstack](docs/src/content/docs/integrations/pstack.md) |
|
|
63
75
|
| Select models by role | [Model routing](docs/src/content/docs/configuration/models.md) |
|
|
64
|
-
| Run without your laptop | [GitHub Actions](docs/src/content/docs/integrations/github-actions.md) |
|
|
76
|
+
| Run without your laptop | [GitHub Actions](docs/src/content/docs/integrations/github-actions.md): `shepherd workflows --model <provider/model>` writes the loop and the gate |
|
|
77
|
+
| Pick a model and its key | [Environment](docs/src/content/docs/reference/environment.md): `SHEPHERD_MODEL=provider/model` and the provider's own key |
|
|
65
78
|
| Get told when a PR needs you | [Notifications](docs/src/content/docs/integrations/notifications.md) |
|
|
66
79
|
| Investigate a failure after merge | [Incidents](docs/src/content/docs/guides/incidents.md) |
|
|
67
80
|
| Improve recurring findings | [Gardening](docs/src/content/docs/operations/gardening.md) |
|
package/THIRD_PARTY_NOTICES.md
CHANGED
|
@@ -12,6 +12,8 @@ These skill directories are copied unchanged from [mattpocock/skills](https://gi
|
|
|
12
12
|
| `skills/retro/` | `skills/engineering/retro/` |
|
|
13
13
|
| `skills/writing-for-agents/` | `skills/productivity/writing-for-agents/` |
|
|
14
14
|
|
|
15
|
+
`skills/branch-review/` adapts `skills/engineering/code-review/` at the same commit: it reads the issue tracker from GitHub with `gh` in place of the upstream setup step, reads the standards from a freshly fetched, pinned default-branch commit, and includes uncommitted work in the diff. The rest is the same text.
|
|
16
|
+
|
|
15
17
|
To update, copy each upstream directory over its copy here and update the commit above. Never edit these files: shepherd's own skills point at them and adapt them. `skills/pr/CREDITS.md` carries the upstream attribution for its Summary section.
|
|
16
18
|
|
|
17
19
|
They are used under the MIT License:
|