@jagreehal/shepherd 0.15.0 → 0.17.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 +3 -3
- package/README.md +40 -27
- package/THIRD_PARTY_NOTICES.md +2 -0
- package/gate/.shepherd/gate.schema.json +657 -0
- package/gate/.shepherd/gate.yml +123 -0
- package/gate/.shepherd/review-guidance.md +95 -0
- package/gate/src/actions.ts +32 -0
- package/gate/src/cli.ts +1046 -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 +292 -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 +647 -0
- package/gate/src/notify.ts +57 -0
- package/gate/src/policy.ts +1313 -0
- package/gate/src/prices.ts +62 -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 +128 -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 +21 -7
- 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 +8 -8
- package/skills/garden/references/telemetry.md +4 -4
- package/skills/incident/SKILL.md +9 -9
- package/skills/lens-import/SKILL.md +7 -7
- package/skills/review-slop/SKILL.md +1 -1
- package/skills/shepherd/SKILL.md +43 -41
- package/skills/shepherd/references/degradation.md +3 -3
- package/skills/shepherd/references/dispatch.md +1 -1
- 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 +21 -17
- package/skills/swarm/references/custom-lenses.md +2 -2
- package/skills/swarm/references/formats.md +1 -1
- package/skills/triage/SKILL.md +10 -10
- package/src/bin.ts +10 -0
- package/src/cli.ts +285 -42
- package/src/config.ts +26 -25
- package/src/doctor.ts +31 -18
- package/src/garden-traces.ts +13 -13
- package/src/garden.ts +4 -4
- 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 +7 -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
|
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:
|