@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/contract-drafting/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: contract-drafting
+description: Assembles first-draft commercial agreements, namely master services agreements, NDAs, statements of work and GDPR-style data processing agreements, by filling the organisation's own clause template from a structured term sheet, logging every departure from the standard position in a deviation register with its risk and approver, and producing a plain-language redline summary, with a mandatory gate that a qualified lawyer reviews the draft before anyone signs or sends it. Use when you need a first draft of an MSA, NDA, SOW or DPA from your template and agreed terms, when the other side's paper must be compared against your playbook, or when preparing a summary of changes for legal sign-off.
+license: MIT
+compatibility: Any Agent Skills host. Works on the user's templates and documents (Markdown, plain text or .docx through the host's document tools). Not legal advice; every output is a draft for a qualified lawyer to review.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: compliance
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Contract drafting
+
+Produce a clean draft that says exactly what was agreed, in the organisation's own approved language, and make every deviation visible so a lawyer can review the draft quickly. You assemble and flag; you never decide that a term is legally acceptable.
+
+## Lawyer-review gate (mandatory)
+
+Every output from this skill is marked `DRAFT - FOR LEGAL REVIEW - NOT FOR SIGNATURE`. Keep that marking until the user confirms a qualified lawyer has approved the draft. **Never** remove it, send the draft to the counterparty, or call it final on your own.
+
+**Stop and tell the user a lawyer must handle it** (do not draft the clause yourself) when:
+
+- There is no approved template for the agreement type or the clause, and the user asks you to write legal terms from scratch.
+- The governing law, jurisdiction or a party's country is one the template was not written for.
+- The deal touches regulated areas: personal data transfers outside the EEA/UK, health data, financial services, export-controlled goods, employment, consumer contracts, government contracts, or competition-sensitive terms (exclusivity, non-competes, pricing between competitors).
+- The term sheet asks for unlimited liability, an uncapped indemnity, IP assignment of the organisation's core IP, or a change to any clause the template marks "non-negotiable".
+
+## 0. Gather inputs
+
+1. The template: the organisation's own clause library or standard form for this agreement type, with its version. If the user has none, see the gate above.
+2. The playbook, if there is one: preferred position, acceptable fallbacks and walk-away for each key clause.
+3. The term sheet, as structured fields. The field list per agreement type is in `references/term-sheets.md`. Ask for every missing required field; never fill a commercial term with a guess.
+4. The counterparty's draft or redline, if you are comparing their paper against yours.
+
+## 1. Assemble the draft
+
+1. Copy the template; do not rewrite its clauses for style. Approved language is approved because it was reviewed.
+2. Fill placeholders from the term sheet only. Party names must be full legal names with entity type and registration details as the user supplied them.
+3. Keep defined terms consistent: every capitalised term is defined once and used with the same spelling. Check that every cross-reference points to a clause that exists after edits.
+4. Keep the document order the template uses. Schedules (SOW, pricing, DPA, service levels) attach to the master agreement and the order-of-precedence clause says which wins on conflict.
+5. Where the term sheet asks for something the template does not say, do not invent wording. Insert `[DEVIATION D-n: <what is requested>]` and log it.
+
+## 2. Deviation register
+
+Log every place the draft differs from the template or the playbook's preferred position:
+
+```
+ID | clause | standard position | requested / drafted position | why (business reason) | risk (low | medium | high) | playbook fallback? | approver needed | status
+```
+
+Rules for the risk rating:
+
+- High: liability caps, indemnities, IP ownership, data protection, termination for convenience, exclusivity, governing law, anything outside the playbook.
+- Medium: payment terms, warranties, service levels and credits, acceptance, notice periods, renewal.
+- Low: dates, contact details, administrative wording.
+
+When comparing the counterparty's paper, log each of their changes the same way, with the playbook position next to it.
+
+## 3. Redline summary
+
+For the reviewer, in plain language, ordered by risk:
+
+1. One paragraph: deal, parties, agreement type, template version, governing law.
+2. A table of deviations (from the register), high risk first, each with one sentence on what it means in practice ("we would owe them up to 12 months of fees if a data breach is our fault").
+3. Missing information and open questions.
+4. Clauses that need specialist review (data protection, tax, export, employment).
+
+Produce a tracked-changes or comparison document against the template when the host's document tools allow it; otherwise list changes clause by clause.
+
+## 4. Agreement-type checks
+
+Before handing over, run the checklist for the agreement type in `references/term-sheets.md`. Short version:
+
+- **NDA:** mutual or one-way; definition of confidential information and exclusions; permitted use and disclosees; term and survival; return or destruction; no licence granted; remedies.
+- **MSA:** scope and order of precedence; fees, invoicing and payment; warranties; liability cap and exclusions; indemnities; IP ownership and licences; confidentiality; data protection hook to a DPA; term, renewal and termination; insurance; governing law and disputes.
+- **SOW:** deliverables, milestones, acceptance criteria and process, assumptions, dependencies, change control, fees per milestone, named contacts; nothing in the SOW silently overrides the MSA.
+- **DPA (GDPR Article 28):** the Article 28(3) contents must be present: subject matter, duration, nature and purpose, types of personal data and data subjects, and the processor obligations (documented instructions, confidentiality, security, sub-processors, assistance with data subject rights and with security and impact assessments, deletion or return, audit). International transfers need a transfer mechanism such as the EU Standard Contractual Clauses (2021) or the UK addendum; route those to a privacy lawyer and the `privacy-compliance` skill.
+
+## Rules
+
+- Never remove the draft marking or send the draft outside the organisation without the user confirming lawyer approval.
+- Never invent a commercial term, party detail or legal clause that is not in the template, playbook or term sheet.
+- Never silently change approved template language; every change is a logged deviation.
+- Do not give an opinion on whether a clause is enforceable; say it needs a lawyer.
+- Keep counterparty documents confidential; do not paste them into external services the user has not approved.
+
+## Report
+
+```
+Draft: <file> | type <NDA | MSA | SOW | DPA> | template <name, version> | status DRAFT - FOR LEGAL REVIEW
+Parties: <legal names>   Governing law: <law>
+Deviations: <n high, n medium, n low>  (register attached)
+Missing inputs: <list>
+Specialist review needed: <data protection, tax, export, employment, none>
+Next step: lawyer review by <name or role, if the user named one>
+```

package/skills/contract-drafting/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Use our MSA template and this term sheet to draft the agreement with Acme Logistics, and flag anything that differs from our standard",
+    "Draft a mutual NDA for talks with a potential acquirer using the clause library in legal/templates",
+    "The customer sent back our SOW with their changes, compare it to our playbook and write a redline summary for legal",
+    "We need a data processing agreement with our new email vendor based on our DPA template, fill in the processing details",
+    "Build a deviation register for this services agreement showing every change from our standard liability and indemnity clauses"
+  ],
+  "should_not_trigger": [
+    "Map the personal data our signup flow collects and set retention periods for each field",
+    "Check whether our invention is novel before we spend money on a patent application",
+    "Generate invoices with the right VAT fields for our customers in Germany",
+    "Explain in two sentences the difference between an MSA and a SOW",
+    "Negotiate better rates with our truckload carriers on the Midwest lanes"
+  ]
+}

package/skills/contract-drafting/references/term-sheets.md

@@ -0,0 +1,68 @@
+# Term sheet fields and pre-review checklists
+
+Read this when collecting inputs for a draft (section 0) or running the agreement-type checks (section 4). Required fields are marked `*`. Ask for every missing required field.
+
+## Common to all agreements
+
+- `*` Parties: full legal name, entity type, jurisdiction of incorporation, registered address, company number where used.
+- `*` Effective date, and signatories (name, title).
+- `*` Governing law and dispute forum (courts or arbitration, seat, rules).
+- Notices: addresses and email for formal notice.
+- Template name and version used.
+
+## NDA
+
+- `*` Mutual or one-way; who discloses.
+- `*` Purpose (the permitted use of the information).
+- `*` Term of the agreement and how long confidentiality obligations survive; any trade secrets carve-out to last longer.
+- Permitted disclosees (employees, affiliates, advisers, financing sources).
+- Exclusions: public, already known, independently developed, received from a third party lawfully; compelled disclosure process.
+- Return or destruction on request, with a backup-copy carve-out.
+- Non-solicitation or standstill (high risk; often belongs in a separate agreement).
+
+## MSA
+
+- `*` Services or products in scope; how orders or SOWs are created.
+- `*` Fees, currency, invoicing schedule, payment terms, late payment, price changes, taxes.
+- `*` Liability cap (amount or formula, for example fees paid in the prior 12 months) and exclusions from the cap.
+- `*` Term, renewal (auto-renew and notice), termination for cause and for convenience, effects of termination.
+- Indemnities: who indemnifies whom, for what (IP infringement, data breach, third-party claims), procedure.
+- Warranties and disclaimers; service levels and credits as a schedule.
+- IP: background IP stays with its owner; ownership of deliverables; licences granted.
+- Data protection: whether a DPA is needed; security schedule.
+- Insurance types and minimums.
+- Subcontracting, assignment and change of control.
+- Order of precedence between MSA, SOW, schedules and purchase orders.
+
+## SOW
+
+- `*` Reference to the governing MSA and its date.
+- `*` Deliverables with descriptions; milestones and dates.
+- `*` Acceptance criteria, acceptance period, and what happens on rejection.
+- `*` Fees per milestone or rate card, expenses policy.
+- Assumptions and customer dependencies; change-request process.
+- Named contacts and governance meetings.
+- Checks: the SOW must not change liability, IP or payment terms set in the MSA unless the MSA allows it, and then the change is a logged deviation.
+
+## DPA
+
+- `*` Roles: controller and processor (or processor and sub-processor).
+- `*` Subject matter, duration, nature and purpose of processing.
+- `*` Types of personal data, special categories if any, categories of data subjects.
+- `*` Security measures (usually an annex).
+- `*` Sub-processors: list, approval method (specific or general with notice and objection).
+- Breach notice period from processor to controller.
+- Assistance with data subject requests, security, impact assessments and prior consultation.
+- Deletion or return at end of services.
+- Audits and information rights.
+- International transfers: destinations and mechanism (EU SCCs 2021 module, UK IDTA or addendum). Route to a privacy lawyer.
+
+Check each DPA against the processor terms of GDPR Article 28(3) and the law of the user's jurisdiction; other data protection laws have their own processor contract requirements.
+
+## Final pre-review checks (all types)
+
+- Every placeholder filled or logged as a deviation; no `[ ]` left unexplained.
+- Defined terms defined once and used consistently; cross-references valid.
+- Dates, amounts and currencies match the term sheet exactly (amounts in words and figures agree if both are used).
+- Signature blocks match the party names.
+- Draft marking present on every page or in the header.

package/skills/contract-first-development/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: contract-first-development
+description: Coordinates frontend and backend teams, or two services, around one machine-checked interface contract in OpenAPI, AsyncAPI, protobuf or JSON Schema that is reviewed and merged before code, then drives generated clients and server stubs, mock servers for parallel work, CI gates for breaking changes with oasdiff and buf breaking, and Pact consumer-driven contract tests with can-i-deploy checks. Use when two teams or services must build against the same interface at the same time, a spec keeps drifting from the implementation, or a provider change broke a consumer that nobody tested against.
+license: MIT
+compatibility: Any Agent Skills host. Uses the contract tooling the repo already has (for example oasdiff, buf, Prism, openapi-generator, Pact); network access only for a Pact Broker.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Contract-first development
+
+One contract file is the source of truth for an interface. Both sides generate from it or test against it, CI blocks breaking edits to it, and nobody codes against a Slack message or a screenshot of a JSON payload.
+
+For designing the API itself (resource naming, status codes, pagination, versioning policy) use the `api-design` skill if installed; this skill is about the workflow around the contract once its shape is being agreed.
+
+## 0. Pick the format and the owner
+
+| Interface | Contract format |
+|---|---|
+| HTTP/REST | OpenAPI 3.x (3.1 aligns schemas with JSON Schema 2020-12) |
+| Events, queues, WebSockets | AsyncAPI 3.x, payloads in JSON Schema or Avro |
+| gRPC / internal RPC | protobuf with buf |
+| A data file or message without a transport | JSON Schema |
+
+1. Use the format already in the repo. If there are several, ask the user which is authoritative; never keep two hand-written sources of the same interface.
+2. Decide where the contract lives: in the provider repo, or a shared contracts repo/package. Record the owner who approves changes (a `CODEOWNERS` entry is ideal).
+3. **Stop and ask** if the implementation exists and the spec is generated from code: switching to spec-first is a team decision.
+
+## 1. Write and review the contract before code
+
+1. Draft the change as a pull request that touches only the contract (plus examples).
+2. Every operation or message has: request and response schemas, required vs optional fields, error responses, at least one realistic example, and an `operationId` (OpenAPI) so generated code has stable names.
+3. Lint it: `redocly lint` or `spectral lint` for OpenAPI, `asyncapi validate` for AsyncAPI, `buf lint` for protobuf, and validate examples against the schemas.
+4. Both sides review. A consumer approval is required for anything they will call.
+5. Merge, then tag or version the contract so both sides pin the same revision.
+
+## 2. Work in parallel from the contract
+
+- **Consumer side**: generate a typed client and start against a mock server built from the contract (`prism mock openapi.yaml` for OpenAPI; buf/connect or a generated stub for protobuf; AsyncAPI generators or a test broker for events). Never hand-write request types that the generator can produce.
+- **Provider side**: generate server interfaces or stubs, or validate requests and responses against the spec at runtime in tests, so the implementation can't silently diverge.
+- Commit generated code or regenerate in the build; follow whichever the repo already does, and make CI fail when the committed output is stale. Tools and commands: `references/tooling.md`.
+
+## 3. Block breaking changes in CI
+
+On every PR that touches a contract, compare with the base branch:
+
+- OpenAPI: `oasdiff breaking --fail-on ERR origin/main:openapi.yaml HEAD:openapi.yaml`; `oasdiff changelog` for the PR description.
+- protobuf: `buf breaking --against '.git#branch=main'` (default rule set `FILE`; set `breaking.use` in `buf.yaml`).
+- JSON Schema / AsyncAPI: run the repo's diff tool, or treat removed properties, newly required fields, narrowed types and removed enum values as breaking in review.
+
+A breaking change needs one of: a new version (path, package, or message type), an additive alternative plus deprecation, or written agreement from every consumer. **Stop and ask the user** before merging any breaking change.
+
+Common breaking edits: removing or renaming a field, endpoint, message or enum value; making an optional request field required; changing a type or format; tightening validation; reusing a protobuf field number. Also breaking for many consumers: adding a value to a response enum (strict clients and exhaustive switches fail) and changing default values. Usually safe: adding optional request fields, adding response fields (only if consumers ignore unknown fields), adding endpoints.
+
+## 4. Consumer-driven contract tests (Pact)
+
+Use when consumers depend on behaviour a schema can't express (which fields they actually read, state-dependent responses), or when providers deploy independently.
+
+1. Consumer tests run against the Pact mock and write a pact file describing only the interactions the consumer uses.
+2. Publish pacts to a Pact Broker (or PactFlow) tagged with the consumer's git SHA and branch.
+3. The provider verifies pacts in its CI with provider states set up through a test hook, never against shared staging data.
+4. Before each deploy: `pact-broker can-i-deploy --pacticipant <name> --version <sha> --to-environment <env>`; after it: `pact-broker record-deployment --pacticipant <name> --version <sha> --environment <env>`.
+5. Pact does not replace schema checks; run both.
+
+## Never
+
+- Never edit generated code by hand; change the contract or the generator config.
+- Never let the mock server drift from the spec (generate it from the spec, don't hand-write fixtures).
+- Never disable a breaking-change check to get a PR green.
+- Never reuse a deleted protobuf field number or name; `reserved` them.
+
+## Report
+
+```
+## Contract: <interface> (<format>, <path>@<revision>)
+Owner: <team/person>
+Lint: <command> -> pass/fail
+Breaking-change check: <command> -> <n breaking> (<list>)
+Generated: client <tool/path>, server <tool/path>, stale: yes/no
+Mock: <command or none>
+Consumer contracts: <Pact status, can-i-deploy result, or not used>
+Needs agreement: <breaking changes and which consumers must approve>
+```

package/skills/contract-first-development/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "The mobile team and the backend team keep disagreeing about payload shapes. Set us up so both build from one OpenAPI spec with a mock server.",
+    "Add a CI check that fails the PR if someone makes a breaking change to our protobuf files",
+    "A provider deploy broke the checkout frontend again. Set up Pact consumer tests and can-i-deploy before releases.",
+    "Our openapi.yaml has drifted from what the Go service actually returns. Generate the server interfaces from the spec so they can't diverge.",
+    "We're about to start a new order-events topic. Agree the AsyncAPI contract first so both services can start in parallel."
+  ],
+  "should_not_trigger": [
+    "Design the REST endpoints and status codes for our new invoicing API",
+    "Write a typed client for the Shopify Admin API with retries and pagination",
+    "Write Playwright end-to-end tests for the signup flow",
+    "Which packages in our monorepo depend on the shared validation library?",
+    "Add a migration that renames the orders.total column"
+  ]
+}

package/skills/contract-first-development/references/tooling.md

@@ -0,0 +1,46 @@
+# Contract tooling
+
+Prefer tools already in the repo. Check flags with `--help` for the installed version.
+
+## OpenAPI
+
+| Job | Tool and command |
+|---|---|
+| Lint | `npx @redocly/cli lint openapi.yaml`, or `spectral lint openapi.yaml` with a `.spectral.yaml` ruleset |
+| Breaking changes | `oasdiff breaking --fail-on ERR <base> <revision>`; bases can be files, URLs or `<git-ref>:<path>`; `--fail-on WARN` is stricter |
+| Changelog | `oasdiff changelog <base> <revision>` |
+| Mock server | `npx @stoplight/prism-cli mock openapi.yaml` (serves examples; `-d` for dynamic data) |
+| Validating proxy | `prism proxy openapi.yaml <upstream-url>` reports requests and responses that violate the spec |
+| TypeScript types | `npx openapi-typescript openapi.yaml -o src/api/schema.d.ts`, with `openapi-fetch` for a typed client |
+| Clients and stubs, many languages | `openapi-generator-cli generate -i openapi.yaml -g <generator> -o <dir>` |
+| Go | `oapi-codegen` with a config file selecting client, server or types |
+| Property-based API tests | Schemathesis, run against a provider test instance |
+
+## protobuf (buf)
+
+| Job | Command |
+|---|---|
+| Lint | `buf lint` |
+| Breaking changes | `buf breaking --against '.git#branch=main'` (or a BSR module, or a tag) |
+| Generate | `buf generate` with `buf.gen.yaml` listing plugins |
+| Format | `buf format -w` |
+
+Rules: never change a field number or type; `reserved` removed numbers and names; add fields as optional.
+
+## AsyncAPI
+
+- Validate: `asyncapi validate asyncapi.yaml` (AsyncAPI CLI).
+- Generate code or docs: `asyncapi generate fromTemplate asyncapi.yaml <template>`.
+- Payload schemas can be JSON Schema or Avro; keep Avro schemas in a schema registry with compatibility mode set (for example BACKWARD) if the platform has one.
+
+## JSON Schema
+
+- Validate examples and fixtures in tests with the language's validator (Ajv for JS/TS, `jsonschema` for Python).
+- Declare `$schema` so tools pick the right draft.
+
+## Pact
+
+- Consumer libraries: pact-js, pact-python, pact-jvm, pact-go, pact-net and others; consumer tests write pact files to `pacts/`.
+- Publish: `pact-broker publish pacts/ --consumer-app-version <sha> --branch <branch> --broker-base-url <url>`.
+- Provider verification runs in the provider's test suite with a provider-states setup endpoint or hook.
+- Gate deploys: `pact-broker can-i-deploy --pacticipant <name> --version <sha> --to-environment <env>`; then `pact-broker record-deployment --pacticipant <name> --version <sha> --environment <env>`.

package/skills/conventional-commits/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: conventional-commits
+description: Writes and checks commit messages in the Conventional Commits 1.0.0 format - choosing the type and scope, marking breaking changes with "!" or a BREAKING CHANGE footer, writing a body that explains why the change was made, and adding issue footers - so changelog and semantic-version tooling can read the history. Use when composing a commit message, splitting staged work into well-labelled commits, fixing a message that commitlint rejected, or deciding whether a change counts as feat, fix or breaking.
+license: MIT
+compatibility: Any Agent Skills host. Needs git. Checking messages with commitlint needs Node.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# Conventional Commits
+
+A commit message is a record for the next person who runs `git blame`, and for the tools that build the changelog and pick the next version. Write it for both.
+
+## 0. Before writing
+
+1. Look for project rules first: `commitlint.config.*`, `.commitlintrc*`, a `commitlint` key in `package.json`, `CONTRIBUTING.md`, `.czrc`, or release config (`release-please-config.json`, `.releaserc*`). Allowed types and scopes there override this skill.
+2. Read recent history for the house style: `git log --oneline -20`. Match the scopes and casing already in use.
+3. Read what is actually staged: `git diff --cached --stat`, then `git diff --cached`. Write about the staged diff, not what you remember changing.
+4. If nothing is staged, **stop and ask** what should go in the commit. Don't `git add -A` on the user's behalf.
+
+## 1. One change per commit
+
+If the staged diff mixes unrelated things (a bug fix plus a rename plus a dependency bump), propose splitting it and say which files go where. If the user wants one commit anyway, use the type of the most significant change and mention the rest in the body.
+
+## 2. Format
+
+```
+<type>[optional scope][!]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Rules from the specification:
+
+- `type` is a noun, followed by optional `(scope)`, optional `!`, then `: ` (colon and space) and the description.
+- The body starts after one blank line and is free text.
+- Footers start after one blank line. Each is `Token: value` or `Token #value`. Tokens use `-` instead of spaces (`Reviewed-by`), except `BREAKING CHANGE`.
+- `BREAKING CHANGE` must be uppercase. `BREAKING-CHANGE` means the same.
+
+House conventions on top of the spec (follow the project's config if it differs):
+
+- Description: imperative mood ("add", not "added"/"adds"), lower case first word, no trailing period, aim for 72 characters or fewer on the whole first line.
+- Wrap the body at about 72 characters.
+
+## 3. Choose the type
+
+| Type | Use for | Version effect with standard tooling |
+|---|---|---|
+| `feat` | New behaviour a user or caller can see | minor |
+| `fix` | Corrects wrong behaviour | patch |
+| `perf` | Faster or leaner, same behaviour | patch in most presets |
+| `refactor` | Code change with no behaviour change | none |
+| `docs` | Documentation only | none |
+| `test` | Adding or fixing tests only | none |
+| `build` | Build system, packaging, dependencies | none |
+| `ci` | CI configuration and scripts | none |
+| `style` | Formatting, whitespace; no code meaning change | none |
+| `chore` | Maintenance that fits nothing above | none |
+| `revert` | Reverts an earlier commit | depends on the tool |
+
+Only `feat` and `fix` have meaning in the specification itself; the rest are the widely used `@commitlint/config-conventional` set. Any type can carry a breaking change.
+
+Decision rules:
+
+- If a user-visible behaviour changes to correct a defect, it is `fix`, even if the code change is large.
+- If you are unsure between `feat` and `refactor`, ask: would the changelog reader care? Yes means `feat` or `fix`.
+- A dependency bump that fixes a user-facing bug is `fix(deps): ...`; a routine bump is `build(deps): ...` (or `chore(deps)` if that is the house style).
+
+## 4. Choose the scope
+
+- A scope names the area touched: a package, module or subsystem (`feat(auth): ...`, `fix(api): ...`).
+- Use scopes already in the history or config. Don't invent a new one per commit.
+- Leave the scope out rather than guess, or when the change spans the whole project.
+
+## 5. Breaking changes
+
+A change is breaking when existing callers, configs, data or users must change something to keep working: removed or renamed public API, changed defaults, changed output format, dropped runtime support, a required new setting.
+
+Mark it with either or both:
+
+```
+feat(api)!: remove v1 order endpoints
+
+BREAKING CHANGE: /v1/orders is gone. Call /v2/orders, which returns
+amounts in minor units instead of decimals.
+```
+
+- Prefer `!` plus a `BREAKING CHANGE:` footer that says **what breaks and what to do instead**. That footer text usually lands in the changelog verbatim.
+- If you think a change is breaking but the user hasn't said so, **stop and ask** before marking it; it decides a major release.
+- On a project still at `0.y.z`, a breaking change is still marked; the release tooling decides how to bump.
+
+## 6. Write a body that explains why
+
+The diff shows what changed. The body says:
+
+1. Why the change was needed (the bug, the requirement, the constraint).
+2. Why this approach, if it isn't obvious, and what was ruled out.
+3. Side effects a reviewer would not guess (migration needed, cache to clear, behaviour change at the edges).
+
+Skip the body only for changes whose reason is self-evident (`docs: fix typo in README`). Never restate the diff line by line, and never write "update file" or "misc fixes".
+
+## 7. Footers
+
+- Issue links: `Refs: #123`. On GitHub and GitLab, `Closes #123` or `Fixes #123` closes the issue when the commit reaches the default branch, so use those only when the commit really completes it.
+- Co-authors: `Co-authored-by: Name <email>`.
+- Reverts: `git revert --no-commit <sha>`, then commit as `revert: <original subject>` with the body line `This reverts commit <sha>.` and a `Refs: <sha>` footer. Plain `git revert` writes a `Revert "<subject>"` subject, which is not in the Conventional Commits format.
+
+## 8. Check before committing
+
+- If the project has commitlint, check the message: `echo "<message>" | npx commitlint`, or a range with `npx commitlint --from origin/main --to HEAD`.
+- Commit without opening an editor: `git commit -F <message-file>` or `git commit -m "<subject>" -m "<body>" -m "<footer>"`.
+- If a commit hook rejects the message, fix the message. Don't skip hooks with `--no-verify` unless the user asks.
+- If the commit is already pushed to a shared branch, don't amend it; the squash-merge title or a follow-up commit is the place to fix it.
+
+## Examples
+
+```
+fix(cart): reject negative quantities
+
+The quantity input accepted values below zero, which produced negative
+line totals and let users reduce an order's price. Validate on the
+server as well as in the form, since the API is called directly by the
+mobile app.
+
+Fixes #482
+```
+
+```
+perf(search): cache tokenised queries per request
+
+Profiling showed tokenisation was 40% of search latency for repeated
+filter queries. The cache lives only for the request, so there is no
+invalidation to manage.
+```
+
+## Report back
+
+Give the final message in a code block, the files it covers, and one line on why that type, scope and breaking flag were chosen. If you proposed a split, list each commit's message and files.

package/skills/conventional-commits/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Write a conventional commit message for what I've staged",
+    "commitlint keeps failing with 'subject may not be empty', fix my commit message",
+    "Is removing the legacy config flag a feat or a breaking change? How do I mark it in the commit?",
+    "I've staged a bug fix and a refactor together, split them into properly typed commits",
+    "Rewrite this commit message so it explains why we changed the retry logic, not just what"
+  ],
+  "should_not_trigger": [
+    "Decide whether the next release should be 3.0.0 or 2.5.0 and publish it",
+    "My rebase onto main has conflicts in the lockfile, help me finish it",
+    "Write the pull request description for this branch",
+    "Generate release notes for v1.8.0 from the changelog",
+    "Recover the commits I lost after a bad interactive rebase"
+  ]
+}

package/skills/cpp-patterns/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: cpp-patterns
+description: Modern C++ (17/20/23) house rules for writing and restructuring code - RAII for every resource, unique_ptr/shared_ptr ownership, value semantics and the rule of zero, const-correctness, steering clear of undefined behaviour, concepts used sparingly, target-based CMake, plus sanitizer and clang-tidy setup. Use when writing new C++ code, modernising legacy C++98/03 code, deciding who owns an object, or setting up a CMake project with warnings, sanitizers and clang-tidy.
+license: MIT
+compatibility: Any Agent Skills host. Needs a C++17-or-later compiler (GCC, Clang or MSVC) and CMake for the build sections.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "cmake"
+  kete-loom/owner: "Kete-org"
+---
+
+# Modern C++ patterns
+
+Write C++ where ownership is visible in the types, resources clean themselves up, and the compiler plus sanitizers catch what review misses.
+
+## 0. Before you write code
+
+1. Find the language standard the project builds with: `CMAKE_CXX_STANDARD` or `target_compile_features(... cxx_std_NN)` in `CMakeLists.txt`, `-std=` in compile flags, or `compile_commands.json`. Never use a feature newer than that standard.
+2. Match the project's existing conventions (naming, error style, exceptions on or off, header layout). If the codebase builds with `-fno-exceptions`, do not introduce `throw`.
+3. If the change would alter a public header used by other libraries or shipped as a binary SDK, **stop and ask the user**: it may be an ABI break.
+
+## 1. Ownership and RAII
+
+Decision rules, in order:
+
+1. **Store by value** when the object has one owner and a known type. `std::vector<Widget>`, not `std::vector<Widget*>`.
+2. **`std::unique_ptr<T>`** for single ownership of a heap object (polymorphic types, pimpl, large or optional objects). Create with `std::make_unique<T>(...)`.
+3. **`std::shared_ptr<T>`** only when ownership is genuinely shared and lifetimes cannot be ordered. Create with `std::make_shared`. Break cycles with `std::weak_ptr`.
+4. **Raw pointer or reference = non-owning.** `T&` when it cannot be null, `T*` when it can. A raw pointer never gets `delete`d by the code that receives it.
+5. **Views do not own.** `std::string_view` and `std::span` must not outlive the buffer they point into; never return one that points at a local or a temporary.
+
+Every resource (file handle, socket, lock, OS handle, C library object) is wrapped in an object whose destructor releases it:
+
+```cpp
+struct FileCloser { void operator()(std::FILE* f) const noexcept { if (f) std::fclose(f); } };
+using File = std::unique_ptr<std::FILE, FileCloser>;
+
+File open_file(const char* path) { return File{std::fopen(path, "rb")}; }
+```
+
+Locks: `std::scoped_lock` (C++17) or `std::lock_guard`; `std::unique_lock` when you must unlock early or wait on a `std::condition_variable`. Never manual `lock()`/`unlock()`.
+
+Never write: naked `new`/`delete` in application code, `malloc`/`free` for C++ objects, `delete this`, `std::auto_ptr`, or a `shared_ptr` passed by value into a function that only reads it (pass `const T&` instead).
+
+## 2. Value semantics and special members
+
+- **Rule of zero:** if members are RAII types, declare no destructor, copy or move operations. The compiler-generated ones are correct.
+- **Rule of five:** if you must write one of destructor / copy ctor / copy assign / move ctor / move assign, write or `= delete` all five.
+- Mark move constructors and move assignment `noexcept`. A copyable type whose move constructor is not `noexcept` gets copied, not moved, when `std::vector` reallocates.
+- Pass parameters: cheap types (ints, pointers, `string_view`, `span`) by value; read-only larger objects by `const T&`; sink parameters (the callee keeps a copy) by value then `std::move` into place.
+- Return by value. Do not write `return std::move(local);`; it blocks copy elision.
+- Never use an object after `std::move` from it except to assign to it or destroy it.
+- Make single-argument constructors `explicit` unless implicit conversion is the point.
+
+## 3. Const-correctness
+
+- Variables are `const` (or `constexpr`) unless they are mutated.
+- Member functions that do not change observable state are `const`. `mutable` only for caches and mutexes.
+- Prefer `constexpr` functions and `static_assert` for things knowable at compile time.
+- Mark functions `[[nodiscard]]` when ignoring the result is almost always a bug (error codes, `expected`-style results, factory functions).
+
+## 4. Avoiding undefined behaviour
+
+Check each of these in code you write or touch. Details and examples: `references/undefined-behaviour.md`.
+
+- Signed integer overflow, shifting by >= the bit width, and division by zero.
+- Out-of-bounds indexing: use `.at()` in non-hot code, range-for, or `std::span`; check indices from input.
+- Dangling references: returning a reference or view to a local, lambdas capturing locals by reference that outlive the scope, iterators or references into a `vector` after `push_back`/`insert`/`erase`.
+- Uninitialised variables: initialise at declaration (`int n{};`, `T x = make();`).
+- Strict aliasing and type punning: use `std::memcpy` or `std::bit_cast` (C++20), not `reinterpret_cast` between unrelated types.
+- Data races: any variable written by one thread and read by another needs a mutex or `std::atomic`.
+- Deleting through a pointer to a polymorphic base class whose destructor is neither `virtual` nor `protected`.
+
+## 5. Errors
+
+- Follow the project's existing strategy. If none: exceptions for errors the immediate caller cannot handle, return values for expected failures (`std::optional`, `std::expected` in C++23, or the project's own result type).
+- Destructors, move operations and `swap` are `noexcept` and never throw.
+- Give every function the strong or basic exception guarantee: on throw, state is unchanged or still valid, and nothing leaks (RAII makes this automatic).
+
+## 6. Templates and concepts in moderation
+
+- Write a plain function or class first. Add a template only when there are two real call sites with different types.
+- In C++20, constrain templates with standard concepts (`std::integral`, `std::ranges::range`) or a short named `concept`, instead of `enable_if`.
+- Keep template definitions in headers. No template metaprogramming where `if constexpr` or an overload does the job.
+- Prefer standard algorithms and ranges (`std::ranges::sort`, `std::ranges::find_if`) over hand-written loops when they read more clearly.
+
+## 7. Project structure and CMake
+
+Use target-based CMake; never set flags globally with `CMAKE_CXX_FLAGS` edits or `include_directories()`.
+
+```cmake
+cmake_minimum_required(VERSION 3.20)
+project(app LANGUAGES CXX)
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+add_library(core src/core.cpp)
+target_include_directories(core PUBLIC include)
+target_compile_features(core PUBLIC cxx_std_20)
+
+add_executable(app src/main.cpp)
+target_link_libraries(app PRIVATE core)
+```
+
+- Layout: `include/<project>/` public headers, `src/` sources and private headers, `tests/` tests.
+- `PUBLIC` when consumers need it (it appears in your headers), `PRIVATE` when only your `.cpp` files need it.
+- Get dependencies with `find_package` (fed by vcpkg or Conan) or `FetchContent`; do not vendor copies.
+- Out-of-source builds only: `cmake -S . -B build && cmake --build build`.
+
+Warnings, sanitizers, clang-tidy and a `CMakePresets.json` example: `references/cmake-and-tooling.md`.
+
+## 8. Tooling loop
+
+1. Build with warnings on: GCC/Clang `-Wall -Wextra -Wpedantic -Wshadow -Wconversion`, MSVC `/W4`. Treat new warnings in touched files as errors.
+2. Run the tests under AddressSanitizer + UndefinedBehaviorSanitizer (`-fsanitize=address,undefined -fno-omit-frame-pointer`). Run ThreadSanitizer (`-fsanitize=thread`) in a **separate** build for concurrent code; it cannot be combined with ASan.
+3. Run `clang-tidy` on changed files using `compile_commands.json` (`clang-tidy -p build <files>`). Fix findings in code you touched; do not mass-fix the rest of the codebase unasked.
+4. Format with the project's `.clang-format` if one exists (`clang-format -i <files>`). Do not add one unasked.
+
+## Rules
+
+- Never silence a warning or sanitizer report with a cast, pragma or suppression file without explaining the root cause to the user.
+- Never change a public header's layout, virtual functions or inline functions in a shipped library without asking (ABI).
+- Do not modernise unrelated code in the same change. Keep diffs focused.
+- If you cannot build the project locally, say so; do not claim code compiles.
+
+## Report back
+
+End with: files changed, the build and test commands you ran (with sanitizer flags), their results, and any warnings or clang-tidy findings left unresolved.

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Rewrite this class so it stops using raw new and delete and uses smart pointers instead",
+    "Should this member be a unique_ptr, a shared_ptr or just a value?",
+    "Set up a new C++20 CMake project with warnings, sanitizers and clang-tidy",
+    "Modernise this old C++03 parser to C++17 style with RAII and string_view",
+    "Write a thread-safe connection pool class in modern C++"
+  ],
+  "should_not_trigger": [
+    "Write GoogleTest unit tests for the Matrix class and hook them into CTest",
+    "Review my C++ pull request for dangling references and data races",
+    "The linker says undefined reference to vtable for Widget, fix the build",
+    "Refactor this Rust module to avoid cloning and use borrowed slices",
+    "Add idiomatic error handling with errors.Is to this Go service"
+  ]
+}