@davidbalzan/groundwork 0.3.1

package/src/commands/doctor.mjs

@@ -0,0 +1,292 @@
+import fs from "node:fs";
+import path from "node:path";
+import { TARGET, PKG_ROOT } from "../lib/paths.mjs";
+import { exists, readText, walk, listDirs } from "../lib/fs.mjs";
+import { countCheckboxes, progressBar } from "../lib/progress.mjs";
+import { ARTIFACTS } from "../lib/artifacts.mjs";
+import { log, bold, green, yellow, dim, cyan } from "../lib/log.mjs";
+import { adrTripwire } from "../lib/adr-tripwire.mjs";
+import { parseFactsDoc, parseWorkDoc, workDocIssues, workDocLegacyWriteIssues } from "@davidbalzan/groundwork-seam";
+
+/**
+ * `groundwork doctor` — flag drift between the docs and reality. Offline + deterministic.
+ * `--json` emits { checks: [{check, level, items[]}], ok } for kit-console.
+ */
+export function collectDoctor(targetDir) {
+  const root = path.resolve(targetDir || ".");
+  const docs = path.join(root, TARGET.docs);
+  if (!exists(docs)) {
+    return {
+      ok: false,
+      exit: 1,
+      error: "No docs/ here. Run `groundwork init` first.",
+      checks: [],
+    };
+  }
+
+  const checks = [];
+  const push = (check, level, items) => checks.push({ check, level, items });
+  const mdFiles = [...walk(docs)].filter((f) => f.endsWith(".md"));
+
+  const valid = validLinkTargets(docs, mdFiles);
+  const orphanItems = [];
+  const seen = new Set();
+  for (const rel of mdFiles) {
+    const text = readText(path.join(docs, rel));
+    for (const target of wikilinks(text)) {
+      if (resolves(target, valid)) continue;
+      const key = `${rel}::${target.toLowerCase()}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      orphanItems.push(`${rel}: [[${target}]] → no such doc`);
+    }
+  }
+  push("orphan-wikilinks", orphanItems.length ? "warn" : "ok", orphanItems.length ? orphanItems : ["all wikilinks resolve"]);
+
+  const phaseDir = path.join(docs, "phases");
+  const phaseItems = [];
+  let phaseWarn = false;
+  if (exists(phaseDir)) {
+    for (const rel of walk(phaseDir)) {
+      if (!/PHASE.*TASKS\.md$/i.test(rel)) continue;
+      const { done, total } = countCheckboxes(readText(path.join(phaseDir, rel)));
+      const pct = total ? Math.round((done / total) * 100) : 0;
+      const label = rel.split(path.sep)[0];
+      const line = `${label}  ${progressBar(pct)} ${pct}% (${done}/${total})`;
+      if (total > 0 && done === total) {
+        phaseWarn = true;
+        phaseItems.push(`${line} — 100% done; mark it complete in the roadmap & record it in DONE.md`);
+      } else phaseItems.push(line);
+    }
+  }
+  if (!phaseItems.length) push("phase-progress", "ok", ["no phase task files yet (run /plan-phase)"]);
+  else push("phase-progress", phaseWarn ? "warn" : "ok", phaseItems);
+
+  const coverageItems = [];
+  if (exists(phaseDir)) {
+    for (const dir of listDirs(phaseDir)) {
+      if (!/^phase\d+/i.test(dir)) continue;
+      const files = fs.readdirSync(path.join(phaseDir, dir));
+      const hasTasks = files.some((f) => /PHASE.*TASKS\.md$/i.test(f));
+      const hasReadme = files.some((f) => /^README.md$/i.test(f));
+      if (!hasTasks) coverageItems.push(`${dir}: no PHASE*_TASKS.md — run /plan-phase`);
+      else if (!hasReadme) coverageItems.push(`${dir}: tasks present but no README.md`);
+    }
+  }
+  const prd = mdFiles.find((f) => /(^|\/)PRD(_.*)?\.md$/i.test(f));
+  if (prd) {
+    const t = readText(path.join(docs, prd)).toLowerCase();
+    const need = [
+      ["problem", /problem/],
+      ["goals", /goals?/],
+      ["non-goals / out of scope", /non-goals|out of scope/],
+      ["functional requirements", /functional requirements|requirements/],
+      ["success metrics", /success metrics|kpi|success criteria/],
+      ["risks", /risks?/],
+    ];
+    const missing = need.filter(([, re]) => !re.test(t)).map(([n]) => n);
+    if (missing.length) coverageItems.push(`PRD missing section(s): ${missing.join(", ")}`);
+  } else coverageItems.push("no PRD yet (run /create-prd)");
+  const coverageInfoOnly = coverageItems.length === 1 && coverageItems[0].startsWith("no PRD");
+  if (!coverageItems.length) push("spec-coverage", "ok", ["phase structure + PRD sections look complete"]);
+  else push("spec-coverage", coverageInfoOnly ? "info" : "warn", coverageItems);
+
+  const marker = path.join(docs, ".groundwork", "VERSION");
+  const cliV = pkgVersion();
+  if (exists(marker)) {
+    const got = readText(marker).trim();
+    if (cmpVer(got, cliV) < 0)
+      push("version-marker", "warn", [`installed v${got}, CLI is v${cliV} — run \`groundwork update --all --docs\``]);
+    else push("version-marker", "ok", [`up to date (v${got})`]);
+  } else push("version-marker", "warn", ["no VERSION marker — re-run `groundwork init`/`update`"]);
+
+  const sm = path.join(docs, "STACK_MAP.md");
+  if (exists(sm)) {
+    const m = readText(sm).match(/Last audited[^\d]*(\d{4})-(\d{2})-(\d{2})/);
+    if (!m) push("stack-map-freshness", "warn", ["STACK_MAP has no `Last audited` date — run `/check-versions`"]);
+    else {
+      const days = daysSince(+m[1], +m[2], +m[3]);
+      if (days > 90) push("stack-map-freshness", "warn", [`STACK_MAP last audited ${days} days ago — run \`/check-versions\``]);
+      else push("stack-map-freshness", "ok", [`STACK_MAP audited ${days} days ago`]);
+    }
+  } else push("stack-map-freshness", "info", ["no STACK_MAP.md yet (run /kickstart)"]);
+
+  const wsFile = path.join(docs, "WORKSTREAMS.md");
+  if (exists(wsFile)) {
+    const wsDoc = parseWorkDoc(readText(wsFile));
+    const wsIssues = [...workDocIssues(wsDoc), ...workDocLegacyWriteIssues(wsDoc)];
+    if (wsIssues.length) push("workstreams", "warn", wsIssues);
+    else push("workstreams", "ok", ["write grammar is workstreams.v1"]);
+  } else push("workstreams", "info", ["no WORKSTREAMS.md yet (run `groundwork update --docs`)"]);
+
+  const factsFile = path.join(docs, "FACTS.md");
+  if (exists(factsFile)) {
+    const { entries, issues } = parseFactsDoc(readText(factsFile));
+    if (issues.length) push("facts-freshness", "warn", issues);
+    else
+      push(
+        "facts-freshness",
+        "ok",
+        [entries.length ? `${entries.length} fact(s), all verified and fresh` : "no facts recorded yet"],
+      );
+  } else push("facts-freshness", "info", ["no FACTS.md yet (run `groundwork update --docs`)"]);
+
+  const decisions = path.join(docs, "DECISIONS.md");
+  if (exists(decisions)) {
+    const acceptedIds = new Set();
+    if (exists(factsFile))
+      for (const m of readText(factsFile).matchAll(/^- `(adr-\d+-accepted-deviation)` — /gm)) acceptedIds.add(m[1]);
+    const hits = adrTripwire({ decisionsText: readText(decisions), root, acceptedFactIds: acceptedIds });
+    const byAdr = new Map();
+    for (const h of hits) (byAdr.get(h.adr) || byAdr.set(h.adr, []).get(h.adr)).push(h);
+    const adrItems = [];
+    for (const [adr, hs] of byAdr) {
+      const seenTok = new Set();
+      const uniq = hs.filter((h) => !seenTok.has(h.token) && seenTok.add(h.token));
+      const shown = uniq.slice(0, 3).map((h) => `\`${h.token}\` (${h.kind}: ${h.where}) ← "${h.alternative}"`);
+      const ev = shown.join("; ") + (uniq.length > 3 ? `; +${uniq.length - 3} more` : "");
+      adrItems.push(
+        `${adr} "${hs[0].title}" is Accepted but the tree contains its rejected alternative: ${ev} — supersede the ADR, or record fact \`${adr.toLowerCase()}-accepted-deviation\``,
+      );
+    }
+    if (adrItems.length) push("adr-tripwire", "warn", adrItems);
+    else push("adr-tripwire", "ok", ["no Accepted ADR contradicted by dependencies/paths"]);
+  } else push("adr-tripwire", "info", ["no DECISIONS.md yet (run /kickstart)"]);
+
+  const warnCount = checks.filter((c) => c.level === "warn").length;
+  return { ok: warnCount === 0, exit: warnCount === 0 ? 0 : 1, checks };
+}
+
+export function doctor(targetDir, opts = {}) {
+  const report = collectDoctor(targetDir);
+  if (opts.json) {
+    console.log(JSON.stringify(report, null, 2));
+    process.exitCode = report.exit;
+    return;
+  }
+  if (report.error) {
+    log.warn(report.error);
+    process.exitCode = 1;
+    return;
+  }
+  const titles = {
+    "orphan-wikilinks": "Wikilinks",
+    "phase-progress": "Phase progress",
+    "spec-coverage": "Spec coverage",
+    "version-marker": "Version",
+    "stack-map-freshness": "Versions audit",
+    workstreams: "Workstreams",
+    "facts-freshness": "Facts",
+    "adr-tripwire": "ADR tripwire",
+  };
+  for (const c of report.checks) {
+    log.heading(titles[c.check] ?? c.check);
+    for (const item of c.items) {
+      if (c.level === "warn") console.log(`  ${yellow("⚠")} ${item}`);
+      else if (c.level === "info") log.info(dim(`  ${item}`));
+      else if (c.check === "phase-progress" && item !== "no phase task files yet (run /plan-phase)")
+        console.log(`  ${dim("·")} ${item}`);
+      else console.log(`  ${green("✓")} ${item}`);
+    }
+  }
+  log.heading("Summary");
+  if (report.ok) log.ok("No drift detected — docs match reality.");
+  else console.log(`  ${yellow(String(report.checks.filter((c) => c.level === "warn").length))} issue(s) to look at.`);
+  process.exitCode = report.exit;
+  console.log(dim("  (offline checks; run `/check-versions` for dependency freshness)"));
+}
+
+// ---------- helpers ----------
+function wikilinks(text) {
+  const out = [];
+  for (const m of text.matchAll(/\[\[([^\]]+)\]\]/g)) {
+    let t = m[1].split("|")[0].split("#")[0].trim(); // strip alias + heading
+    if (!t) continue; // intra-doc heading link
+    out.push(t);
+  }
+  return out;
+}
+
+function validLinkTargets(docs, mdFiles) {
+  const set = new Set();
+  const add = (s) => set.add(s.toLowerCase());
+  // existing docs (basename + relative path, both without .md) + their frontmatter aliases
+  // (Obsidian resolves [[link]] by filename OR by a note's declared alias)
+  for (const rel of mdFiles) {
+    const noExt = rel.replace(/\.md$/, "").split(path.sep).join("/");
+    add(noExt);
+    add(noExt.split("/").pop());
+    for (const alias of frontmatterAliases(readText(path.join(docs, rel)))) add(alias);
+  }
+  // expected artifacts from the manifest (so links to not-yet-generated docs aren't flagged)
+  for (const a of ARTIFACTS) {
+    const base = a.path
+      .replace(/^docs\//, "")
+      .replace(/\s*\(.*\)\s*/g, "") // drop "(+ CONTEXT-MAP.md)"
+      .replace(/\.md$/, "")
+      .replace(/\/$/, "");
+    if (base) {
+      add(base);
+      add(base.split("/").pop());
+    }
+  }
+  // extra known names + phase placeholders handled in resolves()
+  ["context-map", "phasen_tasks", "task_template", "prd"].forEach(add);
+  return set;
+}
+
+/** Extract `aliases:` from a doc's YAML frontmatter (inline `[a, b]` or block `- a` form). */
+function frontmatterAliases(text) {
+  const fm = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return [];
+  const body = fm[1];
+  const out = [];
+  const inline = body.match(/^aliases:\s*\[([^\]]*)\]/m);
+  if (inline) {
+    for (const t of inline[1].split(",")) {
+      const v = t.trim().replace(/^["']|["']$/g, "");
+      if (v) out.push(v);
+    }
+  } else {
+    const lines = body.split("\n");
+    const i = lines.findIndex((l) => /^aliases:\s*$/.test(l));
+    if (i >= 0) {
+      for (let j = i + 1; j < lines.length; j++) {
+        const m = lines[j].match(/^\s*-\s*(.+)$/);
+        if (!m) break;
+        out.push(m[1].trim().replace(/^["']|["']$/g, ""));
+      }
+    }
+  }
+  return out;
+}
+
+function resolves(target, valid) {
+  let t = target.replace(/^\.\//, "").replace(/\.md$/, "").toLowerCase();
+  const base = t.split("/").pop();
+  if (valid.has(t) || valid.has(base)) return true;
+  if (/phase\d+/.test(base) || /^phases?\//.test(t)) return true; // phase refs
+  if (/_template$|template$/.test(base)) return true;
+  return false;
+}
+
+function pkgVersion() {
+  try {
+    return JSON.parse(readText(path.join(PKG_ROOT, "package.json"))).version;
+  } catch {
+    return "0.0.0";
+  }
+}
+function cmpVer(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+  }
+  return 0;
+}
+function daysSince(y, mo, d) {
+  const then = new Date(y, mo - 1, d).getTime();
+  return Math.floor((Date.now() - then) / 86400000);
+}

package/src/commands/init.mjs

@@ -0,0 +1,147 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  PAYLOAD_SKILLS,
+  PAYLOAD_DOCS,
+  PAYLOAD_SCRIPTS,
+  TARGET,
+  MINIMAL_SKILLS,
+} from "../lib/paths.mjs";
+import { copyFileSafe, walk, exists } from "../lib/fs.mjs";
+import { loadSkills, mirrorFiles } from "../lib/skills.mjs";
+import { writeArtifacts } from "./artifacts.mjs";
+import { log, bold, cyan, dim } from "../lib/log.mjs";
+
+/** Docs that are about Groundwork-the-product, not a per-project doc. */
+const DOC_EXCLUDE = new Set(["README.md"]);
+
+export function init(targetDir, flags) {
+  const root = path.resolve(targetDir || ".");
+  const minimal = flags.minimal;
+  const force = flags.force;
+  const only = minimal ? MINIMAL_SKILLS : null;
+
+  if (!exists(root)) {
+    log.err(`Target folder not found: ${root}`);
+    log.info(
+      dim(
+        "  init installs into an existing repo — it won't create the target. " +
+          "Check the path, or `mkdir` it first (a missing folder usually means a typo or wrong directory)."
+      )
+    );
+    process.exitCode = 1;
+    return;
+  }
+  log.heading(`Installing Groundwork → ${cyan(root)}`);
+  if (minimal) log.info(dim(`  (minimal: ${MINIMAL_SKILLS.join(", ")})`));
+
+  const counts = { added: 0, skipped: 0 };
+  const bump = (r) => counts[r]++;
+
+  // 1. Skills → .claude/skills
+  log.step("Skills");
+  const skillNames = (only || allSkillNames()).filter(skillExists);
+  for (const name of skillNames) {
+    const src = path.join(PAYLOAD_SKILLS, name, "SKILL.md");
+    const dest = path.join(root, TARGET.skills, name, "SKILL.md");
+    const r = copyFileSafe(src, dest, { force });
+    bump(r);
+    r === "added" ? log.added(`${TARGET.skills}/${name}/SKILL.md`) : null;
+  }
+
+  // 2. Generated IDE mirrors → .cursor/commands + .vscode/prompts
+  log.step("IDE mirrors (Cursor + VS Code, generated from skills)");
+  const skills = loadSkills(only);
+  for (const f of mirrorFiles(skills, {
+    cursorDir: path.join(root, TARGET.cursor),
+    vscodeDir: path.join(root, TARGET.vscode),
+  })) {
+    if (exists(f.rel) && !force) {
+      bump("skipped");
+      continue;
+    }
+    fs.mkdirSync(path.dirname(f.rel), { recursive: true });
+    fs.writeFileSync(f.rel, f.content);
+    bump("added");
+  }
+  log.info(dim(`  ${skills.length} skills × 2 mirrors`));
+
+  // 3. Doc scaffolding → docs/
+  log.step("Docs (methodology, templates, phases, WORKSTREAMS)");
+  for (const rel of walk(PAYLOAD_DOCS)) {
+    if (DOC_EXCLUDE.has(rel)) continue;
+    const r = copyFileSafe(
+      path.join(PAYLOAD_DOCS, rel),
+      path.join(root, TARGET.docs, rel),
+      { force }
+    );
+    bump(r);
+  }
+  // ARTIFACTS.md is generated from the manifest (single source), not copied.
+  if (!exists(path.join(root, TARGET.docs, "ARTIFACTS.md")) || force) {
+    writeArtifacts(root);
+    bump("added");
+  } else bump("skipped");
+
+  // 4. Helper scripts → docs/.groundwork/scripts
+  if (exists(PAYLOAD_SCRIPTS)) {
+    log.step("Helper scripts");
+    for (const rel of walk(PAYLOAD_SCRIPTS)) {
+      const r = copyFileSafe(
+        path.join(PAYLOAD_SCRIPTS, rel),
+        path.join(root, TARGET.scripts, rel),
+        { force }
+      );
+      bump(r);
+    }
+  }
+
+  // 5. Stamp version marker
+  const marker = path.join(root, TARGET.docs, ".groundwork", "VERSION");
+  if (!exists(marker) || force) {
+    fs.mkdirSync(path.dirname(marker), { recursive: true });
+    fs.writeFileSync(marker, readPkgVersion() + "\n");
+  }
+
+  log.heading("Done");
+  log.ok(`${counts.added} files written, ${counts.skipped} skipped (already present)`);
+  console.log(
+    [
+      "",
+      bold("Next steps:"),
+      `  1. Open this repo in Claude Code / Cursor / VS Code`,
+      `  2. Run ${cyan('/create-prd "<your idea>"')} FIRST — define the product (problem, scope, goals)`,
+      `  3. Run ${cyan("/kickstart")} — scaffolds tech stack / architecture / roadmap / phases FROM the PRD`,
+      `  4. Then ${cyan("/check-versions")} → ${cyan("/plan-phase 1 <name>")} → ${cyan("/start-session")}`,
+      dim(`  (unsure where you are at any point? run ${cyan("/next")})`),
+      counts.skipped
+        ? dim(`\n  Re-run with --force to overwrite the ${counts.skipped} skipped files.`)
+        : "",
+    ]
+      .filter(Boolean)
+      .join("\n")
+  );
+}
+
+function allSkillNames() {
+  return walkSkillNames();
+}
+function walkSkillNames() {
+  return fs
+    .readdirSync(PAYLOAD_SKILLS, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+}
+function skillExists(name) {
+  return exists(path.join(PAYLOAD_SKILLS, name, "SKILL.md"));
+}
+function readPkgVersion() {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(new URL("../../package.json", import.meta.url), "utf8")
+    );
+    return pkg.version;
+  } catch {
+    return "0.0.0";
+  }
+}

package/src/commands/knowledge.mjs

@@ -0,0 +1,148 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { writeConfig, resolveKnowledgePath, configFile } from "../lib/config.mjs";
+import { log, bold, cyan, dim, green } from "../lib/log.mjs";
+
+/**
+ * `groundwork knowledge <init|link|path>` — configure THIS user's central
+ * ADR/lessons repo. The location is per-user (varies by user); the `remember`
+ * `remember` skill resolves it via $GROUNDWORK_KNOWLEDGE or the saved config.
+ */
+export function knowledge(sub, arg, flags = {}) {
+  switch (sub) {
+    case "path":
+      return knowledgePath();
+    case "init":
+      return knowledgeInit(arg);
+    case "link":
+      return knowledgeLink(arg);
+    case "sync":
+      return knowledgeSync(flags.push);
+    default:
+      log.info(
+        [
+          bold("groundwork knowledge") + dim(" — configure your central ADR/lessons repo"),
+          "",
+          `  ${cyan("init")} [dir]   create a new knowledge repo and remember its path (default: ~/groundwork-knowledge)`,
+          `  ${cyan("link")} <dir>   point at an existing clone and save it`,
+          `  ${cyan("sync")} [--push] pull latest from origin (and optionally push)`,
+          `  ${cyan("path")}         print the resolved knowledge-repo path for this user`,
+          "",
+          dim("Resolution order: $GROUNDWORK_KNOWLEDGE → user config → (unset)"),
+        ].join("\n")
+      );
+  }
+}
+
+function knowledgePath() {
+  const { path: p, source } = resolveKnowledgePath();
+  if (!p) {
+    log.warn("No knowledge repo configured for this user.");
+    log.info(dim("  Set one with: groundwork knowledge init   (or: link <dir>)"));
+    process.exitCode = 1;
+    return;
+  }
+  console.log(p);
+  log.info(dim(`  via ${source}${fs.existsSync(p) ? "" : "  — ⚠ path does not exist"}`));
+}
+
+function knowledgeSync(push) {
+  const { path: p } = resolveKnowledgePath();
+  if (!p || !fs.existsSync(p)) {
+    log.err("No knowledge repo configured/found. Run `groundwork knowledge init` or `link <dir>`.");
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    log.step(`Pulling latest into ${cyan(p)}`);
+    execFileSync("git", ["pull", "--rebase", "--autostash"], { cwd: p, stdio: "inherit" });
+    if (push) {
+      execFileSync("git", ["push"], { cwd: p, stdio: "inherit" });
+      log.ok("Pulled and pushed.");
+    } else {
+      log.ok("Up to date.");
+    }
+  } catch (e) {
+    log.err(`git sync failed: ${e.message}`);
+    process.exitCode = 1;
+  }
+}
+
+function knowledgeLink(dir) {
+  if (!dir) {
+    log.err("Usage: groundwork knowledge link <dir>");
+    process.exitCode = 1;
+    return;
+  }
+  const abs = path.resolve(dir);
+  if (!fs.existsSync(abs)) {
+    log.err(`Path does not exist: ${abs}`);
+    process.exitCode = 1;
+    return;
+  }
+  writeConfig({ knowledgeRepo: abs });
+  log.ok(`Knowledge repo set to ${cyan(abs)}`);
+  log.info(dim(`  saved in ${configFile()}`));
+}
+
+function knowledgeInit(dir) {
+  const abs = path.resolve(dir || path.join(os.homedir(), "groundwork-knowledge"));
+  if (fs.existsSync(path.join(abs, "adr"))) {
+    log.warn(`Already looks initialised: ${abs}`);
+  } else {
+    fs.mkdirSync(path.join(abs, "adr"), { recursive: true });
+    fs.mkdirSync(path.join(abs, "notes"), { recursive: true });
+    fs.writeFileSync(path.join(abs, "notes", ".gitkeep"), "");
+    fs.writeFileSync(path.join(abs, "README.md"), README);
+    fs.writeFileSync(path.join(abs, "INDEX.md"), INDEX);
+    fs.writeFileSync(path.join(abs, "notes", "lessons.md"), "# Lessons\n\n");
+    try {
+      execFileSync("git", ["init", "-q"], { cwd: abs });
+    } catch {
+      /* git optional */
+    }
+    log.ok(`Created knowledge repo at ${cyan(abs)}`);
+  }
+  writeConfig({ knowledgeRepo: abs });
+  log.info(dim(`  saved path in ${configFile()}`));
+  console.log(
+    [
+      "",
+      bold("Next:"),
+      `  1. (optional) create a remote and push:`,
+      dim(`       cd ${abs} && git add -A && git commit -m init`),
+      dim(`       gh repo create <you>/groundwork-knowledge --source=. --private --push`),
+      `  2. ${cyan("export GROUNDWORK_KNOWLEDGE=" + abs)}  ${dim("(add to your shell profile)")}`,
+      `  3. Use ${green("/remember")} — it writes here.`,
+    ].join("\n")
+  );
+}
+
+const README = `# groundwork-knowledge
+
+Central, git-level **ADR + lessons log** — cross-project, cross-machine, swarm-readable.
+Created by \`groundwork knowledge init\`.
+
+## Layout
+
+\`\`\`
+adr/      formal ADRs — NNNN-kebab-title.md
+notes/    raw dated captures (lessons.md)
+INDEX.md  the ADR index
+\`\`\`
+
+Notes are written by \`/remember\`; ADRs by \`/remember --adr\`.
+Resolved via the \`GROUNDWORK_KNOWLEDGE\` env var or your \`groundwork\` user config.
+`;
+
+const INDEX = `# ADR Index
+
+Cross-project architectural decisions and lessons learned.
+
+| ID | Title | Tags | Date |
+| -- | ----- | ---- | ---- |
+
+_New ADRs are added by \`/remember --adr\`. Keep IDs zero-padded and sequential._
+`;

package/src/commands/list.mjs

@@ -0,0 +1,61 @@
+import path from "node:path";
+import { TARGET, MINIMAL_SKILLS } from "../lib/paths.mjs";
+import { listDirs, exists, readText } from "../lib/fs.mjs";
+import { loadSkills, isReadOnly } from "../lib/skills.mjs";
+import { log, bold, green, dim, cyan } from "../lib/log.mjs";
+
+export function collectList(targetDir) {
+  const root = path.resolve(targetDir || ".");
+  const installed = new Set(listDirs(path.join(root, TARGET.skills)));
+  const here = exists(path.join(root, TARGET.skills));
+  const marker = path.join(root, TARGET.docs, ".groundwork", "VERSION");
+  const version = exists(marker) ? readText(marker).trim() : null;
+  const skills = loadSkills().map((skill) => ({
+    name: skill.name,
+    description: skill.data.description || "",
+    set: MINIMAL_SKILLS.includes(skill.name) ? "min" : "opt",
+    mode: isReadOnly(skill) ? "ask" : "edit",
+    installed: here && installed.has(skill.name),
+    mirrors: {
+      cursor: exists(path.join(root, TARGET.cursor, `${skill.name}.md`)),
+      vscode: exists(path.join(root, TARGET.vscode, `${skill.name}.prompt.md`)),
+    },
+  }));
+  return { ok: true, version, project: here, skills };
+}
+
+/** List every available skill, marking minimal-set, mode, and install state. */
+export function list(targetDir, opts = {}) {
+  const report = collectList(targetDir);
+  if (opts.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  const here = report.project;
+
+  log.heading("Available skills");
+  for (const skill of report.skills) {
+    const min = skill.set === "min" ? green("min") : dim("opt");
+    const mode = skill.mode === "ask" ? dim("ask ") : dim("edit");
+    const mark = here
+      ? skill.installed
+        ? green("●")
+        : dim("○")
+      : " ";
+    console.log(
+      `  ${mark} ${cyan(skill.name.padEnd(20))} ${min} ${mode}  ${dim(
+        skill.description
+      )}`
+    );
+  }
+  if (here) {
+    console.log(
+      `\n  ${green("●")} installed   ${dim("○")} available   ${green(
+        "min"
+      )}=minimal set   ${dim("opt")}=optional`
+    );
+  } else {
+    console.log(`\n  ${dim("Run inside a project (or pass a path) to see install state.")}`);
+  }
+  console.log(dim(`  Add one with: ${bold("groundwork add <name>")}`));
+}