@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/threat-modeling/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: threat-modeling
+description: STRIDE threat modelling for a planned feature or an existing system, done before or alongside the code. Maps the data flow, trust boundaries and assets, enumerates spoofing, tampering, repudiation, information disclosure, denial of service and elevation of privilege threats per element, and ends with a ranked list of mitigations the team can turn into tickets. Use when designing a feature that touches auth, money, personal data, uploads, webhooks or third-party integrations, when someone asks what could go wrong or how this could be attacked, or before a security sign-off on an architecture.
+license: MIT
+compatibility: Any Agent Skills host. Reads design docs and code only; no tools required.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: security
+  kete-loom/risk: read-only
+  kete-loom/owner: "Kete-org"
+---
+
+# Threat modelling (STRIDE)
+
+Answer four questions for one feature or system: what are we building, what can go wrong, what are we doing about it, and did we do a good enough job. Keep it lightweight: one sitting, one document, a ranked list at the end. This skill designs defences; it does not review a diff line by line (use the security-review skill or the security-reviewer agent for that).
+
+## 1. Set the scope
+
+1. Name the one feature, service or flow being modelled. If the request is "the whole platform", **stop and ask** which flow matters most and model that first.
+2. Collect what exists: design doc, ticket, API spec, architecture diagram, or the code if it is already built (search for route definitions, queue consumers, webhook handlers, cron jobs, outbound HTTP clients).
+3. Note the assumptions you are making (hosting, who the users are, which parts are out of scope). List them in the output; a wrong assumption is the most common reason a model misses the real threat.
+
+## 2. Draw the data flow
+
+Write a text data-flow diagram. Use five element types:
+
+| Element | Example |
+|---|---|
+| External entity | browser user, admin, partner API, payment provider |
+| Process | API server, worker, Lambda, LLM agent with tools |
+| Data store | Postgres, S3 bucket, Redis, log pipeline |
+| Data flow | HTTPS request, queue message, webhook, file upload |
+| Trust boundary | internet to edge, app to database, tenant A to tenant B, your code to a third party |
+
+```
+[User browser] --HTTPS (session cookie)--> (API) --SQL--> [(orders DB)]
+        ======= boundary: internet | VPC =======
+(API) --HTTPS (secret key)--> [Payment provider] --webhook (signed)--> (API)
+```
+
+Mark every place data crosses a trust boundary. Threats cluster there.
+
+## 3. List the assets
+
+What would hurt if stolen, changed or made unavailable: credentials and tokens, personal data, payment state, money movement, admin capability, availability of a critical path, audit logs, model prompts and tool permissions. Rate each **high, medium or low** by impact.
+
+## 4. Walk STRIDE per element
+
+For each element and each boundary-crossing flow, ask the questions that apply:
+
+| Threat | Property broken | Applies to | Ask |
+|---|---|---|---|
+| **S**poofing | Authentication | entities, processes | Can someone pretend to be this user, service or webhook sender? |
+| **T**ampering | Integrity | flows, stores, processes | Can input, a message, a file or a stored row be changed in transit or at rest? Can the client set a price, role or owner ID? |
+| **R**epudiation | Non-repudiation | entities, processes | Could a user deny an action and we can't prove otherwise? Are security events logged with who, what, when? |
+| **I**nformation disclosure | Confidentiality | flows, stores, processes | Can data leak via responses, errors, logs, URLs, caches, backups, other tenants, or an LLM's output? |
+| **D**enial of service | Availability | flows, stores, processes | Can one caller exhaust CPU, memory, connections, queue depth, paid API quota or disk? Is there a rate limit and size limit? |
+| **E**levation of privilege | Authorization | processes | Can a normal user reach admin actions, another tenant's data (IDOR), or code execution via injection or deserialisation? |
+
+Rules while walking:
+
+- Write each threat as **actor + action + asset + consequence**: "An unauthenticated caller replays a captured webhook to mark an unpaid order as paid."
+- Only list threats that are plausible for this design. Skip a STRIDE letter for an element when it genuinely does not apply; don't pad.
+- Check what already mitigates it (framework CSRF protection, signed webhooks, row-level security). Record it; a threat with a working control is still worth listing at low priority.
+
+## 5. Rate and decide
+
+Rate each threat with a simple likelihood x impact (each high, medium or low). Do not invent precise scores. Then pick one response:
+
+- **Mitigate**: add a control (name the concrete one: "verify HMAC on raw body", "scope query by tenant_id", "argon2id hashing").
+- **Eliminate**: remove the feature or data (don't store card numbers; don't log tokens).
+- **Transfer**: move it to a provider built for it (hosted payment page, managed identity provider).
+- **Accept**: only the user or owner can accept a risk. **Stop and ask** before marking anything high as accepted.
+
+## 6. Check your work
+
+- Every trust boundary has at least one threat considered.
+- Every high asset has at least one threat and one control.
+- Every mitigation is specific enough to become a ticket and to test.
+- Re-read the assumptions: if one is false, which threats change?
+
+## Never
+
+- Never produce a generic OWASP list unrelated to the diagram.
+- Never claim the system is secure; say what was modelled and what was not.
+- Never mark a high risk as accepted on the user's behalf.
+- Never include real secrets, hostnames or customer data from the codebase in the document.
+
+## Output format
+
+```
+# Threat model: <feature>
+Scope: <what is in and out>    Date: <date>
+Assumptions: <bulleted>
+
+## Data flow
+<text diagram with trust boundaries marked>
+
+## Assets
+| Asset | Impact |
+
+## Threats
+| ID | STRIDE | Element / flow | Threat (actor, action, asset, consequence) | Existing control | L | I | Response |
+
+## Prioritised mitigations
+1. [high] T3, T7: <concrete control> (owner: ?, test: <how to prove it works>)
+2. ...
+
+## Open questions
+<things only the team can answer>
+```
+
+Order the mitigations by risk (high likelihood and high impact first), and group threats fixed by one control into a single line.

package/skills/threat-modeling/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Threat model the new document upload and sharing feature before we build it",
+    "Do a STRIDE analysis of our payment webhook architecture",
+    "What could an attacker do to this design? Here's the data flow for our multi-tenant reporting service",
+    "We're adding an LLM agent with tool access to our support portal, map the trust boundaries and threats",
+    "Before security sign-off, list the assets, threats and mitigations for the mobile login flow and rank them"
+  ],
+  "should_not_trigger": [
+    "Scan the code in this pull request for XSS and injection flaws",
+    "Check whether any of our npm packages have known CVEs",
+    "Implement role-based access control on the admin routes",
+    "Write an architecture decision record for moving from REST to gRPC",
+    "Break this feature into implementation tasks and a delivery plan"
+  ]
+}

package/skills/typescript-patterns/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: typescript-patterns
+description: Idiomatic TypeScript and modern JavaScript for Node.js and the browser, covering strict tsconfig settings, discriminated unions and narrowing, restrained generics, typed error handling, async/await pitfalls, ESM versus CommonJS packaging, project layout and ESLint/Prettier setup. Use when writing or restructuring TS/JS code, designing types for a module, setting up tsconfig or package.json "type"/"exports", or choosing lint and format tooling.
+license: MIT
+compatibility: Any Agent Skills host. Needs Node.js 18+ and the project's package manager (npm, pnpm, yarn or bun).
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/requires: "node"
+  kete-loom/owner: "Kete-org"
+---
+
+# TypeScript patterns
+
+Write TypeScript that the compiler can actually check. Every rule here exists to keep the types honest about what happens at runtime.
+
+## 0. Read the project first
+
+1. Read `package.json` (`type`, `exports`, `engines`, scripts), every `tsconfig*.json`, and the lint/format config (`eslint.config.*`, `.eslintrc*`, `.prettierrc*`, `biome.json`).
+2. Note the lockfile (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock*`) and use only that package manager.
+3. Follow the existing style, folder layout and module system. Do not convert a codebase between ESM and CJS, or between tools, unless the user asked.
+4. Find the type-check command (often `tsc --noEmit` or a `typecheck` script) and run it before and after your change.
+
+## 1. tsconfig baseline
+
+For new projects, or when the user asks to tighten settings, start from:
+
+```jsonc
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "exactOptionalPropertyTypes": true,   // optional; stricter about `undefined`
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "target": "ES2022",
+    "module": "NodeNext",                 // Node apps and libraries
+    "moduleResolution": "NodeNext"
+    // bundled browser apps: "module": "ESNext", "moduleResolution": "Bundler"
+  }
+}
+```
+
+- Turning on `strict` in an existing codebase can produce hundreds of errors. **Stop and ask** before enabling it repo-wide; offer to enable it per package or fix errors in batches.
+- `verbatimModuleSyntax` suits ESM packages (`"type": "module"`) and bundled apps. In files that compile to CommonJS it rejects `import`/`export` syntax (you would need `import x = require()`), so leave it off for CJS packages.
+- Never weaken a compiler option to make an error go away.
+
+## 2. Type design
+
+- Model states as **discriminated unions**, not bags of optional fields:
+  `type Result = { ok: true; value: User } | { ok: false; error: string }`.
+- Narrow with `typeof`, `instanceof`, `in`, a discriminant check, or a type predicate (`(x): x is Foo`). End exhaustive `switch` statements with `default: return assertNever(x)`, where `function assertNever(x: never): never { throw new Error("Unexpected: " + String(x)) }`, so a new variant fails to compile.
+- Prefer `unknown` over `any` for values you have not checked. Parse untrusted input (HTTP bodies, `JSON.parse`, env vars, files) at the boundary with a schema library the project already uses (zod, valibot, io-ts) or a hand-written guard.
+- Use `as const` and `satisfies` to keep literal types while checking shape: `const routes = {...} satisfies Record<string, Route>`.
+- Use `readonly` arrays and properties for data you do not mutate.
+- Generics: add a type parameter only when it links two or more positions (input to output). If a parameter appears once, replace it with its constraint. Avoid conditional and mapped types in application code unless they remove real duplication.
+- Prefer `type` aliases for unions and `interface` for object shapes that are extended; follow the project if it already chose.
+- Avoid `enum`; use a union of string literals or an `as const` object. Avoid `namespace` in new code.
+
+## 3. Things never to do
+
+- `any`, `as any`, `@ts-ignore`, or `!` non-null assertions to silence an error. If a cast is truly needed, use `@ts-expect-error` with a reason, or a checked guard.
+- Double casts (`x as unknown as T`) outside tests.
+- `Function`, `Object` or `{}` as types.
+- Default exports in a codebase that uses named exports (or the reverse).
+
+## 4. Errors
+
+1. Throw `Error` subclasses, never strings or plain objects. Set `name` and pass `{ cause }` when wrapping: `throw new ConfigError("bad port", { cause: err })`.
+2. In `catch (err)`, `err` is `unknown`. Narrow before reading properties: `if (err instanceof HttpError) ...`.
+3. Catch only where you can handle, add context, or translate the error. Do not catch and log and continue unless losing the operation is acceptable.
+4. For expected failures (validation, not-found), returning a result union is often clearer than throwing. Pick one style per module.
+
+## 5. Async/await pitfalls
+
+| Pitfall | Fix |
+|---|---|
+| Floating promise: `save(x);` with no `await` | `await` it, return it, or mark intentional fire-and-forget with `void save(x).catch(log)` |
+| `arr.forEach(async x => ...)` does not wait | `for (const x of arr) await f(x)` (serial) or `await Promise.all(arr.map(f))` (parallel) |
+| Async callback passed where a sync one is expected (event handlers, `Array.filter`) | Wrap and handle the promise explicitly |
+| Sequential awaits on independent work | `await Promise.all([...])`; use `Promise.allSettled` when one failure must not cancel the rest |
+| Unbounded `Promise.all` over thousands of items | Batch, or use a concurrency limiter the project already has |
+| `return promise` inside `try` without `await` | `return await promise` so the `catch`/`finally` applies |
+| Shared mutable state across awaits (check-then-act) | Re-read after the await, or serialise with a lock/queue |
+| No timeout on network calls | `fetch(url, { signal: AbortSignal.timeout(5000) })` |
+
+Turn on `@typescript-eslint/no-floating-promises` and `@typescript-eslint/no-misused-promises` (they need type-aware linting) to catch the first three.
+
+## 6. ESM versus CommonJS
+
+- `"type": "module"` in `package.json` makes `.js` files ESM; otherwise they are CJS. `.mjs`/`.mts` are always ESM, `.cjs`/`.cts` always CJS.
+- With `module: NodeNext`, relative imports in ESM need the runtime extension: `import { x } from "./util.js"` even though the source is `util.ts`.
+- ESM has no `require`, `__dirname` or `__filename`. Use `import.meta.url` with `fileURLToPath`, or `import.meta.dirname` / `import.meta.filename` (Node 20.11+).
+- Libraries: declare entry points with `exports` (with a `types` condition first in each block). Shipping both ESM and CJS needs a build tool such as tsup; verify with `npx @arethetypeswrong/cli --pack .` before publishing.
+- With `verbatimModuleSyntax`, write `import type { Foo }` for type-only imports.
+- **Stop and ask** before changing `type`, `exports` or `main` on a published package: it is a breaking change for consumers.
+
+## 7. Project layout
+
+- Source in `src/`, build output in `dist/` (git-ignored), tests next to code (`foo.test.ts`) or in `test/`, following the project.
+- Monorepos: use the package manager's workspaces (`pnpm-workspace.yaml`, `workspaces` in `package.json`) and TypeScript project references (`composite`, `references`) when packages build separately.
+- Keep side effects out of module top level; export functions and wire them in an entry file.
+- Read config from `process.env` once, validate it, and export a typed object.
+
+## 8. Lint and format
+
+- ESLint 9+ uses flat config (`eslint.config.js`/`.mjs`). Use `typescript-eslint` with `recommendedTypeChecked` (or `strictTypeChecked`) and `parserOptions.projectService: true`.
+- Let Prettier (or Biome, if the project uses it) own formatting; disable stylistic lint rules that conflict (`eslint-config-prettier`).
+- Do not add a new linter, formatter or major dependency without asking.
+
+## 9. Finish
+
+1. Run, in this order, whatever the project defines: format check, lint, type-check, tests.
+2. Fix what you introduced. Report pre-existing failures instead of fixing them silently.
+
+## Report back
+
+End with: files changed, the commands you ran with pass/fail, any `any`/casts you could not remove and why, and anything that needs the user's decision (strictness, module system, new dependency).

package/skills/typescript-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Set up a strict tsconfig for a new Node 20 library that ships ESM",
+    "How should I type this API response so the success and error cases can't get mixed up?",
+    "Our package mixes require and import and half the files are .mjs, what's the right way to structure ESM vs CommonJS here?",
+    "Refactor this user service to stop using any and use proper unions and narrowing",
+    "Configure ESLint flat config with typescript-eslint and Prettier for our monorepo"
+  ],
+  "should_not_trigger": [
+    "Write Vitest tests for the date formatting helpers and mock the clock",
+    "Review my TypeScript pull request for unhandled promises before I merge",
+    "tsc fails with TS2307 Cannot find module '@app/config', make the build pass",
+    "Add a useMemo to stop this React component re-rendering on every keystroke",
+    "Write idiomatic Python dataclasses for the order model"
+  ]
+}

package/skills/typescript-testing/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: typescript-testing
+description: Vitest and Jest test suites for TypeScript and JavaScript projects, picking whichever runner the repo already uses, with module mocks, spies, fake timers, async assertions, fixtures, coverage thresholds and a procedure for diagnosing flaky tests. Use when writing or fixing unit and integration tests in a TS/JS codebase, mocking an import or the clock, raising coverage, or chasing a test that passes locally and fails in CI.
+license: MIT
+compatibility: Any Agent Skills host. Needs Node.js 18+ and the project's package manager and test runner.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "node"
+  kete-loom/owner: "Kete-org"
+---
+
+# TypeScript testing
+
+Tests that run fast, fail for one reason, and give the same answer every time. Use the runner the project already has.
+
+## 0. Detect the setup
+
+1. Check `package.json` (`devDependencies`, `scripts.test`) and config files: `vitest.config.*` or a `test` block in `vite.config.*` means Vitest; `jest.config.*` or a `jest` key means Jest. `node:test` imports mean the built-in Node runner: keep using it (`node --test`, `mock` from `node:test`) and apply the rules below, not the Vitest/Jest APIs.
+2. If none exists, **stop and ask** which to add. Suggest Vitest for Vite or ESM-first projects, and Jest only if the team already knows it.
+3. Note the environment (`node`, `jsdom`, `happy-dom`), setup files, path aliases and whether globals (`describe`, `it`) are enabled or imported.
+4. Run the suite once. If it already fails, report which tests fail before changing anything.
+5. Run a single file while working: `npx vitest run path/to/file.test.ts` or `npx jest path/to/file.test.ts`. Filter by name with `-t "name"`.
+
+## 1. Write the test
+
+- One behaviour per test; name it after that behaviour (`"rejects an expired token"`).
+- Arrange, act, assert. Test through the public API of the module, not private helpers.
+- Use the narrowest matcher that says what you mean: `toEqual` for structure, `toStrictEqual` when `undefined` properties matter, `toBe` for identity and primitives, `toThrow(ErrorClass)` for errors.
+- Build test data with small factory functions (`makeUser({ role: "admin" })`) rather than large shared fixtures that every test mutates.
+- Keep fixtures in files next to tests (`__fixtures__/`) for large payloads; load them, do not inline 200 lines.
+
+## 2. Async code
+
+- Always `await` (or `return`) the promise under test. A missing `await` lets the test pass before the assertion runs.
+- Rejections: `await expect(fn()).rejects.toThrow(NotFoundError)`. Never wrap in `try/catch` without `expect.assertions(n)`.
+- Resolutions: `await expect(fn()).resolves.toEqual(value)`.
+- Do not use real `setTimeout` sleeps to wait for work; await the operation, or use fake timers.
+
+## 3. Mocks and spies
+
+Mock only boundaries: network, clock, randomness, filesystem, third-party SDKs. Never mock the unit under test.
+
+| Need | Vitest | Jest |
+|---|---|---|
+| Mock a module | `vi.mock("./db", () => ({ query: vi.fn() }))` | `jest.mock("./db", () => ({ query: jest.fn() }))` |
+| Keep the rest of the real module | `vi.mock(import("./db"), async (orig) => ({ ...(await orig()), query: vi.fn() }))` | `jest.mock("./db", () => ({ ...jest.requireActual("./db"), query: jest.fn() }))` |
+| Variable used inside a mock factory | `const m = vi.hoisted(() => vi.fn())` | name it with a `mock` prefix |
+| Spy on a method | `vi.spyOn(obj, "method")` | `jest.spyOn(obj, "method")` |
+| Typed mock | `vi.mocked(fn)` | `jest.mocked(fn)` |
+| Reset between tests | `vi.restoreAllMocks()` in `afterEach`, or `restoreMocks: true` in config | `restoreMocks: true` in config |
+
+- `vi.mock` and `jest.mock` are hoisted above imports, so a factory cannot reference normal top-level variables.
+- Jest with native ESM cannot use `jest.mock` on ESM imports; use `jest.unstable_mockModule` followed by a dynamic `await import()`, or run Jest through a CJS transform.
+- For HTTP, prefer intercepting at the network layer (`msw`, `nock`, or `undici` `MockAgent`) over mocking `fetch` by hand, if the project already has one of them.
+- Assert on what matters (`toHaveBeenCalledWith(expected)`), not on call counts that are an implementation detail.
+
+## 4. Timers and dates
+
+```ts
+beforeEach(() => { vi.useFakeTimers(); vi.setSystemTime(new Date("2025-01-01T00:00:00Z")); });
+afterEach(() => { vi.useRealTimers(); });
+
+it("retries after 1s", async () => {
+  const p = withRetry(task);
+  await vi.advanceTimersByTimeAsync(1000);   // async variant flushes promises between timers
+  await expect(p).resolves.toBe("ok");
+});
+```
+
+Jest equivalents: `jest.useFakeTimers()`, `jest.setSystemTime()`, `jest.advanceTimersByTimeAsync()`. Always restore real timers in `afterEach`.
+
+## 5. Coverage
+
+- Vitest: `npx vitest run --coverage` (needs `@vitest/coverage-v8` or `@vitest/coverage-istanbul`). Jest: `npx jest --coverage`.
+- Set thresholds in config (`test.coverage.thresholds` in Vitest, `coverageThreshold` in Jest) only if the team wants them enforced.
+- Read the uncovered-lines report and test the **branches** that matter (error paths, boundaries). Do not write tests that only execute lines without asserting.
+
+## 6. Flaky tests
+
+Follow this order and stop when you find the cause:
+
+1. Reproduce: run the single test many times (a shell loop or the runner's repeat option) and the whole file in random order (Vitest `--sequence.shuffle`, Jest `--randomize`).
+2. Run it alone and with the full suite. Passing alone but failing together means **shared state**: module-level variables, unrestored mocks, leftover DB rows, `process.env` changes. Reset in `beforeEach`/`afterEach`.
+3. Look for real time (`Date.now()`, `new Date()`), real timers, randomness, or locale/timezone (`TZ=UTC` in the test script).
+4. Look for missing `await`, unawaited promises in setup, or assertions on work still in progress.
+5. Look for real network, ports already in use, or order-dependent file writes. Use temp dirs (`fs.mkdtemp`) and port `0`.
+6. CI-only failures: compare Node version, CPU count (worker pools), and environment variables.
+
+Never fix flakiness by adding retries, longer timeouts or `.skip` without telling the user; those hide the bug.
+
+## Rules
+
+- Never delete, skip or loosen an existing assertion to get green. If a test is wrong, explain why and ask first.
+- No real network calls, no real time, no dependence on test order.
+- Do not add a new test runner or mocking library without asking.
+
+## Report back
+
+End with: tests added or changed (file and name), the command you ran, pass/fail counts, coverage change if measured, and for a flaky test the root cause you found.

package/skills/typescript-testing/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Write Vitest unit tests for the invoice calculator in src/billing",
+    "How do I mock the ./db module in Jest but keep the rest of its real exports?",
+    "This retry test uses setTimeout and takes 30 seconds, use fake timers instead",
+    "Our auth.test.ts passes locally but fails randomly in CI, find out why",
+    "Get coverage on the payments package above 80% with jest --coverage"
+  ],
+  "should_not_trigger": [
+    "Set up a strict tsconfig and decide between ESM and CommonJS for the new package",
+    "Write Playwright end-to-end tests for the signup flow in the browser",
+    "Review this TypeScript diff for type holes and async races",
+    "npm run build fails with ERR_REQUIRE_ESM after upgrading a dependency, fix it",
+    "Write pytest fixtures for the Django order views"
+  ]
+}

package/skills/verification-loop/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: verification-loop
+description: Pre-merge verification that detects the project's build, lint, type-check and test commands, runs them in order, fixes what it safely can and reports a pass/fail verdict. Use when the user asks to verify, check or validate changes before committing, opening a pull request, merging or shipping.
+license: MIT
+compatibility: Any Agent Skills host. The detection script needs Node 18+; without Node, detect commands by reading project files manually.
+metadata:
+  kete-loom/version: "0.1.1"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git, node"
+  kete-loom/owner: "Kete-org"
+---
+
+# Verification loop
+
+Prove the change works before anyone else has to. Run every check the project defines, in a fixed order, and give a clear verdict.
+
+## 1. Scope the change
+
+Run `git status` and `git diff --stat` against the base branch (usually `main`). Note which files and packages changed. In a monorepo, verify the changed packages plus anything that depends on them.
+
+## 2. Detect the checks
+
+Run the helper from this skill's folder:
+
+```
+node scripts/detect-checks.js [project-dir]
+```
+
+It prints a JSON list of the build, lint, type-check, format-check and test commands it finds (npm/pnpm/yarn/bun scripts, Python, Go, Rust, Java, .NET, Makefile). Also read `AGENTS.md`, the README and the CI workflow files: if CI runs a command the script missed, add it. CI is the source of truth.
+
+If nothing is detected, ask the user how they verify changes. Don't invent commands.
+
+## 3. Run in this order
+
+1. **Install / build**: does it compile?
+2. **Format check**: check mode only (`--check`), never a reformat of the whole repo.
+3. **Lint**
+4. **Type-check**
+5. **Tests**: unit, then integration. Skip end-to-end suites that need external services unless the user asks.
+
+Run each command exactly as the project defines it. Capture the exit code and the first relevant error lines.
+
+## 4. Fix, then re-run
+
+For each failure:
+
+- **Caused by this change**: fix it, then re-run that check and everything after it.
+- **Pre-existing** (also fails on the base branch): don't fix it unasked. Report it as pre-existing. Confirm with `git stash` or by checking the base branch only if it's cheap and safe.
+- **Flaky** (passes on retry with no change): report it as flaky, with the test name.
+
+Never make a check pass by disabling a rule, adding `skip`/`ignore`, loosening types to `any`, or deleting tests. If that seems like the only path, stop and ask.
+
+Stop after three fix rounds on the same check and report.
+
+## 5. Final review of the diff
+
+Re-read the full diff once. Look for: debug prints, commented-out code, secrets or tokens, TODOs you introduced, unrelated changes, and missing tests for new behaviour.
+
+## 6. Verdict
+
+Report a table, then one line:
+
+| Check | Command | Result |
+|---|---|---|
+| Build | `npm run build` | ✅ pass |
+| Lint | `npm run lint` | ✅ pass (2 warnings) |
+| Tests | `npm test` | ❌ 1 failing (pre-existing: `auth.spec.ts`) |
+
+**Verdict:** READY, READY WITH NOTES, or NOT READY, followed by what must happen before merge.

package/skills/verification-loop/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "Run all the checks on my branch before I open a pull request",
+    "Is this ready to merge? Make sure lint, types and tests all pass",
+    "Verify my changes compile and the test suite is green before I push",
+    "Do a final pre-ship check of the repo"
+  ],
+  "should_not_trigger": [
+    "Add a discount-code field to the checkout service, test first please",
+    "Set up GitHub Actions CI for this new repository",
+    "Why does this single unit test fail intermittently on Windows?",
+    "Write release notes for version 2.3"
+  ]
+}

package/skills/verification-loop/scripts/detect-checks.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+'use strict';
+
+// Detects a project's verification commands and prints them as JSON.
+// Usage: node detect-checks.js [project-dir]
+// Read-only: it never runs the commands it finds.
+
+const fs = require('fs');
+const path = require('path');
+
+const root = path.resolve(process.argv[2] || '.');
+const has = (f) => fs.existsSync(path.join(root, f));
+const read = (f) => {
+  try {
+    return fs.readFileSync(path.join(root, f), 'utf8');
+  } catch {
+    return '';
+  }
+};
+const checks = [];
+const add = (kind, command, source) => {
+  if (!checks.some((c) => c.command === command)) checks.push({ kind, command, source });
+};
+
+// JavaScript / TypeScript
+if (has('package.json')) {
+  let pkg = {};
+  try {
+    pkg = JSON.parse(read('package.json'));
+  } catch {}
+  const pm = has('pnpm-lock.yaml') ? 'pnpm' : has('yarn.lock') ? 'yarn' : has('bun.lockb') || has('bun.lock') ? 'bun' : 'npm';
+  // bun needs `run`: `bun test` / `bun build` are its own runner and bundler, not the scripts.
+  const run = (s) => (pm === 'npm' || pm === 'bun' ? `${pm} run ${s}` : `${pm} ${s}`);
+  const scripts = pkg.scripts || {};
+  const map = [
+    ['build', /^build$/],
+    ['format', /^(format:check|fmt:check|prettier:check|check:format)$/],
+    ['lint', /^(lint|eslint|biome)$/],
+    ['typecheck', /^(typecheck|type-check|tsc|check:types|types)$/],
+    ['test', /^(test|test:unit|vitest|jest)$/],
+    ['test-integration', /^test:(integration|int)$/],
+  ];
+  for (const [kind, re] of map) for (const s of Object.keys(scripts)) if (re.test(s)) add(kind, s === 'test' && pm === 'npm' ? 'npm test' : run(s), 'package.json');
+  if (!Object.keys(scripts).some((s) => /type/.test(s)) && has('tsconfig.json')) add('typecheck', `${pm === 'npm' ? 'npx' : pm + ' exec'} tsc --noEmit`, 'tsconfig.json');
+}
+
+// Python
+if (has('pyproject.toml') || has('setup.cfg') || has('requirements.txt')) {
+  const py = read('pyproject.toml') + read('setup.cfg');
+  const runner = has('uv.lock') ? 'uv run ' : has('poetry.lock') ? 'poetry run ' : '';
+  if (/\[tool\.ruff/.test(py) || has('ruff.toml')) {
+    add('format', `${runner}ruff format --check .`, 'ruff');
+    add('lint', `${runner}ruff check .`, 'ruff');
+  } else if (/flake8/.test(py) || has('.flake8')) add('lint', `${runner}flake8`, 'flake8');
+  if (/\[tool\.black/.test(py)) add('format', `${runner}black --check .`, 'black');
+  if (/\[tool\.mypy/.test(py) || has('mypy.ini')) add('typecheck', `${runner}mypy .`, 'mypy');
+  if (/\[tool\.pyright/.test(py) || has('pyrightconfig.json')) add('typecheck', `${runner}pyright`, 'pyright');
+  if (/pytest/.test(py) || has('pytest.ini') || has('tests') || has('conftest.py')) add('test', `${runner}pytest`, 'pytest');
+}
+
+// Go
+if (has('go.mod')) {
+  add('build', 'go build ./...', 'go.mod');
+  add('lint', 'go vet ./...', 'go.mod');
+  if (has('.golangci.yml') || has('.golangci.yaml')) add('lint', 'golangci-lint run', '.golangci.yml');
+  add('test', 'go test ./...', 'go.mod');
+}
+
+// Rust
+if (has('Cargo.toml')) {
+  add('format', 'cargo fmt --check', 'Cargo.toml');
+  add('lint', 'cargo clippy --all-targets -- -D warnings', 'Cargo.toml');
+  add('test', 'cargo test', 'Cargo.toml');
+}
+
+// JVM
+if (has('gradlew')) {
+  add('build', './gradlew build -x test', 'gradlew');
+  add('test', './gradlew test', 'gradlew');
+} else if (has('pom.xml')) {
+  add('build', 'mvn -q -DskipTests package', 'pom.xml');
+  add('test', 'mvn -q test', 'pom.xml');
+}
+
+// .NET
+if (fs.readdirSync(root).some((f) => /\.(sln|csproj|fsproj)$/.test(f))) {
+  add('build', 'dotnet build', '.NET');
+  add('test', 'dotnet test', '.NET');
+}
+
+// Makefile targets
+const make = read('Makefile');
+for (const [kind, target] of [['build', 'build'], ['lint', 'lint'], ['typecheck', 'typecheck'], ['test', 'test']]) {
+  if (new RegExp(`^${target}:`, 'm').test(make)) add(kind, `make ${target}`, 'Makefile');
+}
+
+const order = ['build', 'format', 'lint', 'typecheck', 'test', 'test-integration'];
+checks.sort((a, b) => order.indexOf(a.kind) - order.indexOf(b.kind));
+
+const ci = has('.github/workflows') ? fs.readdirSync(path.join(root, '.github/workflows')).map((f) => `.github/workflows/${f}`) : [];
+console.log(JSON.stringify({ root, checks, ciFilesToReview: ci }, null, 2));
+if (!checks.length) process.exitCode = 3;