@benjaminthomas/spec-driven-dev 0.0.0-stage → 1.4.0

package/bin/cli.mjs

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+// spec-driven-dev installer: detects your AI coding tools, copies the skills into each one, and
+// runs project discovery (layout, tracker, branches, commands) to write .spec-driven.yml.
+//
+//   npx @benjaminthomas/spec-driven-dev                 install + project setup (interactive)
+//   npx @benjaminthomas/spec-driven-dev setup           project setup only
+//   npx @benjaminthomas/spec-driven-dev doctor          check .spec-driven.yml against the real repos (exit 1 on problems)
+//   npx @benjaminthomas/spec-driven-dev status          list specs with unfinished tasks (used by the session-start hook)
+//   flags: --yes  --global  --tools=claude,cursor  --skills=spec-create,...  --no-setup  --dir=<path>
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const SKILLS_DIR = path.join(ROOT, "skills");
+const HOME = process.env.SPEC_DRIVEN_HOME || os.homedir(); // overridable for tests
+const ALL_SKILLS = fs.readdirSync(SKILLS_DIR).filter((d) => fs.existsSync(path.join(SKILLS_DIR, d, "SKILL.md")));
+
+const TOOLS = {
+  claude: { label: "Claude Code", home: ".claude", bin: "claude", project: ".claude/skills", global: ".claude/skills" },
+  cursor: { label: "Cursor", home: ".cursor", bin: "cursor", project: ".cursor/skills", global: ".cursor/skills" },
+  codex: { label: "Codex CLI", home: ".codex", bin: "codex", project: ".agents/skills", global: ".agents/skills" }, // Codex reads $HOME/.agents/skills
+  antigravity: { label: "Antigravity", home: ".gemini", bin: "antigravity", project: ".agents/skills", global: ".gemini/config/skills" },
+};
+
+// ---------- args & prompts ----------
+const args = process.argv.slice(2);
+const flag = (n) => args.includes(`--${n}`);
+const opt = (n) => args.find((a) => a.startsWith(`--${n}=`))?.split("=")[1];
+const command = args.find((a) => !a.startsWith("-")) || "install";
+const YES = flag("yes") || flag("y") || !process.stdin.isTTY || ["doctor", "status"].includes(command);
+const DIR = path.resolve(opt("dir") || process.cwd());
+
+if (flag("help") || flag("h")) {
+  console.log(fs.readFileSync(fileURLToPath(import.meta.url), "utf8").split("\n").slice(1, 9).join("\n").replace(/^\/\/ ?/gm, ""));
+  process.exit(0);
+}
+
+const rl = YES ? null : createInterface({ input: process.stdin, output: process.stdout });
+async function ask(q, def = "") {
+  if (YES) return def;
+  const a = (await rl.question(`${q}${def ? ` [${def}]` : ""}: `)).trim();
+  return a || def;
+}
+async function pick(q, items, defaults) {
+  items.forEach((it, i) => console.log(`  ${i + 1}. ${it.label}`));
+  const defIdx = items.map((it, i) => (defaults.includes(it.value) ? i + 1 : null)).filter(Boolean).join(",");
+  const a = await ask(`${q} (comma-separated numbers, "all", or "none")`, defIdx || "none");
+  if (a === "all") return items.map((it) => it.value);
+  if (a === "none") return [];
+  return a.split(",").map((n) => items[Number(n.trim()) - 1]?.value).filter(Boolean);
+}
+
+const run = (cmd, argv, cwd) => {
+  try { return execFileSync(cmd, argv, { cwd, stdio: ["ignore", "pipe", "ignore"] }).toString().trim(); } catch { return ""; }
+};
+const onPath = (bin) => !!run(process.platform === "win32" ? "where" : "which", [bin]);
+
+// ---------- install ----------
+async function install() {
+  const detected = Object.keys(TOOLS).filter((t) => fs.existsSync(path.join(HOME, TOOLS[t].home)) || onPath(TOOLS[t].bin));
+  let tools = opt("tools")?.split(",");
+  if (!tools) {
+    console.log("\nWhich AI coding tools should get the skills? (detected ones are pre-selected)");
+    tools = await pick("Tools", Object.entries(TOOLS).map(([value, t]) => ({ value, label: t.label + (detected.includes(value) ? "  ✓ detected" : "") })), detected);
+  }
+  const bad = tools.filter((t) => !TOOLS[t]);
+  if (bad.length) throw new Error(`Unknown tool(s): ${bad.join(", ")} — expected ${Object.keys(TOOLS).join(", ")}`);
+
+  // Claude Code users who already have the plugin would get every skill twice.
+  const plugins = path.join(HOME, ".claude/plugins/installed_plugins.json");
+  if (tools.includes("claude") && !opt("tools") && fs.existsSync(plugins) && fs.readFileSync(plugins, "utf8").includes('"spec-driven-dev@')) {
+    console.log("• Claude Code already has the spec-driven-dev plugin, so it's skipped here (update it with /plugin).");
+    tools = tools.filter((t) => t !== "claude");
+  }
+
+  const global = flag("global") || (!YES && (await ask("Install for this project only, or globally for all projects? (project/global)", "project")) === "global");
+  const skills = opt("skills")?.split(",") || ALL_SKILLS;
+  const unknown = skills.filter((s) => !ALL_SKILLS.includes(s));
+  if (unknown.length) throw new Error(`Unknown skill(s): ${unknown.join(", ")} — expected ${ALL_SKILLS.join(", ")}`);
+
+  const dests = [...new Set(tools.map((t) => (global ? path.join(HOME, TOOLS[t].global) : path.join(DIR, TOOLS[t].project))))];
+  for (const dest of dests) {
+    for (const s of skills) {
+      const to = path.join(dest, s);
+      fs.rmSync(to, { recursive: true, force: true });
+      fs.cpSync(path.join(SKILLS_DIR, s), to, { recursive: true, dereference: true, filter: (f) => !f.endsWith(".DS_Store") });
+    }
+    console.log(`✓ ${skills.length} skills → ${dest}`);
+  }
+  if (!dests.length) console.log("• No tools selected — nothing installed.");
+}
+
+// ---------- discovery ----------
+const MARKERS = ["pnpm-workspace.yaml", "turbo.json", "nx.json", "lerna.json", "go.work"];
+const PKG_DIRS = ["apps", "packages", "services", "libs"];
+const MANIFESTS = ["package.json", "go.mod", "pyproject.toml", "Cargo.toml", "composer.json", "pom.xml"];
+const isRepo = (d) => run("git", ["rev-parse", "--is-inside-work-tree"], d) === "true";
+const readJson = (f) => { try { return JSON.parse(fs.readFileSync(f, "utf8")); } catch { return null; } };
+const subdirs = (d) => { try { return fs.readdirSync(d, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => e.name); } catch { return []; } };
+
+function detectLayout(dir) {
+  if (isRepo(dir)) {
+    const top = run("git", ["rev-parse", "--show-toplevel"], dir);
+    const pkg = readJson(path.join(top, "package.json"));
+    const cargo = fs.existsSync(path.join(top, "Cargo.toml")) && fs.readFileSync(path.join(top, "Cargo.toml"), "utf8").includes("[workspace]");
+    const hasManifest = (rel) => MANIFESTS.some((m) => fs.existsSync(path.join(top, rel, m)));
+    // Prefer the workspace list the repo declares; fall back to conventional folders.
+    // shortcut: only "dir/*", "dir/**" and exact paths are expanded — enough for typical workspace globs.
+    const pnpm = fs.existsSync(path.join(top, "pnpm-workspace.yaml")) ? [...fs.readFileSync(path.join(top, "pnpm-workspace.yaml"), "utf8").matchAll(/^\s*-\s*['"]?([^'"\n#]+?)['"]?\s*$/gm)].map((m) => m[1]) : [];
+    const declared = [...(Array.isArray(pkg?.workspaces) ? pkg.workspaces : pkg?.workspaces?.packages || []), ...pnpm].filter((g) => !g.startsWith("!"));
+    const globs = declared.length ? declared : PKG_DIRS.map((p) => `${p}/*`);
+    const packages = [...new Set(globs.flatMap((g) => {
+      const base = g.replace(/\/\*\*?$/, "");
+      return base === g ? [g.replace(/\/$/, "")] : subdirs(path.join(top, base)).map((n) => `${base}/${n}`);
+    }))].filter(hasManifest);
+    const mono = MARKERS.some((m) => fs.existsSync(path.join(top, m))) || pkg?.workspaces || cargo || packages.length > 1;
+    return { layout: mono ? "monorepo" : "single", root: top, repos: mono ? packages : [] };
+  }
+  // a git worktree has a .git *file*; it belongs to its main repo, so skip it
+  const repos = subdirs(dir).filter((n) => { try { return fs.statSync(path.join(dir, n, ".git")).isDirectory(); } catch { return false; } });
+  return repos.length ? { layout: "multi-repo", root: dir, repos } : { layout: "single", root: dir, repos: [] };
+}
+
+function commandsFor(dir) {
+  const pkg = readJson(path.join(dir, "package.json"));
+  const out = { install: "", lint: "", typecheck: "", test: "", build: "", dev: "" };
+  if (!pkg) return out;
+  const pm = fs.existsSync(path.join(dir, "pnpm-lock.yaml")) ? "pnpm" : fs.existsSync(path.join(dir, "yarn.lock")) ? "yarn" : fs.existsSync(path.join(dir, "bun.lockb")) || fs.existsSync(path.join(dir, "bun.lock")) ? "bun" : "npm";
+  const s = pkg.scripts || {};
+  const name = (...ks) => ks.find((k) => s[k]);
+  const cmd = (k) => (k ? (pm === "npm" && k === "test" ? "npm test" : `${pm} run ${k}`) : "");
+  return { install: `${pm} install`, lint: cmd(name("lint")), typecheck: cmd(name("typecheck", "type-check", "tsc", "check-types")), test: cmd(name("test")), build: cmd(name("build")), dev: cmd(name("dev", "start")) };
+}
+
+function gitFacts(dir) {
+  if (!isRepo(dir)) return null;
+  const def = run("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], dir).replace(/^origin\//, "") || run("git", ["branch", "--show-current"], dir);
+  const branches = run("git", ["for-each-ref", "--sort=-committerdate", "--count=40", "--format=%(refname:short)", "refs/remotes", "refs/heads"], dir).split("\n").filter(Boolean).map((b) => b.replace(/^origin\//, ""));
+  const subjects = run("git", ["log", "-40", "--format=%s"], dir).split("\n").filter(Boolean);
+  const owner = (run("git", ["remote", "get-url", "origin"], dir).match(/[:/]([^/:]+)\/[^/]+?(\.git)?$/) || [])[1] || "";
+  return { def, branches, subjects, owner, integration: ["staging", "develop", "development"].find((b) => branches.includes(b)) || "" };
+}
+
+function infer(facts) {
+  const branches = facts.flatMap((f) => f.branches);
+  const subjects = facts.flatMap((f) => f.subjects);
+  const keys = {};
+  for (const s of [...branches, ...subjects]) for (const m of s.matchAll(/\b([A-Z][A-Z0-9]{1,9})-\d+\b/g)) keys[m[1]] = (keys[m[1]] || 0) + 1;
+  const key = Object.entries(keys).sort((a, b) => b[1] - a[1])[0]?.[0] || "";
+  const ghRefs = subjects.filter((s) => /#\d+/.test(s)).length;
+  const bare = branches.filter((b) => /^[A-Z][A-Z0-9]+-\d+$/.test(b)).length;
+  const work = branches.filter((b) => !["main", "master", "HEAD", "staging", "develop", "development", "pre-prod", "origin"].includes(b)).length || 1;
+  const conv = subjects.filter((s) => /^(feat|fix|chore|docs|refactor|test|perf|build|ci|style)(\(.+\))?!?:/.test(s)).length;
+  const tick = subjects.filter((s) => /^\[?[A-Z][A-Z0-9]+-\d+/.test(s)).length;
+  const n = subjects.length || 1;
+  return {
+    trackerType: key ? "jira" : ghRefs ? "github" : "none",
+    key,
+    branchName: key && bare / work >= 0.3 ? "{ticket}" : key ? "{type}/{ticket}-{slug}" : "{type}/{slug}",
+    commitStyle: conv / n >= 0.5 ? "conventional" : tick / n >= 0.5 ? "ticket" : "freeform",
+    base: facts.filter((f) => f.integration === "staging").length > facts.length / 2 ? "staging" : facts.find((f) => f.integration)?.integration || "default",
+  };
+}
+
+const y = (v) => JSON.stringify(v ?? ""); // JSON strings are valid YAML scalars
+function toYaml(c) {
+  const cmds = (o, pad) => Object.entries(o).map(([k, v]) => `${pad}${k}: ${y(v)}`).join("\n");
+  let out = `# .spec-driven.yml — written by spec-driven-dev setup. Edit freely, or re-run setup.\n# Every spec-* skill reads this first. Field reference: skills/spec-setup/references/config-template.yml\nversion: 1\nlayout: ${c.layout}\n`;
+  if (c.repos.length) {
+    out += "repos:\n" + c.repos.map((r) => {
+      let e = `  - path: ${y(r.path)}\n    role: ${y(r.role)}\n`;
+      if (r.base && r.base !== c.git.base_branch) e += `    git:\n      base_branch: ${y(r.base)}\n      pr_target: ${y(r.base)}\n`;
+      if (r.commands && Object.values(r.commands).some(Boolean)) e += `    commands:\n${cmds(r.commands, "      ")}\n`;
+      return e;
+    }).join("");
+  }
+  out += `tracker:\n  type: ${c.tracker.type}\n  key: ${y(c.tracker.key)}\n  url: ${y(c.tracker.url)}\n`;
+  out += `git:\n${cmds(c.git, "  ")}\n`;
+  out += `commands:\n${cmds(c.commands, "  ")}\n  dev_url: ${y(c.devUrl)}\n`;
+  return out + `specs_dir: ${y(c.specsDir)}\n`;
+}
+
+async function setup() {
+  console.log("\nProject setup — detecting how this project works…");
+  const d = detectLayout(DIR);
+  let repos = d.repos;
+  if (d.layout === "multi-repo") {
+    const owners = {};
+    for (const r of repos) (owners[gitFacts(path.join(d.root, r))?.owner || "?"] ||= []).push(r);
+    const biggest = Object.values(owners).sort((a, b) => b.length - a.length)[0] || [];
+    console.log(`Found ${repos.length} git repos in ${d.root}. Which ones change together as one workspace?`);
+    repos = await pick("Repos", repos.map((r) => ({ value: r, label: `${r}  (${Object.keys(owners).find((o) => owners[o].includes(r))})` })), biggest);
+  }
+  const layout = await ask(`Layout — single, monorepo, or multi-repo (detected: ${d.layout})`, d.layout);
+  const root = d.root;
+  const file = path.join(root, ".spec-driven.yml");
+  if (fs.existsSync(file) && (await ask(`${file} exists — overwrite? (y/n)`, "n")) !== "y") {
+    console.log("• Kept the existing config. Run the spec-setup skill in your AI tool to review it.");
+    return;
+  }
+
+  const repoDirs = layout === "multi-repo" ? repos.map((r) => path.join(root, r)) : [isRepo(root) ? root : DIR];
+  const facts = repoDirs.map(gitFacts).filter(Boolean);
+  const g = infer(facts);
+  if (facts.length) console.log(`Detected: tracker ${g.trackerType}${g.key ? ` (${g.key}-…)` : ""}, base ${g.base}, branches "${g.branchName}", commits ${g.commitStyle}`);
+
+  const trackerType = await ask("Issue tracker (jira/github/linear/none)", g.trackerType);
+  const key = trackerType === "jira" || trackerType === "linear" ? await ask("Ticket key prefix (e.g. STP)", g.key) : "";
+  const url = trackerType === "none" ? "" : await ask("Tracker URL (optional)", "");
+  const base = await ask('Base branch work is cut from ("default" = repo default branch)', g.base);
+  const pr = await ask("Branch PRs target", base);
+  const branchName = await ask("Branch name pattern ({ticket} {slug} {type})", g.branchName);
+  const commitStyle = await ask("Commit style (conventional/ticket/freeform)", g.commitStyle);
+  const specsDir = await ask("Where specs/<feature>/ folders go", "specs");
+
+  const config = {
+    layout, tracker: { type: trackerType, key, url }, specsDir, devUrl: "",
+    git: { remote: "origin", base_branch: base, pr_target: pr, branch_name: branchName, commit_style: commitStyle },
+    commands: layout === "single" ? commandsFor(repoDirs[0]) : commandsFor(root),
+    repos: layout === "single" ? [] : (layout === "multi-repo" ? repos : d.repos).map((r) => {
+      const f = layout === "multi-repo" ? gitFacts(path.join(root, r)) : null;
+      // a repo without an integration branch must say so, or it inherits the top-level base (e.g. staging) it doesn't have
+      return { path: r, role: "", base: f ? f.integration || "default" : "", commands: commandsFor(path.join(root, r)) };
+    }),
+  };
+  fs.writeFileSync(file, toYaml(config));
+  console.log(`✓ Wrote ${file}`);
+  console.log(isRepo(root) ? "  Commit it so your team shares the same rules." : "  This folder isn't a git repo, so the config is personal to this machine.");
+  console.log('  Fill in repo roles, dev_url, and non-Node commands by asking your AI tool to "run spec-setup".');
+}
+
+// ---------- reading the config ----------
+// shortcut: parses the YAML subset setup writes (nested maps, lists of maps, scalars); a full YAML parser if users start hand-writing anchors/flow style.
+function parseYaml(text) {
+  const root = {};
+  const stack = [{ indent: -1, node: root }];
+  const scalar = (v) => {
+    v = v.replace(/\s+#.*$/, "").trim();
+    if (/^".*"$/.test(v)) return JSON.parse(v);
+    if (/^'.*'$/.test(v)) return v.slice(1, -1);
+    return v;
+  };
+  for (const raw of text.split("\n")) {
+    if (!raw.trim() || raw.trim().startsWith("#")) continue;
+    const indent = raw.search(/\S/);
+    let line = raw.trim();
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) stack.pop();
+    let parent = stack[stack.length - 1].node;
+    if (line.startsWith("- ")) {
+      const item = {};
+      parent.push(item);
+      stack.push({ indent, node: item });
+      parent = item;
+      line = line.slice(2);
+    }
+    const m = line.match(/^([\w-]+):\s*(.*)$/);
+    if (!m) continue;
+    const [, key, val] = m;
+    if (val === "") {
+      const next = text.split("\n").slice(text.split("\n").indexOf(raw) + 1).find((l) => l.trim() && !l.trim().startsWith("#"));
+      parent[key] = next && next.trim().startsWith("- ") ? [] : {};
+      stack.push({ indent: line === raw.trim() ? indent : indent + 2, node: parent[key] });
+    } else parent[key] = scalar(val);
+  }
+  return root;
+}
+
+function findConfig(dir) {
+  for (let d = dir; ; d = path.dirname(d)) {
+    const f = path.join(d, ".spec-driven.yml");
+    if (fs.existsSync(f)) return f;
+    if (d === path.dirname(d) || d === HOME) return null;
+  }
+}
+
+function doctor() {
+  const file = findConfig(DIR);
+  if (!file) throw new Error(`No .spec-driven.yml in ${DIR} or above. Run: npx @benjaminthomas/spec-driven-dev setup`);
+  const root = path.dirname(file);
+  let c;
+  try { c = parseYaml(fs.readFileSync(file, "utf8")); } catch (e) { throw new Error(`${file} could not be read: ${e.message}`); }
+  const problems = [], notes = [];
+  if (!["single", "monorepo", "multi-repo"].includes(c.layout)) problems.push(`layout "${c.layout}" must be single, monorepo, or multi-repo`);
+  if (c.tracker && !["jira", "github", "linear", "none"].includes(c.tracker.type)) problems.push(`tracker.type "${c.tracker.type}" must be jira, github, linear, or none`);
+  if (c.git?.commit_style && !["conventional", "ticket", "freeform"].includes(c.git.commit_style)) problems.push(`git.commit_style "${c.git.commit_style}" must be conventional, ticket, or freeform`);
+  if (c.git?.branch_name && !/\{(ticket|slug)\}/.test(c.git.branch_name)) problems.push(`git.branch_name "${c.git.branch_name}" needs {ticket} or {slug}`);
+  const repos = c.layout === "single" ? [{ path: "." }] : Array.isArray(c.repos) ? c.repos : [];
+  if (c.layout !== "single" && !repos.length) problems.push(`layout is ${c.layout} but repos: is empty`);
+  for (const r of repos) {
+    const dir = path.join(root, r.path || "");
+    const label = r.path === "." ? "repo" : r.path;
+    if (!fs.existsSync(dir)) { problems.push(`${label}: folder not found`); continue; }
+    const gitDir = c.layout === "monorepo" ? root : dir;
+    if (c.layout !== "monorepo" && !isRepo(gitDir)) { problems.push(`${label}: not a git repo`); continue; }
+    if (c.layout === "multi-repo" && !r.role) notes.push(`${label}: no role — investigations search better with one`);
+    if (/\(role inferred, verify\)/.test(r.role || "")) notes.push(`${label}: role is still marked "inferred, verify"`);
+    for (const k of ["base_branch", "pr_target"]) {
+      const b = r.git?.[k] || c.git?.[k];
+      if (b && b !== "default" && isRepo(gitDir) && !run("git", ["rev-parse", "--verify", "--quiet", `refs/remotes/${c.git?.remote || "origin"}/${b}`], gitDir) && !run("git", ["rev-parse", "--verify", "--quiet", `refs/heads/${b}`], gitDir))
+        problems.push(`${label}: git.${k} "${b}" doesn't exist (locally or on ${c.git?.remote || "origin"})`);
+    }
+    const pkg = readJson(path.join(dir, "package.json"));
+    const cmds = { ...(c.layout === "single" ? c.commands : {}), ...(r.commands || {}) };
+    for (const [k, v] of Object.entries(cmds)) {
+      const script = typeof v === "string" && v.match(/^(?:npm|pnpm|yarn|bun) run ([\w:.-]+)$/)?.[1];
+      if (script && pkg && !pkg.scripts?.[script]) problems.push(`${label}: commands.${k} runs "${script}", which isn't in package.json scripts`);
+    }
+  }
+  const specs = path.join(root, c.specs_dir || "specs");
+  if (!fs.existsSync(specs)) notes.push(`${c.specs_dir || "specs"}/ doesn't exist yet — created on first spec`);
+  console.log(`Checked ${file}`);
+  for (const n of notes) console.log(`  • ${n}`);
+  for (const p of problems) console.log(`  ✗ ${p}`);
+  if (problems.length) { process.exitCode = 1; console.log(`${problems.length} problem(s). Fix the file, or ask your AI tool to "run spec-setup".`); }
+  else console.log("✓ Config matches the repos.");
+}
+
+// Silent unless something is unfinished, so it costs no context in a session start hook.
+function status() {
+  const file = findConfig(DIR);
+  const root = file ? path.dirname(file) : DIR;
+  const specsName = (file && parseYaml(fs.readFileSync(file, "utf8")).specs_dir) || "specs";
+  const specs = path.join(root, specsName);
+  const lines = [];
+  for (const name of subdirs(specs)) {
+    const readme = path.join(specs, name, "README.md");
+    if (!fs.existsSync(readme)) {
+      if (fs.existsSync(path.join(specs, name, "investigation.md"))) lines.push(`- ${specsName}/${name}: investigated, no spec yet → next: spec-create`);
+      continue;
+    }
+    const t = fs.readFileSync(readme, "utf8");
+    const done = (t.match(/^\s*- \[x\]/gim) || []).length, todo = (t.match(/^\s*- \[ \]/gm) || []).length;
+    if (todo) lines.push(`- ${specsName}/${name}: ${done}/${done + todo} tasks done → next: spec-implement`);
+    else if (done && !fs.existsSync(path.join(specs, name, "verification-report.md"))) lines.push(`- ${specsName}/${name}: all tasks done, not verified → next: spec-verify`);
+  }
+  if (lines.length) console.log(`spec-driven-dev: unfinished work in ${root}\n${lines.join("\n")}`);
+}
+
+try {
+  if (command === "doctor") doctor();
+  else if (command === "status") status();
+  else if (command === "install") {
+    await install();
+    if (!flag("no-setup") && (YES || (await ask("\nSet up this project now? (y/n)", "y")) === "y")) await setup();
+  } else if (command === "setup") await setup();
+  else throw new Error(`Unknown command "${command}" — use install (default), setup, doctor, or status`);
+  if (["install", "setup"].includes(command)) console.log('\nNext: in your AI tool, say "investigate <ticket>" or "create a spec".');
+} catch (e) {
+  console.error(`✗ ${e.message}`);
+  process.exitCode = 1;
+} finally {
+  rl?.close();
+}

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "@benjaminthomas/spec-driven-dev",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.4.0",
+  "description": "Spec-driven AI development workflow (investigate → spec → implement → verify → ship) as Agent Skills for Claude Code, Cursor, Codex CLI and Antigravity.",
+  "type": "module",
+  "bin": { "spec-driven-dev": "bin/cli.mjs" },
+  "files": ["bin", "skills"],
+  "scripts": { "test": "python3 scripts/check.py && node scripts/test-cli.mjs" },
+  "engines": { "node": ">=18" },
+  "keywords": ["agent-skills", "claude-code", "cursor", "codex", "antigravity", "spec-driven-development", "ai-agents"],
+  "repository": { "type": "git", "url": "git+https://github.com/benjaminthomas/spec-driven-dev.git" },
+  "license": "MIT",
+  "publishConfig": { "access": "public" }
+}

package/skills/generative-seo/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: generative-seo
+description: Run an evidence-based SEO + GEO (Generative Engine Optimization) program for ANY website or product codebase — auditing technical SEO, writing or retrofitting content so it gets cited by ChatGPT/Perplexity/AI Overviews, tracking AI-citation visibility, refreshing competitor research, and drafting distribution posts. Use whenever the user asks to audit SEO, improve AI-search/AI-citation visibility, write or optimize marketing/blog content for search or GEO, check whether a product shows up in ChatGPT/Perplexity answers, do competitor/keyword research, or wants a monthly SEO performance report — regardless of framework (Next.js, Astro, Remix, plain HTML, WordPress, etc.) or what the product is. Works on any repo; it interviews you once to learn the project's specifics (brand, domain, framework, docs location) and remembers the answers.
+license: MIT
+---
+
+# Generative SEO (GEO) Operations
+
+Runs an SEO + GEO program the same way a sharp in-house SEO operator would: technical
+audits, answer-first content built to be quoted by AI engines, an AI-citation tracker,
+competitor watch, and (draft-only) distribution. It is deliberately generic — first use
+in a repo spends a few minutes learning that project's facts, then behaves like a
+project-specific skill from then on.
+
+**Mode selection:** the argument names the mode (`content`, `audit`, `optimize`,
+`competitors`, `citations`, `report`, `social`). No argument → read the project's docs
+(below), summarize current state, and recommend the highest-impact next action.
+
+For the full evidence behind every rule below (which studies, what they found, why
+each technique works) and the complete technical checklist, see
+`references/geo-methodology.md`. Read it before an `audit` or before writing a
+first piece of `content` in a new project; skip re-reading it on later runs in the
+same project.
+
+---
+
+## First run in a project: learn the project
+
+Look for a config file at `docs/seo/geo-config.md` (or wherever the user says their
+SEO docs live — some repos keep them in `content/`, `marketing/`, or a wiki instead).
+If it exists, read it and skip to **Read these first**.
+
+If it does not exist, this is the first run — ask the user (batch these, don't
+interview one question at a time):
+
+1. **Product/brand name(s)** — and critically, if the product is a sub-brand of a
+   parent company or a different name than the company that builds it, get that
+   distinction explicit now (e.g. "Acme Corp is the company; Acme Flow is the
+   product we're marketing" or "same name, no distinction needed"). Getting this
+   wrong (writing "is Acme Corp free?" when the product is Acme Flow) is a
+   real, recurring mistake — nail it once here instead of guessing per-page later.
+2. **Primary domain** the content lives on (affects sitemap/robots checks and
+   internal-link audits).
+3. **Framework** — Next.js, Astro, Remix, SvelteKit, plain static HTML, a CMS
+   (WordPress/Webflow/etc.), or something else. This determines where
+   sitemap/robots/metadata/JSON-LD live (see `references/geo-methodology.md` for
+   the per-framework map) — if unsure, look at the repo yourself first
+   (`package.json`, top-level config files) before asking.
+4. **Where marketing/content pages live** in the repo (a directory, a headless
+   CMS, or "not in this repo" if content is managed elsewhere).
+5. **Existing design system doc**, if any (a `DESIGN.md`, a Storybook, a Figma
+   library) — new/edited pages should match it rather than invent a new look.
+6. **How to source real statistics** for content — product analytics the user can
+   query, a public dataset, or "external sources only." Never invent numbers
+   regardless of the answer.
+7. **Docs folder** for this skill's own working files (default: `docs/seo/` at
+   repo root — offer this default rather than making the user think of one).
+
+Write the answers to `<docs_dir>/geo-config.md` using
+`assets/geo-config-template.md` as the shape. Then create the four working docs
+from their templates in `assets/` (only the ones missing — never overwrite an
+existing one):
+
+| File | Template | Purpose |
+|---|---|---|
+| `<docs_dir>/geo-playbook.md` | `assets/geo-playbook-template.md` | This project's evidence-based rules + house style, filled in from the config answers |
+| `<docs_dir>/content-plan.md` | `assets/content-plan-template.md` | The execution backlog with statuses |
+| `<docs_dir>/competitor-analysis.md` | `assets/competitor-analysis-template.md` | Competitor landscape + keyword gaps |
+| `<docs_dir>/citation-log.md` | `assets/citation-log-template.md` | Dated AI-citation audit history |
+
+For `citations` mode specifically, also derive a **fixed prompt set**: 10–15
+realistic queries someone would type into ChatGPT/Perplexity/Google when looking
+for a product like this one (category term, "best X for Y" roundups, problem-first
+questions, a couple of named-competitor-alternative queries). Save them into
+`<docs_dir>/citation-log.md`'s header. Keep this list stable run-over-run — append
+new queries, don't rewrite the set, or trend comparison breaks.
+
+## Read these first (source of truth — keep them updated every run)
+
+- `<docs_dir>/geo-config.md` — project facts (brand, domain, framework, paths)
+- `<docs_dir>/geo-playbook.md` — this project's rules, filled in from the methodology reference
+- `<docs_dir>/content-plan.md` — phased content queue with statuses
+- `<docs_dir>/competitor-analysis.md` — competitor landscape + keyword gap map
+- `<docs_dir>/citation-log.md` — AI-citation audit history + the fixed prompt set
+
+---
+
+## Non-negotiable content rules (every page you write or edit)
+
+Full evidence (Princeton GEO paper, Ahrefs citation studies) in
+`references/geo-methodology.md`. Summary:
+
+1. **Answer-first**: the complete, direct answer to the target query lands in the
+   first ~200 words. Most AI citations pull from early-page content.
+2. **≥3 statistics, ≥1 quotable expert-voice line, cited sources** per substantive
+   page — measurably lifts AI-citation odds. Stats must be real and sourced (see
+   the project's config for where "real" comes from) — never invented.
+3. **Extractable structure**: H2/H3s phrased as the questions people actually ask;
+   Q&A blocks; comparison tables; a TL;DR/summary box; definition-style openings
+   ("X is …").
+4. **Self-contained sections**: every H2 section should make sense quoted in
+   isolation — AI retrieval is passage-level, not whole-page.
+5. **Author + published date + last-updated date** visible on-page. Refresh
+   anything older than ~6 months.
+6. **FAQ block + `FAQPage` JSON-LD** on pricing, feature, and comparison pages.
+7. Tone: practitioner-credible, specific, first-hand. No filler, never keyword-stuff.
+8. Word count follows the query's actual answer depth — never pad, never ship a
+   page so thin it can't stand on its own (a rough floor: ~300 words).
+9. Follow the naming/brand distinction captured in `geo-config.md` on every page —
+   re-check it before publishing if the page discusses "who makes this."
+10. Match whatever design system this repo already has (`geo-config.md` points at
+    it) — a GEO-optimized page that looks out of place hurts more than it helps.
+
+---
+
+## Mode: `audit` — technical SEO + GEO audit (add `--fix` to also apply fixes)
+
+Audit BOTH the codebase and the live site (fetch the live URLs — deployed state
+drifts from the repo). Report every failure with file:line. With `--fix`, apply
+code-level fixes and run the project's own check commands (lint/typecheck —
+inspect `package.json` scripts or the repo's build tooling; skip anything that
+doesn't exist rather than assuming `npm run check`).
+
+Full checklist (sitemap/robots by framework, JSON-LD schema types, AI-crawler
+allowlist, `llms.txt`, heading hygiene, internal linking, Core Web Vitals sanity)
+is in `references/geo-methodology.md` — pull it up for this mode.
+
+**Output:** severity-ordered findings table (blocker / high / med / low), each
+with file:line and the fix. With `--fix`: apply, verify with the project's checks,
+summarize the diff.
+
+## Mode: `content` — write the next content piece
+
+1. Read `<docs_dir>/content-plan.md`; pick the first `todo` item in the current
+   phase (or the item the user names). Flag any unresolved blockers first.
+2. Check the target query's live SERP (web search) — confirm intent, note what
+   ranks, find a differentiating angle grounded in what this specific product
+   actually does differently (pull that from `geo-config.md` / the codebase, not
+   assumption).
+3. Write the piece following the non-negotiable rules above. Comparison pages
+   must be honest about competitors — credibility is the citation currency.
+4. Implement it wherever this repo's content actually lives (per `geo-config.md`
+   — a route file, a CMS entry, a markdown collection) with full metadata,
+   JSON-LD, and design-system compliance.
+5. Add the URL to the project's sitemap mechanism. Update the item's status in
+   `content-plan.md` to `shipped (YYYY-MM-DD)`.
+6. Run the project's lint/typecheck/build if it has them. Present the draft for
+   review — content is outward-facing; the user approves before it goes live.
+7. AFTER the page is deployed and live, if the project has an IndexNow/Bing-ping
+   mechanism, use it (shortens AI-engine discovery from days to hours). If it
+   doesn't, mention manual IndexNow submission (bing.com/indexnow) as an option
+   rather than inventing tooling. Never ping before deploy.
+
+## Mode: `optimize` — GEO-retrofit an existing page
+
+Given a URL/path: score it against the non-negotiable rules (answer-first? stats?
+extractable structure? dates? FAQ? schema?), report a before/after checklist, then
+apply improvements preserving the page's voice and design.
+
+## Mode: `competitors` — refresh competitor & keyword research
+
+1. Re-run research (web search) covering the players already in
+   `competitor-analysis.md`, plus new AI-native entrants in the same category.
+2. Check whether the product's category term has a new canonical answer in
+   search; check who's cited in relevant "best X" roundups.
+3. Diff against the existing doc: new entrants, keyword-gap changes, threats.
+   Append a dated changelog entry — don't remove existing queue items. Suggest
+   content-plan additions.
+   Cadence: quarterly, or whenever the user senses a new competitor.
+
+## Mode: `citations` — AI-visibility audit
+
+1. Run the fixed prompt set from `citation-log.md` through web search (captures
+   Google/AI-Overview signals) and check Bing presence for the same queries.
+   Direct ChatGPT/Perplexity querying usually isn't possible from here — log
+   what's checkable and list the 5-minute manual checks for the user with exact
+   prompts to paste.
+2. For each query: record who ranks / is cited, whether this product appears
+   (distinguish **mention** vs **citation**), and which of the project's own
+   pages should be winning it.
+3. Append a dated entry to `citation-log.md`. Report the trend vs. the previous
+   entry.
+
+## Mode: `report` — periodic performance summary
+
+Compile from: citation-log trend, content-plan ship rate, live-site spot checks,
+and (if the user provides Search Console/Bing/GA exports — ask, don't assume
+access) impressions/clicks on target queries. Output: what shipped, what moved,
+top 3 recommended actions for next period. Set realistic expectations: Google
+traction is typically months out from a content ship; Bing/Perplexity move faster
+(weeks).
+
+## Mode: `social` — draft distribution posts for shipped content (drafts ONLY)
+
+This mode never posts anywhere — automated posting risks ToS violations on
+LinkedIn/Reddit/etc. and the account behind it. Output goes to
+`<docs_dir>/social-queue.md` (create from `assets/social-queue-template.md` on
+first run); the user reviews, pastes, and marks items posted.
+
+1. Read `social-queue.md` and `content-plan.md`. Pick shipped pages with no queue
+   entry yet — or the page the user names. Newest first, max 3 pages per run.
+2. For each page draft, in the founder/team's actual voice (first person,
+   practitioner tone, one concrete stat or claim pulled from the page, minimal
+   hashtags, ends with a question or the link — never reads like a press
+   release):
+   - A personal-profile post for whatever the primary channel is (ask if
+     unclear — LinkedIn and X are common defaults).
+   - A shorter, product-forward version for a company/brand page, if one exists.
+   - If the piece is worth republishing elsewhere (e.g. Medium), a checklist
+     entry noting the platform's canonical-URL mechanism must be used — never
+     copy-paste in a way that loses canonical attribution.
+   - Community threads (Reddit-style forums, Hacker News, niche Slack/Discord
+     communities): only where the skill has search budget to find 1–3 live
+     threads the page genuinely answers; draft a value-first reply that stands
+     on its own without the link, flagged for the user to post manually, in
+     their own voice. Never suggest posting the identical comment in 2 places.
+3. Append drafts under a dated heading, one entry per page, with a status marker
+   the user flips (`[ ] queued` → `[x] posted YYYY-MM-DD <URL>` or `[-]
+   skipped`). Never overwrite prior entries.
+4. Report what was drafted and what's still unposted from previous runs — an
+   aging queue means distribution, not content, is the bottleneck.
+
+---
+
+## Automation (scheduled agents)
+
+If the harness supports scheduled/cron-style agent runs, these are reasonable
+cadences — set them up only if the user asks, never silently:
+
+| Routine | Cadence | Action |
+|---|---|---|
+| Content | Weekly | Pick the next queue item, open a PR (never push straight to main) |
+| Citation audit | Monthly | Update the citation log on a branch |
+| Technical audit | Monthly | File findings as a report; PR fixes only for blockers |
+| Competitor refresh | Quarterly | Refresh competitor-analysis.md |
+| Social drafts | Weekly | Draft posts for newly-shipped pages |
+
+Scheduled runs always work on a branch + PR — content is outward-facing and needs
+human review before going live. If a run hits an unresolved blocker, report
+rather than plow ahead. Never invent statistics, in scheduled or interactive runs.
+
+## Standing cautions
+
+- A subdomain is a separate site for authority purposes — don't split content
+  onto a subdomain without a deliberate reason; it usually just dilutes signal.
+- Programmatic/templated pages need real data depth per page — thin
+  variable-injection pages risk scaled-content-abuse penalties for the whole
+  domain.
+- `llms.txt` and schema markup are hygiene, not strategy — don't over-invest
+  expecting them alone to move AI-citation odds. The actual lever is answer-first
+  content + real stats + third-party mentions (roundups, directories, forums,
+  YouTube) + fast indexing (Bing/IndexNow).
+- Anything gated behind a login the skill can't access (Search Console, Bing
+  Webmaster Tools, review-site dashboards, social platforms) → give the user a
+  precise action list; don't fake having checked it.

package/skills/generative-seo/assets/citation-log-template.md

@@ -0,0 +1,17 @@
+# AI Citation Log
+
+## Fixed prompt set
+
+<!--
+10-15 queries a real prospect would type into ChatGPT / Perplexity / Google
+when looking for a product like this one. Derived once on first `citations`
+run, kept stable so trend comparisons mean something — append, don't rewrite.
+-->
+
+- 
+
+## Audit history
+
+| Date | Prompt | Engine | Our status (mention/citation/absent) | Who wins | Note |
+|---|---|---|---|---|---|
+| | | | | | |