@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.
Files changed (82) hide show
  1. package/AGENTS.md +13 -5
  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 +29 -10
  52. package/skills/garden/references/telemetry.md +4 -4
  53. package/skills/incident/SKILL.md +19 -9
  54. package/skills/lens-import/SKILL.md +7 -7
  55. package/skills/review-maintainability/SKILL.md +1 -1
  56. package/skills/review-slop/SKILL.md +1 -1
  57. package/skills/shepherd/SKILL.md +59 -44
  58. package/skills/shepherd/references/degradation.md +3 -3
  59. package/skills/shepherd/references/dispatch.md +2 -2
  60. package/skills/shepherd/references/formats.md +5 -5
  61. package/skills/shepherd/references/models.md +2 -2
  62. package/skills/shepherd/references/policy.md +9 -9
  63. package/skills/swarm/SKILL.md +26 -17
  64. package/skills/swarm/references/custom-lenses.md +2 -2
  65. package/skills/swarm/references/formats.md +1 -1
  66. package/skills/triage/SKILL.md +11 -11
  67. package/src/bin.ts +10 -0
  68. package/src/cli.ts +283 -41
  69. package/src/config.ts +26 -25
  70. package/src/doctor.ts +31 -18
  71. package/src/garden-traces.ts +13 -13
  72. package/src/garden.ts +43 -8
  73. package/src/lens.ts +19 -7
  74. package/src/setup.ts +72 -0
  75. package/src/stack.ts +2 -2
  76. package/src/status.ts +80 -0
  77. package/src/summary.ts +52 -9
  78. package/src/trace.ts +4 -4
  79. package/src/working.ts +30 -0
  80. package/templates/shepherd-audit.yml +7 -15
  81. package/templates/shepherd-incident.yml +9 -12
  82. 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
@@ -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. [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: