@schneiderjoseph/devia 0.1.0

package/src/commands/doctor.mjs

@@ -0,0 +1,139 @@
+import path from "node:path";
+import { exists, read, readJSON, packageRoot, walk } from "../lib/fs.mjs";
+import { git, isRepo } from "../lib/git.mjs";
+import { standardVersion } from "../lib/version.mjs";
+import { color, heading, status, line } from "../lib/ui.mjs";
+import { ADAPTERS } from "./skills.mjs";
+import { REQUIRED_MEMORY, registryIds } from "./validate.mjs";
+
+function lastCommitTime(root, pathspec) {
+  const out = git(root, ["log", "-1", "--format=%ct", "--", ...pathspec]);
+  const n = Number(out);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+function commitsSince(root, sinceEpoch, pathspec) {
+  const out = git(root, [
+    "log",
+    `--since=${sinceEpoch}`,
+    "--format=%h",
+    "--",
+    ...pathspec,
+  ]);
+  if (out === null) return null;
+  return out ? out.split("\n").filter(Boolean).length : 0;
+}
+
+export default async function doctor(ctx) {
+  const { root, deviaDir, flags } = ctx;
+
+  if (flags.help) {
+    line(`
+${color.bold("devia doctor")} — adoption, drift and staleness
+
+  --root <dir>   repository to diagnose
+`.trim());
+    return 0;
+  }
+
+  heading(`devia doctor — ${path.basename(root)}`);
+
+  // Adoption
+  if (!exists(deviaDir)) {
+    status("FAIL", "no .devia/", "run `devia init` — this is rule zero (AGT-002)");
+    line("");
+    return 1;
+  }
+  const missing = REQUIRED_MEMORY.filter((f) => !exists(path.join(deviaDir, f)));
+  status(
+    missing.length ? "WARN" : "PASS",
+    `memory files (${REQUIRED_MEMORY.length - missing.length}/${REQUIRED_MEMORY.length})`,
+    missing.length ? `missing ${missing.join(", ")}` : ""
+  );
+
+  // Version pin
+  const config = readJSON(path.join(deviaDir, "devia.json")) || {};
+  const installed = standardVersion();
+  if (config.standardVersion && installed && config.standardVersion !== installed) {
+    status("WARN", `standard pinned at ${config.standardVersion}`, `installed ${installed} — run \`devia sync\``);
+  } else {
+    status("PASS", `standard v${config.standardVersion || installed || "?"}`);
+  }
+
+  // devia's own repository *is* the standard: it vendors nothing into itself (01_ARCHITECTURE.md).
+  const vendored = walk(path.join(deviaDir, "standard")).length;
+  if (path.resolve(root) === path.resolve(packageRoot)) {
+    status("SKIP", "vendored standard", "this repository is the standard");
+  } else {
+    status(
+      vendored ? "PASS" : "WARN",
+      `vendored standard: ${vendored} files`,
+      vendored ? "" : "run `devia sync`"
+    );
+  }
+
+  // Adapters
+  const present = Object.entries(ADAPTERS).filter(([, [, t]]) => exists(path.join(root, t)));
+  status(
+    present.length ? "PASS" : "WARN",
+    `agent adapters: ${present.length}/${Object.keys(ADAPTERS).length}`,
+    present.map(([k]) => k).join(", ") || "run `devia skills install`"
+  );
+
+  // Placeholders
+  let placeholders = 0;
+  for (const f of REQUIRED_MEMORY) {
+    const text = read(path.join(deviaDir, f));
+    if (text) placeholders += (text.match(/TODO\(devia\)/g) || []).length;
+  }
+  status(
+    placeholders ? "WARN" : "PASS",
+    `unfilled placeholders: ${placeholders}`,
+    placeholders ? "memory that describes nothing protects nothing" : ""
+  );
+
+  // Registries
+  const gaps = registryIds(read(path.join(deviaDir, "11_GAPS.md")) || "", "G");
+  const debt = registryIds(read(path.join(deviaDir, "12_DEBT.md")) || "", "D");
+  status("INFO", `registries: ${gaps.length} gap ids, ${debt.length} debt ids`);
+
+  // Staleness — is the memory older than the code it describes?
+  if (!isRepo(root)) {
+    status("SKIP", "staleness", "not a git repository");
+  } else {
+    const codePaths = (config.code?.paths || []).filter((p) => exists(path.join(root, p)));
+    const spec = codePaths.length ? codePaths : ["."];
+    const codeTime = lastCommitTime(root, spec);
+    const memTime = lastCommitTime(root, [".devia"]);
+
+    if (!codeTime) {
+      status("SKIP", "staleness", "no commits touching the code paths yet");
+    } else if (!memTime) {
+      status("WARN", "the memory has never been committed", "commit .devia/ with the code");
+    } else {
+      const drift = Math.max(0, codeTime - memTime);
+      const days = Math.floor(drift / 86400);
+      const behind = commitsSince(root, memTime, spec);
+      if (drift === 0) {
+        status("PASS", "memory is current with the code");
+      } else if (days < 3 && (behind ?? 0) < 5) {
+        status("PASS", `memory ${days}d behind the code`, `${behind ?? "?"} commits since`);
+      } else {
+        status(
+          "WARN",
+          `memory ${days}d behind the code`,
+          `${behind ?? "?"} commits touched ${spec.join(", ")} since the memory changed (MEM-009)`
+        );
+      }
+    }
+
+    const branch = git(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    const isDefault = ["main", "master"].includes(branch);
+    status(isDefault ? "WARN" : "PASS", `branch: ${branch}`, isDefault ? "work happens on a branch (OPS-002)" : "");
+  }
+
+  line("");
+  line(color.dim("  Next: `devia validate` for integrity, `devia check` for readiness gates."));
+  line("");
+  return 0;
+}

package/src/commands/init.mjs

@@ -0,0 +1,186 @@
+import fs from "node:fs";
+import path from "node:path";
+import { packageRoot, exists, read, writeFile, writeJSON, walk } from "../lib/fs.mjs";
+import { cliVersion, standardVersion } from "../lib/version.mjs";
+import { vendorStandard } from "../lib/vendor.mjs";
+import { color, heading, status, line } from "../lib/ui.mjs";
+import { installAdapters, ADAPTERS } from "./skills.mjs";
+
+const PROFILES = {
+  "web-app": "Web or SaaS application: UI, API, database",
+  service: "Backend service or API without its own UI",
+  library: "Library or package consumed by other code",
+  cli: "Command line tool",
+  "design-system": "Component library or design system",
+  docs: "Documentation or content repository",
+};
+
+function detectProfile(root) {
+  const pkg = path.join(root, "package.json");
+  if (exists(pkg)) {
+    const json = JSON.parse(read(pkg) || "{}");
+    const deps = { ...json.dependencies, ...json.devDependencies };
+    if (json.bin) return "cli";
+    if (deps.next || deps.react || deps.vue || deps.svelte || deps["@angular/core"])
+      return "web-app";
+    if (deps.express || deps.fastify || deps["@nestjs/core"]) return "service";
+    if (json.main || json.exports) return "library";
+  }
+  if (exists(path.join(root, "pyproject.toml")) || exists(path.join(root, "requirements.txt")))
+    return "service";
+  if (exists(path.join(root, "go.mod")) || exists(path.join(root, "Cargo.toml"))) return "service";
+  return "web-app";
+}
+
+function detectName(root) {
+  const pkg = path.join(root, "package.json");
+  if (exists(pkg)) {
+    try {
+      const name = JSON.parse(read(pkg)).name;
+      if (name) return String(name).replace(/^@[^/]+\//, "");
+    } catch {
+      /* fall through to the directory name */
+    }
+  }
+  return path.basename(root);
+}
+
+function detectCodePaths(root) {
+  const candidates = ["src", "app", "lib", "packages", "server", "api", "web", "components"];
+  return candidates.filter((c) => exists(path.join(root, c)));
+}
+
+function fill(text, vars) {
+  return text.replace(/\{\{(\w+)\}\}/g, (m, key) => (key in vars ? vars[key] : m));
+}
+
+export default async function init(ctx) {
+  const { root, deviaDir, flags, rootAwayFromCwd } = ctx;
+
+  if (flags.help) {
+    line(`
+${color.bold("devia init")} — create .devia/ in this repository
+
+  --root <dir>        target repository (default: detected root)
+  --profile <name>    ${Object.keys(PROFILES).join(" | ")}
+  --force             overwrite existing memory files (dangerous: they hold your decisions)
+  --no-agents         do not write the agent adapters
+  --no-vendor         do not vendor the standard into .devia/standard/
+  --yes               accept a detected root that is not the current directory
+`.trim());
+    return 0;
+  }
+
+  // `init` writes. When the root was detected rather than given, and it is not where the user is
+  // standing, stop and say so: a memory created in a parent repository is not something the
+  // output can undo afterwards.
+  if (rootAwayFromCwd && !flags.yes) {
+    status("FAIL", `init would write into ${root}`, "not the current directory");
+    line("");
+    line(`  ${color.bold("--root .")} to create the memory here, or ${color.bold("--yes")} to accept that root.`);
+    line("");
+    return 2;
+  }
+
+  const force = Boolean(flags.force);
+  const profile = String(flags.profile || detectProfile(root));
+  if (!PROFILES[profile]) {
+    console.error(`unknown profile: ${profile}`);
+    console.error(`known profiles: ${Object.keys(PROFILES).join(", ")}`);
+    return 2;
+  }
+
+  const name = detectName(root);
+  const version = standardVersion();
+  const cli = cliVersion();
+  const vars = {
+    PROJECT_NAME: name,
+    DEVIA_VERSION: cli,
+    DATE: new Date().toISOString().slice(0, 10),
+  };
+
+  heading(`devia init — ${name}`);
+  line(`  ${color.dim("root")}     ${root}`);
+  line(`  ${color.dim("profile")}  ${profile} — ${PROFILES[profile]}`);
+  line("");
+
+  const existed = exists(deviaDir);
+  fs.mkdirSync(deviaDir, { recursive: true });
+
+  // 1. Memory files
+  const templateDir = path.join(packageRoot, "templates", "project");
+  let written = 0;
+  let kept = 0;
+  for (const rel of walk(templateDir)) {
+    const target = path.join(deviaDir, rel);
+    if (exists(target) && !force) {
+      kept++;
+      continue;
+    }
+    writeFile(target, fill(read(path.join(templateDir, rel)) || "", vars));
+    written++;
+  }
+  status(written ? "PASS" : "SKIP", `memory files: ${written} written`, kept ? `${kept} kept` : "");
+
+  // 2. Configuration
+  const configPath = path.join(deviaDir, "devia.json");
+  if (!exists(configPath) || force) {
+    writeJSON(configPath, {
+      deviaVersion: cli,
+      standardVersion: version,
+      project: { name, profile },
+      maturity: { target: "gold", current: "bronze" },
+      code: { paths: detectCodePaths(root) },
+      modules: {
+        engineering: true,
+        design: profile !== "service" && profile !== "cli" && profile !== "library",
+        memory: true,
+      },
+      waivers: [],
+      initializedAt: vars.DATE,
+    });
+    status("PASS", "devia.json written");
+  } else {
+    status("SKIP", "devia.json kept", "use --force to regenerate");
+  }
+
+  // 3. Vendored standard
+  if (flags.vendor === false || flags["no-vendor"]) {
+    status("SKIP", "standard not vendored", "--no-vendor");
+  } else {
+    const files = vendorStandard(path.join(deviaDir, "standard"), {
+      by: "devia init",
+      cli,
+      standard: version,
+      date: vars.DATE,
+    });
+    status("PASS", `standard vendored: ${files} files`, `v${version}`);
+  }
+
+  // 4. Agent adapters
+  if (flags.agents === false || flags["no-agents"]) {
+    status("SKIP", "agent adapters not written", "--no-agents");
+  } else {
+    const res = installAdapters(root, { force });
+    status(
+      "PASS",
+      `agent adapters: ${res.written.length} written`,
+      res.kept.length ? `kept ${res.kept.join(", ")}` : ""
+    );
+  }
+
+  heading("Next");
+  line(`  1. Fill ${color.bold(".devia/00_OVERVIEW.md")} from what this repository actually is`);
+  line("  2. Move known issues into 11_GAPS.md (undecided) and 12_DEBT.md (decided, not built)");
+  line("  3. Write the real commands into 13_RECIPES.md and .devia/AGENTS.md");
+  line("  4. Run " + color.bold("npx devia validate") + " and " + color.bold("npx devia check"));
+  line("");
+  line(color.dim("  Commit .devia/ — it is part of the repository, not a scratch pad."));
+  if (existed && !force) {
+    line(color.dim("  Existing memory files were kept. --force overwrites them."));
+  }
+  line("");
+  return 0;
+}
+
+export { PROFILES, ADAPTERS };

package/src/commands/registry.mjs

@@ -0,0 +1,154 @@
+import path from "node:path";
+import { exists, read, writeFile } from "../lib/fs.mjs";
+import { color, heading, status, line } from "../lib/ui.mjs";
+import { registryIds } from "./validate.mjs";
+
+const REGISTRIES = {
+  gap: {
+    file: "11_GAPS.md",
+    prefix: "G",
+    label: "gap",
+    subjectCol: 1, // ID | Question | Impact if wrong | Interim behaviour | Status
+    row: (id, text) => `| ${id} | ${text} | | | open |`,
+    rule: "MEM-001",
+  },
+  debt: {
+    file: "12_DEBT.md",
+    prefix: "D",
+    label: "debt",
+    subjectCol: 3, // ID | Rule | Where | What is missing | Priority | Opened
+    row: (id, text, flags) =>
+      `| ${id} | ${flags.rule || ""} | ${flags.where || ""} | ${text} | ${
+        String(flags.priority || "P2").toUpperCase()
+      } | ${new Date().toISOString().slice(0, 10)} |`,
+    rule: "MEM-002",
+  },
+};
+
+const TEMPLATE_ROW = /^\|\s*[GD]\d+\s*\|\s*TODO\(devia\)/;
+
+function nextId(text, prefix) {
+  const ids = registryIds(text, prefix);
+  const max = ids.reduce((a, r) => Math.max(a, r.n), 0);
+  return `${prefix}${max + 1}`;
+}
+
+/** Insert a row after the last row of the first table in the file. */
+function insertRow(text, row) {
+  const lines = text.split("\n");
+  let lastRow = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\|/.test(lines[i])) lastRow = i;
+    if (/^##\s+(Closed|Discharged)/i.test(lines[i])) break;
+  }
+  if (lastRow < 0) return text.trimEnd() + "\n\n" + row + "\n";
+  lines.splice(lastRow + 1, 0, row);
+  return lines.join("\n");
+}
+
+export default async function registry(ctx, command) {
+  const { deviaDir, args, flags } = ctx;
+  const spec = REGISTRIES[command];
+  const action = args._[1];
+  const text = args._.slice(2).join(" ").trim();
+
+  if (flags.help || !action || (action === "add" && !text)) {
+    line(`
+${color.bold(`devia ${command}`)} — the ${spec.label} registry (${spec.rule})
+
+  devia ${command} add "<what>"        add a line with the next id
+  devia ${command} list                show the open lines
+  devia ${command} close <ID> "<by>"   move a line to the closed section
+
+${command === "debt" ? "  --rule <ID>  --where <path>  --priority P0|P1|P2|P3\n" : ""}
+A line is never deleted by a change that did not discharge it (MEM-003, MEM-011).
+`.trim());
+    return flags.help ? 0 : 2;
+  }
+
+  const file = path.join(deviaDir, spec.file);
+  if (!exists(file)) {
+    status("FAIL", `${spec.file} not found`, "run `devia init`");
+    return 1;
+  }
+  let content = read(file) || "";
+
+  if (action === "list") {
+    heading(`open ${spec.label} lines`);
+    const rows = [];
+    for (const l of content.split("\n")) {
+      if (/^##\s+(Closed|Discharged)/i.test(l)) break;
+      if (new RegExp(`^\\|\\s*${spec.prefix}\\d+\\s*\\|`).test(l)) rows.push(l);
+    }
+    if (!rows.length) status("INFO", "no open lines");
+    for (const r of rows) line("  " + r);
+    line("");
+    return 0;
+  }
+
+  if (action === "add") {
+    // A template row is a placeholder, not a record: the first real line replaces it.
+    const lines = content.split("\n");
+    const templateAt = lines.findIndex((l) => TEMPLATE_ROW.test(l));
+    if (templateAt >= 0) lines.splice(templateAt, 1);
+    content = lines.join("\n");
+
+    const id = nextId(content, spec.prefix);
+    content = insertRow(content, spec.row(id, text, flags));
+    writeFile(file, content);
+    heading(`${spec.label} added`);
+    status("PASS", id, text);
+    line(color.dim(`  ${spec.file} — verify the claim before you trust it (MEM-005)`));
+    line("");
+    return 0;
+  }
+
+  if (action === "close") {
+    const id = String(args._[1 + 1] || "").toUpperCase();
+    const by = args._.slice(3).join(" ").trim();
+    if (!id || !by) {
+      status("FAIL", "usage", `devia ${command} close <ID> "closed by <what>"`);
+      return 2;
+    }
+    // Splice the row out rather than blanking it: a blank line ends a markdown table, so every
+    // row below the closed one would render as loose text instead.
+    const rowRe = new RegExp(`^\\|\\s*${id}\\s*\\|`);
+    const rows = content.split("\n");
+    const at = rows.findIndex((l) => rowRe.test(l));
+    if (at < 0) {
+      status("FAIL", `${id} not found in ${spec.file}`);
+      return 1;
+    }
+    const [closed] = rows.splice(at, 1);
+    // An empty template row is a placeholder, not a record — dropped, not emptied.
+    content = rows.filter((l) => !/^\|(\s*\|)+\s*$/.test(l)).join("\n");
+
+    const cells = closed.split("|").slice(1, -1).map((c) => c.trim());
+    const subject = cells[spec.subjectCol] || cells[1] || "";
+    const closedRow = `| ${id} | ${subject} | ${by} |`;
+    const idx = content.search(/^##\s+(Closed|Discharged)/im);
+    if (idx < 0) {
+      content = content.trimEnd() + `\n\n## Closed\n\n| ID | Subject | Closed by |\n|---|---|---|\n${closedRow}\n`;
+    } else {
+      const lines = content.split("\n");
+      let insertAt = lines.length;
+      let inSection = false;
+      for (let i = 0; i < lines.length; i++) {
+        if (/^##\s+(Closed|Discharged)/i.test(lines[i])) inSection = true;
+        else if (inSection && /^\|/.test(lines[i])) insertAt = i + 1;
+      }
+      lines.splice(insertAt, 0, closedRow);
+      content = lines.join("\n");
+    }
+    content = content.replace(/\n{3,}/g, "\n\n");
+    writeFile(file, content);
+    heading(`${spec.label} closed`);
+    status("PASS", id, by);
+    line(color.dim("  Closure names the change that closed it (MEM-003)."));
+    line("");
+    return 0;
+  }
+
+  status("FAIL", `unknown action: ${action}`);
+  return 2;
+}

package/src/commands/rules.mjs

@@ -0,0 +1,101 @@
+import path from "node:path";
+import { loadRules, ruleStats } from "../lib/rules.mjs";
+import { exists, read, packageRoot } from "../lib/fs.mjs";
+import { color, heading, line, status } from "../lib/ui.mjs";
+import { parseFrontmatter } from "../lib/yaml.mjs";
+
+/** Prefer the copy pinned in the project; fall back to the installed package. */
+function rulesDir(ctx) {
+  const vendored = path.join(ctx.deviaDir, "standard", "rules");
+  return exists(vendored) ? vendored : path.join(packageRoot, "rules");
+}
+
+export default async function rules(ctx) {
+  const { flags } = ctx;
+
+  if (flags.help) {
+    line(`
+${color.bold("devia rules")} — the rule registry
+
+  devia rules                       list every active rule
+  devia rules --id SEC-001          show one rule in full
+  devia rules --domain security     filter by domain
+  devia rules --priority P0         filter by priority
+  devia rules --severity "MUST NOT" filter by severity
+  devia rules --search webhook      filter by text
+  devia rules --stats               counts only
+  devia rules --json                machine-readable
+`.trim());
+    return 0;
+  }
+
+  const dir = rulesDir(ctx);
+  const { rules: all, errors } = loadRules(dir);
+
+  if (errors.length && !ctx.json) {
+    for (const e of errors) status("WARN", "registry", e);
+  }
+
+  if (flags.id) {
+    const id = String(flags.id).toUpperCase();
+    const rule = all.find((r) => r.id === id);
+    if (!rule) {
+      console.error(`no such rule: ${id}`);
+      return 1;
+    }
+    const file = path.join(dir, rule.file);
+    if (ctx.json) {
+      const { body } = parseFrontmatter(read(file) || "");
+      console.log(JSON.stringify({ ...rule, body }, null, 2));
+      return 0;
+    }
+    line("");
+    line(read(file) || "");
+    return 0;
+  }
+
+  let list = all;
+  if (flags.domain) list = list.filter((r) => r.domain === String(flags.domain));
+  if (flags.priority) list = list.filter((r) => r.priority === String(flags.priority).toUpperCase());
+  if (flags.severity)
+    list = list.filter((r) => r.severity === String(flags.severity).toUpperCase());
+  if (flags.status) list = list.filter((r) => r.status === String(flags.status));
+  else list = list.filter((r) => r.status === "active");
+  if (flags.search) {
+    const q = String(flags.search).toLowerCase();
+    list = list.filter((r) =>
+      `${r.id} ${r.title} ${r.requirement}`.toLowerCase().includes(q)
+    );
+  }
+
+  if (ctx.json) {
+    console.log(JSON.stringify({ count: list.length, rules: list }, null, 2));
+    return 0;
+  }
+
+  if (flags.stats) {
+    const s = ruleStats(list);
+    heading(`Rules — ${s.total}`);
+    for (const [k, v] of Object.entries(s.priority).sort()) line(`  ${k}  ${v}`);
+    line("");
+    for (const [k, v] of Object.entries(s.domain).sort()) line(`  ${k.padEnd(16)} ${v}`);
+    line("");
+    return 0;
+  }
+
+  heading(`Rules (${list.length})`);
+  let domain = null;
+  for (const r of list) {
+    if (r.domain !== domain) {
+      domain = r.domain;
+      line(`\n  ${color.bold(domain)}`);
+    }
+    const tag =
+      r.priority === "P0" ? color.red(r.priority) : r.priority === "P1" ? color.yellow(r.priority) : color.gray(r.priority);
+    line(`    ${tag} ${color.bold(r.id.padEnd(9))} ${r.severity.padEnd(8)} ${r.title}`);
+  }
+  line("");
+  line(color.dim(`  devia rules --id <ID> for the full text · source: ${path.relative(ctx.root, dir).split(path.sep).join("/") || dir}`));
+  line("");
+  return 0;
+}

package/src/commands/skills.mjs

@@ -0,0 +1,97 @@
+import path from "node:path";
+import { packageRoot, exists, read, writeFile } from "../lib/fs.mjs";
+import { color, heading, status, line } from "../lib/ui.mjs";
+
+/** agent key -> [template file, target path relative to the repository root] */
+export const ADAPTERS = {
+  universal: ["AGENTS.md", "AGENTS.md"],
+  claude: ["CLAUDE.md", "CLAUDE.md"],
+  cursor: ["cursor.mdc", path.join(".cursor", "rules", "devia.mdc")],
+  copilot: ["copilot-instructions.md", path.join(".github", "copilot-instructions.md")],
+  windsurf: ["windsurfrules.md", ".windsurfrules"],
+};
+
+const SKILL_TARGETS = {
+  cursor: path.join(".cursor", "skills", "devia", "SKILL.md"),
+  claude: path.join(".claude", "skills", "devia", "SKILL.md"),
+};
+
+export function installAdapters(root, { force = false, agents = Object.keys(ADAPTERS) } = {}) {
+  const written = [];
+  const kept = [];
+  for (const key of agents) {
+    const entry = ADAPTERS[key];
+    if (!entry) continue;
+    const [template, target] = entry;
+    const dest = path.join(root, target);
+    if (exists(dest) && !force) {
+      kept.push(key);
+      continue;
+    }
+    const content = read(path.join(packageRoot, "templates", "agents", template));
+    if (content === null) continue;
+    writeFile(dest, content);
+    written.push(key);
+  }
+  return { written, kept };
+}
+
+export function installSkill(root, { force = false, agents = Object.keys(SKILL_TARGETS) } = {}) {
+  const skill = read(path.join(packageRoot, "skills", "devia", "SKILL.md"));
+  const written = [];
+  const kept = [];
+  for (const key of agents) {
+    const target = SKILL_TARGETS[key];
+    if (!target || skill === null) continue;
+    const dest = path.join(root, target);
+    if (exists(dest) && !force) {
+      kept.push(key);
+      continue;
+    }
+    writeFile(dest, skill);
+    written.push(key);
+  }
+  return { written, kept };
+}
+
+export default async function skills(ctx) {
+  const { root, flags, args } = ctx;
+  const action = args._[1] || "install";
+
+  if (flags.help || !["install", "list"].includes(action)) {
+    line(`
+${color.bold("devia skills")} — the same contract for every coding agent
+
+  devia skills list
+  devia skills install [--agent all|${Object.keys(ADAPTERS).join("|")}] [--force] [--skill]
+
+  --skill    also install skills/devia/SKILL.md for Cursor and Claude Code
+`.trim());
+    return flags.help ? 0 : 2;
+  }
+
+  if (action === "list") {
+    heading("Adapters");
+    for (const [key, [, target]] of Object.entries(ADAPTERS)) {
+      const there = exists(path.join(root, target));
+      status(there ? "PASS" : "SKIP", key.padEnd(10), target.split(path.sep).join("/"));
+    }
+    line("");
+    return 0;
+  }
+
+  const wanted = flags.agent && flags.agent !== "all" ? String(flags.agent).split(",") : undefined;
+  const res = installAdapters(root, { force: Boolean(flags.force), agents: wanted });
+
+  heading("devia skills install");
+  for (const key of res.written) status("PASS", key, "written");
+  for (const key of res.kept) status("SKIP", key, "already present — use --force");
+
+  if (flags.skill) {
+    const s = installSkill(root, { force: Boolean(flags.force) });
+    for (const key of s.written) status("PASS", `${key} skill`, "written");
+    for (const key of s.kept) status("SKIP", `${key} skill`, "already present");
+  }
+  line("");
+  return 0;
+}