ai-engineering-kit 0.4.0 → 0.6.0

package/README.md

@@ -7,9 +7,9 @@
 `ai-engineering-kit` scaffolds a repeatable workflow for building software with AI coding agents:
 
 - **Skills** — Markdown playbooks, grouped into categories you pick at install time:
-  - **core-workflow** — kickoff → foundations → PRD → plan → implement → review → verify.
+  - **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

@@ -25,7 +25,7 @@ var CATEGORIES = [
   {
     id: "core-workflow",
     label: "Core workflow",
-    hint: "End-to-end loop: kickoff \u2192 PRD \u2192 plan \u2192 implement \u2192 review \u2192 verify",
+    hint: "End-to-end loop: brainstorm \u2192 PRD \u2192 plan \u2192 implement \u2192 review \u2192 verify",
     from: "skills/core-workflow",
     to: "ai/skills"
   },
@@ -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() {
@@ -593,7 +631,7 @@ function formatSummary(summary) {
 function successOutro(verb, written, selection) {
   if (selection.components.includes("skills")) {
     note(
-      "Open your coding agent in this project and run a skill:\n  setup-foundations   fill in docs/foundations\n  kickoff             brainstorm an MVP",
+      "Open your coding agent in this project and run a skill:\n  setup-foundations   fill in docs/foundations\n  brainstorm          shape the MVP before building",
       "Next steps"
     );
   }
@@ -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.4.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/agents/claude-code.CLAUDE.md

@@ -8,7 +8,7 @@ When a project skill in `ai/skills/` and a global skill share the same name or s
 
 For a freshly scaffolded project, set up the foundations before building:
 
-1. `ai/skills/kickoff/SKILL.md` — brainstorm the MVP (writes to `ai/brainstorms/`).
+1. `ai/skills/brainstorm/SKILL.md` — brainstorm the MVP (writes to `ai/brainstorms/`).
 2. `ai/skills/setup-foundations/SKILL.md` — fill in `docs/foundations/` (vision, technical decisions, code & test guidelines).
 3. `ai/skills/write-prd/SKILL.md` — first PRD.
 4. `ai/skills/plan-feature/SKILL.md` → `ai/skills/implement/SKILL.md` — plan, then build.
@@ -58,8 +58,8 @@ Development artefacts (ephemeral, under `ai/`):
 Project workflows live in `ai/skills/`. Read only the matching `SKILL.md`, not every skill upfront:
 
 - `ai/skills/load-context/SKILL.md` — starting or resuming in-flight work, or when continuity matters
-- `ai/skills/kickoff/SKILL.md` — stress-test or clarify a plan/design through focused questioning
-- `ai/skills/setup-foundations/SKILL.md` — fill in `docs/foundations/` (vision, technical decisions, code & test guidelines) from the kickoff brainstorm; run before the first PRD
+- `ai/skills/brainstorm/SKILL.md` — stress-test or clarify a plan/design through focused questioning
+- `ai/skills/setup-foundations/SKILL.md` — fill in `docs/foundations/` (vision, technical decisions, code & test guidelines) from the brainstorm doc; run before the first PRD
 - `ai/skills/write-prd/SKILL.md` — turn a feature idea into a PRD saved in `ai/prds/`
 - `ai/skills/plan-feature/SKILL.md` — turn a PRD into a phased implementation plan
 - `ai/skills/implement/SKILL.md` — build features or fix bugs with TDD / red-green-refactor

package/template/agents/codex.AGENTS.md

@@ -17,7 +17,7 @@ Non-negotiable:
 
 For a freshly scaffolded project, set up the foundations first:
 
-1. `ai/skills/kickoff/SKILL.md` — brainstorm the MVP (writes to `ai/brainstorms/`).
+1. `ai/skills/brainstorm/SKILL.md` — brainstorm the MVP (writes to `ai/brainstorms/`).
 2. `ai/skills/setup-foundations/SKILL.md` — fill in `docs/foundations/` (vision, technical decisions, code & test guidelines).
 3. `ai/skills/write-prd/SKILL.md` — first PRD, then `plan-feature` and `implement`.
 
@@ -28,8 +28,8 @@ Project workflows live in `ai/skills/`. If a project workflow and a global Codex
 Read only the matching `SKILL.md`, not every skill upfront:
 
 - `ai/skills/load-context/SKILL.md` — starting or resuming in-flight work, or when continuity matters.
-- `ai/skills/kickoff/SKILL.md` — stress-test or clarify a plan/design through focused questioning.
-- `ai/skills/setup-foundations/SKILL.md` — fill in `docs/foundations/` from the kickoff brainstorm; run before the first PRD.
+- `ai/skills/brainstorm/SKILL.md` — stress-test or clarify a plan/design through focused questioning.
+- `ai/skills/setup-foundations/SKILL.md` — fill in `docs/foundations/` from the brainstorm doc; run before the first PRD.
 - `ai/skills/write-prd/SKILL.md` — turn a feature idea into a PRD saved in `ai/prds/`.
 - `ai/skills/plan-feature/SKILL.md` — turn a PRD into a phased implementation plan.
 - `ai/skills/implement/SKILL.md` — build features or fix bugs with TDD/red-green-refactor.

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.

package/template/skills/core-workflow/{kickoff → brainstorm}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: kickoff
-description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to start a plan, kick off a feature or refactor, stress-test a design, or mentions "grill me".
+name: brainstorm
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to start a plan, brainstorm a feature or refactor, stress-test a design, or mentions "grill me".
 ---
 
 Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

package/template/skills/core-workflow/setup-foundations/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: setup-foundations
-description: Define a new project's foundation docs — product vision, seed technical decisions, code guidelines, and testing principles — through a guided interview that reads the kickoff brainstorm. Use right after kickoff and before the first PRD, or when a project's docs/foundations/ are still stubs.
+description: Define a new project's foundation docs — product vision, seed technical decisions, code guidelines, and testing principles — through a guided interview that reads the brainstorm doc. Use right after `brainstorm` and before the first PRD, or when a project's docs/foundations/ are still stubs.
 ---
 
 # Setup Foundations
 
-Run once near the start of a project — after `kickoff` and before `write-prd` —
+Run once near the start of a project — after `brainstorm` and before `write-prd` —
 to turn the empty `docs/foundations/` stubs into real, project-specific docs.
 Works for any stack; never assume TypeScript/Node.
 
@@ -31,7 +31,7 @@ instead of asking.
 ### 1. docs/foundations/product-vision.md
 
 Confirm and fill: what we're building, users, core surfaces, constraints, out of
-scope. Distil from the kickoff brainstorm; ask only where it is silent or ambiguous.
+scope. Distil from the brainstorm doc; ask only where it is silent or ambiguous.
 
 ### 2. docs/foundations/technical-decisions.md
 

package/template/skills/engineering/{grill-with-docs → discovery}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: grill-with-docs
-description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.
+name: discovery
+description: Deep discovery interview that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use at the start of a feature to establish shared understanding, or to stress-test a plan against your project's language and documented decisions.
 ---
 
 <what-to-do>

package/template/skills/engineering/improve-codebase-architecture/SKILL.md

@@ -75,7 +75,7 @@ Once the user picks a candidate, drop into a grilling conversation. Walk the des
 
 Side effects happen inline as decisions crystallize:
 
-- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/grill-with-docs` (see [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist.
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/discovery` (see [CONTEXT-FORMAT.md](../discovery/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist.
 - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
-- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md).
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../discovery/ADR-FORMAT.md).
 - **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).

package/template/skills/engineering/setup-matt-pocock-skills/SKILL.md

@@ -1,121 +0,0 @@
----
-name: setup-matt-pocock-skills
-description: Sets up an `## Agent skills` block in AGENTS.md/CLAUDE.md and `docs/agents/` so the engineering skills know this repo's issue tracker (GitHub or local markdown), triage label vocabulary, and domain doc layout. Run before first use of `to-issues`, `to-prd`, `triage`, `diagnose`, `tdd`, `improve-codebase-architecture`, or `zoom-out` — or if those skills appear to be missing context about the issue tracker, triage labels, or domain docs.
-disable-model-invocation: true
----
-
-# Setup Matt Pocock's Skills
-
-Scaffold the per-repo configuration that the engineering skills assume:
-
-- **Issue tracker** — where issues live (GitHub by default; local markdown is also supported out of the box)
-- **Triage labels** — the strings used for the five canonical triage roles
-- **Domain docs** — where `CONTEXT.md` and ADRs live, and the consumer rules for reading them
-
-This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.
-
-## Process
-
-### 1. Explore
-
-Look at the current repo to understand its starting state. Read whatever exists; don't assume:
-
-- `git remote -v` and `.git/config` — is this a GitHub repo? Which one?
-- `AGENTS.md` and `CLAUDE.md` at the repo root — does either exist? Is there already an `## Agent skills` section in either?
-- `CONTEXT.md` and `CONTEXT-MAP.md` at the repo root
-- `docs/adr/` and any `src/*/docs/adr/` directories
-- `docs/agents/` — does this skill's prior output already exist?
-- `.scratch/` — sign that a local-markdown issue tracker convention is already in use
-
-### 2. Present findings and ask
-
-Summarise what's present and what's missing. Then walk the user through the three decisions **one at a time** — present a section, get the user's answer, then move to the next. Don't dump all three at once.
-
-Assume the user does not know what these terms mean. Each section starts with a short explainer (what it is, why these skills need it, what changes if they pick differently). Then show the choices and the default.
-
-**Section A — Issue tracker.**
-
-> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-issues`, `triage`, `to-prd`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
-
-Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose that. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer:
-
-- **GitHub** — issues live in the repo's GitHub Issues (uses the `gh` CLI)
-- **GitLab** — issues live in the repo's GitLab Issues (uses the [`glab`](https://gitlab.com/gitlab-org/cli) CLI)
-- **Local markdown** — issues live as files under `.scratch/<feature>/` in this repo (good for solo projects or repos without a remote)
-- **Other** (Jira, Linear, etc.) — ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose
-
-**Section B — Triage label vocabulary.**
-
-> Explainer: When the `triage` skill processes an incoming issue, it moves it through a state machine — needs evaluation, waiting on reporter, ready for an AFK agent to pick up, ready for a human, or won't fix. To do that, it needs to apply labels (or the equivalent in your issue tracker) that match strings *you've actually configured*. If your repo already uses different label names (e.g. `bug:triage` instead of `needs-triage`), map them here so the skill applies the right ones instead of creating duplicates.
-
-The five canonical roles:
-
-- `needs-triage` — maintainer needs to evaluate
-- `needs-info` — waiting on reporter
-- `ready-for-agent` — fully specified, AFK-ready (an agent can pick it up with no human context)
-- `ready-for-human` — needs human implementation
-- `wontfix` — will not be actioned
-
-Default: each role's string equals its name. Ask the user if they want to override any. If their issue tracker has no existing labels, the defaults are fine.
-
-**Section C — Domain docs.**
-
-> Explainer: Some skills (`improve-codebase-architecture`, `diagnose`, `tdd`) read a `CONTEXT.md` file to learn the project's domain language, and `docs/adr/` for past architectural decisions. They need to know whether the repo has one global context or multiple (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place.
-
-Confirm the layout:
-
-- **Single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. Most repos are this.
-- **Multi-context** — `CONTEXT-MAP.md` at the root pointing to per-context `CONTEXT.md` files (typically a monorepo).
-
-### 3. Confirm and edit
-
-Show the user a draft of:
-
-- The `## Agent skills` block to add to whichever of `CLAUDE.md` / `AGENTS.md` is being edited (see step 4 for selection rules)
-- The contents of `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, `docs/agents/domain.md`
-
-Let them edit before writing.
-
-### 4. Write
-
-**Pick the file to edit:**
-
-- If `CLAUDE.md` exists, edit it.
-- Else if `AGENTS.md` exists, edit it.
-- If neither exists, ask the user which one to create — don't pick for them.
-
-Never create `AGENTS.md` when `CLAUDE.md` already exists (or vice versa) — always edit the one that's already there.
-
-If an `## Agent skills` block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.
-
-The block:
-
-```markdown
-## Agent skills
-
-### Issue tracker
-
-[one-line summary of where issues are tracked]. See `docs/agents/issue-tracker.md`.
-
-### Triage labels
-
-[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.
-
-### Domain docs
-
-[one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.
-```
-
-Then write the three docs files using the seed templates in this skill folder as a starting point:
-
-- [issue-tracker-github.md](./issue-tracker-github.md) — GitHub issue tracker
-- [issue-tracker-gitlab.md](./issue-tracker-gitlab.md) — GitLab issue tracker
-- [issue-tracker-local.md](./issue-tracker-local.md) — local-markdown issue tracker
-- [triage-labels.md](./triage-labels.md) — label mapping
-- [domain.md](./domain.md) — domain doc consumer rules + layout
-
-For "other" issue trackers, write `docs/agents/issue-tracker.md` from scratch using the user's description.
-
-### 5. Done
-
-Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit `docs/agents/*.md` directly later — re-running this skill is only necessary if they want to switch issue trackers or restart from scratch.

package/template/skills/engineering/setup-matt-pocock-skills/domain.md

@@ -1,51 +0,0 @@
-# Domain Docs
-
-How the engineering skills should consume this repo's domain documentation when exploring the codebase.
-
-## Before exploring, read these
-
-- **`CONTEXT.md`** at the repo root, or
-- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
-- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
-
-If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved.
-
-## File structure
-
-Single-context repo (most repos):
-
-```
-/
-├── CONTEXT.md
-├── docs/adr/
-│   ├── 0001-event-sourced-orders.md
-│   └── 0002-postgres-for-write-model.md
-└── src/
-```
-
-Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
-
-```
-/
-├── CONTEXT-MAP.md
-├── docs/adr/                          ← system-wide decisions
-└── src/
-    ├── ordering/
-    │   ├── CONTEXT.md
-    │   └── docs/adr/                  ← context-specific decisions
-    └── billing/
-        ├── CONTEXT.md
-        └── docs/adr/
-```
-
-## Use the glossary's vocabulary
-
-When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
-
-If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/grill-with-docs`).
-
-## Flag ADR conflicts
-
-If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
-
-> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/template/skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md

@@ -1,22 +0,0 @@
-# Issue tracker: GitHub
-
-Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
-
-## Conventions
-
-- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
-- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
-- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
-- **Comment on an issue**: `gh issue comment <number> --body "..."`
-- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
-- **Close**: `gh issue close <number> --comment "..."`
-
-Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
-
-## When a skill says "publish to the issue tracker"
-
-Create a GitHub issue.
-
-## When a skill says "fetch the relevant ticket"
-
-Run `gh issue view <number> --comments`.