@gonxped31/agent-kit 0.0.0-stage → 0.3.0

package/lib/setup.mjs

@@ -0,0 +1,205 @@
+// agk setup: copies the kit (and a preset, if any) into a folder, then the agent there follows
+// BOOTSTRAP.md. Where the folder has one of the 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.
+import fs from "node:fs";
+import path from "node:path";
+import { NOTHING_CHANGED, each, exclusive, gh, git, noGit, parse, said, shownPath } from "./cli.mjs";
+import { SETUP_ONLY, VERSION, hashAt, kitCopy, kitFiles, put, setUpAlready, writeRecord } from "./kit.mjs";
+import { DEFAULT, compose, loadPreset, presetRecord, presetSummary } from "./presets.mjs";
+import { Failure, clip, count, details, header, list, ok, out, step, warn } from "./ui.mjs";
+
+/** 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 file. 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, files) {
+  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 = files.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, leaveOut) {
+  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 ${leaveOut}. ${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 ${leaveOut}. ${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;
+}
+
+/** The preset to use: --preset's, else the default one unless --no-preset. */
+function choosePreset(opts, vals) {
+  const name = vals["--preset"];
+  if (name) {
+    const preset = loadPreset(name);
+    if (!preset) throw new Failure(`There's no preset named ${name}`, { hint: `agk preset list shows yours. ${NOTHING_CHANGED}` });
+    return { preset, note: "" };
+  }
+  if (opts.has("--no-preset")) return { preset: null, note: "" };
+  const preset = loadPreset(DEFAULT);
+  return { preset, note: preset ? out.dim(" (your default; --no-preset leaves it out)") : "" };
+}
+
+export async function setup(args) {
+  const { opts, vals, pos } = parse("setup", args, {
+    flags: ["--github", "--no-github", "--public", "--private", "--no-preset"],
+    values: ["--preset"],
+  });
+  exclusive(opts, "--github", "--no-github");
+  exclusive(opts, "--public", "--private");
+  if (vals["--preset"] && opts.has("--no-preset")) throw new Failure("--preset and --no-preset don't go together");
+  const root = path.resolve(pos[0] ?? ".");
+  const shown = shownPath(root);
+  header(VERSION, "Setting up a repo for Claude Code");
+
+  // 1. Look, changing nothing: anything that would stop the setup stops it here.
+  const { preset, note } = choosePreset(opts, vals);
+  const defaults = preset?.meta.defaults ?? {};
+  const github = opts.has("--github") || (!opts.has("--no-github") && defaults.github === true);
+  const visibility = opts.has("--public") || (!opts.has("--private") && defaults.visibility === "public") ? "public" : "private";
+  for (const flag of ["--public", "--private"]) if (opts.has(flag) && !github) throw new Failure(`${flag} goes with --github`);
+  const { files, warnings } = compose(kitFiles(), preset);
+  const plan = inspect(root, shown, files);
+  let repo = "";
+  if (github) {
+    // Said in every hint: how to do without GitHub, whether --github or the preset asked for it.
+    const leaveOut = opts.has("--github") ? "leave out --github" : `add --no-github (preset ${preset.name} asks for GitHub)`;
+    if (plan.origin) {
+      throw new Failure(`This repo already has a remote origin: ${plan.origin}`, { hint: `To set it up anyway, ${leaveOut}. ${NOTHING_CHANGED}` });
+    }
+    const name = repoName(root);
+    await step("Checking GitHub", async () => {
+      repo = `${await checkGitHub(name, leaveOut)}/${name}`;
+      return `GitHub: github.com/${repo} is free`;
+    });
+  }
+
+  // 2. Set up the folder.
+  if (preset) ok(`Preset ${out.cyan(preset.name)}: ${presetSummary(plan.files)}${note}`);
+  for (const w of warnings) warn(w);
+  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, { preset: preset && presetRecord(preset, plan.files) });
+  const total = plan.files.length;
+  const whose = preset ? "" : "the kit's ";
+  if (fresh.length === total) {
+    ok(preset ? `Copied all ${total} files` : `Copied the kit's ${total} files ${out.dim("(CLAUDE.md, BOOTSTRAP.md, .claude/, scripts/ and more)")}`);
+  } else {
+    ok(`Copied ${fresh.length} of ${whose}${total} files`);
+    if (same.length) ok(`${count(same.length, "file")} already here, the same as the ${preset ? "setup's" : "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}`,
+  ]);
+}

package/lib/ui.mjs

@@ -0,0 +1,145 @@
+// How agk prints: colors, symbols and a spinner, with plain fallbacks.
+// - Color is on for a terminal, unless NO_COLOR is set or TERM is dumb. FORCE_COLOR=1 forces it
+//   on, FORCE_COLOR=0 off.
+// - Symbols are Unicode where the terminal can show them, ASCII elsewhere. On Windows that's only
+//   in Windows Terminal, VS Code and the like: an old console lacks the glyphs, and a pipe may be
+//   decoded with an old code page.
+// - The spinner moves only in a terminal. Elsewhere (a pipe, Claude Code) each step prints one
+//   line when it's done.
+
+import readline from "node:readline";
+
+const env = process.env;
+const tty = Boolean(process.stdout.isTTY) && env.TERM !== "dumb";
+/** True when someone can answer a question: both ends are a terminal. */
+export const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+
+function colorOn(stream) {
+  if (env.FORCE_COLOR) return env.FORCE_COLOR !== "0";
+  return Boolean(stream.isTTY) && !env.NO_COLOR && env.TERM !== "dumb";
+}
+
+const modernWindowsTerminal = Boolean(
+  env.WT_SESSION || env.TERM_PROGRAM === "vscode" || env.TERMINAL_EMULATOR === "JetBrains-JediTerm" || env.ConEmuTask,
+);
+const unicode = process.platform === "win32" ? tty && modernWindowsTerminal : env.TERM !== "linux";
+
+const sym = unicode
+  ? { ok: "✔", fail: "✖", warn: "▲", more: "…", frames: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] }
+  : { ok: "+", fail: "x", warn: "!", more: "...", frames: ["-", "\\", "|", "/"] };
+
+function palette(on) {
+  const wrap = (open, close) => (s) => (on ? `\x1b[${open}m${s}\x1b[${close}m` : String(s));
+  return { bold: wrap(1, 22), dim: wrap(2, 22), red: wrap(31, 39), green: wrap(32, 39), yellow: wrap(33, 39), cyan: wrap(36, 39) };
+}
+/** Styles for stdout, and for stderr (failures). */
+export const out = palette(colorOn(process.stdout));
+const err = palette(colorOn(process.stderr));
+
+const say = (text = "") => process.stdout.write(`${text}\n`);
+export const blank = () => say();
+/** A line indented under the header. */
+export const line = (text) => say(`  ${text}`);
+export const ok = (text) => line(`${out.green(sym.ok)} ${text}`);
+export const warn = (text) => line(`${out.yellow(sym.warn)} ${text}`);
+/** The items of the line above, indented under it (the first 8 of them). */
+export const details = (items) => {
+  for (const item of clip(items)) line(`    ${item}`);
+};
+/** Asks a question in the terminal and returns the answer, trimmed. */
+export function ask(question) {
+  return new Promise((resolve) => {
+    // terminal: false: no raw mode, so it also reads a piped answer (the kit's tests).
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+    process.stdout.write(`  ${out.bold(question)} `);
+    // Resolve before close(): it emits "close" at once, and a closed input answers "".
+    rl.once("line", (answer) => {
+      resolve(answer.trim());
+      rl.close();
+    });
+    rl.once("close", () => resolve(""));
+  });
+}
+/** "1 file", "2 files". */
+export const count = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
+
+export function header(version, subtitle) {
+  blank();
+  line(`${out.bold(out.cyan("agk"))} ${out.dim(`v${version}`)}${subtitle ? `  ${subtitle}` : ""}`);
+  blank();
+}
+
+/** A numbered list under a bold title. An item's later lines are dimmed, as its explanation. */
+export function list(title, items) {
+  blank();
+  line(out.bold(title));
+  items.forEach((item, i) => {
+    const [first, ...rest] = item.split("\n");
+    line(`  ${out.cyan(`${i + 1}.`)} ${first}`);
+    for (const r of rest) line(`     ${out.dim(r)}`);
+  });
+  blank();
+}
+
+/** What went wrong, for the user: a message, the lines that show it, and what to do next. */
+export class Failure extends Error {
+  constructor(message, { details = [], hint = "" } = {}) {
+    super(message);
+    this.details = details;
+    this.hint = hint;
+  }
+}
+
+export function showFailure(e) {
+  const lines = [`  ${err.red(sym.fail)} ${err.bold(e.message)}`, ...e.details.map((d) => `      ${d}`)];
+  if (e.hint) lines.push(...e.hint.split("\n").map((h) => `    ${h}`));
+  process.stderr.write(`${lines.join("\n")}\n\n`);
+}
+
+/** Up to `max` items, then "... and N more". */
+export function clip(items, max = 8) {
+  return items.length <= max ? items : [...items.slice(0, max), `${sym.more} and ${items.length - max} more`];
+}
+
+let cursorHidden = false;
+function showCursor() {
+  if (cursorHidden) process.stdout.write("\x1b[?25h");
+  cursorHidden = false;
+}
+process.on("exit", showCursor);
+process.on("SIGINT", () => {
+  if (tty) process.stdout.write("\r\x1b[2K");
+  showCursor();
+  process.exit(130);
+});
+
+/**
+ * Runs `work` (async) behind a spinner, then marks the step done with the text `work` returns,
+ * or `text`. If `work` throws, the spinner is cleared and the error goes on.
+ */
+export async function step(text, work) {
+  if (!tty) {
+    ok((await work()) ?? text);
+    return;
+  }
+  let frame = 0;
+  const draw = () => process.stdout.write(`\r\x1b[2K  ${out.cyan(sym.frames[frame++ % sym.frames.length])} ${text}${out.dim(sym.more)}`);
+  process.stdout.write("\x1b[?25l");
+  cursorHidden = true;
+  draw();
+  const timer = setInterval(draw, 80);
+  const stop = () => {
+    clearInterval(timer);
+    process.stdout.write("\r\x1b[2K");
+    showCursor();
+  };
+  let done;
+  try {
+    done = await work();
+  } catch (e) {
+    stop();
+    throw e;
+  }
+  stop();
+  ok(done ?? text);
+}

package/lib/update.mjs

@@ -0,0 +1,97 @@
+// agk update: brings the kit's (and the preset's) later changes into a repo the kit set up.
+//
+// It compares each file agk writes now with the repo's file and with the record of what agk wrote:
+// - agk's file hasn't changed, or the repo has it already: nothing to do;
+// - the repo didn't change it: updated (or added, if it's new);
+// - the repo changed it: agk's version goes next to it, as <file>.kit, to merge;
+// - the repo deleted it: it stays deleted.
+// A file agk no longer writes 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.
+// If the repo's preset isn't on this machine, the files it added or changed stay as they are.
+import fs from "node:fs";
+import path from "node:path";
+import { NOTHING_CHANGED, each, parse, repoRoot, shownPath } from "./cli.mjs";
+import { PACKAGE, RECORD, SETUP_ONLY, VERSION, hashAt, kitCopy, kitFiles, newer, put, readRecord, remove, setUpAlready, writeRecord } from "./kit.mjs";
+import { compose, loadPreset, presetRecord } from "./presets.mjs";
+import { Failure, blank, count, details, header, list, ok, out, warn } from "./ui.mjs";
+
+export async function update(args) {
+  const { pos } = parse("update", args);
+  const folder = path.resolve(pos[0] ?? ".");
+  const shown = shownPath(folder);
+  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 root = repoRoot(folder, "update");
+  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}`,
+    });
+  }
+
+  // The preset the repo was set up with, if it's on this machine. If not, its files are left out.
+  const used = record?.preset;
+  const preset = used ? loadPreset(used.name) : null;
+  const skip = new Set(used && !preset ? used.files ?? [] : []);
+  const composed = compose(kitFiles(), preset);
+  const files = composed.files.filter((f) => f.to !== SETUP_ONLY && !skip.has(f.to));
+  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 ours = new Map(files.map((f) => [f.to, f]));
+  for (const [rel, before] of Object.entries(wrote)) {
+    const here = ours.has(rel) || skip.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, ours.get(rel).text);
+  for (const rel of c.merge) put(root, kitCopy(rel), ours.get(rel).text);
+  for (const rel of c.removed) remove(root, rel);
+  const keep = Object.fromEntries([...skip].filter((rel) => rel in wrote).map((rel) => [rel, wrote[rel]]));
+  const recorded = writeRecord(root, files, { preset: preset ? presetRecord(preset, files) : used ?? null, keep });
+
+  if (!record) warn(`No ${RECORD} (agk 0.1.0 kept none), so a file that differs from the kit's counts as yours`);
+  if (used && !preset) {
+    warn(
+      `This repo uses preset ${used.name}, which isn't on this machine: its ${count(skip.size, "file")} stay as they are` +
+        (used.source ? `\n    To get it: agk preset add ${used.source}` : ""),
+    );
+  }
+  for (const w of composed.warnings) warn(w);
+  const source = preset ? `the kit or preset ${preset.name}` : "the kit";
+  const report = (paths, say, text) => {
+    if (!paths.length) return;
+    say(text(count(paths.length, "file"), paths.length));
+    details(paths);
+  };
+  const them = (k) => (k === 1 ? "it" : "them");
+  report(c.updated, ok, (n) => `Updated ${n} you hadn't changed`);
+  report(c.added, ok, (n) => `Added ${n} new in ${source}`);
+  report(c.removed, ok, (n) => `Removed ${n} ${source} no longer has`);
+  const how = record ? `changed both here and in ${source}` : "differ from the kit's";
+  report(c.merge, warn, (n, k) => `${n} ${how}: the ${preset ? "new" : "kit's"} version is next to ${each(k)}, as <file>.kit`);
+  report(c.kept, warn, (n, k) => `Kept ${n} you changed, though ${source} no longer has ${them(k)}`);
+  report(c.deleted, warn, (n, k) => `Left ${n} deleted, as you had ${them(k)}, though ${source} changed ${them(k)}`);
+  const touched = c.updated.length + c.added.length + c.removed.length + c.merge.length;
+  if (!touched && !recorded) {
+    ok(`Up to date with ${preset ? `the kit (v${VERSION}) and preset ${preset.name}` : `the kit (v${VERSION})`}`);
+    blank();
+    return;
+  }
+  if (recorded) ok(preset ? `Recorded the files (v${VERSION}, preset ${preset.name}) in ${RECORD}` : `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`,
+  ]);
+}
+

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@gonxped31/agent-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Sets up git repos for Claude Code, and keeps them up to date: a short CLAUDE.md, git and todo skills, hooks and checks.",
+  "license": "MIT",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "agents",
+    "git-hooks",
+    "cli"
+  ],
+  "bin": {
+    "agk": "bin/agk.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "template/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/kit.test.mjs"
+  }
+}

package/template/.gitattributes

@@ -0,0 +1,5 @@
+* text=auto
+# sh can't run a hook with CRLF line endings, so hooks stay LF on every OS.
+.githooks/* text eol=lf
+# Two branches that both finish todos keep both archive lines.
+todo-archive.md merge=union

package/template/.githooks/pre-commit

@@ -0,0 +1,8 @@
+#!/bin/sh
+# Refuses commits on main (except a repo's very first commit), then runs the fast checks.
+# Turned on once per clone: git config core.hooksPath .githooks
+if git rev-parse -q --verify HEAD >/dev/null && [ "$(git symbolic-ref --short -q HEAD)" = "main" ]; then
+  echo "pre-commit: no commits on main. Work on a branch; main moves through node scripts/merge.mjs (git skill)." >&2
+  exit 1
+fi
+exec node scripts/check.mjs --fast

package/template/BOOTSTRAP.md

@@ -0,0 +1,106 @@
+# Bootstrap: set up this repo for agents
+
+agent-kit's `agk setup` copied this file and the setup files into the repo, and ran
+`git init` if it wasn't one yet. Where the repo had one of those files already, it left
+that file as it was and put the kit's version next to it, as `<file>.kit`. Follow these
+steps once, in order. Step 6 deletes this file.
+
+## 1. Look before asking
+
+Find out on your own:
+- Does it have commits (`git log --oneline -3`)? If so, its main branch must be called
+  `main` (the hook and `scripts/merge.mjs` assume it). If it's called something else,
+  ask the user before renaming it.
+- Remotes (`git remote -v`). None is fine: the `git` skill handles both.
+  `agk setup --github` adds an empty GitHub repo as `origin`.
+- The stack, from what's there: `package.json`, `pyproject.toml`, `go.mod`,
+  `Cargo.toml`, a README.
+- The preset, if `.claude/agk.json` names one: the user's own setup, added to the
+  kit's. Keep what it added, and don't ask what it answers already (check steps say
+  how to test, for example).
+- Uncommitted work (`git status --short`) in `scripts/`, `docs/` or `.claude/` that
+  isn't the kit's (`.claude/agk.json` lists the kit's files): step 6 stages those
+  folders whole, so ask the user to commit it first.
+- Git hooks of its own (`git config core.hooksPath`, `.husky/`): step 5 points git at
+  `.githooks/` instead, which turns them off. Ask the user; to keep both,
+  `.githooks/pre-commit` can run theirs.
+
+## 2. Ask, in one message
+
+Ask only what step 1 didn't answer. "Don't know yet" is a good answer: it becomes a
+todo (step 4), never a guess.
+
+1. The project's name, and what it is in 2-3 sentences.
+2. The stack, if it's chosen: language, framework, how to test and lint.
+3. Does `main` deploy anywhere when it changes?
+4. What must never break?
+5. What do you need to see before a change counts as done (tests, screenshots, a demo)?
+6. Is there anything agents must never read or change (large data, secrets, generated files)?
+
+## 3. Fill in the setup
+
+- Each `<file>.kit` (`node scripts/doctor.mjs` lists them) is the kit's version of a
+  file the repo had. Merge it into that file: keep what the repo has, add what the
+  kit's brings (for `CLAUDE.md` its sections, for `.claude/settings.json` its hooks
+  and rules), and ask the user where they conflict. Then delete the `.kit` file.
+- `CLAUDE.md`: replace every `{{...}}`. Write only the rules the user gave, one bullet
+  each. Keep it short: it's in context on every turn.
+- If `main` deploys, add to "Working here": "`main` deploys to <where> on every merge."
+- Never read or change → `deny` rules in `.claude/settings.json`, e.g.
+  `Read(./data/**)` and `Edit(./data/**)`.
+- If the stack is known, do the "stack chosen" row of step 4 now instead of adding it.
+
+## 4. Add a todo for everything deferred
+
+`T` stands for `node .claude/skills/todo/scripts/todo.mjs`. One todo per deferred
+part. Its detail holds the trigger, what to do and why, and must stand alone: this
+file will be gone.
+
+    T add 'Stack chosen: checks, ignores, deny rules' -p 1 --tag setup
+    T detail <ID> 'Trigger: ... Do: ... Why: ...'
+
+Single quotes, not double: the `todo` skill says why, and what to do about apostrophes.
+
+| Trigger | Do |
+| :--- | :--- |
+| The stack is chosen | Add its checks to `scripts/check.json` (`{ "name": "test", "run": "npm test", "slow": true }`; `slow` steps skip the pre-commit hook but run in `check` and `merge`). Add a `.gitignore`, `deny` reads of dependency and build folders, and allow the check commands in `.claude/settings.json`. |
+| The first screen exists (if there's a UI) | A skill that screenshots it at phone and desktop sizes and flags overflow and console errors. |
+| A remote is added (or `agk setup --github` added one) | CI that runs `node scripts/check.mjs`. |
+| A "don't know yet" from step 2 | Ask again then. |
+
+Add any others the answers suggest, e.g. large data files coming: `deny` reads of
+them, and a script that queries them with short output.
+
+## 5. Turn on the hooks and check
+
+    git config core.hooksPath .githooks
+    node scripts/check.mjs
+
+Fix whatever `check` reports (it runs `doctor`) until it prints OK.
+
+## 6. Delete this file and commit
+
+1. Delete `BOOTSTRAP.md`.
+2. Stage by name, adding `todos` if step 4 added any and `.gitignore` if you wrote one:
+
+       git add CLAUDE.md .claude/settings.json .claude/skills .claude/agk.json .githooks scripts docs .gitattributes
+       git add --chmod=+x .githooks/pre-commit
+
+   Not all of `.claude`: Claude Code may keep the user's personal `settings.local.json`
+   there, and a machine's git ignore can miss it. `.claude/agk.json` records the kit's
+   files, for `agk update`. The `--chmod` line is for Windows, which doesn't record the
+   executable bit.
+3. If the repo had no commits, commit on `main`: the hook allows a repo's first commit
+   there. Otherwise `git switch -c agent-setup`, commit, and merge with
+   `node scripts/merge.mjs` once the user approves.
+   Message: `Agent setup: <what was set up>`.
+4. If there's a remote (`git remote`), push `main` once the user agrees:
+   `git push -u origin main`.
+
+## 7. Report
+
+In a few lines: what was set up, the todos added (`T list`), and two notes for the user:
+- The git hooks are turned on per clone. After cloning this repo elsewhere, run
+  `git config core.hooksPath .githooks` (`doctor` says so when they're off).
+- Personal habits that hold in every repo belong in `~/.claude/CLAUDE.md`, not here.
+- `agk update` brings in the kit's later changes.

package/template/CLAUDE.template.md

@@ -0,0 +1,36 @@
+# {{NAME}}
+
+{{WHAT IT IS, in 2-3 sentences}}
+
+This file holds what must stay true on **every** change. Everything else loads on
+demand: skills by their descriptions, a folder's rules from its own `CLAUDE.md`, and
+the docs below.
+
+| Need | Where |
+| :--- | :--- |
+| Session habits: one task per session, `/clear`, reading narrowly | `docs/workflow.md` |
+
+## Always true
+
+{{RULES: what must never break, one bullet each. Remove this section if there are none yet.}}
+
+## Working here
+
+- **Every task starts on its own branch.** `main` moves only through
+  `node scripts/merge.mjs`, after the user approves (`git` skill).
+- **Deferred work is a todo with its trigger** ("when X happens, do Y"), never a note
+  in chat (`todo` skill).
+- **Before finishing a task, check the todos**
+  (`node .claude/skills/todo/scripts/todo.mjs list --all`) for items the work
+  triggers: do them, or tell the user they're due.
+- **New rules, skills, hooks or docs for agents** follow the `agent-setup` skill: a
+  check beats a written rule, and nothing is written twice.
+
+## Commands
+
+| Command | What it does |
+| :--- | :--- |
+| `node scripts/check.mjs` | Every check in `scripts/check.json`: only what failed, then OK or FAIL (`--verbose` for full output) |
+| `node scripts/doctor.mjs` | The agent setup: size limits, dead paths, hooks turned on |
+
+**Before calling a change done:** `node scripts/check.mjs` passes.

package/template/docs/workflow.md

@@ -0,0 +1,15 @@
+# Session workflow
+
+Habits that keep sessions cheap and focused.
+
+- **One task per session.** `todo next`, finish it, `todo done`, stop.
+- **`/clear` between unrelated tasks.** Old context costs tokens on every turn.
+- **`/compact` with a focus** when a long task must go on, e.g.
+  `/compact keep the failing test names and the files changed`.
+- **`/context` and `/cost`** show what's using the window, and the money, before you
+  guess.
+- **Change `CLAUDE.md` and MCP config between sessions**, not in the middle of one:
+  either change breaks prompt caching for the rest of the session.
+- **Read narrowly.** Grep, or Read with `offset` and `limit`; a hook refuses
+  whole-file reads over 1500 lines.
+- **Run `node scripts/check.mjs`** instead of reading raw test or lint output.