@ketecode/loom 0.1.0 → 0.2.0

package/commands/debug.md

@@ -0,0 +1,27 @@
+---
+name: debug
+description: Find the root cause of a bug, failing test or unexpected behaviour by evidence before proposing or making any fix.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/argument-hint: "<symptom, error message or failing test>"
+  kete-loom/owner: "Kete-org"
+---
+
+Find the root cause of the problem below before fixing anything.
+
+If the user gave no symptom, ask for the error, the failing test or the steps that reproduce it, and stop.
+
+If the `systematic-debugging` skill is available, follow it. Otherwise:
+
+1. Read the full error and stack trace. Reproduce the failure reliably and write down the exact command or steps.
+2. Check what changed: `git log`, `git diff`, recent dependency or config changes. For a regression, consider `git bisect run <script>`.
+3. Trace the bad value back to where it first goes wrong, adding temporary logging at component boundaries if needed. Compare with similar code that works.
+4. State one hypothesis and test it with the smallest possible change or experiment. If it is wrong, form a new one; do not stack fixes.
+5. State the root cause in one sentence with file:line. To fix it, write a failing test first (`/fix-bug` or the `tdd-workflow` skill). If three fixes in a row fail, stop and question the design with the user.
+
+Report: reproduction, root cause, evidence, proposed fix, and what is still unknown.
+
+Problem from the user: $ARGUMENTS

package/commands/dual-review.md

@@ -0,0 +1,34 @@
+---
+name: dual-review
+description: Two independent reviewers, optionally on different models or providers, review the same change against one rubric; fix and repeat until both approve or the round limit is hit, then report disagreements.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/argument-hint: "[scope] [--rounds N] [--models a,b]"
+  kete-loom/owner: "Kete-org"
+---
+
+Run a dual review of the change below. Default: 3 rounds at most.
+
+1. **Scope.** Use the files, commit range or PR in the arguments; otherwise `git diff HEAD` plus untracked files from `git status --short`; if empty, the branch diff against its merge base with the default branch. If there is nothing to review, say so and stop.
+2. **Rubric.** Write one rubric and give it to both reviewers unchanged: correctness, security, error handling, tests for changed behaviour, breaking changes for callers. Each finding needs `path:line`, severity (blocking | should fix | nit) and a concrete fix. Verdict: approve | request changes.
+3. **Reviewers.** Start two reviewers in separate contexts, at the same time, with the same scope and rubric, and never show either the other's output. Use the matching Kete Loom reviewer agent for the language (as `/review` routes: `typescript-reviewer`, `python-reviewer`, `payments-reviewer` and so on), else `code-reviewer`. If `--models` names two models or the host has a second provider configured, run one reviewer on each; otherwise use two separate subagents and say the independence is weaker. If subagents aren't available, tell the user and stop rather than reviewing twice in one context.
+4. **Reconcile.** Merge findings. Mark each as *both*, *A only* or *B only*. Check every single-reviewer finding against the code yourself before acting on it; drop ones you can disprove and note why.
+5. **Fix.** Show the user the blocking and should-fix list and ask before editing. Apply the smallest fix per finding, run the project's tests, and don't touch code outside the scope.
+6. **Repeat.** Re-run both reviewers on the updated diff with fresh contexts. Stop when both approve, at the round limit, or when a round fixes nothing new (the same blocking findings keep coming back); in the last two cases list every unresolved blocking finding under Open. Never weaken the rubric to get an approval.
+
+Report:
+
+```
+## Dual review: <scope>   Rounds: <n>/<max>   Reviewers: <A agent/model>, <B agent/model>
+Verdict: both approve | A approves, B requests changes | both request changes
+Fixed: path:line — issue (found by A|B|both)
+Open: path:line — issue — why not fixed
+Disagreements: <finding> — A says ..., B says ..., your assessment
+Tests: <command> → <result>
+```
+
+Scope and options: $ARGUMENTS

package/commands/feature-dev.md

@@ -3,20 +3,21 @@ name: feature-dev
 description: Build a feature end to end: plan it, implement it test-first, review it and verify it, stopping for approval between stages.
 license: MIT
 metadata:
-  kete-loom/version: "0.1.0"
+  kete-loom/version: "0.2.0"
   kete-loom/category: coding
   kete-loom/risk: writes-files
   kete-loom/argument-hint: "<the feature>"
   kete-loom/owner: "Kete-org"
 ---
 
-Build the feature below in four stages. Stop after each stage, show the result, and wait for the user before starting the next.
+Build the feature below in stages. Stop after each stage, show the result, and wait for the user before starting the next.
 
-1. **Plan.** Use the `planner` agent if available (otherwise plan it yourself): files to touch, tests to add, risks, and anything to ask. Ask the open questions now.
-2. **Build test-first.** Follow the `tdd-workflow` skill: a failing test for each behaviour, the smallest change that passes it, then refactor with the suite green. Keep to the plan; if the plan turns out wrong, stop and say so.
-3. **Review.** Run `/review` (or the language reviewer agent, or `code-reviewer`) on the change. Fix what it finds that is in scope, and list the rest.
-4. **Verify.** Run the project's checks with the `verification-loop` skill (or `/verify`) and report pass or fail per check.
+1. **Design.** If the feature is more than a small, well-defined change, agree the design first with the `design-brainstorming` skill (one question at a time, two or three approaches, approval per section). Skip this for small changes.
+2. **Plan.** Write the plan with the `implementation-plans` skill, or use the `planner` agent (otherwise plan it yourself): files to touch, tests to add, risks, and anything to ask. Ask the open questions now. For larger work, offer an isolated workspace with the `git-worktrees` skill.
+3. **Build test-first.** Follow the `tdd-workflow` skill: a failing test for each behaviour, the smallest change that passes it, then refactor with the suite green. For a plan with several tasks on a host with subagents, run it with the `subagent-driven-development` skill. Keep to the plan; if the plan turns out wrong, stop and say so.
+4. **Review.** Run `/review` (or the language reviewer agent, or `code-reviewer`) on the change. Fix what it finds that is in scope, and list the rest.
+5. **Verify.** Run the project's checks with the `verification-loop` skill (or `/verify`) and report pass or fail per check.
 
-Finish with a short summary: what changed, the tests added, the checks run, and anything left. Don't commit or push unless the user asks.
+Finish with a short summary: what changed, the tests added, the checks run, and anything left. Don't commit or push unless the user asks; when they want to wrap up, use the `finishing-a-branch` skill (or `/finish-branch`).
 
 Feature: $ARGUMENTS

package/commands/finish-branch.md

@@ -0,0 +1,26 @@
+---
+name: finish-branch
+description: Finish the current branch - run the checks, confirm the base, then merge locally, open a pull request, keep it or discard it, with cleanup and no force-push or deletion without consent.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/argument-hint: "[base branch]"
+  kete-loom/owner: "Kete-org"
+---
+
+Finish the work on the current branch.
+
+If the `finishing-a-branch` skill is available, follow it. Otherwise:
+
+1. If the working tree has uncommitted changes, ask what to do with them. Run the project's checks (`/verify`); if any fail, report them and stop.
+2. Confirm the base branch (the one given below, else the repository's default branch), and ask if unsure. Show `git log --oneline <base>..HEAD`.
+3. Offer exactly four choices and wait: merge into the base locally, push and open a pull request, keep the branch as it is, or discard it.
+4. Merge: switch to the base, `git merge <branch>`, re-run the checks, then delete the branch with `git branch -d`. Pull request: `git push -u origin <branch>` and create it as `/pr` does. Keep: change nothing. Discard: list the commits and files that will be lost and require the user to type `discard <branch>` before `git branch -D`.
+5. Remove the branch's worktree (`git worktree remove`, then `git worktree prune`) only after a merge or a confirmed discard; keep it for a pull request.
+
+Never force-push, delete a remote branch or use `--force` without the user's explicit consent.
+
+Base branch from the user, if any: $ARGUMENTS

package/commands/fix-bug.md

@@ -0,0 +1,38 @@
+---
+name: fix-bug
+description: Fix a reported bug by reproducing it as a failing regression test, finding the root cause, making the smallest fix, verifying, reviewing the diff and offering a commit.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/argument-hint: "<bug report, issue link or failing behaviour>"
+  kete-loom/owner: "Kete-org"
+---
+
+Fix the bug described below. If no bug was given, ask for the report (what happened, what was expected, how to trigger it) and stop.
+
+1. **Understand.** Restate the bug as: input or steps, expected result, actual result. If you can't, ask the user for the missing detail. Run the existing test suite once; if it already fails, report which tests fail and ask before going on.
+2. **Reproduce as a failing test.** Write a regression test that reproduces the bug exactly as reported, next to the existing tests for that code and in their style. Run it and confirm it fails for the reported reason, not a typo or import error. If the `tdd-workflow` skill is available, follow its red step. If the bug can't be captured in an automated test (timing, environment, external service), write down the manual reproduction, show it failing, and tell the user why there is no test.
+3. **Find the root cause.** Trace from the failing test to where the wrong value first appears; read the code, add temporary logging, or use `git log -L` or `git bisect run <script>` when the bug is a regression (keep the new test in a script or file outside the tracked tree, since older commits don't contain it). Search the codebase for every caller of the function you will change and for the same mistake elsewhere. State the root cause in one sentence before editing. Fix the cause, not the symptom (no special-casing the reported input).
+4. **Smallest fix.** Change only what the root cause requires. No refactors, renames or dependency upgrades in the same change. Never weaken, skip or delete an existing test to get green; if one conflicts with the fix, stop and ask.
+5. **Verify.** Run the new test (now passing), the tests for the changed module and its callers, then the full check set. If the `verification-loop` skill is available, follow it; otherwise run the project's build, lint, type-check and test commands. If the fix touches a shared module, consider the `change-impact-analysis` skill for its consumers.
+6. **Review the diff.** Delegate to the `code-reviewer` agent if it is available (or the reviewer for that language); otherwise read `git diff` yourself for correctness, error paths, and leftover debug code. Remove temporary logging.
+7. **Offer a commit.** Propose a message such as `fix(<area>): <what was wrong>` with the root cause in the body and the issue reference if given. Commit only if the user agrees; never push.
+
+Stop and ask the user if the fix changes documented or public behaviour, needs a data migration or a dependency change, or if three focused attempts haven't found the root cause.
+
+Report:
+
+```
+## Bug fix: <summary>
+Reproduction: <test path::name, or manual steps>
+Root cause: <one sentence, file:line>
+Fix: <files changed: what>
+Verification: <commands> -> <pass/fail counts>
+Review: <findings addressed, or none>
+Commit: <proposed message> (committed: yes/no)
+```
+
+Bug report from the user: $ARGUMENTS

package/commands/production-readiness.md

@@ -0,0 +1,45 @@
+---
+name: production-readiness
+description: Audit a service before launch for health checks, observability, rollback, backups, limits, secrets and runbooks, and return a go/no-go list with evidence.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: runs-commands
+  kete-loom/argument-hint: "[service path or name]"
+  kete-loom/owner: "Kete-org"
+---
+
+Audit this service for production readiness. Do not edit files and do not run anything that changes infrastructure or data; read the code, config and docs, and run only read-only commands.
+
+1. Find the service: the path or name below, or the repository root. Identify how it is built, deployed (Dockerfile, Kubernetes manifests, Helm, Terraform, CI workflows) and configured.
+2. Check each area, using the matching Kete Loom skill as the standard when it is available:
+   - **Health checks**: liveness and readiness endpoints, wired into the deploy config, readiness checking real dependencies (`kubernetes-patterns`, `deployment-strategies`).
+   - **Observability**: structured logs with trace IDs, RED metrics, traces, SLOs, alerts that link to runbooks, an on-call dashboard (`observability`).
+   - **Rollback**: a tested way back to the previous version, and schema changes that the old version survives (`deployment-strategies`, `database-migrations`).
+   - **Backups**: automated backups of every stateful store, retention, and a restore that has actually been tested.
+   - **Limits**: CPU and memory requests and limits, timeouts and retries with backoff on outbound calls, rate limits, connection pool sizes, autoscaling bounds.
+   - **Secrets**: no secrets in the repo or images, read from a secret store or environment, rotation possible (`security-review` for depth).
+   - **Runbooks and ownership**: an owner, an on-call rotation, a runbook for each paging alert (`runbook-writing`).
+   - **Dependencies and images**: pinned base images, no known critical vulnerabilities (`dependency-audit`, `docker-patterns`).
+3. For deeper infrastructure review delegate to the `infra-reviewer` agent if it is available. If none of the skills are installed, apply the checks above directly.
+4. Mark each item from evidence: a file and line, a command output, or a link. If you cannot find evidence, mark it **unknown**, not pass. Ask the user about anything that lives outside the repo (backup restore tests, on-call rotation).
+
+Return:
+
+```
+## Production readiness: <service>
+Verdict: GO | GO WITH CONDITIONS | NO-GO
+Blockers (must fix before launch)
+- <area>: <finding>. Evidence: <path:line or output>. Fix: <action>
+Conditions (fix within <agreed time> after launch)
+- ...
+Passed
+- <area>: <evidence>
+Unknown (needs an answer from the team)
+- <question>
+```
+
+Any blocker means NO-GO. Health checks, rollback, backups for stateful data and secrets handling are blockers when missing.
+
+Service or focus from the user, if any: $ARGUMENTS

package/commands/usage-report.md

@@ -0,0 +1,43 @@
+---
+name: usage-report
+description: Summarise token usage and estimated cost per session, project and model from local agent session logs (Claude Code, Codex, Gemini CLI, OpenCode, Kete Code), read-only.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: ai
+  kete-loom/risk: runs-commands
+  kete-loom/argument-hint: "[today | 7d | 30d | since YYYY-MM-DD] [host] [project]"
+  kete-loom/owner: "Kete-org"
+---
+
+Build a token usage report from local agent session logs. Read-only: never edit, move or delete a log, and never send log contents anywhere. Logs contain prompts and code; only print aggregates, never message text.
+
+Default period: last 7 days, all hosts found. Formats change between releases, so inspect one record before parsing and say if a format looks different from below.
+
+**Where to look**
+
+- **Claude Code**: `~/.claude/projects/<project-slug>/*.jsonl` (subagent logs may sit in subfolders). Assistant lines carry `message.model` and `message.usage` with `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`. One response can span several lines with the same `message.id` and repeated usage; count each `message.id` (plus `requestId` if present) once. Skip lines whose model is `<synthetic>`. Project = `cwd` field, or the slug.
+- **Codex**: `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`. `event_msg` records with `payload.type == "token_count"` hold `info.total_token_usage` (cumulative: `input_tokens`, `cached_input_tokens`, `output_tokens`, `reasoning_output_tokens`); take the last non-null `info` per file, not the sum (early records can have `info: null`). Model and `cwd` come from `turn_context` records.
+- **Gemini CLI**: `~/.gemini/tmp/<project-hash>/chats/` (session files with per-message token counts). Check whether files are `.json` or `.jsonl` before parsing. Read only `chats/`; `/chat save` and checkpoint files elsewhere under the project folder repeat the same conversation and would double-count.
+- **OpenCode**: SQLite at the path `opencode db path` prints (usually `~/.local/share/opencode/opencode.db`); older versions used JSON under `~/.local/share/opencode/storage/`. **Kete Code**: `~/.local/share/kete/kete.db`; table `session_v2` has `directory`, `cost`, `tokens_input`, `tokens_output`, `tokens_reasoning`, `tokens_cache_read`, `tokens_cache_write`. Open databases read-only (`sqlite3 -readonly`); inspect `.tables` and `.schema` first.
+
+**Steps**
+
+1. Find which of these exist; skip missing ones and list them under "Not found".
+2. Write a small throwaway script in a temporary directory (Node or Python, no installs) that streams the files, filters by timestamp to the period, and aggregates by host, project, model, and session. Don't load huge files into memory at once.
+3. Keep input, cache write, cache read, output and reasoning tokens as separate columns; they are priced differently.
+4. Cost: use a cost the log itself records where present (OpenCode, Kete Code). Otherwise estimate with per-million-token prices for each model, and state the prices used and their date. Prices change: tell the user to check them against each provider's current pricing page; never present the estimate as a bill. Subscription plans aren't billed per token, so say the figure is the API-equivalent cost.
+
+**Report**
+
+```
+## Agent usage: <period>
+Totals: <sessions>, input <n>, cache write <n>, cache read <n>, output <n>, est. cost <$>
+By host and model: table (host, model, sessions, tokens by type, est. cost)
+By project: top 10 by est. cost
+Top sessions: top 5 (date, host, project, model, tokens, est. cost)
+Prices used: <model: $in/$out/$cache per 1M, source, date>; check current provider price pages
+Not found / unparsed: <hosts, files skipped and why>
+```
+
+Period, host or project filter: $ARGUMENTS

package/hooks/block-foreground-servers/HOOK.md

@@ -0,0 +1,34 @@
+---
+name: block-foreground-servers
+description: Stops the agent from starting a dev server or file watcher in the foreground, where it never exits and hangs the agent's shell, and tells it to run it in the background with output going to a log.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: read-only
+  kete-loom/event: "pre-shell"
+  kete-loom/opt-in: "true"
+  kete-loom/owner: "Kete-org"
+---
+
+# Block foreground servers
+
+Runs before every shell command. It blocks commands that start a long-running server or watcher and never return:
+
+- `npm|pnpm|yarn|bun run dev|start|serve|watch`, `next dev`, `vite` (not `vite build`), `ng serve`, `webpack serve`, `nodemon`;
+- `rails server`, `php artisan serve`, `flask run`, `uvicorn`, `python -m http.server`, `manage.py runserver`;
+- `docker compose up` without `-d`, `hugo server`, `jekyll serve`, `tsc --watch`, test runners in `--watch` mode.
+
+They are allowed when they are already backgrounded:
+
+- with a trailing `&` or `nohup`;
+- under `setsid`, `tmux`, `screen`, `pm2` or `timeout`;
+- by the host's own background option (for example Claude Code's background shell).
+
+When it blocks, the agent is told to start the server in the background with its output in a log file, wait for it to be ready, and stop it when done:
+
+```bash
+npm run dev > .dev-server.log 2>&1 &
+```
+
+Opt-in: `--hooks` leaves it out; install it by name with `--hook` or with `--profile strict`.

package/hooks/block-foreground-servers/cases.json

@@ -0,0 +1,31 @@
+{
+  "should_block": [
+    "npm run dev",
+    "pnpm dev",
+    "yarn start",
+    "bun run dev --port 3001",
+    "cd web && npx next dev",
+    "npx vite",
+    "ng serve --open",
+    "rails server -p 4000",
+    "python -m http.server 8000",
+    "uvicorn app.main:app --reload",
+    "docker compose up",
+    "npx tsc --watch",
+    "npx vitest --watch"
+  ],
+  "should_allow": [
+    "npm run build",
+    "npm test",
+    "npx vite build",
+    "npm run dev > .dev-server.log 2>&1 &",
+    "nohup python -m http.server 8000 > http.log 2>&1 &",
+    "docker compose up -d",
+    "docker compose up --detach db",
+    "timeout 20 npm start",
+    "tmux new -d -s web 'npm run dev'",
+    "npm run start:prod -- --help",
+    "grep -r 'npm run dev' README.md",
+    "npx vitest run"
+  ]
+}

package/hooks/block-foreground-servers/hook.js

@@ -0,0 +1,41 @@
+'use strict';
+
+// Blocks shell commands that start a dev server or watcher in the foreground (they never return and
+// hang the agent's shell) unless they are already backgrounded. check({ command, background }) -> verdict.
+
+const SERVER = [
+  /\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:dev|start|serve|watch)\b(?!:)/,
+  /\bnext\s+dev\b/,
+  /(?:^|[\s;&|(])(?:npx\s+)?vite(?:\s+(?:dev|serve|--\S+|\.)|\s*$)/,
+  /\bng\s+serve\b/,
+  /\bwebpack(?:-dev-server|\s+serve)\b/,
+  /\bnodemon\b/,
+  /\brails\s+s(?:erver)?\b/,
+  /\bartisan\s+serve\b/,
+  /\bflask\s+run\b/,
+  /\buvicorn\b/,
+  /\bpython3?\s+-m\s+http\.server\b/,
+  /\bmanage\.py\s+runserver\b/,
+  /\bdocker[\s-]compose\s+(?:\S+\s+)*?up\b(?![^;&|]*\s(?:-d|--detach)\b)/,
+  /\bhugo\s+server\b/,
+  /\bjekyll\s+serve\b/,
+  /\btsc\b[^;&|]*\s(?:--watch|-w)\b/,
+  /\b(?:vitest|jest)\b[^;&|]*\s--watch\b/,
+];
+const BACKGROUNDED = /(?:^|\s)(?:nohup|setsid|tmux|screen|pm2|timeout)\s|&\s*(?:disown\s*)?$|&\s*(?:;|$)/;
+
+function check(event) {
+  const command = String(event.command || '');
+  if (event.background) return { block: false };
+  if (BACKGROUNDED.test(command.trim())) return { block: false };
+  // shortcut: quoted text is ignored (so `grep 'npm run dev'` passes), which also lets `sh -c "npm run dev"` through.
+  const bare = command.replace(/'[^']*'|"(?:[^"\\]|\\.)*"/g, "''");
+  const hit = SERVER.find((re) => re.test(bare));
+  if (!hit) return { block: false };
+  return {
+    block: true,
+    reason: 'Blocked by kete-loom (block-foreground-servers): this starts a server or watcher that never exits and would hang the shell. Run it in the background with output in a log, e.g. `npm run dev > .dev-server.log 2>&1 &`, poll the log or the port until it is ready, and stop it when you are done.',
+  };
+}
+
+module.exports = { check };

package/hooks/capture-lessons/HOOK.md

@@ -0,0 +1,24 @@
+---
+name: capture-lessons
+description: Once per session, when the agent finishes with changes in the repository, asks it to propose up to three reusable lessons from the session for /learn, saving nothing unless you approve.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: meta
+  kete-loom/risk: writes-files
+  kete-loom/event: "stop-gate"
+  kete-loom/opt-in: "true"
+  kete-loom/owner: "Kete-org"
+---
+
+# Capture lessons
+
+Runs when the agent ends its turn, in a git repository with uncommitted changes. Once per session, it sends the agent back with one request: propose at most three lessons this session taught. Each lesson can be a mistake it made, a correction you gave, or something it had to work out about the project. A lesson is written as one line plus the evidence for it, or as "No lessons".
+
+The agent saves nothing on its own. You turn the lessons you want into rules, skills or AGENTS.md entries with `/learn`.
+
+It remembers which sessions it has asked in `~/.kete-loom/state/capture-lessons.json` (set `KETE_LOOM_STATE_DIR` to move it). It keeps them per session when the host sends a session id, otherwise once per project per day. It reads no files and never uses the network.
+
+Available in Claude Code, Codex, Gemini CLI, Cursor and GitHub Copilot. Kete Code's and OpenCode's stop hooks can't send the agent back to work.
+
+Opt-in: `--hooks` leaves it out; install it by name with `--hook`.

package/hooks/capture-lessons/hook.js

@@ -0,0 +1,48 @@
+'use strict';
+
+// Once per session, when the agent finishes with uncommitted changes, asks it to propose up to three
+// lessons for /learn. Saves nothing itself. check({ cwd, session, again }) -> verdict.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const KEEP_MS = 14 * 24 * 60 * 60 * 1000;
+
+const stateFile = () => path.join(process.env.KETE_LOOM_STATE_DIR || path.join(os.homedir(), '.kete-loom', 'state'), 'capture-lessons.json');
+
+function check(event, now = Date.now()) {
+  if (event.again) return { block: false };
+  const cwd = path.resolve(event.cwd || process.cwd());
+  let status;
+  try {
+    status = execFileSync('git', ['status', '--porcelain'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 });
+  } catch {
+    return { block: false };
+  }
+  if (!status.trim()) return { block: false };
+  const file = stateFile();
+  let asked = {};
+  try {
+    asked = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    // first run
+  }
+  for (const k of Object.keys(asked)) if (!(now - asked[k] < KEEP_MS)) delete asked[k];
+  const key = event.session || `${cwd}@${new Date(now).toISOString().slice(0, 10)}`;
+  if (asked[key]) return { block: false };
+  asked[key] = now;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(asked));
+  } catch {
+    return { block: false }; // without the record it would ask on every stop
+  }
+  return {
+    block: true,
+    reason: 'kete-loom (capture-lessons): before you finish, list at most 3 lessons from this session worth keeping for next time: a mistake you made, a correction the user gave, or a non-obvious fact about this project. One line each, with the evidence. Do not save them anywhere; the user decides with /learn. If there is nothing worth keeping, reply "No lessons" and stop.',
+  };
+}
+
+module.exports = { check };

package/hooks/notify-on-stop/HOOK.md

@@ -0,0 +1,25 @@
+---
+name: notify-on-stop
+description: Shows a desktop notification when the agent finishes its turn, so you can switch away during long tasks and come back when it is your move.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: meta
+  kete-loom/risk: runs-commands
+  kete-loom/event: "stop"
+  kete-loom/opt-in: "true"
+  kete-loom/owner: "Kete-org"
+---
+
+# Notify on stop
+
+Runs when the agent ends its turn and shows a notification naming the project folder:
+
+- on macOS through `osascript`;
+- on Linux through `notify-send`, when it is installed.
+
+On Windows and on machines with neither, it does nothing. It never blocks, never changes files and never uses the network.
+
+Available in Claude Code, Codex, Gemini CLI, Kete Code, Cursor and GitHub Copilot.
+
+Opt-in: `--hooks` leaves it out; install it by name with `--hook`.

package/hooks/notify-on-stop/hook.js

@@ -0,0 +1,27 @@
+'use strict';
+
+// Desktop notification when the agent finishes its turn. Never blocks. check({ cwd }) -> {}
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function notifier(platform = process.platform, env = process.env) {
+  if (platform === 'darwin') return (title, body) => ['osascript', ['-e', `display notification ${JSON.stringify(body)} with title ${JSON.stringify(title)}`]];
+  if (platform === 'linux' && (env.PATH || '').split(path.delimiter).some((d) => d && fs.existsSync(path.join(d, 'notify-send')))) return (title, body) => ['notify-send', [title, body]];
+  return null; // shortcut: no Windows toast (it needs a PowerShell module); add one if Windows users ask
+}
+
+function check(event) {
+  const make = notifier();
+  if (!make) return {};
+  const [program, args] = make('Agent finished', `${path.basename(path.resolve(event.cwd || process.cwd()))}: your turn`);
+  try {
+    execFileSync(program, args, { stdio: 'ignore', timeout: 3000 });
+  } catch {
+    // a notification that can't be shown is not worth failing over
+  }
+  return {};
+}
+
+module.exports = { check, notifier };

package/hooks/protect-lint-config/HOOK.md

@@ -0,0 +1,29 @@
+---
+name: protect-lint-config
+description: Stops the agent from editing existing linter, formatter and type-checker configs, so it fixes the code that breaks a rule instead of weakening or switching off the rule.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: read-only
+  kete-loom/event: "pre-edit"
+  kete-loom/opt-in: "true"
+  kete-loom/owner: "Kete-org"
+---
+
+# Protect lint config
+
+Runs before every file write or edit. It blocks changes to existing quality-gate configs:
+
+| Tool | Files |
+|---|---|
+| ESLint | `.eslintrc*`, `eslint.config.*` |
+| Biome, Prettier, Stylelint | `biome.json(c)`, `.prettierrc*`, `prettier.config.*`, `.stylelintrc*`, `stylelint.config.*` |
+| Python | `ruff.toml`, `.ruff.toml`, `.flake8`, `.pylintrc`, `mypy.ini`, `.mypy.ini` |
+| Go, Rust, Ruby, PHP | `.golangci.yml/.yaml/.toml`, `clippy.toml`, `.clippy.toml`, `rustfmt.toml`, `.rubocop.yml`, `phpstan.neon(.dist)` |
+
+The agent is told to fix the code that breaks the rule instead. If you asked for the config change yourself, the agent says so, and you make the edit or turn this hook off.
+
+Creating a config that doesn't exist yet is allowed, so setting up a new project still works. Settings inside `pyproject.toml` or `package.json` are not covered, because those files hold much more than lint settings.
+
+Opt-in: `--hooks` leaves it out; install it by name with `--hook` or with `--profile strict`. Not available in Cursor, which has no documented hook before an edit.

package/hooks/protect-lint-config/cases.json

@@ -0,0 +1,18 @@
+{
+  "should_block": [
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": ".eslintrc.json", "content": "{\"rules\":{}}" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": "eslint.config.mjs", "content": "export default []" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": "biome.json", "content": "{}" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": ".prettierrc", "content": "{}" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": "ruff.toml", "content": "ignore = [\"E501\"]" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": ".golangci.yml", "content": "linters: {}" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": "src/a.ts", "content": "x" }, { "path": ".rubocop.yml", "content": "" }] }
+  ],
+  "should_allow": [
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": "src/app.ts", "content": "x" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": "tsconfig.json", "content": "{}" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": ".stylelintrc.json", "content": "{}" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": "docs/eslint-rules.md", "content": "x" }] },
+    { "cwd": "hooks/protect-lint-config/fixtures", "files": [{ "path": "pyproject.toml", "content": "[tool.ruff]" }] }
+  ]
+}

package/hooks/protect-lint-config/fixtures/.eslintrc.json

@@ -0,0 +1 @@
+{}

package/hooks/protect-lint-config/fixtures/.golangci.yml

@@ -0,0 +1 @@
+{}

package/hooks/protect-lint-config/fixtures/.prettierrc

@@ -0,0 +1 @@
+{}

package/hooks/protect-lint-config/fixtures/.rubocop.yml

@@ -0,0 +1 @@
+{}

package/hooks/protect-lint-config/fixtures/biome.json

@@ -0,0 +1 @@
+{}

package/hooks/protect-lint-config/fixtures/eslint.config.mjs

@@ -0,0 +1 @@
+{}

package/hooks/protect-lint-config/fixtures/ruff.toml

@@ -0,0 +1 @@
+{}

package/hooks/protect-lint-config/hook.js

@@ -0,0 +1,25 @@
+'use strict';
+
+// Blocks edits to existing linter, formatter and type-checker configs, so the agent fixes the code
+// instead of weakening the rule. New configs are allowed. check({ files: [{ path }], cwd }) -> verdict.
+
+const fs = require('fs');
+const path = require('path');
+
+const CONFIG = /^(?:\.eslintrc(?:\.[a-z]+)?|eslint\.config\.[cm]?[jt]s|biome\.jsonc?|\.prettierrc(?:\.[a-z]+)?|prettier\.config\.[cm]?[jt]s|\.stylelintrc(?:\.[a-z]+)?|stylelint\.config\.[cm]?js|\.?ruff\.toml|\.flake8|\.pylintrc|\.?mypy\.ini|\.golangci\.(?:ya?ml|toml|json)|\.?clippy\.toml|\.?rustfmt\.toml|\.rubocop\.yml|phpstan\.neon(?:\.dist)?)$/;
+
+function check(event) {
+  const cwd = event.cwd || process.cwd();
+  for (const f of event.files || []) {
+    if (!f || typeof f.path !== 'string') continue;
+    const base = path.basename(f.path);
+    if (!CONFIG.test(base) || !fs.existsSync(path.resolve(cwd, f.path))) continue;
+    return {
+      block: true,
+      reason: `Blocked by kete-loom (protect-lint-config): \`${f.path}\` configures a linter or formatter. Fix the code that breaks the rule instead of changing the rule. If the user asked for this config change, tell them this hook blocks it so they can make the edit themselves.`,
+    };
+  }
+  return { block: false };
+}
+
+module.exports = { check };

package/hooks/read-before-edit/HOOK.md

@@ -0,0 +1,26 @@
+---
+name: read-before-edit
+description: Stops the first edit of each existing file in a session and tells the agent to read the file and search for its callers first, so changes are grounded in the real code rather than a guess.
+license: MIT
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/event: "pre-edit"
+  kete-loom/opt-in: "true"
+  kete-loom/owner: "Kete-org"
+---
+
+# Read before edit
+
+Runs before every file write or edit. The first time in a session the agent tries to change a file that already exists, the edit is refused with this instruction:
+
+1. Read the whole file.
+2. Search the codebase for everything that imports, calls or configures it.
+3. Then make the same edit again.
+
+The retry goes through, and so does every later edit of that file in the session. New files are never blocked.
+
+It remembers which files it has seen in `~/.kete-loom/state/read-before-edit.json` (set `KETE_LOOM_STATE_DIR` to move it). It keeps them per session when the host sends a session id, otherwise per project per day. Entries older than two days are dropped. It reads no file contents and never uses the network.
+
+Expect one extra round trip per file. Opt-in: `--hooks` leaves it out; install it by name with `--hook` or with `--profile strict`. Not available in Cursor, which has no documented hook before an edit.