@jagreehal/shepherd 0.15.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.
Files changed (81) hide show
  1. package/AGENTS.md +3 -3
  2. package/README.md +40 -27
  3. package/THIRD_PARTY_NOTICES.md +2 -0
  4. package/gate/.shepherd/gate.schema.json +647 -0
  5. package/gate/.shepherd/gate.yml +122 -0
  6. package/gate/.shepherd/review-guidance.md +95 -0
  7. package/gate/src/actions.ts +32 -0
  8. package/gate/src/cli.ts +1028 -0
  9. package/gate/src/config.ts +102 -0
  10. package/gate/src/delta.ts +29 -0
  11. package/gate/src/env.ts +30 -0
  12. package/gate/src/eval.ts +288 -0
  13. package/gate/src/familiarity.ts +461 -0
  14. package/gate/src/github.ts +761 -0
  15. package/gate/src/inline.ts +59 -0
  16. package/gate/src/isolated-cli.ts +281 -0
  17. package/gate/src/leads.ts +257 -0
  18. package/gate/src/llm.ts +606 -0
  19. package/gate/src/notify.ts +57 -0
  20. package/gate/src/policy.ts +1297 -0
  21. package/gate/src/provider-errors.ts +80 -0
  22. package/gate/src/retention.ts +86 -0
  23. package/gate/src/reviewer.ts +739 -0
  24. package/gate/src/signals.ts +105 -0
  25. package/gate/src/smoke-live.ts +64 -0
  26. package/gate/src/stack.ts +87 -0
  27. package/gate/src/stories.ts +297 -0
  28. package/gate/templates/policy-strict.yml +127 -0
  29. package/gate/templates/reviewer.Dockerfile +8 -0
  30. package/gate/templates/rules/observability/SKILL.md +33 -0
  31. package/gate/templates/shepherd-gate-actions.yml +35 -0
  32. package/gate/templates/shepherd-gate-edited.yml +29 -0
  33. package/gate/templates/shepherd-gate.yml +111 -0
  34. package/lenses/dotnet/SKILL.md +1 -1
  35. package/lenses/go/SKILL.md +1 -1
  36. package/lenses/java/SKILL.md +1 -1
  37. package/lenses/nextjs/SKILL.md +1 -1
  38. package/lenses/node-api/SKILL.md +1 -1
  39. package/lenses/nx-monorepo/SKILL.md +1 -1
  40. package/lenses/observability/SKILL.md +1 -1
  41. package/lenses/owasp-asvs/SKILL.md +1 -1
  42. package/lenses/owasp-llm/SKILL.md +1 -1
  43. package/lenses/pstack/SKILL.md +1 -1
  44. package/lenses/python/SKILL.md +1 -1
  45. package/lenses/react/SKILL.md +1 -1
  46. package/lenses/rust/SKILL.md +1 -1
  47. package/package.json +20 -6
  48. package/schema/config.json +1 -1
  49. package/skills/branch-review/SKILL.md +123 -0
  50. package/skills/ci-repair/SKILL.md +79 -35
  51. package/skills/garden/SKILL.md +8 -8
  52. package/skills/garden/references/telemetry.md +4 -4
  53. package/skills/incident/SKILL.md +9 -9
  54. package/skills/lens-import/SKILL.md +7 -7
  55. package/skills/review-slop/SKILL.md +1 -1
  56. package/skills/shepherd/SKILL.md +43 -41
  57. package/skills/shepherd/references/degradation.md +3 -3
  58. package/skills/shepherd/references/dispatch.md +1 -1
  59. package/skills/shepherd/references/formats.md +5 -5
  60. package/skills/shepherd/references/models.md +2 -2
  61. package/skills/shepherd/references/policy.md +9 -9
  62. package/skills/swarm/SKILL.md +21 -17
  63. package/skills/swarm/references/custom-lenses.md +2 -2
  64. package/skills/swarm/references/formats.md +1 -1
  65. package/skills/triage/SKILL.md +10 -10
  66. package/src/bin.ts +10 -0
  67. package/src/cli.ts +283 -41
  68. package/src/config.ts +26 -25
  69. package/src/doctor.ts +31 -18
  70. package/src/garden-traces.ts +13 -13
  71. package/src/garden.ts +4 -4
  72. package/src/lens.ts +19 -7
  73. package/src/setup.ts +72 -0
  74. package/src/stack.ts +2 -2
  75. package/src/status.ts +80 -0
  76. package/src/summary.ts +52 -9
  77. package/src/trace.ts +4 -4
  78. package/src/working.ts +30 -0
  79. package/templates/shepherd-audit.yml +7 -15
  80. package/templates/shepherd-incident.yml +7 -12
  81. 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 stamp.
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 stamp asks for. ci-repair classifies a gate's failing check as
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 stamp approved
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. [Stamp](https://github.com/jagreehal/stamp) supplies the approval verdict; you decide when to merge.
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
- ## Start here
9
+ ## Set it up
10
10
 
11
- - [Run your first review](docs/src/content/docs/start/quickstart.md)
12
- - [Choose local review, a PR loop, or CI](docs/src/content/docs/start/choose-a-setup.md)
13
- - [Browse the documentation](docs/src/content/docs/index.md)
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
- You need Bun 1.2 or later, Git, an authenticated GitHub CLI and a coding agent that can load skills and run subagents.
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
- In your terminal, from the repository clone:
19
+ Once merged, `shepherd doctor` checks the setup. On any PR:
18
20
 
19
21
  ```bash
20
- bun add -g @jagreehal/shepherd
21
- shepherd install
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
- Or install it as a Claude Code plugin, beside pstack or any other plugin:
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
- ```text
30
- /plugin install shepherd --marketplace jagreehal/shepherd
31
- ```
28
+ ## Customize it
32
29
 
33
- The default `shepherd install` targets Claude Code. For another harness, use `shepherd install --target <skills-directory>`; Cursor reads the plugin manifest in `.cursor-plugin/`. 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`.
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
- In your coding agent:
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
- ```text
38
- /shepherd 42
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
- 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.
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 Stamp approves the current head, CI passes and no review thread remains open.
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
- ## Configure it for your team
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
- | Compose checks, modes and recipes | [Configuration reference](docs/src/content/docs/reference/configuration.md) |
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) |
@@ -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: