stackfit 0.0.0-stage → 0.1.1

package/src/refresh.mjs

@@ -0,0 +1,64 @@
+import { existsSync } from "node:fs";
+import { cp, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { loadJson, loadSources } from "./catalog.mjs";
+import { git } from "./sync.mjs";
+
+// GITHUB_TOKEN (shell or catalog .env) lets refresh read private repositories.
+// It is passed as a one-off HTTP header, never written into a URL, config, or log.
+function cloneArgs(repository) {
+  const token = process.env.GITHUB_TOKEN;
+  if (!token || !repository.startsWith("https://github.com/")) return [];
+  const basic = Buffer.from(`x-access-token:${token}`).toString("base64");
+  return ["-c", `http.https://github.com/.extraheader=AUTHORIZATION: basic ${basic}`];
+}
+
+export async function refreshSkills(catalog, options) {
+  const manifest = loadSources(catalog);
+  const selected = options.skill
+    ? [[options.skill, manifest.skills[options.skill]]]
+    : options.all
+      ? Object.entries(manifest.skills).filter(([, entry]) => entry.source)
+      : [];
+  if (!selected.length) throw new Error("Choose --skill <name> or --all; only skills with a recorded source can be refreshed");
+  for (const [name, entry] of selected) {
+    if (!entry) throw new Error(`Unknown skill '${name}' in skill-sources.json`);
+    if (!entry.source) throw new Error(`${name} has no recorded upstream source`);
+  }
+  if (options.dryRun) {
+    for (const [name, entry] of selected) console.log(`${name}: would refresh from ${entry.source.repository} ${entry.source.path}`);
+    return;
+  }
+
+  const tempRoot = await mkdtemp(resolve(tmpdir(), "stackfit-refresh-"));
+  const lock = loadJson(catalog.sourcesLockPath, { schemaVersion: 1, skills: {} });
+  const repositories = new Map();
+  try {
+    for (const [name, entry] of selected) {
+      let checkout = repositories.get(entry.source.repository);
+      if (!checkout) {
+        checkout = resolve(tempRoot, `source-${repositories.size}`);
+        const clone = git([...cloneArgs(entry.source.repository), "clone", "--quiet", "--depth", "1", entry.source.repository, checkout], catalog.root, "inherit");
+        if (clone.status !== 0) throw new Error(`Could not clone ${entry.source.repository}`);
+        repositories.set(entry.source.repository, checkout);
+      }
+      const source = resolve(checkout, entry.source.path);
+      if (!existsSync(resolve(source, "SKILL.md"))) throw new Error(`${name}: upstream path ${entry.source.path} has no SKILL.md`);
+      const staging = resolve(catalog.skills, `.${name}.refresh`);
+      const destination = resolve(catalog.skills, name);
+      await rm(staging, { recursive: true, force: true });
+      await cp(source, staging, { recursive: true });
+      await rm(destination, { recursive: true, force: true });
+      await rename(staging, destination);
+      const revision = git(["rev-parse", "HEAD"], checkout).stdout.trim();
+      lock.skills[name] = { repository: entry.source.repository, path: entry.source.path, revision, refreshedAt: new Date().toISOString() };
+      console.log(`${name}: refreshed at ${revision.slice(0, 12)}`);
+    }
+    lock.skills = Object.fromEntries(Object.entries(lock.skills).sort(([a], [b]) => a.localeCompare(b)));
+    await writeFile(catalog.sourcesLockPath, `${JSON.stringify(lock, null, 2)}\n`);
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+  console.log("Review with `git diff`, run `stackfit audit`, then commit the catalog.");
+}

package/src/render.mjs

@@ -0,0 +1,93 @@
+// Text transforms between the catalog format and each agent's expected files.
+
+// Minimal YAML frontmatter editing for top-level scalar keys; enough for upstream overrides.
+export function setFrontmatter(content, fields) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  const lines = match ? match[1].split(/\r?\n/) : [];
+  const body = match ? content.slice(match[0].length) : content;
+  const isKey = (line) => /^[A-Za-z][\w-]*:/.test(line);
+  for (const [key, value] of Object.entries(fields)) {
+    const start = lines.findIndex((line) => line.startsWith(`${key}:`));
+    let end = start + 1;
+    if (start !== -1) while (end < lines.length && !isKey(lines[end])) end += 1;
+    const rendered = value === null ? [] : [`${key}: ${typeof value === "string" ? JSON.stringify(value) : value}`];
+    if (start === -1) lines.push(...rendered);
+    else lines.splice(start, end - start, ...rendered);
+  }
+  return `---\n${lines.join("\n")}\n---\n${body}`;
+}
+
+// Reads top-level keys, joining folded/literal block scalars (`description: >-`).
+export function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) return { fields: {}, body: content };
+  const fields = {};
+  let current = null;
+  for (const line of match[1].split(/\r?\n/)) {
+    const field = line.match(/^([A-Za-z][\w-]*):\s*(.*)$/);
+    if (field) {
+      current = field[1];
+      fields[current] = field[2].trim().replace(/^['"]|['"]$/g, "");
+    } else if (current && /^\s+\S/.test(line)) {
+      fields[current] = `${fields[current].replace(/^[>|]-?$/, "")} ${line.trim()}`.trim();
+    }
+  }
+  return { fields, body: content.slice(match[0].length).replace(/^\r?\n/, "") };
+}
+
+// Split a Cursor `globs` value on commas that are not inside `{...}`.
+export function splitGlobs(value) {
+  const globs = [];
+  let depth = 0;
+  let current = "";
+  for (const char of value) {
+    if (char === "{") depth += 1;
+    if (char === "}") depth -= 1;
+    if (char === "," && depth === 0) {
+      globs.push(current);
+      current = "";
+    } else current += char;
+  }
+  globs.push(current);
+  return globs.map((glob) => glob.trim().replace(/^['"]|['"]$/g, "")).filter(Boolean);
+}
+
+// Cursor .mdc → Claude Code .claude/rules/*.md. Always-apply rules load every session;
+// glob rules become `paths:`; description-only rules stay routed through AGENTS.md.
+export function claudeRule(content) {
+  const { fields, body } = parseFrontmatter(content);
+  if (fields.alwaysApply === "true") return body;
+  if (fields.globs) {
+    const paths = splitGlobs(fields.globs).map((glob) => `  - ${JSON.stringify(glob)}`).join("\n");
+    return `---\npaths:\n${paths}\n---\n\n${body}`;
+  }
+  return null;
+}
+
+export function cursorRule(content, name) {
+  if (content.startsWith("---\n")) return content;
+  return `---\ndescription: Repository-specific ${name} guidance; read when relevant\nalwaysApply: false\n---\n\n${content}`;
+}
+
+// Claude Code treats commands as skills; keep side-effecting workflows manual-only.
+export function claudeCommand(content) {
+  if (/^---\r?\n/.test(content)) return content;
+  const summary = content.split(/\r?\n/).map((line) => line.trim()).find((line) => line && !line.startsWith("#")) ?? "";
+  return `---\ndescription: ${JSON.stringify(summary.slice(0, 200))}\ndisable-model-invocation: true\n---\n\n${content}`;
+}
+
+export function claudeAgent(content) {
+  return content.replace(/^model:\s*.+$/m, "model: inherit").replace(/^readonly:\s*true$/m, "permissionMode: plan");
+}
+
+// Effective skill metadata = SKILL.md frontmatter + render overrides from skill-sources.json.
+export function effectiveMetadata(skillContent, overrides = {}) {
+  const { fields } = parseFrontmatter(skillContent);
+  return { ...fields, ...Object.fromEntries(Object.entries(overrides).map(([key, value]) => [key, String(value)])) };
+}
+
+// Characters of a skill that sit in every session: its name + description, unless manual-only.
+export function listingCost(metadata, name) {
+  if (!metadata || metadata["disable-model-invocation"] === "true") return 0;
+  return (metadata.description?.length ?? 0) + name.length;
+}

package/src/report.mjs

@@ -0,0 +1,111 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, resolve } from "node:path";
+import { loadSources } from "./catalog.mjs";
+import { effectiveMetadata, listingCost, parseFrontmatter } from "./render.mjs";
+import { createPlan } from "./sync.mjs";
+
+// Rough rule of thumb for English prose in current tokenizers.
+export const charsToTokens = (chars) => Math.round(chars / 4);
+
+// Folders whose skills load in every repo regardless of stackfit.
+export const GLOBAL_SKILL_DIRS = [".claude/skills", ".agents/skills", ".cursor/skills", ".codex/skills"];
+
+export function skillCosts(catalog, registry) {
+  const sources = loadSources(catalog).skills;
+  const costs = new Map();
+  for (const name of registry.skills) {
+    const path = resolve(catalog.skills, name, "SKILL.md");
+    const metadata = existsSync(path) ? effectiveMetadata(readFileSync(path, "utf8"), sources[name]?.render?.frontmatter) : null;
+    costs.set(name, listingCost(metadata, name));
+  }
+  return costs;
+}
+
+export function globalSkills(home = homedir()) {
+  const folders = [];
+  for (const relativeDir of GLOBAL_SKILL_DIRS) {
+    const directory = resolve(home, relativeDir);
+    let names;
+    try {
+      names = readdirSync(directory);
+    } catch {
+      continue;
+    }
+    let count = 0;
+    let chars = 0;
+    for (const name of names) {
+      const skillFile = resolve(directory, name, "SKILL.md");
+      try {
+        if (!statSync(skillFile).isFile()) continue;
+      } catch {
+        continue;
+      }
+      count += 1;
+      chars += listingCost(effectiveMetadata(readFileSync(skillFile, "utf8")), name);
+    }
+    if (count) folders.push({ path: `~/${relativeDir}`, skills: count, tokens: charsToTokens(chars) });
+  }
+  return { folders, tokens: folders.reduce((total, folder) => total + folder.tokens, 0) };
+}
+
+// Uses the same plan as `sync`, so the numbers describe exactly what would be written:
+// catalog and repo-owned skills, overrides applied, and always-on Claude rules.
+export async function projectReport(catalog, registry, project, costs) {
+  const plan = await createPlan(catalog, project.path, registry, { scaffold: project.scaffold, selection: project.selection });
+  let listingChars = 0;
+  let ruleChars = 0;
+  let skills = 0;
+  for (const [destination, item] of plan.plan) {
+    const key = destination.slice(project.path.length + 1).replaceAll("\\", "/");
+    const content = item.content.toString("utf8");
+    const skill = key.match(/^\.agents\/skills\/([^/]+)\/SKILL\.md$/);
+    if (skill) {
+      skills += 1;
+      listingChars += listingCost(parseFrontmatter(content).fields, skill[1]);
+    } else if (/^\.claude\/rules\/.+\.md$/.test(key) && !parseFrontmatter(content).fields.paths && !/^---\r?\npaths:/.test(content)) {
+      ruleChars += content.length;
+    }
+  }
+  const everything = [...costs.values()].reduce((total, cost) => total + cost, 0);
+  const listingTokens = charsToTokens(listingChars);
+  const ruleTokens = charsToTokens(ruleChars);
+  const tokensIfEverything = charsToTokens(everything) + ruleTokens;
+  const tokens = listingTokens + ruleTokens;
+  return {
+    project: basename(project.path),
+    packs: plan.packs,
+    skills,
+    catalogSkills: registry.skills.length,
+    listingTokens,
+    ruleTokens,
+    tokens,
+    tokensIfEverything,
+    saved: tokensIfEverything ? Math.round((1 - tokens / tokensIfEverything) * 100) : 0,
+  };
+}
+
+const formatTokens = (tokens) => (tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}k` : String(tokens));
+const tok = (tokens) => `~${formatTokens(tokens)} tok`;
+
+export function printReport({ projects: rows, global }) {
+  const width = Math.max(7, ...rows.map((row) => row.project.length));
+  console.log(`${"project".padEnd(width)}  skills  skill listings     rules  per session  packs`);
+  for (const row of rows) {
+    console.log(
+      `${row.project.padEnd(width)}  ${String(row.skills).padStart(6)}  ${tok(row.listingTokens).padStart(14)}  ${tok(row.ruleTokens).padStart(8)}  `
+      + `${tok(row.tokens).padStart(11)}  ${row.packs.join(", ")}`,
+    );
+  }
+  const total = rows.reduce((sum, row) => sum + row.tokens, 0);
+  const everything = rows.reduce((sum, row) => sum + row.tokensIfEverything, 0);
+  console.log(`\nWith stackfit: ~${formatTokens(total)} tokens across ${rows.length} project(s). Every catalog skill in every repo would be ~${formatTokens(everything)}.`);
+  if (global.tokens) {
+    const where = global.folders.map((folder) => `${folder.path} (${folder.skills})`).join(", ");
+    console.log(`Global skills add ~${formatTokens(global.tokens)} tokens to every session in every repo, with or without stackfit: ${where}.`);
+    console.log("Skills that also live in the catalog can be removed from those folders once their packs cover the repos that need them.");
+  } else {
+    console.log("No global skill folders found (~/.claude/skills, ~/.agents/skills, ~/.cursor/skills, ~/.codex/skills).");
+  }
+  console.log("Estimates: skill names + descriptions and always-on rules, about 4 characters per token. Skill bodies load only when used; manual-only skills cost 0.");
+}

package/src/scaffold.mjs

@@ -0,0 +1,88 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, readdir, writeFile } from "node:fs/promises";
+import { basename, dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { expandHome } from "./catalog.mjs";
+
+const STARTER_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../starter");
+
+async function writeMissing(root, files, { dryRun }) {
+  const created = [];
+  for (const [key, content] of Object.entries(files)) {
+    const destination = resolve(root, key);
+    if (existsSync(destination)) continue;
+    created.push(key);
+    if (dryRun) continue;
+    await mkdir(dirname(destination), { recursive: true });
+    await writeFile(destination, content);
+  }
+  return created;
+}
+
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+
+// Tracked per-project context. Never overwrites.
+export async function initProject(projectPath, options) {
+  if (options.scaffold === false) {
+    console.log(`${basename(projectPath)}: skipped scaffold (adapter-only project)`);
+    return 0;
+  }
+  const created = await writeMissing(projectPath, {
+    "AGENTS.md": "# Repository agent instructions\n\nRead `docs/agent/index.md` first, then load only the pages and repo-owned components relevant to the task. Repository instructions take precedence over shared defaults when they conflict.\n",
+    "CLAUDE.md": "@AGENTS.md\n",
+    "docs/agent/config.json": json({ schemaVersion: 1, packs: [], excludePacks: [], skills: [], overrides: { skills: [], agents: [], commands: [], rules: [] } }),
+    "docs/agent/index.md": "# Agent context\n\nRead only the page relevant to the task:\n\n- `architecture.md`: structure, boundaries, and generated code\n- `design-system.md`: UI primitives, tokens, and visual conventions\n- `workflows.md`: package manager, checks, Git, PR, and release policy\n- `rules/*.md`: additional repository constraints, when relevant\n\nRepository-owned components live under `docs/agent/` (`skills/<name>/SKILL.md`, `commands/*.md`, `agents/*.md`, `rules/*.md`). Run `stackfit sync` to render them for each agent.\n",
+    "docs/agent/architecture.md": "# Architecture\n\nDocument stable repository boundaries and where new code belongs. Link existing detailed docs instead of duplicating them.\n",
+    "docs/agent/design-system.md": "# Design system\n\nDocument the canonical UI primitives, tokens, typography, and accessibility conventions. Remove this page for repositories without a UI.\n",
+    "docs/agent/workflows.md": "# Workflows\n\nDocument the package manager, validation commands, generated files, branch/PR policy, and release automation.\n",
+  }, options);
+  console.log(`${basename(projectPath)}: ${created.length ? `${created.length} tracked docs file(s)` : "already initialized"}`);
+  if (!options.quiet) for (const key of created) console.log(`  create ${key}`);
+  return created.length;
+}
+
+async function listFiles(root) {
+  const files = [];
+  async function walk(directory) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const path = resolve(directory, entry.name);
+      if (entry.isDirectory()) await walk(path);
+      else files.push(path);
+    }
+  }
+  await walk(root);
+  return files;
+}
+
+// A catalog is a plain folder you keep in your own (usually private) Git repository.
+export async function initCatalog(target, options) {
+  const root = expandHome(target ?? "~/.stackfit");
+  const created = [];
+  if (options.starter) {
+    for (const source of await listFiles(STARTER_ROOT)) {
+      const key = relative(STARTER_ROOT, source);
+      const destination = resolve(root, key === "gitignore" ? ".gitignore" : key);
+      if (existsSync(destination)) continue;
+      created.push(relative(root, destination));
+      if (options.dryRun) continue;
+      await mkdir(dirname(destination), { recursive: true });
+      await cp(source, destination);
+    }
+  } else {
+    created.push(...await writeMissing(root, {
+      "stackfit.json": json({ $schema: "https://unpkg.com/stackfit/schemas/stackfit.schema.json", schemaVersion: 3, skills: [], packs: { core: { description: "Every repository.", always: true, skills: [] } }, adapters: { agents: [], commands: [], rules: [] } }),
+      "skill-sources.json": json({ schemaVersion: 2, skills: {} }),
+      "stackfit.local.example.json": json({ schemaVersion: 1, machines: [{ id: "laptop", match: { platform: "darwin" }, roots: ["~/code"] }] }),
+      ".env.example": "# Copy to .env (gitignored). Values here fill {{env:NAME}} placeholders in commands, rules, and agents.\n# STACKFIT_CATALOG=~/path/to/this/catalog\n# GITHUB_TOKEN=\n",
+      ".gitignore": "stackfit.local.json\n.env\nskills/.*.refresh/\n.DS_Store\n",
+      "skills/.gitkeep": "",
+    }, options));
+  }
+  console.log(`${options.dryRun ? "Would create" : "Created"} catalog at ${root} (${created.length} file(s)).`);
+  if (!options.quiet) for (const key of created) console.log(`  create ${key}`);
+  console.log(options.starter
+    ? "\nNext:\n  stackfit refresh --all      # vendor the starter's upstream skills\n  stackfit audit\n  stackfit report --root ~/code   # what each repo would load\n  stackfit status --root ~/code   # dry run\n  stackfit sync --root ~/code"
+    : "\nNext: add skills under skills/<name>/SKILL.md, list them in stackfit.json and a pack, record them in skill-sources.json, then:\n  stackfit audit\n  stackfit report --root ~/code\n  stackfit status --root ~/code   # dry run\n  stackfit sync --root ~/code");
+  if (!root.endsWith(".stackfit")) console.log(`\nPoint stackfit at it with --catalog ${target}, STACKFIT_CATALOG, or run commands from inside the folder.`);
+  return created.length;
+}

package/src/sync.mjs

@@ -0,0 +1,300 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, readlinkSync } from "node:fs";
+import { mkdir, readFile, readdir, rm, symlink, writeFile } from "node:fs/promises";
+import { platform } from "node:os";
+import { basename, dirname, relative, resolve, sep } from "node:path";
+import { spawnSync } from "node:child_process";
+import { expandEnv, loadJson, loadSources } from "./catalog.mjs";
+import { resolveSelection } from "./detect.mjs";
+import { claudeAgent, claudeCommand, claudeRule, cursorRule, setFrontmatter } from "./render.mjs";
+
+export const LOCK_NAME = ".stackfit.lock.json";
+// Older names of the lock, from before the tool was called stackfit; read once, then replaced.
+const LEGACY_LOCK_NAMES = [".skillfit.lock.json", ".agent-config.lock.json"];
+const LOCAL_SCAFFOLD_EXCLUDES = ["/CLAUDE.md", "/docs/agent/"];
+const EXCLUDE_BEGIN = "# >>> stackfit: generated files (managed, do not edit)";
+const EXCLUDE_END = "# <<< stackfit";
+// Lines written by older versions, which excluded whole .claude/ and .cursor/ folders.
+const LEGACY_HEADER = /^# Managed locally by (agent-config|skillfit|stackfit)$/;
+const LEGACY_LINES = new Set([".agent-config.lock.json", ".skillfit.lock.json", ".stackfit.lock.json", ".agents/", ".cursor/", ".claude/", "CLAUDE.md", "docs/agent/"]);
+
+export function lstatMaybe(path) {
+  try {
+    return lstatSync(path);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+const sha256 = (content) => createHash("sha256").update(content).digest("hex");
+export const toPosixPath = (path) => path.replaceAll("\\", "/");
+const projectKey = (projectPath, destination) => toPosixPath(relative(projectPath, destination));
+const normalizeEntries = (entries = {}) => Object.fromEntries(Object.entries(entries).map(([key, value]) => [toPosixPath(key), value]));
+
+function loadLock(projectPath) {
+  const found = [LOCK_NAME, ...LEGACY_LOCK_NAMES].map((name) => resolve(projectPath, name)).find((path) => existsSync(path));
+  const previous = loadJson(found, { files: {}, links: {} }) ?? { files: {}, links: {} };
+  return { ...previous, files: normalizeEntries(previous.files), links: normalizeEntries(previous.links) };
+}
+
+export function git(args, cwd, stdio = "pipe") {
+  return spawnSync("git", args, { cwd, encoding: "utf8", stdio });
+}
+
+function currentRevision(cwd) {
+  const result = git(["rev-parse", "HEAD"], cwd);
+  return result.status === 0 ? result.stdout.trim() : "unknown";
+}
+
+async function walkFiles(root) {
+  if (!existsSync(root)) return [];
+  const files = [];
+  async function walk(directory) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const path = resolve(directory, entry.name);
+      if (entry.isDirectory()) await walk(path);
+      else if (entry.isFile()) files.push(path);
+    }
+  }
+  await walk(root);
+  return files.sort();
+}
+
+function addFile(plan, source, destination, transform = undefined) {
+  if (!existsSync(source)) throw new Error(`Configured source does not exist: ${source}`);
+  const raw = readFileSync(source);
+  const content = transform ? Buffer.from(transform(raw.toString("utf8"))) : raw;
+  plan.set(destination, { source, content, hash: sha256(content) });
+}
+
+async function addTree(plan, sourceRoot, destinationRoot, render = {}) {
+  const exclude = new Set(render.exclude ?? []);
+  for (const source of await walkFiles(sourceRoot)) {
+    const file = toPosixPath(relative(sourceRoot, source));
+    if (exclude.has(file) || basename(file) === ".DS_Store") continue;
+    const transform = file === "SKILL.md" && render.frontmatter ? (content) => setFrontmatter(content, render.frontmatter) : undefined;
+    addFile(plan, source, resolve(destinationRoot, file), transform);
+  }
+}
+
+const componentName = (file) => file.replace(/\.(md|mdc)$/, "");
+
+function assertLocalComponentAllowed(projectName, projectConfig, kind, name, sharedNames) {
+  if (!sharedNames.has(name)) return;
+  if (new Set(projectConfig.overrides?.[kind] ?? []).has(name)) return;
+  throw new Error(
+    `${projectName}: repo-owned ${kind.slice(0, -1)} '${name}' conflicts with shared ${kind}; `
+    + `rename it or add '${name}' to overrides.${kind} in docs/agent/config.json`,
+  );
+}
+
+function addCommand(plan, projectPath, source, file) {
+  const fill = (content) => expandEnv(content, `commands/${file}`);
+  addFile(plan, source, resolve(projectPath, ".cursor/commands", file), fill);
+  addFile(plan, source, resolve(projectPath, ".claude/commands", file), (content) => claudeCommand(fill(content)));
+}
+
+function addRule(plan, projectPath, source, name, cursorTransform = (content) => content) {
+  const cursorContent = expandEnv(cursorTransform(readFileSync(source, "utf8")), `rules/${name}`);
+  addFile(plan, source, resolve(projectPath, ".cursor/rules", `${name}.mdc`), () => cursorContent);
+  const claudeContent = claudeRule(cursorContent);
+  if (claudeContent !== null) addFile(plan, source, resolve(projectPath, ".claude/rules", `${name}.md`), () => claudeContent);
+}
+
+function addAgent(plan, projectPath, source, file) {
+  const fill = (content) => expandEnv(content, `agents/${file}`);
+  addFile(plan, source, resolve(projectPath, ".cursor/agents", file), fill);
+  addFile(plan, source, resolve(projectPath, ".claude/agents", file), (content) => claudeAgent(fill(content)));
+}
+
+export function loadProjectConfig(projectPath, registry, scaffold) {
+  const configPath = resolve(projectPath, registry.projectConfigPath);
+  const projectConfig = scaffold ? loadJson(configPath, { schemaVersion: 1 }) : { schemaVersion: 1 };
+  if (projectConfig.schemaVersion !== 1) throw new Error(`${basename(projectPath)}: unsupported ${registry.projectConfigPath} schema`);
+  return { projectConfig, configPath };
+}
+
+export async function createPlan(catalog, projectPath, registry, { scaffold = true, selection: localSelection = {} } = {}) {
+  const projectName = basename(projectPath);
+  const { projectConfig, configPath } = loadProjectConfig(projectPath, registry, scaffold);
+  const selection = resolveSelection(projectPath, registry, projectConfig, localSelection);
+  const renderOptions = loadSources(catalog).skills;
+  const sharedSkills = new Set(selection.skills);
+  const sharedAgents = new Set(registry.adapters.agents.map(componentName));
+  const sharedCommands = new Set(registry.adapters.commands.map(componentName));
+  const sharedRules = new Set(registry.adapters.rules.map(componentName));
+  const plan = new Map();
+  const links = new Map([
+    [resolve(projectPath, ".claude/skills"), "../.agents/skills"],
+    [resolve(projectPath, ".cursor/skills"), "../.agents/skills"],
+  ]);
+
+  for (const skill of selection.skills) {
+    const source = resolve(catalog.skills, skill);
+    if (!existsSync(resolve(source, "SKILL.md"))) {
+      throw new Error(`Skill '${skill}' is enabled but not in the catalog. Run \`stackfit refresh --skill ${skill}\` or add skills/${skill}/SKILL.md.`);
+    }
+    await addTree(plan, source, resolve(projectPath, ".agents/skills", skill), renderOptions[skill]?.render);
+  }
+  for (const file of registry.adapters.agents) addAgent(plan, projectPath, resolve(catalog.agents, file), file);
+  for (const file of registry.adapters.commands) addCommand(plan, projectPath, resolve(catalog.commands, file), file);
+  for (const file of registry.adapters.rules) addRule(plan, projectPath, resolve(catalog.rules, file), componentName(file));
+
+  if (scaffold) {
+    const localSkills = resolve(projectPath, "docs/agent/skills");
+    if (existsSync(localSkills)) {
+      for (const entry of await readdir(localSkills, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        const source = resolve(localSkills, entry.name);
+        if (!existsSync(resolve(source, "SKILL.md"))) throw new Error(`${projectName}: docs/agent/skills/${entry.name} lacks SKILL.md`);
+        assertLocalComponentAllowed(projectName, projectConfig, "skills", entry.name, sharedSkills);
+        await addTree(plan, source, resolve(projectPath, ".agents/skills", entry.name));
+      }
+    }
+    const localKinds = [
+      ["agents", "docs/agent/agents", sharedAgents, (source, file) => addAgent(plan, projectPath, source, file)],
+      ["commands", "docs/agent/commands", sharedCommands, (source, file) => addCommand(plan, projectPath, source, file)],
+      ["rules", "docs/agent/rules", sharedRules, (source, file) => {
+        const name = componentName(file);
+        addRule(plan, projectPath, source, name, (content) => cursorRule(content, name));
+      }],
+    ];
+    for (const [kind, folder, shared, add] of localKinds) {
+      const root = resolve(projectPath, folder);
+      for (const source of await walkFiles(root)) {
+        if (!source.endsWith(".md")) continue;
+        const file = relative(root, source);
+        assertLocalComponentAllowed(projectName, projectConfig, kind, componentName(file), shared);
+        add(source, file);
+      }
+    }
+  }
+
+  return { plan, links, projectName, scaffold, packs: selection.packs, skills: selection.skills, configPath: scaffold ? relative(projectPath, configPath) : null };
+}
+
+// Git-exclude exactly what stackfit generates, so a user's own files in .claude/ or .cursor/
+// (settings.json, personal commands) stay visible to git.
+async function ensureLocalGitExclude(projectPath, generatedKeys, { scaffold = true } = {}) {
+  const gitPath = git(["rev-parse", "--git-path", "info/exclude"], projectPath);
+  const excludePath = gitPath.status === 0 ? resolve(projectPath, gitPath.stdout.trim()) : resolve(projectPath, ".git/info/exclude");
+  const existing = existsSync(excludePath) ? await readFile(excludePath, "utf8") : "";
+  const kept = [];
+  let inBlock = false;
+  let inLegacy = false;
+  for (const line of existing.split(/\r?\n/)) {
+    if (line === EXCLUDE_BEGIN) { inBlock = true; continue; }
+    if (inBlock) { if (line === EXCLUDE_END) inBlock = false; continue; }
+    if (LEGACY_HEADER.test(line)) { inLegacy = true; continue; }
+    if (inLegacy && LEGACY_LINES.has(line)) continue;
+    inLegacy = false;
+    kept.push(line);
+  }
+  while (kept.length && kept[kept.length - 1] === "") kept.pop();
+  const entries = [
+    `/${LOCK_NAME}`,
+    "/.agents/",
+    ...generatedKeys.filter((key) => !key.startsWith(".agents/")).map((key) => `/${key}`).sort(),
+    ...(scaffold ? [] : LOCAL_SCAFFOLD_EXCLUDES),
+  ];
+  const next = `${kept.length ? `${kept.join("\n")}\n` : ""}${EXCLUDE_BEGIN}\n${[...new Set(entries)].join("\n")}\n${EXCLUDE_END}\n`;
+  if (next === existing) return;
+  await mkdir(dirname(excludePath), { recursive: true });
+  await writeFile(excludePath, next);
+}
+
+// After removing a dropped skill's files, remove its now-empty folders (never the project root).
+async function pruneEmptyParents(projectPath, directory) {
+  let current = directory;
+  while (current.startsWith(`${projectPath}${sep}`) && !lstatMaybe(current)?.isSymbolicLink()) {
+    let entries;
+    try {
+      entries = await readdir(current);
+    } catch {
+      return;
+    }
+    if (entries.length) return;
+    await rm(current, { recursive: true, force: true });
+    current = dirname(current);
+  }
+}
+
+// Windows junctions need no admin rights or developer mode; they store absolute targets.
+const LINK_TYPE = platform() === "win32" ? "junction" : "dir";
+const sameLinkTarget = (linkPath, target) => resolve(dirname(linkPath), readlinkSync(linkPath)) === resolve(dirname(linkPath), target);
+
+export async function applyPlan(catalog, projectPath, planData, options) {
+  const previous = loadLock(projectPath);
+  const nextFiles = {};
+  const nextLinks = {};
+  const actions = [];
+  // Managed symlinks this plan no longer wants. Files "found" through them are not
+  // real collisions: the link is deleted before writes.
+  const retiredLinks = Object.keys(previous.links ?? {})
+    .map((key) => resolve(projectPath, key))
+    .filter((linkPath) => !planData.links.has(linkPath) && lstatMaybe(linkPath)?.isSymbolicLink());
+  const throughRetiredLink = (destination) => retiredLinks.some((linkPath) => destination.startsWith(`${linkPath}${sep}`));
+
+  for (const [destination, item] of planData.plan) {
+    const key = projectKey(projectPath, destination);
+    nextFiles[key] = item.hash;
+    const existing = existsSync(destination) && !throughRetiredLink(destination) ? await readFile(destination) : null;
+    if (existing && sha256(existing) === item.hash) continue;
+    if (existing && !previous.files[key] && !options.force) {
+      throw new Error(`${planData.projectName}: unmanaged collision at ${key}; review it, then rerun with --force`);
+    }
+    actions.push({ type: existing ? "update" : "create", key, destination, item });
+  }
+  for (const key of Object.keys(previous.files)) {
+    if (nextFiles[key]) continue;
+    const destination = resolve(projectPath, key);
+    const underLink = [...planData.links.keys()].find((linkPath) => destination.startsWith(`${linkPath}${sep}`) && lstatMaybe(linkPath)?.isSymbolicLink());
+    if (!underLink && lstatMaybe(destination)) actions.push({ type: "delete", key, destination });
+  }
+  for (const [destination, target] of planData.links) {
+    const key = projectKey(projectPath, destination);
+    nextLinks[key] = target;
+    const stat = lstatMaybe(destination);
+    if (stat?.isSymbolicLink() && sameLinkTarget(destination, target)) continue;
+    if (stat?.isDirectory()) {
+      const unmanaged = (await walkFiles(destination)).map((path) => projectKey(projectPath, path)).filter((path) => !previous.files[path]);
+      if (unmanaged.length && !options.force) throw new Error(`${planData.projectName}: unmanaged collision under ${key}: ${unmanaged[0]}`);
+    } else if (stat && !previous.links?.[key] && !options.force) {
+      throw new Error(`${planData.projectName}: unmanaged collision at ${key}; review it, then rerun with --force`);
+    }
+    actions.push({ type: stat ? "link" : "create-link", key, destination, target });
+  }
+  for (const key of Object.keys(previous.links ?? {})) {
+    if (!nextLinks[key] && lstatMaybe(resolve(projectPath, key))) actions.push({ type: "delete", key, destination: resolve(projectPath, key) });
+  }
+
+  if (!options.dryRun) {
+    await ensureLocalGitExclude(projectPath, [...Object.keys(nextFiles), ...Object.keys(nextLinks)], { scaffold: planData.scaffold !== false });
+    for (const action of actions.filter((item) => item.type === "delete")) {
+      await rm(action.destination, { recursive: true, force: true });
+      await pruneEmptyParents(projectPath, dirname(action.destination));
+    }
+    for (const action of actions.filter((item) => ["create", "update"].includes(item.type))) {
+      await mkdir(dirname(action.destination), { recursive: true });
+      await writeFile(action.destination, action.item.content);
+    }
+    for (const action of actions.filter((item) => ["link", "create-link"].includes(item.type))) {
+      await rm(action.destination, { recursive: true, force: true });
+      await mkdir(dirname(action.destination), { recursive: true });
+      await symlink(action.target, action.destination, LINK_TYPE);
+    }
+    await writeFile(resolve(projectPath, LOCK_NAME), `${JSON.stringify({
+      schemaVersion: 3,
+      sourceRevision: currentRevision(catalog.root),
+      projectConfig: planData.configPath,
+      scaffold: planData.scaffold !== false,
+      packs: planData.packs,
+      generatedAt: new Date().toISOString(),
+      files: nextFiles,
+      links: nextLinks,
+    }, null, 2)}\n`);
+    for (const name of LEGACY_LOCK_NAMES) await rm(resolve(projectPath, name), { force: true });
+  }
+  return actions;
+}