@gonxped31/agent-kit 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gonxped31
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# agent-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sets up a git repo for Claude Code, new or existing, in two steps: `agk setup` copies
+the kit's files in, then the agent finishes the setup with you. `agk update` brings in
+the kit's later changes.
+
+## What a repo gets
+
+- **A short `CLAUDE.md`**: only what must be true on every change, and where
+  everything else is.
+- **Three skills**:
+  - `git`: a branch per task, files staged by name, `main` only with your approval.
+  - `todo`: a work queue the agent drives through a script, including deferred work
+    with its trigger ("when X happens, do Y").
+  - `agent-setup`: where each kind of knowledge goes, when to add a rule or a skill,
+    and the size limits.
+- **Guardrails that don't rely on the agent remembering**:
+  - a git hook: no commits on `main`, and the checks before every commit;
+  - a Claude hook (Bash and PowerShell): refuses `--no-verify` and bulk staging, and
+    asks you before merges, pushes and commands that discard work;
+  - a Claude hook that refuses whole-file reads of huge files.
+- **Scripts with short output**:
+  - `scripts/check.mjs`: every check, printing only what failed;
+  - `scripts/doctor.mjs`: keeps the agent setup within its size limits and catches
+    dead paths in the docs;
+  - `scripts/merge.mjs`: the only way into `main`.
+
+It works with local git alone: no GitHub, no remote needed.
+
+## Requirements
+
+- git, and Node 18 or later with its npm. No npm packages.
+- Claude Code: the skills, hooks and settings are in its formats.
+- Only for `agk setup --github`: the [GitHub CLI](https://cli.github.com) (`gh`),
+  logged in (`gh auth login`).
+
+## Install
+
+    npm install -g @gonxped31/agent-kit
+
+That puts the `agk` command on your PATH, on Windows, macOS and Linux. The same command
+updates it; `npm uninstall -g @gonxped31/agent-kit` removes it. To run it once without
+installing: `npx @gonxped31/agent-kit setup`.
+
+## Use
+
+1. In the project's folder, run `agk setup` (or `agk setup <folder>` from its
+   parent). It runs `git init` if the folder isn't a repo yet, then copies the kit's
+   files in. It never overwrites a file: where the repo has one already (its own
+   `CLAUDE.md`, say), the kit's version goes next to it as `CLAUDE.md.kit`, and the
+   agent merges the two in step 2.
+
+   With `--github`, it also creates the repo on GitHub as `origin`: private, or public
+   with `--public`. It checks `gh`, your login and the name first, so a problem stops
+   it before anything changes. The agent pushes `main` after the first commit, once
+   you agree.
+2. Open Claude Code there and say "follow BOOTSTRAP.md". It looks around, asks
+   you up to six questions, and fills in the setup. Whatever isn't decided yet (like
+   the stack) becomes a todo with its trigger. Then it makes the first commit.
+3. After cloning the repo somewhere else, run `git config core.hooksPath .githooks`.
+   `doctor` reminds you if you forget.
+
+### Updating a repo
+
+When the kit changes, run `agk update` in the repo. `.claude/agk.json` records each
+file as the kit wrote it, so `agk update` can tell the files you changed:
+
+- a file you haven't changed is updated (or added, or removed, as the kit's is);
+- a file you changed stays as it is, and the kit's new version goes next to it as
+  `<file>.kit`. Say "merge the .kit files" to Claude Code: `doctor` fails until it's
+  done.
+
+It commits nothing: review the changes and commit them on a branch, like any change.
+
+Your own habits, the ones that hold in every repo, go in `~/.claude/CLAUDE.md`, not in
+the kit.
+
+## Working on the kit
+
+`npm test` installs the template into temporary repos and runs its scripts and hooks.
+On GitHub, `.github/workflows/test.yml` runs it on Windows, macOS and Linux, with Node
+18 and the current LTS. In a clone, `npm link` makes `agk` run the clone's files (a
+`git pull` updates it), and `node bin/agk.mjs` runs them without linking. The design
+and its decisions are in `docs/design.md`.
+
+## License
+
+MIT, in `LICENSE`.

package/bin/agk.mjs

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+// agk: sets up git repos for Claude Code, and brings the kit's later changes into them.
+// - `agk setup` copies template/ into a folder, then the agent there follows BOOTSTRAP.md. Where
+//   the folder has one of the kit's files already, the kit's version goes next to it as
+//   <file>.kit, for the agent to merge. With --github it also creates the repo on GitHub, via gh.
+// - `agk update` updates the kit's files that a repo hasn't changed, and puts the kit's version
+//   next to the others as <file>.kit. The repo's .claude/agk.json says what the kit wrote.
+// Installed with `npm install -g @gonxped31/agent-kit` (or `npm link` in a clone); template/ is next
+// to this file.
+// AGK_GH=<path> runs that instead of gh, with node if it ends in .mjs (the kit's tests only).
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { PACKAGE, RECORD, SETUP_ONLY, VERSION, hashAt, kitCopy, kitFiles, newer, put, readRecord, remove, setUpAlready, writeRecord } from "../lib/kit.mjs";
+import { Failure, blank, clip, count, details, header, line, list, ok, out, showFailure, step, warn } from "../lib/ui.mjs";
+
+const NOTHING_CHANGED = "Nothing was changed.";
+
+const git = (cwd, ...args) => spawnSync("git", args, { cwd, encoding: "utf8" });
+const noGit = () => new Failure("git isn't installed, or isn't on the PATH", { hint: "The kit needs it: https://git-scm.com" });
+
+/** Runs a command without blocking (so the spinner moves). `error` is set if it couldn't start. */
+function run(cmd, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { ...options, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += d));
+    child.stderr.on("data", (d) => (stderr += d));
+    child.on("error", (error) => resolve({ status: null, stdout, stderr, error }));
+    child.on("close", (status) => resolve({ status, stdout, stderr }));
+  });
+}
+
+function gh(...args) {
+  const env = { ...process.env, GH_PROMPT_DISABLED: "1" };
+  const fake = process.env.AGK_GH;
+  return fake?.endsWith(".mjs") ? run(process.execPath, [fake, ...args], { env }) : run(fake || "gh", args, { env });
+}
+
+/** The last lines of what a command said, to show under a failure. */
+const said = (r) => (r.stderr || r.stdout).trim().split(/\r?\n/).filter(Boolean).slice(-3);
+
+/** A command's options and its one folder (default: the current one). */
+function parse(cmd, args, allowed) {
+  const options = args.filter((a) => a.startsWith("-"));
+  const folders = args.filter((a) => !a.startsWith("-"));
+  const bad = options.find((o) => !allowed.includes(o));
+  if (bad) throw new Failure(`Unknown option '${bad}'`, { hint: "Run agk help for the options." });
+  if (folders.length > 1) throw new Failure(`${cmd} takes one folder, got ${folders.length}: ${folders.join(", ")}`);
+  const folder = path.resolve(folders[0] ?? ".");
+  return { options, folder, shown: path.relative(process.cwd(), folder) || "." };
+}
+
+/** The nearest folder at or above `dir` that exists. */
+function nearestExisting(dir) {
+  while (!fs.existsSync(dir)) dir = path.dirname(dir);
+  return dir;
+}
+
+/**
+ * What setup would do in `root`, changing nothing: whether to create it and run git init, and
+ * what to do with each of the kit's files. The folder is a repo's root (set it up as it is),
+ * outside any repo (git init), or inside one: part of that project (refused: the hooks and
+ * CLAUDE.md work only at a repo's root), or a new project that merely sits under it, such as
+ * under a home folder that's a repo.
+ */
+function inspect(root, shown) {
+  if (fs.existsSync(root) && !fs.statSync(root).isDirectory()) throw new Failure(`${root} is a file, not a folder`);
+  const base = nearestExisting(root);
+  const probe = git(base, "rev-parse", "--show-toplevel");
+  if (probe.error) throw noGit();
+  const plan = { exists: fs.existsSync(root), init: probe.status !== 0, note: "", origin: "" };
+  if (!plan.init) {
+    // Compare real paths: git resolves symlinks, and path.relative ignores case on Windows.
+    const top = fs.realpathSync.native(probe.stdout.trim());
+    const here = path.join(fs.realpathSync.native(base), path.relative(base, root));
+    if (path.relative(top, here) !== "") {
+      if (plan.exists && git(root, "ls-files", "-z").stdout) {
+        throw new Failure(`${root} holds files of the repo at ${top}`, {
+          hint: `The kit sets up a whole repo, from its root: run agk setup there. ${NOTHING_CHANGED}`,
+        });
+      }
+      plan.init = true;
+      plan.note = `It's inside the repo at ${top} but holds none of its files, so it gets a repo of its own.`;
+    } else {
+      plan.origin = git(root, "remote", "get-url", "origin").stdout?.trim() ?? "";
+    }
+  }
+
+  const place = shown === "." ? "here" : `in ${shown}`;
+  if (plan.exists && setUpAlready(root)) {
+    throw new Failure(`The kit is set up ${place} already`, { hint: `To bring in its changes since, run agk update. ${NOTHING_CHANGED}` });
+  }
+  // A file the folder has already stays as it is: the kit's version goes next to it, to merge.
+  plan.files = kitFiles().map((f) => {
+    const here = hashAt(root, f.to);
+    return { ...f, state: here === null ? "new" : here === f.hash ? "same" : "differs" };
+  });
+  if (plan.files.some((f) => f.to === SETUP_ONLY && f.state === "differs")) {
+    throw new Failure(`There's a ${SETUP_ONLY} ${place} already`, {
+      hint: `The setup's instructions go in that file, for Claude Code to follow: rename yours first.\n${NOTHING_CHANGED}`,
+    });
+  }
+  const inTheWay = plan.files.filter((f) => f.state === "differs" && fs.existsSync(path.join(root, kitCopy(f.to))));
+  if (inTheWay.length) {
+    throw new Failure(`${count(inTheWay.length, "file")} in the way ${place}`, {
+      details: clip(inTheWay.map((f) => kitCopy(f.to))),
+      hint: `The kit's version of a file you have goes next to it, as <file>.kit: move these aside first.\n${NOTHING_CHANGED}`,
+    });
+  }
+  return plan;
+}
+
+/** The GitHub repo name for a folder: GitHub allows letters, digits, ".", "-" and "_". */
+function repoName(root) {
+  const name = path.basename(root).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  if (!name || /^\.+$/.test(name)) throw new Failure(`Can't make a GitHub repo name from the folder name "${path.basename(root)}"`);
+  return name;
+}
+
+/** The GitHub account gh is logged in to, once it's clear `name` is free there. */
+async function checkGitHub(name) {
+  const user = await gh("api", "user", "--jq", ".login");
+  if (user.error) {
+    throw new Failure("--github needs gh, GitHub's command line tool, and it isn't installed", {
+      hint: `Install it from https://cli.github.com and run gh auth login, or leave out --github. ${NOTHING_CHANGED}`,
+    });
+  }
+  if (user.status !== 0) {
+    throw new Failure("gh couldn't reach your GitHub account", {
+      details: said(user),
+      hint: `Run gh auth login (or check your connection), then run this again. ${NOTHING_CHANGED}`,
+    });
+  }
+  const login = user.stdout.trim();
+  const view = await gh("repo", "view", `${login}/${name}`, "--json", "url");
+  if (view.status === 0) {
+    throw new Failure(`github.com/${login}/${name} already exists`, {
+      hint: `Name the folder differently, or leave out --github. ${NOTHING_CHANGED}`,
+    });
+  }
+  if (!/could not resolve to a repository/i.test(view.stderr)) {
+    throw new Failure(`gh couldn't check whether github.com/${login}/${name} exists`, { details: said(view), hint: NOTHING_CHANGED });
+  }
+  return login;
+}
+
+const each = (n) => (n === 1 ? "it" : "each");
+
+async function setup(args) {
+  const { options, folder: root, shown } = parse("setup", args, ["--github", "--public"]);
+  const github = options.includes("--github");
+  const visibility = options.includes("--public") ? "public" : "private";
+  if (visibility === "public" && !github) throw new Failure("--public goes with --github");
+  header(VERSION, "Setting up a repo for Claude Code");
+
+  // 1. Look, changing nothing: anything that would stop the setup stops it here.
+  const plan = inspect(root, shown);
+  let repo = "";
+  if (github) {
+    if (plan.origin) {
+      throw new Failure(`This repo already has a remote origin: ${plan.origin}`, { hint: `Leave out --github. ${NOTHING_CHANGED}` });
+    }
+    const name = repoName(root);
+    await step("Checking GitHub", async () => {
+      repo = `${await checkGitHub(name)}/${name}`;
+      return `GitHub: github.com/${repo} is free`;
+    });
+  }
+
+  // 2. Set up the folder.
+  if (!plan.exists) {
+    fs.mkdirSync(root, { recursive: true });
+    ok(`Created the folder ${out.cyan(shown)}`);
+  }
+  if (plan.init) {
+    const r = git(root, "init", "-q", "-b", "main");
+    if (r.status !== 0) throw new Failure("git init failed", { details: said(r) });
+    ok("Created a git repo on main");
+    if (plan.note) warn(plan.note);
+  }
+  const fresh = plan.files.filter((f) => f.state === "new");
+  const same = plan.files.filter((f) => f.state === "same");
+  const differs = plan.files.filter((f) => f.state === "differs");
+  for (const f of fresh) put(root, f.to, f.text);
+  for (const f of differs) put(root, kitCopy(f.to), f.text);
+  writeRecord(root, plan.files);
+  const total = plan.files.length;
+  if (fresh.length === total) {
+    ok(`Copied the kit's ${total} files ${out.dim("(CLAUDE.md, BOOTSTRAP.md, .claude/, scripts/ and more)")}`);
+  } else {
+    ok(`Copied ${fresh.length} of the kit's ${total} files`);
+    if (same.length) ok(`${count(same.length, "file")} already here, the same as the kit's`);
+    if (differs.length) {
+      warn(`${count(differs.length, "file")} already here, different: the kit's version is next to ${each(differs.length)}, as <file>.kit`);
+      details(differs.map((f) => f.to));
+    }
+  }
+
+  // 3. Create the GitHub repo. Its first push waits for the bootstrap's first commit.
+  if (github) {
+    await step(`Creating github.com/${repo} (${visibility})`, async () => {
+      const r = await gh("repo", "create", repo, `--${visibility}`, "--source", root, "--remote", "origin");
+      if (r.status !== 0) {
+        throw new Failure("GitHub didn't create the repo", {
+          details: said(r),
+          hint: `The local setup is done. To try again, from the folder:\ngh repo create ${repo} --${visibility} --source . --remote origin`,
+        });
+      }
+      return `Created github.com/${repo} (${visibility}) as remote origin`;
+    });
+  }
+
+  const cd = shown === "." ? [] : [`cd ${/\s/.test(shown) ? `"${shown}"` : shown}`];
+  const merging = differs.length ? ", merges the .kit files into yours" : "";
+  const push = github ? `\nThen it pushes main to github.com/${repo}, once you agree.` : "";
+  list("Next", [
+    ...cd,
+    `Open Claude Code (${out.cyan("claude")}) and say ${out.cyan('"follow BOOTSTRAP.md"')}\nIt asks a few questions${merging}, fills in the setup and makes the first commit.${push}`,
+  ]);
+}
+
+/**
+ * Compares each of the kit's files with the repo's and with the record of what the kit wrote:
+ * - the kit's file hasn't changed, or the repo has it already: nothing to do;
+ * - the repo didn't change it: updated (or added, if the kit's is new);
+ * - the repo changed it: the kit's version goes next to it, as <file>.kit, to merge;
+ * - the repo deleted it: it stays deleted.
+ * A file the kit no longer has is removed, unless the repo changed it.
+ * Without a record (agk 0.1.0 kept none), a file that differs from the kit's counts as changed.
+ */
+async function update(args) {
+  const { folder, shown } = parse("update", args, []);
+  header(VERSION, "Bringing the kit's changes into a repo");
+  if (!fs.existsSync(folder) || !fs.statSync(folder).isDirectory()) throw new Failure(`${shown} isn't a folder`);
+  const probe = git(folder, "rev-parse", "--show-toplevel");
+  if (probe.error) throw noGit();
+  if (probe.status !== 0) {
+    throw new Failure(`${shown === "." ? "This folder" : shown} isn't in a git repo`, {
+      hint: "agk update works in a repo the kit set up. To set one up, run agk setup.",
+    });
+  }
+  const root = path.resolve(probe.stdout.trim());
+  const record = readRecord(root);
+  if (!record && !setUpAlready(root)) {
+    throw new Failure("The kit isn't set up in this repo", { hint: `To set it up, run agk setup. ${NOTHING_CHANGED}` });
+  }
+  if (record && newer(record.version, VERSION)) {
+    throw new Failure(`This repo has the kit of agk v${record.version}, newer than this agk (v${VERSION})`, {
+      hint: `Update agk first: npm install -g ${PACKAGE} (or git pull, in a clone). ${NOTHING_CHANGED}`,
+    });
+  }
+
+  const files = kitFiles().filter((f) => f.to !== SETUP_ONLY);
+  const wrote = record?.files ?? {};
+  const c = { updated: [], added: [], merge: [], deleted: [], removed: [], kept: [] };
+  for (const f of files) {
+    const here = hashAt(root, f.to);
+    const before = wrote[f.to] ?? null;
+    if ((record && f.hash === before) || here === f.hash) continue;
+    if (here === null) (before === null ? c.added : c.deleted).push(f.to);
+    else (here === before ? c.updated : c.merge).push(f.to);
+  }
+  const kit = new Map(files.map((f) => [f.to, f]));
+  for (const [rel, before] of Object.entries(wrote)) {
+    const here = kit.has(rel) || rel === SETUP_ONLY ? null : hashAt(root, rel);
+    if (here !== null) (here === before ? c.removed : c.kept).push(rel);
+  }
+
+  for (const rel of [...c.updated, ...c.added]) put(root, rel, kit.get(rel).text);
+  for (const rel of c.merge) put(root, kitCopy(rel), kit.get(rel).text);
+  for (const rel of c.removed) remove(root, rel);
+  const recorded = writeRecord(root, files);
+
+  if (!record) warn(`No ${RECORD} (agk 0.1.0 kept none), so a file that differs from the kit's counts as yours`);
+  const report = (paths, say, text) => {
+    if (!paths.length) return;
+    say(text(count(paths.length, "file"), paths.length));
+    details(paths);
+  };
+  report(c.updated, ok, (n) => `Updated ${n} you hadn't changed`);
+  report(c.added, ok, (n) => `Added ${n} new in the kit`);
+  report(c.removed, ok, (n) => `Removed ${n} the kit no longer has`);
+  const how = record ? "changed both here and in the kit" : "differ from the kit's";
+  report(c.merge, warn, (n, k) => `${n} ${how}: the kit's version is next to ${each(k)}, as <file>.kit`);
+  report(c.kept, warn, (n, k) => `Kept ${n} you changed, though the kit no longer has ${k === 1 ? "it" : "them"}`);
+  report(c.deleted, warn, (n, k) => `Left ${n} deleted, as you had ${k === 1 ? "it" : "them"}, though the kit changed ${k === 1 ? "it" : "them"}`);
+  const touched = c.updated.length + c.added.length + c.removed.length + c.merge.length;
+  if (!touched && !recorded) {
+    ok(`Up to date with the kit (v${VERSION})`);
+    blank();
+    return;
+  }
+  if (recorded) ok(`Recorded the kit's files (v${VERSION}) in ${RECORD}`);
+  const merge = `Open Claude Code (${out.cyan("claude")}) and say ${out.cyan('"merge the .kit files"')}\nIt brings what's new in each into your file, then deletes the .kit file.\ndoctor reports them until then.`;
+  list("Next", [
+    ...(c.merge.length ? [merge] : []),
+    `Review the changes (${out.cyan("git status")}), then commit them on a branch, as any change`,
+  ]);
+}
+
+function help() {
+  header(VERSION, "Sets up git repos for Claude Code");
+  const row = (a, b) => line(`  ${out.cyan(a.padEnd(30))}${b}`);
+  line(out.bold("Usage"));
+  row("agk setup [folder] [options]", "Set up folder (default: this one): git init if needed,");
+  row("", "then the kit's files. For a file it has already, the");
+  row("", "kit's version goes next to it, as <file>.kit, to merge");
+  row("agk update [folder]", "Bring in the kit's changes: updates the files the repo");
+  row("", "hasn't changed, and puts the kit's next to the others");
+  row("agk help", "Show this help");
+  row("agk --version", "Print the version");
+  blank();
+  line(out.bold("Setup options"));
+  row("--github", "Also create the repo on GitHub (with gh), as remote origin");
+  row("--public", "With --github: make it public (default: private)");
+  blank();
+  line(out.bold("Examples"));
+  for (const e of ["agk setup", "agk setup my-app --github", "agk update"]) line(`  ${out.dim("$")} ${e}`);
+  blank();
+}
+
+async function main([cmd, ...args]) {
+  const wantsHelp = args.includes("--help") || args.includes("-h");
+  switch (cmd) {
+    case "setup":
+      return wantsHelp ? help() : setup(args);
+    case "update":
+      return wantsHelp ? help() : update(args);
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      return help();
+    case "--version":
+    case "-v":
+      return console.log(VERSION);
+    default:
+      throw new Failure(`Unknown command '${cmd}'`, { hint: "Run agk help for the commands." });
+  }
+}
+
+main(process.argv.slice(2)).catch((e) => {
+  if (!(e instanceof Failure)) throw e;
+  showFailure(e);
+  process.exitCode = 1;
+});

package/lib/kit.mjs

@@ -0,0 +1,125 @@
+// The kit's files, and the record agk keeps of them in each repo it sets up (.claude/agk.json):
+// the hash of each file as the kit wrote it. agk update compares a repo's files with it, to tell
+// the files the repo changed from those it didn't.
+// Text is compared and written with LF endings, whatever endings a checkout has.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Failure } from "./ui.mjs";
+
+export const KIT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export const TEMPLATE = path.join(KIT, "template");
+const pkg = JSON.parse(fs.readFileSync(path.join(KIT, "package.json"), "utf8"));
+export const VERSION = pkg.version;
+/** The npm package agk comes in. */
+export const PACKAGE = pkg.name;
+export const RECORD = ".claude/agk.json";
+/** The setup's instructions. The bootstrap deletes the file, so agk update never brings it back. */
+export const SETUP_ONLY = "BOOTSTRAP.md";
+const HOOK = ".githooks/pre-commit";
+// Kept under other names in the kit, so Claude Code working on the kit doesn't load the template's
+// CLAUDE.md and skills as the kit's own. The template's name -> the name in a repo.
+const RENAMED = { "CLAUDE.template.md": "CLAUDE.md", "dot-claude": ".claude" };
+
+/** Where the kit puts its version of a file a repo already has, or changed: next to it. */
+export const kitCopy = (rel) => `${rel}.kit`;
+
+function walk(dir, rel = "") {
+  return fs.readdirSync(path.join(dir, rel), { withFileTypes: true }).flatMap((e) => {
+    const child = path.join(rel, e.name);
+    return e.isDirectory() ? walk(dir, child) : [child];
+  });
+}
+
+const lf = (file) => fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n");
+const hash = (text) => crypto.createHash("sha256").update(text).digest("hex");
+
+/**
+ * The kit's files, sorted by `to`: where each is in template/ (`from`), its path in a repo (`to`,
+ * with forward slashes), its text and that text's hash.
+ */
+export function kitFiles() {
+  return walk(TEMPLATE)
+    .map((from) => {
+      const [first, ...rest] = from.split(path.sep);
+      const text = lf(path.join(TEMPLATE, from));
+      return { from, to: [RENAMED[first] ?? first, ...rest].join("/"), text, hash: hash(text) };
+    })
+    .sort((a, b) => (a.to < b.to ? -1 : 1));
+}
+
+/** The hash of a repo's file; null if there's nothing there, "not a file" for a folder. */
+export function hashAt(root, rel) {
+  const file = path.join(root, rel);
+  if (!fs.existsSync(file)) return null;
+  return fs.statSync(file).isFile() ? hash(lf(file)) : "not a file";
+}
+
+/** Writes a file, making its folders. The git hook is made executable. */
+export function put(root, rel, text) {
+  const file = path.join(root, rel);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+  if (rel === HOOK) fs.chmodSync(file, 0o755);
+}
+
+/** Deletes a file, then the folders it leaves empty, up to the repo's root. */
+export function remove(root, rel) {
+  fs.rmSync(path.join(root, rel));
+  for (let dir = path.dirname(rel); dir !== "."; dir = path.dirname(dir)) {
+    const full = path.join(root, dir);
+    if (fs.readdirSync(full).length) break;
+    fs.rmdirSync(full);
+  }
+}
+
+/** A path in a repo, as the record may hold one: relative, inside the repo, and not in .git. */
+const inRepo = (rel) => !/^[\\/]|^[a-z]:|\\/i.test(rel) && !rel.split("/").some((p) => p === ".." || p === "") && !/^\.git(\/|$)/.test(rel);
+
+/** A repo's record, or null if it has none. */
+export function readRecord(root) {
+  const file = path.join(root, RECORD);
+  if (!fs.existsSync(file)) return null;
+  let record;
+  try {
+    record = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {}
+  const files = record?.files;
+  const valid =
+    typeof record?.version === "string" &&
+    files &&
+    typeof files === "object" &&
+    Object.entries(files).every(([rel, h]) => inRepo(rel) && typeof h === "string");
+  if (!valid) {
+    throw new Failure(`${RECORD} isn't what agk wrote`, {
+      hint: `agk reads it to tell the files you changed. Restore it from git, or delete it to update\nas if the repo had none. Nothing was changed.`,
+    });
+  }
+  return record;
+}
+
+/** Records the kit's files (but the setup's instructions) in a repo. False if it held that already. */
+export function writeRecord(root, files) {
+  const record = {
+    about: "Written by agk setup and agk update: the kit's files as it wrote them, so agk update can tell the ones you changed.",
+    version: VERSION,
+    files: Object.fromEntries(files.filter((f) => f.to !== SETUP_ONLY).map((f) => [f.to, f.hash])),
+  };
+  const text = `${JSON.stringify(record, null, 2)}\n`;
+  const file = path.join(root, RECORD);
+  if (fs.existsSync(file) && lf(file) === text) return false;
+  put(root, RECORD, text);
+  return true;
+}
+
+/** True if the kit has set up `root`: it has a record, or a file only the kit writes (agk 0.1.0 kept no record). */
+export const setUpAlready = (root) =>
+  [RECORD, ".claude/skills/agent-setup/SKILL.md"].some((rel) => fs.existsSync(path.join(root, rel)));
+
+/** True if version `a` is newer than `b` (both like 1.2.3). */
+export function newer(a, b) {
+  const [x, y] = [a, b].map((v) => v.split(".").map((n) => Number.parseInt(n, 10) || 0));
+  for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) > (y[i] ?? 0);
+  return false;
+}