ai-engineering-kit 0.3.0 → 0.5.0

package/README.md

@@ -7,7 +7,7 @@
 `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.
 - **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.

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { basename as basename2 } from "path";
-import { intro, outro, confirm, select, isCancel as isCancel2, cancel as cancel2, log } from "@clack/prompts";
+import { basename as basename3 } from "path";
+import { intro, outro, confirm, select as select2, isCancel as isCancel2, cancel as cancel2, note } from "@clack/prompts";
 
 // src/catalog/load.ts
 import { readdirSync, readFileSync } from "fs";
@@ -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"
   },
@@ -162,6 +162,31 @@ function resolveSelection(catalog, selection) {
   });
 }
 
+// src/menu/summary.ts
+import { basename } from "path";
+var labelOf = (id) => COMPONENTS.find((c) => c.id === id)?.label ?? id;
+function summarize(files, plan) {
+  const byPath = new Map(files.map((f) => [f.targetPath, f]));
+  const groups = /* @__PURE__ */ new Map();
+  const conflicts = [];
+  let written = 0;
+  for (const action of plan.actions) {
+    if (action.type === "conflict") {
+      conflicts.push(action.path);
+      continue;
+    }
+    if (action.type !== "add" && action.type !== "refresh") continue;
+    const file = byPath.get(action.path);
+    if (!file) continue;
+    written++;
+    const group = groups.get(file.component) ?? groups.set(file.component, { component: file.component, label: labelOf(file.component), count: 0, names: [] }).get(file.component);
+    group.count++;
+    if (file.component === "entry-files") group.names.push(basename(file.targetPath));
+  }
+  const ordered = COMPONENTS.map((c) => groups.get(c.id)).filter((g) => g !== void 0);
+  return { groups: ordered, conflicts, written };
+}
+
 // src/planner/planner.ts
 function planInstall(input) {
   const files = resolveSelection(input.catalog, input.selection);
@@ -338,8 +363,8 @@ On Windows, enable Developer Mode (or run as admin) and re-run, or point Claude
 }
 
 // src/menu/prompt.ts
-import { basename } from "path";
-import { multiselect, text, isCancel, cancel } from "@clack/prompts";
+import { basename as basename2 } from "path";
+import { select, multiselect, text, isCancel, cancel } from "@clack/prompts";
 
 // src/menu/menu.ts
 function componentOptions() {
@@ -351,6 +376,13 @@ function categoryOptions() {
 function agentOptions() {
   return AGENTS.map((a) => ({ value: a.id, label: a.label, hint: a.hint }));
 }
+function presetSelection(preset) {
+  return {
+    components: COMPONENTS.map((c) => c.id),
+    categories: preset === "everything" ? CATEGORIES.map((c) => c.id) : ["core-workflow"],
+    agents: AGENTS.map((a) => a.id)
+  };
+}
 function buildSelection(answers) {
   return {
     components: answers.components,
@@ -367,35 +399,31 @@ function required(value) {
   }
   return value;
 }
-var allValues = (options) => options.map((o) => o.value);
-async function pickAll(message, options) {
-  return required(
-    await multiselect({
-      message: `${message} (everything is pre-selected \u2014 toggle off what you don't want)`,
-      options,
-      initialValues: allValues(options),
-      required: true
-    })
-  );
+async function pick(message, options) {
+  return required(await multiselect({ message, options, required: true }));
+}
+async function chooseSelection() {
+  const components = await pick("Select parts to install", componentOptions());
+  const categories = components.includes("skills") ? await pick("Select skill categories", categoryOptions()) : [];
+  const agents = components.includes("entry-files") ? await pick("Select coding agents", agentOptions()) : [];
+  return buildSelection({ components, categories, agents });
 }
 async function promptForSelection(projectDir) {
-  const components = await pickAll("Which parts do you want to install?", componentOptions());
-  let categories = [];
-  if (components.includes("skills")) {
-    categories = await pickAll("Which skill categories?", categoryOptions());
-  }
-  let agents = [];
-  if (components.includes("entry-files")) {
-    agents = await pickAll("Which coding agents?", agentOptions());
-  }
-  const projectName = required(
-    await text({
-      message: "Project name",
-      defaultValue: basename(projectDir),
-      placeholder: basename(projectDir)
+  const mode = required(
+    await select({
+      message: `How do you want to set up ${basename2(projectDir)}?`,
+      options: [
+        { value: "everything", label: "Everything", hint: "all skills, docs, and workspace \u2014 Claude Code + Codex" },
+        { value: "core", label: "Core skills only", hint: "core-workflow skills, docs, and workspace \u2014 both agents" },
+        { value: "choose", label: "Choose what to install\u2026", hint: "pick components, skill categories, and agents" }
+      ]
     })
   );
-  return { selection: buildSelection({ components, categories, agents }), projectName };
+  const selection = mode === "choose" ? await chooseSelection() : presetSelection(mode);
+  const projectName = selection.components.includes("entry-files") ? required(
+    await text({ message: "Project name", defaultValue: basename2(projectDir), placeholder: basename2(projectDir) })
+  ) : basename2(projectDir);
+  return { selection, projectName };
 }
 
 // src/applier/update.ts
@@ -547,7 +575,29 @@ function planFor(projectDir, selection) {
     onDisk: readOnDiskHashes(projectDir, files),
     manifest: readManifest(projectDir)
   });
-  return { catalog, plan };
+  return { catalog, files, plan };
+}
+function formatSummary(summary) {
+  if (summary.written === 0 && summary.conflicts.length === 0) return "Everything is already up to date.";
+  const width = Math.max(0, ...summary.groups.map((g) => g.label.length));
+  const lines = summary.groups.map((g) => {
+    const detail = g.names.length > 0 ? g.names.join(", ") : String(g.count);
+    return `  ${g.label.padEnd(width)}  ${detail}`;
+  });
+  if (summary.conflicts.length > 0) {
+    lines.push("", `Conflicts \u2014 you edited these (you'll choose per file):`);
+    for (const path of summary.conflicts) lines.push(`  ${path}`);
+  }
+  return lines.join("\n");
+}
+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  brainstorm          shape the MVP before building",
+      "Next steps"
+    );
+  }
+  outro(`${verb} ${written} file${written === 1 ? "" : "s"}.`);
 }
 function reportConflict(error) {
   if (!(error instanceof ApplyConflictError)) return false;
@@ -567,7 +617,7 @@ function dryRun(args) {
 function init(args) {
   const projectDir = process.cwd();
   const selection = selectionFromArgs(args);
-  const projectName = parseValue(args, "--name") ?? basename2(projectDir);
+  const projectName = parseValue(args, "--name") ?? basename3(projectDir);
   try {
     const result = runInit({ projectDir, selection, projectName });
     console.log(`ai-engineering-kit ${kitVersion()} installed into ${projectDir}`);
@@ -587,7 +637,7 @@ async function runReRun(projectDir) {
   const manifest = readManifest(projectDir);
   intro(`ai-engineering-kit ${kitVersion()} \u2014 already installed`);
   const mode = bail(
-    await select({
+    await select2({
       message: "What would you like to do?",
       options: [
         { value: "update", label: "Update installed parts to latest" },
@@ -597,7 +647,7 @@ async function runReRun(projectDir) {
     })
   );
   let addParts = EMPTY_SELECTION;
-  let projectName = basename2(projectDir);
+  let projectName = basename3(projectDir);
   if (mode === "add" || mode === "both") {
     const picked = await promptForSelection(projectDir);
     addParts = picked.selection;
@@ -607,24 +657,27 @@ async function runReRun(projectDir) {
   const applicable = {
     actions: prepared.plan.actions.filter((a) => prepared.applyTypes.has(a.type))
   };
-  log.message(formatPlan(applicable));
+  const pending = applicable.actions.filter((a) => a.type !== "skip").length;
+  if (pending === 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();
-  if (prepared.applyTypes.has("conflict")) {
-    for (const action of applicable.actions.filter((a) => a.type === "conflict")) {
-      const choice = bail(
-        await select({
-          message: `You edited ${action.path}. A newer version exists.`,
-          options: [
-            { value: "keep-mine", label: "Keep mine" },
-            { value: "overwrite", label: "Overwrite with the new version" },
-            { value: "keep-theirs", label: "Keep mine, save theirs as .new" }
-          ]
-        })
-      );
-      resolutions.set(action.path, choice);
-    }
+  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 pending = applicable.actions.filter((a) => a.type !== "skip").length;
   const proceed = await confirm({ message: `Apply ${pending} changes in ${projectDir}?` });
   if (isCancel2(proceed) || !proceed) {
     outro("Nothing written.");
@@ -642,24 +695,24 @@ async function runReRun(projectDir) {
     projectName,
     applyTypes: prepared.applyTypes
   });
-  outro(`Done. ${result.written.length} files written.`);
+  successOutro(mode === "add" ? "Added" : "Updated", result.written.length, prepared.selection);
 }
 async function runInteractive() {
   const projectDir = process.cwd();
   if (readManifest(projectDir)) return runReRun(projectDir);
   intro(`ai-engineering-kit ${kitVersion()}`);
   const { selection, projectName } = await promptForSelection(projectDir);
-  const { plan } = planFor(projectDir, selection);
-  log.message(formatPlan(plan));
+  const { files, plan } = planFor(projectDir, selection);
+  note(formatSummary(summarize(files, plan)), "This will add");
   const pending = plan.actions.filter((a) => a.type !== "skip").length;
-  const proceed = await confirm({ message: `Scaffold ${pending} files into ${projectDir}?` });
+  const proceed = await confirm({ message: `Install ${pending} files into ${projectDir}?` });
   if (isCancel2(proceed) || !proceed) {
     outro("Nothing written.");
     return;
   }
   try {
     const result = runInit({ projectDir, selection, projectName });
-    outro(`Installed ${result.written.length} files into ${projectDir}.`);
+    successOutro("Installed", result.written.length, selection);
   } catch (error) {
     if (!reportConflict(error)) throw error;
   }
@@ -682,7 +735,7 @@ function performReRun(projectDir, mode, addParts) {
     priorManifest: manifest,
     selection: prepared.selection,
     version: prepared.version,
-    projectName: basename2(projectDir),
+    projectName: basename3(projectDir),
     applyTypes: prepared.applyTypes
   });
   console.log(`${result.written.length} files written. Edited files were kept (use the interactive flow to resolve).`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-engineering-kit",
-  "version": "0.3.0",
+  "version": "0.5.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/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`.

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

@@ -1,23 +0,0 @@
-# Issue tracker: GitLab
-
-Issues and PRDs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.
-
-## Conventions
-
-- **Create an issue**: `glab issue create --title "..." --description "..."`. Use a heredoc for multi-line descriptions. Pass `--description -` to open an editor.
-- **Read an issue**: `glab issue view <number> --comments`. Use `-F json` for machine-readable output.
-- **List issues**: `glab issue list -F json` with appropriate `--label` filters.
-- **Comment on an issue**: `glab issue note <number> --message "..."`. GitLab calls comments "notes".
-- **Apply / remove labels**: `glab issue update <number> --label "..."` / `--unlabel "..."`. Multiple labels can be comma-separated or by repeating the flag.
-- **Close**: `glab issue close <number>`. `glab issue close` does not accept a closing comment, so post the explanation first with `glab issue note <number> --message "..."`, then close.
-- **Merge requests**: GitLab calls PRs "merge requests". Use `glab mr create`, `glab mr view`, `glab mr note`, etc. — the same shape as `gh pr ...` with `mr` in place of `pr` and `note`/`--message` in place of `comment`/`--body`.
-
-Infer the repo from `git remote -v` — `glab` does this automatically when run inside a clone.
-
-## When a skill says "publish to the issue tracker"
-
-Create a GitLab issue.
-
-## When a skill says "fetch the relevant ticket"
-
-Run `glab issue view <number> --comments`.

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

@@ -1,19 +0,0 @@
-# Issue tracker: Local Markdown
-
-Issues and PRDs for this repo live as markdown files in `.scratch/`.
-
-## Conventions
-
-- One feature per directory: `.scratch/<feature-slug>/`
-- The PRD is `.scratch/<feature-slug>/PRD.md`
-- Implementation issues are `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`
-- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
-- Comments and conversation history append to the bottom of the file under a `## Comments` heading
-
-## When a skill says "publish to the issue tracker"
-
-Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
-
-## When a skill says "fetch the relevant ticket"
-
-Read the file at the referenced path. The user will normally pass the path or the issue number directly.