@evertonferreira96/agents 0.0.0-stage → 0.1.0

package/scripts/bootstrap.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// Install this config into a project, keep it updated, or check it for drift.
+// Preferred entry: the package CLI, bin/agents.mjs (`npx <package> init | update | check`).
+// Legacy entry, kept for projects bootstrapped from a local clone:
+//   node scripts/bootstrap.mjs <target>            init: copy what is missing; never overwrite
+//   node scripts/bootstrap.mjs <target> --check    check: list missing, outdated, edited and obsolete files; exit 1 on drift
+//   node scripts/bootstrap.mjs <target> --force    update --force: also overwrite files edited in the project
+//   node scripts/bootstrap.mjs --sync              inside a project bootstrapped from a local clone: pull it, then update
+// Protected (never written over): CLAUDE.md, .claude/settings.local.json, .claude/agent-memory/**
+// .claude/config-manifest.json records the hash of every file the config installed. `update` uses it to tell a file that is
+// only outdated (overwritten) from one edited in the project (kept unless --force), and deletes files that left the config
+// only when the project copy is untouched.
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, rmdirSync, statSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const SYNC = [".claude/agents", ".claude/hooks", ".claude/rules", ".claude/skills", ".claude/settings.json", "AGENTS.md", ".worktreeinclude",
+  "docs/plans/README.md", "docs/adr/README.md", "docs/brief-template.md", "scripts/skills-update.mjs", "scripts/check-catalog.mjs", "scripts/bootstrap.mjs", "skills-lock.json"];
+export const SKIP = /(^|\/)(scripts\/bin|__pycache__|node_modules|\.context-band)(\/|$)|\.pyc$/;
+export const PROTECTED = /^(CLAUDE\.md|\.claude\/settings\.local\.json|\.claude\/agent-memory\/.*)$/;
+export const GITIGNORE = [".claude/worktrees/", ".claude/handoffs/", ".claude/.context-band", ".claude/.stop-verify-ran", ".claude/settings.local.json",
+  ".claude/agent-memory-local/", "graphify-out/", ".claude/skills/impeccable/scripts/bin/", "__pycache__/", "*.pyc"];
+export const MANIFEST = ".claude/config-manifest.json";
+export const SOURCE_FILE = ".claude/config-source.json";
+export const DEFAULT_SRC = fileURLToPath(new URL("..", import.meta.url));
+
+const sha = (p) => createHash("sha256").update(readFileSync(p)).digest("hex");
+const readJson = (p) => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } };
+function* walk(p) { if (statSync(p).isDirectory()) { for (const n of readdirSync(p)) yield* walk(join(p, n)); } else yield p; }
+
+// Name and version of the config at `src`: package.json first, VERSION as fallback.
+export function readPackage(src = DEFAULT_SRC) {
+  const pkg = readJson(join(src, "package.json")) || {};
+  const versionFile = join(src, "VERSION");
+  const version = pkg.version || (existsSync(versionFile) ? readFileSync(versionFile, "utf8").trim() : "unknown");
+  return { name: pkg.name || "agents-config", version };
+}
+
+// Every file the config installs, keyed by its path relative to the config root (forward slashes).
+export function configFiles(src = DEFAULT_SRC) {
+  const files = new Map();
+  for (const entry of SYNC) {
+    const abs = join(src, entry);
+    if (!existsSync(abs)) continue;
+    for (const f of walk(abs)) {
+      const rel = relative(src, f).split(sep).join("/");
+      if (!SKIP.test(rel)) files.set(rel, f);
+    }
+  }
+  return files;
+}
+
+function removeEmptyParents(target, rel) {
+  let dir = dirname(join(target, rel));
+  const root = resolve(target);
+  while (resolve(dir) !== root && existsSync(dir) && readdirSync(dir).length === 0) {
+    rmdirSync(dir);
+    dir = dirname(dir);
+  }
+}
+
+// mode: "init" (copy what is missing), "update" (also refresh untouched files and drop obsolete ones), "check" (report only).
+export function install({ src = DEFAULT_SRC, target, mode = "init", force = false, dryRun = false }) {
+  if (!["init", "update", "check"].includes(mode)) throw new Error(`unknown mode: ${mode}`);
+  if (!target || !existsSync(target) || !statSync(target).isDirectory()) throw new Error(`target is not a directory: ${target}`);
+  if (resolve(target) === resolve(src)) throw new Error("target is the config repo itself; pass a project directory");
+
+  const write = mode !== "check" && !dryRun;
+  const pkg = readPackage(src);
+  const files = configFiles(src);
+  const previous = readJson(join(target, MANIFEST));
+  const installed = previous?.files ?? null; // hashes of what the config wrote last time
+  const next = {};
+  const r = { pkg, mode, dryRun, force, hadManifest: Boolean(installed), same: 0, added: [], updated: [], kept: [], removed: [], obsoleteKept: [], missing: [], outdated: [], edited: [], obsolete: [], written: [] };
+
+  for (const [rel, abs] of files) {
+    const want = sha(abs);
+    const dst = join(target, rel);
+    if (!existsSync(dst)) {
+      if (mode === "check") { r.missing.push(rel); continue; }
+      if (write) { mkdirSync(dirname(dst), { recursive: true }); copyFileSync(abs, dst); }
+      r.added.push(rel); next[rel] = want;
+      continue;
+    }
+    const have = sha(dst);
+    if (have === want) { r.same++; next[rel] = want; continue; }
+    const untouched = installed?.[rel] === have;
+    if (mode === "check") { (untouched ? r.outdated : r.edited).push(rel); continue; }
+    if (mode === "update" && (untouched || force) && !PROTECTED.test(rel)) {
+      if (write) copyFileSync(abs, dst);
+      r.updated.push(rel); next[rel] = want;
+      continue;
+    }
+    r.kept.push(rel);
+    if (installed?.[rel]) next[rel] = installed[rel];
+  }
+
+  for (const [rel, hash] of Object.entries(installed ?? {})) {
+    if (files.has(rel)) continue;
+    const dst = join(target, rel);
+    if (!existsSync(dst)) continue;
+    const untouched = sha(dst) === hash;
+    if (mode === "check") { r.obsolete.push(rel); continue; }
+    if (mode === "update" && untouched && !PROTECTED.test(rel)) {
+      if (write) { rmSync(dst); removeEmptyParents(target, rel); }
+      r.removed.push(rel);
+      continue;
+    }
+    if (mode === "update") r.obsoleteKept.push(rel);
+    next[rel] = hash; // keep tracking it so a later update can still remove it
+  }
+
+  if (mode !== "check") {
+    const isClone = existsSync(join(src, ".git"));
+    const sourceInfo = { package: pkg.name, version: pkg.version, ...(isClone ? { source: resolve(src) } : {}), syncedAt: new Date().toISOString() };
+    const manifest = { package: pkg.name, version: pkg.version, files: Object.fromEntries(Object.entries(next).sort(([a], [b]) => a.localeCompare(b))) };
+    if (write) {
+      mkdirSync(join(target, ".claude", "agent-memory"), { recursive: true });
+      writeFileSync(join(target, SOURCE_FILE), JSON.stringify(sourceInfo, null, 2) + "\n");
+      writeFileSync(join(target, MANIFEST), JSON.stringify(manifest, null, 2) + "\n");
+    }
+    r.written.push(`${SOURCE_FILE} (${pkg.name} ${pkg.version}${isClone ? `, source ${resolve(src)}` : ""})`, `${MANIFEST} (${Object.keys(next).length} files)`);
+    const claude = join(target, "CLAUDE.md");
+    if (!existsSync(claude)) {
+      if (write) copyFileSync(join(src, "templates", "CLAUDE.project.md"), claude);
+      r.written.push("CLAUDE.md (from templates/CLAUDE.project.md: fill in purpose and commands)");
+    }
+    const gi = join(target, ".gitignore");
+    const have = existsSync(gi) ? readFileSync(gi, "utf8").split(/\r?\n/) : [];
+    const add = GITIGNORE.filter((l) => !have.includes(l));
+    if (add.length) {
+      if (write) appendFileSync(gi, (have.length && have.at(-1) !== "" ? "\n" : "") + add.join("\n") + "\n");
+      r.written.push(`.gitignore (+${add.length} lines)`);
+    }
+  }
+  return r;
+}
+
+export function drift(r) { return r.missing.length + r.outdated.length + r.edited.length + r.obsolete.length; }
+
+export function report(r, log = console.log) {
+  const head = `${r.pkg.name} ${r.pkg.version} - ${r.mode}${r.force ? " --force" : ""}${r.dryRun ? " (dry run: nothing written)" : ""}`;
+  log(head);
+  const list = (label, items, note = "") => { for (const i of items) log(`  ${label.padEnd(8)} ${i}${note}`); };
+  if (r.mode === "check") {
+    log(`${r.same} identical, ${r.missing.length} missing, ${r.outdated.length} outdated, ${r.edited.length} edited here, ${r.obsolete.length} obsolete`);
+    list("missing", r.missing); list("outdated", r.outdated); list("edited", r.edited); list("obsolete", r.obsolete);
+    if (drift(r)) log("run `update` to apply; `update --force` also overwrites the files edited here");
+    return;
+  }
+  log(`${r.added.length} added, ${r.updated.length} updated, ${r.removed.length} removed, ${r.kept.length + r.obsoleteKept.length} kept, ${r.same} unchanged`);
+  list("added", r.added); list("updated", r.updated); list("removed", r.removed);
+  list("kept", r.kept, r.mode === "init" ? "  (differs; init never overwrites)" : "  (edited here)");
+  list("kept", r.obsoleteKept, "  (left the config, but edited here)");
+  if (r.written.length) { log("written:"); for (const w of r.written) log(`  ${w}`); }
+  if (r.mode === "update" && !r.hadManifest && r.kept.length) log("no manifest from a previous install, so differing files count as edited; review them and run `update --force` once to adopt the config versions");
+  else if (r.kept.length && r.mode === "update") log("`update --force` overwrites the files kept above (protected files excepted)");
+  else if (r.kept.length) log("run `update` to refresh differing files");
+}
+
+// Legacy CLI (scripts/bootstrap.mjs <target> [--check|--force] | --sync).
+function legacy(argv) {
+  let [target, ...flags] = argv;
+  let src = DEFAULT_SRC;
+  if (target === "--sync" || flags.includes("--sync")) {
+    const info = readJson(join(process.cwd(), SOURCE_FILE));
+    if (!info) { console.error(`--sync needs ${SOURCE_FILE} (written by a previous install)`); return 2; }
+    if (!info.source || !existsSync(info.source)) {
+      console.log(`This project was installed from the ${info.package || "config"} package. Update it with: npx ${info.package || "<package>"}@latest update`);
+      return 0;
+    }
+    src = info.source; target = process.cwd();
+    if (existsSync(join(src, ".git"))) { const g = spawnSync("git", ["-C", src, "pull", "--ff-only"], { encoding: "utf8" }); console.log((g.stdout || g.stderr || "").trim()); }
+    flags = ["--update", ...flags.filter((f) => f !== "--sync")];
+  }
+  if (!target) { console.error("usage: node scripts/bootstrap.mjs <target-project> [--check|--force] | --sync"); return 2; }
+  const mode = flags.includes("--check") ? "check" : flags.includes("--force") || flags.includes("--update") ? "update" : "init";
+  const r = install({ src, target, mode, force: flags.includes("--force"), dryRun: flags.includes("--dry-run") });
+  report(r);
+  return mode === "check" && drift(r) ? 1 : 0;
+}
+
+const isMain = (() => { try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; } })();
+if (isMain) {
+  try { process.exitCode = legacy(process.argv.slice(2)); } catch (e) { console.error(e.message); process.exitCode = 2; }
+}

package/scripts/check-catalog.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// Drift checks: skills on disk vs docs/skills.md vs frontmatter vs skills-lock.json vs agents' skills: vs settings hooks.
+// Exit 1 on any error. Warnings do not fail.
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+const errors = [], warnings = [];
+const read = (p) => readFileSync(p, "utf8");
+const fm = (p) => read(p).split("---")[1] ?? "";
+
+const skills = readdirSync(".claude/skills").filter((d) => existsSync(`.claude/skills/${d}/SKILL.md`)).sort();
+const catalog = read("docs/skills.md");
+const rows = new Map([...catalog.matchAll(/^\| ([a-z0-9-]+) \| (auto|manual) \|/gm)].map((m) => [m[1], m[2]]));
+const lockFile = JSON.parse(read("skills-lock.json"));
+const lock = lockFile.skills, own = new Set(lockFile.own ?? []);
+
+for (const s of skills) {
+  const f = fm(`.claude/skills/${s}/SKILL.md`);
+  const name = /^name:\s*(\S+)/m.exec(f)?.[1];
+  if (name !== s) errors.push(`${s}: frontmatter name is "${name}"`);
+  const manual = /^disable-model-invocation:\s*true/m.test(f);
+  if (!rows.has(s)) errors.push(`${s}: no row in docs/skills.md`);
+  else if (rows.get(s) !== (manual ? "manual" : "auto")) errors.push(`${s}: catalog says ${rows.get(s)}, frontmatter says ${manual ? "manual" : "auto"}`);
+  if (!existsSync(`.claude/skills/${s}/agents/openai.yaml`)) warnings.push(`${s}: no agents/openai.yaml (Codex metadata)`);
+  if (!lock[s] && !own.has(s)) warnings.push(`${s}: neither in skills-lock.json nor in its "own" list`);
+}
+for (const r of rows.keys()) if (!skills.includes(r)) errors.push(`docs/skills.md row "${r}" has no .claude/skills/${r}/SKILL.md`);
+for (const [n, e] of Object.entries(lock)) {
+  if (!skills.includes(n)) errors.push(`skills-lock.json entry "${n}" has no skill folder`);
+  if (e.sourceType === "github" && !e.sha256) warnings.push(`${n}: lock has no sha256 (run scripts/skills-update.mjs --lock)`);
+}
+for (const a of readdirSync(".claude/agents").filter((f) => f.endsWith(".md"))) {
+  const f = fm(`.claude/agents/${a}`);
+  const block = /^skills:\n((?:\s+-\s+\S+\n)+)/m.exec(f)?.[1] ?? "";
+  for (const s of [...block.matchAll(/-\s+(\S+)/g)].map((m) => m[1])) if (!skills.includes(s)) errors.push(`agent ${a}: preloads unknown skill "${s}"`);
+}
+const settings = JSON.parse(read(".claude/settings.json"));
+for (const list of Object.values(settings.hooks ?? {})) for (const e of list) for (const h of e.hooks ?? []) {
+  const m = /\$CLAUDE_PROJECT_DIR\/(\.claude\/hooks\/[^" ]+)/.exec(h.command ?? "");
+  if (m && !existsSync(m[1])) errors.push(`settings.json: hook file ${m[1]} does not exist`);
+}
+for (const w of warnings) console.log(`warn  ${w}`);
+for (const e of errors) console.log(`ERROR ${e}`);
+console.log(`${skills.length} skills, ${rows.size} catalog rows, ${Object.keys(lock).length} lock entries: ${errors.length} error(s), ${warnings.length} warning(s)`);
+process.exit(errors.length ? 1 : 0);

package/scripts/skills-update.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// Compare vendored skills with their upstream and say what to do.
+//   node scripts/skills-update.mjs          report only
+//   node scripts/skills-update.mjs --lock   also record the upstream sha256 and commit in skills-lock.json
+// Needs Node 18+ (global fetch). No dependencies.
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+
+const LOCK = "skills-lock.json";
+const lock = JSON.parse(readFileSync(LOCK, "utf8"));
+const writeLock = process.argv.includes("--lock");
+const sha = (s) => createHash("sha256").update(s).digest("hex");
+const headers = (url) => ({
+  "User-Agent": "skills-update",
+  // the token only helps api.github.com rate limits; raw.githubusercontent.com rejects it
+  ...(process.env.GITHUB_TOKEN && url.startsWith("https://api.github.com/") ? { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` } : {}),
+});
+
+async function text(url) {
+  try { const r = await fetch(url, { headers: headers(url) }); return r.ok ? await r.text() : null; } catch { return null; }
+}
+async function latestCommit(src, path) {
+  const j = await text(`https://api.github.com/repos/${src}/commits?path=${encodeURIComponent(path)}&per_page=1`);
+  try { return JSON.parse(j)[0]?.sha?.slice(0, 7) ?? null; } catch { return null; }
+}
+
+const rows = [];
+for (const [name, e] of Object.entries(lock.skills)) {
+  const localFile = `.claude/skills/${name}/SKILL.md`;
+  const local = existsSync(localFile) ? sha(readFileSync(localFile, "utf8").replace(/\r\n/g, "\n")) : null;
+  if (e.sourceType !== "github" || !e.skillPath) {
+    rows.push([name, local ? "manual source" : "missing locally", e.installedWith ?? e.source ?? ""]);
+    continue;
+  }
+  const remoteText = await text(`https://raw.githubusercontent.com/${e.source}/main/${e.skillPath}`);
+  const remote = remoteText ? sha(remoteText.replace(/\r\n/g, "\n")) : null;
+  const commit = await latestCommit(e.source, e.skillPath);
+  let status, hint = commit ? `upstream ${commit}` : "";
+  if (!remote) status = "unreachable";
+  else if (!local) { status = "missing locally"; hint = `npx skills add ${e.source} -a claude-code -s ${name} -y --copy`; }
+  else if (remote === local) status = "up to date";
+  else if (remote === e.sha256) status = e.adapted ? "adapted (upstream unchanged)" : "LOCAL EDITS: mark adapted in the lock, or restore";
+  else if (e.adapted) { status = "UPSTREAM CHANGED (adapted: merge by hand)"; hint = `https://github.com/${e.source}/commits/main/${e.skillPath}`; }
+  else { status = "UPSTREAM CHANGED"; hint = `npx skills add ${e.source} -a claude-code -s ${name} -y --copy`; }
+  if (writeLock && remote) { e.sha256 = remote; delete e.sha256Note; if (commit) e.sourceCommit = commit; }
+  rows.push([name, status, hint]);
+}
+
+const w = [Math.max(...rows.map((r) => r[0].length)), Math.max(...rows.map((r) => r[1].length))];
+for (const [n, s, h] of rows) console.log(`${n.padEnd(w[0])}  ${s.padEnd(w[1])}  ${h}`);
+if (writeLock) { writeFileSync(LOCK, JSON.stringify(lock, null, 2) + "\n"); console.log(`\n${LOCK} updated`); }

package/skills-lock.json

@@ -0,0 +1,269 @@
+{
+  "version": 1,
+  "own": [
+    "orchestrate",
+    "brief",
+    "review",
+    "project-docs",
+    "arch-api",
+    "arch-web",
+    "arch-app",
+    "arch-db",
+    "triage"
+  ],
+  "skills": {
+    "animate": {
+      "source": "emilkowalski/skills",
+      "sourceType": "github",
+      "skillPath": "skills/animate/SKILL.md",
+      "computedHash": "7598d33e7f60dd5c24531eaaa897621cc3bdb48e8050324211627973bc59c4ce",
+      "sha256": "87889357e7bc8427a31ec45d6637ee945ce7227b7417358a2ffd5ae724631064",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`",
+      "adapted": true,
+      "adaptedNote": "frontmatter only: disable-model-invocation: true (preloaded by the agents that use it)"
+    },
+    "animate-expo": {
+      "source": "emilkowalski/skills",
+      "sourceType": "github",
+      "skillPath": "skills/animate-expo/SKILL.md",
+      "computedHash": "5de09593d564091f9db60aabede7bed760251e118548272050a247c653c417d2",
+      "sha256": "36086a5c9493a888076ff45593748b2940e76cdf6939fd60d623a2e3e57d0e1c",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`",
+      "adapted": true,
+      "adaptedNote": "frontmatter only: disable-model-invocation: true (preloaded by the agents that use it)"
+    },
+    "animation-performance": {
+      "source": "emilkowalski/skills",
+      "sourceType": "github",
+      "skillPath": "skills/animation-performance/SKILL.md",
+      "computedHash": "b68ba704106e27b1f83df0cb817e09ec947abb76825d86eabdee2954b6c1bb84",
+      "sha256": "c16c9ea0e2fb753e47cdb376b068f89b89ca1058a8330c545501dbd35e63fae7",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`",
+      "adapted": true,
+      "adaptedNote": "frontmatter only: disable-model-invocation: true (preloaded by the agents that use it)"
+    },
+    "apple-design": {
+      "source": "emilkowalski/skills",
+      "sourceType": "github",
+      "skillPath": "skills/apple-design/SKILL.md",
+      "computedHash": "0190417d092a0df447b000154e39733ea6d97efad6d3bec8a6ce3845aeb88914",
+      "sha256": "62dfdafaf5c56c67a96f7505c22fde7284e772fec9d564c1c7fc43b1fc40258e",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`",
+      "adapted": true,
+      "adaptedNote": "frontmatter only: disable-model-invocation: true (preloaded by the agents that use it)"
+    },
+    "break-ui": {
+      "source": "emilkowalski/skills",
+      "sourceType": "github",
+      "skillPath": "skills/break-ui/SKILL.md",
+      "computedHash": "60ada67662925f4df5e3c6ff41cac3ab241b66f8898100a5ffcd7ba7196cb868",
+      "sha256": "c5e2bdc98a0e261569219b942a54d207ad19d29e1417476ec4fedd4c3d658ee2",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`",
+      "adapted": true,
+      "adaptedNote": "frontmatter only: disable-model-invocation: true (preloaded by the agents that use it)"
+    },
+    "diagnosing-bugs": {
+      "source": "mattpocock/skills",
+      "sourceType": "github",
+      "sourceCommit": "49dd158",
+      "skillPath": "skills/engineering/diagnosing-bugs/SKILL.md",
+      "sha256": "849198df88cdb65fd0d97236604c1fca7ff2f22d2f705f9724a800d0266b118d"
+    },
+    "emil-design-eng": {
+      "source": "emilkowalski/skills",
+      "sourceType": "github",
+      "skillPath": "skills/emil-design-eng/SKILL.md",
+      "computedHash": "51f2537e04d15911b41d78e2de24c36a0e26d41beae15e82a954fe5496a5eda9",
+      "sha256": "b54101b99461deeae06a1782310b232519c025f2083e53652980f139880039fa",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`",
+      "adapted": true,
+      "adaptedNote": "frontmatter only: disable-model-invocation: true (preloaded by the agents that use it)"
+    },
+    "find-animation-opportunities": {
+      "source": "emilkowalski/skills",
+      "sourceType": "github",
+      "skillPath": "skills/find-animation-opportunities/SKILL.md",
+      "computedHash": "465d087c41768e4f14ed640dd049036009f613feb55baaa5831b68b33178f9d2",
+      "sha256": "fb7bdc5112e2a01aacbd3c89d372b5b50090746020a0e6d542affd80b3622cd5",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`",
+      "adapted": true,
+      "adaptedNote": "frontmatter only: disable-model-invocation: true (preloaded by the agents that use it)"
+    },
+    "graphify": {
+      "source": "graphifyy",
+      "sourceType": "pypi",
+      "installedWith": "pip install graphifyy",
+      "version": "0.9.92"
+    },
+    "grill-me": {
+      "source": "mattpocock/skills",
+      "sourceType": "github",
+      "sourceCommit": "49dd158",
+      "skillPath": "skills/productivity/grill-me/SKILL.md",
+      "sha256": "caaf8b8de1684f96e26b28f3c29189db5c89cce4b73e1c93d86164f66ef88637"
+    },
+    "grill-with-docs": {
+      "source": "mattpocock/skills",
+      "sourceType": "github",
+      "sourceCommit": "49dd158",
+      "skillPath": "skills/engineering/grill-with-docs/SKILL.md",
+      "note": "adapted: upstream calls grilling + domain-modeling; local version inlines glossary/ADR rules and adds docs/plans read-first, graphify and the decisions block for the orchestrator",
+      "adapted": true,
+      "sha256": "4a6d8bb82e01431ecee9a13b06ccfc4b911f6ee2efcf09bc6686a8e4cee58f72",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`"
+    },
+    "grilling": {
+      "source": "mattpocock/skills",
+      "sourceType": "github",
+      "sourceCommit": "49dd158",
+      "skillPath": "skills/productivity/grilling/SKILL.md",
+      "sha256": "befdff1e27a1dfe2a294d5871169ac1afe16d983911daa4f32627514a48c1e15"
+    },
+    "handoff": {
+      "source": "mattpocock/skills",
+      "sourceType": "github",
+      "sourceCommit": "49dd158",
+      "skillPath": "skills/productivity/handoff/SKILL.md",
+      "sha256": "<upstream; run scripts/skills-update.mjs --lock>",
+      "adapted": true,
+      "adaptedNote": "saves to .claude/handoffs/ inside the worktree instead of the OS temp dir (orchestrator-guard and durability); opens with worktree, branch, base ref, plan and frontier"
+    },
+    "impeccable": {
+      "source": "pbakaus/impeccable",
+      "sourceType": "github",
+      "installedWith": "npx impeccable install",
+      "version": "0.1.15 (scripts) / 4.6.0 (skill)",
+      "sha256": "9665ab04249cc7fe889ddf3a6dc92023de1edc5edd949e2710424b51febdf84a",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`",
+      "adapted": true,
+      "adaptedNote": "frontmatter only: disable-model-invocation: true (preloaded by the agents that use it)"
+    },
+    "improve-animations": {
+      "source": "emilkowalski/skills",
+      "sourceType": "github",
+      "skillPath": "skills/improve-animations/SKILL.md",
+      "computedHash": "524ea241e41d58bbdd8e288700fe24f5725e2a2f3ae7186ad7cebf9055058356",
+      "sha256": "52850830943147b1df7c02be596d8871b3540a7d9519f11157433940a6c6da79",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`",
+      "adapted": true,
+      "adaptedNote": "frontmatter only: disable-model-invocation: true (preloaded by the agents that use it)"
+    },
+    "mobile-native": {
+      "source": "emilkowalski/skills",
+      "sourceType": "github",
+      "skillPath": "skills/mobile-native/SKILL.md",
+      "computedHash": "f221cea36642168df6d3d6d7f236237cbf1ae669138ff7df07775674223d49ad",
+      "sha256": "888b7651d66d66dbac4e72b7c554638eb19bd971d686d6cbdf030a5ef3788f55",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`"
+    },
+    "pick-ui-library": {
+      "source": "emilkowalski/skills",
+      "sourceType": "github",
+      "skillPath": "skills/pick-ui-library/SKILL.md",
+      "computedHash": "5d2a77bf0ecafbda85aa95fb49999b6d77945d9066ec83d970b62e5b388cd686",
+      "sha256": "675fdce308683256ed617351a9b74d23457a5fbd0a562d9831b9c764b8c5e682",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`",
+      "adapted": true,
+      "adaptedNote": "frontmatter only: disable-model-invocation: true (preloaded by the agents that use it)"
+    },
+    "ponytail": {
+      "source": "DietrichGebert/ponytail",
+      "sourceType": "github",
+      "skillPath": "skills/ponytail/SKILL.md",
+      "computedHash": "061f887d9e3e735f85db3be3655a8936a00f24d5fb65ac4ab74a968a770fe342",
+      "sha256": "9badd22a32e19cb884e46dfa8d3aae82bb81dfa5484105b8b4f0262df823a509",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`"
+    },
+    "ponytail-audit": {
+      "source": "DietrichGebert/ponytail",
+      "sourceType": "github",
+      "skillPath": "skills/ponytail-audit/SKILL.md",
+      "computedHash": "1d718f893dabc01caad0dacef86444b5b4b3e1e59409527d66e8b5dd0cd85ae0",
+      "sha256": "2b3223a02c386d1263e1b08343cb8eb3a53e444cdafb1d79e26c8ec2a8fcad28",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`"
+    },
+    "ponytail-debt": {
+      "source": "DietrichGebert/ponytail",
+      "sourceType": "github",
+      "skillPath": "skills/ponytail-debt/SKILL.md",
+      "computedHash": "f5d1d2ab891ff0a650a90b67235e487828e7d2a189de08a1ae073032de379407",
+      "sha256": "b5ec2762f6ba8c4af9ea7173aa6c9f91b88655a25e43f9de0264f6ce8722b25f",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`"
+    },
+    "ponytail-review": {
+      "source": "DietrichGebert/ponytail",
+      "sourceType": "github",
+      "skillPath": "skills/ponytail-review/SKILL.md",
+      "computedHash": "800dc0c86402978e12359f701b9e0c81ba4607a0cd0027f4596d0f835a67eadc",
+      "sha256": "33fe4ebe22a460924e5d4a261e223df22e409cc94ab76182bee9fb91a3ef022e",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`"
+    },
+    "postgres-best-practices": {
+      "source": "neondatabase/postgres-skills",
+      "sourceType": "github",
+      "skillPath": "skills/postgres-best-practices/SKILL.md",
+      "computedHash": "f0e9670a035895d50945ca10ed4466513df2c486414c6fcebd3b4e38cc98a88c",
+      "sha256": "ade0096e963f1b7c3ec4c209318df50a8a891f3335c1dd05eca4b3f84d3e192f",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`"
+    },
+    "prototype": {
+      "source": "emilkowalski/skills",
+      "sourceType": "github",
+      "skillPath": "skills/prototype/SKILL.md",
+      "computedHash": "77be567d8c946608fdd15e61b62ab383cdf289a194dce2479828b7eda860d3ba",
+      "sha256": "bba39c955eb1871c5a02733976ceec5d0324198e0812e667604756489c89f7b9",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`",
+      "adapted": true,
+      "adaptedNote": "frontmatter only: disable-model-invocation: true (preloaded by the agents that use it)"
+    },
+    "retro": {
+      "source": "mattpocock/skills",
+      "sourceType": "github",
+      "sourceCommit": "49dd158",
+      "skillPath": "skills/engineering/retro/SKILL.md",
+      "sha256": "d39f65cfd1027788ac2ff9e9aa6caa555d9dd2e6e9d3eaea4c28cf493a45cdff",
+      "adapted": true,
+      "adaptedNote": "frontmatter only: disable-model-invocation removed so the orchestrator can call it after L tasks and verifier blocks"
+    },
+    "review-animations": {
+      "source": "emilkowalski/skills",
+      "sourceType": "github",
+      "skillPath": "skills/review-animations/SKILL.md",
+      "computedHash": "b4e5f0f4fe3e2743c85bf7354108f48a0b9d502cb20ef5c4a9c195da91f93736",
+      "sha256": "6ff590d29e436766135aa3d137be1fac2a867165c7257fc315b189361f1873af",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`",
+      "adapted": true,
+      "adaptedNote": "frontmatter only: disable-model-invocation: true (preloaded by the agents that use it)"
+    },
+    "tdd": {
+      "source": "mattpocock/skills",
+      "sourceType": "github",
+      "sourceCommit": "49dd158",
+      "skillPath": "skills/engineering/tdd/SKILL.md",
+      "sha256": "5505d25bbaa8fc14a79e4d20163936958992a2995b7f1dd1d6197edc9ed722e0"
+    },
+    "ui-ux-pro-max": {
+      "source": "nextlevelbuilder/ui-ux-pro-max-skill",
+      "sourceType": "github",
+      "skillPath": ".claude/skills/ui-ux-pro-max/SKILL.md",
+      "installedWith": "npx ui-ux-pro-max-cli init --ai claude",
+      "note": "skillPath is the repo's dev copy; the CLI generates the installed files from src/ui-ux-pro-max",
+      "sha256": "6c0b6c49351f88d579f95a55a37bcda7f00e8213c88b77490a97d9a31fa23498",
+      "sha256Note": "baseline taken from the local file on 2026-10-17; replaced by the upstream hash on the next `skills-update.mjs --lock`",
+      "adapted": true,
+      "adaptedNote": "frontmatter only: disable-model-invocation: true (preloaded by the agents that use it)"
+    },
+    "writing-for-agents": {
+      "source": "mattpocock/skills",
+      "sourceType": "github",
+      "sourceCommit": "49dd158",
+      "skillPath": "skills/productivity/writing-for-agents/SKILL.md",
+      "sha256": "551adca942227b44192edba88acd4e8db911f0121ce58ad16944ccf6a896a74a"
+    }
+  },
+  "notes": {
+    "sha256": "sha256 of the upstream SKILL.md at sourceCommit (or of the local file when sha256Note says so)",
+    "adapted": "local SKILL.md differs from upstream on purpose; skills-update.mjs never suggests overwriting it",
+    "computedHash": "hash written by skills.sh at install time; not reproducible here"
+  }
+}

package/templates/CLAUDE.project.md

@@ -0,0 +1,41 @@
+@AGENTS.md
+
+# <Project name>
+
+<One sentence: what this project is for the user.>
+
+## Commands
+
+- Install: `<pnpm install>`
+- Dev: `<pnpm dev>`
+- Lint / typecheck / test: `<pnpm lint>` / `<pnpm typecheck>` / `<pnpm test>`
+
+## Work size
+
+- Orchestrator writes only docs/plans, docs/adr and git integration. Everything else is delegated.
+- S: 1 file, diff fits in 1 sentence -> /quick (opus high, short brief). The orchestrator never edits code.
+- M: 1-2 scopes, paths known -> grill if a decision is open, /product plan with tickets, one implementer per ticket, /verifier.
+- L: 3+ scopes or architecture trigger -> grill, /product, /architect, tickets on the frontier, integrate, /architect again, /verifier, /security on trigger.
+- Full playbook: skill `orchestrate`.
+- Enforced by hook `orchestrator-guard` (main session has no `agent_id` in hook input).
+- Context: hook `context-budget` warns at 60k / 90k / 110k tokens; `autoCompactWindow` compacts at 120k. Phase-boundary tree in skill `orchestrate` section 14.
+
+## Where things live
+
+- Rules: `.claude/rules/` (loaded by `paths:` glob or always)
+- Agents: `.claude/agents/`
+- Skills: `.claude/skills/` (catalog and wiring: docs/skills.md)
+- Architecture skills: arch-api (NestJS), arch-web (Next.js), arch-app (Expo), arch-db (Postgres/MySQL; loaded by rule db.md)
+- Plans: `docs/plans/` (template in docs/plans/README.md)
+- ADRs: `docs/adr/` (template and numbering in docs/adr/README.md)
+- Brief template: skill `brief` (`docs/brief-template.md` points there)
+- Vendored skills: origins in `skills-lock.json`; check upstream with `node scripts/skills-update.mjs`
+- Decisions about this repo: `docs/adr/`; changes: `CHANGELOG.md`
+
+## graphify
+
+Skill `graphify` is installed (`.claude/skills/graphify`). Rule `.claude/rules/graphify.md` says when to query it; it applies only when `graphify-out/graph.json` exists. First build in a project: `/graphify .`
+
+# Compact instructions
+
+When compacting, keep: the task worktree path, branch and base ref; the plan path and every decision, ticket status and open question in it; files changed and commands run with their errors; the next step. Drop file contents, tool output and agent returns already reflected in `docs/plans/<task>.md`. The plan file is re-injected after compaction by the post-compact hook.