nitm-ai-dev-toolkit 3.0.15

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

@@ -0,0 +1,200 @@
+# Bootstrap Patch
+
+Fetch the latest AI instruction templates from the ai-assisted-dev-toolkit repository and apply any updated, new, or missing guidance to this project.
+
+## 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 |
+
+   ### ✅ 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/repo/.claude/prompt-snippets/bootstrap-upgrade.md

@@ -0,0 +1,357 @@
+# Bootstrap Upgrade to v3.0
+
+One-time migration from pre-3.0 inline pattern to 3.0+ snippet-based architecture. Converts all tool directories (`.claude/`, `.github/`, `.cursor/`) to thin wrappers referencing centralized snippets, creates `.opencode/` directory, and cleans up duplicate skills.
+
+## Usage
+
+```
+/bootstrap-upgrade
+/bootstrap-upgrade --dry-run
+/bootstrap-upgrade --verbose
+/bootstrap-upgrade --dry-run --verbose
+```
+
+- `--dry-run`: Show what would be changed without writing files
+- `--verbose`: Log every file operation with paths and content summaries
+
+## Orchestrator Checkpoint
+
+> **🛑 Before starting**: This command modifies files across 5+ directory trees (`.claude/`, `.github/`, `.cursor/`, `.opencode/`, `.agents/`).
+> Steps 3–6 are **parallelizable** — dispatch one subagent per directory tree (rules, commands, agents, instructions, prompts).
+> See `.claude/rules-snippets/subagent-workflow.md` for patterns.
+
+## Process
+
+### 1. Pre-flight Checks
+
+Run all checks before making any changes:
+
+1. **Detect project type**:
+   - If `apps/` and `packages/` directories exist at root → `monorepo` (use `src/monorepo/` templates)
+   - Otherwise → `repo` (use `src/repo/` templates)
+
+2. **Check toolkit version**:
+   - If `.toolkit-version` exists and contains `3.0.0` or higher → **abort** with message: "Project already on v3.0+. Run `/bootstrap-patch` for incremental updates."
+   - If `.toolkit-version` exists with a version below `3.0.0` → migration needed
+   - If `.toolkit-version` is missing → migration needed (legacy project)
+
+3. **Confirm migration scope**:
+
+   ```markdown
+   ## 🔄 Bootstrap Upgrade: pre-3.0 → 3.0+
+
+   **Project type**: repo | monorepo
+   **Current version**: <version or "none (legacy)">
+
+    ### What will happen:
+
+    1. Create snippet directories: `.claude/rules-snippets/`, `.claude/prompt-snippets/`, `.claude/agents-snippets/`
+    2. Extract content from `.claude/` files → snippet files
+    3. Convert `.claude/` files to thin wrappers
+    4. Convert `.github/` files to thin wrappers
+    5. Convert `.cursor/` files to thin wrappers
+    6. Create `.opencode/` directory with config and wrappers
+    7. Install pre-commit hook (CHANGELOG/Zone.Identifier/secrets enforcement)
+    8. Install project hooks (runtime hooks and ponytail support)
+    9. Clean up duplicate skill directories
+    10. Update `CLAUDE.md` with multi-tool sections
+    11. Create `.toolkit-version` with `3.0.0`
+    12. Commit all changes
+
+   Proceed? (Y/n)
+   ```
+
+   If `--dry-run`: show the report and **stop** — do not write any files.
+
+### 2. Create Snippet Directories
+
+```bash
+mkdir -p .claude/rules-snippets
+mkdir -p .claude/prompt-snippets
+mkdir -p .claude/agents-snippets
+```
+
+### 3. Extract Content from `.claude/` → Snippet Files
+
+**Parallelizable**: Process rules, commands, and agents independently.
+
+**Frontmatter extraction rule**: Content between the first `---` and the second `---` is frontmatter. Everything after the second `---` (including leading newline) is the body.
+
+| Source | Destination | Example |
+|--------|-------------|---------|
+| `.claude/rules/*.md` body | `.claude/rules-snippets/<name>.md` | `coding-standards.md` |
+| `.claude/commands/*.md` body | `.claude/prompt-snippets/<name>.md` | `bootstrap.md` |
+| `.claude/agents/*.agent.md` body | `.claude/agents-snippets/<name>.md` | `reviewer.agent.md` |
+
+For each file: read → extract body after frontmatter → write to snippet destination. **Preserve all `{{PLACEHOLDER}}` values exactly.**
+
+### 4. Convert `.claude/` Files to Thin Wrappers
+
+**Parallelizable**: Process rules, commands, and agents independently.
+
+Replace each file's body with a wrapper that preserves frontmatter and references the snippet:
+
+| File Type | Frontmatter to Keep | Reference Line |
+|-----------|---------------------|----------------|
+| `.claude/rules/*.md` | `applyTo`, `description` | `Follow the rules defined in [../rules-snippets/<name>.md](../rules-snippets/<name>.md).` |
+| `.claude/commands/*.md` | `description`, `allowed-tools`, `argument-hint` | `Follow the prompt defined in [../prompt-snippets/<name>.md](../prompt-snippets/<name>.md).` |
+| `.claude/agents/*.agent.md` | `name`, `description`, `tools` | `Follow the agent definition in [../agents-snippets/<name>.md](../agents-snippets/<name>.md).` |
+
+Wrapper format:
+```markdown
+---
+<original frontmatter preserved>
+---
+
+# <Title from original>
+
+<reference line from table above>
+```
+
+### 5. Convert `.github/` Files to Thin Wrappers
+
+**Parallelizable**: Process instructions, prompts, and agents independently.
+
+Same wrapper pattern as Step 4 — preserve frontmatter, replace body with reference:
+
+| Source | Frontmatter | Snippet Target | Reference Path |
+|--------|-------------|----------------|----------------|
+| `.github/instructions/*.instructions.md` | `applyTo`, `description` | `.claude/rules-snippets/<name>.md` | `../../.claude/rules-snippets/<name>.md` |
+| `.github/prompts/*.prompt.md` | `description` | `.claude/prompt-snippets/<name>.md` | `../../.claude/prompt-snippets/<name>.md` |
+| `.github/agents/*.agent.md` | `name`, `description`, `tools` | `.claude/agents-snippets/<name>.md` | `../../.claude/agents-snippets/<name>.md` |
+
+**Name mapping for instructions**: Strip `.instructions` suffix — `agent-conduct.instructions.md` → `agent-conduct.md`.
+
+**Missing snippet?** If an instruction file (e.g., `deployment.instructions.md`) has no matching `.claude/rules/` file, first create the snippet by copying the full content to `.claude/rules-snippets/<name>.md`, then convert to wrapper.
+
+For `.github/instructions/` wrappers, include 2–3 key bullet points after the reference line:
+```markdown
+Follow the rules defined in [../../.claude/rules-snippets/<name>.md](../../.claude/rules-snippets/<name>.md).
+
+Key points:
+- <first key point from original>
+- <second key point from original>
+```
+
+### 6. Convert `.cursor/` Files to Thin Wrappers
+
+**Parallelizable**: Process rules, commands, and agents independently.
+
+Same pattern as Steps 4–5 — preserve frontmatter, replace body with reference:
+
+| Source | Snippet Target | Reference Path |
+|--------|----------------|----------------|
+| `.cursor/rules/*.mdc` | `.claude/rules-snippets/<name>.md` | `../../.claude/rules-snippets/<name>.md` |
+| `.cursor/commands/*.md` | `.claude/prompt-snippets/<name>.md` | `../../.claude/prompt-snippets/<name>.md` |
+| `.cursor/agents/*.agent.md` | `.claude/agents-snippets/<name>.md` | `../../.claude/agents-snippets/<name>.md` |
+
+For `.cursor/rules/*.mdc`: preserve the original frontmatter exactly (it may use different field names than `.claude/` rules).
+
+### 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 wrappers using `@` import syntax** — one file per snippet:
+
+   | Directory | Source Snippets | Wrapper Body |
+   |-----------|-----------------|--------------|
+   | `.opencode/commands/*.md` | `.claude/prompt-snippets/` | `@.claude/prompt-snippets/<name>.md` |
+   | `.opencode/rules/*.md` | `.claude/rules-snippets/` | `@.claude/rules-snippets/<name>.md` |
+   | `.opencode/agents/*.md` | `.claude/agents-snippets/` | `@.claude/agents-snippets/<name>.md` |
+
+   Wrapper format for all three:
+   ```markdown
+   ---
+   description: "<description from snippet frontmatter>"
+   ---
+
+   # <Title>
+
+   @.claude/<snippet-type>/<name>.md
+   ```
+
+### 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.
+
+### 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`
+
+### 10. Clean Up Duplicate Skills
+
+- Copy `.agents/rules/*.md` from the template
+
+**Source of truth**: `.agents/skills/` — all other skill directories are duplicates.
+**Parallelizable with Steps 3–6**: Skill cleanup is independent of file conversion.
+
+```bash
+# Remove duplicate skill subdirs (keep README.md if present)
+find .claude/skills -mindepth 1 -maxdepth 1 -type d -exec rm -rf {} +
+find .cursor/skills -mindepth 1 -maxdepth 1 -type d -exec rm -rf {} +
+find .github/skills -mindepth 1 -maxdepth 1 -type d -exec rm -rf {} +
+
+# Remove nested duplicates (e.g., subagent-driven-development/subagent-driven-development/)
+rm -rf .agents/skills/subagent-driven-development/subagent-driven-development/
+```
+
+### 11. Update `CLAUDE.md`
+
+If `CLAUDE.md` is a thin redirect to `AGENTS.md`, add these sections if missing:
+
+1. **Snippet Directories** section with links to `rules-snippets/`, `prompt-snippets/`, `agents-snippets/`
+2. **Multi-Tool Support** section with links to `.github/`, `.cursor/`, `.opencode/`
+3. **Related Documentation** entries for snippet dirs, `.opencode/`, and `.toolkit-version`
+
+See existing `CLAUDE.md` in the toolkit template (`src/repo/CLAUDE.md`) for the exact format.
+
+### 12. Create `.toolkit-version` File
+
+```bash
+echo "3.0.0" > .toolkit-version
+```
+
+### 13. Validation
+
+Run all checks after writing files:
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| Snippet files exist | `ls -la .claude/{rules,prompt,agents}-snippets/` | All files > 0 bytes |
+| Thin wrappers reference correct paths | Grep each wrapper for its reference line | Every reference points to an existing snippet |
+| No `{{PLACEHOLDER}}` lost | `grep -r '{{' .claude/*-snippets/` | Count matches original files |
+| No broken relative paths | For each wrapper, verify linked snippet exists | All links resolve |
+| `.opencode/` complete | Check `opencode.json` + one file per snippet in commands/, rules/, agents/ | Counts match |
+| Duplicate skills removed | No subdirs in `.claude/skills/`, `.cursor/skills/`, `.github/skills/` (except README.md) | Clean |
+
+If `--verbose`: log each check result with file paths.
+
+### 14. Generate Upgrade Report
+
+Output the report to stdout (and optionally to `docs/upgrade-report-v3.md`):
+
+```markdown
+## 🚀 Bootstrap Upgrade Report
+
+**From**: pre-3.0 (inline pattern)
+**To**: 3.0+ (snippet-based architecture)
+**Date**: {{DATE}}
+**Dry run**: yes | no
+
+### Snippet Directories Created
+- `.claude/rules-snippets/` — X files
+- `.claude/prompt-snippets/` — X files
+- `.claude/agents-snippets/` — X files
+
+### Files Converted to Thin Wrappers
+- `.claude/rules/` — X files
+- `.claude/commands/` — X files
+- `.claude/agents/` — X files
+- `.github/instructions/` — X files
+- `.github/prompts/` — X files
+- `.github/agents/` — X files
+- `.cursor/rules/` — X files
+- `.cursor/commands/` — X files
+- `.cursor/agents/` — X files
+
+### New Directories Created
+- `.opencode/` — X files (config, commands, rules, agents)
+
+### Cleanup
+- Removed X duplicate skill directories
+- Removed X nested duplicates
+
+### Files Created
+- `.toolkit-version` — 3.0.0
+
+### Validation
+- [x] All snippet files exist and have content
+- [x] All thin wrappers reference correct snippets
+- [x] No {{PLACEHOLDER}} syntax lost
+- [x] No broken relative paths
+- [x] .opencode/ directory complete
+- [x] Duplicate skills removed
+```
+
+If `--verbose`: include a file-by-file log of every operation.
+
+### 15. Git Commit
+
+If not `--dry-run`, stage and commit all changes:
+
+```bash
+git add -A
+git commit -m "chore: upgrade AI instructions to toolkit v3.0.0 (snippet architecture)"
+```
+
+If `--dry-run`: skip commit, note in report: "Dry run — no changes committed."
+
+## Parallelization Summary
+
+Steps that can run in parallel (dispatch subagents):
+
+| Step | Parallelizable Groups |
+|------|-----------------------|
+| 3 | rules extraction ‖ commands extraction ‖ agents extraction |
+| 4 | rules wrappers ‖ commands wrappers ‖ agents wrappers |
+| 5 | instructions wrappers ‖ prompts wrappers ‖ agents wrappers |
+| 6 | rules wrappers ‖ commands wrappers ‖ agents wrappers |
+| 10 | Independent of 3–6 — can run in parallel with file conversion |
+
+Steps that must be sequential: 1 → 2 → (3‖4‖5‖6‖10) → 7 → 8 → 9 → 11 → 12 → 13 → 14 → 15.
+
+## Error Handling
+
+- If a file has no frontmatter: treat entire file as body content, create wrapper with empty frontmatter fields
+- If a snippet file already exists: **skip** with warning (do not overwrite)
+- If `.opencode/` already exists: merge — add missing files, skip existing ones
+- If git commit fails: show error, suggest manual commit
+- If any validation check fails: report the failure but continue with remaining checks
+
+## Notes
+
+- This is a **one-time operation** — running it again on an already-migrated project should be a no-op (pre-flight check aborts)
+- All `{{PLACEHOLDER}}` values are preserved exactly — this migration changes file structure, not content
+- Project-specific customizations in file bodies are preserved in the extracted snippets
+- After upgrade, use `/bootstrap-patch` for incremental template updates