@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/laravel-patterns/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: laravel-patterns
+description: Laravel application conventions for routes, controllers and Eloquent models, with N+1 detection through eager loading and preventLazyLoading, validation in Form Request classes, authorization through policies and gates, queued jobs that dispatch after commit, config caching and the env() trap, mass-assignment and other framework security defaults, and feature tests in Pest or PHPUnit using RefreshDatabase and fakes. Use when building or reviewing a Laravel app, fixing slow Eloquent pages, adding a policy, form request or queued job, or writing Laravel feature tests.
+license: MIT
+compatibility: Any Agent Skills host. Needs PHP, Composer and the project's artisan command. Written for Laravel 11 and later; most rules also apply to 9 and 10.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "php, composer"
+  kete-loom/owner: "Kete-org"
+---
+
+# Laravel patterns
+
+Write Laravel code the way the framework expects, so the next developer finds things where Laravel puts them. For plain PHP language style (types, enums, PSR-12) follow the `php-patterns` skill; for PHPUnit or Pest mechanics outside Laravel follow `php-testing`.
+
+## 0. Before you change anything
+
+1. Read `composer.json` for the `laravel/framework` version and whether `pestphp/pest` is installed. Match the project, not this skill, where they differ.
+2. Check the layout: Laravel 11+ apps configure middleware, exceptions and routing in `bootstrap/app.php` and have no `Http/Kernel.php`. Older apps use the kernel. Do not mix the two styles.
+3. Run the test command (`php artisan test`, or `./vendor/bin/pest` / `./vendor/bin/phpunit`). If it fails before you start, **stop and tell the user**.
+
+## 1. Structure
+
+- Routes stay thin: `routes/web.php` and `routes/api.php` map URLs to controllers. No business logic in route closures beyond trivial pages.
+- Controllers: one resource controller per model (`php artisan make:controller PostController --resource --model=Post`). A controller method does: authorize, validate, call the domain code, return a response.
+- Put multi-step business logic in an action or service class under `app/` (for example `app/Actions/PublishPost.php`) injected through the constructor. Do not invent a repository layer over Eloquent unless the project already has one.
+- Use route model binding (`Post $post`) instead of `Post::findOrFail($id)` in the controller. Scope child bindings with `->scopeBindings()` so `/users/{user}/posts/{post}` can't load another user's post.
+- Return API data through API resources (`php artisan make:resource PostResource`), never `$model->toArray()` straight from the database, so new columns don't leak.
+
+## 2. Eloquent and N+1
+
+1. Turn lazy loading into an error outside production, in `AppServiceProvider::boot()`:
+   ```php
+   Model::preventLazyLoading(! $this->app->isProduction());
+   ```
+   Then every N+1 shows up as a `LazyLoadingViolationException` in tests and local runs.
+2. Load relations before the loop: `Post::with(['author', 'tags'])->paginate()`. On an already loaded collection use `$posts->load('author')`. For counts use `withCount('comments')`, not `$post->comments->count()`.
+3. Select only what the page needs on wide tables (`->select(['id', 'title', 'user_id'])`), keeping the foreign keys the eager loads need.
+4. Large batch work: `chunkById(500, ...)` or `lazyById()`, never `Model::all()` on a table that grows.
+5. Writes that touch many rows: `Post::where(...)->update([...])` runs one query but skips model events and observers. Say so if the code relies on them.
+6. Wrap multi-write operations in `DB::transaction(function () { ... })`.
+7. Index every column you filter, join or sort on, in the same migration that adds the query.
+
+## 3. Validation with Form Requests
+
+- Any input with more than a couple of rules gets a Form Request: `php artisan make:request StorePostRequest`. Type-hint it in the controller; Laravel validates before the method runs.
+- Persist only `$request->validated()` (or `$request->safe()->only([...])`). Never `$request->all()` into `create()` or `update()`.
+- `make:request` generates `authorize()` returning `false`, which turns every request into a 403. Return the policy check there (`return $this->user()->can('update', $this->route('post'));`), or delete the method and authorize in the controller; never leave both with different logic.
+- Use rule objects for real rules: `Rule::unique('users')->ignore($user)`, `Rule::exists('teams', 'id')`, `Rule::enum(Status::class)`, `Password::defaults()`.
+- Validate files with `file`, `mimes:` and `max:` (kilobytes). Never trust the client file name; store with `store()` and a generated name.
+
+## 4. Authorization: policies and gates
+
+- One policy per model: `php artisan make:policy PostPolicy --model=Post`. Policies in `app/Policies` named `<Model>Policy` are discovered automatically.
+- Authorize in every action that reads or changes a specific record:
+  ```php
+  Gate::authorize('update', $post);           // throws, becomes 403
+  Route::put('/posts/{post}', ...)->can('update', 'post');
+  ```
+  `$this->authorize()` in a controller only exists if the base controller uses the `AuthorizesRequests` trait; the Laravel 11+ skeleton's base controller does not, so prefer `Gate::authorize`.
+- Gates (`Gate::define` in `AppServiceProvider`) are for actions without a model, such as viewing an admin dashboard.
+- Return `Response::denyAsNotFound()` from a policy when a 403 would reveal that the record exists.
+- Hiding a button in Blade with `@can` is not authorization. The controller check is.
+
+## 5. Queues and jobs
+
+1. `php artisan make:job SendInvoice`; implement `ShouldQueue`. Pass models or IDs, not large payloads; `SerializesModels` reloads the model when the job runs.
+2. Dispatch after the database commit when the job reads rows you just wrote: `SendInvoice::dispatch($invoice)->afterCommit()`, or set `after_commit` to `true` on the queue connection in `config/queue.php`.
+3. Make every job safe to run twice. Set `$tries`, `$backoff` and `$timeout`, check state before acting, and use `ShouldBeUnique` or `WithoutOverlapping` middleware where duplicates hurt.
+4. Implement `failed(Throwable $e)` for anything the user is waiting on, so a failure is recorded, not lost.
+5. Production runs a real driver (redis, database, SQS) with a supervised `php artisan queue:work`; `sync` is for tests only. Run `php artisan queue:restart` on deploy so workers load new code.
+
+## 6. Config and environment
+
+- Read `env()` **only** inside `config/*.php`. After `php artisan config:cache`, `env()` elsewhere returns `null`. Application code uses `config('services.stripe.secret')`.
+- `.env` is never committed. Add every new key to `.env.example` with a placeholder.
+- Production: `APP_DEBUG=false`, `APP_ENV=production`, a set `APP_KEY`, and `php artisan optimize` (config, route, event and view caches) in the deploy.
+
+## 7. Security defaults to keep
+
+- Mass assignment: declare `$fillable` (or a narrow `$guarded`) on every model. Never `$guarded = []` on models that take user input. Consider `Model::preventSilentlyDiscardingAttributes()` outside production.
+- Blade `{{ }}` escapes; `{!! !!}` does not. Use `{!! !!}` only for HTML you sanitised yourself.
+- Raw SQL: `DB::select('... where id = ?', [$id])` or `whereRaw('x = ?', [$v])`. Never interpolate input into `whereRaw`, `orderByRaw` or column names; whitelist sortable columns.
+- Keep CSRF protection on web routes. Exclude only webhook routes that verify their own signature.
+- Hash passwords with `Hash::make` (or the `hashed` cast). Rate-limit login and API routes with `RateLimiter::for` and the `throttle` middleware.
+- Signed URLs (`URL::temporarySignedRoute`) for one-off links; check `hasValidSignature()` or use the `signed` middleware.
+
+## 8. Testing (Pest or PHPUnit)
+
+Use whichever the project has. Feature tests hit routes; unit tests cover plain classes.
+
+```php
+uses(RefreshDatabase::class);
+
+it('lets the owner update a post', function () {
+    $post = Post::factory()->create();
+
+    $this->actingAs($post->author)
+        ->put(route('posts.update', $post), ['title' => 'New'])
+        ->assertRedirect();
+
+    expect($post->fresh()->title)->toBe('New');
+});
+
+it('forbids other users', function () {
+    $post = Post::factory()->create();
+    $this->actingAs(User::factory()->create())
+        ->put(route('posts.update', $post), ['title' => 'x'])
+        ->assertForbidden();
+});
+```
+
+- Build data with model factories and states, not hand-written inserts.
+- Fake side effects: `Queue::fake()`, `Bus::fake()`, `Mail::fake()`, `Notification::fake()`, `Event::fake()`, `Storage::fake('s3')`, `Http::fake([...])` plus `Http::preventStrayRequests()`.
+- Every policy gets an allowed and a forbidden test. Every Form Request gets at least one invalid-input test asserting `assertSessionHasErrors` or `assertUnprocessable()`.
+- Freeze time with `$this->travelTo(...)` or `Carbon::setTestNow()` for anything date-based.
+
+## Stop and ask the user
+
+- Before a migration that drops or renames a column or table with data, or rewrites a large table.
+- Before changing the queue driver, cache store, session driver or auth guard.
+- Before adding a Composer package for something Laravel already does.
+
+## Never
+
+- Never commit `.env`, `APP_KEY` or credentials, or set `APP_DEBUG=true` in production.
+- Never call `env()` outside `config/`.
+- Never pass `$request->all()` to `create`, `update` or `fill`.
+- Never skip the policy check because "the UI hides it".
+- Never run `migrate:fresh` or `db:wipe` against anything but a local or test database.
+
+## Finish
+
+Run the test command and `php artisan route:list` if routes changed. Report: files changed, N+1s found and fixed, authorization added, and anything you could not test.

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "My Laravel posts index runs 200 queries, how do I fix the N+1 with Eloquent?",
+    "Add a form request and a policy so only the owner can update an invoice in our Laravel app",
+    "The welcome email job in Laravel sometimes runs before the user row is committed, how do I dispatch it safely?",
+    "env('STRIPE_KEY') returns null in production after php artisan config:cache, why?",
+    "Write Pest feature tests for the Laravel orders controller, including the forbidden case"
+  ],
+  "should_not_trigger": [
+    "Convert these PHPUnit docblock annotations to PHP 8 attributes in my plain Composer library",
+    "Make this PHP 8 value object readonly and use a backed enum for its status",
+    "My Rails index page has an N+1 on comments, fix it with includes",
+    "Review the Stripe webhook handler for idempotency and signature checks",
+    "Set up GitHub Actions to run our PHP tests on every pull request"
+  ]
+}

package/skills/linear-integration/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: linear-integration
+description: Talks to Linear's GraphQL API at api.linear.app/graphql with the @linear/sdk or raw queries, covering personal API keys versus OAuth 2.0 apps (actor=app, 24-hour access tokens with refresh, client credentials), querying and mutating issues, projects, cycles, teams and workflow states, Relay-style first/after cursor pagination, Linear-Signature HMAC webhook checks with the webhookTimestamp replay window, and request plus complexity rate limits reported as RATELIMITED errors. Use when building a Linear sync, bot or agent, creating or moving Linear issues from code, receiving Linear webhooks, or fixing Linear auth, paging or rate-limit problems.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to api.linear.app. Examples use TypeScript and the official @linear/sdk; raw GraphQL works from any language.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Linear integration
+
+Build a Linear integration that uses the right credential, asks GraphQL only for what it needs, pages through every result, trusts only signed webhooks, and stays within both the request and complexity budgets.
+
+## Ground rules
+
+1. **One endpoint:** `POST https://api.linear.app/graphql`, JSON body `{ "query": ..., "variables": ... }`. Explore the schema with Linear's API explorer or introspection; do not guess field names.
+2. **Credentials from the environment** (`LINEAR_API_KEY`, OAuth client secret, webhook signing secret). Never commit or log them.
+3. **Look up IDs, never hard-code them.** Team, workflow state, label, project and cycle IDs differ per workspace. Fetch them once and cache.
+4. **Errors arrive in the body.** A GraphQL response can be HTTP 200 or 400 with an `errors` array. Always check `errors` and each mutation's `success` field.
+5. **Ask only for the fields you use**; every field and nested connection adds complexity points.
+
+## Choose the auth
+
+| Situation | Use |
+|---|---|
+| Personal script or internal tool, acting as you | Personal API key, sent as `Authorization: <API_KEY>` (no `Bearer`) |
+| App other users or workspaces install | OAuth 2.0, `Authorization: Bearer <access token>` |
+| Bot or agent whose actions show as the app, not a person | OAuth with `actor=app` |
+| Server-to-server for your own workspace without a user | OAuth client credentials grant (enable it on the app first) |
+
+### OAuth 2.0
+
+1. Create an OAuth app in Linear's settings; set redirect URIs.
+2. Redirect to `https://linear.app/oauth/authorize?client_id=...&redirect_uri=...&response_type=code&scope=read,write&state=...` (add `&actor=app` for app actor). Scopes: `read` (always), `write`, `issues:create`, `comments:create`, `timeSchedule:write`, `admin`. Request `admin` only if the user confirms it is needed.
+3. Exchange the code at `POST https://api.linear.app/oauth/token`. Access tokens last 24 hours; refresh with `grant_type=refresh_token` and store the new refresh token each time.
+4. Client credentials tokens last 30 days, have no refresh token, and are invalidated when the client secret is rotated; request a new one on 401.
+5. Revoke on disconnect: `POST https://api.linear.app/oauth/revoke`.
+
+## Common operations
+
+```ts
+import { LinearClient } from '@linear/sdk';
+const linear = new LinearClient({ apiKey: process.env.LINEAR_API_KEY }); // or { accessToken } for OAuth
+
+const team = (await linear.teams({ filter: { key: { eq: 'ENG' } } })).nodes[0];
+const done = (await team.states({ filter: { type: { eq: 'completed' } } })).nodes[0];
+
+const res = await linear.createIssue({ teamId: team.id, title: 'Checkout 500s', description: 'Markdown body', priority: 2 });
+if (!res.success) throw new Error('issueCreate failed');
+const issue = await res.issue;
+await linear.updateIssue(issue.id, { stateId: done.id });
+```
+
+Raw GraphQL equivalents: `issueCreate(input: IssueCreateInput!)`, `issueUpdate(id:, input:)`, `commentCreate(input:)`, and queries `issues(filter:)`, `issue(id:)` (accepts the UUID or the identifier such as `ENG-123`), `projects`, `cycles`, `teams`, `workflowStates`.
+
+- **Workflow states** belong to a team and have a `type` (`triage`, `backlog`, `unstarted`, `started`, `completed`, `canceled`). Move issues by choosing a state of the target type in that issue's team, not by state name across teams.
+- **Priority** is an integer: 0 none, 1 urgent, 2 high, 3 medium, 4 low.
+- **Descriptions and comments** are Markdown.
+- **Projects** span teams; set `projectId` on the issue. **Cycles** are per team; set `cycleId` to a cycle of the issue's team (find the active one via the team's `activeCycle`).
+- **Filtering** happens on the server: `issues(filter: { team: { key: { eq: "ENG" } }, state: { type: { nin: ["completed", "canceled"] } }, updatedAt: { gt: $since } })`. Never fetch everything and filter client-side.
+- **Idempotency:** Linear has no idempotency key. Store your external ID (for example in an attachment URL or your own table) and check before creating. Attachments with the same URL on one issue are deduplicated, which makes `attachmentCreate` a good link-back anchor.
+
+## Pagination
+
+- Connections are Relay-style: `first` / `after` (or `last` / `before`), returning `nodes` and `pageInfo { hasNextPage endCursor }`. Default page size is 50.
+- Loop: pass `endCursor` as `after` while `hasNextPage` is true. In the SDK, `connection.fetchNext()` appends the next page.
+- Default order is `createdAt`; use `orderBy: updatedAt` for incremental sync, and store the last `updatedAt` you processed.
+- Avoid nested connections inside a paged list (issues, each with all comments, each with all reactions); page the inner data separately. Nested pages multiply complexity.
+
+## Webhooks
+
+1. Create the webhook in workspace settings (or with the `webhookCreate` mutation, admin scope), choosing resource types (Issue, Comment, Project, Cycle and others). Note its signing secret.
+2. Verify every request: `Linear-Signature` is the hex HMAC-SHA256 of the **raw** body with the signing secret. Compute it before parsing JSON; compare with a constant-time function.
+3. Reject replays: `webhookTimestamp` in the body (milliseconds) must be within about one minute of now.
+4. Respond `200` within 5 seconds and process from a queue. Linear retries failures up to 3 times (after 1 minute, 1 hour and 6 hours) and may disable a webhook that keeps failing.
+5. Route on `type` and `action` (`create`, `update`, `remove`); for updates, `updatedFrom` holds the previous values. Ignore changes your own integration made (compare `actor`) to avoid loops.
+6. Payloads may be stale by the time you process them; re-query the issue if you need current state.
+
+## Rate limits
+
+Per hour (check the docs, they change): API key 2,500 requests and 3,000,000 complexity points per user; OAuth app 5,000 requests and 2,000,000 points per user or app user; unauthenticated 600 requests per IP. A single query over 10,000 complexity points is rejected.
+
+- Read `X-RateLimit-Requests-Remaining`, `X-RateLimit-Complexity-Remaining` and `X-Complexity` (this query's cost). Reset headers are UTC epoch **milliseconds**.
+- When limited, Linear returns HTTP 400 with `errors[].extensions.code == "RATELIMITED"`. Wait until the relevant reset time, then retry with backoff and a retry cap. Do not treat every 400 as a rate limit; check the code.
+- Lower cost: smaller `first`, fewer fields, no deep nesting, filters instead of scans, webhooks instead of polling.
+
+## Stop and ask the user
+
+- Before bulk updates, moves or archiving across many issues; show the filter and the count first.
+- Before requesting the `admin` scope or creating workspace-wide webhooks.
+- Before an agent or bot acts as a person (`actor=user`) rather than as the app.
+
+## Before you finish
+
+Test against a test workspace or team: a list longer than one page, an issue created and moved to a completed state in its own team, a duplicate create (no second issue), a webhook with a bad signature and one with a stale `webhookTimestamp` (both rejected), and a `RATELIMITED` response handled with a wait. Linear's developer docs at linear.app/developers are the final word on schema and limits.

package/skills/linear-integration/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Create Linear issues from our error tracker using the Linear GraphQL API",
+    "Verify the Linear-Signature header on webhooks our server receives from Linear",
+    "Our Linear sync gets RATELIMITED errors, how do we stay under the complexity limit?",
+    "Should our Linear bot use a personal API key or OAuth with actor=app?",
+    "Page through every issue in the current Linear cycle with the @linear/sdk",
+    "Move a Linear issue to the team's completed state when the PR merges"
+  ],
+  "should_not_trigger": [
+    "Move a Jira ticket to In Review when a pull request is opened",
+    "Plan the next sprint and pick which tickets fit",
+    "Write a GraphQL schema for our own product API",
+    "Turn on Linear's built-in GitHub integration in workspace settings so PRs link to issues",
+    "Post a Slack message whenever a deploy finishes"
+  ]
+}

package/skills/literature-review/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: literature-review
+description: Scientific literature review that plans a reproducible search across PubMed, Google Scholar and arXiv, screens papers against written inclusion and exclusion criteria, appraises study design and risk of bias, extracts effect sizes into a table, cites each claim to a DOI or PMID, and states how certain the evidence is. Use when someone needs a literature review, a background or related-work section for a paper or grant, an evidence summary on a scientific or clinical question, or a PRISMA-style record of how studies were found and screened.
+license: MIT
+compatibility: Any Agent Skills host. Searching needs network access to PubMed (NCBI E-utilities), arXiv and Google Scholar; without it, work only from papers the user supplies.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: data
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Literature review
+
+Produce a review a reader could repeat: the same search, the same screening rules, and every claim traceable to a paper you actually read.
+
+## Scope and limits
+
+- This skill organises and summarises published evidence. It is **not** a formal systematic review, meta-analysis or clinical guideline. If the output will inform patient care, regulatory submissions or a published systematic review, say so and tell the user a qualified reviewer (and, for a systematic review, a second independent screener and an information specialist) must check it.
+- Never invent a paper, author, DOI, PMID, page number, sample size or effect size. If you cannot open a source, say "not retrieved" rather than guessing what it says.
+
+## 1. Frame the question (stop and ask if unclear)
+
+1. Write the question in one sentence. For clinical or intervention questions, break it into PICO: Population, Intervention or exposure, Comparator, Outcome. For other fields use the closest equivalent (system, method, baseline, metric).
+2. Agree with the user on: review type (narrative overview, scoping review, or systematic-style), date range, languages, study types wanted, and the deliverable (related-work section, evidence table, full report).
+3. If the user cannot state the outcome they care about, stop and ask. A review without a defined outcome cannot be screened.
+
+## 2. Write the inclusion and exclusion criteria before searching
+
+Record them as a short list, for example:
+
+- Include: peer-reviewed primary studies or preprints, 2015 onward, adult humans, reports outcome X.
+- Exclude: editorials, conference abstracts without data, animal-only studies, duplicate reports of the same cohort.
+
+Decide now how preprints are handled (included but flagged is the usual choice). Do not change the criteria after seeing results without noting the change and why.
+
+## 3. Build and run the search
+
+1. List synonyms and controlled vocabulary for each concept. Combine synonyms with `OR`, concepts with `AND`.
+2. Run the strategy in each source and record the exact query string, the date run and the hit count. Source-specific syntax, field tags and API endpoints are in `references/search-sources.md`.
+3. Use at least two sources. PubMed for biomedicine, arXiv for physics, maths, CS and quantitative fields, Google Scholar for breadth and grey literature (its results are not reproducible, so record it as supplementary).
+4. Snowball: check the reference lists of key included papers (backward) and papers that cite them (forward).
+5. Respect source limits: NCBI E-utilities allow 3 requests per second without an API key and 10 with one; the arXiv API asks for no more than one request every three seconds on a single connection. Do not scrape Google Scholar programmatically.
+
+## 4. Screen
+
+1. De-duplicate by DOI, then by title and first author.
+2. Screen titles and abstracts against the criteria; then screen full texts for anything that passes.
+3. Log every exclusion at full-text stage with one reason from your criteria list.
+4. Keep counts for each stage (identified, duplicates removed, screened, full texts assessed, excluded with reasons, included). These are the numbers a PRISMA 2020 flow diagram needs.
+
+## 5. Appraise quality
+
+Judge each included study by its design before you weigh its findings. Use the checklist in `references/appraisal.md`:
+
+- Design hierarchy as a starting point: systematic reviews of RCTs, RCTs, cohort, case-control, cross-sectional, case series, expert opinion. Benchmarks and simulation studies in computational fields are judged on dataset, baselines, and whether code and data are available.
+- Named tools when the field uses them: Cochrane RoB 2 for randomised trials, ROBINS-I for non-randomised intervention studies, Newcastle-Ottawa Scale for cohort and case-control studies.
+- Always note: sample size, preregistration, conflicts of interest, funding, retractions (check the journal page or Retraction Watch), and whether the result has been replicated.
+
+## 6. Extract findings
+
+Fill one row per study in an evidence table:
+
+| Study (first author, year) | ID (DOI/PMID/arXiv) | Design | N | Population | Intervention / method | Comparator | Outcome and effect (with CI or error) | Risk of bias | Notes |
+
+- Copy numbers exactly as reported, with units and the confidence interval or standard error. Mark values you computed yourself.
+- Report the effect measure the paper uses (risk ratio, odds ratio, mean difference, accuracy); never convert between them without saying so.
+
+## 7. Synthesise and state uncertainty
+
+1. Group studies by outcome, then by design. Describe agreement and disagreement; explain disagreements by design, population or method where you can.
+2. Do not count votes ("7 studies positive, 3 negative") as evidence strength. Weigh by size, design and risk of bias.
+3. Rate certainty per main outcome. For health questions use GRADE wording (high, moderate, low, very low) and give the reasons for downgrading: risk of bias, inconsistency, indirectness, imprecision, publication bias. For other fields use the same four words and the same reasons in plain language.
+4. Name the gaps: populations not studied, outcomes not measured, methods never compared.
+5. Do not pool numbers into a meta-analysis unless the user asked for one and the studies are comparable; if pooled, a statistician should check it.
+
+## 8. Cite correctly
+
+- Cite every factual claim to a specific paper. Prefer the DOI; give PMID or arXiv ID too when present.
+- Cite the version you read. If a preprint has since been published, cite the published version and say so.
+- Use the style the user names (Vancouver, APA, a journal's own). If none is given, use author-year in text and a full reference list with DOIs.
+- Quote sparingly and with page or section. Paraphrase faithfully; never strengthen a hedged finding ("associated with" stays "associated with", not "causes").
+
+## Never
+
+- Cite a paper from its abstract alone when the claim depends on methods or numbers in the full text; mark it "abstract only" if that is all you could access.
+- Present a Google Scholar-only or unsearched topic as comprehensive.
+- Drop studies that contradict the expected answer.
+
+## Report format
+
+```
+# <Question>
+Scope: <review type, date range, sources, date searched>
+## Search
+<source>: <exact query> (<date>, <hits>)  ... one line per source
+## Screening
+Identified N, duplicates N, screened N, full text N, excluded N (reasons), included N
+## Evidence table
+<table from step 6>
+## Synthesis
+<per outcome: what the evidence shows, certainty rating, reasons>
+## Gaps and limitations
+<including limits of this review itself>
+## References
+<full list with DOIs>
+```
+
+If the user wants only a related-work section, still keep the search and screening log as an appendix so the review can be checked.

package/skills/literature-review/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Do a literature review on whether intermittent fasting improves insulin sensitivity in adults, with the PubMed search strings you used",
+    "I need a related-work section for my paper on graph neural networks for protein folding, pull the key arXiv papers and cite them properly",
+    "Summarise the published evidence on microplastics in drinking water and how confident we can be in it",
+    "Help me set inclusion criteria and screen these 40 abstracts for a scoping review on telehealth in rural clinics",
+    "Appraise the risk of bias in these five RCTs on vitamin D and depression and build an evidence table"
+  ],
+  "should_not_trigger": [
+    "Compare three Python job queue libraries and recommend one with links to their docs",
+    "Run a differential expression analysis on my RNA-seq counts table",
+    "Size the market for a lab notebook SaaS and list the competitors",
+    "Write the methods section describing the statistical tests I ran in my own experiment",
+    "Clean up my Jupyter notebook so the statistics in it are reproducible"
+  ]
+}

package/skills/literature-review/references/appraisal.md

@@ -0,0 +1,41 @@
+# Appraising study quality
+
+Read this in step 5. Record a judgement and a one-line reason for every item; "unclear" is an allowed answer.
+
+## Any primary study
+
+1. Is the question and primary outcome stated in advance (registration, protocol, preregistration)?
+2. Is the sample size adequate, and was it justified (power calculation)?
+3. How were participants or data selected? Could selection explain the result?
+4. Are the comparison groups comparable at baseline?
+5. Were outcomes measured the same way in every group, ideally blind to group?
+6. How much missing data or loss to follow-up, and how was it handled?
+7. Are confounders measured and adjusted for (observational designs)?
+8. Are all prespecified outcomes reported, or only the significant ones?
+9. Effect size with a confidence interval, not just a p-value?
+10. Funding source and conflicts of interest declared?
+11. Retracted, corrected or subject to an expression of concern?
+
+## Named tools
+
+| Design | Tool | Domains (summary) |
+|---|---|---|
+| Randomised trial | Cochrane RoB 2 | randomisation process, deviations from intended interventions, missing outcome data, outcome measurement, selection of the reported result |
+| Non-randomised intervention study | ROBINS-I V2 (Nov 2025 draft; check riskofbias.info for the current version) | confounding, classification of intervention, selection into the study, missing data, measurement of the outcome, selection of the reported result (V2 dropped the 2016 version's deviations-from-intended-interventions domain) |
+| Cohort or case-control | Newcastle-Ottawa Scale | selection, comparability, outcome or exposure |
+| Diagnostic accuracy | QUADAS-2 | patient selection, index test, reference standard, flow and timing |
+| Systematic review | AMSTAR 2 | 16 items, including protocol, search, duplicate selection and extraction, risk-of-bias assessment, meta-analysis methods, publication bias |
+
+Apply the tool's official guidance documents; this table is a reminder, not a substitute. Sources: RoB 2 and ROBINS-I at https://www.riskofbias.info/ , Cochrane Handbook chapter 8 (https://www.cochrane.org/authors/handbooks-and-manuals/handbook/current/chapter-08), QUADAS-2 (Whiting 2011, PMID 22007046), AMSTAR 2 (https://amstar.ca/Amstar_Checklist.php), GRADE Handbook (https://gdt.gradepro.org/app/handbook/handbook.html).
+
+## Computational and benchmark studies
+
+- Dataset: public, described, and free from train/test leakage?
+- Baselines: strong, recent and tuned with the same effort?
+- Variance: multiple seeds or runs, with error bars?
+- Code and data available, and does the reported result reproduce?
+- Claims match the evaluation (no general claims from one dataset)?
+
+## Certainty of a body of evidence (GRADE-style)
+
+Start high for randomised evidence and low for observational evidence, then move down for: risk of bias, inconsistency (results disagree), indirectness (different population or outcome from the question), imprecision (wide intervals, small samples), publication bias. Observational evidence may move up for a large effect, a dose-response gradient, or when all plausible residual confounding would have reduced the observed effect. State the final level (high, moderate, low, very low) and each reason.

package/skills/literature-review/references/search-sources.md

@@ -0,0 +1,39 @@
+# Search sources
+
+Read this when building or running the search in step 3.
+
+## PubMed
+
+- Web: https://pubmed.ncbi.nlm.nih.gov/ . Use "Advanced" to see the query translation PubMed actually ran, and record it.
+- Field tags: `[tiab]` title/abstract, `[mh]` MeSH heading, `[majr]` MeSH major topic, `[au]` author, `[dp]` publication date, `[pt]` publication type.
+- Example: `("sleep deprivation"[mh] OR "sleep restriction"[tiab]) AND ("working memory"[tiab] OR "memory, short-term"[mh]) AND 2015:2025[dp]`
+- Look up MeSH terms in the MeSH database before relying on them; newer papers may not be indexed with MeSH yet, so always pair `[mh]` with `[tiab]` synonyms.
+- Programmatic access, NCBI E-utilities, base `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/`:
+  - `esearch.fcgi?db=pubmed&term=<query>&retmax=200&usehistory=y` returns PMIDs (and a WebEnv for large sets).
+  - `efetch.fcgi?db=pubmed&id=<pmids>&rettype=abstract&retmode=xml` returns records.
+  - `esummary.fcgi?db=pubmed&id=<pmids>` returns brief metadata.
+  - Pass `tool`, `email` and, if you have one, `api_key`. Limit: 3 requests/second without a key, 10 with one.
+- Biopython wrapper: `Bio.Entrez` (set `Entrez.email` first).
+
+## arXiv
+
+- Web search: https://arxiv.org/search/ ; API: `https://export.arxiv.org/api/query?search_query=<q>&start=0&max_results=100` returns Atom XML.
+- Field prefixes: `ti:` title, `abs:` abstract, `au:` author, `cat:` category (for example `cat:cs.LG`), `all:`. Combine with `AND`, `OR`, `ANDNOT`.
+- Example: `search_query=abs:"graph neural network" AND cat:q-bio.QM`. URL-encode it in the request: spaces as `+`, quotes as `%22` (`abs:%22graph+neural+network%22+AND+cat:q-bio.QM`).
+- Terms of use: no more than one request every three seconds, one connection at a time.
+- arXiv papers are preprints and are not peer reviewed. Check whether a later published version exists (the arXiv page often lists a journal reference or DOI).
+
+## Google Scholar
+
+- Useful for breadth, citations ("Cited by" for forward snowballing) and grey literature.
+- Operators documented in Scholar help: quotes for phrases, `author:`, `site:`; use Advanced search for title-only words and the sidebar for a date range. Each query returns at most 1,000 results.
+- Results are personalised and change over time; record them as supplementary and not as a reproducible search. No official API; do not scrape it.
+
+## Other sources worth naming to the user
+
+- Europe PMC (includes preprints and full text, has a REST API), Semantic Scholar (API with citation graph), Crossref (DOI metadata), bioRxiv / medRxiv (life-science preprints), Cochrane Library (systematic reviews), ClinicalTrials.gov (registered and unpublished trials), field databases such as Embase, Web of Science, Scopus, PsycINFO, IEEE Xplore, ACM DL (often need an institutional subscription).
+
+## Search log template
+
+| Source | Date run | Exact query | Filters | Hits | Exported to |
+|---|---|---|---|---|---|

package/skills/llm-app-patterns/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: llm-app-patterns
+description: Engineering patterns for shipping LLM-backed product features in application code, covering schema-validated structured output, timeouts and bounded retries, streaming responses, prompt caching and token budgets, choosing a model tier, defending against prompt injection from untrusted content, and logging each call so it can be evaluated later. Use when wiring a model API call into a backend or app, hardening an existing LLM feature for production, cutting its latency or cost, or handling tool output and user documents that reach the model.
+license: MIT
+compatibility: Any Agent Skills host. Provider-neutral; applies to any model API or SDK in any backend language.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: ai
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# LLM app patterns
+
+Treat a model call like any other unreliable network dependency that returns untrusted text. This skill covers the code around the call. For wording the prompt itself, use `prompt-engineering`; for measuring quality, use `llm-evals`; for retrieval pipelines, use `rag-pipeline-patterns`.
+
+## 0. Before you write code
+
+1. Find what the project already uses: search for the provider SDK import, an existing client wrapper, env vars holding API keys, and any logging or tracing of model calls. Extend that; don't add a second client.
+2. Write down the feature contract in one or two lines: input, output shape, latency budget, and what the user sees when the model fails.
+3. If there is no fallback behaviour for "model unavailable" and the feature is user-facing, **stop and ask the user** what should happen (hide the feature, show an error, use a non-LLM default).
+
+## 1. Structured output
+
+1. Define the output as a schema in code (JSON Schema, Zod, Pydantic, a typed struct). That schema is the source of truth for the prompt, the parser and the tests.
+2. Use the provider's native structured output or tool/function calling with that schema when available. Otherwise ask for JSON only and parse strictly.
+3. **Always validate** the parsed result against the schema in your code, even when the provider claims to enforce it. Reject unknown enum values and out-of-range numbers.
+4. On a validation failure: retry once, sending the validation error back to the model. If it fails again, return the defined fallback. Never pass unvalidated model output to a database write, a shell, a SQL query, an HTML page or another tool.
+5. Keep schemas flat and small. Add an explicit "unknown" or `null` option so the model is not forced to invent a value.
+
+## 2. Timeouts, retries and failure
+
+- Set a client timeout on every call. Streaming calls get a time-to-first-token timeout and an overall timeout.
+- Check the SDK's own retry behaviour before adding yours. The official OpenAI and Anthropic SDKs already retry connection errors, 408, 409, 429 and 5xx (2 retries by default, configurable with `max_retries`). Wrapping your own retry loop around that multiplies the attempts; either tune the SDK setting or disable it and own the loop.
+- Retry only transient failures: timeouts, connection errors, 408, 429, 5xx and provider "overloaded" errors. Use exponential backoff with jitter and honour a `retry-after` header if present. Cap the total at 2 to 3 attempts.
+- Don't retry other 4xx errors (bad request, auth, permission, not found, request too large): fix the request instead.
+- Put a per-user and global concurrency limit in front of the API so a traffic spike cannot burn the rate limit for everyone.
+- If an action has side effects (sending an email, calling a tool that writes), make the retry idempotent or don't retry the step that has the side effect.
+
+## 3. Streaming
+
+- Stream when a human is waiting on long free text. Don't stream when the output must be validated as a whole before use (structured output feeding code).
+- Forward chunks to the client as they arrive (SSE or WebSocket), and handle the stream ending early: show partial text as incomplete, never as final.
+- Read the final usage and stop reason from the end of the stream and log them. A stop because of the max-token limit means the answer is truncated; treat it as a failure for structured output.
+- Cancel the upstream request when the client disconnects so you stop paying for tokens nobody reads.
+
+## 4. Cost and latency
+
+1. Measure first: log input tokens, output tokens, cached tokens and latency per call (section 6). Optimise the call that costs the most, not the one you suspect.
+2. **Prompt caching:** put stable content first (system prompt, tool definitions, long reference documents, few-shot examples) and variable content (the user's turn) last. Some providers cache matching prefixes automatically; others need an explicit cache marker on the stable block. Check the provider's docs for the minimum cacheable length and cache lifetime, and confirm hits in the usage fields.
+3. Don't put timestamps, request IDs or per-user data at the top of the prompt: they break the cached prefix.
+4. Set `max_tokens` (or the provider's equivalent) to what the feature needs, not the model maximum.
+5. Trim context: send only the fields the task needs, summarise long histories, and cap retrieved documents.
+6. Cache whole responses in your own store only for deterministic, non-personal requests, keyed on model + prompt version + normalised input.
+7. Use batch APIs for offline jobs that can wait.
+
+## 5. Model selection
+
+- Start with the most capable model to prove the feature works and to build the eval set, then try a smaller, cheaper or faster tier and keep it only if it passes the same evals.
+- Route by task: a small model for classification, extraction and routing; a larger one for multi-step reasoning or long writing.
+- Pin an exact model version in config, not a floating alias, so behaviour doesn't change under you. Upgrading the model is a change that must re-run the evals.
+- Keep the model name, temperature and max tokens in config next to the prompt version, not scattered through code.
+
+## 6. Prompt injection and untrusted content
+
+Anything the model reads that you did not write is untrusted: user messages, uploaded files, web pages, emails, retrieved documents and tool results.
+
+1. Keep instructions in the system prompt. Put untrusted content in clearly delimited blocks (for example XML-style tags) and say in the instructions that text inside them is data, not instructions.
+2. **Assume injection will sometimes succeed** and limit the damage: give the model only the tools the task needs, scope credentials to the current user, and enforce authorisation in your code, never by asking the model to check.
+3. Require human confirmation before irreversible or external actions the model proposes (payments, sending messages, deleting data).
+4. Never render model output as raw HTML or Markdown that can load remote images or links without sanitising; that is a data-exfiltration path.
+5. Don't put secrets in prompts. Assume the system prompt can be extracted.
+6. Add injection attempts to the eval set (`llm-evals`) so a prompt change cannot quietly remove a defence.
+
+## 7. Logging for evaluation
+
+Log one record per model call, with the project's normal logger or tracing system:
+
+```
+{ request_id, feature, prompt_version, model, params, input_tokens, output_tokens,
+  cached_tokens, latency_ms, stop_reason, validation_ok, retry_count, error, user_feedback }
+```
+
+- Log full prompts and outputs only where the project's privacy rules allow it. Redact or hash personal data and secrets before storage, and set a retention period. If unsure, **stop and ask the user**.
+- Version prompts like code (a constant or file with a version string) and log the version, so a regression can be traced to a change.
+- Capture explicit user feedback (thumbs, edits, retries) against the `request_id`. Those records become eval cases.
+
+## Never
+
+- Never trust model output as authorisation, as a safe identifier, or as already validated.
+- Never send API keys to a browser or mobile client; call the model from your server.
+- Never retry without a cap, or loop on tool calls without a maximum step count.
+- Never ship a prompt or model change without re-running the evals.
+
+## Report back
+
+End with: the files changed, the schema and fallback chosen, timeout and retry settings, how caching is arranged, what is logged, and any risk left open (for example "no eval set yet").

package/skills/llm-app-patterns/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Our summarize endpoint calls the model and sometimes returns broken JSON, make it return a validated object every time",
+    "Add retries with backoff and a timeout around the OpenAI call in our ticket classifier",
+    "The chat feature is too expensive, help me restructure the prompt so prompt caching actually hits",
+    "Stream the assistant's reply to the browser over SSE and cancel the request if the user closes the tab",
+    "Users can upload PDFs that get sent to the LLM, how do we stop instructions inside those files from hijacking it?"
+  ],
+  "should_not_trigger": [
+    "Rewrite this system prompt so the model stops ignoring the tone guidelines",
+    "Build a test set of 50 cases and a grader to score our extraction feature",
+    "Chunk our docs and set up vector search for the support bot",
+    "Write an MCP server that exposes our inventory database as tools",
+    "Fine-tune a PyTorch model on our labelled images",
+    "Design the planner and executor loop and tool permissions for our coding agent harness"
+  ]
+}