doctrina-cli 0.1.0

package/src/commands/clarify.js

@@ -0,0 +1,146 @@
+import path from "node:path";
+import process from "node:process";
+import { isFile, read } from "../lib/fs-ops.js";
+import { c } from "../lib/colors.js";
+
+const RULES = [
+  {
+    // "may" is intentionally NOT in this list: EARS Optional grammar
+    // uses "the system may ..." legitimately, and a clarify pass that
+    // flags every EARS Optional is unusable on Doctrina-style specs.
+    // The remaining weasel terms are unambiguous.
+    name: "weasel",
+    re: /\b(might|could|should\s+probably|perhaps|maybe|approximately|roughly)\b/gi,
+    hint: "state explicitly with a definite verb",
+  },
+  {
+    name: "vague",
+    re: /\b(many|few|some|several)\b(?!\s+\d)/gi,
+    hint: "quantify (use a number or a precise scope)",
+  },
+  {
+    name: "placeholder",
+    re: /\b(TBD|TODO|FIXME|XXX|\?\?\?)\b/g,
+    hint: "resolve before applying",
+  },
+];
+
+export async function run(positional, _flags) {
+  const target = positional[0];
+  if (!target) {
+    console.error(c.red("error:") + " clarify requires a path to a Markdown file");
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  const fullPath = path.resolve(projectRoot, target);
+  if (!isFile(fullPath)) {
+    console.error(c.red("error:") + ` file not found: ${target}`);
+    return 1;
+  }
+
+  console.log(`clarify ${path.relative(projectRoot, fullPath)}`);
+  console.log("");
+
+  const text = read(fullPath);
+  const skippedRanges = collectSkippedRanges(text);
+  const smells = [];
+
+  // Per-line rules: regex pass with skip-range filter.
+  const lines = text.split("\n");
+  let cursor = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineStart = cursor;
+    const lineEnd = cursor + line.length;
+    for (const rule of RULES) {
+      rule.re.lastIndex = 0;
+      let m;
+      while ((m = rule.re.exec(line))) {
+        const absoluteStart = lineStart + m.index;
+        if (isInSkippedRange(absoluteStart, skippedRanges)) continue;
+        smells.push({
+          line: i + 1,
+          rule: rule.name,
+          token: m[0],
+          hint: rule.hint,
+        });
+      }
+    }
+    cursor = lineEnd + 1; // +1 for the newline
+  }
+
+  // Section rule: empty Acceptance criteria.
+  if (hasEmptyAcceptanceCriteria(text)) {
+    smells.push({
+      line: findAcceptanceLine(text),
+      rule: "empty-section",
+      token: "Acceptance criteria",
+      hint: "fill in observable, verifiable signals",
+    });
+  }
+
+  smells.sort((a, b) => a.line - b.line);
+
+  for (const s of smells) {
+    console.log(`${c.yellow("⚠")} line ${s.line}: ${s.rule} "${s.token}" — ${s.hint}`);
+  }
+
+  console.log("");
+  if (smells.length === 0) {
+    console.log(c.green("ok") + " no smells found");
+    return 0;
+  }
+  const word = smells.length === 1 ? "smell" : "smells";
+  console.log(c.red("fail") + ` ${smells.length} ${word}`);
+  return 1;
+}
+
+// Build ranges to skip: fenced code blocks, HTML comments, inline backticks.
+function collectSkippedRanges(text) {
+  const ranges = [];
+  // Fenced code blocks (``` ... ```)
+  for (const m of text.matchAll(/```[\s\S]*?```/g)) ranges.push([m.index, m.index + m[0].length]);
+  // HTML comments (<!-- ... -->)
+  for (const m of text.matchAll(/<!--[\s\S]*?-->/g)) ranges.push([m.index, m.index + m[0].length]);
+  // Inline backtick spans (`...`)
+  for (const m of text.matchAll(/`[^`\n]+`/g)) ranges.push([m.index, m.index + m[0].length]);
+  return ranges;
+}
+
+function isInSkippedRange(offset, ranges) {
+  for (const [a, b] of ranges) if (offset >= a && offset < b) return true;
+  return false;
+}
+
+function hasEmptyAcceptanceCriteria(text) {
+  const headingRe = /^##\s+Acceptance criteria\s*$/m;
+  const m = headingRe.exec(text);
+  if (!m) return false;
+  const after = text.slice(m.index + m[0].length);
+  // Find the body between this heading and the next heading of equal level.
+  const nextHeadingMatch = after.match(/^##\s+/m);
+  const body = nextHeadingMatch ? after.slice(0, nextHeadingMatch.index) : after;
+  // Strip HTML comments before checking emptiness.
+  const stripped = body.replace(/<!--[\s\S]*?-->/g, "").trim();
+  return stripped.length === 0;
+}
+
+function findAcceptanceLine(text) {
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    if (/^##\s+Acceptance criteria\s*$/.test(lines[i])) return i + 1;
+  }
+  return 1;
+}
+
+export const help = `
+Usage: doctrina clarify <path>
+
+Read a Markdown file and report weasel words, vague quantifiers,
+placeholders, and empty Acceptance criteria sections. Exits 0 when
+no smells are found, 1 otherwise. Matches inside fenced code
+blocks, HTML comments, and inline backtick spans are skipped.
+
+Intended use: run before \`doctrina change apply\` or before
+opening a PR. The command never modifies files.
+`;

package/src/commands/decision.js

@@ -0,0 +1,183 @@
+import path from "node:path";
+import process from "node:process";
+import { exists, read, write } from "../lib/fs-ops.js";
+import { walk } from "../lib/fs-ops.js";
+import { locateTemplatesDir, substitute } from "../lib/templates.js";
+import * as idx from "../lib/index-json.js";
+import { today, slugify, padNumber } from "../lib/dates.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+
+const SUBCOMMANDS = ["new", "supersede"];
+
+export async function run(positional, _flags) {
+  const sub = positional[0];
+  switch (sub) {
+    case "new":
+      return decisionNew(positional.slice(1));
+    case "supersede":
+      return decisionSupersede(positional.slice(1));
+    default:
+      console.error(c.red("error:") + ` unknown decision subcommand "${sub ?? ""}"`);
+      const guess = suggest(sub, SUBCOMMANDS);
+      console.error(c.gray("hint: ") + (guess
+        ? `did you mean \`doctrina decision ${guess}\`?`
+        : `available: ${SUBCOMMANDS.join(", ")}`));
+      return 2;
+  }
+}
+
+function decisionNew(args) {
+  const title = args.join(" ").trim();
+  if (!title) {
+    console.error(c.red("error:") + " decision new requires \"<title>\"");
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const next = nextDecisionNumber(projectRoot);
+  const date = today();
+  const slug = slugify(title);
+  const filename = `${next}-${slug}.md`;
+  const targetPath = path.join(projectRoot, ".doctrina", "decisions", filename);
+  if (exists(targetPath)) {
+    console.error(c.red("error:") + ` ${path.relative(projectRoot, targetPath)} already exists`);
+    return 1;
+  }
+
+  const templatesDir = locateTemplatesDir();
+  const tpl = read(path.join(templatesDir, "decision.md.template"));
+  const body = substitute(tpl, {
+    DECISION_NUMBER: next,
+    DECISION_TITLE: title,
+    DECISION_SLUG: slug,
+    DATE: date,
+  });
+  write(targetPath, body, { force: false });
+  console.log(c.green("created") + ` ${path.relative(projectRoot, targetPath)}`);
+
+  const index = idx.load(projectRoot);
+  idx.addDecision(index, {
+    id: next,
+    path: `.doctrina/decisions/${filename}`,
+    title,
+    status: "proposed",
+    date,
+  });
+  idx.touch(index, date);
+  idx.save(projectRoot, index);
+  console.log(c.green("indexed") + ` decision ${next}`);
+  return 0;
+}
+
+function decisionSupersede(args) {
+  const target = args[0];
+  if (!target) {
+    console.error(c.red("error:") + " decision supersede requires the target ADR number (e.g. 0003)");
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const padded = padNumber(parseInt(target, 10));
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  const files = walk(adrDir);
+  const oldFile = files.find((f) => path.basename(f).startsWith(`${padded}-`));
+  if (!oldFile) {
+    console.error(c.red("error:") + ` no ADR found with number ${padded} in ${path.relative(projectRoot, adrDir)}`);
+    return 1;
+  }
+  const oldText = read(oldFile);
+  const oldStatusMatch = oldText.match(/^-\s+\*\*Status:\*\*\s+(.+)$/m);
+  if (!oldStatusMatch) {
+    console.error(c.red("error:") + ` ADR at ${path.relative(projectRoot, oldFile)} has no Status: header`);
+    return 1;
+  }
+  const oldStatus = oldStatusMatch[1].trim();
+  if (oldStatus.toLowerCase().startsWith("superseded")) {
+    console.error(c.red("error:") + ` ADR ${padded} is already superseded`);
+    return 1;
+  }
+
+  // Title for new ADR is read from argv after the target number, or prompted.
+  const title = args.slice(1).join(" ").trim();
+  if (!title) {
+    console.error(c.red("error:") + " supply the new ADR title as the second argument");
+    return 2;
+  }
+
+  // Create the new ADR using the same path the `new` flow uses.
+  const next = nextDecisionNumber(projectRoot);
+  const date = today();
+  const slug = slugify(title);
+  const filename = `${next}-${slug}.md`;
+  const newPath = path.join(adrDir, filename);
+  const templatesDir = locateTemplatesDir();
+  const tpl = read(path.join(templatesDir, "decision.md.template"));
+  let body = substitute(tpl, {
+    DECISION_NUMBER: next,
+    DECISION_TITLE: title,
+    DECISION_SLUG: slug,
+    DATE: date,
+  });
+  // Inject Supersedes link
+  body = body.replace(/(\*\*Supersedes:\*\*)\s+—/, `$1 ${padded}`);
+  write(newPath, body, { force: false });
+  console.log(c.green("created") + ` ${path.relative(projectRoot, newPath)}`);
+
+  // Mutate ONLY the Status: and Superseded by: headers of the old ADR
+  const updated = oldText
+    .replace(/^(-\s+\*\*Status:\*\*)\s+.+$/m, `$1 superseded by ${next}`)
+    .replace(/^(-\s+\*\*Superseded by:\*\*)\s+.+$/m, `$1 ${next}`);
+  write(oldFile, updated, { force: true });
+  console.log(c.green("updated") + ` ${path.relative(projectRoot, oldFile)} status -> superseded by ${next}`);
+
+  // Update index
+  const index = idx.load(projectRoot);
+  idx.addDecision(index, {
+    id: next,
+    path: `.doctrina/decisions/${filename}`,
+    title,
+    status: "proposed",
+    date,
+    supersedes: padded,
+  });
+  idx.updateDecision(index, padded, () => ({
+    status: `superseded by ${next}`,
+    superseded_by: next,
+  }));
+  idx.touch(index, date);
+  idx.save(projectRoot, index);
+  console.log(c.green("indexed") + ` supersession recorded`);
+  return 0;
+}
+
+function nextDecisionNumber(projectRoot) {
+  const adrDir = path.join(projectRoot, ".doctrina", "decisions");
+  const files = walk(adrDir);
+  let max = 0;
+  for (const f of files) {
+    const m = path.basename(f).match(/^(\d{4})-/);
+    if (m) {
+      const n = parseInt(m[1], 10);
+      if (n > max) max = n;
+    }
+  }
+  return padNumber(max + 1);
+}
+
+function ensureDoctrinaProject(projectRoot) {
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+}
+
+export const help = `
+Usage: doctrina decision <subcommand> [args]
+
+Subcommands:
+  new "<title>"                        Create the next sequentially numbered ADR
+  supersede <number> "<new title>"     Create a new ADR that supersedes the target
+                                       and rewrite the target's Status: header
+`;

package/src/commands/hooks.js

@@ -0,0 +1,59 @@
+import path from "node:path";
+import process from "node:process";
+import { chmodSync } from "node:fs";
+import { exists, mkdirp, read, write } from "../lib/fs-ops.js";
+import { locateTemplatesDir } from "../lib/templates.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+
+const SUBCOMMANDS = ["install"];
+
+export async function run(positional, flags) {
+  const sub = positional[0];
+  if (!SUBCOMMANDS.includes(sub)) {
+    console.error(c.red("error:") + ` unknown hooks subcommand "${sub ?? ""}"`);
+    const guess = suggest(sub, SUBCOMMANDS);
+    console.error(c.gray("hint: ") + (guess
+      ? `did you mean \`doctrina hooks ${guess}\`?`
+      : `available: ${SUBCOMMANDS.join(", ")}`));
+    return 2;
+  }
+
+  const force = flagBool(flags, "force", false);
+  const projectRoot = process.cwd();
+
+  if (!exists(path.join(projectRoot, ".git"))) {
+    console.error(c.red("error:") + " not a git repository (no .git/ in cwd)");
+    return 1;
+  }
+
+  const hooksDir = path.join(projectRoot, ".git", "hooks");
+  mkdirp(hooksDir);
+
+  const target = path.join(hooksDir, "pre-commit");
+  if (exists(target) && !force) {
+    console.error(c.red("error:") + ` ${path.relative(projectRoot, target)} already exists (pass --force to overwrite)`);
+    return 1;
+  }
+
+  const templatesDir = locateTemplatesDir();
+  const tplPath = path.join(templatesDir, "hooks", "pre-commit.sample");
+  const body = read(tplPath);
+  write(target, body, { force: true });
+  chmodSync(target, 0o755);
+  console.log(c.green("installed") + ` ${path.relative(projectRoot, target)}`);
+  console.log(`The hook runs ${c.cyan("doctrina validate")} before each commit.`);
+  return 0;
+}
+
+export const help = `
+Usage: doctrina hooks install [--force]
+
+Install the Doctrina pre-commit hook into .git/hooks/pre-commit.
+The hook runs \`doctrina validate\` and blocks the commit when
+validation reports errors.
+
+Options:
+  --force    Overwrite an existing pre-commit hook
+`;

package/src/commands/init.js

@@ -0,0 +1,158 @@
+import path from "node:path";
+import process from "node:process";
+import { exists, isDir, isFile, read, write } from "../lib/fs-ops.js";
+import { locateTemplatesDir, loadTemplateTree, materialiseEntry, substitute } from "../lib/templates.js";
+import { today } from "../lib/dates.js";
+import { flagBool, flagString } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { ask } from "../lib/prompt.js";
+
+const SUPPORTED_AGENTS = [
+  "claude",
+  "codex",
+  "cursor",
+  "copilot",
+  "gemini",
+  "aider",
+  "windsurf",
+  "continue",
+  "amp",
+  "devin",
+  "factory",
+  "jules",
+];
+
+export async function run(_positional, flags) {
+  const force = flagBool(flags, "force", false);
+  const nonInteractive = flagBool(flags, "non-interactive", false);
+  const projectRoot = process.cwd();
+  const projectName = flagString(flags, "project-name") ?? path.basename(projectRoot);
+  const date = flagString(flags, "date") ?? today();
+
+  let description = flagString(flags, "project-description") ?? "";
+  if (!description && !nonInteractive) {
+    description = await ask("One-sentence project description:");
+  }
+
+  const agentSelector = flagString(flags, "agent");
+  const fromPath = flagString(flags, "from");
+  const agentsMdPath = path.join(projectRoot, "AGENTS.md");
+  const doctrinaDir = path.join(projectRoot, ".doctrina");
+
+  if (!force && (exists(agentsMdPath) || exists(doctrinaDir))) {
+    console.error(c.red("error:") + " AGENTS.md or .doctrina/ already exists at this path");
+    console.error(c.gray("hint: ") + "pass --force to overwrite");
+    return 1;
+  }
+
+  // Resolve --from conventions source if supplied.
+  let fromAgentsContent = null;
+  let fromProductContent = null;
+  if (fromPath) {
+    const fromAbs = path.resolve(projectRoot, fromPath);
+    if (!isDir(fromAbs)) {
+      console.error(c.red("error:") + ` --from path is not a directory: ${fromPath}`);
+      return 1;
+    }
+    const fromAgents = path.join(fromAbs, "AGENTS.md");
+    const fromProduct = path.join(fromAbs, ".doctrina", "product.md");
+    if (isFile(fromAgents)) fromAgentsContent = read(fromAgents);
+    if (isFile(fromProduct)) fromProductContent = read(fromProduct);
+    if (!fromAgentsContent && !fromProductContent) {
+      console.error(c.yellow("warn:") + ` no AGENTS.md or .doctrina/product.md found at ${fromPath}, proceeding with defaults`);
+    }
+  }
+
+  const templatesDir = locateTemplatesDir();
+  const tokens = {
+    PROJECT_NAME: projectName,
+    PROJECT_DESCRIPTION: description,
+    DATE: date,
+    AGENTS_MD_PATH: "AGENTS.md",
+  };
+
+  // Root AGENTS.md — with optional --from base content prepended.
+  const agentsTemplatePath = path.join(templatesDir, "AGENTS.md.template");
+  const agentsTemplateBody = read(agentsTemplatePath);
+  const projectAgents = substitute(agentsTemplateBody, tokens);
+  const finalAgents = fromAgentsContent
+    ? fromAgentsContent.replace(/\n+$/, "") + "\n\n---\n\n## Project-specific\n\n" + projectAgents
+    : projectAgents;
+  write(agentsMdPath, finalAgents, { force });
+  console.log(c.green("created") + ` ${path.relative(projectRoot, agentsMdPath)}` + (fromAgentsContent ? " (with --from base)" : ""));
+  const finalLines = finalAgents.split("\n").length;
+  if (finalLines > 150) {
+    console.log(c.yellow("warn:") + ` AGENTS.md is ${finalLines} lines (>150 soft cap); consider trimming the base`);
+  }
+
+  // .doctrina/ skeleton
+  const skeleton = loadTemplateTree(templatesDir, "doctrina");
+  for (const entry of skeleton) {
+    // Inject --from product.md vision if present
+    if (fromProductContent && entry.relativePath === "product.md.template") {
+      const visionMatch = fromProductContent.match(/##\s+Vision\b[\s\S]*?(?=\n##\s|$)/);
+      const visionBlock = visionMatch ? visionMatch[0].trim() : fromProductContent.trim();
+      const projectBody = substitute(entry.body, tokens);
+      const merged = `# ${projectName} — Product\n\n## Conventions base (from ${fromPath})\n\n${visionBlock}\n\n---\n\n${projectBody.replace(/^#[^\n]*\n+/, "")}`;
+      const dest = path.join(doctrinaDir, "product.md");
+      write(dest, merged, { force });
+      console.log(c.green("created") + ` ${path.relative(projectRoot, dest)} (with --from base)`);
+      continue;
+    }
+    const written = materialiseEntry(entry, doctrinaDir, tokens, { force });
+    console.log(c.green("created") + ` ${path.relative(projectRoot, written)}`);
+  }
+
+  // Adapters
+  if (agentSelector) {
+    const agents = agentSelector === "all" ? SUPPORTED_AGENTS : [agentSelector];
+    for (const agent of agents) {
+      if (!SUPPORTED_AGENTS.includes(agent)) {
+        console.error(c.yellow("warn:") + ` unknown agent "${agent}", skipping`);
+        continue;
+      }
+      installAdapter(templatesDir, projectRoot, agent, tokens, { force });
+    }
+  }
+
+  console.log("");
+  console.log(c.bold("Doctrina initialised."));
+  console.log(`Next: edit ${c.cyan("AGENTS.md")} and ${c.cyan(".doctrina/product.md")} for your project.`);
+  return 0;
+}
+
+function installAdapter(templatesDir, projectRoot, agent, tokens, opts) {
+  const tree = loadTemplateTree(templatesDir, path.join("adapters", agent));
+  for (const entry of tree) {
+    if (entry.relativePath === "README.md") continue;
+    const adapterTokens = {
+      ...tokens,
+      AGENTS_MD_PATH: adapterAgentsMdRelativePath(entry.relativePath),
+    };
+    const written = materialiseEntry(entry, projectRoot, adapterTokens, opts);
+    console.log(c.green(`adapter[${agent}]`) + ` ${path.relative(projectRoot, written)}`);
+  }
+}
+
+function adapterAgentsMdRelativePath(relativePath) {
+  const cleaned = relativePath.replace(/\.template$/, "");
+  const depth = cleaned.split(path.sep).length - 1;
+  return depth === 0 ? "AGENTS.md" : "../".repeat(depth) + "AGENTS.md";
+}
+
+export const help = `
+Usage: doctrina init [options]
+
+Scaffold AGENTS.md and the .doctrina/ skeleton in the current directory.
+
+Options:
+  --project-name <name>          Override the project name (default: basename of cwd)
+  --project-description <text>   One-sentence description
+  --agent <name>                 Install adapter for one agent
+                                 (claude|codex|cursor|copilot|gemini|aider|windsurf|continue|amp|devin|factory|jules|all)
+  --from <path>                  Local conventions directory; if it contains AGENTS.md and/or
+                                 .doctrina/product.md, the content is folded into the new project
+  --date <YYYY-MM-DD>            Override the system date
+  --force                        Overwrite existing files
+  --non-interactive              Fail instead of prompting for missing values
+`;

package/src/commands/skill.js

@@ -0,0 +1,130 @@
+import path from "node:path";
+import process from "node:process";
+import { exists, isDir, mkdirp, read, walk, write } from "../lib/fs-ops.js";
+import { locateTemplatesDir, substitute } from "../lib/templates.js";
+import * as idx from "../lib/index-json.js";
+import { today } from "../lib/dates.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+
+const SUBCOMMANDS = ["new", "list"];
+
+export async function run(positional, flags) {
+  const sub = positional[0];
+  if (!SUBCOMMANDS.includes(sub)) {
+    console.error(c.red("error:") + ` unknown skill subcommand "${sub ?? ""}"`);
+    const guess = suggest(sub, SUBCOMMANDS);
+    console.error(c.gray("hint: ") + (guess
+      ? `did you mean \`doctrina skill ${guess}\`?`
+      : `available: ${SUBCOMMANDS.join(", ")}`));
+    return 2;
+  }
+  if (sub === "new") return skillNew(positional.slice(1), flags);
+  return skillList();
+}
+
+function skillNew(args, flags) {
+  const name = args[0];
+  if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) {
+    console.error(c.red("error:") + " skill name must be lowercase letters, digits, or hyphens (e.g. \"db-migration\")");
+    return 2;
+  }
+  const force = flagBool(flags, "force", false);
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  mkdirp(skillsDir);
+  const targetPath = path.join(skillsDir, `${name}.md`);
+  if (exists(targetPath) && !force) {
+    console.error(c.red("error:") + ` ${path.relative(projectRoot, targetPath)} already exists (pass --force to overwrite)`);
+    return 1;
+  }
+
+  const templatesDir = locateTemplatesDir();
+  const tplPath = path.join(templatesDir, "skill.md.template");
+  const body = substitute(read(tplPath), { SKILL_NAME: name });
+  write(targetPath, body, { force });
+  console.log(c.green("created") + ` ${path.relative(projectRoot, targetPath)}`);
+
+  const date = today();
+  const index = idx.load(projectRoot);
+  idx.addSkill(index, {
+    id: name,
+    path: `.doctrina/skills/${name}.md`,
+    description: "<edit me — one-sentence summary>",
+    last_updated: date,
+  });
+  idx.touch(index, date);
+  idx.save(projectRoot, index);
+  console.log(c.green("indexed") + ` skill "${name}"`);
+  console.log("");
+  console.log(c.gray("hint: ") + "fill the description and when frontmatter fields, then update index.json description by hand");
+  return 0;
+}
+
+function skillList() {
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const skillsDir = path.join(projectRoot, ".doctrina", "skills");
+  if (!isDir(skillsDir)) {
+    console.log(c.gray("no skills directory; create one with `doctrina skill new <name>`"));
+    return 0;
+  }
+
+  const files = walk(skillsDir).filter((f) => f.endsWith(".md"));
+  if (files.length === 0) {
+    console.log(c.gray("no skills found in .doctrina/skills/"));
+    return 0;
+  }
+
+  console.log(c.bold("Skills:"));
+  console.log("");
+  for (const f of files) {
+    const text = read(f);
+    const name = parseFrontmatter(text, "name") ?? path.basename(f, ".md");
+    const desc = parseFrontmatter(text, "description") ?? c.gray("<missing description>");
+    console.log(`  ${c.cyan(name.padEnd(24))}  ${desc}`);
+  }
+  console.log("");
+  console.log(c.gray(`${files.length} skill${files.length === 1 ? "" : "s"}`));
+  return 0;
+}
+
+function parseFrontmatter(text, key) {
+  // Match frontmatter blocks bounded by `---` lines at start of file.
+  const fmMatch = text.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
+  if (!fmMatch) return null;
+  const block = fmMatch[1];
+  const lineRe = new RegExp(`^${key}\\s*:\\s*(.+)$`, "m");
+  const m = block.match(lineRe);
+  return m ? m[1].trim() : null;
+}
+
+function ensureDoctrinaProject(projectRoot) {
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+}
+
+export const help = `
+Usage: doctrina skill <subcommand>
+
+Manage on-demand procedural memory — specialised "how to do X"
+knowledge loaded only when relevant.
+
+Subcommands:
+  new <name>    Scaffold a new skill from the template and index
+                it. Name must match [a-z][a-z0-9-]*.
+  list          Print one line per skill with name + description.
+                Read-only.
+
+Skills are written by humans, not generated. See docs/en/skills.md
+for the design rationale and the distinction from specs / AGENTS.md /
+the rejected memory/ folder.
+`;
+
+// Re-export the frontmatter parser so validate.js can reuse it.
+export { parseFrontmatter };