nitm-ai-dev-toolkit 3.0.23 → 4.0.0

package/CHANGELOG.md

@@ -7,8 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Migration
+
+- Toolkit v4 / package 4.0.0 requires native OpenCode V2 for OpenCode use; oh-my-opencode-slim >=3.0.0 requires OpenCode >=2.0.7. Native host config uses plural maps, ordered permissions, skill directories, and `mcp.servers`. Back up V1 (converted files are incompatible with it), preserve user/global settings and Slim's separate strict schema, leave the external starter unchanged, and activate on the next run/restart. Config `instructions` are ignored, ambient `AGENTS.md` works, `@refs` require explicit reads, and `request.body.temperature` is preserved but not currently sent by the runner. Preserve `lsp: true`; use project checks, not unavailable V2 LSP tools. Plugin/runtime integration is untested; publishing has not been executed.
+- Removed all three local Ponytail plugin copies (root, repo template, monorepo template). Both templates register the author's native V2 `@dietrichgebert/ponytail@4.12.0` package locally; `opentmux` remains commented as V1-only. No API port or bridge was added. The toolkit root alone omits `plugins` to inherit existing user/global registrations; no global config was changed. Existing targets remove only known obsolete toolkit Ponytail `.js`/`.mjs`/`.ts` copies after backup and approval, preserving unrelated plugins and deduplicating upstream registration locally.
+
 ### Fixed
 
+- All six repo/monorepo bootstrap flows now require a fail-closed `opencode --version` preflight before changes for confirmed OpenCode use: accept an optional leading `v`, reject V1 before OpenCode customization/migration or toolkit 4.0.0 marking, and stop on a missing CLI or unparseable version. Slim >=3.0.0 enforces OpenCode >=2.0.7; other-harness-only setup is unaffected. Focused instruction-order/version-metadata regression checks cover the guard.
 - Bootstrap audit/creation examples are explicitly conditional on confirmed Copilot use; completion reports describe performed harness-specific checks without assuming OpenCode configuration, Codex trust/loading, or Copilot/Cursor readiness. Codex-scoped install documentation now includes linked standards and their wrapper sources without implying other harness activation.
 
 ### Added
@@ -32,7 +38,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `bkt-cli` skill — Bitbucket CLI (`bkt`) command reference for repo and monorepo templates
 - `glab-cli` skill — GitLab CLI (`glab`) command reference for repo and monorepo templates
 - Ponytail skill bundle — 6 YAGNI/stdlib/native/minimum-discipline skills (`ponytail`, `ponytail-audit`, `ponytail-debt`, `ponytail-gain`, `ponytail-help`, `ponytail-review`)
-- Ponytail OpenCode plugin (`.opencode/plugins/ponytail.mjs`) loaded via the `plugin` config key
+- Author's upstream Ponytail OpenCode plugin registration (`@dietrichgebert/ponytail@4.12.0`) in both template configs; no bundled local plugin source
 - 7 ponytail hooks in `hooks/` (`ponytail-activate`, `ponytail-config`, `ponytail-instructions`, `ponytail-mode-tracker`, `ponytail-runtime`, `ponytail-statusline.sh`, `ponytail-statusline.ps1`), plus 2 hook configuration files for Claude/Codex and Copilot (`claude-codex-hooks.json`, `copilot-hooks.json`)
 - Ponytail rule in `.agents/rules/` and `.cursor/rules/` for ambient agent context
 - 6 ponytail commands (`ponytail`, `ponytail-audit`, `ponytail-debt`, `ponytail-gain`, `ponytail-help`, `ponytail-review`) with thin-wrapper sources in `.claude/prompt-snippets/`
@@ -74,7 +80,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added missing templates referenced in templates/README.md
 - `scripts/pre-commit-check.sh` — early-exit when no files are staged so the CHANGELOG check no longer fires on empty commits (PR #20 review)
 - `scripts/check-parity.sh` — removed duplicate `check_body_match` call for the cursor ↔ github prompt body (PR #20 review)
-- `.opencode/plugins/ponytail.mjs` — wrapped `writeMode` in a try/catch so an unwritable state directory no longer crashes the plugin (PR #20 review)
 - `ponytail-help` SKILL.md and prompt snippet — added missing `ponytail-audit`, `ponytail-debt`, and `/ponytail-gain` entries; corrected OpenCode slash-command count to six; rewrote the Claude-Code-specific Update section to describe the template update flow (PR #20 review)
 - `ponytail-gain` SKILL.md and prompt snippet (repo, monorepo, root) — replaced the phantom `benchmarks/` source reference with the upstream `DietrichGebert/ponytail` repo link (PR #20 review)
 - `README.md` — corrected "8 activation hooks" to "7 activation hooks" to match CHANGELOG and the actual hook count (PR #20 review)

package/README.md

@@ -65,7 +65,7 @@ This repository serves as a **template source** for AI development instructions
 ├── .cursor/            # This toolkit's own Cursor config
 ├── .github/            # This toolkit's own GitHub config
 ├── .opencode/          # This toolkit's own OpenCode config
-│   └── plugins/        # OpenCode plugins (ponytail mode manager, etc.)
+│   └── plugins/        # Other local OpenCode plugins (Ponytail uses upstream)
 ├── hooks/              # Claude Code / Copilot activation hooks (ponytail, etc.)
 └── AGENTS.md           # This toolkit's agent context
 ```
@@ -181,6 +181,37 @@ npx nitm-ai-dev-toolkit omo-slim-starter install
 
 After `install`, ask your AI agent to read and follow `.nitm/BOOTSTRAP.md`. Harnesses that supply a toolkit `/bootstrap` wrapper can also use it; **Codex has no native toolkit `/bootstrap` command**. Use `doctor` to verify the result.
 
+### Native OpenCode V2 (toolkit 4.0.0)
+
+Toolkit v4 requires **OpenCode V2 (major >=2)** for OpenCode use; **oh-my-opencode-slim >=3.0.0** requires **OpenCode >=2.0.7**. All repo/monorepo bootstrap, patch, and upgrade flows run `opencode --version` before changes, accepting an optional leading `v`. V1 must stop before OpenCode customization/migration or marking toolkit 4.0.0: upgrade OpenCode or remain on toolkit 3.x. A missing CLI or unparseable version stops OpenCode steps and version marking until the user confirms/installs a supported version. Confirm harness use from runtime evidence or ask; scaffold directories are not proof. Other-harness-only setup is unaffected.
+
+Publishing 4.0.0 has not been executed. The external `nitm-opencode-starter` is a separate package, not automatically upgraded.
+
+With user approval, merge this reproducible registration without replacing user/global plugins:
+
+```jsonc
+{ "plugins": ["oh-my-opencode-slim@3.0.0"] }
+```
+
+The toolkit root deliberately omits `plugins` to inherit user/global registrations; its existing upstream Ponytail registration is unchanged. Both target templates register the author's native V2 package `@dietrichgebert/ponytail@4.12.0` in their local `plugins` arrays, alongside `opencode-mem` and `@tarquinen/opencode-dcp@latest`; `opentmux` remains commented as V1-only. The local `ponytail.mjs` files are removed from the toolkit root and both templates; no local API port or bridge replaces them.
+
+For existing targets, back up and obtain approval before removing only known obsolete toolkit `.opencode/plugins/ponytail.js`, `.mjs`, or `.ts` copies. Preserve unrelated local plugins; merge/deduplicate upstream package registration locally where appropriate, without editing or overwriting global plugins. Native local plugins are discovered automatically, so do not register them twice. Slim's separate strict schema keeps its own `prompt`, `permission`, and `variant`: do not host-migrate plugin-owned fields. The root's no-`plugins` policy is specific to this toolkit repository, not target templates.
+
+| Setting | Native V2 form |
+| --- | --- |
+| Agents | `agents`, JSON `system` (Markdown body for file agents), `request.body.temperature`, model `provider/model#variant` |
+| Permissions | Ordered `permissions` with `action`, `resource`, `effect`; `shell`/`subagent` actions; last match wins |
+| Commands | `commands`; delegated commands use `subagent` |
+| Plugins | `plugins`; options use `{ "package": "…", "options": {} }` |
+| Skills | Directory-path array, e.g. `[".agents/skills"]`, not Markdown globs |
+| MCP | `mcp.servers`; `disabled` inverts legacy `enabled`; `timeout.catalog`/`timeout.execution` |
+
+Follow official V2 [migration](https://opencode.ai/v2/docs/migrate-v1), [config](https://opencode.ai/v2/docs/config), [agents](https://opencode.ai/v2/docs/agents), and [plugins](https://opencode.ai/v2/docs/build/plugins) docs. The published `https://opencode.ai/config.json` schema may describe V1; it is not native V2 validation authority.
+
+**Runtime limits:** config `instructions` entries are accepted but not loaded; ambient `AGENTS.md` works. `@refs` are ordinary text, not automatic attachments: agents must read referenced snippets explicitly. `request.body.temperature` remains in config, but the current runner does not send it. Plugin/runtime integration has not been tested. Preserve `lsp: true`, but V2 currently exposes no LSP tools or diagnostics: use project lint/typecheck/compiler commands.
+
+`--env opencode` includes minimal shared references for wrappers and AGENTS-linked standards without activating other harnesses. Merge, don't clobber: back up V1, preserve models/providers and user/global plugins, and ask before changes. Native-converted files are **incompatible with V1**. Activate on the next run/restart, then check behavior with the installed V2 runtime. `doctor` checks scaffold files/placeholders, not runtime behavior; do not substitute a V1 API/schema fetch or claim checks that were not run.
+
 ### Native Codex
 
 - `--env codex` includes `.codex/`, `.agents/`, and shared context, plus `.github/instructions/` and `.claude/rules-snippets/` solely to supply the standards linked from `AGENTS.md` and those standards' wrapper source content. It does not install other harness command, agent, or config directories. These reference files neither establish Copilot/Claude use nor load automatically as Codex rules; other harness scopes are unchanged.
@@ -701,7 +732,7 @@ This toolkit includes **32 pre-installed universal skills** in the `.agents/skil
 
 **These skills are ready to use immediately after copying the templates.** No `npx -y skills add -a <agent> <owner/repo> --skill '*' --agent github-copilot cursor` commands needed.
 
-The **ponytail** skill bundle is an integrated optional skill set from [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) that adds YAGNI/stdlib/native/one-line/minimum discipline to your AI agents. It includes 6 skills, 6 commands, an OpenCode plugin, 7 activation hooks, and ambient agent rules — all pre-configured and ready to use.
+The **ponytail** skill bundle is an integrated optional skill set from [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) that adds YAGNI/stdlib/native/one-line/minimum discipline to your AI agents. It includes 6 skills, 6 commands, 7 activation hooks, and ambient agent rules. OpenCode uses the author's upstream `@dietrichgebert/ponytail@4.12.0` package, not a bundled local plugin. See [native setup](#native-opencode-v2-toolkit-400); scaffolding alone does not establish activation.
 
 ### Additional Recommended Skills
 

package/bin/cli.js

@@ -19,7 +19,10 @@ const ENV_DIRS = {
   codex: ['.codex', '.agents', path.join('.github', 'instructions'), path.join('.claude', 'rules-snippets')],
   copilot: ['.github', '.vscode'],
   cursor: ['.cursor'],
-  opencode: ['.opencode'],
+  // Shared reference sources, not other harnesses' active config/agent wrappers.
+  opencode: ['.opencode', path.join('.agents', 'skills'),
+    path.join('.claude', 'agents-snippets'), path.join('.claude', 'prompt-snippets'),
+    path.join('.claude', 'rules-snippets'), path.join('.github', 'instructions')],
 };
 const ENV_INFO = {
   claude: { name: 'Claude Code', command: '/bootstrap (Claude Code command in .claude/commands/)' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nitm-ai-dev-toolkit",
-  "version": "3.0.23",
+  "version": "4.0.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/commands/ponytail-audit.md

@@ -1,15 +1,13 @@
 ---
-description: Audit the whole repo for over-engineering and identify what can be deleted
-allowed-tools: "Read, Grep, Bash"
+description: Audit the whole repo for over-engineering — find what can be deleted
+allowed-tools: "Read, Grep"
 argument-hint: "no arguments required"
 ---
 
-## Agent Dispatch
+# Ponytail Audit
 
+## Agent Dispatch
 > **Recommended agent:** `oracle`
 > Whole-repo over-engineering analysis
 
-
-# Ponytail Audit
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail-audit.md](../prompt-snippets/ponytail-audit.md).

package/src/monorepo/.claude/commands/ponytail-debt.md

@@ -1,15 +1,13 @@
 ---
 description: "Harvest ponytail: comments into a tracked debt ledger"
-allowed-tools: "Read, Grep, Bash"
+allowed-tools: "Read, Grep"
 argument-hint: "no arguments required"
 ---
 
-## Agent Dispatch
+# Ponytail Debt
 
+## Agent Dispatch
 > **Recommended agent:** `fixer`
 > Debt ledger harvesting
 
-
-# Ponytail Debt
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail-debt.md](../prompt-snippets/ponytail-debt.md).

package/src/monorepo/.claude/commands/ponytail-gain.md

@@ -4,12 +4,10 @@ allowed-tools: "Read"
 argument-hint: "no arguments required"
 ---
 
-## Agent Dispatch
+# Ponytail Gain
 
+## Agent Dispatch
 > **Recommended agent:** `fixer`
 > Impact scoreboard display
 
-
-# Ponytail Gain
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail-gain.md](../prompt-snippets/ponytail-gain.md).

package/src/monorepo/.claude/commands/ponytail-help.md

@@ -4,12 +4,10 @@ allowed-tools: "Read"
 argument-hint: "no arguments required"
 ---
 
-## Agent Dispatch
+# Ponytail Help
 
+## Agent Dispatch
 > **Recommended agent:** `fixer`
 > Quick-reference display
 
-
-# Ponytail Help
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail-help.md](../prompt-snippets/ponytail-help.md).

package/src/monorepo/.claude/commands/ponytail-review.md

@@ -1,15 +1,13 @@
 ---
-description: Review changes for over-engineering and identify what can be deleted
+description: Review changes for over-engineering — find what can be deleted
 allowed-tools: "Read, Grep"
 argument-hint: "no arguments required"
 ---
 
-## Agent Dispatch
+# Ponytail Review
 
+## Agent Dispatch
 > **Recommended agent:** `oracle`
 > Diff-level over-engineering review
 
-
-# Ponytail Review
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail-review.md](../prompt-snippets/ponytail-review.md).

package/src/monorepo/.claude/commands/ponytail.md

@@ -1,15 +1,13 @@
 ---
 description: Switch ponytail intensity level (lite/full/ultra/off)
-allowed-tools: "Read, Grep, Bash, Edit, Write"
+allowed-tools: "Read, Grep"
 argument-hint: "optional level (lite/full/ultra/off)"
 ---
 
-## Agent Dispatch
+# Ponytail
 
+## Agent Dispatch
 > **Recommended agent:** `fixer`
 > Apply YAGNI/stdlib discipline
 
-
-# Ponytail
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail.md](../prompt-snippets/ponytail.md).

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

@@ -1,9 +1,17 @@
-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.
+You are helping to patch AI instructions by comparing against supported toolkit v4.x templates from the ai-assisted-dev-toolkit repository's `v4.x` branch and merging updates into this project.
+
+## OpenCode version preflight (before any changes)
+
+- Confirm OpenCode use from actual session/runtime evidence or ask the user; directory presence alone is not proof. If only other harnesses are used, skip this preflight and all OpenCode steps.
+- For confirmed OpenCode use, run `opencode --version` before any project writes. Trim output and parse numeric major/minor/patch components, accepting an optional leading `v`; toolkit 4.x requires `major >= 2`.
+- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as `4.0.0`. Ask the user to upgrade OpenCode to V2 or remain on toolkit 3.x.
+- If the CLI is missing, fails, or output is unparseable, **STOP OpenCode steps** and leave the version marker unchanged; ask the user to confirm/install a supported OpenCode version, then rerun this check. Never assume V2.
+- If oh-my-opencode-slim >=3.0.0 is used or planned, require OpenCode >=2.0.7 (compare version components numerically); otherwise **STOP** before changes and ask to upgrade. Proceed only after this gate passes.
 
 ## 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).
+> Complete Step 1's source/version gates before dispatching parallel diff agents for independent file groups (rules, commands, prompts, instructions, skills, agents).
 > See `.claude/rules-snippets/subagent-workflow.md` for patterns.
 
 ## Usage
@@ -23,13 +31,16 @@ You are helping to patch AI instructions in this project by comparing against th
 
 1.  **Fetch Latest Templates**:
 
-    Clone or fetch the latest ai-assisted-dev-toolkit templates:
+    Fetch only the supported `v4.x` source branch:
 
     ```bash
+    set -e
     TOOLKIT_TEMP=$(mktemp -d)
-    git clone --depth 1 https://github.com/ninjasitm/ai-assisted-dev-toolkit.git "$TOOLKIT_TEMP"
+    git clone --depth 1 --branch v4.x https://github.com/ninjasitm/ai-assisted-dev-toolkit.git "$TOOLKIT_TEMP"
     ```
 
+    **Source availability gate:** If the clone fails or `v4.x` is unavailable (for example, not yet published), **STOP** before diff/apply/version marking. Do not fall back to the default branch or V3, and do not push/publish a branch to unblock this task; ask for an approved available v4.x source.
+
     Determine the correct source path based on project structure:
     - **Single repo**: Use `$TOOLKIT_TEMP/src/repo/`
     - **Monorepo**: Use `$TOOLKIT_TEMP/src/monorepo/`
@@ -42,9 +53,11 @@ You are helping to patch AI instructions in this project by comparing against th
 
     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)
+    - If missing: Verify the installed version or legacy state with the user; absence alone does not prove a pre-3.0 installation
 
-    Read the toolkit's version from `$TOOLKIT_TEMP/.toolkit-version` to compare.
+    Read the toolkit's version from the `version` field in `$TOOLKIT_TEMP/package.json` to compare; `.toolkit-version` tracks the target project's installed version.
+
+    **Source version guard (before diff/apply/version marking):** Parse source/target versions as SemVer and compare them (major/minor/patch numerically). If the fetched package's major is not `4`, or its version is older than the target `.toolkit-version`, **STOP** without diffing, applying changes, or updating the marker. Unknown/unparseable versions must also **STOP** and ask rather than guess. Never auto-downgrade.
 
     **Version Comparison:**
     - **Same version**: No structural changes expected
@@ -76,20 +89,20 @@ You are helping to patch AI instructions in this project by comparing against th
     | **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`                |
+    | **OpenCode Local Plugins** | `.opencode/plugins/*.{js,mjs,ts}`        | Inventory only; preserve unrelated plugins         |
     | **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.jsonc` Schema Validation:**
-
-    When patching `.opencode/opencode.jsonc`, **only add or modify supported top-level keys**. The schema is defined at `https://opencode.ai/config.json`. Do NOT add unsupported keys.
+    | **Toolkit Version**        | `.toolkit-version`                       | `package.json` `version` (toolkit root)             |
 
-    **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`
+    **OpenCode native V2 merge checks (confirmed OpenCode use only):**
 
-        **Do NOT add** keys like `rules`, `agents`, `commands`, `prompts` as top-level keys — OpenCode uses the `.opencode/` directory structure and `instructions` array instead.
+    Follow official V2 [migration](https://opencode.ai/v2/docs/migrate-v1), [config](https://opencode.ai/v2/docs/config), [agents](https://opencode.ai/v2/docs/agents), and [plugins](https://opencode.ai/v2/docs/build/plugins) docs. The published schema may describe V1; neither it nor a V1 API fetch validates native V2. Plural keys are intentional.
 
-    > **Watch out:** the ponytail template uses the `plugin` key (singular). If you see `plugins` (plural) in your `opencode.jsonc`, that's a typo and the plugin won't load.
+    - Use `agents`/`system`, `request.body.temperature`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`, last match wins), `commands`/`subagent`, `plugins` with `{ "package": "…", "options": {} }`, skill-directory arrays, and `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`.
+    - The version preflight must pass before changes. Back up V1 before native conversion (converted files are incompatible with V1). Preserve models/providers/user-global plugins. Only with approval, merge `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally. Slim's separate strict schema keeps `prompt`/`permission`/`variant`; do not host-migrate it or silently upgrade the separate external starter.
+    - **Ponytail replacement (plan here; apply after backup and approval in Step 5):** Remove only known obsolete toolkit-owned `.opencode/plugins/ponytail.js`, `.opencode/plugins/ponytail.mjs`, and `.opencode/plugins/ponytail.ts` copies. Preserve unrelated local plugins. Merge/deduplicate the author's native V2 `@dietrichgebert/ponytail@4.12.0` registration in the local `plugins` array where appropriate, retaining other registrations/options; do not edit global config. Keep `opentmux` commented as V1-only. Do not port local APIs or add bridges; runtime integration is untested. Native local discovery needs no duplicate registration.
+    - `instructions` entries are accepted but not loaded; ambient root/nested `AGENTS.md` works. `@refs` are ordinary text: explicitly read snippets. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`; use workspace lint/typecheck/compiler commands (no V2 LSP tools/diagnostics currently).
+    - `--env opencode` supplies minimal shared references without other harness activation. Activate on the next run/restart and report only installed-V2 checks actually run, not assumed runtime validation. Publishing 4.0.0 has not been executed.
 
 3.  **Diff Analysis** (parallelizable — dispatch one subagent per category):
 
@@ -100,7 +113,7 @@ You are helping to patch AI instructions in this project by comparing against th
     - **📝 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
+    - **⚠️ 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**:
     - Preserve project-specific `{{PLACEHOLDER}}` replacements (already-bootstrapped values)
@@ -161,7 +174,9 @@ You are helping to patch AI instructions in this project by comparing against th
       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:
+      d. **OpenCode plugins**: Apply only the approved Ponytail replacement above after backing up the known obsolete toolkit copies and local config; preserve all unrelated local/global plugins.
+      e. **Toolkit version**: Update `.toolkit-version` to the fetched toolkit version (`4.0.0` for this migration) 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:
       ```bash
       git add -A
       git commit -m "chore: patch AI instructions from toolkit [$(date +%Y-%m-%d)]"

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

@@ -1,12 +1,32 @@
 # Bootstrap Upgrade — Monorepo
 
-Migrate this monorepo's AI instruction files from the pre-3.0 inline pattern to the 3.0+ snippet-based architecture.
+Upgrade this monorepo to toolkit 4.0.0, including native OpenCode V2 for confirmed OpenCode users. For pre-3.0 installations, also migrate inline content to snippet-based architecture. Only modify confirmed harness targets; preserve unrelated harness/Codex behavior.
+
+## OpenCode version preflight (before any changes)
+
+- Confirm OpenCode use from actual session/runtime evidence or ask the user; directory presence alone is not proof. If only other harnesses are used, skip this preflight and all OpenCode steps.
+- For confirmed OpenCode use, run `opencode --version` before any project writes. Trim output and parse numeric major/minor/patch components, accepting an optional leading `v`; toolkit 4.x requires `major >= 2`.
+- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as `4.0.0`. Ask the user to upgrade OpenCode to V2 or remain on toolkit 3.x.
+- If the CLI is missing, fails, or output is unparseable, **STOP OpenCode steps** and leave the version marker unchanged; ask the user to confirm/install a supported OpenCode version, then rerun this check. Never assume V2.
+- If oh-my-opencode-slim >=3.0.0 is used or planned, require OpenCode >=2.0.7 (compare version components numerically); otherwise **STOP** before changes and ask to upgrade. Proceed only after this gate passes.
+
+## Toolkit version routing (before parallel dispatch)
+
+Read `.toolkit-version` and select the route before dispatching agents or changing files; apply only confirmed harness scopes:
+
+- **>=4.0.0**: Use bootstrap-patch and **STOP** this upgrade without rewrites or version marking.
+- **v3 (`3.x`)**: **Skip Steps 2–6 and 8–10.** Run only the relevant native OpenCode migration in Step 7 (confirmed OpenCode use only), then applicable approved merge/validation/version/report steps 11–15. Preserve existing snippet bodies/frontmatter and unrelated harness files.
+- **Pre-3.0 or missing marker**: Steps 2–6 and applicable approved legacy steps 8–10 require a verified legacy inline installation. A missing marker alone is not legacy evidence; if snippets already exist or the installed version cannot be verified, **STOP** and ask rather than extracting/rewriting them. Back up before legacy conversion and preserve existing customizations.
+- **Invalid or unverified version**: **STOP** and ask; never guess a route or downgrade.
+
+## OpenCode migration guardrails
+
+Back up V1; native-converted files are incompatible with V1. Preserve models/providers/user-global plugins. Templates register the author's native V2 package `@dietrichgebert/ponytail@4.12.0`; obsolete toolkit-local Ponytail copies are replaced only after backup and approval (Step 7), with no API port or bridge. Keep `opentmux` commented as V1-only. Only with approval, merge pinned `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally without replacing other registrations. Slim's separate strict schema retains `prompt`/`permission`/`variant`; do not host-migrate it or silently upgrade the separate external starter. Activate on the next run/restart; plugin/runtime integration is untested and publishing 4.0.0 has not been executed.
 
 ## 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.
+> Complete version routing above before parallel dispatch; only the verified legacy route may dispatch Steps 3–6, for confirmed harnesses. Applicable Steps 7–15 are sequential.
 
 ## Usage
 
@@ -25,9 +45,7 @@ Migrate this monorepo's AI instruction files from the pre-3.0 inline pattern to
 
 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.
+2. **Check existing version**: Apply the route selected above; inventory and confirm only its applicable steps and confirmed harness targets.
 
 3. **Detect build system** (for CLAUDE.md update in Step 10):
    - `turbo.json` → Turborepo
@@ -53,17 +71,17 @@ Migrate this monorepo's AI instruction files from the pre-3.0 inline pattern to
 5. **Present summary and ask for confirmation**:
 
    ```markdown
-   ## 🔄 Monorepo Upgrade: Pre-3.0 → v3.0.0 (Snippet Architecture)
+    ## 🔄 Monorepo Upgrade: toolkit v4.0.0
 
-   ### What will change
+    **Selected route**: verified legacy | v3 native OpenCode
 
-   - 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`
+    ### What will change (omit skipped steps for the selected route)
+
+    - Verified legacy only: create missing snippet directories, extract inline content from {{N}} files, and convert confirmed harness wrappers (Steps 2–6)
+    - Confirmed OpenCode only: merge native V2 host files and approved missing wrappers (Step 7)
+    - Verified legacy only: approved hook installation and verified identical duplicate skill cleanup (Steps 8–10); preserve custom skills
+    - Merge only applicable missing documentation and validate the selected route; v3 keeps existing snippet bodies/frontmatter unchanged
+   - Write `.toolkit-version` with `4.0.0` after the approved migration
 
    ### Monorepo-specific changes
 
@@ -76,6 +94,8 @@ Migrate this monorepo's AI instruction files from the pre-3.0 inline pattern to
 
 ### Step 2: Create Snippet Directories
 
+**Steps 2–6 are verified-legacy-only.** Skip this entire block for v3; never extract or rewrite existing snippet bodies/frontmatter. Process only confirmed harness targets.
+
 Create these directories if they don't exist:
 
 ```bash
@@ -233,27 +253,29 @@ Follow the rules defined in [.claude/rules-snippets/{{NAME}}.md](../../.claude/r
 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
+### Step 7: Create .opencode/ Directory (confirmed OpenCode use only)
+
+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. Create `.opencode/opencode.jsonc` using only supported schema keys:
+1. Merge `.opencode/opencode.jsonc` using native V2 fields:
 
    ```json
    {
-   	"$schema": "https://opencode.ai/config.json",
-   	"instructions": ["AGENTS.md", ".opencode/rules/*.md"],
-   	"skills": {
-   		"paths": [".agents/skills/**/*.md", ".claude/skills/**/*.md"]
-   	},
-   	"lsp": true
+     "$schema": "https://opencode.ai/config.json",
+      "instructions": ["AGENTS.md", ".opencode/rules/*.md"],
+      "skills": [".agents/skills"],
+      "plugins": ["@dietrichgebert/ponytail@4.12.0"],
+      "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.
+   Follow official V2 [migration](https://opencode.ai/v2/docs/migrate-v1), [config](https://opencode.ai/v2/docs/config), [agents](https://opencode.ai/v2/docs/agents), and [plugins](https://opencode.ai/v2/docs/build/plugins) docs. The published schema may describe V1; do not use it or a V1 API fetch as native V2 validation authority. Use `agents`/JSON `system` (Markdown bodies for file agents), `request.body.temperature`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`, last match wins), `commands`/`subagent`, `plugins` with `{ "package": "…", "options": {} }`, skill-directory arrays, and `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`.
 
-   **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`
+   `instructions` entries are accepted but not loaded; ambient root/nested `AGENTS.md` works. `@refs` are ordinary text, not attachments: wrappers must explicitly tell agents to read referenced snippets. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`; use workspace lint/typecheck/compiler commands (no current V2 LSP tools/diagnostics). `--env opencode` supplies minimal shared references without other harness activation. Verify using installed V2 after the next run/restart; report only checks actually run.
 
-2. **Copy OpenCode plugins**:
-   - Copy any `.opencode/plugins/*.mjs` files from the template
+2. **Replace obsolete toolkit Ponytail (backup and approval only)**:
+   - 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.
+   - Merge/deduplicate the author's native V2 `@dietrichgebert/ponytail@4.12.0` package in the local `plugins` array where appropriate, preserving other registrations/options. 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. Native local discovery needs no duplicate explicit registration; runtime integration remains untested.
 
 3. Create `.opencode/commands/*.md` — one thin wrapper per `.claude/commands/*.md`:
 
@@ -265,7 +287,7 @@ Follow the rules defined in [.claude/rules-snippets/{{NAME}}.md](../../.claude/r
 
    # {{TITLE}}
 
-   @.claude/prompt-snippets/{{NAME}}.md
+   Read and follow `.claude/prompt-snippets/{{NAME}}.md` before executing this command.
    ```
 
 4. Create `.opencode/rules/*.md` — one thin wrapper per `.claude/rules/*.md`:
@@ -273,7 +295,7 @@ Follow the rules defined in [.claude/rules-snippets/{{NAME}}.md](../../.claude/r
    ```markdown
    # {{TITLE}}
 
-   @.claude/rules-snippets/{{NAME}}.md
+   Read and follow `.claude/rules-snippets/{{NAME}}.md` when these standards apply.
    ```
 
 5. Create `.opencode/agents/*.md` — one thin wrapper per `.claude/agents/*.agent.md`:
@@ -286,7 +308,7 @@ Follow the rules defined in [.claude/rules-snippets/{{NAME}}.md](../../.claude/r
 
    # {{AGENT_NAME}}
 
-   @.claude/agents-snippets/{{NAME}}.md
+   Read and follow `.claude/agents-snippets/{{NAME}}.md` before performing this role.
    ```
 
 ### Step 8: Install Pre-Commit Hook
@@ -317,16 +339,14 @@ Use `git commit --no-verify` to bypass.
 
 ### 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/`
+- Merge approved `.agents/rules/*.md` additions without overwriting custom content; skip this step on the v3 route.
+- Preserve custom, unmatched, modified, and nested skill content; name or location alone does not prove duplication.
+- A candidate in a confirmed harness skill directory may be removed only after the same-name canonical `.agents/skills/<skill-name>/` copy exists and a complete recursive comparison (`diff -qr` or equivalent, including nested content) proves them identical. Missing canonical copy, differences, or comparison errors mean preserve and report, not delete.
+- Back up the verified identical duplicate and obtain explicit approval before removing only that duplicate; keep the canonical copy intact. No bulk deletion or name/location-based nested cleanup.
 
 ### Step 11: Update CLAUDE.md
 
-Read the existing `CLAUDE.md` and add missing sections:
+If `CLAUDE.md` is an applicable confirmed harness target, merge only missing relevant sections; preserve existing bodies/frontmatter:
 
 1. **Multi-tool sections** — add if missing:
    - GitHub Copilot section (references `.github/instructions/`, `.github/prompts/`, `.github/agents/`)
@@ -354,32 +374,37 @@ Read the existing `CLAUDE.md` and add missing sections:
    - `.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}/`
+   - `.opencode/{commands,rules,agents}/*.md` → explicit read instructions for `.claude/{snippet-type}/` (no automatic `@ref` attachment)
    ```
 
 ### Step 12: Create .toolkit-version File
 
-Write `3.0.0` to `.toolkit-version`.
+Write `4.0.0` to `.toolkit-version` only after the approved migration and OpenCode preflight pass (or OpenCode is confirmed out of scope).
 
 ### Step 13: Validation
 
-Run these checks (parallelizable):
+Run only checks applicable to the selected route and confirmed harnesses (parallelizable); on v3 compare retained snippet bodies/frontmatter to backups:
 
 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/`)
+6. **Custom skills preserved**: Only approved verified identical duplicates were removed; canonical copies and custom, unmatched, and nested content remain
 
 If `--verbose`: log each check result.
 
 ### Step 14: Generate Upgrade Report
 
+Include only operations/checks actually performed for the selected route; omit legacy extraction/cleanup rows on v3 and never pre-mark skipped checks as passed.
+
 ```markdown
-## ✅ Monorepo Upgrade Complete: v3.0.0 (Snippet Architecture)
+## ✅ Monorepo Upgrade Complete: v4.0.0
 
 ### Build System: {{BUILD_SYSTEM}}
 
+**Selected route**: verified legacy | v3 native OpenCode
+
 ### Directories Created
 
 | Directory                  | Files |
@@ -410,22 +435,22 @@ If `--verbose`: log each check result.
 | File                       | Purpose                    |
 | -------------------------- | -------------------------- |
 | `.opencode/opencode.jsonc` | OpenCode configuration     |
-| `.toolkit-version`         | Version tracking (`3.0.0`) |
+| `.toolkit-version`         | Version tracking (`4.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              |
+| Snippet completeness           | Report actual applicable checks            |
+| Thin wrapper references        | Report actual applicable checks            |
+| `paths:` frontmatter preserved | Report actual checks; v3 snippets unchanged |
+| No lost placeholders           | Report actual `{{VAR}}` preservation checks |
+| No broken paths                | Report actual applicable checks            |
 
 ### Cleanup
 
-- Removed duplicate skill directories from `.claude/skills/`, `.cursor/skills/`, `.github/skills/`
-- Kept `.agents/skills/` as source of truth
+- Removed only verified identical duplicates after comparison, backup, and approval (if performed)
+- Preserved custom, unmatched, and nested skill content and canonical `.agents/skills/` copies
 
 ### Next Steps
 
@@ -439,7 +464,7 @@ If `--verbose`: log each check result.
 
 ```bash
 git add -A
-git commit -m "chore: upgrade AI instructions to toolkit v3.0.0 (snippet architecture)"
+git commit -m "chore: upgrade AI instructions to toolkit v4.0.0"
 ```
 
 ## Error Handling
@@ -447,7 +472,7 @@ git commit -m "chore: upgrade AI instructions to toolkit v3.0.0 (snippet archite
 - 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
+- If `.opencode/` already exists, add missing files and propose native V2 conversion of existing host files; preserve customizations and skip files already migrated
 
 ## Notes