@mayurdluffy/ccwf 0.0.0-stage → 0.1.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# @mayurdluffy/ccwf
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@mayurdluffy/ccwf?logo=npm)](https://www.npmjs.com/package/@mayurdluffy/ccwf)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://img.shields.io/github/actions/workflow/status/mayurdluffy/ccwf/ci.yml?branch=main&label=CI&logo=github)](https://github.com/mayurdluffy/ccwf/actions/workflows/ci.yml)
+[![Publish](https://img.shields.io/github/actions/workflow/status/mayurdluffy/ccwf/publish.yml?label=Publish%20to%20npm&logo=github)](https://github.com/mayurdluffy/ccwf/actions/workflows/publish.yml)
+
+One command that sets up the same agent system on any computer and in any repo, for **Claude Code, Codex and Cursor** (only those three; macOS and Linux).
+
+```bash
+cd your-repo
+npx @mayurdluffy/cbm-cli install --agents claude,codex,cursor  # code-graph MCP first (see docs/agents/setup.md after init)
+npx @mayurdluffy/ccwf init  # tools + user-level skills + project files
+```
+
+`init` shows what is missing on your machine, installs it after one confirmation, then writes the project files. `--yes` skips the question: it runs vendor install scripts from the network and installs skills from the current head of third-party repos. Re-running is safe: your own text and config keys are kept. `--force` overwrites only files ccwf owns, never seeded docs.
+
+## What you get
+
+**On the machine (once):** the pinned user-level skills (`mattpocock/skills`, `find-skills`), `agent-browser`, `herdr` + `hc`, `gh`, `ffmpeg`, the Claude / Codex / Cursor CLIs you pick, and Codex trust for the repo. Chrome and logins are checked and explained, not installed.
+
+**In the repo (committed):**
+
+| Module | Writes |
+|---|---|
+| `core` (always) | discipline rules in `AGENTS.md` (`CLAUDE.md` imports it), `commit` skill, Cursor rule, `docs/agents/workflow.md` and `setup.md` |
+| `memory` | `.agent-memory/MEMORY.md` + rules |
+| `tracking` | empty `docs/GLOSSARY.md`, `DECISIONS.md`, `FEATURES.md`, `BACKLOG.md`, `adr/` + rules; `docs/agents/{domain,issue-tracker,triage-labels}.md` |
+| `browser` | `agent-browser` + `verify-ui` skills, `chrome-devtools` MCP, `.cursor/cli.json`, Claude MCP approval and allowed sites |
+| `workers` | `orchestrate-workers` skill (herdr panes, `hc` reference, `workers.conf`) |
+
+Skills live in `.agents/skills/` (Codex, Cursor); Claude Code gets symlinks in `.claude/skills/`. Files are written only for the agents you select.
+
+The code-graph server itself is set up by [`@mayurdluffy/cbm-cli`](https://github.com/mayurdluffy/cbm-cli); once `.codebase-memory/cbm-server.sh` exists, `ccwf sync` adds the graph-first navigation rules.
+
+## How skills get their settings
+
+A skill that needs project settings asks you the first time it runs and saves them next to itself. `verify-ui` asks for the dev server URL and the sites the browser may visit, writes `.agents/skills/verify-ui/verify-ui.conf`, and runs `ccwf sync`, which copies the allowed sites into `.claude/settings.json` and `.codex/config.toml`.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `ccwf init` | machine setup + repo setup (`--agents`, `--modules`, `--project-only`, `--machine-only`, `--yes`, `--dry-run`, `--force`, `--dir`) |
+| `ccwf add <module>` | add a module |
+| `ccwf update` | the only command that re-renders templates from this ccwf version; edited files are skipped |
+| `ccwf sync` | push skill settings into agent configs and add navigation rules; does not re-render templates |
+| `ccwf doctor` | check tools, skills and files; offer to fix |
+| `ccwf eject <skill>` | stop managing a skill you changed |
+| `ccwf status` | installed modules, drifted files |
+
+State is in `.ccwf.json` (choices and a hash of every file ccwf wrote). Commit it.
+
+## What a first run looks like
+
+```text
+$ npx @mayurdluffy/ccwf init
+  + AGENTS.md
+  + .agents/skills/commit/SKILL.md
+  ...
+repo: 40 created, 0 updated, 0 unchanged, 0 skipped
+machine:
+  ✗ mattpocock/skills skills (0/38 installed)
+  ✓ gh (GitHub CLI)
+  ✗ Codex trusts this repo
+
+Will run:
+  - install 38 skills from mattpocock/skills with `npx skills add` (full command: ccwf init --machine-only --dry-run)
+  - add [projects."/path/to/repo"] trust_level = "trusted" to ~/.codex/config.toml
+Install all? [Y/n]:
+```
+
+Then follow `docs/agents/workflow.md` in your repo. Commit `.ccwf.json` and the files `init` listed.
+
+## Troubleshooting
+
+| You see | Do |
+|---|---|
+| `skipped: not a terminal; re-run with --yes` | run `ccwf init --yes` from a terminal script, or install by hand from `docs/agents/setup.md` |
+| `warning: <file>: modified locally, left as is` | your edit was kept; `ccwf update --force` replaces only files ccwf owns |
+| `... already defined by hand, skipped` | you wrote that config table yourself; ccwf leaves it alone |
+| `next: codebase-memory is not set up here` | run `npx @mayurdluffy/cbm-cli install --agents claude,codex,cursor`, then `ccwf sync` |
+| anything else | `ccwf doctor` checks tools, skills and files and offers to fix them |
+
+## Read next (in your repo after `init`)
+
+- `docs/agents/workflow.md` — grill-with-docs → to-spec → to-tickets → orchestrate-workers.
+- `docs/agents/setup.md` — every tool and skill, and how to install each by hand.
+
+## Maintaining the templates
+
+`node scripts/harvest.js <repo> --terms yourproduct` diffs a working repo's skills against `templates/skills/`, flags project-specific lines, and with `--apply` copies the clean ones. Not published to npm.
+
+## Releasing
+
+Push a tag `vX.Y.Z`; `.github/workflows/publish.yml` publishes using the `NPM_ACCESS_TOKEN` repository secret.
+
+## Contributing
+
+Issues and PRs are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT. `templates/skills/agent-browser/SKILL.md` is the skill stub from [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser) (Apache-2.0, license text shipped next to it, copied from the version installed with the CLI).
+
+---
+
+<p align="center">
+  <a href="https://github.com/mayurdluffy/ccwf">GitHub</a> •
+  <a href="https://www.npmjs.com/package/@mayurdluffy/ccwf">npm</a>
+</p>

package/bin/ccwf.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+const { main } = require("../lib/index");
+
+main().catch((err) => {
+  console.error(`ccwf: ${err.message}`);
+  process.exit(1);
+});

package/lib/index.js

@@ -0,0 +1,312 @@
+"use strict";
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const readline = require("readline/promises");
+const { Installer, sha } = require("./installer");
+const { MODULES, ORDER, AGENTS, makeParams, sync } = require("./modules");
+const machine = require("./machine");
+const pkg = require("../package.json");
+
+const MANIFEST = ".ccwf.json";
+const STATE_MARK = { created: "+", updated: "~", unchanged: "=", skipped: "!" };
+
+const HELP = `ccwf ${pkg.version} — agent setup for Claude Code, Codex and Cursor (macOS, Linux)
+
+Usage: ccwf <command> [options]
+
+  init            set up this computer (tools, user-level skills) and the current repo
+  add <module>    add one module to an initialised repo
+  update          the only command that re-renders templates from this ccwf version (keeps files you edited)
+  sync            push skill settings and add navigation rules; does not re-render templates
+  doctor          check tools, skills and files; offer to fix what is missing
+  eject <skill>   stop managing a skill you changed
+  status          show installed modules and drifted files
+
+Modules: ${ORDER.join(", ")}
+${ORDER.map((m) => `  ${m.padEnd(9)} ${MODULES[m].desc}`).join("\n")}
+
+Options:
+  --agents a,b       claude,codex,cursor (default: all)
+  --modules a,b|all  default: all
+  --project-only     skip machine setup
+  --machine-only     skip the repo
+  --yes, -y          no prompts (install everything missing)
+  --dry-run          show what would change, write and install nothing
+  --force            overwrite only files ccwf owns, never seeded docs
+  --dir PATH         target repo (default: current directory)
+  -h, --help  -v, --version`;
+
+const OPTIONS = new Set(["agents", "modules", "dir", "project-only", "machine-only", "yes", "dry-run", "force", "help", "version"]);
+const VALUED = new Set(["agents", "modules", "dir"]);
+const SHORT = { y: "yes", h: "help", v: "version" };
+
+function parseArgs(argv) {
+  const o = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const [k, inline] = a.slice(2).split("=");
+      if (!OPTIONS.has(k)) throw new Error(`unknown option: --${k}`);
+      if (VALUED.has(k)) o[k] = inline ?? argv[++i];
+      else o[k] = true;
+    } else if (a.startsWith("-") && a !== "-") {
+      const k = a.length === 2 ? SHORT[a[1]] : undefined;
+      if (!k) throw new Error(`unknown option: ${a}`);
+      o[k] = true;
+    } else o._.push(a);
+  }
+  return o;
+}
+
+function list(v, all, what) {
+  const items = v === "all" ? all : String(v).split(",").map((s) => s.trim()).filter(Boolean);
+  const bad = items.filter((i) => !all.includes(i));
+  if (bad.length) throw new Error(`unknown ${what}: ${bad.join(", ")} (valid: ${all.join(", ")})`);
+  return items;
+}
+
+function loadManifest(root) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, MANIFEST), "utf8"));
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw new Error(`${MANIFEST} is not valid JSON: ${err.message}`);
+  }
+}
+
+function saveManifest(root, data, version = pkg.version) {
+  fs.writeFileSync(path.join(root, MANIFEST), JSON.stringify({ ...data, ccwf: version }, null, 2) + "\n");
+}
+
+async function confirm(question, def = true) {
+  if (!process.stdin.isTTY) return false;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const a = (await rl.question(`${question} [${def ? "Y/n" : "y/N"}]: `)).trim().toLowerCase();
+    return a === "" ? def : a === "y" || a === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+// One line per path: a file touched by several modules reports its strongest state.
+function collapse(log) {
+  const rank = { unchanged: 0, skipped: 1, updated: 2, created: 3 };
+  const by = new Map();
+  for (const { rel, state } of log) if (!by.has(rel) || rank[state] > rank[by.get(rel)]) by.set(rel, state);
+  return [...by].map(([rel, state]) => ({ rel, state }));
+}
+
+function report(ins, dryRun) {
+  const log = collapse(ins.log);
+  for (const { rel, state } of log) if (state !== "unchanged") console.log(`  ${STATE_MARK[state]} ${rel}`);
+  const n = (s) => log.filter((l) => l.state === s).length;
+  console.log(`${dryRun ? "would change" : "repo"}: ${n("created")} created, ${n("updated")} updated, ${n("unchanged")} unchanged, ${n("skipped")} skipped`);
+  for (const w of ins.warnings) console.log(`  warning: ${w}`);
+}
+
+// A server entry is the "codebase-memory" key under mcpServers (top level, or under
+// projects in ~/.claude.json), or a Codex mcp_servers table. The name elsewhere is not one.
+const CODEX_CBM_TABLE = /^\[mcp_servers\.(?:"codebase-memory"|'codebase-memory'|codebase-memory)(?:\.env)?\][ \t]*$/;
+
+function hasCbmServer(obj) {
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) return false;
+  const box = obj.mcpServers;
+  return !!box && typeof box === "object" && !Array.isArray(box) && "codebase-memory" in box;
+}
+
+function jsonHasCbmServer(text, projects) {
+  const data = JSON.parse(text);
+  if (hasCbmServer(data)) return true;
+  if (!projects || !data || typeof data !== "object" || Array.isArray(data)) return false;
+  const map = data.projects;
+  if (!map || typeof map !== "object" || Array.isArray(map)) return false;
+  return Object.values(map).some((proj) => hasCbmServer(proj));
+}
+
+function tomlHasCbmTable(text) {
+  return text.split("\n").some((line) => CODEX_CBM_TABLE.test(line));
+}
+
+function globalCbmFindings() {
+  const home = os.homedir();
+  const files = [
+    [".claude.json", true],
+    [".claude/mcp.json", false],
+    [".codex/config.toml", false],
+    [".cursor/mcp.json", false],
+  ];
+  const found = [];
+  for (const [rel, projects] of files) {
+    const file = path.join(home, rel);
+    let text;
+    try {
+      text = fs.readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    try {
+      const hit = rel.endsWith(".toml") ? tomlHasCbmTable(text) : jsonHasCbmServer(text, projects);
+      if (hit) found.push({ file, kind: "server" });
+    } catch {
+      found.push({ file, kind: "unparsed" });
+    }
+  }
+  return found;
+}
+
+// ---- project ----
+
+function applyProject({ root, agents, modules, ejected, files, dryRun, force }) {
+  const ins = new Installer({ root, dryRun, force, files, ejected });
+  const ctx = { ins, agents, params: makeParams({ agents }) };
+  for (const m of ORDER.filter((x) => modules.includes(x))) MODULES[m].run(ctx);
+  const synced = sync(ctx, modules);
+  return { ins, synced };
+}
+
+function projectNextSteps(synced) {
+  if (!synced.cbm) {
+    console.log("  next: codebase-memory is not set up here. Run `npx @mayurdluffy/cbm-cli install --agents claude,codex,cursor`, then `npx @mayurdluffy/ccwf sync` (see docs/agents/setup.md)");
+  }
+  for (const { file, kind } of globalCbmFindings()) {
+    const shown = file.replace(os.homedir(), "~");
+    if (kind === "server") console.log(`  warning: ${shown} registers a global codebase-memory server; run \`npx @mayurdluffy/cbm-cli clean-global\``);
+    else console.log(`  note: ${shown} could not be checked`);
+  }
+}
+
+// ---- machine ----
+
+async function machineSetup({ agents, modules, root, opts, fixOnly = false }) {
+  const items = machine.plan({ agents, modules, repoRoot: root });
+  const missing = items.filter((i) => i.status === "missing");
+  console.log("machine:");
+  for (const i of items) console.log(`  ${i.status === "ok" ? "✓" : "✗"} ${i.label}`);
+  if (missing.length === 0) return console.log("  everything is installed");
+
+  for (const i of missing.filter((m) => m.kind === "manual")) console.log(`  by hand: ${i.hint}`);
+  const todo = missing.filter((i) => i.kind !== "manual");
+  if (todo.length === 0) return;
+
+  const dry = opts["dry-run"];
+  console.log(dry ? "\nWould run:" : "\nWill run:");
+  for (const i of todo) console.log(`  - ${i.kind === "run" ? (dry ? i.cmd : i.summary || i.cmd) : i.hint}`);
+  if (dry) return;
+  const go = opts.yes || (await confirm("Install all?"));
+  if (!go) {
+    console.log(!process.stdin.isTTY && !opts.yes ? "  skipped: not a terminal; re-run with --yes to install" : "  skipped");
+    return;
+  }
+  for (const r of machine.run(todo)) console.log(`  ${r.ok ? "installed" : "FAILED"}: ${r.id}${r.error ? ` (${r.error})` : ""}`);
+  console.log(`\nLog in once (cannot be scripted): ${machine.loginHints(agents).join(" · ")}`);
+  if (!fixOnly) console.log("Restart your coding agents so they see new skills.");
+}
+
+// ---- commands ----
+
+async function install(cmd, opts, root) {
+  const prev = loadManifest(root);
+  let agents;
+  let modules;
+  const ejected = prev?.ejected || [];
+  if (cmd === "update") {
+    if (!prev) throw new Error(`no ${MANIFEST} here; run \`ccwf init\` first`);
+    ({ agents, modules } = prev);
+  } else {
+    agents = list(opts.agents ?? (prev?.agents || AGENTS).join(","), AGENTS, "agent");
+    modules = list(opts.modules ?? "all", ORDER, "module");
+    // Re-init keeps modules already installed, the same way add does.
+    if (prev && (cmd === "add" || cmd === "init")) modules = [...new Set([...(prev.modules || []), ...modules])];
+    if (!modules.includes("core")) modules.unshift("core");
+  }
+
+  let synced = { cbm: true };
+  if (!opts["machine-only"]) {
+    if (!fs.existsSync(path.join(root, ".git"))) console.log("  note: not a git repo root; ccwf works anyway, but `commit`/`orchestrate-workers` expect git");
+    const r = applyProject({ root, agents, modules, ejected, files: prev?.files, dryRun: opts["dry-run"], force: opts.force });
+    synced = r.synced;
+    report(r.ins, opts["dry-run"]);
+    if (!opts["dry-run"]) saveManifest(root, { agents, modules, ejected, files: r.ins.files });
+  }
+  if (!opts["project-only"] && cmd === "init") await machineSetup({ agents, modules, root, opts });
+  if (!opts["machine-only"]) projectNextSteps(synced);
+}
+
+async function runSync(opts, root) {
+  const prev = loadManifest(root);
+  if (!prev) throw new Error(`no ${MANIFEST} here; run \`ccwf init\` first`);
+  // Settings and the navigation block only. Re-rendering templates is update's job.
+  const ins = new Installer({ root, dryRun: opts["dry-run"], force: false, files: prev.files, ejected: prev.ejected || [] });
+  const agents = prev.agents;
+  const synced = sync({ ins, agents, params: makeParams({ agents }) }, prev.modules);
+  report(ins, opts["dry-run"]);
+  if (!opts["dry-run"]) saveManifest(root, { ...prev, files: ins.files }, prev.ccwf);
+  console.log(`allowed sites: ${synced.domains}${synced.cbm ? " · codebase-memory rules: on" : ""}`);
+  projectNextSteps(synced);
+}
+
+function eject(opts, root) {
+  const name = opts._[1];
+  const prev = loadManifest(root);
+  if (!prev) throw new Error(`no ${MANIFEST} here; run \`ccwf init\` first`);
+  const dir = `.agents/skills/${name}`;
+  if (!name || !fs.existsSync(path.join(root, dir))) throw new Error(`usage: ccwf eject <skill> (no ${dir})`);
+  const ejected = [...new Set([...(prev.ejected || []), dir])];
+  const files = Object.fromEntries(Object.entries(prev.files).filter(([rel]) => !rel.startsWith(dir + "/")));
+  saveManifest(root, { ...prev, ejected, files });
+  console.log(`ejected ${name}: ccwf no longer touches ${dir}/`);
+}
+
+function status(root) {
+  const m = loadManifest(root);
+  if (!m) return console.log(`not initialised (no ${MANIFEST}); run \`ccwf init\``);
+  console.log(`ccwf ${m.ccwf} (installed) / ${pkg.version} (this package)`);
+  console.log(`agents: ${m.agents.join(", ")}\nmodules: ${m.modules.join(", ")}`);
+  if (m.ejected?.length) console.log(`ejected: ${m.ejected.join(", ")}`);
+  let drift = 0;
+  for (const [rel, hash] of Object.entries(m.files)) {
+    let cur = null;
+    try {
+      cur = fs.readFileSync(path.join(root, rel), "utf8");
+    } catch {}
+    const state = cur === null ? "missing" : sha(cur) === hash ? null : "modified";
+    if (state) {
+      drift++;
+      console.log(`  ${state}: ${rel}`);
+    }
+  }
+  console.log(drift ? `${drift} file(s) differ from what ccwf wrote` : "all ccwf-owned files match");
+}
+
+async function doctor(opts, root) {
+  const m = loadManifest(root);
+  if (m) status(root);
+  else console.log(`(no ${MANIFEST} in ${root}: checking the machine only)`);
+  console.log("");
+  const agents = m?.agents || AGENTS;
+  const modules = m?.modules || ORDER;
+  await machineSetup({ agents, modules, root: m ? root : null, opts, fixOnly: true });
+  if (m) projectNextSteps(applyProject({ root, agents, modules, ejected: m.ejected || [], files: m.files, dryRun: true, force: false }).synced);
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const opts = parseArgs(argv);
+  const cmd = opts._[0];
+  if (opts.version) return console.log(pkg.version);
+  if (opts.help || !cmd || cmd === "help") return console.log(HELP);
+  const root = path.resolve(opts.dir || process.cwd());
+  if (cmd === "status") return status(root);
+  if (cmd === "doctor") return doctor(opts, root);
+  if (cmd === "sync") return runSync(opts, root);
+  if (cmd === "eject") return eject(opts, root);
+  if (cmd === "init" || cmd === "update") return install(cmd, opts, root);
+  if (cmd === "add") {
+    if (!opts._[1]) throw new Error("usage: ccwf add <module>");
+    return install("add", { ...opts, modules: opts._.slice(1).join(",") }, root);
+  }
+  throw new Error(`unknown command: ${cmd}\n\n${HELP}`);
+}
+
+module.exports = { main, parseArgs };

package/lib/installer.js

@@ -0,0 +1,127 @@
+"use strict";
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { upsertBlock, mergeJson, hasTableOutsideBlock, missingMarker } = require("./merge");
+
+const sha = (s) => crypto.createHash("sha256").update(s).digest("hex");
+
+// Applies file operations under `root`, records what it did, and never clobbers user edits.
+class Installer {
+  constructor({ root, dryRun = false, force = false, files = {}, ejected = [] }) {
+    this.root = root;
+    this.ejected = ejected; // path prefixes the user took over (ccwf eject)
+    this.dryRun = dryRun;
+    this.force = force;
+    this.files = { ...files }; // rel -> sha256 of the content ccwf last wrote
+    this.log = []; // { rel, state: created|updated|unchanged|skipped }
+    this.warnings = [];
+  }
+
+  abs(rel) {
+    return path.join(this.root, rel);
+  }
+  read(rel) {
+    try {
+      return fs.readFileSync(this.abs(rel), "utf8");
+    } catch {
+      return null;
+    }
+  }
+  note(rel, state) {
+    this.log.push({ rel, state });
+  }
+  warn(msg) {
+    this.warnings.push(msg);
+  }
+  write(rel, content, mode) {
+    if (this.dryRun) return;
+    fs.mkdirSync(path.dirname(this.abs(rel)), { recursive: true });
+    fs.writeFileSync(this.abs(rel), content, mode ? { mode } : undefined);
+    if (mode) fs.chmodSync(this.abs(rel), mode);
+  }
+
+  // A file ccwf owns: replaced on update only while it still matches what ccwf wrote.
+  owned(rel, content, mode) {
+    if (this.ejected.some((p) => rel === p || rel.startsWith(p + "/"))) return this.note(rel, "unchanged");
+    const cur = this.read(rel);
+    if (cur === content) {
+      this.files[rel] = sha(content);
+      return this.note(rel, "unchanged");
+    }
+    if (cur !== null && !this.force && this.files[rel] !== sha(cur)) {
+      this.warn(`${rel}: modified locally, left as is (use --force to overwrite)`);
+      return this.note(rel, "skipped");
+    }
+    this.write(rel, content, mode);
+    this.files[rel] = sha(content);
+    this.note(rel, cur === null ? "created" : "updated");
+  }
+
+  // A file the user will edit: written once, never touched again. --force does not apply.
+  seed(rel, content, mode) {
+    if (this.read(rel) !== null) return this.note(rel, "unchanged");
+    this.write(rel, content, mode);
+    this.note(rel, "created");
+  }
+
+  // Managed section inside a shared text file (AGENTS.md, .gitignore, config.toml).
+  block(rel, id, body, style = "md") {
+    const raw = this.read(rel);
+    const cur = raw ?? "";
+    const missing = missingMarker(cur, id, style);
+    if (missing) {
+      this.warn(`${rel}: managed block ${id} has no ${missing} marker, skipped`);
+      return this.note(rel, "skipped");
+    }
+    const next = upsertBlock(cur, id, body, style);
+    if (next === cur) return this.note(rel, "unchanged");
+    this.write(rel, next);
+    this.note(rel, raw === null ? "created" : "updated");
+  }
+
+  // Codex TOML: a managed block, unless the user already defines the same table by hand.
+  tomlBlock(rel, id, body, tables) {
+    const cur = this.read(rel) ?? "";
+    const clash = tables.find((t) => hasTableOutsideBlock(cur, id, t));
+    if (clash) {
+      this.warn(`${rel}: [${clash}] already defined by hand, skipped ${id}`);
+      return this.note(rel, "skipped");
+    }
+    this.block(rel, id, body, "hash");
+  }
+
+  // Deep-merge keys into a JSON file; invalid JSON aborts without touching the file.
+  json(rel, patch, union = []) {
+    const cur = this.read(rel) ?? "";
+    const next = mergeJson(cur, patch, rel, union);
+    if (next === cur) return this.note(rel, "unchanged");
+    const existed = cur !== "";
+    this.write(rel, next);
+    this.note(rel, existed ? "updated" : "created");
+  }
+
+  // Relative symlink. A failure is an error for this skill; the files are not copied.
+  link(rel, target) {
+    let cur = null;
+    try {
+      cur = fs.readlinkSync(this.abs(rel));
+    } catch {}
+    if (cur === target) return this.note(rel, "unchanged");
+    if (fs.existsSync(this.abs(rel)) || cur !== null) {
+      this.warn(`${rel}: already exists and is not the expected link, left as is`);
+      return this.note(rel, "skipped");
+    }
+    if (!this.dryRun) {
+      fs.mkdirSync(path.dirname(this.abs(rel)), { recursive: true });
+      try {
+        fs.symlinkSync(target, this.abs(rel), "dir");
+      } catch (err) {
+        throw new Error(`${rel}: could not create symlink (${err.code || err.message})`);
+      }
+    }
+    this.note(rel, "created");
+  }
+}
+
+module.exports = { Installer, sha };