@jagreehal/shepherd 0.4.0 → 0.6.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 (47) hide show
  1. package/README.md +9 -1
  2. package/THIRD_PARTY_NOTICES.md +41 -0
  3. package/lenses/dotnet/SKILL.md +32 -0
  4. package/lenses/go/SKILL.md +30 -0
  5. package/lenses/java/SKILL.md +31 -0
  6. package/lenses/nextjs/SKILL.md +33 -0
  7. package/lenses/node-api/SKILL.md +32 -0
  8. package/lenses/nx-monorepo/SKILL.md +30 -0
  9. package/lenses/owasp-asvs/SKILL.md +50 -0
  10. package/lenses/owasp-llm/SKILL.md +44 -0
  11. package/lenses/pstack/SKILL.md +33 -0
  12. package/lenses/python/SKILL.md +32 -0
  13. package/lenses/react/SKILL.md +33 -0
  14. package/lenses/rust/SKILL.md +31 -0
  15. package/package.json +2 -1
  16. package/packs/dotnet.yml +6 -0
  17. package/packs/go.yml +6 -0
  18. package/packs/java.yml +6 -0
  19. package/packs/nextjs.yml +7 -0
  20. package/packs/node-api.yml +7 -0
  21. package/packs/nx-monorepo.yml +6 -0
  22. package/packs/observability.yml +6 -0
  23. package/packs/owasp-asvs.yml +6 -0
  24. package/packs/owasp-llm.yml +8 -0
  25. package/packs/pstack.yml +8 -0
  26. package/packs/python.yml +6 -0
  27. package/packs/react.yml +6 -0
  28. package/packs/rust.yml +6 -0
  29. package/skills/ci-repair/SKILL.md +11 -3
  30. package/skills/lens-import/SKILL.md +187 -0
  31. package/skills/lens-import/references/conversion.md +96 -0
  32. package/skills/lens-import/scripts/check-import.mjs +154 -0
  33. package/skills/shepherd/SKILL.md +32 -9
  34. package/skills/shepherd/references/dispatch.md +7 -4
  35. package/skills/shepherd/references/models.md +20 -7
  36. package/skills/shepherd/references/policy.md +9 -5
  37. package/skills/swarm/SKILL.md +11 -1
  38. package/skills/swarm/references/custom-lenses.md +50 -7
  39. package/skills/triage/SKILL.md +15 -0
  40. package/src/cli.ts +109 -13
  41. package/src/config.ts +137 -21
  42. package/src/doctor.ts +16 -13
  43. package/src/lens.ts +217 -14
  44. package/src/stack.ts +121 -0
  45. package/templates/shepherd-audit.yml +180 -0
  46. package/templates/shepherd-incident.yml +30 -4
  47. package/templates/shepherd.yml +34 -4
package/README.md CHANGED
@@ -22,7 +22,13 @@ shepherd config validate
22
22
  shepherd preview --working-tree
23
23
  ```
24
24
 
25
- The default install targets Claude Code. For another harness, use `shepherd install --target <skills-directory>`. 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`.
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
 
@@ -50,6 +56,8 @@ Replace `42` with your PR number. Expect findings on the PR and a `reviewed` res
50
56
  | Compose checks, modes and recipes | [Configuration reference](docs/src/content/docs/reference/configuration.md) |
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) |
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) |
53
61
  | Select models by role | [Model routing](docs/src/content/docs/configuration/models.md) |
54
62
  | Run without your laptop | [GitHub Actions](docs/src/content/docs/integrations/github-actions.md) |
55
63
  | Get told when a PR needs you | [Notifications](docs/src/content/docs/integrations/notifications.md) |
@@ -39,3 +39,44 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
39
39
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
40
40
  SOFTWARE.
41
41
  ```
42
+
43
+ ## OWASP Secure Agent Playbook
44
+
45
+ These lenses adapt material from the [OWASP Secure Agent Playbook](https://github.com/OWASP/secure-agent-playbook) at commit `65d4efd2cd0b081d52101e9708792b944e4ddebb`. Each rule condenses the source's requirements into one review line, cut to what a diff can show:
46
+
47
+ | Here | Adapted from |
48
+ | --- | --- |
49
+ | `lenses/owasp-asvs/` | `plugins/code-security-skills/skills/security-guidance/` and `plugins/code-security-skills/data/asvs/` (OWASP ASVS 5.0) |
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
+
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
+ ```
@@ -0,0 +1,32 @@
1
+ ---
2
+ name: dotnet
3
+ description: C# and ASP.NET Core rules for a code review. Flags code that deadlocks, leaks, trusts input or loses data in ways the compiler and Roslyn analysers miss. Covers sync-over-async and async void, cancellation tokens not passed, missing authorization on endpoints, unvalidated input and over-posting, raw SQL and commands built from input, unsafe deserialisation, EF Core N+1 and tracking pitfalls, DI lifetime mismatches, HttpClient misuse, disposables not disposed, swallowed exceptions, and API and entity contract changes. Use as a review lens or as a stamp rule pack.
4
+ ---
5
+
6
+ # dotnet
7
+
8
+ ASP.NET Core runs every request on a shared thread pool with services wired
9
+ by lifetime. Review whether this change stays async end to end, carries
10
+ cancellation, gives each service a lifetime that matches its dependencies, and
11
+ checks who is calling before it touches data.
12
+
13
+ ## Review
14
+
15
+ - **sync-over-async**: Async code is awaited all the way up. Flag: `.Result`, `.Wait()` or `.GetAwaiter().GetResult()` on a task in request code, `async void` outside event handlers, a fire-and-forget `Task` with no error handling, `Task.Run` wrapping I/O in a request. Why: thread-pool starvation and deadlocks under load, and exceptions that crash the process.
16
+ - **cancellation**: Endpoints and async methods accept a `CancellationToken` and pass it to I/O (EF Core, `HttpClient`, streams). Flag: a new async method that does I/O with no token, a token accepted and not passed on, `CancellationToken.None` in a request path. Why: abandoned requests keep querying and holding connections.
17
+ - **endpoint-authz** [refuse]: Every new controller action or minimal API endpoint is covered by authorization and checks the caller may act on the resource. Flag: `[AllowAnonymous]` added, a new endpoint group without `RequireAuthorization` where the app has no fallback policy, a handler loading a record by id with no ownership or policy check. Why: the endpoint is public or exposes other users' data.
18
+ - **validate-input**: Request models are validated (data annotations, FluentValidation, or explicit checks) and bound to DTOs, never to EF entities. Flag: an entity used as a request body, missing `ModelState`/validation in a non-`[ApiController]` controller, an over-posted field like `IsAdmin` or `TenantId`. Why: callers set fields the code never meant to expose.
19
+ - **injection** [refuse]: SQL takes input through parameters, commands through `ProcessStartInfo.ArgumentList`, file paths through a containment check. Flag: `FromSqlRaw` or `ExecuteSqlRaw` with interpolated input (use `FromSql`/`FromSqlInterpolated`), string-built `SqlCommand` text, `Path.Combine(root, userInput)` without checking the full path stays under root. Why: injection and path traversal.
20
+ - **unsafe-deserialization** [refuse]: Untrusted data never reaches `BinaryFormatter`, `NetDataContractSerializer`, or polymorphic type handling that names types from the payload. Flag: `TypeNameHandling` other than `None` in Newtonsoft settings for untrusted input, `BinaryFormatter` anywhere, `XmlDocument` with a resolver on untrusted XML. Why: remote code execution.
21
+ - **ef-query-shape**: EF Core queries fetch what the code uses, in a bounded number of round trips. Flag: navigation properties read in a loop (N+1 through lazy loading), `ToList()` before `Where`, a list endpoint with no paging, tracked queries on read-only paths that load many rows, `Include` chains that explode rows. Why: queries multiply and memory grows with the table.
22
+ - **di-lifetime**: Service lifetimes match their dependencies. Flag: a singleton taking a scoped service (DbContext, a per-request service) in its constructor, a `DbContext` held in a static or singleton, a scoped service resolved from the root provider in a background service without `CreateScope`. Why: captive dependencies share a DbContext across threads and corrupt state.
23
+ - **httpclient-use**: Outbound HTTP goes through `IHttpClientFactory` or a long-lived `HttpClient`, with a timeout and resilience policy where the repository uses one. Flag: `new HttpClient()` per call, a client with no timeout calling a slow dependency, retries added on non-idempotent POSTs. Why: socket exhaustion and stale DNS, or duplicated writes.
24
+ - **dispose**: `IDisposable` and `IAsyncDisposable` objects created by the code are disposed with `using`/`await using`. Flag: a stream, `SqlConnection`, `CancellationTokenSource` or timer created and never disposed, a DI-owned service disposed manually. Why: handle and connection leaks under load.
25
+ - **exception-handling**: Exceptions are handled once with their context. Flag: an empty `catch`, `catch (Exception) { return null; }`, `throw ex;` that resets the stack (use `throw;`), logging `ex.Message` without the exception. Why: the cause of the failure is lost.
26
+ - **contract-change**: Changes to entities, DTOs serialised to clients and public types are deliberate and paired with a migration. Flag: a renamed or removed entity property with no EF migration, a changed JSON property name, a public method signature change in a shared library, a new non-nullable column with no default. Why: data or clients break at deploy.
27
+
28
+ ## Fix
29
+
30
+ - Prefer: `async`/`await` end to end with `CancellationToken`, DTO records with validation, `IHttpClientFactory`, `AsNoTracking()` for reads, projections with `Select`, and the repository's existing authorization policies.
31
+ - Never touch: `Program.cs` middleware order and authentication setup beyond the endpoint in the PR, `.csproj` package versions, and existing EF migrations.
32
+ - Escalate: `endpoint-authz` and `contract-change` breaks, new EF migrations, and changes to service lifetimes in shared registration code.
@@ -0,0 +1,30 @@
1
+ ---
2
+ name: go
3
+ description: Go rules for a code review. Flags code that leaks goroutines, races, loses errors or hangs in production in ways go vet and staticcheck do not catch. Covers context not passed or ignored, goroutines with no way to stop, unsynchronised shared state, errors dropped or wrapped without %w, resources not closed, HTTP servers and clients with no timeouts, SQL and commands built from input, panics in library code, nil maps and interfaces holding typed nils, unbounded concurrency, and exported API changes. Use as a review lens or as a stamp rule pack.
4
+ ---
5
+
6
+ # go
7
+
8
+ Go makes concurrency cheap and failure explicit, which makes both easy to get
9
+ quietly wrong. Review whether this change lets every goroutine finish,
10
+ carries cancellation through, keeps every error, and releases what it opens.
11
+
12
+ ## Review
13
+
14
+ - **context-flow**: A function that does I/O or may block takes `ctx context.Context` first and passes it down, and long loops check `ctx.Done()`. Flag: `context.Background()` or `TODO()` inside a request path, a ctx accepted but not passed to the database or HTTP call, a `select` on a channel with no `ctx.Done()` case. Why: cancelled requests keep running and hold connections after the client left.
15
+ - **goroutine-lifetime**: Every goroutine has a way to stop and an owner that waits for it (`errgroup`, `WaitGroup`, a done channel). Flag: `go func()` in a handler with no cancellation, a goroutine blocked forever sending on an unbuffered channel nobody reads, a ticker never stopped. Why: goroutine leaks grow until the process runs out of memory.
16
+ - **data-race**: State shared between goroutines is guarded by a mutex, an atomic, or owned by one goroutine behind a channel. Flag: a map written from more than one goroutine, a struct field updated in a goroutine and read in the caller, a loop variable captured in Go before 1.22 semantics, a `sync.Mutex` copied by value. Why: races corrupt data and crash with `concurrent map writes`, intermittently.
17
+ - **error-handling**: Errors are checked, and wrapped with `%w` and context when returned. Flag: `_ =` or an ignored error from a write, close or commit; `fmt.Errorf("...: %v", err)` where callers use `errors.Is`/`As`; comparing `err.Error()` strings; logging an error and also returning it. Why: failures disappear, or callers can no longer tell which error happened.
18
+ - **resource-close**: Opened files, response bodies, rows, statements and transactions are closed or rolled back on every path, close errors on writes are checked. Flag: `resp.Body` not closed, `rows` not closed or `rows.Err()` unchecked, a transaction with no deferred rollback, `defer f.Close()` on a file written to with the error ignored. Why: connection pools exhaust and writes are lost silently.
19
+ - **http-timeouts**: `http.Server` sets `ReadHeaderTimeout` (and usually read, write and idle timeouts), and `http.Client` has a `Timeout` or per-request context deadline. Flag: `http.ListenAndServe` with the default server, `http.DefaultClient` or `&http.Client{}` for outbound calls. Why: slowloris holds the server, and a hung dependency holds every goroutine.
20
+ - **injection** [refuse]: SQL takes input through placeholders, commands through `exec.Command` argument lists, file paths through a containment check. Flag: `fmt.Sprintf` into a query, `exec.Command("sh", "-c", input)`, `filepath.Join(root, userPath)` with no check that the result stays under root, `template.HTML` from user input. Why: injection and path traversal.
21
+ - **no-library-panic**: Library and request code returns errors instead of panicking, and recovers at goroutine boundaries the program starts. Flag: `panic` on bad input, `log.Fatal` or `os.Exit` outside `main`, a goroutine with no recover in a server where one panic kills the process. Why: one bad request takes the whole service down.
22
+ - **nil-traps**: Writes go to initialised maps, and functions returning an interface return a literal `nil` on success. Flag: writing to a nil map field, `var err *MyErr; return err` as an `error`, dereferencing an optional pointer field without a check. Why: panics in production, and `err != nil` true for a nil pointer.
23
+ - **bounded-concurrency**: Fan-out over input is bounded (`errgroup.SetLimit`, a semaphore, a worker pool). Flag: `for _, x := range items { go work(x) }` over request or database-sized input, an unbounded buffered channel used as a queue. Why: a large input spawns thousands of goroutines and connections at once.
24
+ - **exported-contract**: Changes to exported identifiers, struct fields marshalled to JSON, and error values callers match are deliberate. Flag: a renamed or removed exported function or field, a changed `json:` tag, a sentinel error replaced by a new one, a new required argument on a widely used function. Why: downstream packages and stored data break at the next build or deploy.
25
+
26
+ ## Fix
27
+
28
+ - Prefer: `errgroup` with a context, `fmt.Errorf("doing x: %w", err)`, `defer` close and rollback right after the open succeeds, and the repository's existing HTTP client and database helpers.
29
+ - Never touch: `go.mod` versions, generated code (`*.pb.go`, `*_gen.go`), and vendored packages.
30
+ - Escalate: `exported-contract` breaks, changes to server timeouts or pool sizes, and any switch of concurrency model across a package.
@@ -0,0 +1,31 @@
1
+ ---
2
+ name: java
3
+ description: Java and Spring rules for a code review. Flags code that leaks resources, breaks transactions, trusts input or falls over under load in ways the compiler and static analysers miss. Covers @Transactional pitfalls, N+1 queries and unbounded fetches, missing authorisation on endpoints, unvalidated request bodies, queries and commands built from input, unsafe deserialisation and XML parsing, resources not closed, swallowed exceptions, thread-unsafe shared state in singletons, blocking calls without timeouts, and entity or API contract changes. Use as a review lens or as a stamp rule pack.
4
+ ---
5
+
6
+ # java
7
+
8
+ Spring hides a lot behind annotations, proxies and a thread pool. Review
9
+ whether this change gets the transaction, security and lifecycle behaviour it
10
+ assumes, keeps singleton beans free of request state, and bounds the work a
11
+ single request can cause.
12
+
13
+ ## Review
14
+
15
+ - **transaction-boundary**: `@Transactional` sits on a public method called through the Spring proxy, with the propagation, read-only flag and rollback rules the code needs. Flag: `@Transactional` on a private method or a method called from the same class (self-invocation skips the proxy), a checked exception that should roll back but does not (`rollbackFor` missing), a remote call or message publish inside a long transaction, a read path writing in a `readOnly` transaction. Why: data is committed half-done, or not at all, with no error.
16
+ - **query-shape**: Repository calls fetch what the code uses, in a bounded number of queries. Flag: a lazy association accessed in a loop (N+1), `findAll()` on a table that grows, a list endpoint with no `Pageable` or limit, `FetchType.EAGER` added to an entity. Why: a page that ran 3 queries in test runs 3,000 in production.
17
+ - **endpoint-authz** [refuse]: Every new controller method is covered by the security configuration and checks the caller may act on the resource. Flag: a new path not matched by the `SecurityFilterChain` rules, `permitAll` widened, a method taking an id with no ownership or role check (`@PreAuthorize` or an explicit check), CSRF disabled for a cookie-authenticated app. Why: the endpoint is public or lets users act on each other's data.
18
+ - **validate-input**: Request bodies and parameters are validated at the controller (`@Valid` with constraints) and bound to DTOs, never to entities. Flag: a `@RequestBody` entity, a DTO with no `@Valid`, mass assignment of fields like `role` or `id`. Why: callers set fields the code never meant to expose.
19
+ - **injection** [refuse]: Queries take input through bind parameters, commands through `ProcessBuilder` argument lists, file paths through a containment check. Flag: string concatenation into JPQL, SQL, `@Query(nativeQuery=true)` or `JdbcTemplate`; `Runtime.exec` with a built string; SpEL or OGNL evaluated over input; `Paths.get(base, userInput)` without normalising and checking the prefix. Why: injection and path traversal.
20
+ - **unsafe-parsing** [refuse]: Untrusted data is never handed to Java serialisation, and XML parsers disable external entities. Flag: `ObjectInputStream.readObject` on network or user data, Jackson default typing (`enableDefaultTyping`, `@JsonTypeInfo(use = CLASS)`) on untrusted input, a `DocumentBuilderFactory` or `XMLInputFactory` without XXE protection. Why: remote code execution and file disclosure.
21
+ - **resource-close**: Streams, connections, readers, clients and executors are closed with try-with-resources or a lifecycle hook. Flag: a `Connection`, `InputStream` or `HttpClient` response not closed on every path, an `ExecutorService` created per request and never shut down. Why: pools and file handles exhaust under load.
22
+ - **exception-handling**: Exceptions are handled once, with their cause, and never swallowed. Flag: an empty `catch`, `catch (Exception e) { log.error(e.getMessage()); }` that drops the stack, `throw new RuntimeException("failed")` without the cause, catching `InterruptedException` without restoring the interrupt flag. Why: the failure leaves no trail, or a thread pool cannot shut down.
23
+ - **singleton-state**: Singleton beans (the Spring default) hold no request or user state in fields, and shared mutable state is thread-safe. Flag: a non-final field set per request in a `@Service` or `@Controller`, a `HashMap` or `SimpleDateFormat` shared across threads, a static mutable cache with no bound or eviction. Why: requests see each other's data under concurrency.
24
+ - **blocking-timeouts**: Outbound HTTP, database and messaging calls set connect and read timeouts, and blocking calls stay off reactive or event-loop threads. Flag: a `RestTemplate`, `WebClient`, `HttpClient` or JDBC pool with default (infinite) timeouts, `.block()` inside a WebFlux handler, `@Async` with the default unbounded executor. Why: one slow dependency exhausts the thread pool.
25
+ - **contract-change**: Changes to entity mappings, DTOs serialised to clients, and public interfaces are deliberate and paired with a migration. Flag: a renamed or removed entity field with no migration, a changed `@Column` or `@Table`, a JSON field renamed, an enum persisted as `ORDINAL` that gains a value in the middle. Why: existing data or clients break at deploy.
26
+
27
+ ## Fix
28
+
29
+ - Prefer: constructor injection, DTOs with Bean Validation, Spring Data pagination and fetch joins or entity graphs, try-with-resources, and the repository's configured HTTP client beans.
30
+ - Never touch: the security configuration beyond the endpoint in the PR, build files (`pom.xml`, `build.gradle`), and generated sources.
31
+ - Escalate: `endpoint-authz` and `contract-change` breaks, changes to transaction propagation on shared services, and any database migration.
@@ -0,0 +1,33 @@
1
+ ---
2
+ name: nextjs
3
+ description: Next.js rules for a code review, meant to be composed with the react lens. Flags App Router and Pages Router code that leaks data across the server/client boundary, skips authorisation, caches the wrong thing or ships too much to the browser. Covers route handlers and server actions without auth, middleware matchers that miss routes, server-only code reaching the client, props that serialise secrets, user data cached across users, dynamic APIs that break static rendering, redirects built from input, unvalidated action input, heavy client bundles, and metadata or image misuse. Use as a review lens or as a stamp rule pack.
4
+ ---
5
+
6
+ # nextjs
7
+
8
+ Next.js decides per file where code runs and what gets cached. Review whether
9
+ this change keeps secrets and per-user data on the server, checks who is
10
+ asking at every entry point, and caches only what is the same for everyone.
11
+ React component rules belong to the react lens; this one covers what the
12
+ framework adds.
13
+
14
+ ## Review
15
+
16
+ - **handler-auth** [refuse]: Every route handler (`app/**/route.ts`, `pages/api/**`) and every server action checks authentication and authorisation itself, for the resource it touches. Flag: a handler or action that reads or writes data with no session check, an ownership check missing on an id from the request, reliance on a page-level check that the endpoint does not repeat. Why: server actions and API routes are public HTTP endpoints anyone can call directly.
17
+ - **middleware-matcher**: Middleware that enforces auth or headers covers every route it means to. Flag: a `matcher` that excludes `/api`, a negative lookahead that also skips a new protected segment, a new route outside the matcher, auth enforced only in middleware with no check in the handler. Why: the protected route is reachable by skipping the matcher.
18
+ - **server-only-boundary**: Modules that read secrets, the database or server env are marked `import "server-only"` (or live where client code cannot import them), and `"use client"` files import none of them. Flag: a database client, ORM model or secret-reading helper imported from a client component, a `"use client"` added to a file that imports server code. Why: the build bundles it for the browser or fails late in production.
19
+ - **serialised-props** [refuse]: Data passed from a server component to a client component, or returned from `getServerSideProps`/`getStaticProps`, holds only what the client may see. Flag: a whole user or database row passed as a prop, password hashes, tokens or internal fields in props, a server action returning more than the caller needs. Why: every prop is serialised into the HTML payload, readable in view-source.
20
+ - **per-user-cache**: Responses and data that depend on the user, cookies or headers are not cached for everyone. Flag: `fetch` with `force-cache` or `revalidate` on a per-user request, `unstable_cache`/`"use cache"` wrapping a function that reads the session without the user in its key, a route segment marked static that reads cookies. Why: one user's data is served to the next.
21
+ - **stale-after-mutation**: A server action or route handler that changes data revalidates what shows it (`revalidatePath`, `revalidateTag`, `router.refresh()`). Flag: a mutation with no revalidation of cached pages or tags that list the changed data. Why: users see the old value after saving and retry.
22
+ - **action-input**: Server action and route handler input is parsed and validated at the boundary before use. Flag: `formData.get(...)` cast straight to a type, a JSON body spread into a database call, a search param used as a number without parsing. Why: anyone can post any shape to the endpoint.
23
+ - **open-redirect**: `redirect()`, `NextResponse.redirect` and `router.push` with a URL from the request go only to same-origin paths or an allow-list. Flag: `redirect(searchParams.get("next"))`, a `callbackUrl` passed through unchecked. Why: phishing through a trusted domain.
24
+ - **public-env** [refuse]: `NEXT_PUBLIC_*` variables hold only values safe to publish. Flag: a key, token, internal URL or credential under a `NEXT_PUBLIC_` name, a server secret renamed to `NEXT_PUBLIC_` to make a client component work. Why: Next.js inlines every `NEXT_PUBLIC_` value into the client bundle.
25
+ - **dynamic-api-placement**: `cookies()`, `headers()`, `searchParams` and `noStore` are read only in the segments that need them. Flag: a dynamic API added to a layout or a shared component that makes every page under it dynamic, a static marketing page turned dynamic by a helper call. Why: the whole subtree loses static rendering and caching, and latency jumps.
26
+ - **client-bundle-weight**: Large or browser-only dependencies (editors, charts, maps, PDF, date libraries with locales) load with `next/dynamic` or in a server component. Flag: a heavy library imported at the top of a client component on a common route, `"use client"` added high in the tree so a whole page becomes client code. Why: every visitor downloads and parses it on first load.
27
+ - **framework-primitives**: Pages use `next/image` with dimensions or `fill` and sizes, `next/link` for internal navigation, and `generateMetadata`/`metadata` for titles. Flag: a raw `<img>` for content images without dimensions, `<a href>` for internal routes in a client app, `remotePatterns` widened to `**`. Why: layout shift, full reloads, and an image optimiser anyone can use as a proxy.
28
+
29
+ ## Fix
30
+
31
+ - Prefer: the repository's existing auth helper (`auth()`, `getServerSession`, its own wrapper) at the top of each handler or action, its validation schemas, `server-only` imports, and narrowing props to a view type.
32
+ - Never touch: `next.config.*`, middleware matchers beyond the route in the PR, caching defaults for the whole app, or the auth provider setup.
33
+ - Escalate: any `handler-auth`, `serialised-props` or `public-env` break that changes who can see data in production, changing a matcher, and moving a large subtree between server and client.
@@ -0,0 +1,32 @@
1
+ ---
2
+ name: node-api
3
+ description: Node.js HTTP service rules for a code review (Express, Fastify, Hono, Koa, NestJS). Flags handlers that skip auth, trust input, leak errors, hang or lose work. Covers middleware mount order, per-resource authorisation, unvalidated bodies and params, queries and commands built from input, error responses that leak internals, async errors that escape the handler, missing timeouts on outbound calls, unbounded bodies and lists, idempotency on retried writes, blocking the event loop, untyped request augmentation and unsafe CORS. Use as a review lens or as a stamp rule pack.
4
+ ---
5
+
6
+ # node-api
7
+
8
+ An HTTP handler is a public function anyone on the network can call with any
9
+ input, at any rate. Review whether this change checks who is calling, rejects
10
+ input it cannot handle, answers without leaking how it works, and never leaves
11
+ the process hung or the data half-written.
12
+
13
+ ## Review
14
+
15
+ - **mount-order** [refuse]: Auth, rate-limit and body-size middleware are registered before the routes they protect. Flag: a new router mounted above `app.use(auth)`, a route registered in a plugin that Fastify encapsulates outside the auth hook, an error handler mounted before the routes. Why: Express and friends run middleware in registration order, so the route is public.
16
+ - **resource-authz** [refuse]: A handler that reads or changes a resource by id checks the caller may act on that resource, not only that they are signed in. Flag: `findById(req.params.id)` returned or updated with no owner, tenant or role check; an admin action guarded only by authentication. Why: any signed-in user can read or change anyone's data (IDOR).
17
+ - **validate-input**: Body, params, query and headers are parsed with a schema at the boundary, and the handler uses the parsed value. Flag: `req.body` spread into a database write, `Number(req.query.limit)` with no bounds, a schema parsed but the raw body used afterwards, mass assignment of fields like `role` or `isAdmin`. Why: callers send shapes the code never expected.
18
+ - **injection** [refuse]: Queries, shell commands, file paths and URLs take input only through parameters, argument arrays and validated values. Flag: SQL or NoSQL query strings built with template literals, `exec` with interpolated input, `path.join(base, req.params.file)` with no containment check, a server-side fetch to a URL from the request. Why: injection, path traversal and SSRF.
19
+ - **error-leak**: Error responses carry a stable code and message, never stack traces, SQL, internal hostnames or the raw error object. Flag: `res.status(500).json(err)`, `res.send(err.message)` for unexpected errors, a framework's dev error page enabled by default. Why: attackers map the system from it, and clients come to depend on internal text.
20
+ - **async-error-path**: Every async handler's rejection reaches the framework's error handler. Flag: an `async` Express 4 handler with no wrapper or `next(err)`, a promise started in a handler and not awaited, `.catch(() => {})` that answers 200. Why: an unhandled rejection hangs the request or crashes the process.
21
+ - **outbound-timeout**: Calls to databases, HTTP services and queues set a timeout and handle its failure. Flag: `fetch` with no `signal`/`AbortSignal.timeout`, an HTTP client with no timeout, a database pool with no acquire or statement timeout, a retry loop with no limit or backoff. Why: one slow dependency holds every request open until the service falls over.
22
+ - **bounded-work**: Request bodies, uploads, list endpoints and batch inputs have limits. Flag: a JSON or raw body parser with no size limit, a list endpoint with no pagination or max page size, a batch endpoint that loops over unbounded input, a regex from or over user input that can backtrack. Why: one request can exhaust memory or CPU for everyone.
23
+ - **idempotent-writes**: A write the client or a queue can retry (payments, orders, emails, webhooks) is safe to repeat: an idempotency key, a unique constraint, or a check-and-insert in one transaction. Flag: a webhook handler that does work before checking it has seen the event, a POST that creates a duplicate on retry. Why: retries are normal, so duplicates reach production.
24
+ - **event-loop-block**: Request handlers do no synchronous heavy work. Flag: `fs.readFileSync`, `execSync`, `crypto.pbkdf2Sync`, large `JSON.parse` or sorting of unbounded data inside a handler. Why: every concurrent request waits behind it.
25
+ - **typed-request-context**: Data attached to the request (`req.user`, tenant, request id) is declared through the framework's typing (module augmentation, Fastify decorators, Hono variables) and read from that one place. Flag: `(req as any).user`, a second ad-hoc property for the same thing, reading a user from a header after auth already set it. Why: a renamed field type-checks and the auth check quietly reads `undefined`.
26
+ - **cors-credentials**: CORS allows only known origins when credentials are allowed. Flag: `origin: true` or reflecting `req.headers.origin` with `credentials: true`, `*` added to an authenticated API. Why: any site can make authenticated calls as the visitor.
27
+
28
+ ## Fix
29
+
30
+ - Prefer: the repository's existing validation schemas, auth middleware, error handler and HTTP client wrapper; parameterised queries through its database layer; `AbortSignal.timeout`.
31
+ - Never touch: the server entry file's middleware order beyond the route in the PR, global error handling, CORS and rate-limit configuration.
32
+ - Escalate: `mount-order`, `resource-authz` and `cors-credentials` breaks, since they change who can call the service; changing a response's error shape that clients read; adding a new dependency.
@@ -0,0 +1,30 @@
1
+ ---
2
+ name: nx-monorepo
3
+ description: Nx monorepo rules for a code review. Flags changes that break project boundaries or quietly switch off what keeps a monorepo honest. Covers deep imports past a project's public entry, circular project dependencies, shared contracts changed without their dependents, app code in shared libs, targets, inputs, outputs and cache settings that stop affected and caching from covering code, loosened tags and dependency constraints, path aliases that bypass boundaries, untagged projects, implicit dependency workarounds, environment and secrets in shared libs, and version drift between projects. Use as a review lens or as a stamp rule pack.
4
+ ---
5
+
6
+ # nx-monorepo
7
+
8
+ A monorepo holds together because of its boundaries and its build graph.
9
+ Review whether this change keeps each project behind its public entry, keeps
10
+ the graph acyclic and accurate, and leaves the rules that enforce both intact.
11
+
12
+ ## Review
13
+
14
+ - **public-entry**: Code imports another project only through its published entry (`@org/lib`, its `index.ts`). Flag: an import reaching into `libs/x/src/lib/...`, a relative path climbing into another project, a re-export of internals to get around the entry. Why: internals become a contract nobody agreed to, and refactors break distant apps.
15
+ - **no-cycles**: A new import keeps the project graph acyclic. Flag: lib A importing lib B when B already imports A, directly or through a third project; a cycle papered over with a lazy `import()`. Why: cycles break build order, caching and affected detection.
16
+ - **shared-contract**: A change to a shared lib's exported types, functions or behaviour updates every dependent in the same PR, or keeps the old shape. Flag: a renamed or removed export, a changed signature or return shape, with dependents untouched in the diff. Why: other apps break at their next build or, worse, at runtime.
17
+ - **lib-purity**: Shared libs hold code more than one app uses, with no app-specific logic. Flag: an app's route, feature flag, copy or business rule added to a shared or `util` lib; a shared lib importing from an app. Why: every app now carries and couples to one app's behaviour.
18
+ - **boundary-rules** [refuse]: Module boundary enforcement stays on and as strict as it was. Flag: `@nx/enforce-module-boundaries` disabled or downgraded, `depConstraints` widened (`onlyDependOnLibsWithTags: ['*']`), a project's tags changed to escape a constraint, an `eslint-disable` for the boundary rule. Why: the one check that keeps the architecture is gone, and nothing says so.
19
+ - **graph-accuracy**: Targets, `inputs`, `outputs`, `namedInputs` and cache settings in `project.json` or `nx.json` still cover every file that affects the result. Flag: inputs narrowed so a source, config or env change no longer invalidates the cache, outputs missing a build directory, `cache: false` or `parallel` changed with no reason, a target removed that CI's `nx affected` runs. Why: affected skips tests that should run, and caches serve stale builds.
20
+ - **alias-bypass**: `tsconfig` path aliases map to a project's public entry only. Flag: a new path mapping to a file deep inside another project, a wildcard alias (`@org/*`) to `libs/*/src/*`, an alias that duplicates a project under a second name. Why: aliases sidestep the boundary rule and the graph alike.
21
+ - **project-tags**: A new project declares its type and scope tags, and sits where its kind belongs. Flag: a new `project.json` with no `tags`, an app created under `libs/` or a lib under `apps/`. Why: untagged projects match no constraint, so boundaries do not apply to them.
22
+ - **implicit-dependencies**: Dependencies come from real imports. Flag: `implicitDependencies` added to force build order or to hide a missing import, `"*"` implicit dependencies, a target `dependsOn` reaching into an unrelated project. Why: the graph stops matching the code, and affected runs too much or too little.
23
+ - **lib-config**: Shared libs read configuration passed in by the app, never environment variables or secrets of their own. Flag: `process.env` read inside a shared lib, a hard-coded URL, key or tenant id in a lib, a `.env` added to a lib. Why: every app inherits one app's settings, and secrets spread across deployables.
24
+ - **version-drift**: Each dependency has one version across the workspace. Flag: a project `package.json` pinning a different version of a library the root already provides, a second copy of a framework or React, a new dependency added to a project instead of the root where the workspace keeps them. Why: duplicate copies break singletons and bloat bundles.
25
+
26
+ ## Fix
27
+
28
+ - Prefer: exporting what a consumer needs from the lib's `index.ts`, moving shared code into a lib with the right tags, passing configuration in from the app, and the repository's Nx generators for new projects.
29
+ - Never touch: `nx.json` cache and task-runner settings, `depConstraints`, CI's affected commands, and generated files.
30
+ - Escalate: `boundary-rules`, `graph-accuracy` and `shared-contract` breaks, splitting or merging projects, and any new cross-project dependency the tags do not already allow.
@@ -0,0 +1,50 @@
1
+ ---
2
+ name: owasp-asvs
3
+ description: >
4
+ OWASP ASVS 5.0 rules for a code review, in any language or framework. Flags
5
+ changes that break an ASVS requirement a diff can show: injection, output
6
+ encoding, SSRF, unsafe parsing, server-side validation and mass assignment,
7
+ business-flow atomicity, rate limits, file uploads and paths, cookies,
8
+ sessions, token validation, authorization at function, object and field level,
9
+ password storage, account enumeration, cryptography, secrets and transport,
10
+ data exposure, error leakage and fail-open handling, and security event
11
+ logging. Each finding cites the ASVS requirement and CWE. Use as a review lens
12
+ or as a stamp rule pack.
13
+ source: github:OWASP/secure-agent-playbook/plugins/code-security-skills/skills/security-guidance@65d4efd2cd0b081d52101e9708792b944e4ddebb
14
+ license: CC-BY-4.0
15
+ ---
16
+
17
+ # owasp-asvs
18
+
19
+ Review the change against the OWASP Application Security Verification Standard
20
+ 5.0, whatever the stack. Each rule names the requirements it checks, so a
21
+ finding reads as a traceable ASVS gap. Cite the requirement id with the rule id.
22
+ The full requirement text lives in the source under `data/asvs/V<chapter>.md`.
23
+
24
+ ## Review
25
+
26
+ - **injection** [refuse]: Untrusted data reaches a query, shell, LDAP, XPath, template or evaluator only as a bound parameter. Flag: a query or command built by concatenation, eval or SpEL on input, a template compiled from input. Why: injection. (ASVS 1.2.4, 1.2.5, 1.3.2, 1.3.7, CWE-74)
27
+ - **output-encoding**: Output is encoded for its context (HTML, attribute, JS or JSON, URL, header), and a URL from input allows only http(s). Flag: input concatenated into markup or script, a `javascript:` link. Why: XSS. (ASVS 1.2.1-1.2.3, CWE-79)
28
+ - **ssrf** [refuse]: A server-side request to a URL or host from input checks scheme, host and port against an allowlist and follows no redirect. Flag: fetching a user-supplied URL. Why: internal services and cloud metadata exposed. (ASVS 1.3.6, 15.3.2, CWE-918)
29
+ - **unsafe-parsing** [refuse]: XML parsers disable external entities, and untrusted data deserializes into allowlisted types or plain data. Flag: default XML parser settings, native object deserialization of request data. Why: XXE and code execution. (ASVS 1.5.1, 1.5.2, CWE-611, CWE-502)
30
+ - **server-validation**: The server validates input against allowlists and ranges and binds only permitted fields. Flag: a check enforced only in the client, a request body bound whole to a model. Why: tampering and mass assignment. (ASVS 2.2.1, 2.2.2, 15.3.3, CWE-20, CWE-915)
31
+ - **atomic-flow**: Multi-step flows enforce their order, a business operation commits or rolls back whole, and a check and the action it guards run atomically. Flag: a skippable step, writes outside a transaction, check-then-act on stock or balance. Why: double spends. (ASVS 2.3.1, 2.3.3, 2.3.4, 15.4.2, CWE-367)
32
+ - **rate-limit**: Login, reset, signup, messaging and costly endpoints carry anti-automation limits. Flag: a new such endpoint with no limit. Why: brute force and quota drain. (ASVS 2.4.1, 6.3.1, CWE-307, CWE-770)
33
+ - **file-handling** [refuse]: Uploads cap size, check extension and content, and paths come from internal ids or stay under a fixed root; archives cap size and entry count and ignore entry paths. Flag: a user filename in a path. Why: traversal and zip slip. (ASVS 5.2.1-5.2.3, 5.3.2, 5.3.3, CWE-22, CWE-434)
34
+ - **cookie-flags**: Session cookies set Secure, HttpOnly and SameSite, with a `__Host-` prefix when not shared. Flag: a session cookie missing a flag. Why: theft and CSRF. (ASVS 3.3.1, 3.3.2, 3.3.4, CWE-614)
35
+ - **session-lifecycle**: Login issues a new session token from a CSPRNG, and logout or account disable invalidates it on the server. Flag: a reused session id, a logout that only clears the cookie. Why: fixation and replay. (ASVS 7.2.3, 7.2.4, 7.4.1, 7.4.2, CWE-384, CWE-613)
36
+ - **token-validation** [refuse]: Self-contained tokens verify their signature with an allowlisted algorithm and a preconfigured key, then `exp`, `nbf`, audience and type. Flag: decode without verify, `alg: none`, a key URL from the token. Why: forged identity. (ASVS 9.1.1-9.1.3, 9.2.1-9.2.3, CWE-347)
37
+ - **access-control** [refuse]: The server checks the caller's permission for each function, object and field it reads or writes. Flag: a new route or query with no check, a lookup by id without an owner filter. Why: IDOR and privilege escalation. (ASVS 8.2.1-8.2.3, 8.3.1, CWE-639, CWE-862)
38
+ - **password-storage** [refuse]: Passwords hash with argon2id, scrypt, bcrypt or PBKDF2 and verify exactly as typed, with 64+ characters allowed. Flag: a fast hash, truncation or lower-casing. Why: offline cracking. (ASVS 11.4.2, 6.2.8, 6.2.9, CWE-916)
39
+ - **account-enumeration**: Login, signup and reset answer the same for known and unknown accounts. Flag: "user not found", a different status code or timing. Why: account discovery. (ASVS 6.3.8, CWE-204)
40
+ - **approved-crypto**: Encryption uses authenticated modes with unique nonces, hashing avoids MD5 and SHA-1, secrets and ids come from a CSPRNG. Flag: ECB, a fixed IV, `Math.random` for a token. Why: broken confidentiality. (ASVS 11.3.1-11.3.4, 11.4.1, 11.5.1, CWE-327, CWE-338)
41
+ - **secret-transport**: Secrets come from a secret store, never code or URLs, and outbound calls use verified TLS. Flag: a key literal, a token in a query string, verification off. Why: leaks. (ASVS 13.3.1, 14.2.1, 12.2.1, CWE-798, CWE-319)
42
+ - **data-minimisation**: Responses return only needed fields, and sensitive data skips trackers and shared caches. Flag: a whole record serialized to the client. Why: exposure. (ASVS 15.3.1, 14.2.2, 14.2.3, CWE-200)
43
+ - **fail-closed**: Clients get generic errors, and an exception in validation or authorization denies. Flag: a stack trace or query in a response, a catch that proceeds. Why: leakage and fail-open. (ASVS 16.5.1, 16.5.3, 13.4.2, CWE-209, CWE-636)
44
+ - **security-events**: Authentication outcomes and authorization failures are logged with who and what, without secrets. Flag: a new auth path with no log. Why: attacks go unseen. (ASVS 16.3.1-16.3.3, CWE-778)
45
+
46
+ ## Fix
47
+
48
+ - Prefer: the framework's parameterized queries, encoders, session, token and password-hashing APIs, and the repository's existing authorization helper.
49
+ - Never touch: cryptographic keys, secret stores, identity provider configuration.
50
+ - Escalate: `access-control`, `token-validation`, `password-storage`, `session-lifecycle` and `approved-crypto` changes that alter an existing contract, and any new dependency.
@@ -0,0 +1,44 @@
1
+ ---
2
+ name: owasp-llm
3
+ description: >
4
+ OWASP LLM Top 10 (2025) and Agentic Top 10 (2026) rules for a code review of
5
+ code that calls a model, runs an agent or serves MCP tools, in any language.
6
+ Flags untrusted content mixed into instructions, model output used as code,
7
+ SQL, HTML or a command, tools with more power than their job, destructive
8
+ actions without a person's approval, secrets and personal data in prompts,
9
+ poisoned retrieval and memory, unbounded tokens and loops, MCP servers without
10
+ auth or scoped tools, unpinned models and tools, agent-to-agent trust, and
11
+ answers presented as fact without grounding. Each finding cites the LLM or ASI
12
+ id. Use as a review lens or as a stamp rule pack.
13
+ source: github:OWASP/secure-agent-playbook/plugins/ai-security-skills@65d4efd2cd0b081d52101e9708792b944e4ddebb
14
+ license: CC-BY-4.0
15
+ ---
16
+
17
+ # owasp-llm
18
+
19
+ Review a change to code that builds prompts, calls a model, runs an agent loop,
20
+ defines tools or serves an MCP server. Treat everything the model reads as
21
+ attacker-controlled once any untrusted text reaches it, and everything the
22
+ model writes as untrusted input. Cite the OWASP id with the rule id.
23
+
24
+ ## Review
25
+
26
+ - **instruction-boundary**: Untrusted text (user input, documents, web pages, emails, tool results) enters the prompt fenced as data, apart from system instructions. Flag: user or retrieved text concatenated into the system prompt, tool output fed back with no boundary. Why: prompt injection and goal hijack. (LLM01, ASI01)
27
+ - **output-as-input** [refuse]: Model output passes through the same validation, encoding and parameterization as user input before it reaches a shell, interpreter, query, HTML, file path or URL. Flag: `eval` or `exec` of generated code outside a sandbox, generated SQL run as is, model text rendered as raw HTML or Markdown with images. Why: injection and code execution. (LLM05, ASI05)
28
+ - **least-agency** [refuse]: Each tool does one narrow job with typed, constrained parameters and runs with the caller's permissions. Flag: a tool taking a free-form shell command, SQL, path or URL, a tool with a service account broader than the user's. Why: one injected instruction gains everything the tool can do. (LLM06, ASI02, ASI03)
29
+ - **human-approval**: Destructive, financial, external-send or permission-changing tool calls wait for a person's confirmation the model cannot supply. Flag: delete, pay, email or deploy executed straight from a model decision. Why: an injected goal acts unchecked. (LLM06, ASI09)
30
+ - **prompt-secrets**: Prompts, tool descriptions and system messages hold no keys, credentials, internal URLs or personal data beyond what the task needs. Flag: an API key or connection string in a prompt, a whole customer record sent to a model. Why: leakage and system prompt extraction. (LLM02, LLM07)
31
+ - **retrieval-scope**: Retrieval and vector queries filter by the caller's permissions, and ingested documents come from a known source. Flag: a vector search with no tenant or ACL filter, user uploads indexed into a shared store. Why: data leaks across users and poisoned context. (LLM04, LLM08)
32
+ - **memory-integrity**: Persistent agent memory records its source, stays scoped per user or session, and holds no instructions written by untrusted input. Flag: model output written to shared memory, memory replayed into later sessions as trusted. Why: one poisoned turn steers future runs. (ASI06)
33
+ - **bounded-consumption**: Model calls set max tokens and a timeout, agent loops cap steps and tool calls, and per-user rate or budget limits apply. Flag: a loop until the model says done, no `max_tokens`, user-chosen context size. Why: cost and denial of service. (LLM10, ASI08)
34
+ - **mcp-auth** [refuse]: An MCP server on HTTP or SSE authenticates clients, validates Origin, uses TLS and restricts CORS, and its tools reach only the paths and hosts they need. Flag: a network transport with no auth, a file tool with no root, a fetch tool that can reach internal addresses. Why: anyone on the network drives the tools. (LLM06, ASI02)
35
+ - **tool-description**: Tool names, descriptions and schemas state exactly what the tool does and carry no instructions to the model. Flag: a description broader or narrower than the code, imperative text aimed at the model. Why: tool poisoning and misuse. (LLM01, ASI02)
36
+ - **pinned-supply**: Models, MCP servers, tools and prompt packages are pinned to a version or digest from a trusted source, and the client passes each server only the env vars it needs. Flag: `latest`, a server launched through `npx` unpinned, the whole environment passed to a server. Why: a swapped component takes over the agent. (LLM03, ASI04)
37
+ - **agent-trust**: Messages between agents are authenticated and validated like external input, and one agent's failure stops the chain. Flag: an agent acting on another's output as instructions, retries that loop between agents. Why: cascading compromise. (ASI07, ASI08, ASI10)
38
+ - **grounded-output**: Factual answers that drive decisions cite retrieved sources or say they are unverified, and code acting on them checks the result. Flag: generated values stored as fact, an answer shown with no source. Why: misinformation users trust. (LLM09, ASI09)
39
+
40
+ ## Fix
41
+
42
+ - Prefer: the SDK's structured messages and tool schemas, enums over free text, the repository's existing validation, sandbox and auth helpers.
43
+ - Never touch: model provider keys, system prompts owned by another team, MCP client configuration outside the change.
44
+ - Escalate: `least-agency`, `human-approval` and `mcp-auth` changes that remove a control, new tools with write or network reach, and switching model providers.
@@ -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.
@@ -0,0 +1,32 @@
1
+ ---
2
+ name: python
3
+ description: Python rules for a code review (services, workers, Django, FastAPI, Flask). Flags code that trusts input, loses errors, blocks or misbehaves under load in ways ruff and mypy miss. Covers queries and commands built from input, unsafe deserialisation, missing authorization on views, unvalidated input, swallowed exceptions, blocking calls in async code, outbound calls with no timeout, mutable defaults and module state shared across requests, ORM N+1 and unbounded queries, transactions that commit half the work, naive datetimes, and API and model contract changes. Use as a review lens or as a stamp rule pack.
4
+ ---
5
+
6
+ # python
7
+
8
+ Python lets almost anything run, so the defects show up in production rather
9
+ than at build time. Review whether this change keeps input away from
10
+ interpreters, keeps errors visible, stays non-blocking where it is async, and
11
+ keeps state from leaking between requests.
12
+
13
+ ## Review
14
+
15
+ - **injection** [refuse]: SQL takes input through parameters, commands through argument lists, file paths through a containment check. Flag: f-strings or `%` into `cursor.execute`, `text()` or `.raw()`/`.extra()`; `subprocess` with `shell=True` and input; `os.system`; `open(os.path.join(root, user_path))` with no check that the resolved path stays under root; `eval`/`exec` on input. Why: injection and path traversal.
16
+ - **unsafe-deserialization** [refuse]: Untrusted data never reaches `pickle`, `marshal`, `shelve`, `yaml.load` without `SafeLoader`, or `torch.load` without `weights_only=True`. Flag: unpickling a request body, cache value or uploaded file; `yaml.load(data)`. Why: remote code execution.
17
+ - **view-authz** [refuse]: Every new view, route or endpoint checks authentication and the caller's right to the resource. Flag: a Django view without `login_required`/permission classes where neighbours have them, a FastAPI route without the auth dependency, a lookup by id with no owner or tenant filter. Why: the endpoint is public or exposes other users' data.
18
+ - **validate-input**: Request data is parsed with the framework's schema (Pydantic, DRF serializers, Django forms) before use, and only declared fields are written. Flag: `request.json`/`request.POST` passed straight to a model constructor or `update(**data)`, a serializer with `fields = "__all__"` on a write path. Why: callers set fields like `is_staff` or `tenant_id`.
19
+ - **exception-handling**: Exceptions are caught narrowly, keep their cause, and are logged once with the traceback. Flag: bare `except:` or `except Exception: pass`, `raise NewError(...)` inside `except` without `from err`, `logger.error(str(e))` without `exc_info`, a broad catch that returns a default and hides a failure. Why: the cause of the incident is lost, or a real error becomes wrong data.
20
+ - **async-blocking**: `async def` code never makes blocking calls. Flag: `requests`, `time.sleep`, synchronous database drivers, file I/O or CPU-heavy work inside an `async def` view or task without `run_in_executor`/`to_thread`; a sync ORM call from async Django without `sync_to_async`. Why: one call stalls the event loop for every request.
21
+ - **outbound-timeout**: HTTP, database and queue calls set timeouts, and retries are bounded with backoff. Flag: `requests.get(url)` with no `timeout`, an `httpx` client with timeouts disabled, `while True` retry loops. Why: requests hang indefinitely and exhaust workers.
22
+ - **shared-state**: Nothing request-specific lives in mutable defaults, module globals or class attributes. Flag: `def f(items=[])` or `={}`, a module-level dict used as a cache with no bound or lock, request data stored on a class attribute or a global client mutated per request. Why: data leaks between calls and requests, and memory grows.
23
+ - **orm-query-shape**: ORM access fetches what the code uses in a bounded number of queries. Flag: related objects accessed in a loop without `select_related`/`prefetch_related`/`selectinload`, `.all()` on a growing table in a request, a list endpoint with no pagination, `len(queryset)` instead of `.count()`. Why: N+1 queries and memory that grows with the table.
24
+ - **transaction-scope**: Multi-step writes that must succeed together run in one transaction, and side effects (emails, tasks, webhooks) fire after commit. Flag: two related writes outside `transaction.atomic()`/a session transaction, a Celery task enqueued inside a transaction that might roll back (use `on_commit`). Why: half-written data, or a task that runs against a row that does not exist.
25
+ - **datetime-aware**: Datetimes are timezone-aware and in UTC at boundaries. Flag: `datetime.now()` or `utcnow()` for stored or compared times, comparing naive and aware values, parsing timestamps without a zone. Why: off-by-hours bugs around DST and across servers, or a `TypeError` at runtime.
26
+ - **contract-change**: Changes to models, serialised response shapes and public functions are deliberate and paired with a migration. Flag: a renamed or removed model field with no migration, a new non-null column with no default, a changed response key, a removed keyword argument in a shared module. Why: data or clients break at deploy.
27
+
28
+ ## Fix
29
+
30
+ - Prefer: parameterised queries through the ORM or driver, the framework's schema and permission classes, `logger.exception`, `raise ... from err`, `httpx`/`requests` with explicit timeouts, and `transaction.on_commit`.
31
+ - Never touch: dependency pins (`pyproject.toml`, `requirements*.txt`, lockfiles), existing migrations, and settings modules beyond the change.
32
+ - Escalate: `view-authz` and `contract-change` breaks, new migrations, and any change to authentication or middleware settings.
@@ -0,0 +1,33 @@
1
+ ---
2
+ name: react
3
+ description: React rules for a code review. Flags component code that renders wrong, leaks, races or locks out users in ways the hooks lint cannot see. Covers state derived in effects, effects that race or never clean up, stale closures, unstable identities that defeat memoisation, keys that lose state, uncontrolled-to-controlled switches, server data copied into local state, HTML injected from untrusted input, secrets in client bundles, error and loading states left out, and interactive elements no keyboard or screen reader can use. Use as a review lens or as a stamp rule pack.
4
+ ---
5
+
6
+ # react
7
+
8
+ A component is correct when it shows the right thing for every state it can
9
+ be in, and stops doing work once it is gone. Review whether this change keeps
10
+ each render a pure function of props and state, keeps effects for
11
+ synchronising with the outside world, and keeps every user able to reach what
12
+ it renders.
13
+
14
+ ## Review
15
+
16
+ - **derived-state-effect**: Values computable from props or state are computed during render (or with `useMemo` when costly), never copied into state by an effect. Flag: `useEffect(() => setX(f(props.y)), [props.y])`, state that mirrors a prop, a chain of effects each setting state for the next. Why: an extra render with stale values on screen, and two sources of truth that drift.
17
+ - **effect-race**: An effect that fetches or subscribes ignores results that arrive after its inputs changed or the component unmounted: an `AbortController`, an `ignore` flag, or the data library's own cancellation. Flag: `fetch(...).then(setData)` in an effect with no abort or ignore, a subscription with no unsubscribe in the cleanup. Why: a slow old response overwrites the new one, and the user sees data for the wrong id.
18
+ - **effect-cleanup**: Every timer, listener, observer, socket or subscription an effect starts is stopped in its cleanup. Flag: `setInterval`, `addEventListener`, `new IntersectionObserver`, a WebSocket opened in an effect with no returned cleanup, or a cleanup that removes a different function than was added. Why: leaks and duplicate handlers that grow with every mount, doubled under Strict Mode.
19
+ - **stale-closure**: A callback stored for later (an interval, a listener, a debounced function, a ref callback) reads current state through the setter's updater, a ref, or its dependencies. Flag: a `setInterval` in a mount-only effect that reads state, `setCount(count + 1)` inside a long-lived callback, a `useCallback` with a deliberately trimmed dependency list. Why: the callback acts on the values from its first render, silently.
20
+ - **unstable-identity**: An object, array or function created during render and passed to a memoised child, a context value, or a dependency array is stabilised when its identity matters. Flag: `value={{ user, setUser }}` on a context provider, an inline object in a `useEffect` dependency list, a fresh callback into a `React.memo` child that the change made memoised. Why: every render re-runs the effect or re-renders every consumer, and the memoisation buys nothing.
21
+ - **key-identity**: List keys come from the item's stable identity. Flag: index keys on a list that can reorder, insert or delete; `Math.random()` or a fresh id generated during render; a key that changes when the item is edited. Why: React reuses the wrong component, so input text, focus and local state jump to another row.
22
+ - **controlled-switch**: An input stays either controlled or uncontrolled for its whole life. Flag: `value={maybeUndefined}`, `value` without `onChange` and without `readOnly`, `defaultValue` changed after mount expecting the input to follow. Why: React warns and the field stops reflecting state, so the user's edit or the reset is lost.
23
+ - **server-state-copy**: Data from the server lives in the data-fetching cache (React Query, SWR, the router's loader), not copied into `useState` or a global store. Flag: a query result copied into state on success, a store that holds fetched rows with no invalidation, a mutation that updates local state but not the cache. Why: screens disagree after a mutation, and refetches overwrite edits.
24
+ - **html-injection** [refuse]: `dangerouslySetInnerHTML`, `innerHTML`, `href`/`src` built from data, and `eval`-like APIs take only sanitised or trusted content. Flag: `dangerouslySetInnerHTML={{ __html: userText }}` with no sanitiser, a `javascript:` URL reachable from user input, markdown rendered to HTML without sanitising. Why: stored XSS runs as the signed-in user.
25
+ - **client-secret** [refuse]: Nothing secret reaches code that ships to the browser. Flag: an API key, private token or service credential in a component, a client-exposed env var (`VITE_`, `NEXT_PUBLIC_`, `REACT_APP_`) holding a secret, a server-only module imported into a client component. Why: anything in the bundle is public.
26
+ - **async-states**: A component that loads or mutates data renders its loading, empty and error states, and disables or guards a submit while it is pending. Flag: a fetch with only a success branch, a list with no empty state, a submit button that can fire twice, an error swallowed into a blank screen with no error boundary. Why: users see nothing, retry, and create duplicates.
27
+ - **accessible-interaction**: Interactive elements are real controls with accessible names. Flag: `onClick` on a `div` or `span` with no role, tab stop and key handler; an icon-only button with no label; an image that carries meaning with no `alt`; a modal that does not move or trap focus; custom form fields with no associated label. Why: keyboard and screen-reader users cannot use the feature, a legal exposure as well as a defect.
28
+
29
+ ## Fix
30
+
31
+ - Prefer: computing in render, the data library the repository already uses for server state, the existing design-system components for controls and dialogs, and the repository's sanitiser for HTML.
32
+ - Never touch: shared design-system components, lint configuration, or the data library's global client setup.
33
+ - Escalate: introducing a new state, data or sanitiser library; a change to a context's value shape that consumers outside the PR read; and any `client-secret` break, since the key must be rotated as well as removed.
@@ -0,0 +1,31 @@
1
+ ---
2
+ name: rust
3
+ description: Rust rules for a code review. Flags code that compiles and passes clippy but panics, blocks, leaks or breaks soundness in production. Covers unsafe blocks without a SAFETY argument, unwrap and expect on fallible input, panics across FFI, blocking calls in async code, locks held across await, unbounded channels and spawns, lost errors, integer overflow in release builds, untrusted deserialisation limits, SQL and commands built from input, and public API and serde changes. Use as a review lens or as a stamp rule pack.
4
+ ---
5
+
6
+ # rust
7
+
8
+ The compiler proves memory safety outside `unsafe`; it does not prove the
9
+ program stays up. Review whether this change keeps every `unsafe` justified,
10
+ turns bad input into errors rather than panics, and keeps async code from
11
+ stalling the runtime.
12
+
13
+ ## Review
14
+
15
+ - **unsafe-justified** [refuse]: Every `unsafe` block or `unsafe impl` (`Send`, `Sync`) carries a `// SAFETY:` comment naming the invariant that makes it sound, and the invariant actually holds in the code around it. Flag: a new `unsafe` with no SAFETY comment, a comment that restates the code, `transmute` between types without a documented layout guarantee, `get_unchecked` with no bounds argument, `unsafe impl Send` for a type holding `Rc` or a raw pointer. Why: unsoundness is undefined behaviour, the one failure Rust otherwise rules out.
16
+ - **no-panic-on-input**: Code that handles input, network data, files or configuration returns errors rather than panicking. Flag: `.unwrap()`, `.expect()`, indexing `v[i]`, slicing `&s[a..b]` on byte offsets, or `unreachable!()` on values that come from outside the program. Why: one malformed request aborts the task or the process.
17
+ - **ffi-panic**: A function called from C (`extern "C"`) or another language catches panics and turns them into an error code. Flag: an `extern "C" fn` that can panic with no `catch_unwind`, a callback passed to C that can unwind. Why: unwinding across FFI aborts the process or is undefined behaviour.
18
+ - **async-blocking**: Async code never blocks the executor thread. Flag: `std::fs`, `std::thread::sleep`, `std::sync::Mutex` held over work, a blocking database or HTTP client, or heavy CPU loops inside an `async fn` without `spawn_blocking`. Why: one blocked worker thread stalls every task scheduled on it.
19
+ - **lock-across-await**: No lock guard (std or `tokio::sync`) is held across an `.await` unless that is the intent and the lock is async. Flag: a `MutexGuard` alive across `.await`, `RefCell` borrows held across `.await`. Why: deadlocks, or futures that are not `Send` and fail far from the change.
20
+ - **bounded-async**: Channels and task spawning are bounded. Flag: `unbounded_channel` fed by external input, `tokio::spawn` per request item with no limit or `JoinSet`, a spawned task whose `JoinHandle` is dropped while its errors matter. Why: memory grows under load and failures vanish.
21
+ - **error-context**: Errors keep their source and context. Flag: `.map_err(|_| ...)` that drops the original error, `Box<dyn Error>` in a library's public API where callers need to match, `let _ = ` on a `Result` from a write or send, `.ok()` that hides a failure the caller should see. Why: the cause of the incident is gone from logs.
22
+ - **overflow**: Arithmetic on sizes, lengths, counts, money or values from input uses `checked_`, `saturating_` or `wrapping_` deliberately. Flag: `a + b`, `a * b` or `as` casts between integer widths on external values. Why: release builds wrap silently, producing wrong lengths and allocations.
23
+ - **untrusted-decode** [refuse]: Deserialisation of untrusted input sets size and depth limits and never trusts lengths from the data. Flag: `bincode` or similar with no size limit on network input, `Vec::with_capacity(len_from_input)`, reading a whole request body with no cap. Why: one small message allocates gigabytes.
24
+ - **injection** [refuse]: SQL takes input through bind parameters, commands through `Command::arg`, paths through a containment check. Flag: `format!` into a query string, `Command::new("sh").arg("-c").arg(input)`, `root.join(user_path)` without checking the result stays under root. Why: injection and path traversal.
25
+ - **public-contract**: Changes to public items, trait definitions and serde shapes are deliberate and versioned. Flag: a removed or renamed `pub` item, a new required trait method without a default, a changed `#[serde(rename)]`, removed `#[serde(default)]` on a stored type, a new variant on a public enum without `#[non_exhaustive]`. Why: downstream crates and stored data break.
26
+
27
+ ## Fix
28
+
29
+ - Prefer: `?` with the repository's error type (`thiserror` in libraries, `anyhow` with `.context()` in binaries), `spawn_blocking`, `tokio::sync` primitives, bounded channels, and checked arithmetic.
30
+ - Never touch: `Cargo.toml` features and versions, `build.rs`, generated bindings, and `#![forbid(unsafe_code)]` or lint attributes.
31
+ - Escalate: any new or changed `unsafe` block, `public-contract` breaks, and changes to the async runtime configuration.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jagreehal/shepherd",
3
- "version": "0.4.0",
3
+ "version": "0.6.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",
@@ -15,6 +15,7 @@
15
15
  "commands",
16
16
  "examples",
17
17
  "lenses",
18
+ "packs",
18
19
  "templates",
19
20
  "AGENTS.md",
20
21
  "THIRD_PARTY_NOTICES.md"
@@ -0,0 +1,6 @@
1
+ # C# and ASP.NET Core services. Extend pinned: github:jagreehal/shepherd/packs/dotnet.yml@<sha>
2
+ lenses:
3
+ dotnet:
4
+ skill: lenses/dotnet
5
+ applies_to: ['**/*.cs']
6
+ gate: escalate
package/packs/go.yml ADDED
@@ -0,0 +1,6 @@
1
+ # Go services and libraries. Extend pinned: github:jagreehal/shepherd/packs/go.yml@<sha>
2
+ lenses:
3
+ go:
4
+ skill: lenses/go
5
+ applies_to: ['**/*.go']
6
+ gate: escalate