nitm-ai-dev-toolkit 5.1.2 → 5.2.0

package/bin/relevance.js

@@ -0,0 +1,306 @@
+'use strict';
+
+// Relevance-aware patch and doctor. This module decides; bin/cli.js plans and writes.
+//   - .nitm/retired.json: paths the project retired (never re-added) and an optional tracker override
+//   - detectProject(): trackers, Playwright, Prisma, UI and stack facts read from the project
+//   - relevanceOf(): add | irrelevant | review for one template path
+//   - auditWrapper(): whether a harness wrapper is thin (link to its snippet plus key points) or inlines policy
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const RETIRED_FILE = path.join('.nitm', 'retired.json');
+const TRACKERS = ['github', 'gitlab', 'bitbucket', 'jira', 'linear'];
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const MAX_KEY_POINTS = 5;
+const MAX_SUMMARY_WORDS = 30;
+
+// Tracker CLI skills ship only for the tracker they talk to. gh-cli also covers GitHub pull requests.
+const TRACKER_SKILLS = { 'gh-cli': 'github', 'glab-cli': 'gitlab', 'bkt-cli': 'bitbucket', acli: 'jira', 'linear-cli': 'linear' };
+// Files named after a tool or stack. They apply only when that tool or stack is detected.
+const STEM_TOPICS = {
+  'playwright-test': 'playwright',
+  'prisma-migrations': 'prisma',
+  'component-structure': 'ui',
+  'ui-accessibility': 'ui',
+};
+const TOPIC_NOTES = {
+  playwright: 'no Playwright setup detected',
+  prisma: 'no Prisma setup detected',
+  ui: 'no UI framework detected',
+};
+// Empty MCP templates ship no servers, so a missing copy adds nothing.
+const MCP_TEMPLATES = ['.mcp.json', '.cursor/mcp.json', '.vscode/mcp.json'];
+
+const HOST_TRACKERS = { 'github.com': 'github', 'gitlab.com': 'gitlab', 'bitbucket.org': 'bitbucket' };
+const UI_DEPS = ['react', 'react-dom', 'react-native', 'expo', 'next', 'vue', 'nuxt', 'svelte', '@sveltejs/kit',
+  '@angular/core', 'solid-js', 'astro', 'preact'];
+const PLAYWRIGHT_DEPS = ['playwright', '@playwright/test'];
+const PLAYWRIGHT_CONFIGS = ['playwright.config.ts', 'playwright.config.js', 'playwright.config.mjs', 'playwright.config.cjs'];
+const PRISMA_DEPS = ['prisma', '@prisma/client'];
+const PRISMA_FILES = ['schema.prisma', path.join('prisma', 'schema.prisma')];
+// Root manifests that prove a stack exists (for ui decisions) and that may name Playwright.
+const STACK_MANIFESTS = ['package.json', 'pyproject.toml', 'requirements.txt', 'setup.py', 'composer.json',
+  'go.mod', 'Cargo.toml', 'Gemfile', 'pom.xml', 'build.gradle', 'build.gradle.kts'];
+
+// Harness wrappers and the shared source each one links to. Snippets hold the policy; a skill with the
+// same name (orient-to-recent-work) is the source when no snippet exists.
+const WRAPPER_KINDS = [
+  { dir: '.claude/rules', snippets: 'rules-snippets' },
+  { dir: '.claude/commands', snippets: 'prompt-snippets' },
+  { dir: '.claude/agents', snippets: 'agents-snippets' },
+  { dir: '.cursor/rules', snippets: 'rules-snippets' },
+  { dir: '.cursor/commands', snippets: 'prompt-snippets' },
+  { dir: '.cursor/agents', snippets: 'agents-snippets' },
+  { dir: '.github/instructions', snippets: 'rules-snippets' },
+  { dir: '.github/prompts', snippets: 'prompt-snippets' },
+  { dir: '.github/agents', snippets: 'agents-snippets' },
+  { dir: '.opencode/rules', snippets: 'rules-snippets' },
+  { dir: '.opencode/commands', snippets: 'prompt-snippets' },
+  { dir: '.opencode/agents', snippets: 'agents-snippets' },
+];
+
+function readJsonFile(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return null; }
+}
+
+function readText(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch (_) { return ''; }
+}
+
+// ---- retirement list ----
+
+// Canonical form: forward slashes, no leading ./, no doubled or inner / segments, no trailing /. Climbing
+// segments and absolute paths are refused on the raw input, before normalising could fold them away.
+function safeRetiredPath(value, where) {
+  const raw = typeof value === 'string' ? value.replace(/\\/g, '/') : '';
+  const absolute = path.posix.isAbsolute(raw) || path.win32.isAbsolute(raw);
+  const climbs = raw.split('/').includes('..');
+  const rel = raw ? path.posix.normalize(raw).replace(/^(\.\/)+/, '').replace(/\/+$/, '') : '';
+  if (!rel || rel === '.' || absolute || climbs) {
+    throw new Error(`${where}.path must be a relative path inside the project (got ${JSON.stringify(value)})`);
+  }
+  return rel;
+}
+
+function normalizeRetired(entry, index) {
+  const where = `${RETIRED_FILE} retired[${index}]`;
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw new Error(`${where} must be an object with path, reason and date`);
+  }
+  const rel = safeRetiredPath(entry.path, where);
+  if (typeof entry.reason !== 'string' || !entry.reason.trim()) {
+    throw new Error(`${where}.reason is required: say why the file was retired`);
+  }
+  if (typeof entry.date !== 'string' || !DATE_RE.test(entry.date)) {
+    throw new Error(`${where}.date is required as YYYY-MM-DD`);
+  }
+  return { path: rel, reason: entry.reason.trim(), date: entry.date };
+}
+
+// Reads .nitm/retired.json. Absent means nothing retired. A file that exists but is invalid throws, so
+// patch never falls back to re-adding files the project retired.
+function readRetired(cwd) {
+  const p = path.join(cwd, RETIRED_FILE);
+  if (!fs.existsSync(p)) return { trackers: undefined, entries: [] };
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (ex) {
+    throw new Error(`${RETIRED_FILE} exists but is not valid JSON (${ex.message}). Fix or remove it; nothing was written.`);
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    throw new Error(`${RETIRED_FILE} must be a JSON object with "retired" and optional "trackers"`);
+  }
+  let trackers;
+  if (data.trackers !== undefined && data.trackers !== null) {
+    if (!Array.isArray(data.trackers) || data.trackers.some((t) => !TRACKERS.includes(t))) {
+      throw new Error(`${RETIRED_FILE}: "trackers" must be a list drawn from ${TRACKERS.join(', ')} (use [] for none)`);
+    }
+    trackers = [...new Set(data.trackers)];
+  }
+  const list = data.retired === undefined ? [] : data.retired;
+  if (!Array.isArray(list)) throw new Error(`${RETIRED_FILE}: "retired" must be a list`);
+  return { trackers, entries: list.map(normalizeRetired) };
+}
+
+// The retirement entry covering a template path (exact file, or any file under a retired directory).
+function retiredFor(key, entries) {
+  return entries.find((e) => key === e.path || key.startsWith(e.path + '/')) || null;
+}
+
+// ---- project facts ----
+
+// package.json at the root and one level down (apps/*, packages/*), so monorepo dependencies count.
+function packageJsons(cwd) {
+  const out = [];
+  const pkg = readJsonFile(path.join(cwd, 'package.json'));
+  if (pkg) out.push(pkg);
+  for (const parent of ['apps', 'packages']) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(path.join(cwd, parent), { withFileTypes: true });
+    } catch (_) { continue; }
+    for (const e of entries) {
+      const child = readJsonFile(path.join(cwd, parent, e.name, 'package.json'));
+      if (e.isDirectory() && child) out.push(child);
+    }
+  }
+  return out;
+}
+
+function dependencyNames(cwd) {
+  const names = new Set();
+  for (const pkg of packageJsons(cwd)) {
+    for (const name of [...Object.keys(pkg.dependencies || {}), ...Object.keys(pkg.devDependencies || {})]) {
+      names.add(name);
+    }
+  }
+  return names;
+}
+
+// The tracker implied by the git origin host, or null when there is no origin or the host is unknown.
+function remoteTrackers(cwd) {
+  let url;
+  try {
+    url = execFileSync('git', ['-C', cwd, 'remote', 'get-url', 'origin'],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).trim();
+  } catch (_) {
+    return null;
+  }
+  const match = url.match(/^(?:[a-z][a-z0-9+.-]*:\/\/)?(?:[^@/]+@)?([^/:]+)/i);
+  const tracker = match && HOST_TRACKERS[match[1].toLowerCase()];
+  return tracker ? [tracker] : null;
+}
+
+// Facts the relevance rules read. `trackers` is null when unknown (the rules then ask for a decision),
+// an array otherwise (possibly empty when the project has no tracker).
+function detectProject(cwd, retired) {
+  const deps = dependencyNames(cwd);
+  const rootManifests = STACK_MANIFESTS.map((f) => readText(path.join(cwd, f))).join('\n').toLowerCase();
+  const configured = retired && retired.trackers !== undefined;
+  const trackers = configured ? retired.trackers : remoteTrackers(cwd);
+  const trackerSource = configured ? `configured in ${RETIRED_FILE}` : (trackers ? 'git origin' : 'not detected');
+  return {
+    trackers,
+    trackerSource,
+    playwright: PLAYWRIGHT_DEPS.some((d) => deps.has(d)) || /playwright/.test(rootManifests)
+      || PLAYWRIGHT_CONFIGS.some((f) => fs.existsSync(path.join(cwd, f))),
+    prisma: PRISMA_DEPS.some((d) => deps.has(d)) || PRISMA_FILES.some((f) => fs.existsSync(path.join(cwd, f))),
+    ui: UI_DEPS.some((d) => deps.has(d)),
+    stackKnown: STACK_MANIFESTS.some((f) => fs.existsSync(path.join(cwd, f))),
+  };
+}
+
+// ---- relevance ----
+
+// What a template path depends on: 'tracker:<name>', 'playwright', 'prisma', 'ui', 'mcp', or null (generic).
+function topicOf(rel) {
+  const n = rel.split(path.sep).join('/');
+  if (MCP_TEMPLATES.includes(n)) return 'mcp';
+  const skill = /^\.agents\/skills\/([^/]+)\//.exec(n);
+  if (skill && TRACKER_SKILLS[skill[1]]) return `tracker:${TRACKER_SKILLS[skill[1]]}`;
+  return STEM_TOPICS[path.posix.basename(n).split('.')[0]] || null;
+}
+
+// 'add' applies to the project; 'irrelevant' does not (never added); 'review' cannot be decided from the
+// project yet (never added until someone decides).
+function relevanceOf(rel, facts) {
+  const topic = topicOf(rel);
+  if (!topic) return { status: 'add', reason: '' };
+  if (topic === 'mcp') return { status: 'irrelevant', reason: 'empty MCP template, no servers configured' };
+  if (topic.startsWith('tracker:')) {
+    const tracker = topic.slice('tracker:'.length);
+    if (facts.trackers === null) {
+      return { status: 'review', reason: `tracker not detected; set "trackers" in ${RETIRED_FILE}` };
+    }
+    if (facts.trackers.includes(tracker)) return { status: 'add', reason: '' };
+    return { status: 'irrelevant', reason: `project tracker is ${facts.trackers.join(', ') || 'none'}` };
+  }
+  const detected = { playwright: facts.playwright, prisma: facts.prisma, ui: facts.ui }[topic];
+  if (detected) return { status: 'add', reason: '' };
+  if (topic === 'ui' && !facts.stackKnown) return { status: 'review', reason: 'no stack manifest found' };
+  return { status: 'irrelevant', reason: TOPIC_NOTES[topic] };
+}
+
+// ---- thin wrappers ----
+
+// The wrapper's kind and the sources it must link to: its snippet, then a same-named skill.
+function wrapperSources(rel) {
+  const n = rel.split(path.sep).join('/');
+  const kind = WRAPPER_KINDS.find((k) => n.startsWith(k.dir + '/') && !n.slice(k.dir.length + 1).includes('/'));
+  if (!kind) return null;
+  const base = path.posix.basename(n);
+  const name = base.replace(/\.(agent|instructions|prompt)\.md$/, '').replace(/\.mdc$/, '').replace(/\.md$/, '');
+  const snippet = `.claude/${kind.snippets}/${name}.md`;
+  const skill = `.agents/skills/${name}/SKILL.md`;
+  return [{ rel: snippet, needle: `${kind.snippets}/${name}.md` }, { rel: skill, needle: skill }];
+}
+
+function bodyOf(content) {
+  if (!content.startsWith('---\n')) return content;
+  const end = content.indexOf('\n---', 3); // the closing delimiter; empty frontmatter ("---\n---") included
+  return end < 0 ? content : content.slice(end + 4);
+}
+
+// `targets` are the sources that exist in the project, each as { rel, needle }.
+// thin: links a source, with at most one short summary line, a few key points and no table or other policy
+// text; inlined: more prose, a table or too many key points outside the link; diverged: links no existing source.
+function auditWrapper(content, targets) {
+  const linked = targets.find((t) => bodyOf(content).includes(t.needle));
+  if (!linked) return { status: 'diverged', reason: `does not link ${targets.map((t) => t.rel).join(' or ')}` };
+  const prose = [];
+  let bullets = 0;
+  // "Agent Dispatch" names the agent to activate and "Arguments" the command syntax: both are activation metadata.
+  let metadata = false;
+  for (const raw of bodyOf(content).split('\n')) {
+    const line = raw.trim();
+    if (/^#+\s/.test(line)) { metadata = /^#+\s+(agent dispatch|arguments)\b/i.test(line); continue; }
+    if (metadata || line === '$ARGUMENTS') continue;
+    if (!line || line.startsWith('>') || line.includes(linked.needle)) continue;
+    if (/^([-*]|\d+\.)\s/.test(line)) { bullets++; continue; }
+    if (/:$/.test(line) && line.split(/\s+/).length <= 3) continue; // a label such as "Key points:"
+    prose.push(line);
+  }
+  const summaryOnly = prose.length === 1 && prose[0].split(/\s+/).length <= MAX_SUMMARY_WORDS;
+  if (prose.length > 0 && !summaryOnly) {
+    return { status: 'inlined', reason: `${prose.length} line(s) of policy text or table outside the link` };
+  }
+  if (bullets > MAX_KEY_POINTS) {
+    return { status: 'inlined', reason: `${bullets} key points (max ${MAX_KEY_POINTS}); move the rest into the source` };
+  }
+  return { status: 'thin', reason: '' };
+}
+
+// Wrappers among the planned entries that exist in the project and are not thin. Read-only: the caller
+// reports them and proposes moving the inlined content into the snippet.
+function auditWrappers(cwd, plan) {
+  const out = [];
+  for (const e of plan) {
+    if (e.action === 'retired') continue;
+    const sources = wrapperSources(e.rel);
+    const file = path.join(cwd, e.rel);
+    if (!sources || !fs.existsSync(file)) continue;
+    const targets = sources.filter((s) => fs.existsSync(path.join(cwd, s.rel)));
+    const result = targets.length
+      ? auditWrapper(fs.readFileSync(file, 'utf8'), targets)
+      : { status: 'diverged', reason: `no ${sources[0].rel} or ${sources[1].rel} to link` };
+    if (result.status !== 'thin') out.push({ rel: e.rel, status: result.status, reason: result.reason });
+  }
+  return out;
+}
+
+module.exports = {
+  RETIRED_FILE,
+  TRACKERS,
+  MAX_KEY_POINTS,
+  readRetired,
+  retiredFor,
+  detectProject,
+  topicOf,
+  relevanceOf,
+  wrapperSources,
+  auditWrapper,
+  auditWrappers,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nitm-ai-dev-toolkit",
-  "version": "5.1.2",
+  "version": "5.2.0",
   "description": "Scaffold AI agent config (Cursor, GitHub Copilot, Claude Code, OpenCode, Codex) into any repo, then hand off to your AI agent to finish setup.",
   "bin": {
     "nitm-ai-dev-toolkit": "bin/cli.js"

package/src/monorepo/.claude/prompt-snippets/bootstrap-patch.md

@@ -115,11 +115,13 @@ The CLI runs the same patch flow without an AI session: `npx nitm-ai-dev-toolkit
 
     For each category, compare template files against project files:
 
-    a. **Classify each file**:
-    - **🆕 New**: Exists in template but not in project → candidate for addition
-    - **📝 Updated**: Exists in both but template has newer content → candidate for merge
-    - **✅ Current**: Exists in both and content matches → no action needed
-    - **🔧 Customized**: Exists in both, project version has non-placeholder customizations → careful merge
+    a. **Classify each file** (relevance-aware; never a wholesale copy). `npx nitm-ai-dev-toolkit patch --dry-run` makes this classification and prints each reason. Read that plan before deciding anything, and see Relevance and Retirement in `bootstrap.md`:
+    - **add**: missing, and it applies to this project (tracker, Playwright, Prisma, UI, and MCP relevance)
+    - **update**: the toolkit wrote it and the project has not changed it since; the new template replaces it
+    - **current**: identical to the template; no action
+    - **needs review**: differs from the template (locally changed), or missing while relevance is undecided; never overwritten, and never added without a decision
+    - **not relevant**: does not apply to this project; never added. A present copy is a retirement candidate
+    - **retired**: listed in `.nitm/retired.json`; never added, updated or overwritten
     - **⚠️ Missing in Template**: Exists in project but not in template → project-specific, keep as-is except the approved obsolete toolkit Ponytail removal above
 
     b. **For updated files, generate a structured diff**:
@@ -130,7 +132,7 @@ The CLI runs the same patch flow without an AI session: `npx nitm-ai-dev-toolkit
 
     c. **Smart Merge Rules**:
     - **Never overwrite** project-specific values that replaced `{{PLACEHOLDER}}`
-    - **Always add** new files that don't exist in the project
+    - **Add only** files classified *add*. Never add a not-relevant or retired file, and never add a file whose relevance is undecided without the operator's decision
     - **Merge structural additions** into existing customized files
     - **Flag for review** any removals from files that have been customized
     - **Preserve custom agents/skills** that were added by the project
@@ -144,13 +146,13 @@ The CLI runs the same patch flow without an AI session: `npx nitm-ai-dev-toolkit
     **Project Type**: repo | monorepo
     **Categories Scanned**: [list]
 
-    ### 🆕 New Files (X files)
+    ### 🆕 Add (X files; apply to this project)
 
     | File                         | Category | Description              |
     | ---------------------------- | -------- | ------------------------ |
     | `.cursor/rules/new-rule.mdc` | Rules    | New coding standard rule |
 
-    ### 📝 Updated Files (X files)
+    ### 📝 Update (X files; unchanged since the toolkit wrote them)
 
     | File                                                     | Changes                        | Risk           |
     | -------------------------------------------------------- | ------------------------------ | -------------- |
@@ -161,16 +163,30 @@ The CLI runs the same patch flow without an AI session: `npx nitm-ai-dev-toolkit
 
     [No action needed]
 
-    ### 🔧 Customized Files Requiring Review (X files)
+    ### 🔧 Needs Review (X files; locally changed or undecided; not written)
 
     | File        | Template Changes  | Project Customizations       | Merge Strategy |
     | ----------- | ----------------- | ---------------------------- | -------------- |
     | `AGENTS.md` | New section added | Has project-specific content | Manual merge   |
 
+    ### 🚫 Not Relevant or Retired (X files; not written)
+
+    | File                                  | Reason                       | Action                                  |
+    | ------------------------------------- | ---------------------------- | --------------------------------------- |
+    | `.claude/commands/playwright-test.md` | No Playwright setup detected | Keep out; retire if present (approval)  |
+    | `.agents/skills/linear-cli/SKILL.md`  | Project tracker is GitHub    | Retire in `.nitm/retired.json`          |
+
+    ### 🩹 Harness Wrappers to Review (X files; proposals only)
+
+    | Wrapper                       | Finding                              | Proposal                                         |
+    | ----------------------------- | ------------------------------------ | ------------------------------------------------ |
+    | `.claude/rules/api-server.md` | Policy text outside the snippet link | Move the text into its snippet; keep a thin link |
+
     ### Summary
 
-    - **Auto-apply**: X new files + Y updated files with no conflicts
-    - **Review needed**: Z customized files with structural changes
+    - **Auto-apply**: X add + Y update entries, as printed by `patch`
+    - **Review needed**: Z needs-review files and W wrapper proposals
+    - **Not written**: N not-relevant or retired entries
     - **No action**: W files already current
     ```
 
@@ -178,9 +194,9 @@ The CLI runs the same patch flow without an AI session: `npx nitm-ai-dev-toolkit
     - If `--dry-run` flag: Output the report without making changes
     - Otherwise: Present the report and ask the user to confirm with (Y/n)
     - On confirmation:
-      a. **New files**: Copy directly from template
-      b. **Updated files (no customization)**: Replace with template version
-      c. **Updated files (customized)**: Apply structural additions while preserving project values
+      a. **Add and update**: run `npx nitm-ai-dev-toolkit patch`. It writes only the add and update entries it printed; do not copy template files by hand
+      b. **Retirements**: after approval, record each path in `.nitm/retired.json` with a reason and date. Do not delete files to retire them
+      c. **Needs review**: propose a merge per file (structural additions, preserved project values) and apply it only after the operator approves that file. Wrappers that inline policy: propose moving the content into the snippet and reducing the wrapper to a thin link (see Thin Wrapper Policy in `bootstrap.md`)
       d. **OpenCode plugins**: Apply only the approved obsolete Ponytail cleanup above after backing up the known obsolete toolkit copies and local config; preserve all unrelated local/global plugins. Never add Ponytail to project config.
       e. **Toolkit version**: Keep the `.toolkit-version` value the CLI writes for the verified target version (the installed package version, 4.0.0 or later; never hard-coded) only after the approved migration and OpenCode preflight pass (or OpenCode is confirmed out of scope).
       f. **Git commit**: Stage and commit all changes with message:

package/src/monorepo/.claude/prompt-snippets/bootstrap-upgrade.md

@@ -255,6 +255,8 @@ Follow the rules defined in [.claude/rules-snippets/{{NAME}}.md](../../.claude/r
 
 ### Step 7: Create .opencode/ Directory (confirmed OpenCode use only)
 
+Create wrappers below only for entries the patch plan classifies *add* (never retired or not-relevant snippets). Each wrapper stays thin (see Thin Wrapper Policy in `bootstrap.md`).
+
 For the v3 route, merge only relevant native OpenCode host fields; preserve existing wrapper bodies, modes, unrelated frontmatter, and shared snippet bodies/frontmatter. The wrapper examples below apply only to approved missing files, not replacement of existing wrappers.
 
 1. Merge `.opencode/opencode.jsonc` using native V2 fields:
@@ -312,12 +314,13 @@ For the v3 route, merge only relevant native OpenCode host fields; preserve exis
 
 ### Step 8: Install Pre-Commit Hook
 
-Install the CHANGELOG/secrets enforcement hook to run before every commit:
+Install the CHANGELOG/secrets enforcement hook before every commit, only with the operator's approval, only in a git repository, and never over an existing `.git/hooks/pre-commit`. If one exists, show the difference and propose chaining or merging instead:
 
 1. Copy `scripts/pre-commit-check.sh` from the template to the target project's `scripts/` directory
 2. Install as a git hook:
 
    ```bash
+   # only when .git/hooks/pre-commit does not exist yet
    cp scripts/pre-commit-check.sh .git/hooks/pre-commit
    chmod +x .git/hooks/pre-commit
    ```
@@ -330,10 +333,12 @@ This enforces:
 
 Use `git commit --no-verify` to bypass.
 
-### Step 9: Install Project Hooks
+### Step 9: Install Project Hooks (only with approval)
+
+The `hooks/` files are Claude Code plugin hooks (`${CLAUDE_PLUGIN_ROOT}`) and the Ponytail runtime. They fire only when installed through the Ponytail plugin, not from project settings. Copy only the files the operator approves for a project that uses that plugin, and never overwrite an existing hook file.
 
-1. Create `hooks/` directory in the target project
-2. Copy all files from the template's `hooks/*` directory (preserve sub-structure)
+1. Create `hooks/` in the target project when copying
+2. Copy the approved files from the template's `hooks/*` directory (preserve sub-structure); skip any file that already exists
 3. Make `.js` files executable on Unix: `chmod +x hooks/*.js`
 
 ### Step 10: Clean Up Duplicate Skills

package/src/monorepo/.claude/prompt-snippets/bootstrap.md

@@ -20,6 +20,28 @@ You are helping to bootstrap AI instructions for this monorepo by analyzing the
 - Codex MCP uses native `[mcp_servers.name]` TOML, not `.mcp.json`. Treat other harness MCP templates as references only; do not activate servers, copy credentials, or install hooks automatically.
 - Update and audit only confirmed harness targets. For Codex-only setup, the native targets are root/nested `AGENTS.md`, `.agents/skills/`, and `.codex/config.toml`. `--env codex` also includes `.github/instructions/` and `.claude/rules-snippets/` solely as AGENTS-linked standards and their wrapper sources, not automatically loaded rules or evidence of Copilot/Claude use; other harness command, agent, and config directories are excluded. Tool-specific steps below are conditional.
 
+## Thin Wrapper Policy
+
+Canonical policy lives only in `.claude/rules-snippets/`, `.claude/prompt-snippets/`, and `.claude/agents-snippets/`. Every harness wrapper (`.claude/{rules,commands,agents}/`, `.cursor/{rules,commands,agents}/`, `.github/{instructions,prompts,agents}/`, `.opencode/{rules,commands,agents}/`, and Codex and Copilot entry files) is a thin link to its snippet: frontmatter, a title, the link line, at most five key points, and optionally one short summary line. Its agent-dispatch table is activation metadata and may stay.
+
+- **Create or change policy in the snippet first, then the wrapper.** Never write a wrapper with a copy of the policy, and never let a wrapper diverge from its snippet.
+- **Skills that restate a snippet's policy point to the snippet** (or, where the skill is the source, the snippet points to the skill). Keep one source of policy text.
+- **Existing wrappers that inline policy or diverge from their snippet** are reported (`npx nitm-ai-dev-toolkit doctor` lists them). Propose moving the content into the snippet and reducing the wrapper to a link. Change nothing without the operator's approval.
+
+## Relevance and Retirement
+
+The template ships files for every stack, tracker and test tool. Decide what applies to this monorepo and each app; do not copy the whole template.
+
+- **Relevance comes from the project:** the tracker (git origin host, or `"trackers"` in `.nitm/retired.json`), Playwright, Prisma, the UI framework (read from the root and `apps/*`, `packages/*` package manifests), and whether MCP servers are configured. `npx nitm-ai-dev-toolkit patch --dry-run` prints each template file's classification with its reason (add, update, needs review, not relevant, retired). Use that plan; do not copy template files by hand.
+- **Retire what does not apply** by recording it in `.nitm/retired.json` after the operator agrees, with a reason and date:
+
+  ```json
+  { "retired": [{ "path": ".agents/skills/linear-cli", "reason": "GitHub Issues is the tracker", "date": "2026-10-27" }] }
+  ```
+
+  A directory path retires every file under it. Patch and upgrade never re-add retired paths, and doctor reports them as retired, not missing. Never delete files to retire them.
+- **Override tracker detection** with `"trackers": ["github"]` (or `[]` for none) when the git origin does not name the tracker.
+
 ## Your Task
 
 1. **Analyze the Monorepo**:
@@ -333,11 +355,16 @@ Present the replacements and confirm before applying.
 
 10. **Recommend and Install AI Agent Skills**:
 
-Based on detected ecosystem and frameworks, recommend relevant skills from [skills.sh](https://skills.sh/) and [agentskills.io](https://agentskills.io/).
+Recommend skills from [skills.sh](https://skills.sh/) and [agentskills.io](https://agentskills.io/) only for needs this monorepo or app has: its tracker, framework, language, and test tooling. Never install a whole repository with `--skill '*'`. The toolkit already ships the core workflow skills (TDD, debugging, planning, review) in `.agents/skills/`, so do not recommend them again.
+
+**Rules for every recommendation:**
+- One named skill per install (`--skill <name>`). Confirm the name exists in its source repository first. If you cannot confirm it, leave that install out and say so.
+- List the detected need next to each skill. Recommend nothing without a need.
+- Install nothing before the operator approves that skill. Approving one skill does not approve the others.
 
 **Important:** Use the detected agent flags from step 9 in all `npx skills add` commands. This prevents creating unnecessary configurations for agents the user doesn't have installed.
 
-**Core Skills (Always Recommend):**
+**Generic workflow skills (optional; the toolkit already ships equivalents):**
 
 | Skill Repository           | Purpose                                            |
 | -------------------------- | -------------------------------------------------- |
@@ -348,8 +375,7 @@ Based on detected ecosystem and frameworks, recommend relevant skills from [skil
 **Example commands** (replace `{{AGENT_FLAGS}}` with confirmed harness flags from step 9, e.g., `-a codex`):
 
 ```bash
-npx -y skills add {{AGENT_FLAGS}} obra/superpowers --skill '*'
-npx -y skills add {{AGENT_FLAGS}} trailofbits/skills --skill '*'
+npx -y skills add {{AGENT_FLAGS}} <owner/repo> --skill <confirmed name>   # one line per approved skill
 ```
 
 **Issue Tracker Skills Health Check (if {{ISSUE_TRACKER}} is configured):**
@@ -373,10 +399,10 @@ This template bundles issue tracker skills in `.agents/skills/`. Verify the corr
     - Configured tracker: Linear
     - Found skill: acli (not matching)
     - Expected skill: linear-cli
-    Remove acli and keep linear-cli? (Y/n)
+    Retire acli and keep linear-cli? (Y/n)
     ```
-4.  **Prune unused CLI skills:** On confirmation, delete the mismatched skill directory and update AGENTS.md Skills table
-5.  **If missing:** Warn that the expected CLI skill is not present and offer to copy it from the template bundle
+4.  **Retire mismatched CLI skills:** On confirmation, record each in `.nitm/retired.json` (reason and date) and update the AGENTS.md Skills table. Delete a directory only with separate approval and a backup
+5.  **If missing:** Warn that the expected CLI skill is not present; add it only when `patch --dry-run` shows it applies and the operator approves
 
 **Framework-Specific Skills:**
 
@@ -411,13 +437,13 @@ When recommending framework-specific skills, include the detected agent flags. E
 | React              | `vercel-labs/agent-skills`            | `npx -y skills add {{AGENT_FLAGS}} vercel-labs/agent-skills --skill "vercel-react-best-practices"` |
 | Vue                | `onmax/nuxt-skills` (vue)             | `npx -y skills add {{AGENT_FLAGS}} onmax/nuxt-skills --skill "vue"` |
 | Nuxt               | `onmax/nuxt-skills` (nuxt)            | `npx -y skills add {{AGENT_FLAGS}} onmax/nuxt-skills --skill "nuxt"` |
-| Expo               | `expo/skills`                         | `npx -y skills add {{AGENT_FLAGS}} expo/skills --skill '*'` |
-| TypeScript         | `pproenca/dot-skills` (typescript)    | `npx -y skills add {{AGENT_FLAGS}} pproenca/dot-skills --skill '*'` |
-| Advanced Types     | `wshobson/agents` (ts-advanced-types) | `npx -y skills add {{AGENT_FLAGS}} wshobson/agents --skill '*'` |
+| Expo               | `expo/skills`                         | `npx -y skills add {{AGENT_FLAGS}} expo/skills --skill <name confirmed in the repository>` |
+| TypeScript         | `pproenca/dot-skills` (typescript)    | `npx -y skills add {{AGENT_FLAGS}} pproenca/dot-skills --skill "typescript"` |
+| Advanced Types     | `wshobson/agents` (ts-advanced-types) | `npx -y skills add {{AGENT_FLAGS}} wshobson/agents --skill "ts-advanced-types"` |
 
 **Skill Creation for Unsupported Frameworks:**
 
-Use `npx -y skills add {{AGENT_FLAGS}} anthropics/skills --skill '*'` (includes `skill-creator`) to create custom skills.
+To create a custom skill for an unsupported framework, install only `skill-creator` from `anthropics/skills`: `npx -y skills add {{AGENT_FLAGS}} anthropics/skills --skill "skill-creator"`.
 
 **Monorepo-Specific Considerations:**
 
@@ -438,28 +464,26 @@ Using flags: {{AGENT_FLAGS}}
 
 Based on your monorepo ({{BUILD_SYSTEM}}/{{LANGUAGE}}):
 
-Core Skills (recommended for all projects):
-npx -y skills add {{AGENT_FLAGS}} obra/superpowers --skill '*'
-npx -y skills add {{AGENT_FLAGS}} trailofbits/skills --skill '*'
-npx -y skills add {{AGENT_FLAGS}} softaworks/agent-toolkit --skill '*'
+Approved installs (none until the operator approves each one):
+npx -y skills add {{AGENT_FLAGS}} <owner/repo> --skill <confirmed name>   # one line per approved skill
 
 Issue Tracker Skills (bundled — {{ISSUE_TRACKER}}):
 ✅ .agents/skills/issue-tracker/SKILL.md (shared strategy)
 ✅ Matching CLI reference: .agents/skills/acli/SKILL.md, .agents/skills/gh-cli/SKILL.md, or .agents/skills/linear-cli/SKILL.md
-⚠️ Prune any issue-tracker CLI skills that do not match {{ISSUE_TRACKER}} (if any)
+⚠️ Retire any issue-tracker CLI skills that do not match {{ISSUE_TRACKER}} (if any; record them in .nitm/retired.json)
 
-Framework-Specific Skills:
-- web (Next.js): npx -y skills add {{AGENT_FLAGS}} vercel-labs/agent-skills --skill '*'
-- api (Hono): npx -y skills add {{AGENT_FLAGS}} elysiajs/skills --skill '*'
+Framework-Specific Skills (one named skill each, after confirming its name):
+- web (Next.js): npx -y skills add {{AGENT_FLAGS}} vercel-labs/agent-skills --skill <confirmed name>
+- api (Hono): npx -y skills add {{AGENT_FLAGS}} elysiajs/skills --skill <confirmed name>
 
-Install All? (Y/n)
+Approve each skill by name (or none). Nothing is installed without approval.
 ```
 
 **Example with detected agents:**
 
 - If Cursor and Copilot are confirmed: `AGENT_FLAGS="-a cursor -a github-copilot"`
 - If only Codex is confirmed: `AGENT_FLAGS="-a codex"`
-- Codex-only command: `npx -y skills add -a codex obra/superpowers --skill '*'`
+- Codex-only command: `npx -y skills add -a codex <owner/repo> --skill <confirmed name>`
 
 **On Confirmation:**
 
@@ -530,11 +554,12 @@ Next Steps:
    | django-expert | Django patterns | No Django apps detected |
    | php | PHP patterns | JavaScript/TypeScript monorepo |
 
-   Remove flagged skills? (Y/n)
+   Retire flagged skills? (Y/n)
    ```
 
    **On Confirmation:**
-   - Remove unnecessary skill directories
+   - Record each approved skill in `.nitm/retired.json` (reason and date) so `patch` leaves it out; this removes nothing from the template
+   - Delete a skill directory only with separate approval and a backup
    - Update root AGENTS.md to remove references
    - Report cleanup results
 
@@ -566,8 +591,8 @@ Next Steps:
     ```
 
     **On Confirmation (only if Copilot is confirmed in use):**
-    - Generate missing Copilot instruction files with appropriate templates; skip creation for a Codex-only audit even when shared reference standards are present
-    - Include app-specific scoping (applyTo paths)
+    - Write the policy of each missing Copilot instruction into `.claude/rules-snippets/<name>.md` first, then create `.github/instructions/<name>.instructions.md` as a thin wrapper (frontmatter with `applyTo`, a title, a link to the snippet, at most five key points); skip creation for a Codex-only audit even when shared reference standards are present
+    - Include app-specific scoping (applyTo paths) in the wrapper frontmatter only
     - Include framework-specific patterns from skills
     - Report created files
 

package/src/monorepo/.claude/skills/README.md

@@ -1,6 +1,6 @@
 # Claude Code Skills
 
-This folder is for skills installed via `npx -y skills add -a claude-code <owner/repo> --skill '*'`.
+This folder is for skills installed via `npx -y skills add -a claude-code <owner/repo> --skill <confirmed name>`.
 
 ## About Skills
 
@@ -12,10 +12,10 @@ Install skills from [skills.sh](https://skills.sh/) using the `-a claude-code` f
 
 ```bash
 # For Claude Code only
-npx -y skills add -a claude-code <owner/repo> --skill '*'
+npx -y skills add -a claude-code <owner/repo> --skill <confirmed name>
 
 # For multiple agents (e.g., Claude Code + GitHub Copilot)
-npx -y skills add -a claude-code -a github-copilot <owner/repo> --skill '*'
+npx -y skills add -a claude-code -a github-copilot <owner/repo> --skill <confirmed name>
 ```
 
 **Tip:** The skills CLI automatically detects installed agents. If you omit `-a claude-code`, you'll be prompted to choose from detected agents.
@@ -37,14 +37,14 @@ Universal workflow skills are pre-installed in `.agents/skills/`. These include:
 
 ```bash
 # Frontend skills
-npx -y skills add -a claude-code onmax/nuxt-skills --skill '*'
-npx -y skills add -a claude-code vercel-labs/agent-skills --skill '*'
+npx -y skills add -a claude-code onmax/nuxt-skills --skill vue
+npx -y skills add -a claude-code vercel-labs/agent-skills --skill vercel-react-best-practices
 
 # Security skills
-npx -y skills add -a claude-code trailofbits/skills --skill '*'
+npx -y skills add -a claude-code trailofbits/skills --skill <confirmed name>
 
 # Framework-specific
-npx -y skills add -a claude-code better-auth/skills --skill '*'
+npx -y skills add -a claude-code better-auth/skills --skill <confirmed name>
 ```
 
 See the main README.md for a full list of recommended skills.