nitm-ai-dev-toolkit 3.0.15

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

@@ -0,0 +1,199 @@
+You are helping to patch AI instructions in this project by comparing against the latest templates from the ai-assisted-dev-toolkit repository and applying any updates.
+
+## Orchestrator Checkpoint
+
+> **🛑 Before starting**: This command involves fetching, diffing, and applying changes across many files.
+> Dispatch parallel subagents for independent file groups (rules, commands, prompts, instructions, skills, agents).
+> See `.claude/rules-snippets/subagent-workflow.md` for patterns.
+
+## Usage
+
+```
+/bootstrap-patch
+/bootstrap-patch --dry-run
+/bootstrap-patch --category rules
+/bootstrap-patch --category commands,prompts
+```
+
+## Process
+
+1. **Fetch Latest Templates**:
+
+   Clone or fetch the latest ai-assisted-dev-toolkit templates:
+
+   ```bash
+   TOOLKIT_TEMP=$(mktemp -d)
+   git clone --depth 1 https://github.com/ninjasitm/ai-assisted-dev-toolkit.git "$TOOLKIT_TEMP"
+   ```
+
+   Determine the correct source path based on project structure:
+   - **Single repo**: Use `$TOOLKIT_TEMP/src/repo/`
+   - **Monorepo**: Use `$TOOLKIT_TEMP/src/monorepo/`
+
+    Detection heuristic:
+    - If `apps/` and `packages/` directories exist at root → monorepo
+    - Otherwise → single repo
+
+    **Detect Toolkit Version:**
+
+    Check for a `.toolkit-version` file in the project root:
+    - If exists: Read the version string (e.g., `2.0.10`, `3.0.0`)
+    - If missing: Assume legacy version (pre-3.0.0)
+
+    Read the toolkit's version from `$TOOLKIT_TEMP/.toolkit-version` to compare.
+
+    **Version Comparison:**
+    - **Same version**: No structural changes expected
+    - **Newer version**: Check for structural changes (new directories, renamed files, format changes)
+
+2. **Inventory Current State**:
+
+   Scan the project's AI configuration directories:
+
+   | Category         | Project Paths                                                 | Template Source Paths                       |
+   | ---------------- | ------------------------------------------------------------- | ------------------------------------------- |
+   | **Cursor Rules** | `.cursor/rules/*.mdc`                                         | `src/{type}/.cursor/rules/*.mdc`            |
+   | **Cursor Cmds**  | `.cursor/commands/*.md`                                       | `src/{type}/.cursor/commands/*.md`           |
+   | **Cursor Agents**| `.cursor/agents/*.agent.md`                                   | `src/{type}/.cursor/agents/*.agent.md`       |
+   | **GH Prompts**   | `.github/prompts/*.prompt.md`                                 | `src/{type}/.github/prompts/*.prompt.md`     |
+   | **GH Instrs**    | `.github/instructions/*.instructions.md`                      | `src/{type}/.github/instructions/*.instructions.md` |
+   | **GH Agents**    | `.github/agents/*.agent.md`                                   | `src/{type}/.github/agents/*.agent.md`       |
+   | **Claude Rules** | `.claude/rules/*.md`                                          | `src/{type}/.claude/rules/*.md`              |
+   | **Claude Cmds**  | `.claude/commands/*.md`                                       | `src/{type}/.claude/commands/*.md`           |
+   | **Claude Agents**| `.claude/agents/*.agent.md`                                   | `src/{type}/.claude/agents/*.agent.md`       |
+   | **Skills**       | `.agents/skills/*/SKILL.md`                                   | `src/{type}/.agents/skills/*/SKILL.md`       |
+    | **AGENTS.md**    | `AGENTS.md`                                                   | `src/{type}/AGENTS.md`                       |
+    | **CLAUDE.md**    | `CLAUDE.md`                                                   | `src/{type}/CLAUDE.md`                       |
+    | **Claude Rules Snippets** | `.claude/rules-snippets/*.md`                          | `src/{type}/.claude/rules-snippets/*.md`     |
+    | **Claude Prompt Snippets** | `.claude/prompt-snippets/*.md`                       | `src/{type}/.claude/prompt-snippets/*.md`    |
+    | **Claude Agent Snippets** | `.claude/agents-snippets/*.md`                        | `src/{type}/.claude/agents-snippets/*.md`    |
+     | **OpenCode Config** | `.opencode/opencode.json`                                | `src/{type}/.opencode/opencode.json`         |
+     | **OpenCode Commands** | `.opencode/commands/*.md`                               | `src/{type}/.opencode/commands/*.md`         |
+     | **OpenCode Rules** | `.opencode/rules/*.md`                                   | `src/{type}/.opencode/rules/*.md`            |
+     | **OpenCode Agents** | `.opencode/agents/*.md`                                 | `src/{type}/.opencode/agents/*.md`           |
+     | **OpenCode Plugins** | `.opencode/plugins/*.mjs`                             | `src/{type}/.opencode/plugins/*.mjs`         |
+     | **Hooks**           | `hooks/*.{js,sh,ps1}`                                    | `src/{type}/hooks/*.{js,sh,ps1}`              |
+     | **Agent Rules**     | `.agents/rules/*.md`                                     | `src/{type}/.agents/rules/*.md`               |
+      | **Toolkit Version** | `.toolkit-version`                                      | `.toolkit-version` (root of toolkit)         |
+
+   **⚠️ OpenCode `opencode.json` Schema Validation:**
+
+   When patching `.opencode/opencode.json`, **only add or modify supported top-level keys**. The schema is defined at `https://opencode.ai/config.json`. Do NOT add unsupported keys.
+
+   **Supported top-level keys:** `$schema`, `instructions`, `skills`, `agent`, `default_agent`, `model`, `small_model`, `provider`, `mcp`, `tools`, `permission`, `lsp`, `formatter`, `server`, `shell`, `command`, `plugin`, `watcher`, `snapshot`, `share`, `autoupdate`, `compaction`, `attachment`, `logLevel`, `disabled_providers`, `enabled_providers`, `tool_output`, `enterprise`, `experimental`
+
+       **Do NOT add** keys like `rules`, `agents`, `commands`, `prompts` as top-level keys — OpenCode uses the `.opencode/` directory structure and `instructions` array instead.
+
+   > **Watch out:** the ponytail template uses the `plugin` key (singular). If you see `plugins` (plural) in your `opencode.json`, that's a typo and the plugin won't load.
+
+3. **Diff Analysis** (parallelizable — dispatch one subagent per category):
+
+   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
+      - **⚠️ Missing in Template**: Exists in project but not in template → project-specific, keep as-is
+
+   b. **For updated files, generate a structured diff**:
+      - Preserve project-specific `{{PLACEHOLDER}}` replacements (already-bootstrapped values)
+      - Identify structural additions (new sections, new rules, new steps)
+      - Identify structural removals (deprecated guidance, removed sections)
+      - Identify content updates (changed instructions, improved wording)
+
+   c. **Smart Merge Rules**:
+      - **Never overwrite** project-specific values that replaced `{{PLACEHOLDER}}`
+      - **Always add** new files that don't exist in the project
+      - **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
+
+4. **Generate Patch Report**:
+
+   ```markdown
+   ## 🩹 Bootstrap Patch Report
+
+   **Toolkit Version**: [commit hash] ([date])
+   **Project Type**: repo | monorepo
+   **Categories Scanned**: [list]
+
+   ### 🆕 New Files (X files)
+
+   | File | Category | Description |
+   | ---- | -------- | ----------- |
+   | `.cursor/rules/new-rule.mdc` | Rules | New coding standard rule |
+
+   ### 📝 Updated Files (X files)
+
+   | File | Changes | Risk |
+   | ---- | ------- | ---- |
+   | `.cursor/commands/implement.md` | Added orchestrator checkpoint | Low - additive |
+   | `.github/instructions/subagent-workflow.instructions.md` | Added parallelization analysis | Low - additive |
+
+   ### ✅ Current Files (X files)
+   [No action needed]
+
+   ### 🔧 Customized Files Requiring Review (X files)
+
+   | File | Template Changes | Project Customizations | Merge Strategy |
+   | ---- | ---------------- | ---------------------- | -------------- |
+   | `AGENTS.md` | New section added | Has project-specific content | Manual merge |
+
+   ### Summary
+   - **Auto-apply**: X new files + Y updated files with no conflicts
+   - **Review needed**: Z customized files with structural changes
+   - **No action**: W files already current
+   ```
+
+5. **Confirm and Apply**:
+
+   - 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
+     d. **Git commit**: Stage and commit all changes with message:
+        ```bash
+        git add -A
+        git commit -m "chore: patch AI instructions from toolkit [$(date +%Y-%m-%d)]"
+        ```
+
+6. **Cleanup**:
+
+   ```bash
+   rm -rf "$TOOLKIT_TEMP"
+   ```
+
+7. **Post-Patch Validation**:
+
+   - Verify no `{{PLACEHOLDER}}` syntax was accidentally re-introduced
+   - Confirm all files are valid (no broken frontmatter, no syntax errors)
+   - List any new placeholders that need manual `bootstrap` to fill
+
+## Smart Merge Strategy
+
+### Preserving Project Values
+
+When a file has been bootstrapped (placeholders replaced with real values), the patch must:
+
+1. **Detect replaced placeholders**: Compare file against template, identify where `{{VAR}}` was replaced with a concrete value
+2. **Build a replacement map**: `{"{{PROJECT_NAME}}": "my-app", "{{FRAMEWORK}}": "Next.js", ...}`
+3. **Apply template structural changes**: Add new sections, update instructions
+4. **Re-apply replacement map**: Restore project-specific values in the updated content
+
+### Conflict Resolution
+
+- **Additive changes** (new sections, new steps): Auto-merge
+- **Modified instructions** (changed wording in existing sections): Replace template text, re-apply value map
+- **Removed sections**: Flag for user review — project may depend on removed guidance
+- **Structural reorganization**: Replace entire file, re-apply value map, flag for review
+
+## Guidelines
+
+- **Non-destructive by default**: Always show changes before applying
+- **Preserve customizations**: Never lose project-specific configuration
+- **Incremental**: Only apply what's changed, don't re-bootstrap everything
+- **Auditable**: Commit message includes date for tracking patch history

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

@@ -0,0 +1,452 @@
+# Bootstrap Upgrade — Monorepo
+
+Migrate this monorepo's AI instruction files from the pre-3.0 inline pattern to the 3.0+ snippet-based architecture.
+
+## Orchestrator Checkpoint
+
+> **🛑 Before starting**: This command involves reading, extracting, and rewriting many files across multiple directories.
+> Dispatch parallel subagents for independent file groups (`.claude/`, `.github/`, `.cursor/`, `.opencode/`).
+> Steps 3-6 can run in parallel per directory. Steps 7-15 are sequential.
+
+## Usage
+
+```
+/bootstrap-upgrade
+/bootstrap-upgrade --dry-run
+/bootstrap-upgrade --verbose
+```
+
+- `--dry-run`: Show what would be changed without writing files
+- `--verbose`: Log every file read/write operation
+
+## Process
+
+### Step 1: Pre-flight Checks
+
+1. **Confirm monorepo structure**: Verify `apps/` and `packages/` directories exist at root. If not, abort and suggest using the single-repo upgrade command instead.
+
+2. **Check existing version**: Read `.toolkit-version` if it exists.
+   - If version is `>= 3.0.0` and snippet directories exist → **abort**: "Already on v3.0+. No migration needed."
+   - If version is `< 3.0.0` or missing → proceed.
+
+3. **Detect build system** (for CLAUDE.md update in Step 10):
+   - `turbo.json` → Turborepo
+   - `nx.json` → Nx
+   - `lerna.json` → Lerna
+   - `pnpm-workspace.yaml` → pnpm workspaces
+   - `workspaces` in `package.json` → npm/yarn workspaces
+
+4. **Inventory files to migrate** (parallelizable — scan all directories simultaneously):
+
+   | Directory | Glob | Count |
+   |-----------|------|-------|
+   | `.claude/rules/` | `*.md` | {{N}} |
+   | `.claude/commands/` | `*.md` | {{N}} |
+   | `.claude/agents/` | `*.agent.md` | {{N}} |
+   | `.github/instructions/` | `*.instructions.md` | {{N}} |
+   | `.github/prompts/` | `*.prompt.md` | {{N}} |
+   | `.github/agents/` | `*.agent.md` | {{N}} |
+   | `.cursor/rules/` | `*.mdc` | {{N}} |
+   | `.cursor/commands/` | `*.md` | {{N}} |
+   | `.cursor/agents/` | `*.agent.md` | {{N}} |
+
+5. **Present summary and ask for confirmation**:
+
+   ```markdown
+   ## 🔄 Monorepo Upgrade: Pre-3.0 → v3.0.0 (Snippet Architecture)
+
+   ### What will change
+
+   - Create `.claude/rules-snippets/`, `.claude/prompt-snippets/`, `.claude/agents-snippets/`
+   - Extract content from {{N}} files into snippet files
+   - Convert originals to thin wrappers referencing snippets
+   - Create `.opencode/` directory with thin wrappers
+   - Clean up duplicate skill directories
+   - Update CLAUDE.md with multi-tool sections
+   - Write `.toolkit-version` with `3.0.0`
+
+   ### Monorepo-specific changes
+
+   - `paths:` frontmatter preserved in rule snippets (app/package scoping)
+   - Per-app AGENTS.md files left untouched
+   - Cross-app instruction references maintained
+
+   Proceed? (Y/n)
+   ```
+
+### Step 2: Create Snippet Directories
+
+Create these directories if they don't exist:
+
+```bash
+mkdir -p .claude/rules-snippets
+mkdir -p .claude/prompt-snippets
+mkdir -p .claude/agents-snippets
+```
+
+### Step 3: Extract Content from .claude/ (Primary Source of Truth)
+
+> **Parallelizable**: Process rules, commands, and agents in parallel.
+
+For each `.claude/rules/*.md`:
+1. Read the file
+2. Parse frontmatter (between `---` delimiters) — **preserve `paths:` and `applyTo:` fields**
+3. Extract the body (everything after the closing `---`)
+4. Write to `.claude/rules-snippets/<name>.md` — include the frontmatter fields (`paths:`, `applyTo:`, `description:`) at the top of the snippet
+
+For each `.claude/commands/*.md`:
+1. Read the file
+2. Extract body content (after frontmatter)
+3. Write to `.claude/prompt-snippets/<name>.md`
+
+For each `.claude/agents/*.agent.md`:
+1. Read the file
+2. Parse frontmatter — preserve `user-invocable`, `agents`, `mode`, `model`, `temperature`, `permission` fields
+3. Extract body content
+4. Write to `.claude/agents-snippets/<name>.md`
+
+### Step 4: Convert .claude/ Files to Thin Wrappers
+
+> **Parallelizable**: Process rules, commands, and agents in parallel.
+
+**Rules** — Replace each `.claude/rules/*.md` body with:
+
+```markdown
+---
+{{ORIGINAL_FRONTMATTER}}
+---
+
+# {{TITLE}}
+
+Follow the rules defined in [.claude/rules-snippets/{{NAME}}.md](../rules-snippets/{{NAME}}.md).
+```
+
+**Commands** — Replace each `.claude/commands/*.md` body with:
+
+```markdown
+---
+{{ORIGINAL_FRONTMATTER}}
+---
+
+# {{TITLE}}
+
+Follow the prompt defined in [.claude/prompt-snippets/{{NAME}}.md](../prompt-snippets/{{NAME}}.md).
+```
+
+**Agents** — Replace each `.claude/agents/*.agent.md` body with:
+
+```markdown
+---
+{{ORIGINAL_FRONTMATTER}}
+---
+
+# {{AGENT_NAME}}
+
+Follow the agent definition in [.claude/agents-snippets/{{NAME}}.md](../agents-snippets/{{NAME}}.md).
+```
+
+### Step 5: Convert .github/ Files to Thin Wrappers
+
+> **Parallelizable**: Process instructions, prompts, and agents in parallel.
+
+**Instructions** — For each `.github/instructions/*.instructions.md`:
+1. Check if a matching snippet exists in `.claude/rules-snippets/`
+2. If no matching snippet: extract body content → create `.claude/rules-snippets/<name>.md`
+3. Replace body with thin wrapper preserving `applyTo:` and `description:` frontmatter:
+
+```markdown
+---
+applyTo: "{{ORIGINAL_APPLY_TO}}"
+description: "{{ORIGINAL_DESCRIPTION}}"
+---
+
+# {{TITLE}}
+
+Follow the rules defined in [.claude/rules-snippets/{{NAME}}.md](../../.claude/rules-snippets/{{NAME}}.md).
+```
+
+**Prompts** — For each `.github/prompts/*.prompt.md`:
+1. Check if a matching snippet exists in `.claude/prompt-snippets/`
+2. If no matching snippet: extract body → create `.claude/prompt-snippets/<name>.md`
+3. Replace body with thin wrapper:
+
+```markdown
+---
+{{ORIGINAL_FRONTMATTER}}
+---
+
+# {{TITLE}}
+
+Follow the prompt defined in [.claude/prompt-snippets/{{NAME}}.md](../../.claude/prompt-snippets/{{NAME}}.md).
+```
+
+**Agents** — For each `.github/agents/*.agent.md`:
+1. Check if a matching snippet exists in `.claude/agents-snippets/`
+2. If no matching snippet: extract body → create `.claude/agents-snippets/<name>.md`
+3. Replace body with thin wrapper:
+
+```markdown
+---
+{{ORIGINAL_FRONTMATTER}}
+---
+
+# {{AGENT_NAME}}
+
+Follow the agent definition in [.claude/agents-snippets/{{NAME}}.md](../../.claude/agents-snippets/{{NAME}}.md).
+```
+
+### Step 6: Convert .cursor/ Files to Thin Wrappers
+
+> **Parallelizable**: Process rules, commands, and agents in parallel.
+
+**Rules** — For each `.cursor/rules/*.mdc`:
+1. Check if a matching snippet exists in `.claude/rules-snippets/`
+2. If no matching snippet: extract body → create `.claude/rules-snippets/<name>.md`
+3. Replace body with thin wrapper preserving original `.mdc` frontmatter:
+
+```markdown
+---
+{{ORIGINAL_MDC_FRONTMATTER}}
+---
+
+# {{TITLE}}
+
+Follow the rules defined in [.claude/rules-snippets/{{NAME}}.md](../../.claude/rules-snippets/{{NAME}}.md).
+```
+
+**Commands** — For each `.cursor/commands/*.md`:
+1. Check if a matching snippet exists in `.claude/prompt-snippets/`
+2. If no matching snippet: extract body → create `.claude/prompt-snippets/<name>.md`
+3. Replace body with thin wrapper referencing `../../.claude/prompt-snippets/{{NAME}}.md`
+
+**Agents** — For each `.cursor/agents/*.agent.md`:
+1. Check if a matching snippet exists in `.claude/agents-snippets/`
+2. If no matching snippet: extract body → create `.claude/agents-snippets/<name>.md`
+3. Replace body with thin wrapper referencing `../../.claude/agents-snippets/{{NAME}}.md`
+
+### Step 7: Create .opencode/ Directory
+
+1. Create `.opencode/opencode.json` using only supported schema keys:
+
+   ```json
+   {
+     "$schema": "https://opencode.ai/config.json",
+     "instructions": [
+       "AGENTS.md",
+       ".opencode/rules/*.md"
+     ],
+     "skills": {
+       "paths": [
+         ".agents/skills/**/*.md",
+         ".claude/skills/**/*.md"
+       ]
+     },
+     "lsp": true
+   }
+   ```
+
+   **⚠️ Schema Validation:** Only use supported top-level keys from `https://opencode.ai/config.json`. Do NOT add unsupported keys like `rules`, `commands`, or `agents` as top-level entries — OpenCode discovers these via the `.opencode/` directory structure and the `instructions`/`skills` config arrays.
+
+   **Supported top-level keys:** `$schema`, `instructions`, `skills`, `agent`, `default_agent`, `model`, `small_model`, `provider`, `mcp`, `tools`, `permission`, `lsp`, `formatter`, `server`, `shell`, `command`, `plugin`, `watcher`, `snapshot`, `share`, `autoupdate`, `compaction`, `attachment`, `logLevel`, `disabled_providers`, `enabled_providers`, `tool_output`, `enterprise`, `experimental`
+
+2. **Copy OpenCode plugins**:
+   - Copy any `.opencode/plugins/*.mjs` files from the template
+
+3. Create `.opencode/commands/*.md` — one thin wrapper per `.claude/commands/*.md`:
+
+   ```markdown
+   ---
+   description: "{{DESCRIPTION}}"
+   agent: build
+   ---
+
+   # {{TITLE}}
+
+   @.claude/prompt-snippets/{{NAME}}.md
+   ```
+
+4. Create `.opencode/rules/*.md` — one thin wrapper per `.claude/rules/*.md`:
+
+   ```markdown
+   # {{TITLE}}
+
+   @.claude/rules-snippets/{{NAME}}.md
+   ```
+
+5. Create `.opencode/agents/*.md` — one thin wrapper per `.claude/agents/*.agent.md`:
+
+   ```markdown
+   ---
+   description: "{{DESCRIPTION}}"
+   mode: subagent
+   ---
+
+   # {{AGENT_NAME}}
+
+   @.claude/agents-snippets/{{NAME}}.md
+   ```
+
+### Step 8: Install Pre-Commit Hook
+
+Install the CHANGELOG/secrets enforcement hook to run before every commit:
+
+1. Copy `scripts/pre-commit-check.sh` from the template to the target project's `scripts/` directory
+2. Install as a git hook:
+
+   ```bash
+   cp scripts/pre-commit-check.sh .git/hooks/pre-commit
+   chmod +x .git/hooks/pre-commit
+   ```
+
+This enforces:
+- **CHANGELOG.md** — [Unreleased] must have content when non-trivial files are staged
+- **Zone.Identifier** — `*:Zone.Identifier` files are blocked from commit
+- **Secrets** — `.env`, `.env.*`, `*.key`, `*.pem` files are blocked from commit
+
+Use `git commit --no-verify` to bypass.
+
+### Step 9: Install Project Hooks
+
+1. Create `hooks/` directory in the target project
+2. Copy all files from the template's `hooks/*` directory (preserve sub-structure)
+3. Make `.js` files executable on Unix: `chmod +x hooks/*.js`
+
+### Step 10: Clean Up Duplicate Skills
+
+- Copy `.agents/rules/*.md` from the template
+
+1. Keep `.agents/skills/` as the source of truth
+2. For each of `.claude/skills/`, `.cursor/skills/`, `.github/skills/`:
+   - If directory exists, remove all subdirectories except `README.md`
+3. Remove any nested duplicates: `subagent-driven-development/subagent-driven-development/`
+
+### Step 11: Update CLAUDE.md
+
+Read the existing `CLAUDE.md` and add missing sections:
+
+1. **Multi-tool sections** — add if missing:
+   - GitHub Copilot section (references `.github/instructions/`, `.github/prompts/`, `.github/agents/`)
+   - Cursor IDE section (references `.cursor/rules/`, `.cursor/commands/`, `.cursor/agents/`)
+   - OpenCode section (references `.opencode/`)
+
+2. **Monorepo-specific sections** — preserve existing or add if missing:
+   - Apps section (references per-app `AGENTS.md` files)
+   - Packages section
+   - Build system section ({{BUILD_SYSTEM}} detected in Step 1)
+
+3. **Snippet architecture section** — add:
+   ```markdown
+   ## Snippet Architecture
+
+   Content lives in `.claude/{rules,prompt,agents}-snippets/`. All tool configs are thin wrappers:
+
+   - `.claude/rules/*.md` → `.claude/rules-snippets/`
+   - `.claude/commands/*.md` → `.claude/prompt-snippets/`
+   - `.claude/agents/*.agent.md` → `.claude/agents-snippets/`
+   - `.github/instructions/*.md` → `.claude/rules-snippets/`
+   - `.github/prompts/*.md` → `.claude/prompt-snippets/`
+   - `.github/agents/*.agent.md` → `.claude/agents-snippets/`
+   - `.cursor/rules/*.mdc` → `.claude/rules-snippets/`
+   - `.cursor/commands/*.md` → `.claude/prompt-snippets/`
+   - `.cursor/agents/*.agent.md` → `.claude/agents-snippets/`
+   - `.opencode/{commands,rules,agents}/*.md` → `@.claude/{snippet-type}/`
+   ```
+
+### Step 12: Create .toolkit-version File
+
+Write `3.0.0` to `.toolkit-version`.
+
+### Step 13: Validation
+
+Run these checks (parallelizable):
+
+1. **Snippet completeness**: Every `.md` file in `.claude/rules-snippets/`, `.claude/prompt-snippets/`, `.claude/agents-snippets/` must have content (not empty)
+2. **Thin wrapper correctness**: Every thin wrapper must contain a reference to its snippet with the correct relative path
+3. **Monorepo `paths:` preserved**: For files that had `paths:` frontmatter in `.claude/rules/`, verify the snippet also contains `paths:`
+4. **No lost placeholders**: Scan all snippet files — any `{{` in original must appear in snippet
+5. **No broken paths**: Verify all relative paths resolve correctly (e.g., `../rules-snippets/` from `.claude/rules/`)
+
+If `--verbose`: log each check result.
+
+### Step 14: Generate Upgrade Report
+
+```markdown
+## ✅ Monorepo Upgrade Complete: v3.0.0 (Snippet Architecture)
+
+### Build System: {{BUILD_SYSTEM}}
+
+### Directories Created
+
+| Directory | Files |
+|-----------|-------|
+| `.claude/rules-snippets/` | {{N}} |
+| `.claude/prompt-snippets/` | {{N}} |
+| `.claude/agents-snippets/` | {{N}} |
+| `.opencode/commands/` | {{N}} |
+| `.opencode/rules/` | {{N}} |
+| `.opencode/agents/` | {{N}} |
+
+### Files Converted to Thin Wrappers
+
+| Category | Count | Example |
+|----------|-------|---------|
+| `.claude/rules/` | {{N}} | `coding-standards.md` → thin wrapper |
+| `.claude/commands/` | {{N}} | `bootstrap.md` → thin wrapper |
+| `.claude/agents/` | {{N}} | `reviewer.agent.md` → thin wrapper |
+| `.github/instructions/` | {{N}} | `coding-standards.instructions.md` → thin wrapper |
+| `.github/prompts/` | {{N}} | `specify.prompt.md` → thin wrapper |
+| `.github/agents/` | {{N}} | `reviewer.agent.md` → thin wrapper |
+| `.cursor/rules/` | {{N}} | `coding-standards.mdc` → thin wrapper |
+| `.cursor/commands/` | {{N}} | `bootstrap.md` → thin wrapper |
+| `.cursor/agents/` | {{N}} | `reviewer.agent.md` → thin wrapper |
+
+### New Files
+
+| File | Purpose |
+|------|---------|
+| `.opencode/opencode.json` | OpenCode configuration |
+| `.toolkit-version` | Version tracking (`3.0.0`) |
+
+### Validation Results
+
+| Check | Status |
+|-------|--------|
+| Snippet completeness | ✅ All snippets have content |
+| Thin wrapper references | ✅ All wrappers reference correct snippets |
+| `paths:` frontmatter preserved | ✅ Monorepo scoping intact |
+| No lost placeholders | ✅ All `{{VAR}}` preserved |
+| No broken paths | ✅ All relative paths resolve |
+
+### Cleanup
+
+- Removed duplicate skill directories from `.claude/skills/`, `.cursor/skills/`, `.github/skills/`
+- Kept `.agents/skills/` as source of truth
+
+### Next Steps
+
+1. Review thin wrappers to confirm snippet paths are correct
+2. Run `/bootstrap-patch` to sync with latest toolkit templates
+3. Test a few commands (`/bootstrap`, `/specify`) to verify they work
+4. Commit the migration
+```
+
+### Step 15: Git Commit
+
+```bash
+git add -A
+git commit -m "chore: upgrade AI instructions to toolkit v3.0.0 (snippet architecture)"
+```
+
+## Error Handling
+
+- If a `.claude/rules/*.md` file is already a thin wrapper (< 20 lines with a snippet reference), skip it
+- If `.github/instructions/*.instructions.md` already references `.claude/rules-snippets/`, skip it
+- If a snippet file already exists with content, do not overwrite — log a warning
+- If `.opencode/` already exists, merge new files without overwriting existing ones
+
+## Notes
+
+- This command is idempotent — safe to re-run if interrupted
+- Per-app `AGENTS.md` files in `apps/*/` are not modified by this migration
+- Shared package docs in `packages/*/` are not modified
+- The `paths:` frontmatter in monorepo rules enables path-scoped rule application (e.g., `apps/**`, `packages/**`)