@jagreehal/shepherd 0.5.0 → 0.7.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/README.md +8 -1
- package/THIRD_PARTY_NOTICES.md +30 -0
- package/commands/shepherd.md +3 -2
- package/lenses/pstack/SKILL.md +33 -0
- package/package.json +5 -2
- package/packs/pstack.yml +8 -0
- package/schema/config.json +340 -0
- package/skills/ci-repair/SKILL.md +11 -3
- package/skills/incident/SKILL.md +4 -2
- package/skills/lens-import/SKILL.md +5 -3
- package/skills/shepherd/SKILL.md +43 -17
- package/skills/shepherd/references/dispatch.md +11 -6
- package/skills/shepherd/references/models.md +1 -1
- package/skills/swarm/SKILL.md +108 -72
- package/skills/swarm/references/custom-lenses.md +12 -4
- package/skills/swarm/references/formats.md +3 -3
- package/skills/triage/SKILL.md +16 -1
- package/src/cli.ts +189 -23
- package/src/config.ts +169 -2
- package/src/doctor.ts +16 -13
- package/src/install.ts +52 -0
- package/src/lens.ts +91 -7
- package/templates/shepherd-audit.yml +44 -11
- package/templates/shepherd-incident.yml +40 -7
- package/templates/shepherd.yml +148 -25
package/README.md
CHANGED
|
@@ -22,7 +22,13 @@ shepherd config validate
|
|
|
22
22
|
shepherd preview --working-tree
|
|
23
23
|
```
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
Or install it as a Claude Code plugin, beside pstack or any other plugin:
|
|
26
|
+
|
|
27
|
+
```text
|
|
28
|
+
/plugin install shepherd --marketplace jagreehal/shepherd
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
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`.
|
|
26
32
|
|
|
27
33
|
In your coding agent:
|
|
28
34
|
|
|
@@ -51,6 +57,7 @@ Replace `42` with your PR number. Expect findings on the PR and a `reviewed` res
|
|
|
51
57
|
| Share organisation policy | [Team examples](docs/src/content/docs/configuration/examples.md) |
|
|
52
58
|
| Add domain-specific reviewers | [Lenses](docs/src/content/docs/configuration/lenses.md) |
|
|
53
59
|
| 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) |
|
|
60
|
+
| Use with pstack, or any plugin's skills as lenses | [pstack](docs/src/content/docs/integrations/pstack.md) |
|
|
54
61
|
| Select models by role | [Model routing](docs/src/content/docs/configuration/models.md) |
|
|
55
62
|
| Run without your laptop | [GitHub Actions](docs/src/content/docs/integrations/github-actions.md) |
|
|
56
63
|
| Get told when a PR needs you | [Notifications](docs/src/content/docs/integrations/notifications.md) |
|
package/THIRD_PARTY_NOTICES.md
CHANGED
|
@@ -50,3 +50,33 @@ These lenses adapt material from the [OWASP Secure Agent Playbook](https://githu
|
|
|
50
50
|
| `lenses/owasp-llm/` | `plugins/ai-security-skills/` plays and skills for the OWASP LLM Top 10 2025, the Agentic Top 10 2026 and MCP server review |
|
|
51
51
|
|
|
52
52
|
The source is licensed under the [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/) (CC-BY-4.0). The adapted lenses carry the same licence and name their source commit in their frontmatter.
|
|
53
|
+
|
|
54
|
+
## pstack
|
|
55
|
+
|
|
56
|
+
`lenses/pstack/` adapts the principle skills of [pstack](https://github.com/cursor/plugins/tree/main/pstack) by Lauren Tan, version 0.15.29 (`skills/principle-*`). Each rule condenses one or more principles into a review line, cut to what a diff can show.
|
|
57
|
+
|
|
58
|
+
It is used under the MIT License:
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
MIT License
|
|
62
|
+
|
|
63
|
+
Copyright (c) 2026 Lauren Tan
|
|
64
|
+
|
|
65
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
66
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
67
|
+
in the Software without restriction, including without limitation the rights
|
|
68
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
69
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
70
|
+
furnished to do so, subject to the following conditions:
|
|
71
|
+
|
|
72
|
+
The above copyright notice and this permission notice shall be included in all
|
|
73
|
+
copies or substantial portions of the Software.
|
|
74
|
+
|
|
75
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
76
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
77
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
78
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
79
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
80
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
81
|
+
SOFTWARE.
|
|
82
|
+
```
|
package/commands/shepherd.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
description: Shepherd a PR to merge-ready (loop on Sonnet, reviews on their own ladder)
|
|
3
|
-
argument-hint: [pr-number-or-url | --local]
|
|
3
|
+
argument-hint: [pr-number-or-url | --local [--base <ref>]]
|
|
4
4
|
model: sonnet
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -13,6 +13,7 @@ ladder in `shepherd/references/models.md`.
|
|
|
13
13
|
For hands-off cadence: `/loop 5m /shepherd <pr>`.
|
|
14
14
|
|
|
15
15
|
Before a PR exists: `/shepherd --local` reviews and fixes your change on this
|
|
16
|
-
machine and touches nothing on GitHub.
|
|
16
|
+
machine and touches nothing on GitHub. Add `--base <ref>` when the branch will
|
|
17
|
+
merge into something other than the default branch.
|
|
17
18
|
|
|
18
19
|
<!-- shepherd-installed -->
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pstack
|
|
3
|
+
description: pstack's engineering principles as code review rules. Flags changes that work against the principles pstack-driven agents are told to follow. Covers a symptom patched where the fault surfaced, guards that hide a state that should never exist, validation scattered past the boundary, raw external data trusted without a parse, interchangeable primitives, domain rules spread across conditionals, one-caller layers and wider mutable state, old APIs kept beside their replacement, steps that break when run twice, shared write targets, tests that cannot fail or are pinned to internals, and numbers or claims the PR states without evidence. Use as a review lens or as a stamp rule pack.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# pstack
|
|
7
|
+
|
|
8
|
+
These rules come from the principles in
|
|
9
|
+
[pstack](https://github.com/cursor/plugins/tree/main/pstack) by Lauren Tan
|
|
10
|
+
(MIT). A team whose agents work through pstack's `poteto-mode` gets reviews
|
|
11
|
+
that check the same principles. Review whether the change fixes faults where
|
|
12
|
+
they start, keeps checks at the boundary, lets the types and data structures
|
|
13
|
+
carry the domain, and proves what it claims.
|
|
14
|
+
|
|
15
|
+
## Review
|
|
16
|
+
|
|
17
|
+
- **fix-root-cause**: A fix changes the first place the system went wrong, not the place the symptom showed. Flag: a guard, retry, clamp, default value or swallowed error added where a bad state surfaced, when nothing shows that state is legitimate; the same fault left in sibling code the fix did not touch; a workaround justified by a long comment. Why: a symptom fix hides the evidence and the fault surfaces somewhere else.
|
|
18
|
+
- **boundary-checks**: Input is validated and parsed into typed values where it enters (CLI arguments, config, environment, network, files, database rows, model output), and trusted inside. Flag: external data used without a parse at the point it enters; the same value re-checked deep in a call chain the boundary already checked; a transport, storage or framework type exposed through the module's public surface. Why: scattered checks are noisy, and the one that matters is missing.
|
|
19
|
+
- **types-carry-meaning**: Two values that share a primitive but mean different things cannot be swapped, and a union is handled exhaustively. Flag: two same-typed parameters that are easy to pass in the wrong order (`userId, orderId: string`); a switch over a union with no exhaustiveness check; a hand-written type that duplicates one a schema, migration or spec already owns. Why: the compiler can catch these and a reviewer often cannot.
|
|
20
|
+
- **model-the-domain**: The domain lives in one structure: a state machine, discriminated union, lookup table or typed model. Flag: a new branch added to an existing if/else chain over the same kind of value; a second boolean that must stay in sync with a first; the same domain rule repeated across phase-named modules. Why: every new case adds another place to forget.
|
|
21
|
+
- **reader-load**: Each layer the change adds hides a real decision, and state lives in the smallest scope. Flag: a wrapper or adapter with one caller and no second implementation; a layer that repeats the methods and arguments of the one below; a new module-level or shared mutable field where a local or a return value would do; a value kept in sync by hand where it could be derived. Why: readers trace every layer and hold every piece of state.
|
|
22
|
+
- **subtract-first**: The change adds no code for needs nobody has shown. Flag: a validator, option, parameter or extension point with no caller; a stub, placeholder or reference with no content; new code beside dead code it could have replaced. Why: speculative code costs every future reader and is rarely the shape the real need takes.
|
|
23
|
+
- **delete-legacy**: A replaced API is removed in the same change once its callers move. Flag: an old function, flag or code path kept beside its replacement with no external user named; a compatibility shim inside one repository; tests that only protect the old implementation. Why: two ways to do one thing become two things to maintain, and agents copy the old one.
|
|
24
|
+
- **idempotent-steps**: A step that changes state converges when it runs twice or after a crash partway through. Flag: a migration, job, command or handler that inserts, appends or sends without checking what already exists; a lock, temp file or claim marker the next run cannot recognise as stale; a write to a final path that a crash can leave half written. Why: retries and restarts are normal, and each one becomes a debugging session.
|
|
25
|
+
- **separate-shared-state**: Concurrent actors do not share a mutable target unless one shared target is a real invariant, and then access is serialised by structure. Flag: two workers, requests or agents writing the same file, key, row or branch; a race handled by a comment or convention; a lock added where separate owned targets would remove the sharing. Why: races are intermittent and expensive to find.
|
|
26
|
+
- **tests-catch-breaks**: A test fails when the behaviour it covers breaks and survives a refactor that keeps that behaviour. Flag: an expected value computed by the code under test; an assertion looser than the contract; a test that only checks data it built itself; an assertion on private helpers or call order where the user-visible result is the contract. Why: a test that cannot fail proves nothing, and one pinned to internals breaks on every refactor.
|
|
27
|
+
- **prove-the-claim**: What the PR description claims about behaviour or performance has evidence in the PR. Flag: a stated speedup, fix or "verified" with no test, script, run output or measurement behind it; a benchmark number with no run count, spread or named limiter. Why: an unverified claim reads the same as a true one.
|
|
28
|
+
|
|
29
|
+
## Fix
|
|
30
|
+
|
|
31
|
+
- Prefer: the repository's existing parse functions, branded types, state structures and test helpers, found in code next to the change.
|
|
32
|
+
- Never touch: tests that the change did not add, to make a rule pass.
|
|
33
|
+
- Escalate: deleting a legacy API that code outside the diff still calls, introducing a new domain structure across modules, and any `prove-the-claim` finding: the evidence has to come from the author.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jagreehal/shepherd",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.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",
|
|
@@ -17,6 +17,7 @@
|
|
|
17
17
|
"lenses",
|
|
18
18
|
"packs",
|
|
19
19
|
"templates",
|
|
20
|
+
"schema",
|
|
20
21
|
"AGENTS.md",
|
|
21
22
|
"THIRD_PARTY_NOTICES.md"
|
|
22
23
|
],
|
|
@@ -38,12 +39,14 @@
|
|
|
38
39
|
"docs:dev": "bun run --cwd docs dev",
|
|
39
40
|
"docs:build": "bun run docs:check && bun run --cwd docs build && bun docs/scripts/check-built.ts",
|
|
40
41
|
"docs:check": "bun docs/scripts/check.ts",
|
|
41
|
-
"docs:preview": "bun run --cwd docs preview"
|
|
42
|
+
"docs:preview": "bun run --cwd docs preview",
|
|
43
|
+
"schema": "bun src/cli.ts config schema > schema/config.json"
|
|
42
44
|
},
|
|
43
45
|
"devDependencies": {
|
|
44
46
|
"@changesets/cli": "^3.0.3",
|
|
45
47
|
"@oxlint/plugins": "1.88.0",
|
|
46
48
|
"@types/bun": "^1.4.3",
|
|
49
|
+
"ajv": "8.20.0",
|
|
47
50
|
"executable-stories-bun": "^0.1.0",
|
|
48
51
|
"executable-stories-formatters": "^1.27.0",
|
|
49
52
|
"oxlint": "1.88.0",
|
package/packs/pstack.yml
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# pstack's engineering principles as review rules (github.com/cursor/plugins/tree/main/pstack, MIT).
|
|
2
|
+
# Extend pinned: github:jagreehal/shepherd/packs/pstack.yml@<sha>
|
|
3
|
+
# For teams whose agents work through pstack's poteto-mode: reviews check the same principles.
|
|
4
|
+
lenses:
|
|
5
|
+
pstack:
|
|
6
|
+
skill: lenses/pstack
|
|
7
|
+
applies_to: ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx', '**/*.go', '**/*.rs', '**/*.java', '**/*.cs', '**/*.py']
|
|
8
|
+
gate: note
|
|
@@ -0,0 +1,340 @@
|
|
|
1
|
+
{
|
|
2
|
+
"title": "shepherd team policy (.shepherd/config.yml)",
|
|
3
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
4
|
+
"type": "object",
|
|
5
|
+
"properties": {
|
|
6
|
+
"extends": {
|
|
7
|
+
"type": "array",
|
|
8
|
+
"items": {
|
|
9
|
+
"type": "string",
|
|
10
|
+
"minLength": 1
|
|
11
|
+
}
|
|
12
|
+
},
|
|
13
|
+
"tiers": {
|
|
14
|
+
"type": "object",
|
|
15
|
+
"propertyNames": {
|
|
16
|
+
"type": "string",
|
|
17
|
+
"pattern": "^[a-z][a-z0-9-]*$"
|
|
18
|
+
},
|
|
19
|
+
"additionalProperties": {
|
|
20
|
+
"type": "string",
|
|
21
|
+
"minLength": 1
|
|
22
|
+
}
|
|
23
|
+
},
|
|
24
|
+
"ladder": {
|
|
25
|
+
"minItems": 1,
|
|
26
|
+
"type": "array",
|
|
27
|
+
"items": {
|
|
28
|
+
"type": "string",
|
|
29
|
+
"minLength": 1
|
|
30
|
+
}
|
|
31
|
+
},
|
|
32
|
+
"models": {
|
|
33
|
+
"type": "object",
|
|
34
|
+
"propertyNames": {
|
|
35
|
+
"type": "string",
|
|
36
|
+
"pattern": "^[a-z][a-z0-9-]*$"
|
|
37
|
+
},
|
|
38
|
+
"additionalProperties": {
|
|
39
|
+
"type": "string",
|
|
40
|
+
"minLength": 1
|
|
41
|
+
}
|
|
42
|
+
},
|
|
43
|
+
"lenses": {
|
|
44
|
+
"default": {},
|
|
45
|
+
"type": "object",
|
|
46
|
+
"propertyNames": {
|
|
47
|
+
"type": "string",
|
|
48
|
+
"pattern": "^[a-z][a-z0-9-]*$"
|
|
49
|
+
},
|
|
50
|
+
"additionalProperties": {
|
|
51
|
+
"type": "object",
|
|
52
|
+
"properties": {
|
|
53
|
+
"skill": {
|
|
54
|
+
"type": "string",
|
|
55
|
+
"minLength": 1
|
|
56
|
+
},
|
|
57
|
+
"applies_to": {
|
|
58
|
+
"type": "array",
|
|
59
|
+
"items": {
|
|
60
|
+
"type": "string",
|
|
61
|
+
"minLength": 1
|
|
62
|
+
}
|
|
63
|
+
},
|
|
64
|
+
"description": {
|
|
65
|
+
"type": "string",
|
|
66
|
+
"minLength": 1
|
|
67
|
+
},
|
|
68
|
+
"gate": {
|
|
69
|
+
"type": "string",
|
|
70
|
+
"enum": [
|
|
71
|
+
"refuse",
|
|
72
|
+
"escalate",
|
|
73
|
+
"note"
|
|
74
|
+
]
|
|
75
|
+
},
|
|
76
|
+
"only": {
|
|
77
|
+
"minItems": 1,
|
|
78
|
+
"type": "array",
|
|
79
|
+
"items": {
|
|
80
|
+
"type": "string",
|
|
81
|
+
"minLength": 1
|
|
82
|
+
}
|
|
83
|
+
},
|
|
84
|
+
"disable": {
|
|
85
|
+
"minItems": 1,
|
|
86
|
+
"type": "array",
|
|
87
|
+
"items": {
|
|
88
|
+
"type": "string",
|
|
89
|
+
"minLength": 1
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
},
|
|
93
|
+
"additionalProperties": false
|
|
94
|
+
}
|
|
95
|
+
},
|
|
96
|
+
"checks": {
|
|
97
|
+
"type": "object",
|
|
98
|
+
"propertyNames": {
|
|
99
|
+
"type": "string",
|
|
100
|
+
"pattern": "^[a-z][a-z0-9-]*$"
|
|
101
|
+
},
|
|
102
|
+
"additionalProperties": {
|
|
103
|
+
"type": "object",
|
|
104
|
+
"properties": {
|
|
105
|
+
"command": {
|
|
106
|
+
"type": "string",
|
|
107
|
+
"minLength": 1
|
|
108
|
+
}
|
|
109
|
+
},
|
|
110
|
+
"required": [
|
|
111
|
+
"command"
|
|
112
|
+
],
|
|
113
|
+
"additionalProperties": false
|
|
114
|
+
}
|
|
115
|
+
},
|
|
116
|
+
"fixes": {
|
|
117
|
+
"type": "object",
|
|
118
|
+
"properties": {
|
|
119
|
+
"mode": {
|
|
120
|
+
"type": "string",
|
|
121
|
+
"enum": [
|
|
122
|
+
"suggest",
|
|
123
|
+
"local",
|
|
124
|
+
"push"
|
|
125
|
+
]
|
|
126
|
+
}
|
|
127
|
+
},
|
|
128
|
+
"required": [
|
|
129
|
+
"mode"
|
|
130
|
+
],
|
|
131
|
+
"additionalProperties": false
|
|
132
|
+
},
|
|
133
|
+
"escalate": {
|
|
134
|
+
"type": "object",
|
|
135
|
+
"properties": {
|
|
136
|
+
"paths": {
|
|
137
|
+
"minItems": 1,
|
|
138
|
+
"type": "array",
|
|
139
|
+
"items": {
|
|
140
|
+
"type": "string",
|
|
141
|
+
"minLength": 1
|
|
142
|
+
}
|
|
143
|
+
},
|
|
144
|
+
"reason": {
|
|
145
|
+
"type": "string",
|
|
146
|
+
"minLength": 1
|
|
147
|
+
}
|
|
148
|
+
},
|
|
149
|
+
"required": [
|
|
150
|
+
"paths"
|
|
151
|
+
],
|
|
152
|
+
"additionalProperties": false
|
|
153
|
+
},
|
|
154
|
+
"branding": {
|
|
155
|
+
"type": "object",
|
|
156
|
+
"properties": {
|
|
157
|
+
"name": {
|
|
158
|
+
"type": "string",
|
|
159
|
+
"minLength": 1,
|
|
160
|
+
"maxLength": 40,
|
|
161
|
+
"pattern": "\\S"
|
|
162
|
+
},
|
|
163
|
+
"avatar": {
|
|
164
|
+
"type": "string",
|
|
165
|
+
"maxLength": 500,
|
|
166
|
+
"format": "uri",
|
|
167
|
+
"pattern": "^https://(?:[A-Za-z0-9-]+\\.)*[A-Za-z][A-Za-z0-9-]*(?::(?:6553[0-5]|655[0-2]\\d|65[0-4]\\d{2}|6[0-4]\\d{3}|[1-5]\\d{4}|\\d{1,4}))?(?:[/?#]\\S*)?$"
|
|
168
|
+
},
|
|
169
|
+
"emoji": {
|
|
170
|
+
"type": "object",
|
|
171
|
+
"properties": {
|
|
172
|
+
"critical": {
|
|
173
|
+
"type": "string",
|
|
174
|
+
"minLength": 1,
|
|
175
|
+
"maxLength": 16,
|
|
176
|
+
"pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
|
|
177
|
+
},
|
|
178
|
+
"high": {
|
|
179
|
+
"type": "string",
|
|
180
|
+
"minLength": 1,
|
|
181
|
+
"maxLength": 16,
|
|
182
|
+
"pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
|
|
183
|
+
},
|
|
184
|
+
"medium": {
|
|
185
|
+
"type": "string",
|
|
186
|
+
"minLength": 1,
|
|
187
|
+
"maxLength": 16,
|
|
188
|
+
"pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
|
|
189
|
+
},
|
|
190
|
+
"low": {
|
|
191
|
+
"type": "string",
|
|
192
|
+
"minLength": 1,
|
|
193
|
+
"maxLength": 16,
|
|
194
|
+
"pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
|
|
195
|
+
},
|
|
196
|
+
"nit": {
|
|
197
|
+
"type": "string",
|
|
198
|
+
"minLength": 1,
|
|
199
|
+
"maxLength": 16,
|
|
200
|
+
"pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
|
|
201
|
+
},
|
|
202
|
+
"blocked": {
|
|
203
|
+
"type": "string",
|
|
204
|
+
"minLength": 1,
|
|
205
|
+
"maxLength": 16,
|
|
206
|
+
"pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
|
|
207
|
+
},
|
|
208
|
+
"changes_needed": {
|
|
209
|
+
"type": "string",
|
|
210
|
+
"minLength": 1,
|
|
211
|
+
"maxLength": 16,
|
|
212
|
+
"pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
|
|
213
|
+
},
|
|
214
|
+
"approve_with_nits": {
|
|
215
|
+
"type": "string",
|
|
216
|
+
"minLength": 1,
|
|
217
|
+
"maxLength": 16,
|
|
218
|
+
"pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
|
|
219
|
+
},
|
|
220
|
+
"looks_good": {
|
|
221
|
+
"type": "string",
|
|
222
|
+
"minLength": 1,
|
|
223
|
+
"maxLength": 16,
|
|
224
|
+
"pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
|
|
225
|
+
},
|
|
226
|
+
"resolved": {
|
|
227
|
+
"type": "string",
|
|
228
|
+
"minLength": 1,
|
|
229
|
+
"maxLength": 16,
|
|
230
|
+
"pattern": "^[^\\s<>&*_`[\\]\\\\|]+$"
|
|
231
|
+
}
|
|
232
|
+
},
|
|
233
|
+
"additionalProperties": false
|
|
234
|
+
}
|
|
235
|
+
},
|
|
236
|
+
"additionalProperties": false
|
|
237
|
+
},
|
|
238
|
+
"ci": {
|
|
239
|
+
"type": "object",
|
|
240
|
+
"properties": {
|
|
241
|
+
"label": {
|
|
242
|
+
"type": "string",
|
|
243
|
+
"minLength": 1,
|
|
244
|
+
"maxLength": 500,
|
|
245
|
+
"pattern": "^[^\\n\\r]*$"
|
|
246
|
+
},
|
|
247
|
+
"aws_region": {
|
|
248
|
+
"type": "string",
|
|
249
|
+
"minLength": 1,
|
|
250
|
+
"maxLength": 500,
|
|
251
|
+
"pattern": "^[^\\n\\r]*$"
|
|
252
|
+
},
|
|
253
|
+
"notify_on": {
|
|
254
|
+
"minItems": 1,
|
|
255
|
+
"type": "array",
|
|
256
|
+
"items": {
|
|
257
|
+
"type": "string",
|
|
258
|
+
"enum": [
|
|
259
|
+
"success",
|
|
260
|
+
"failure",
|
|
261
|
+
"pending",
|
|
262
|
+
"error"
|
|
263
|
+
]
|
|
264
|
+
}
|
|
265
|
+
},
|
|
266
|
+
"max_commits": {
|
|
267
|
+
"type": "integer",
|
|
268
|
+
"minimum": 1,
|
|
269
|
+
"maximum": 200
|
|
270
|
+
},
|
|
271
|
+
"push_deny": {
|
|
272
|
+
"minItems": 1,
|
|
273
|
+
"type": "array",
|
|
274
|
+
"items": {
|
|
275
|
+
"type": "string",
|
|
276
|
+
"minLength": 1,
|
|
277
|
+
"maxLength": 500,
|
|
278
|
+
"pattern": "^[^\\n\\r]*$"
|
|
279
|
+
}
|
|
280
|
+
},
|
|
281
|
+
"incident_paths": {
|
|
282
|
+
"type": "string",
|
|
283
|
+
"minLength": 1,
|
|
284
|
+
"maxLength": 500,
|
|
285
|
+
"pattern": "^[^\\n\\r]*$"
|
|
286
|
+
},
|
|
287
|
+
"audit": {
|
|
288
|
+
"type": "object",
|
|
289
|
+
"properties": {
|
|
290
|
+
"plays": {
|
|
291
|
+
"minItems": 1,
|
|
292
|
+
"type": "array",
|
|
293
|
+
"items": {
|
|
294
|
+
"type": "string",
|
|
295
|
+
"pattern": "^[a-z0-9-]+$"
|
|
296
|
+
}
|
|
297
|
+
},
|
|
298
|
+
"public": {
|
|
299
|
+
"type": "boolean"
|
|
300
|
+
}
|
|
301
|
+
},
|
|
302
|
+
"additionalProperties": false
|
|
303
|
+
}
|
|
304
|
+
},
|
|
305
|
+
"additionalProperties": false
|
|
306
|
+
},
|
|
307
|
+
"recipes": {
|
|
308
|
+
"type": "object",
|
|
309
|
+
"propertyNames": {
|
|
310
|
+
"type": "string",
|
|
311
|
+
"pattern": "^[a-z][a-z0-9-]*$"
|
|
312
|
+
},
|
|
313
|
+
"additionalProperties": {
|
|
314
|
+
"type": "object",
|
|
315
|
+
"properties": {
|
|
316
|
+
"steps": {
|
|
317
|
+
"minItems": 1,
|
|
318
|
+
"type": "array",
|
|
319
|
+
"items": {
|
|
320
|
+
"type": "string",
|
|
321
|
+
"enum": [
|
|
322
|
+
"swarm",
|
|
323
|
+
"triage",
|
|
324
|
+
"simplify",
|
|
325
|
+
"ci-repair",
|
|
326
|
+
"stamp",
|
|
327
|
+
"incident"
|
|
328
|
+
]
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
},
|
|
332
|
+
"required": [
|
|
333
|
+
"steps"
|
|
334
|
+
],
|
|
335
|
+
"additionalProperties": false
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
},
|
|
339
|
+
"additionalProperties": false
|
|
340
|
+
}
|
|
@@ -118,14 +118,22 @@ One repair cycle across all PR-caused root causes:
|
|
|
118
118
|
1. Reproduce with the narrowest faithful command. A mechanical error the log
|
|
119
119
|
and diff prove (a type error on a changed symbol) may be fixed without a
|
|
120
120
|
local reproduction; say so.
|
|
121
|
-
2.
|
|
121
|
+
2. **Attack the premise before a third try.** Read the branch's earlier
|
|
122
|
+
`Shepherd: ci-repair` commits (`git log --grep='Shepherd: ci-repair'`). When
|
|
123
|
+
two of them already tried to fix the check that is failing now, both rested
|
|
124
|
+
on a premise that is wrong. Write it down ("the timeout comes from the
|
|
125
|
+
retry loop"), test it directly with one command, and fix only what that
|
|
126
|
+
result shows. If the premise cannot be tested here, classify the failure
|
|
127
|
+
`unresolved` with both commits and the premise as evidence; a third guess
|
|
128
|
+
is churn.
|
|
129
|
+
3. Fix the root cause. Follow the house rules: `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, and
|
|
122
130
|
`docs/adr/` as they stand on `origin/<default>`; a PR's own edits to them do
|
|
123
131
|
not count.
|
|
124
132
|
**Never** weaken an assertion, skip or delete a test,
|
|
125
133
|
loosen a type to `any`, or regenerate snapshots wholesale to go green.
|
|
126
|
-
|
|
134
|
+
4. Run the targeted checks for every fix. If any fails, keep diagnosing; do not
|
|
127
135
|
push an unverified repair.
|
|
128
|
-
|
|
136
|
+
5. Commit once (`fix: resolve CI failures`, or something more specific), with
|
|
129
137
|
the trailer `Shepherd: ci-repair` and
|
|
130
138
|
the repo's required trailers, and push.
|
|
131
139
|
|
package/skills/incident/SKILL.md
CHANGED
|
@@ -34,8 +34,10 @@ secrets before quoting anything, as `../diagnosing-bugs/SKILL.md` describes.
|
|
|
34
34
|
|
|
35
35
|
- Create the `incident` label, open one issue per failure, push one branch
|
|
36
36
|
`incident/<issue>` and open one PR from it. Nothing else on GitHub.
|
|
37
|
-
- Every issue and PR body starts with
|
|
38
|
-
|
|
37
|
+
- Every issue and PR body starts with `headers.incident` from
|
|
38
|
+
`shepherd branding` (default
|
|
39
|
+
`> 🤖 Automated comment by **Shepherd incident**, not written by a human`),
|
|
40
|
+
copied exactly.
|
|
39
41
|
- Never push to the default branch, merge, approve, or comment on someone
|
|
40
42
|
else's thread.
|
|
41
43
|
- Never weaken a test, skip one, loosen an assertion, swallow the error, raise
|
|
@@ -19,8 +19,10 @@ agent setup or output instructions. The format is defined in
|
|
|
19
19
|
|
|
20
20
|
## Inputs
|
|
21
21
|
|
|
22
|
-
- Source: an installed name,
|
|
23
|
-
|
|
22
|
+
- Source: an installed name, an installed plugin's skill as `<plugin>:<skill>`
|
|
23
|
+
(`pstack:principle-fix-root-causes`), local path,
|
|
24
|
+
`github:owner/repo/path@<ref>`, pasted document, or collection directory (a
|
|
25
|
+
plugin's `skills/` directory is one). Accept several sources in one request.
|
|
24
26
|
- Target: the caller's repository unless the user names another. Inspect it;
|
|
25
27
|
do not infer its stack from the source skill.
|
|
26
28
|
- `--name <name>`: lowercase letters, digits and dashes, starting with a
|
|
@@ -38,7 +40,7 @@ configuration, including scoped overrides. For infrastructure, prose or other
|
|
|
38
40
|
non-package repositories, inspect their actual files and tooling. A missing
|
|
39
41
|
manifest does not make a source inapplicable.
|
|
40
42
|
|
|
41
|
-
Resolve installed names as `shepherd lens add` does. For a collection,
|
|
43
|
+
Resolve installed names as `shepherd lens add` does: the skills directories of Claude Code, `.agents`, Codex and Cursor, and for `<plugin>:<skill>` the plugin's `skills/` directory, found through `~/.claude/plugins/installed_plugins.json` or `~/.cursor/plugins/`. For a collection,
|
|
42
44
|
enumerate its `SKILL.md` files without following directory symlinks; select
|
|
43
45
|
skills matching the requested target and report the rest as skipped. Keep
|
|
44
46
|
sources separate unless their rules substantially overlap. Work one source
|