@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/clickhouse-patterns/references/engines-and-views.md

@@ -0,0 +1,138 @@
+# ClickHouse engines and materialised view recipes
+
+Read this when choosing an engine, writing a rollup, or deduplicating. Check syntax against clickhouse.com/docs for the server version in use. On ClickHouse Cloud, write the plain engine name (`MergeTree`, `ReplacingMergeTree`); the service maps it to its shared engine. On a self-hosted cluster, use the `Replicated*` variant with the `ON CLUSTER` conventions the existing tables use.
+
+## Choosing an engine
+
+| Engine | Merges rows with the same sorting key by | Use for |
+|---|---|---|
+| `MergeTree` | nothing (keeps all rows) | raw events, logs, append-only facts |
+| `ReplacingMergeTree(version)` | keeping the row with the highest `version` (or the last inserted) | latest state per entity, upserts, CDC from OLTP |
+| `SummingMergeTree` | summing numeric columns | simple counters per key |
+| `AggregatingMergeTree` | merging `AggregateFunction` states | rollups with `uniq`, `quantile`, `avg` |
+| `CollapsingMergeTree(sign)` / `VersionedCollapsingMergeTree` | cancelling `+1`/`-1` row pairs | changing aggregates with explicit cancel rows |
+
+All merging is eventual. Queries must be correct before merges happen.
+
+## Raw events table
+
+```sql
+CREATE TABLE analytics.events
+(
+    tenant_id   UInt32,
+    event_type  LowCardinality(String),
+    ts          DateTime64(3),
+    user_id     UInt64,
+    session_id  String,
+    props       String CODEC(ZSTD(3))
+)
+ENGINE = MergeTree
+PARTITION BY toYYYYMM(ts)
+ORDER BY (tenant_id, event_type, toDate(ts), user_id)
+TTL toDateTime(ts) + INTERVAL 13 MONTH
+SETTINGS ttl_only_drop_parts = 1;
+```
+
+## Latest state with ReplacingMergeTree
+
+```sql
+CREATE TABLE app.users_latest
+(
+    user_id    UInt64,
+    email      String,
+    plan       LowCardinality(String),
+    updated_at DateTime64(3),
+    is_deleted UInt8 DEFAULT 0
+)
+ENGINE = ReplacingMergeTree(updated_at)
+ORDER BY user_id;
+```
+
+Read the current state either way:
+
+```sql
+SELECT * FROM app.users_latest FINAL WHERE is_deleted = 0;
+
+SELECT user_id, argMax(plan, updated_at) AS plan
+FROM app.users_latest
+GROUP BY user_id;
+```
+
+`FINAL` is much cheaper on recent versions than it used to be, but still costs more than a plain read; measure it. Newer versions also accept an `is_deleted` column as a second engine parameter; check the docs for your version before relying on it.
+
+## Daily rollup with AggregatingMergeTree
+
+```sql
+CREATE TABLE analytics.daily_events
+(
+    tenant_id  UInt32,
+    day        Date,
+    event_type LowCardinality(String),
+    events     SimpleAggregateFunction(sum, UInt64),
+    users      AggregateFunction(uniq, UInt64)
+)
+ENGINE = AggregatingMergeTree
+PARTITION BY toYYYYMM(day)
+ORDER BY (tenant_id, day, event_type);
+
+CREATE MATERIALIZED VIEW analytics.daily_events_mv TO analytics.daily_events AS
+SELECT tenant_id, toDate(ts) AS day, event_type,
+       count() AS events,
+       uniqState(user_id) AS users
+FROM analytics.events
+GROUP BY tenant_id, day, event_type;
+```
+
+Query it with merge functions, always grouping:
+
+```sql
+SELECT day, sum(events) AS events, uniqMerge(users) AS users
+FROM analytics.daily_events
+WHERE tenant_id = 42 AND day >= today() - 30
+GROUP BY day ORDER BY day;
+```
+
+Backfill existing data once, in chunks by partition, with the same SELECT as the view:
+
+```sql
+INSERT INTO analytics.daily_events
+SELECT tenant_id, toDate(ts) AS day, event_type, count(), uniqState(user_id)
+FROM analytics.events
+WHERE toYYYYMM(ts) = 202609
+GROUP BY tenant_id, day, event_type;
+```
+
+To avoid double counting, create the view first, note the time, and backfill only rows before it, or pause ingestion during the switch.
+
+## Materialised view gotchas
+
+- The view's SELECT runs on each inserted **block**, not on the whole table. A `GROUP BY` in it aggregates within the block only; the target engine finishes the job.
+- A failing view makes the insert into the source fail. Test the view's SELECT on sample data first.
+- Joins inside an incremental view read the right-hand table at insert time; later changes to it don't update old rows. Use a dictionary or a refreshable view instead.
+- Changing a view: create the new target and view, backfill, switch readers, then drop the old ones.
+
+## Refreshable view
+
+```sql
+CREATE MATERIALIZED VIEW reports.top_customers
+REFRESH EVERY 1 HOUR
+ENGINE = MergeTree ORDER BY revenue
+AS SELECT customer_id, sum(amount) AS revenue
+FROM sales.orders
+GROUP BY customer_id
+ORDER BY revenue DESC
+LIMIT 100;
+```
+
+Each refresh replaces the content atomically. Check status in `system.view_refreshes`.
+
+## Useful system tables
+
+| Table | Use |
+|---|---|
+| `system.query_log` | slow and heavy queries, `read_rows`, `memory_usage` |
+| `system.parts` | active part counts and sizes per partition |
+| `system.merges` | merges in progress |
+| `system.mutations` | `ALTER ... UPDATE/DELETE` progress (`is_done`) |
+| `system.columns` | compressed vs uncompressed size per column |
+| `system.replication_queue` | replicated table backlogs (self-hosted) |

package/skills/clinical-decision-support/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: clinical-decision-support
+description: Engineering discipline for software that recommends or warns at the point of care, including CDS Hooks services (discovery, patient-view and order-sign hooks, prefetch, cards, suggestions, feedback), alert design that avoids alert fatigue, versioned rule logic tied to cited evidence, clinician sign-off and regression testing on synthetic cases, override and audit trails, and the regulatory line where software becomes a medical device (FDA CDS guidance, EU MDR Rule 11, UK DCB0129). Use when building drug-interaction or dosing alerts, risk scores, care-gap reminders or AI suggestions shown to clinicians, writing a CDS Hooks service, or deciding whether a clinical feature needs regulatory or clinical-safety review.
+license: MIT
+compatibility: Any Agent Skills host. Works on any codebase; CDS Hooks testing needs a FHIR sandbox or the CDS Hooks sandbox. Regulatory statements must be checked against current FDA, EU and national guidance by a qualified person.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: compliance
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Clinical decision support
+
+Build decision support that clinicians trust: it fires rarely and correctly, shows its reasoning and evidence, can be overridden with a reason, is traceable to a reviewed rule version, and stays on the right side of medical device regulation.
+
+## Boundary: not clinical, legal or regulatory advice
+
+- You engineer the system. You never author or approve clinical content (thresholds, doses, interactions, risk cut-offs). A named clinician owns every rule and signs off each version.
+- You never decide whether the product is a regulated medical device. You flag the questions; regulatory affairs or counsel decides.
+- Say this once, plainly, when the user asks for clinical thresholds or a regulatory verdict, then continue with the engineering. Never invent a clinical threshold to fill a gap; leave a named placeholder and stop.
+
+## Step 1: classify the feature before building
+
+Answer these and write the answers into the design doc:
+
+1. **Who sees it?** A healthcare professional, a patient or caregiver, or nobody (automatic action)?
+2. **What does it do?** Display reference information, flag something for review, recommend one action, or take an action automatically?
+3. **What are the inputs?** Structured data and published guidelines, or medical images, signals (ECG, waveforms) or IVD data?
+4. **Can the clinician independently review the basis?** Are the inputs, logic and evidence shown so they need not rely on the software alone?
+5. **Is it time-critical?** Would a clinician have time to review the basis before acting?
+
+Then apply the regulatory flags in `references/regulatory-boundaries.md`. If the feature analyses images or signals, targets patients directly, acts automatically, is opaque (for example an ML model whose basis the clinician cannot review), or is used in time-critical decisions, **stop and tell the user it needs regulatory review before build**.
+
+## Step 2: design the intervention
+
+- **Fire only when actionable.** Every alert names one specific patient, finding and action. If nobody can act on it right now, it is not an interruptive alert: make it passive (a chart flag, a worklist, `info` card) or drop it.
+- **Right time, right person.** Trigger at the workflow step where the decision is made (for drug checks: `order-select` or `order-sign`, not `patient-view`). Target the role that can act.
+- **Severity is earned.** Reserve interruptive or `critical` for harm that is likely and serious. Tier everything else. Track the override rate per rule; a rule overridden most of the time is noise and needs clinical review.
+- **Show the why.** Include the triggering data (values, dates), the rule's logic in plain words, and a link to the evidence source.
+- **Make the right action one click.** Offer a concrete suggestion (adjust dose, order test, discontinue) and allow override with a structured reason.
+- **Suppress duplicates.** Don't re-fire the same alert for the same patient and data in one session; respect snoozes and documented exceptions.
+- **Fail safe and visible.** If the CDS service is down or data is missing, show nothing interruptive but never imply "no issues found". Missing inputs must not be treated as normal values.
+
+## Step 3: build the logic as versioned, reviewable artefacts
+
+- Keep rules in data or a dedicated module (for example CQL libraries, or a rules table), not scattered through UI code.
+- Each rule has: ID, semantic version, owner clinician, evidence citation (guideline, version, date), inputs with code systems (LOINC, SNOMED CT, RxNorm), logic, outputs, effective date, review-by date.
+- Units and codes are explicit. Convert units with a library (UCUM), never assume. Handle `preliminary`, `corrected` and `entered-in-error` source data.
+- Every change goes through code review **and** clinical review, and bumps the rule version. Record who approved and when.
+
+## Step 4: implement the delivery
+
+For EHR-embedded CDS use CDS Hooks as in `references/cds-hooks.md`: a discovery endpoint, one service per hook, prefetch templates for the data you need, cards with `summary`, `indicator`, `source` and suggestions, and the feedback endpoint to capture accept/override. Authenticate the EHR's JWT on every call and use the `fhirAuthorization` token only for the patient in context.
+
+## Step 5: test with clinicians
+
+1. Build a test set of synthetic patients (never real records) per rule: must fire, must not fire, boundary values, missing data, unit variants, corrected results, duplicate orders.
+2. Store expected outputs and run them as automated regression tests on every change.
+3. A clinician reviews the cases and the card wording before release and signs the test report.
+4. Pilot silently first where possible ("shadow mode": evaluate and log, don't show) and compare fire rates with expectations.
+
+## Step 6: audit and monitor
+
+Log, for every evaluation that produced output: timestamp, rule ID and version, patient reference (internal ID, not name), user, hook instance, card shown, action taken, override reason. Keep it append-only and access-controlled like other PHI logs (`hipaa-compliance`). Review override rates, fire rates and reported incidents on a schedule, and give clinicians a way to report a bad alert.
+
+## Stop and ask the user
+
+- Before writing any clinical threshold, dose, interaction or score cut-off: ask who the clinical owner is and for the source.
+- When Step 1 raises a regulatory flag.
+- Before making any alert interruptive, or any action automatic.
+- Before shipping a rule change without recorded clinical sign-off.
+
+## Never
+
+- Never auto-order, auto-cancel or auto-change medication or orders without explicit clinical governance approval.
+- Never hide the inputs or reasoning behind a recommendation.
+- Never treat missing data as normal.
+- Never ship ML-based suggestions as if they were rule-based, or without documented validation on the target population.
+- Never let a CDS outage silently disable safety checks without telling users.
+
+## Report format
+
+```
+Feature: <name>, audience, hook or trigger point
+Classification: <answers to Step 1>, regulatory flags: <none | list → needs regulatory review>
+Rules: <ID@version, owner, evidence source> per rule
+Test coverage: <cases per rule, clinician sign-off status>
+Open items for clinical/regulatory owners: <list>
+```

package/skills/clinical-decision-support/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Build a CDS Hooks service that warns at order-sign when a renally cleared drug is ordered for a patient with low eGFR",
+    "Our sepsis alert fires constantly and nurses override 95% of them, how should we redesign it?",
+    "Does our symptom checker that recommends a diagnosis to patients count as a medical device under FDA rules?",
+    "Set up versioning, clinician sign-off and regression tests for our medication dosing rules",
+    "How do we audit which decision support cards were shown, accepted or overridden by each clinician?"
+  ],
+  "should_not_trigger": [
+    "Fetch MedicationRequest resources from the EHR's FHIR API with a SMART standalone launch",
+    "Parse ORU^R01 lab results arriving over MLLP and send an ACK",
+    "Which HIPAA safeguards does our telehealth backend need for video visits?",
+    "Train a gradient boosting model to predict readmission and report its AUC",
+    "Review the clinic scheduling service for PHI in logs and missing consent checks"
+  ]
+}

package/skills/clinical-decision-support/references/cds-hooks.md

@@ -0,0 +1,76 @@
+# CDS Hooks implementation notes
+
+Source: CDS Hooks specification 2.0 (cds-hooks.hl7.org, STU 2, based on FHIR R4). Check the EHR vendor's docs for which hooks and features they support.
+
+## Endpoints
+
+| Endpoint | Purpose |
+|---|---|
+| `GET {base}/cds-services` | discovery: list of services with `hook`, `id`, `title`, `description`, `prefetch`, optional `usageRequirements` |
+| `POST {base}/cds-services/{id}` | invoke a service for a hook |
+| `POST {base}/cds-services/{id}/feedback` | the EHR reports which cards and suggestions were accepted or overridden |
+
+## Standard hooks
+
+`patient-view`, `order-select`, `order-sign`, `order-dispatch`, `appointment-book`, `encounter-start`, `encounter-discharge`, `medication-refill`, `allergyintolerance-create`, `problem-list-item-create`. (`medication-prescribe` and `order-review` are deprecated.) Each hook defines its `context` fields, for example `order-sign` carries `userId`, `patientId`, `encounterId` and `draftOrders` (a Bundle).
+
+## Discovery example
+
+```json
+{
+  "services": [{
+    "hook": "order-sign",
+    "id": "renal-dose-check",
+    "title": "Renal dose check",
+    "description": "Flags renally cleared drugs ordered for patients with reduced eGFR",
+    "prefetch": {
+      "patient": "Patient/{{context.patientId}}",
+      "egfr": "Observation?patient={{context.patientId}}&code=http://loinc.org|<egfr-code>&_sort=-date&_count=1"
+    }
+  }]
+}
+```
+
+Prefetch is an optimisation the EHR may skip: if a key is missing, fetch it from `fhirServer` with `fhirAuthorization.access_token`, and if neither is available return no cards rather than guessing. Log that the check could not run and count it, so an outage shows up in monitoring instead of looking like "no issues".
+
+## Request fields
+
+`hook`, `hookInstance` (UUID, use it as the correlation ID in audit logs), `fhirServer`, `fhirAuthorization` (`access_token`, `token_type`, `expires_in`, `scope`, `subject`), `context`, `prefetch`.
+
+## Security
+
+- The EHR sends a signed JWT bearer token in `Authorization`. Verify it on every request: signature against the EHR's JWK Set (from the optional `jku` header only if that URL is on your allowlist, otherwise a key exchanged out of band), `iss` on your allowlist of EHRs, `aud` equal to the URL of the endpoint being called (`{base}/cds-services/{id}`), `exp` not passed, `iat` present, `jti` not replayed.
+- Use the `fhirAuthorization` token only for the patient in context and discard it after the call.
+- Never log `prefetch` or `context` bodies; log `hookInstance`, service ID, rule versions and card UUIDs.
+
+## Response
+
+```json
+{
+  "cards": [{
+    "uuid": "6f0c...",
+    "summary": "Dose may be too high for eGFR 25 (under 140 chars)",
+    "detail": "Markdown: triggering values, the rule in plain words, evidence link",
+    "indicator": "warning",
+    "source": { "label": "Renal dosing rules v1.4.0", "url": "https://example.org/evidence" },
+    "suggestions": [{ "label": "Reduce dose", "uuid": "...", "isRecommended": true, "actions": [{ "type": "update", "description": "...", "resource": {} }] }],
+    "selectionBehavior": "at-most-one",
+    "overrideReasons": [{ "code": "benefit-outweighs-risk", "system": "https://example.org/override-reasons", "display": "Benefit outweighs risk" }],
+    "links": [{ "label": "Guideline", "url": "https://...", "type": "absolute" }]
+  }],
+  "systemActions": []
+}
+```
+
+- `indicator`: `info`, `warning`, `critical` (increasing urgency).
+- `selectionBehavior` is required when `suggestions` is present.
+- `systemActions` are applied by the EHR without showing the user: leave empty unless clinical governance has approved the automation.
+- Return `{"cards": []}` when nothing applies. Respond fast (the clinician is waiting); set a timeout budget well under the EHR's.
+
+## Feedback
+
+Give every card and suggestion a `uuid`: the EHR sends no feedback for a card or suggestion without one. Store each feedback item (`card`, `outcome` accepted/overridden, `acceptedSuggestions`, `overrideReason`, `outcomeTimestamp`) against the rule version. This is the data for override-rate and alert-fatigue review.
+
+## Testing
+
+The public CDS Hooks sandbox (sandbox.cds-hooks.org) can call a service you host and render its cards. Use synthetic patients only.

package/skills/clinical-decision-support/references/regulatory-boundaries.md

@@ -0,0 +1,37 @@
+# Regulatory boundaries for clinical software
+
+This is a map of questions to raise, not a determination. Regulatory affairs or counsel decides whether a product is a medical device, and the rules change: check the current text of each source before relying on it.
+
+## United States (FDA)
+
+- Basis: section 520(o)(1)(E) of the FD&C Act (added by the 21st Century Cures Act) excludes some CDS software from the device definition. FDA's "Clinical Decision Support Software" guidance explains how it reads the criteria; FDA lists a final version dated January 2026, which replaced the September 2022 version. Secondary summaries say it relaxed FDA's position on software that gives a single recommendation and refined its approach to time-critical use. Read the FDA text itself before relying on either point.
+- All four criteria must be met for the exclusion:
+  1. Not intended to acquire, process or analyse a medical image, a signal from an in vitro diagnostic device, or a pattern or signal from a signal acquisition system.
+  2. Intended to display, analyse or print medical information about a patient or other medical information (such as peer-reviewed studies and guidelines).
+  3. Intended to support or provide recommendations to a healthcare professional about prevention, diagnosis or treatment.
+  4. Intended to enable the healthcare professional to independently review the basis for the recommendations, so they don't rely primarily on the software.
+- Red flags that push toward device regulation: image or waveform analysis; patient- or caregiver-facing recommendations; time-critical alerts; outputs a clinician cannot independently check (opaque ML); automatic actions.
+- Related: FDA guidance on device software functions and mobile medical applications, and general wellness products, describe other functions FDA does or does not focus on.
+
+## European Union (MDR 2017/745)
+
+- Software intended by its manufacturer for a medical purpose (diagnosis, prevention, monitoring, prediction, prognosis, treatment) can be a medical device (MDR Article 2). MDCG 2019-11 is the guidance on qualifying and classifying software.
+- Annex VIII Rule 11: software that provides information used to take decisions with diagnostic or therapeutic purposes is class IIa; class IIb where those decisions could cause a serious deterioration of health or a surgical intervention; class III where they could cause death or an irreversible deterioration. Few decision support products are class I under the MDR.
+- The EU AI Act also applies to AI systems that are, or are safety components of, devices requiring notified-body assessment.
+
+## United Kingdom
+
+- Medical devices: MHRA under the UK MDR 2002 (as amended); MHRA publishes guidance on software and AI as a medical device.
+- NHS clinical safety (applies to health IT deployed in the NHS in England whether or not it is a device): DCB0129 for manufacturers and DCB0160 for deploying organisations. They require a clinical risk management process, a hazard log, a clinical safety case report and a named Clinical Safety Officer (a registered clinician).
+
+## Other markets
+
+Check the national regulator (for example Health Canada, TGA in Australia, and national authorities across Africa and Asia). Many follow IMDRF "Software as a Medical Device" concepts, which classify by the significance of the information to the decision and the state of the condition.
+
+## Engineering practices that help in every regime
+
+- A written intended-use statement for each feature.
+- A hazard log: what could go wrong (wrong patient, wrong unit, missing data, outage), severity, likelihood, mitigations, residual risk.
+- Traceability from requirement to rule version to test case to release.
+- Software lifecycle practices aligned with IEC 62304 and risk management with ISO 14971 where the product is, or may become, a device.
+- Post-release monitoring of fire rates, overrides and incidents, with a route to report safety issues.

package/skills/code-tour/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: code-tour
+description: Authors a step-by-step guided walkthrough of a codebase or a single feature as an ordered list of stops, each pinned to a file:line reference with a short explanation of what that code does and why it matters, written so a new contributor can follow it in one sitting. Use when asked to create a code walkthrough, a feature tour, a "follow the request" guide, or contributor-facing reading order for part of a project.
+license: MIT
+compatibility: Any Agent Skills host. Needs git to pin the tour to a commit.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: docs
+  kete-loom/risk: writes-files
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# Code tour
+
+A code tour is a reading order. It takes a newcomer through the code that matters, one stop at a time, so they understand a feature without reading the whole repo. A good tour has 6 to 15 stops, follows the path execution takes, and every stop points at real code.
+
+## 1. Agree the scope
+
+Before writing, settle with the user:
+
+- **Subject:** the whole codebase at high level, or one feature or flow (for example "how a login request is handled").
+- **Reader:** new contributor, reviewer, new team member, or future maintainer. This sets how much background each stop needs.
+- **Where it lives:** a Markdown file in the repo (default `docs/tours/<topic>.md`), or reply only.
+
+If the subject is "everything" for a large repo, propose splitting into one overview tour plus one tour per major flow, and ask which to write first.
+
+## 2. Find the path
+
+1. Locate the entry point for the subject: a route, command handler, event consumer, UI action or public function.
+2. Follow the call chain by reading code and searching for callers and definitions. Don't trust names; open each function.
+3. Note each place a reader must understand: where input arrives, where it's validated, where the core decision is made, where state changes, where it leaves the system, and where errors are handled.
+4. Find the test that exercises this path. It makes a good last stop.
+
+Drop stops that are pure plumbing (re-exports, trivial wrappers) unless skipping them would confuse the reader.
+
+## 3. Pin it to a commit
+
+Line numbers drift. Record the current commit with `git rev-parse --short HEAD` and put it in the tour header. If `git status --porcelain -- <cited paths>` shows uncommitted changes in files the tour cites, tell the user the references may move once they commit.
+
+## 4. Write the stops
+
+Each stop has:
+
+- a numbered title that says what happens, not the file name ("3. Validate the payload", not "3. validators.ts");
+- a `path:line` or `path:start-end` reference, relative to the repo root;
+- 2 to 5 sentences: what this code does, why it's here, and what to notice;
+- optionally, a short excerpt (at most 10 lines) when the point is a specific construct.
+
+Rules for stops:
+
+- Order follows execution or data flow, not the directory tree.
+- Each stop should connect to the next ("the validated payload is handed to...").
+- Explain intent and non-obvious decisions. Don't narrate code line by line.
+- Flag gotchas the reader would otherwise hit: hidden side effects, global state, ordering requirements, surprising config.
+- Keep ranges tight. A stop pointing at a 300-line file teaches nothing.
+
+## 5. Use this format
+
+```markdown
+# Tour: <subject>
+
+> Commit `<sha>` · Reader: <audience> · About <N> minutes
+
+**You'll learn:** <one or two sentences>
+**Before you start:** <prerequisites, such as how to run the app or which concepts to know>
+
+## 1. <What happens here>
+`path/to/file.ext:12-30`
+
+<2 to 5 sentences.>
+
+## 2. <Next step>
+`path/to/other.ext:44`
+
+<...>
+
+## Where to go next
+- <related tour, doc, or the test to run: `<command>`>
+```
+
+## 6. Verify before you hand it over
+
+1. Open every cited range and confirm it still shows what the stop describes. Fix or drop any that don't.
+2. Confirm every path exists, using the exact case.
+3. Read the tour top to bottom as the target reader. If a stop uses a term no earlier stop or prerequisite introduced, add a sentence or a link.
+4. If the tour includes a command, run it, or mark it as not run.
+
+## Never
+
+- Invent a file, function or line number. If you couldn't find something, say so in the tour.
+- Edit source code to make the tour easier to write.
+- Overwrite an existing tour without asking; offer an updated version alongside it.
+
+## Report back
+
+Return the tour (or its path), the commit it is pinned to, the number of stops, and any references you could not verify. For getting yourself oriented rather than writing for others, use `codebase-onboarding`; for README or API docs, use `technical-writing`.

package/skills/code-tour/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "Write a guided tour of how a login request moves through this app, with file and line references for each stop",
+    "Create a walkthrough of the billing module for new contributors so they know what to read and in what order",
+    "Can you make a step-by-step code tour of the plugin loader for the docs folder?",
+    "Our new hire starts Monday. Put together a feature tour of the search indexing pipeline pinned to the current commit"
+  ],
+  "should_not_trigger": [
+    "I just cloned this project, help me figure out how to build it and where the entry points are",
+    "Write API reference docs for the public functions in the sdk package",
+    "Update the README and CHANGELOG to reflect the renamed config flag",
+    "Explain what this one regular expression in utils.py matches"
+  ]
+}

package/skills/codebase-onboarding/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: codebase-onboarding
+description: Gets you productive in an unfamiliar repository fast by locating its entry points, building and running it locally, mapping modules and the main data flow, reading the tests as a specification, and ending with a one-page orientation note. Use when someone has just cloned or inherited a project, asks "how does this codebase work", "where do I start", or needs to understand a repo before changing it.
+license: MIT
+compatibility: Any Agent Skills host. Needs git and whatever build tool the project uses.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: docs
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# Codebase onboarding
+
+Turn an unknown repository into a mental map you can act on. The goal is not to read everything: it is to find the few files that matter, prove you can build and run the thing, and write down what you learned so the next person starts faster.
+
+Work read-first. Do not edit tracked files during onboarding. The only files you may create are git-ignored local config copies (step 2) and the orientation note, and the note only where the user agrees.
+
+## 1. Get the lay of the land (5 minutes)
+
+1. List the top level of the repo and read, in this order, whichever exist: `README*`, `CONTRIBUTING*`, `AGENTS.md`, `CLAUDE.md`, `docs/` index, `ARCHITECTURE*`.
+2. Identify the stack from manifests: `package.json`, `pyproject.toml`, `requirements*.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle*`, `*.csproj`, `Gemfile`, `composer.json`, `pubspec.yaml`, `Package.swift`, `CMakeLists.txt`, `Makefile`.
+3. Note the scripts or tasks they define (for example `scripts` in `package.json`, targets in a `Makefile`, `[project.scripts]` in `pyproject.toml`). These are the project's own answer to "how do I build, test and run this".
+4. Check recent history: `git log --oneline -20` and `git shortlog -sn --since="6 months ago"` show what is active and who knows it.
+5. Check CI config (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `.circleci/`). CI is the most reliable record of the real build and test commands.
+
+If it is a monorepo (workspaces, `packages/`, `apps/`, `services/`), ask the user which package they care about before going further. Onboarding to everything at once produces nothing useful.
+
+## 2. Build and run it
+
+1. Install dependencies with the command the README or CI uses. Prefer the lockfile-respecting form (`npm ci`, `pip install -r`, `go mod download`, `bundle install`).
+2. Run the test suite once. Record the command, pass/fail counts and duration.
+3. Start the app, CLI or service the way the README says, and hit one real path (a request, a command, a page).
+4. Copy environment templates (`.env.example`, `config/*.sample`) only into files that `git check-ignore <path>` confirms are ignored, and never overwrite an existing `.env`.
+
+Stop and ask the user when:
+
+- setup needs credentials, a paid service, production data or access you don't have;
+- a step would install system-wide packages, change global config or run a database migration against anything but a local database;
+- the build fails and the fix is not obvious after one attempt. Report the exact error instead of guessing.
+
+Never run deploy, publish, release or data-deleting scripts while onboarding, even if they sit next to the build scripts.
+
+## 3. Find the entry points
+
+Search for where execution starts. Typical signs:
+
+| Kind | Look for |
+|---|---|
+| Web server | route or controller registration, `listen(`, app factory, framework config |
+| CLI | `bin` field in `package.json`, `[project.scripts]`, `main` packages, argument parsers |
+| Library | the package's public export file (`index.*`, `__init__.py`, `lib.rs`, `mod.rs`) |
+| Workers and jobs | queue consumers, cron or scheduler definitions, serverless handlers |
+| Frontend | the root component, router definition, HTML entry |
+
+List at most five entry points with `path:line`. If you find more, group them.
+
+## 4. Map modules and data flow
+
+1. Sketch the module layout from directory names, then confirm by reading one file in each major directory. Directory names lie; imports don't.
+2. Pick one representative request or command and trace it end to end: entry point, validation, business logic, persistence or external call, response. Write each hop as `path:line — what happens`.
+3. Note where state lives: databases (look for migrations and schema files), caches, queues, files, third-party APIs.
+4. Note the cross-cutting pieces: config loading, logging, auth, error handling, dependency injection.
+
+## 5. Read the tests as a spec
+
+- Find the test layout and the fixtures or factories.
+- Read the tests for the flow you traced. They show intended behaviour and edge cases the code alone hides.
+- Note what has no tests. That is where changes are risky.
+
+## 6. Write the orientation note
+
+Ask the user where it should go (reply only, a scratch file, or `docs/ONBOARDING.md`). Do not overwrite an existing onboarding doc; propose additions instead. Keep it to one page, in this format:
+
+```markdown
+# <project> orientation
+
+**What it is:** <one sentence>
+**Stack:** <languages, frameworks, datastores>
+
+## Run it
+- Install: `<command>`
+- Test: `<command>` (<N> passed, <duration>)
+- Start: `<command>`, then <how to see it working>
+
+## Entry points
+- `path:line` — <what starts here>
+
+## How a request flows
+1. `path:line` — <step>
+
+## Where things live
+- <directory> — <responsibility>
+
+## Gotchas
+- <surprising thing, flaky test, required env var>
+
+## Open questions
+- <things you could not confirm>
+```
+
+## Rules
+
+- Every claim in the note points to a file or a command output. If you inferred it, say "probably".
+- Don't summarise files you didn't open.
+- Don't paste secrets from `.env` or config into the note or the reply.
+- Keep it short. A note nobody reads is worse than none.
+
+## Report back
+
+Return the orientation note (or its path), the commands you ran with their results, and the open questions the user should take to a maintainer. For a walkthrough meant for other contributors, hand off to the `code-tour` skill; for polished project docs, to `technical-writing`.

package/skills/codebase-onboarding/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "I just inherited this repo and have no idea how it fits together, help me get oriented",
+    "Where do I even start with this codebase? Figure out how to build and run it",
+    "Map out the modules and how a request flows through this service before I change anything",
+    "New job, first day, cloned their monorepo. Give me a quick lay of the land for the payments package"
+  ],
+  "should_not_trigger": [
+    "Write a guided tour of the checkout feature for our new contributors, with file and line stops",
+    "Rewrite our README so a new user can install the CLI in five minutes",
+    "I changed the config loader, update the docs and changelog to match",
+    "Propose how we should split this monolith into separate services and write up the trade-offs"
+  ]
+}