nitm-ai-dev-toolkit 5.1.2 → 5.2.0

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

@@ -1,6 +1,6 @@
 # Cursor Skills
 
-This folder is for skills installed via `npx -y skills add <owner/repo> --skill '*' --agent github-copilot cursor`.
+This folder is for skills installed via `npx -y skills add <owner/repo> --skill <confirmed name> --agent github-copilot cursor`.
 
 ## About Skills
 
@@ -12,13 +12,13 @@ Install skills from [skills.sh](https://skills.sh/) using the `-a cursor` flag:
 
 ```bash
 # For Cursor only
-npx -y skills add -a cursor <owner/repo> --skill '*' --agent github-copilot cursor
+npx -y skills add -a cursor <owner/repo> --skill <confirmed name> --agent github-copilot cursor
 
 # For multiple agents (e.g., Cursor + GitHub Copilot)
-npx -y skills add -a cursor -a github-copilot <owner/repo> --skill '*' --agent github-copilot cursor
+npx -y skills add -a cursor -a github-copilot <owner/repo> --skill <confirmed name> --agent github-copilot cursor
 ```
 
-**Tip:** The skills CLI automatically detects installed agents. If you omit `-a cursor`, you'll be prompted to choose from detected agents. Use `--skill '*' --agent github-copilot cursor` to avoid skill-selection prompts when installing from a repo.
+**Tip:** The skills CLI automatically detects installed agents. If you omit `-a cursor`, you'll be prompted to choose from detected agents. Use `--skill <confirmed name> --agent github-copilot cursor` when installing one named skill from a repo.
 
 **Important:** Always use `-a cursor` to install only for Cursor (or add multiple `-a` flags if you use multiple agents). This prevents creating unnecessary configuration files for other agents.
 
@@ -37,14 +37,14 @@ Universal workflow skills are pre-installed in `.agents/skills/`. These include:
 
 ```bash
 # Frontend skills
-npx -y skills add -a cursor onmax/nuxt-skills --skill '*' --agent github-copilot cursor
-npx -y skills add -a cursor vercel-labs/agent-skills --skill '*' --agent github-copilot cursor
+npx -y skills add -a cursor onmax/nuxt-skills --skill vue --agent github-copilot cursor
+npx -y skills add -a cursor vercel-labs/agent-skills --skill vercel-react-best-practices --agent github-copilot cursor
 
 # Security skills
-npx -y skills add -a cursor trailofbits/skills --skill '*' --agent github-copilot cursor
+npx -y skills add -a cursor trailofbits/skills --skill <confirmed name> --agent github-copilot cursor
 
 # Framework-specific
-npx -y skills add -a cursor better-auth/skills --skill '*' --agent github-copilot cursor
+npx -y skills add -a cursor better-auth/skills --skill <confirmed name> --agent github-copilot cursor
 ```
 
 See the main README.md for a full list of recommended skills.

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

@@ -1,6 +1,6 @@
 # GitHub Copilot Skills
 
-This folder is for skills installed via `npx -y skills add <owner/repo> --skill '*' --agent github-copilot cursor` when using GitHub Copilot.
+This folder is for skills installed via `npx -y skills add <owner/repo> --skill <confirmed name> --agent github-copilot cursor` when using GitHub Copilot.
 
 ## About Skills
 
@@ -12,13 +12,13 @@ Install skills from [skills.sh](https://skills.sh/) using the `-a github-copilot
 
 ```bash
 # For GitHub Copilot only
-npx -y skills add -a github-copilot <owner/repo> --skill '*' --agent github-copilot cursor
+npx -y skills add -a github-copilot <owner/repo> --skill <confirmed name> --agent github-copilot cursor
 
 # For multiple agents (e.g., Copilot + Cursor)
-npx -y skills add -a github-copilot -a cursor <owner/repo> --skill '*' --agent github-copilot cursor
+npx -y skills add -a github-copilot -a cursor <owner/repo> --skill <confirmed name> --agent github-copilot cursor
 ```
 
-**Tip:** The skills CLI automatically detects installed agents. If you omit `-a github-copilot`, you'll be prompted to choose from detected agents. Use `--skill '*' --agent github-copilot cursor` to avoid skill-selection prompts when installing from a repo.
+**Tip:** The skills CLI automatically detects installed agents. If you omit `-a github-copilot`, you'll be prompted to choose from detected agents. Use `--skill <confirmed name> --agent github-copilot cursor` when installing one named skill from a repo.
 
 **Important:** Always use `-a github-copilot` to install only for GitHub Copilot (or add multiple `-a` flags if you use multiple agents). This prevents creating unnecessary configuration files for other agents.
 

package/src/monorepo/.opencode/commands/review-staged.md

@@ -9,3 +9,7 @@ description: "Review currently staged files before committing"
 |-------|-------------|
 | `reviewer` | Standard pre-commit review — correctness, style, patterns |
 | `oracle` | Complex staged change — trade-offs, security, scalability |
+
+Read and follow `.claude/prompt-snippets/review-staged.md` before executing this command.
+
+$ARGUMENTS

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

@@ -117,11 +117,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**:
@@ -132,7 +134,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
@@ -146,13 +148,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           |
     | ------------------------------- | ----------------------------- | -------------- |
@@ -162,16 +164,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
     ```
 
@@ -179,9 +195,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/repo/.claude/prompt-snippets/bootstrap-upgrade.md

@@ -104,7 +104,7 @@ For each file: read → extract body after frontmatter → write to snippet dest
 
 **Parallelizable**: Process rules, commands, and agents independently.
 
-Replace each file's body with a wrapper that preserves frontmatter and references the snippet:
+Replace each file's body with a thin wrapper (see Thin Wrapper Policy in `bootstrap.md`) that preserves frontmatter and references the snippet. Move any policy text into the snippet first; the wrapper keeps only the link, a title and at most five key points:
 
 | File Type                   | Frontmatter to Keep                             | Reference Line                                                                                 |
 | --------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
@@ -188,7 +188,7 @@ For the v3 route, merge only relevant native OpenCode host fields; preserve exis
    - Back up the local config and known obsolete toolkit-owned `.opencode/plugins/ponytail.js`, `.opencode/plugins/ponytail.mjs`, and `.opencode/plugins/ponytail.ts` copies; obtain approval before removing only those copies. Preserve unrelated local plugins.
    - The OpenCode Ponytail plugin (`@dietrichgebert/ponytail`) is installed globally by the operator. Never add or pin it in the local `plugins` array. Check whether it is installed globally; if not, tell the operator to install it globally. Do not edit global config or overwrite global plugins. Keep `opentmux` commented as V1-only; do not copy local Ponytail source, port APIs, or introduce bridges. Runtime integration remains untested.
 
-3. **Create wrappers with explicit snippet-read instructions** — one file per snippet:
+3. **Create wrappers with explicit snippet-read instructions** — only for entries the patch plan classifies *add* (never retired or not-relevant snippets), each one thin (see Thin Wrapper Policy in `bootstrap.md`), one file per snippet:
 
    | Directory                 | Source Snippets            | Wrapper Body                         |
    | ------------------------- | -------------------------- | ------------------------------------ |
@@ -210,12 +210,13 @@ For the v3 route, merge only relevant native OpenCode host fields; preserve exis
 
 ### 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
    ```
@@ -228,10 +229,12 @@ This enforces:
 
 Use `git commit --no-verify` to bypass.
 
-### 9. Install Project Hooks
+### 9. Install Project Hooks (only with approval)
 
-1. Create `hooks/` directory in the target project
-2. Copy all files from the template's `hooks/*` directory (preserve sub-structure)
+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/` 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`
 
 ### 10. Clean Up Duplicate Skills

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

@@ -27,6 +27,28 @@ Analyze the project structure and customize AI instruction templates for this co
 - 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, `AGENTS.md`, `.agents/skills/`, and `.codex/config.toml` are the native targets. `--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. The remaining tool-specific examples 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 project; 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, 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; that removes nothing from the template.
+- **Override tracker detection** with `"trackers": ["github"]` (or `[]` for none) when the git origin does not name the tracker, for example a Linear project hosted on GitHub.
+
 ## Process
 
 > **Merge, don't clobber.** If a target file already exists and carries project-specific content — customized agents, rules, skills, or `{{PLACEHOLDER}}` values already replaced — preserve it. Add missing structure; never overwrite a customized file with template defaults. When a template change conflicts with an existing customization, merge the addition and flag it for the user rather than replacing the file. For incremental updates after the first bootstrap, prefer `/bootstrap-patch`, which is purpose-built for meticulous merging.
@@ -503,13 +525,18 @@ Before recommending skills, identify the running harness from session/runtime in
 - Example: confirmed Cursor and Copilot → `-a cursor -a github-copilot`
 - If no harness is confirmed, ask before installing (or let the CLI prompt); do not infer from scaffold directories
 
-### Step 7: AI Agent Skills Recommendation
+### Step 7: AI Agent Skills by Need
+
+Recommend skills from [skills.sh](https://skills.sh/) and [agentskills.io](https://agentskills.io/) only for needs this project 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.
 
-Based on detected ecosystem and frameworks, recommend relevant skills from [skills.sh](https://skills.sh/) and [agentskills.io](https://agentskills.io/).
+**Rules for every recommendation:**
+- One named skill per install (`--skill <name>`). Confirm the name exists in its source repository first (its README or skill listing). 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 6 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                                                    |
 | -------------------------- | ---------------------------------------------------------- |
@@ -531,9 +558,9 @@ This template bundles issue tracker skills in `.agents/skills/`. Verify the corr
 
 1. **Map tracker → expected CLI skill:** Jira → `acli`, GitHub Issues → `gh-cli`, Linear → `linear-cli`
 2. **Verify presence:** Check `.agents/skills/issue-tracker/SKILL.md` and `.agents/skills/{expected-cli}/SKILL.md` exist
-3. **Warn on mismatch:** If a *different* CLI skill is present, warn the user and offer to prune
-4. **Prune unused CLI skills:** On confirmation, delete mismatched skill directory and update AGENTS.md Skills table
-5. **If missing:** Warn and offer to copy from the template bundle
+3. **Warn on mismatch:** If a *different* CLI skill is present, warn the user and offer to retire it in `.nitm/retired.json` (the patch plan then leaves it out)
+4. **Remove only with approval:** Deleting a skill directory needs explicit approval, a backup copy, and an updated AGENTS.md Skills table. Retiring it (step 3) needs no deletion
+5. **If missing:** `patch --dry-run` shows whether the matching CLI skill applies; add it only when the operator approves
 
 **Framework-Specific Skills:**
 
@@ -566,13 +593,13 @@ This template bundles issue tracker skills in `.agents/skills/`. Verify the corr
 | 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"`.
 
 **Present Recommendation:**
 
@@ -584,12 +611,10 @@ Using flags: {{AGENT_FLAGS}}
 
 Based on your project ({{FRAMEWORK}}/{{LANGUAGE}}):
 
-### Core Skills (recommended for all projects)
+### Approved installs (none until the operator approves each one)
 
 ```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}} softaworks/agent-toolkit --skill '*'
+npx -y skills add {{AGENT_FLAGS}} <owner/repo> --skill <confirmed name>   # one line per approved skill
 `````
 
 ### Issue Tracker Skills (bundled — {{ISSUE_TRACKER}})
@@ -597,7 +622,7 @@ npx -y skills add {{AGENT_FLAGS}} softaworks/agent-toolkit --skill '*'
 ```
 ✅ .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)
 ```
 
 ````
@@ -605,12 +630,12 @@ npx -y skills add {{AGENT_FLAGS}} softaworks/agent-toolkit --skill '*'
 ### Framework-Specific Skills
 
 ```bash
-npx -y skills add {{AGENT_FLAGS}} {{FRAMEWORK_SKILL_REPO}} --skill '*'
+npx -y skills add {{AGENT_FLAGS}} {{FRAMEWORK_SKILL_REPO}} --skill <confirmed name>
 ```
 
-### Install All?
+### Approve Each Skill
 
-Would you like to install these skills now? (Y/n)
+Install only the skills named here, nothing else. Which of these should be installed? (name each one, or none)
 
 ````
 
@@ -662,7 +687,7 @@ Populate this example with only files actually changed and skills actually insta
 6. Create custom skills at https://agentskills.io/specification
 ```
 
-### Step 8: Skills Review & Cleanup
+### Step 8: Skill Review & Retirement
 
 After bootstrap completion, review all installed skills for relevance:
 
@@ -710,22 +735,18 @@ After bootstrap completion, review all installed skills for relevance:
 | php               | PHP patterns     | No PHP files found - TypeScript project   |
 | swift-development | SwiftUI patterns | No iOS/Swift code detected                |
 
-### 🚫 Remove Unnecessary Skills?
+### 🚫 Retire Unnecessary Skills?
 
 These skills don't match your detected tech stack and may clutter AI context.
 
-Remove flagged skills? (Y/n)
+Retire flagged skills? (Y/n)
 ```
 
 **On Confirmation:**
 
 ```bash
-# Remove unnecessary skills
-rm -rf .github/skills/django-expert/
-rm -rf .cursor/skills/php/
-rm -rf .github/skills/swift-development/
-
-# Update AGENTS.md to remove references
+# Retire each approved skill in .nitm/retired.json (see Relevance and Retirement); patch then leaves it out.
+# Delete a directory only after separate approval and a backup, then update the AGENTS.md references.
 ```
 
 **Post-Cleanup Report:**
@@ -733,7 +754,7 @@ rm -rf .github/skills/swift-development/
 ```markdown
 ## ✅ Skill Cleanup Complete
 
-Removed {{N}} unnecessary skills:
+Retired {{N}} unnecessary skills (recorded in .nitm/retired.json):
 
 - django-expert
 - php
@@ -801,10 +822,12 @@ Create recommended instructions? (Y/n)
 
 **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:
+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 (see Thin Wrapper Policy); skip creation for a Codex-only audit even when shared reference standards are present:
 
 **Copilot Example: Framework Instruction Template (only if confirmed in use)**
 
+The body below is the shared snippet, `.claude/rules-snippets/<name>.md`. Write it there first. The `.github/instructions/<name>.instructions.md` file is then a thin wrapper: its frontmatter, a title, a link to the snippet, and at most five key points. Never copy this body into the wrapper.
+
 ```markdown
 ---
 applyTo: "src/**"

package/src/repo/.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.

package/src/repo/.cursor/skills/README.md

@@ -1,6 +1,6 @@
 # Cursor Skills
 
-This folder is for skills installed via `npx -y skills add <owner/repo> --skill '*' --agent github-copilot cursor`.
+This folder is for skills installed via `npx -y skills add <owner/repo> --skill <confirmed name> --agent github-copilot cursor`.
 
 ## About Skills
 
@@ -12,13 +12,13 @@ Install skills from [skills.sh](https://skills.sh/) using the `-a cursor` flag:
 
 ```bash
 # For Cursor only
-npx -y skills add -a cursor <owner/repo> --skill '*' --agent github-copilot cursor
+npx -y skills add -a cursor <owner/repo> --skill <confirmed name> --agent github-copilot cursor
 
 # For multiple agents (e.g., Cursor + GitHub Copilot)
-npx -y skills add -a cursor -a github-copilot <owner/repo> --skill '*' --agent github-copilot cursor
+npx -y skills add -a cursor -a github-copilot <owner/repo> --skill <confirmed name> --agent github-copilot cursor
 ```
 
-**Tip:** The skills CLI automatically detects installed agents. If you omit `-a cursor`, you'll be prompted to choose from detected agents. Use `--skill '*' --agent github-copilot cursor` to avoid skill-selection prompts when installing from a repo.
+**Tip:** The skills CLI automatically detects installed agents. If you omit `-a cursor`, you'll be prompted to choose from detected agents. Use `--skill <confirmed name> --agent github-copilot cursor` when installing one named skill from a repo.
 
 **Important:** Always use `-a cursor` to install only for Cursor (or add multiple `-a` flags if you use multiple agents). This prevents creating unnecessary configuration files for other agents.
 
@@ -37,14 +37,14 @@ Universal workflow skills are pre-installed in `.agents/skills/`. These include:
 
 ```bash
 # Frontend skills
-npx -y skills add -a cursor onmax/nuxt-skills --skill '*' --agent github-copilot cursor
-npx -y skills add -a cursor vercel-labs/agent-skills --skill '*' --agent github-copilot cursor
+npx -y skills add -a cursor onmax/nuxt-skills --skill vue --agent github-copilot cursor
+npx -y skills add -a cursor vercel-labs/agent-skills --skill vercel-react-best-practices --agent github-copilot cursor
 
 # Security skills
-npx -y skills add -a cursor trailofbits/skills --skill '*' --agent github-copilot cursor
+npx -y skills add -a cursor trailofbits/skills --skill <confirmed name> --agent github-copilot cursor
 
 # Framework-specific
-npx -y skills add -a cursor better-auth/skills --skill '*' --agent github-copilot cursor
+npx -y skills add -a cursor better-auth/skills --skill <confirmed name> --agent github-copilot cursor
 ```
 
 See the main README.md for a full list of recommended skills.

package/src/repo/.github/skills/README.md

@@ -1,6 +1,6 @@
 # GitHub Copilot Skills
 
-This folder is for skills installed via `npx -y skills add <owner/repo> --skill '*' --agent github-copilot cursor` when using GitHub Copilot.
+This folder is for skills installed via `npx -y skills add <owner/repo> --skill <confirmed name> --agent github-copilot cursor` when using GitHub Copilot.
 
 ## About Skills
 
@@ -12,13 +12,13 @@ Install skills from [skills.sh](https://skills.sh/) using the `-a github-copilot
 
 ```bash
 # For GitHub Copilot only
-npx -y skills add -a github-copilot <owner/repo> --skill '*' --agent github-copilot cursor
+npx -y skills add -a github-copilot <owner/repo> --skill <confirmed name> --agent github-copilot cursor
 
 # For multiple agents (e.g., Copilot + Cursor)
-npx -y skills add -a github-copilot -a cursor <owner/repo> --skill '*' --agent github-copilot cursor
+npx -y skills add -a github-copilot -a cursor <owner/repo> --skill <confirmed name> --agent github-copilot cursor
 ```
 
-**Tip:** The skills CLI automatically detects installed agents. If you omit `-a github-copilot`, you'll be prompted to choose from detected agents. Use `--skill '*' --agent github-copilot cursor` to avoid skill-selection prompts when installing from a repo.
+**Tip:** The skills CLI automatically detects installed agents. If you omit `-a github-copilot`, you'll be prompted to choose from detected agents. Use `--skill <confirmed name> --agent github-copilot cursor` when installing one named skill from a repo.
 
 **Important:** Always use `-a github-copilot` to install only for GitHub Copilot (or add multiple `-a` flags if you use multiple agents). This prevents creating unnecessary configuration files for other agents.
 

package/src/repo/.opencode/commands/review-staged.md

@@ -9,3 +9,7 @@ description: "Review currently staged files before committing"
 |-------|-------------|
 | `reviewer` | Standard pre-commit review — correctness, style, patterns |
 | `oracle` | Complex staged change — trade-offs, security, scalability |
+
+Read and follow `.claude/prompt-snippets/review-staged.md` before executing this command.
+
+$ARGUMENTS