@mayurdluffy/ccwf 0.0.0-stage → 0.1.0

package/lib/machine.js

@@ -0,0 +1,167 @@
+"use strict";
+// Machine setup: things installed once per computer. plan() only inspects; run() installs.
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const MACHINE = require("../templates/machine.json");
+
+const SKILLS_AGENT_ID = { claude: "claude-code", codex: "codex", cursor: "cursor" };
+const SKILL_DIR = { claude: ".claude/skills", codex: ".agents/skills", cursor: ".cursor/skills" };
+const AGENT_CLI = {
+  claude: { bin: "claude", cmd: "curl -fsSL https://claude.ai/install.sh | bash", login: "claude" },
+  codex: { bin: "codex", cmd: "curl -fsSL https://chatgpt.com/codex/install.sh | sh", login: "codex login" },
+  cursor: { bin: "cursor-agent", cmd: "curl https://cursor.com/install -fsS | bash", login: "cursor-agent login" },
+};
+
+function realEnv() {
+  return {
+    platform: process.platform,
+    home: os.homedir(),
+    have: (bin) => spawnSync("which", [bin], { stdio: "ignore" }).status === 0,
+    exists: (p) => fs.existsSync(p),
+    read: (p) => {
+      try {
+        return fs.readFileSync(p, "utf8");
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+function tomlQuoted(value) {
+  return `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function projectHeader(repoRoot) {
+  return `[projects.${tomlQuoted(repoRoot)}]`;
+}
+
+function repoTrusted(text, repoRoot) {
+  const header = projectHeader(repoRoot);
+  let inTable = false;
+  for (const line of String(text).split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("[")) {
+      inTable = trimmed === header;
+      continue;
+    }
+    if (inTable && trimmed === 'trust_level = "trusted"') return true;
+  }
+  return false;
+}
+
+function skillVisible(exists, home, agent, name) {
+  return exists(path.join(home, SKILL_DIR[agent], name));
+}
+
+// items: { id, label, status: "ok" | "missing", kind: "run" | "edit" | "manual", cmd?, hint?, apply?, detect? }
+function plan({ agents, modules, repoRoot, env = realEnv() }) {
+  const { platform, home, have, exists, read } = env;
+  if (platform !== "darwin" && platform !== "linux") {
+    throw new Error(`machine setup supports macOS and Linux only (this is ${platform})`);
+  }
+  const items = [];
+  const item = (id, label, ok, rest) => items.push({ id, label, status: ok ? "ok" : "missing", ...rest });
+
+  // User-level skills (pinned lists): installed once for all selected agents.
+  const skillAgents = agents.map((a) => SKILLS_AGENT_ID[a]).join(" ");
+  for (const [source, names] of Object.entries(MACHINE.skills)) {
+    const unseen = () => names.filter((n) => agents.some((a) => !skillVisible(exists, home, a, n)));
+    const missing = unseen();
+    item(`skills:${source}`, `${source} skills (${names.length - missing.length}/${names.length} installed)`, missing.length === 0, {
+      kind: "run",
+      summary: `install ${missing.length} skill${missing.length === 1 ? "" : "s"} from ${source} with \`npx skills add\` (full command: ccwf init --machine-only --dry-run)`,
+      cmd: `npx -y skills add ${source} -g -a ${skillAgents} -s ${missing.join(" ")} -y`,
+      detect: () => unseen().length === 0,
+    });
+  }
+
+  const brewOr = (pkg, hint) => (platform === "darwin" && have("brew") ? { kind: "run", cmd: `brew install ${pkg}` } : { kind: "manual", hint });
+  item("gh", "gh (GitHub CLI)", have("gh"), {
+    ...brewOr("gh", "install gh with your package manager: https://cli.github.com"),
+    detect: () => have("gh"),
+  });
+
+  if (modules.includes("browser")) {
+    item("agent-browser", "agent-browser", have("agent-browser"), {
+      kind: "run",
+      cmd: `npm i -g agent-browser && agent-browser install${platform === "linux" ? " --with-deps" : ""}`,
+      detect: () => have("agent-browser"),
+    });
+    item("ffmpeg", "ffmpeg (bug recordings)", have("ffmpeg"), {
+      ...brewOr("ffmpeg", "install ffmpeg with your package manager"),
+      detect: () => have("ffmpeg"),
+    });
+    const chrome =
+      platform === "darwin"
+        ? exists("/Applications/Google Chrome.app")
+        : have("google-chrome") || have("google-chrome-stable") || have("chromium");
+    item("chrome", "Google Chrome (chrome-devtools MCP)", chrome, { kind: "manual", hint: "install Google Chrome: https://google.com/chrome" });
+  }
+
+  if (modules.includes("workers")) {
+    item("herdr", "herdr + hc (worker panes)", have("hc"), {
+      kind: "run",
+      cmd: "curl -fsSL https://releases.herdr.dev/app/install.sh | sh",
+      detect: () => have("hc"),
+    });
+  }
+
+  if (modules.includes("browser") || modules.includes("workers")) {
+    item("zsh", "zsh", have("zsh"), { kind: "manual", hint: "install zsh with your package manager" });
+  }
+  if (modules.includes("workers")) {
+    item("python3", "python3", have("python3"), { kind: "manual", hint: "install python3 with your package manager" });
+  }
+
+  for (const a of agents) {
+    const c = AGENT_CLI[a];
+    item(`cli:${a}`, `${c.bin} CLI`, have(c.bin), { kind: "run", cmd: c.cmd, detect: () => have(c.bin) });
+  }
+
+  if (agents.includes("codex") && repoRoot) {
+    const file = path.join(home, ".codex", "config.toml");
+    const header = projectHeader(repoRoot);
+    item("codex-trust", "Codex trusts this repo", repoTrusted(read(file) ?? "", repoRoot), {
+      kind: "edit",
+      hint: `add ${header} trust_level = "trusted" to ~/.codex/config.toml`,
+      apply: () => {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        let cur = "";
+        if (fs.existsSync(file)) {
+          cur = fs.readFileSync(file, "utf8");
+          fs.copyFileSync(file, `${file}.bak`);
+        }
+        fs.writeFileSync(file, `${cur}${cur === "" || cur.endsWith("\n") ? "" : "\n"}\n${header}\ntrust_level = "trusted"\n`);
+      },
+    });
+  }
+  return items;
+}
+
+function loginHints(agents) {
+  return [...agents.map((a) => AGENT_CLI[a].login), "gh auth login"];
+}
+
+// Runs the given missing items; returns [{ id, ok, error? }]. `exec` is injectable for tests.
+function run(items, exec = (cmd) => spawnSync("sh", ["-c", cmd], { stdio: "inherit" }).status === 0) {
+  const results = [];
+  for (const it of items) {
+    if (it.kind === "run") {
+      const ran = Boolean(exec(it.cmd));
+      results.push({ id: it.id, ok: ran && (it.detect ? it.detect() : true) });
+    } else if (it.kind === "edit") {
+      try {
+        it.apply();
+        results.push({ id: it.id, ok: true });
+      } catch (err) {
+        results.push({ id: it.id, ok: false, error: err.message });
+      }
+    }
+  }
+  return results;
+}
+
+module.exports = { plan, run, loginHints, realEnv };

package/lib/merge.js

@@ -0,0 +1,92 @@
+"use strict";
+// Pure text merges. Each returns the new text; calling twice with the same input is a no-op.
+
+const STYLES = {
+  md: (id, edge) => `<!-- ccwf:${edge} ${id} -->`,
+  hash: (id, edge) => `# ccwf:${edge} ${id}`,
+};
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// "end" or "begin" when that marker is missing and the other is present; null when the pair is usable.
+function missingMarker(text, id, style = "md") {
+  const hasBegin = text.includes(STYLES[style](id, "begin"));
+  const hasEnd = text.includes(STYLES[style](id, "end"));
+  if (hasBegin && !hasEnd) return "end";
+  if (hasEnd && !hasBegin) return "begin";
+  return null;
+}
+
+// Insert or replace the block `id` between begin/end markers; text outside is untouched.
+// A block with only one marker is left unchanged so text after the marker is not swallowed.
+function upsertBlock(text, id, body, style = "md") {
+  if (missingMarker(text, id, style)) return text;
+  const begin = STYLES[style](id, "begin");
+  const end = STYLES[style](id, "end");
+  const block = `${begin}\n${body.trimEnd()}\n${end}`;
+  const re = new RegExp(`${escapeRe(begin)}[\\s\\S]*?${escapeRe(end)}`);
+  if (re.test(text)) return text.replace(re, () => block);
+  const sep = text === "" ? "" : text.endsWith("\n\n") ? "" : text.endsWith("\n") ? "\n" : "\n\n";
+  return `${text}${sep}${block}\n`;
+}
+
+function removeBlock(text, id, style = "md") {
+  const begin = STYLES[style](id, "begin");
+  const end = STYLES[style](id, "end");
+  return text.replace(new RegExp(`\\n?${escapeRe(begin)}[\\s\\S]*?${escapeRe(end)}\\n?`), "\n");
+}
+
+// True when a `[table]` header exists outside the managed block `id` (the user owns it).
+function hasTableOutsideBlock(text, id, table) {
+  const outside = removeBlock(text, id, "hash");
+  return new RegExp(`^\\s*\\[${escapeRe(table)}\\]`, "m").test(outside);
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function deepMerge(target, patch) {
+  for (const [k, v] of Object.entries(patch)) {
+    if (isPlainObject(v) && isPlainObject(target[k])) deepMerge(target[k], v);
+    else target[k] = v;
+  }
+  return target;
+}
+
+function getPath(obj, dotted) {
+  return dotted.split(".").reduce((o, k) => (o == null ? undefined : o[k]), obj);
+}
+
+function setPath(obj, dotted, value) {
+  const keys = dotted.split(".");
+  const last = keys.pop();
+  const box = keys.reduce((o, k) => (isPlainObject(o[k]) ? o[k] : (o[k] = {})), obj);
+  box[last] = value;
+}
+
+// Merge `patch` into JSON text, keeping every other key. Throws on invalid JSON (never overwrite).
+// `union`: dotted paths whose arrays are merged as a set (existing entries first) instead of replaced.
+function mergeJson(text, patch, label = "JSON file", union = []) {
+  let data = {};
+  if (text.trim() !== "") {
+    try {
+      data = JSON.parse(text);
+    } catch (err) {
+      throw new Error(`${label} is not valid JSON (${err.message}); fix it, then re-run`);
+    }
+    if (!isPlainObject(data)) throw new Error(`${label} must contain a JSON object`);
+  }
+  const p = JSON.parse(JSON.stringify(patch));
+  for (const path of union) {
+    const add = getPath(p, path);
+    if (!Array.isArray(add)) continue;
+    const have = getPath(data, path);
+    setPath(p, path, [...new Set([...(Array.isArray(have) ? have : []), ...add])]);
+  }
+  return JSON.stringify(deepMerge(data, p), null, 2) + "\n";
+}
+
+module.exports = { upsertBlock, removeBlock, hasTableOutsideBlock, mergeJson, missingMarker };

package/lib/modules.js

@@ -0,0 +1,199 @@
+"use strict";
+const fs = require("fs");
+const path = require("path");
+
+const TEMPLATES = path.join(__dirname, "..", "templates");
+const AGENTS = ["claude", "codex", "cursor"];
+const CHROME_ARGS = ["-y", "chrome-devtools-mcp@latest", "--isolated", "--no-usage-statistics", "--no-performance-crux"];
+
+function render(text, params) {
+  return text.replace(/\{\{(\w+)\}\}/g, (m, k) => (k in params.vars ? params.vars[k] : m));
+}
+
+function walk(dir, base = dir) {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+    const p = path.join(dir, e.name);
+    return e.isDirectory() ? walk(p, base) : [path.relative(base, p).split(path.sep).join("/")];
+  });
+}
+
+function blockBody(name, params) {
+  return render(fs.readFileSync(path.join(TEMPLATES, "blocks", `${name}.md`), "utf8"), params);
+}
+
+// Rendered files of one skill: [{ rel, content, mode, seed }]
+function skillFiles(name, params) {
+  const dir = path.join(TEMPLATES, "skills", name);
+  return walk(dir).map((rel) => {
+    const st = fs.statSync(path.join(dir, rel));
+    return {
+      rel,
+      content: render(fs.readFileSync(path.join(dir, rel), "utf8"), params),
+      mode: st.mode & 0o111 ? 0o755 : undefined,
+      seed: rel === "workers.conf",
+    };
+  });
+}
+
+function installSkill(ctx, name) {
+  const { ins, params, agents } = ctx;
+  for (const f of skillFiles(name, params)) {
+    const rel = `.agents/skills/${name}/${f.rel}`;
+    if (f.seed) ins.seed(rel, f.content, f.mode);
+    else ins.owned(rel, f.content, f.mode);
+  }
+  if (agents.includes("claude")) {
+    ins.link(`.claude/skills/${name}`, `../../.agents/skills/${name}`);
+  }
+}
+
+const tpl = (...parts) => fs.readFileSync(path.join(TEMPLATES, ...parts), "utf8");
+const CONF = ".agents/skills/verify-ui/verify-ui.conf";
+
+// CLAUDE.md is skipped when it is AGENTS.md (a symlink) or the import is already there.
+function skipClaudeImport(ins) {
+  try {
+    if (fs.realpathSync(ins.abs("CLAUDE.md")) === fs.realpathSync(ins.abs("AGENTS.md"))) return true;
+  } catch {}
+  const cur = ins.read("CLAUDE.md");
+  return cur !== null && cur.includes("@AGENTS.md");
+}
+
+// Same MCP entry for Claude (.mcp.json) and Cursor (.cursor/mcp.json); Codex gets a TOML block.
+function mcp(ctx, id, command, args, tomlBody) {
+  const { ins, agents } = ctx;
+  const entry = { mcpServers: { [id]: { command, args } } };
+  if (agents.includes("claude")) ins.json(".mcp.json", entry);
+  if (agents.includes("cursor")) ins.json(".cursor/mcp.json", entry);
+  if (agents.includes("codex")) ins.tomlBlock(".codex/config.toml", `mcp-${id}`, tomlBody, [`mcp_servers.${id}`]);
+}
+
+function unquote(value) {
+  if (value.length >= 2) {
+    const q = value[0];
+    if ((q === '"' || q === "'") && value[value.length - 1] === q) return value.slice(1, -1);
+  }
+  return value;
+}
+
+// KEY=value lines. Spaces around = are optional, matching quotes are not part of the value,
+// and the last line may lack a newline. Same rules as templates/skills/verify-ui/lib.sh.
+function parseConf(text) {
+  const out = {};
+  for (const raw of (text || "").split("\n")) {
+    const line = raw.trim();
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    if (!/^[A-Z_]+$/.test(key)) continue;
+    out[key] = unquote(line.slice(eq + 1).trim());
+  }
+  return out;
+}
+
+// A site list is comma-separated domains: letters, digits, hyphens and dots.
+function validSiteList(value) {
+  const label = "[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?";
+  return new RegExp(`^(?:${label})(?:\\.(?:${label}))*(?:,(?:${label})(?:\\.(?:${label}))*)*$`).test(value);
+}
+
+const MODULES = {
+  core: {
+    desc: "engineering discipline rules, commit skill, workflow + setup guides",
+    run(ctx) {
+      const { ins, agents, params } = ctx;
+      ins.block("AGENTS.md", "core", blockBody("core", params));
+      if (agents.includes("claude")) {
+        if (skipClaudeImport(ins)) ins.note("CLAUDE.md", "unchanged");
+        else ins.block("CLAUDE.md", "agents", "@AGENTS.md");
+      }
+      if (agents.includes("cursor")) ins.owned(".cursor/rules/ccwf.mdc", tpl("cursor-rule.mdc"));
+      installSkill(ctx, "commit");
+      for (const f of ["workflow", "setup"]) ins.owned(`docs/agents/${f}.md`, tpl("docs", "agents", `${f}.md`));
+    },
+  },
+  memory: {
+    desc: "shared .agent-memory/ for all three agents",
+    run(ctx) {
+      ctx.ins.seed(".agent-memory/MEMORY.md", tpl("agent-memory", "MEMORY.md"));
+      ctx.ins.block("AGENTS.md", "memory", blockBody("memory", ctx.params));
+    },
+  },
+  tracking: {
+    desc: "empty GLOSSARY, DECISIONS, FEATURES, BACKLOG, adr/ + the rules for using them",
+    run(ctx) {
+      const { ins } = ctx;
+      for (const f of ["GLOSSARY", "DECISIONS", "BACKLOG", "FEATURES"]) ins.seed(`docs/${f}.md`, tpl("docs", `${f}.md`));
+      ins.seed("docs/adr/.gitkeep", "");
+      for (const f of ["domain", "issue-tracker", "triage-labels"]) ins.seed(`docs/agents/${f}.md`, tpl("docs", "agents", `${f}.md`));
+      ins.block("AGENTS.md", "tracking", blockBody("tracking", ctx.params));
+    },
+  },
+  browser: {
+    desc: "agent-browser + verify-ui skills, chrome-devtools MCP, Cursor command allowlist",
+    run(ctx) {
+      const { ins, agents, params } = ctx;
+      installSkill(ctx, "agent-browser");
+      installSkill(ctx, "verify-ui");
+      mcp(ctx, "chrome-devtools", "npx", CHROME_ARGS, `[mcp_servers.chrome-devtools]\ncommand = "npx"\nargs = [${CHROME_ARGS.map((a) => `"${a}"`).join(", ")}]`);
+      if (agents.includes("claude")) ins.json(".claude/settings.json", { enabledMcpjsonServers: ["chrome-devtools"] }, ["enabledMcpjsonServers"]);
+      if (agents.includes("cursor")) ins.json(".cursor/cli.json", JSON.parse(tpl("cursor-cli.json")), ["permissions.allow", "permissions.deny"]);
+      ins.block("AGENTS.md", "browser", blockBody("browser", params));
+    },
+  },
+  workers: {
+    desc: "orchestrate-workers skill (needs herdr + hc)",
+    run(ctx) {
+      installSkill(ctx, "orchestrate-workers");
+      ctx.ins.block("AGENTS.md", "workers", blockBody("workers", ctx.params));
+    },
+  },
+};
+
+// Pushes per-project settings into the agent configs. Safe to run any time (idempotent).
+function sync(ctx, modules) {
+  const { ins, agents, params } = ctx;
+  const conf = parseConf(ins.read(CONF));
+  if (conf.ALLOWED_DOMAINS && !validSiteList(conf.ALLOWED_DOMAINS)) {
+    throw new Error("verify-ui.conf: ALLOWED_DOMAINS contains characters that cannot be part of a site list");
+  }
+  const domains = conf.ALLOWED_DOMAINS || "localhost";
+  if (modules.includes("browser")) {
+    if (agents.includes("claude")) ins.json(".claude/settings.json", { env: { AGENT_BROWSER_ALLOWED_DOMAINS: domains } });
+    if (agents.includes("codex")) {
+      ins.tomlBlock(
+        ".codex/config.toml",
+        "browser-env",
+        `[shell_environment_policy]\ninherit = "all"\nset = { AGENT_BROWSER_ALLOWED_DOMAINS = "${domains}" }`,
+        ["shell_environment_policy"],
+      );
+    }
+  }
+  // cbm-cli owns the codebase-memory server; once it has set the repo up, ccwf adds the rules.
+  if (ins.read(".codebase-memory/cbm-server.sh") !== null) {
+    ins.block("AGENTS.md", "cbm", blockBody("cbm", params));
+    if (agents.includes("cursor") && modules.includes("browser")) {
+      ins.json(".cursor/cli.json", { permissions: { allow: ["Mcp(codebase-memory:*)"] } }, ["permissions.allow"]);
+    }
+    return { cbm: true, domains };
+  }
+  return { cbm: false, domains };
+}
+
+const ORDER = Object.keys(MODULES);
+
+const WORKER_NAMES = ["alpha", "beta", "gamma", "theta"];
+const DEFAULT_MODEL = { claude: "claude-sonnet-5-5", codex: "gpt-5-codex", cursor: "grok-4.7" };
+
+function defaultRoster(agents) {
+  return WORKER_NAMES.map((n, i) => {
+    const a = agents[i % agents.length];
+    return `${n.padEnd(8)} ${a.padEnd(8)} ${DEFAULT_MODEL[a].padEnd(18)} auto`;
+  }).join("\n");
+}
+
+function makeParams({ agents }) {
+  return { agents, vars: { DATE: new Date().toISOString().slice(0, 10), ROSTER: defaultRoster(agents) } };
+}
+
+module.exports = { MODULES, ORDER, AGENTS, makeParams, sync, TEMPLATES, parseConf };

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@mayurdluffy/ccwf",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "One command to set up skills, MCP servers, shared memory and rules for Claude Code, Codex and Cursor in any repo",
+  "main": "bin/ccwf.js",
+  "bin": {
+    "ccwf": "bin/ccwf.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepare": "node -e \"require('fs').chmodSync('bin/ccwf.js', 0o755)\""
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "cursor",
+    "agents",
+    "skills",
+    "mcp",
+    "codebase-memory-mcp",
+    "cli",
+    "developer-tools"
+  ],
+  "author": "mayurdluffy <mayurdluffy@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mayurdluffy/ccwf.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mayurdluffy/ccwf/issues"
+  },
+  "homepage": "https://github.com/mayurdluffy/ccwf#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/templates/agent-memory/MEMORY.md

@@ -0,0 +1,4 @@
+# Shared agent memory
+
+Index for Claude Code, Codex and Cursor. One line per memory, alphabetical. Full facts live in the linked files.
+

package/templates/blocks/browser.md

@@ -0,0 +1,9 @@
+## Browser verification (Claude Code, Codex, Cursor)
+
+Never screenshot to check that something exists or loaded; read the accessibility tree instead. Screenshot only for purely visual questions (layout, colors).
+
+- **Start with the `verify-ui` skill** (`.agents/skills/verify-ui`): `probe.sh <path>` prints a page's health (uncaught errors, console, failed and API requests, vitals, interactive elements) in one call; `run.sh <dir>` runs ticket scenarios as a regression suite; `PLAYBOOK.md` maps each browser symptom to one command. Evidence is saved under `.scratch/.verify-out/` (git-ignored). Base URL and allowed sites are in `.agents/skills/verify-ui/verify-ui.conf`; the skill asks for them on first use, then run `npx @mayurdluffy/ccwf sync`.
+- **Drive/inspect UI by hand → `agent-browser`** (CLI; skill in `.agents/skills/agent-browser`; run `agent-browser skills get core` once per session). Use your own session: `S=$(agent-browser session id --scope worktree --prefix task)` then `agent-browser --session $S ...`. Loop: `open <url>` → `snapshot -i -c` (add `--delta` on re-snapshots) → act on `@eN` refs → `console` for errors → `close`.
+- **`chrome-devtools` MCP only for what agent-browser cannot do**: logpoints, CSS cascade, throttling, performance traces, heap snapshots, Lighthouse. Keep its output small.
+- **Dev server**: start it as a background process and stop it by its ID; never `pkill`/`killall`.
+- **Allowed sites** come from `ALLOWED_DOMAINS` in `verify-ui.conf` and are enforced through `AGENT_BROWSER_ALLOWED_DOMAINS` (Claude: `.claude/settings.json`; Codex: `.codex/config.toml`; Cursor: prefix agent-browser commands with it, the `verify-ui` scripts set it themselves). Never visit a site that is not listed; ask the user to add it.

package/templates/blocks/cbm.md

@@ -0,0 +1,9 @@
+## Codebase navigation (Claude Code, Codex, Cursor)
+
+Use the codebase-memory MCP (server `codebase-memory`) before Grep/Read. It is registered **per project** and is the only CBM server any agent runs here:
+
+- Launcher: `.codebase-memory/cbm-server.sh`. Configs: `.mcp.json` (Claude), `.codex/config.toml` (Codex), `.cursor/mcp.json` (Cursor) all point at it.
+- CBM allows one daemon and one cache root per user account at a time. Never set `CBM_CACHE_DIR` per repo and never register a global CBM server (`~/.claude.json`, `~/.codex/config.toml`, `~/.cursor/mcp.json`); either one makes servers fail with a "different cache directory" error. `npx @mayurdluffy/cbm-cli clean-global` removes stray global entries.
+- Order: project docs → graph (`search_graph`, `trace_path`, `get_code_snippet`, `get_architecture`) → Grep/Read only on a graph miss or for non-code files.
+- Exclusions go in the root `.cbmignore`; the indexer also honors `.gitignore`.
+- Re-index after large changes: `npx @mayurdluffy/cbm-cli re-index` (refreshes the committed `.codebase-memory/graph.db.zst`).

package/templates/blocks/core.md

@@ -0,0 +1,35 @@
+## Engineering discipline
+
+Bias toward caution over speed; use judgment on trivial tasks. Lean by default.
+
+**Before changing code**
+- Read the task and the code it affects; trace the real end-to-end flow.
+- Identify callers, tests, config, exports, and data the change could break.
+- State assumptions. If the request is ambiguous or has several readings, present them and ask; don't pick silently or invent product behavior. Push back when a simpler approach exists.
+- Define how success will be verified. For multi-step work, state a short plan with a verify check per step.
+
+**Use the first option that fully solves it**
+1. Does it need to exist? Skip speculative features, options, flexibility; state the skipped scope in one line.
+2. Does the codebase already provide it? Reuse helpers, components, types, patterns.
+3. Standard library → 4. native platform feature → 5. already-installed dependency → 6. a clear one-liner.
+7. Otherwise, the minimum complete code. If 200 lines could be 50, rewrite.
+
+**Keep diffs small and surgical**
+- Every changed line traces to the request. No unrelated refactor, rename, or reformat; match surrounding style.
+- No abstractions, wrappers, or config without a concrete current need. DRY only for true duplication.
+- No new dependency for what the platform, stdlib, or existing code already does.
+- Remove only orphans your change created; mention unrelated dead code instead of deleting it.
+- Bugs: write a reproducing test first, fix the shared root cause, not the symptom.
+
+**Never sacrifice correctness for brevity**
+- Validate external input at trust boundaries; keep auth, data-integrity, and security controls.
+- Preserve accessibility and error/loading/empty states; model failure paths explicitly.
+- Add the smallest useful test for nontrivial logic; finish everything the change requires, including callers, fixtures, and tests it breaks.
+
+**Before completion**: run the project's build, lint and tests; check user-visible behavior; report what changed, what was verified, and remaining risks.
+
+## Skills and commits
+
+New here? Read `docs/agents/workflow.md` (how work flows) and `docs/agents/setup.md` (tools and skills to install).
+
+Project skills live in `.agents/skills/` (Claude Code reaches them through symlinks in `.claude/skills/`). Read a skill's `SKILL.md` before the work it covers. For commits use the `commit` skill: atomic Conventional Commits, explicit paths when staging, no secrets, no `--no-verify`, never push or rewrite history unless asked. Commit only when the user asks.

package/templates/blocks/memory.md

@@ -0,0 +1,7 @@
+## Shared memory (Claude Code, Codex, Cursor)
+
+Project memory lives in `.agent-memory/` (committed). At the start of a task read `.agent-memory/MEMORY.md` (short index) and open only the files relevant to the task. When the user asks you to remember something project-related, write it there instead of any tool-private memory:
+
+- One fact per file with frontmatter (`name`, `description`, `metadata.type`: `user` | `feedback` | `project` | `reference`); body for feedback/project ends with **Why:** and **How to apply:**.
+- Add one line to `MEMORY.md` (`- [Title](file.md) — hook`), keep it alphabetical, update an existing file instead of duplicating, delete memories that turn out wrong.
+- This folder is pushed to GitHub: never store secrets, credentials, emails or personal details, and avoid machine-specific paths. Private notes stay in your tool's own memory.

package/templates/blocks/tracking.md

@@ -0,0 +1,11 @@
+## Project tracking and domain docs (Claude Code, Codex, Cursor)
+
+These files in `docs/` start empty and are kept current in **every** session:
+
+- `docs/GLOSSARY.md` — the project's domain language, only terms, no implementation detail. Read it before exploring or naming things; use its terms exactly. Add or sharpen a term the moment it is resolved (the `domain-modeling` skill does this during `grill-with-docs`).
+- `docs/adr/` — architecture decision records, one file per decision, only for decisions that are hard to reverse, surprising without context and a real trade-off. Read the ones touching the area you work in; surface a conflict instead of silently overriding an ADR.
+- `docs/DECISIONS.md` — append every question you ask the user with your recommendation, the user's answer in their own words, and the resulting decision. Do it right after the user answers, before continuing. Append only: a reversal gets a new entry and the old one is marked `Superseded by <id>`.
+- `docs/BACKLOG.md` — features deferred for later. Add an item the moment it is deferred; remove it when work starts.
+- `docs/FEATURES.md` — every feature as Done / In progress / Planned. Update it in the same change that starts or finishes the work.
+
+Keep the repo root clean: new project documents go under `docs/`. How the planning skills find these files: `docs/agents/domain.md`, `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`. The full workflow is in `docs/agents/workflow.md`; machine and tool setup is in `docs/agents/setup.md`.

package/templates/blocks/workers.md

@@ -0,0 +1,3 @@
+## Worker agents
+
+The `orchestrate-workers` skill (`.agents/skills/orchestrate-workers`) runs a ticket set with other agent CLIs (Codex, Cursor, Claude) as workers in a herdr tab, driven with the `hc` CLI. Needs `herdr` and `hc` installed. The roster is `.agents/skills/orchestrate-workers/workers.conf`; confirm it with the user at the start of each session. Issues and specs live as markdown under `.scratch/<feature>/`. How to drive panes with `hc`: `.agents/skills/orchestrate-workers/HC.md`.

package/templates/cursor-cli.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Shell(ls)", "Shell(cat)", "Shell(head)", "Shell(tail)", "Shell(wc)", "Shell(echo)",
+      "Shell(grep)", "Shell(rg)", "Shell(find)", "Shell(sed)", "Shell(diff)",
+      "Shell(npm)", "Shell(npx)", "Shell(node)",
+      "Shell(agent-browser)", "Shell(curl)",
+      "Shell(.agents/skills/verify-ui/run.sh)", "Shell(.agents/skills/verify-ui/probe.sh)",
+      "Mcp(chrome-devtools:*)",
+      "Shell(git status)", "Shell(git diff)", "Shell(git log)", "Shell(git show)"
+    ],
+    "deny": [
+      "Shell(git commit)", "Shell(git push)", "Shell(git reset)", "Shell(git checkout)",
+      "Shell(git stash)", "Shell(git clean)", "Shell(rm -rf)"
+    ]
+  }
+}

package/templates/cursor-rule.mdc

@@ -0,0 +1,6 @@
+---
+description: Shared agent rules (discipline, memory, tracking, skills); see AGENTS.md
+alwaysApply: true
+---
+
+Follow [AGENTS.md](/AGENTS.md): the same rules apply to Claude Code, Codex and Cursor. Project skills are folders in `.agents/skills/`; read a skill's `SKILL.md` before the work it covers.

package/templates/docs/BACKLOG.md

@@ -0,0 +1,4 @@
+# Backlog
+
+Features deferred for later. Add the moment something is deferred; remove when work starts.
+

package/templates/docs/DECISIONS.md

@@ -0,0 +1,4 @@
+# Decisions
+
+Every question asked of the user, the recommendation, the answer in their words, and the decision. Append only; a reversal gets a new entry and the old one is marked `Superseded by <id>`.
+

package/templates/docs/FEATURES.md

@@ -0,0 +1,8 @@
+# Features
+
+## Done
+
+## In progress
+
+## Planned
+

package/templates/docs/GLOSSARY.md

@@ -0,0 +1,3 @@
+# Glossary
+
+The project's domain language. Add a term the moment it is resolved; terms only, no implementation detail. See `docs/agents/domain.md`.