ai-engineering-kit 0.5.0 → 0.6.0

package/README.md

@@ -9,7 +9,7 @@
 - **Skills** — Markdown playbooks, grouped into categories you pick at install time:
   - **core-workflow** — brainstorm → foundations → PRD → plan → implement → review → verify.
   - **engineering**, **productivity**, **misc** — additional day-to-day skills forked from [`mattpocock/skills`](https://github.com/mattpocock/skills) (see attribution below).
-- **A structured workspace** — `ai/` for ephemeral artifacts (brainstorms, PRDs, plans, reviews) and `docs/foundations/` for canonical, long-lived project knowledge.
+- **A structured workspace** — `ai/` for ephemeral artifacts (brainstorms, PRDs, plans, reviews) and `docs/` for durable knowledge: `foundations/` (vision, guidelines, decisions) plus `system/`, `references/`, `operations/`, and `debt/`.
 - **Agent-agnostic wiring** — skills live as portable Markdown in `ai/skills/`; the kit generates the entry file each agent reads (`CLAUDE.md` + a `.claude/skills/` symlink for Claude Code, `AGENTS.md` for Codex). More agents are a template + a manifest entry away.
 
 ## Quickstart

package/dist/cli.js

@@ -54,10 +54,10 @@ var CATEGORIES = [
 var TREE_COMPONENTS = [
   {
     id: "docs-foundations",
-    label: "Foundation docs",
-    hint: "Starter docs for product vision, guidelines, and technical decisions (docs/foundations/)",
-    from: "docs/foundations",
-    to: "docs/foundations"
+    label: "Project docs",
+    hint: "docs/ scaffold: foundations stubs + system, references, operations, debt",
+    from: "docs",
+    to: "docs"
   },
   {
     id: "ai-workspace",
@@ -211,7 +211,7 @@ function planUntracked(_file, onDisk) {
 }
 
 // src/io/project.ts
-import { existsSync, readFileSync as readFileSync2 } from "fs";
+import { existsSync, readFileSync as readFileSync2, writeFileSync } from "fs";
 import { join as join2 } from "path";
 var MANIFEST_FILE = ".ai-kit.json";
 function readManifest(projectDir) {
@@ -219,6 +219,9 @@ function readManifest(projectDir) {
   if (!existsSync(path)) return null;
   return parseManifest(readFileSync2(path, "utf8"));
 }
+function writeManifest(projectDir, manifest) {
+  writeFileSync(join2(projectDir, MANIFEST_FILE), serializeManifest(manifest));
+}
 function readOnDiskHashes(projectDir, files) {
   const hashes = /* @__PURE__ */ new Map();
   for (const file of files) {
@@ -229,11 +232,11 @@ function readOnDiskHashes(projectDir, files) {
 }
 
 // src/applier/applier.ts
-import { writeFileSync as writeFileSync2 } from "fs";
+import { writeFileSync as writeFileSync3 } from "fs";
 import { join as join4 } from "path";
 
 // src/applier/write.ts
-import { mkdirSync, readFileSync as readFileSync3, writeFileSync } from "fs";
+import { mkdirSync, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
 import { dirname, join as join3 } from "path";
 function writeTemplateFile(projectDir, templateDir, file, projectName, suffix = "") {
   const raw = readFileSync3(join3(templateDir, file.templatePath), "utf8");
@@ -241,7 +244,7 @@ function writeTemplateFile(projectDir, templateDir, file, projectName, suffix =
   const targetPath = file.targetPath + suffix;
   const dest = join3(projectDir, targetPath);
   mkdirSync(dirname(dest), { recursive: true });
-  writeFileSync(dest, content);
+  writeFileSync2(dest, content);
   return targetPath;
 }
 
@@ -280,7 +283,7 @@ function applyPlan(input) {
     categories: input.selection.categories,
     files: entries
   };
-  writeFileSync2(join4(input.projectDir, MANIFEST_FILE), serializeManifest(manifest));
+  writeFileSync3(join4(input.projectDir, MANIFEST_FILE), serializeManifest(manifest));
   return { written, manifest };
 }
 
@@ -426,10 +429,6 @@ async function promptForSelection(projectDir) {
   return { selection, projectName };
 }
 
-// src/applier/update.ts
-import { writeFileSync as writeFileSync3 } from "fs";
-import { join as join7 } from "path";
-
 // src/applier/resolve.ts
 function conflictOps(choice) {
   switch (choice) {
@@ -506,6 +505,10 @@ function applyUpdate(input) {
       entries.push(prior);
     }
   }
+  const covered = new Set(input.files.map((f) => f.targetPath));
+  for (const prior of input.priorManifest.files) {
+    if (!covered.has(prior.path)) entries.push(prior);
+  }
   const manifest = {
     version: input.version,
     agents: input.selection.agents,
@@ -513,10 +516,45 @@ function applyUpdate(input) {
     categories: input.selection.categories,
     files: entries
   };
-  writeFileSync3(join7(input.projectDir, MANIFEST_FILE), serializeManifest(manifest));
+  writeManifest(input.projectDir, manifest);
   return { written, manifest };
 }
 
+// src/applier/prune.ts
+import { existsSync as existsSync3, readFileSync as readFileSync5, rmSync, readdirSync as readdirSync2, rmdirSync } from "fs";
+import { dirname as dirname3, join as join7 } from "path";
+function findOrphans(manifest, catalog) {
+  const inCatalog = new Set(catalog.files.map((f) => f.targetPath));
+  return manifest.files.filter((f) => f.status === "managed" && !inCatalog.has(f.path));
+}
+function pruneOrphans(projectDir, orphans) {
+  const result = { deleted: [], keptEdited: [] };
+  for (const orphan of orphans) {
+    const path = join7(projectDir, orphan.path);
+    if (!existsSync3(path)) continue;
+    if (hashContent(readFileSync5(path, "utf8")) !== orphan.hash) {
+      result.keptEdited.push(orphan.path);
+      continue;
+    }
+    rmSync(path);
+    removeEmptyDirs(projectDir, dirname3(path));
+    result.deleted.push(orphan.path);
+  }
+  const resolved = new Set(orphans.map((o) => o.path));
+  const manifest = readManifest(projectDir);
+  if (manifest) {
+    writeManifest(projectDir, { ...manifest, files: manifest.files.filter((f) => !resolved.has(f.path)) });
+  }
+  return result;
+}
+function removeEmptyDirs(root, dir) {
+  let current = dir;
+  while (current !== root && existsSync3(current) && readdirSync2(current).length === 0) {
+    rmdirSync(current);
+    current = dirname3(current);
+  }
+}
+
 // src/cli.ts
 var EMPTY_SELECTION = { components: [], categories: [], agents: [] };
 function fullSelection() {
@@ -657,31 +695,34 @@ async function runReRun(projectDir) {
   const applicable = {
     actions: prepared.plan.actions.filter((a) => prepared.applyTypes.has(a.type))
   };
+  const orphans = findOrphans(manifest, prepared.catalog);
   const pending = applicable.actions.filter((a) => a.type !== "skip").length;
-  if (pending === 0) {
+  if (pending === 0 && orphans.length === 0) {
     outro("Already up to date \u2014 nothing to do.");
     return;
   }
-  note(formatSummary(summarize(prepared.files, applicable)), mode === "add" ? "This will add" : "This will update");
   const resolutions = /* @__PURE__ */ new Map();
-  const conflicts = applicable.actions.filter((a) => a.type === "conflict");
-  for (const [index, action] of conflicts.entries()) {
-    const choice = bail(
-      await select2({
-        message: `Conflict ${index + 1}/${conflicts.length}: you edited ${action.path}, and a newer version exists.`,
-        options: [
-          { value: "keep-mine", label: "Keep mine", hint: "discard the update for this file" },
-          { value: "overwrite", label: "Use the new version", hint: "replace your file" },
-          { value: "keep-theirs", label: "Keep mine + save theirs", hint: `writes ${basename3(action.path)}.new` }
-        ]
-      })
-    );
-    resolutions.set(action.path, choice);
-  }
-  const proceed = await confirm({ message: `Apply ${pending} changes in ${projectDir}?` });
-  if (isCancel2(proceed) || !proceed) {
-    outro("Nothing written.");
-    return;
+  if (pending > 0) {
+    note(formatSummary(summarize(prepared.files, applicable)), mode === "add" ? "This will add" : "This will update");
+    const conflicts = applicable.actions.filter((a) => a.type === "conflict");
+    for (const [index, action] of conflicts.entries()) {
+      const choice = bail(
+        await select2({
+          message: `Conflict ${index + 1}/${conflicts.length}: you edited ${action.path}, and a newer version exists.`,
+          options: [
+            { value: "keep-mine", label: "Keep mine", hint: "discard the update for this file" },
+            { value: "overwrite", label: "Use the new version", hint: "replace your file" },
+            { value: "keep-theirs", label: "Keep mine + save theirs", hint: `writes ${basename3(action.path)}.new` }
+          ]
+        })
+      );
+      resolutions.set(action.path, choice);
+    }
+    const proceed = await confirm({ message: `Apply ${pending} changes in ${projectDir}?` });
+    if (isCancel2(proceed) || !proceed) {
+      outro("Nothing written.");
+      return;
+    }
   }
   const result = applyUpdate({
     projectDir,
@@ -695,6 +736,16 @@ async function runReRun(projectDir) {
     projectName,
     applyTypes: prepared.applyTypes
   });
+  if (orphans.length > 0) {
+    note(orphans.map((o) => `  ${o.path}`).join("\n"), `${orphans.length} file(s) no longer in the kit`);
+    const doPrune = await confirm({ message: `Delete ${orphans.length} removed file(s) from disk?` });
+    if (!isCancel2(doPrune) && doPrune) {
+      const pruned = pruneOrphans(projectDir, orphans);
+      if (pruned.keptEdited.length > 0) {
+        note(pruned.keptEdited.map((p) => `  ${p}`).join("\n"), "Kept \u2014 you edited these");
+      }
+    }
+  }
   successOutro(mode === "add" ? "Added" : "Updated", result.written.length, prepared.selection);
 }
 async function runInteractive() {
@@ -717,7 +768,7 @@ async function runInteractive() {
     if (!reportConflict(error)) throw error;
   }
 }
-function performReRun(projectDir, mode, addParts) {
+function performReRun(projectDir, mode, addParts, prune) {
   const manifest = readManifest(projectDir);
   if (!manifest) {
     console.error("Not an ai-engineering-kit project (no .ai-kit.json). Run `ai-engineering-kit init` first.");
@@ -725,6 +776,7 @@ function performReRun(projectDir, mode, addParts) {
     return;
   }
   const prepared = prepareReRun({ projectDir, manifest, mode, addParts });
+  const orphans = findOrphans(manifest, prepared.catalog);
   const result = applyUpdate({
     projectDir,
     templateDir: prepared.templateDir,
@@ -739,9 +791,22 @@ function performReRun(projectDir, mode, addParts) {
     applyTypes: prepared.applyTypes
   });
   console.log(`${result.written.length} files written. Edited files were kept (use the interactive flow to resolve).`);
+  if (orphans.length === 0) return;
+  if (prune) {
+    const pruned = pruneOrphans(projectDir, orphans);
+    console.log(`Pruned ${pruned.deleted.length} file(s) no longer in the kit.`);
+    if (pruned.keptEdited.length > 0) {
+      console.log(`Kept ${pruned.keptEdited.length} you edited: ${pruned.keptEdited.join(", ")}`);
+    }
+  } else {
+    console.log(`
+${orphans.length} file(s) are no longer in the kit:`);
+    for (const o of orphans) console.log(`  ${o.path}`);
+    console.log("Run again with --prune to remove them.");
+  }
 }
-function update() {
-  performReRun(process.cwd(), "update", EMPTY_SELECTION);
+function update(args) {
+  performReRun(process.cwd(), "update", EMPTY_SELECTION, args.includes("--prune"));
 }
 function add(args) {
   const addParts = {
@@ -749,20 +814,20 @@ function add(args) {
     categories: parseList(args, "--categories") ?? [],
     agents: parseList(args, "--agents") ?? []
   };
-  performReRun(process.cwd(), "add", addParts);
+  performReRun(process.cwd(), "add", addParts, false);
 }
 async function main(argv) {
   const args = argv.slice(2);
   if (args.includes("--dry-run")) return dryRun(args);
   if (args[0] === "init") return init(args.slice(1));
-  if (args[0] === "update") return update();
+  if (args[0] === "update") return update(args.slice(1));
   if (args[0] === "add") return add(args.slice(1));
   if (args.length === 0) return runInteractive();
   console.log("ai-engineering-kit");
   console.log("\nUsage:");
   console.log("  ai-engineering-kit                 # interactive install or update");
   console.log("  ai-engineering-kit init [--name <project>] [--all | --components a,b --categories x --agents y]");
-  console.log("  ai-engineering-kit update          # refresh installed parts to latest (keeps your edits)");
+  console.log("  ai-engineering-kit update [--prune]  # refresh to latest; --prune removes skills dropped from the kit");
   console.log("  ai-engineering-kit add --components a,b [--categories x] [--agents y]");
   console.log("  ai-engineering-kit --dry-run [--all | --components a,b --categories x --agents y]");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-engineering-kit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "An opinionated, agent-agnostic AI-development kit — disciplined skills plus a structured workspace — installed and updated through one npx command.",
   "type": "module",
   "license": "MIT",

package/template/docs/debt/README.md

@@ -0,0 +1,5 @@
+# Debt
+
+Structured registries of deferred or known work — shortcuts taken, follow-ups owed, known limitations.
+
+Starts empty. Record debt here so it's visible and trackable rather than lost in scattered code comments. Note what was deferred, why, and what would need to change to pay it down.

package/template/docs/operations/README.md

@@ -0,0 +1,5 @@
+# Operations
+
+Runbooks — what a human should do when something needs manual action: incidents, migrations, recovery, routine maintenance.
+
+Starts empty. Add a runbook per procedure, written as numbered steps someone can follow under pressure without re-deriving the process.

package/template/docs/references/README.md

@@ -0,0 +1,5 @@
+# References
+
+How external systems we integrate with work — vendor APIs, protocols, third-party quirks and gotchas.
+
+Starts empty. Add a document per external system as you integrate it, capturing the parts that aren't obvious from the vendor's own docs (auth flows, rate limits, edge cases you hit).

package/template/docs/system/README.md

@@ -0,0 +1,5 @@
+# System
+
+How our own code works — per-flow specs, event/contract conventions, sequence notes.
+
+Starts empty. Promote knowledge here as it stabilises: one document per flow or subsystem, so the next agent (or person) can understand a piece of the system without re-reading all the code.