nitm-ai-dev-toolkit 3.0.23 → 4.0.0

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

@@ -2,6 +2,14 @@ You are helping to bootstrap AI instructions for this monorepo by analyzing the
 
 > **Merge, don't clobber.** If a target file already exists and carries project-specific content — customized agents, rules, skills, or `{{PLACEHOLDER}}` values already replaced — preserve it. Add missing structure; never overwrite a customized file with template defaults. When a template change conflicts with an existing customization, merge the addition and flag it for the user rather than replacing the file. For incremental updates after the first bootstrap, prefer `/bootstrap-patch`, which is purpose-built for meticulous merging.
 
+## 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.
+
 ## Harness selection and native Codex targets
 
 **Codex:** `/bootstrap` is not a native Codex command. For npm installs, ask Codex to read and follow `.nitm/BOOTSTRAP.md`. For manually copied templates without `.nitm/`, ask it to read and follow `.claude/prompt-snippets/bootstrap.md` as a task document.
@@ -133,6 +141,8 @@ You are helping to bootstrap AI instructions for this monorepo by analyzing the
 
 7. **Update Template Files**:
 
+   For confirmed OpenCode use, complete the Ponytail pre-activation cleanup below before customizing OpenCode files or marking the migration complete.
+
    **Root Level:**
    - `AGENTS.md` (include project management section)
    - `.agents/skills/*/SKILL.md` (shared native skills, including Codex)
@@ -148,27 +158,36 @@ You are helping to bootstrap AI instructions for this monorepo by analyzing the
    - `.claude/rules-snippets/*.md` (rules content — source of truth)
    - `.claude/prompt-snippets/*.md` (prompt content — source of truth)
    - `.claude/agents-snippets/*.md` (agent definitions — source of truth)
-   - `.opencode/opencode.jsonc` (OpenCode configuration — ⚠️ see schema validation below)
+   - `.opencode/opencode.jsonc` (OpenCode configuration — see native V2 checks below)
    - `.opencode/commands/*.md` (OpenCode commands)
    - `.opencode/rules/*.md` (OpenCode rules)
    - `.opencode/agents/*.md` (OpenCode agents)
    - `.toolkit-version` (version tracking)
    - `CLAUDE.md` (if it contains placeholders)
 
-   **⚠️ OpenCode `opencode.jsonc` Schema Validation:**
+   **OpenCode native V2 checks (only for confirmed OpenCode use):**
+
+   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, not V1 API/schema fetches. The published schema may describe V1; do not reject native plural keys based on it.
 
-   When creating or modifying `.opencode/opencode.jsonc`, **only use supported top-level keys**. The schema is defined at `https://opencode.ai/config.json`. Adding unsupported keys will cause validation errors.
+   - After the version preflight passes, 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`.
+   - Back up V1; native-converted files are incompatible with V1. Merge rather than clobber models/providers/user-global plugins. Only with approval, merge pinned `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally. Slim's separate strict schema retains `prompt`/`permission`/`variant`; do not host-migrate it or silently upgrade the separate external starter.
+   - Templates register the author's native V2 package `@dietrichgebert/ponytail@4.12.0` locally; no local Ponytail source is bundled or ported. Keep `opentmux` commented as V1-only. Native local discovery needs no duplicate registration; do not introduce API ports or bridges or claim tested runtime integration.
+   - Config `instructions` entries are 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; report only checks actually run with installed V2. Scaffold/placeholder checks are not runtime validation; publishing 4.0.0 has not been executed.
 
-   **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`
+   **Ponytail pre-activation cleanup (confirmed OpenCode use only):**
 
-   **Do NOT add keys not listed above** (e.g., `rules`, `agents`, `commands`, `prompts` as top-level keys — these are configured via `instructions`, `skills`, and the `.opencode/` directory structure instead).
+   1. In this bootstrap flow, inspect `.opencode/plugins/ponytail.js`, `.opencode/plugins/ponytail.mjs`, and `.opencode/plugins/ponytail.ts` for existing-target leftovers. Verify obsolete toolkit ownership from contents/provenance, not filename alone; absent paths need no deletion. Preserve unrelated/custom plugins and global config.
+   2. Back up the local config and verified obsolete toolkit copies, obtain explicit removal approval, then remove ONLY those copies. Do not automatically delete files in the CLI or remove custom plugins.
+   3. With approval, merge/deduplicate upstream `@dietrichgebert/ponytail@4.12.0` registration locally where appropriate, preserving other registrations/options and leaving global config untouched. No API port or bridge.
+   4. If any present copy's ownership or safe removal is unverified, or required removal approval is denied, **STOP OpenCode activation and migration completion**; leave `.toolkit-version` unchanged and report blocked, not complete. Proceed/restart only after this gate passes; runtime integration remains untested.
 
    **Create Toolkit Version File:**
 
-   Create a `.toolkit-version` file in the project root with the current toolkit version:
+   Create a `.toolkit-version` file in the project root with the current toolkit version only after the OpenCode preflight and Ponytail cleanup gate pass (or OpenCode is confirmed out of scope):
 
    ```
-    3.0.0
+    4.0.0
    ```
 
    This file enables `bootstrap-patch` to detect version changes and apply migrations automatically.
@@ -251,9 +270,9 @@ For multi-app monorepos with different frameworks, list all with app context (e.
 
 #### Agent Tool & Permission Calibration
 
-The `tools:` block (Claude Code, GitHub Copilot) and `permission:` block (OpenCode) must match each agent's role **and** the detected project. Templates ship with defaults, but calibrate them during bootstrap so every agent can do its job without being over-provisioned.
+The `tools:` block (Claude Code, GitHub Copilot) and ordered `permissions:` rules (OpenCode V2) must match each agent's role **and** the detected project. Inspect actual defaults before proposing changes; calibrate without over-provisioning.
 
-**Codex native calibration:** customize project instructions and skills, not Claude/Copilot `tools:` frontmatter or OpenCode `permission:` blocks. This toolkit ships no Codex custom-agent format. Use only delegation capabilities actually available in the running harness; do not generate agent files from this table or change native security settings to simulate per-role tool gating.
+**Codex native calibration:** customize project instructions and skills, not Claude/Copilot `tools:` frontmatter or OpenCode `permissions:` rules. This toolkit ships no Codex custom-agent format. Use only delegation capabilities actually available in the running harness; do not generate agent files from this table or change native security settings to simulate per-role tool gating.
 
 **1. Capability baseline per role** — what the agent functionally needs:
 
@@ -268,22 +287,22 @@ The `tools:` block (Claude Code, GitHub Copilot) and `permission:` block (OpenCo
 
 **2. Translate the baseline to each platform's syntax:**
 
-| Capability         | Claude Code     | GitHub Copilot                         | OpenCode (`permission:`) | Cursor  |
+| Capability         | Claude Code     | GitHub Copilot                         | OpenCode (`permissions:` rule) | Cursor  |
 | ------------------ | --------------- | -------------------------------------- | ------------------------ | ------- |
 | read               | `Read`          | `read`                                 | default                  | default |
 | search             | `Grep`          | `search`                               | default                  | default |
-| write / edit files | `Write`, `Edit` | `edit`                                 | `edit: allow`            | default |
-| terminal           | `Bash(*)`       | `runInTerminal`, `terminalLastCommand` | `bash: allow`            | default |
-| spawn subagents    | `agent`         | n/a                                    | `task: allow`            | default |
+| write / edit files | `Write`, `Edit` | `edit`                                 | `{action: edit, resource: "*", effect: allow}` | default |
+| terminal           | `Bash(*)`       | `runInTerminal`, `terminalLastCommand` | `{action: shell, resource: "*", effect: allow}` | default |
+| spawn subagents    | `agent`         | n/a                                    | `{action: subagent, resource: "*", effect: allow}` | default |
 
 > **Cursor note:** these templates declare no `tools:` field, so Cursor subagents inherit the full default toolset. Read-only intent (Researcher, Reviewer) is enforced by the agent's instructions, not tool gating. If your Cursor version supports per-agent tool restriction, add a `tools:` field to match the baseline.
 
 **3. Project-driven adjustments** (widen or narrow from the baseline):
 
-- **Planner** — If plans are persisted to files (e.g. `docs/plans/`, `docs/features/`), it MUST have write + terminal. The Copilot default is read-only (`["read","search"]`) and the OpenCode default denies `edit`/`bash` — **widen both** to the baseline. The Claude default already has `Write` but lacks `Bash(*)` — add it so the planner can run `git log` / discover tests.
-- **Documenter** — Always needs edit (updates existing docs); needs terminal when the project uses doc generators (mkdocs, typedoc, sphinx, docusaurus). The OpenCode default denies `edit`/`bash` and the Claude default omits `Edit`/`Bash(*)` — **widen both** to the baseline. The Copilot default is already correct.
+- **Planner** — Persisted plans need write + terminal. If Copilot is read-only (`["read","search"]`), widen to the baseline. If Claude lacks `Bash(*)`, add it for `git log` / test discovery. For OpenCode, inspect ordered rules and propose `edit`/`shell` allows only when missing and approved.
+- **Documenter** — Needs edit for docs, terminal for doc generators. If Claude omits `Edit`/`Bash(*)`, propose them. For OpenCode, inspect ordered `edit`/`shell` rules against this baseline, not presumed legacy defaults.
 - **Researcher** — Must stay read-only on every platform. The Claude Code default currently grants `Write` — **remove it** (`["Read","Grep"]`).
-- **Reviewer** — Read + terminal only; never grant write/edit. The OpenCode default denies `bash` — **allow `bash`** (keep `edit: deny`) so it can run `git diff` / tests. The Claude default grants `Write` — **remove it** (keep `Bash(*)`).
+- **Reviewer** — Read + terminal only; never grant write/edit. OpenCode ordered rules should allow `shell` and deny `edit` for this baseline. If Claude grants `Write`, remove it (keep `Bash(*)`).
 - **Worker agents** (Planner, Implementer, Red, Green, Refactor) — in a monorepo keep `user-invocable: false`; they are coordinator-dispatched only.
 
 **4. Apply:** for each agent file (`.claude/agents/*.agent.md`, `.github/agents/*.agent.md`, `.opencode/agents/*.md`), compare the declared tools/permissions to the calibrated baseline and adjust. List the changes, then confirm before applying.

package/src/monorepo/.github/prompts/review-staged.prompt.md

@@ -1,5 +1,5 @@
 ---
-description: Review currently staged files before committing
+description: Review staged files with detailed code review
 tools: ["read", "search"]
 argument-hint: "no arguments required"
 ---

package/src/monorepo/.opencode/agents/admin-portal.md

@@ -1,10 +1,16 @@
 ---
 description: "Build administrator portals with RBAC, system dashboards, reporting, analytics, and operational tooling. Specializes in admin frameworks and monitoring ecosystem tools."
 mode: subagent
-temperature: 0.1
-permission:
-  edit: allow
-  bash: allow
+request:
+  body:
+    temperature: 0.1
+permissions:
+  - action: edit
+    resource: "*"
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: allow
 ---
 
 # Admin Portal Specialist

package/src/monorepo/.opencode/agents/api-specialist.md

@@ -1,10 +1,16 @@
 ---
 description: "Design and implement API architecture, documentation, and developer experience. Use for REST design, GraphQL, OpenAPI specs, SDK generation, API versioning, and integration patterns."
 mode: subagent
-temperature: 0.1
-permission:
-  edit: allow
-  bash: allow
+request:
+  body:
+    temperature: 0.1
+permissions:
+  - action: edit
+    resource: "*"
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: allow
 ---
 
 # API Specialist

package/src/monorepo/.opencode/agents/backend-architect.md

@@ -1,10 +1,16 @@
 ---
 description: "Design APIs, databases, and server-side architecture. Use for scalable backend systems, data modeling, caching strategies, system design, and infrastructure decisions."
 mode: subagent
-temperature: 0.1
-permission:
-  edit: allow
-  bash: allow
+request:
+  body:
+    temperature: 0.1
+permissions:
+  - action: edit
+    resource: "*"
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: allow
 ---
 
 # Backend Architect

package/src/monorepo/.opencode/agents/documenter.md

@@ -1,10 +1,16 @@
 ---
 description: "Analyze codebases and create comprehensive documentation. Use for AGENTS.md, README files, API docs, architecture documentation, and onboarding guides."
 mode: subagent
-temperature: 0.1
-permission:
-  edit: allow
-  bash: allow
+request:
+  body:
+    temperature: 0.1
+permissions:
+  - action: edit
+    resource: "*"
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: allow
 ---
 
 # Documenter

package/src/monorepo/.opencode/agents/feature-builder.md

@@ -1,11 +1,19 @@
 ---
 description: "Coordinate end-to-end feature development using subagents for planning, implementation, and review. Orchestrates the full development lifecycle."
 mode: subagent
-temperature: 0.3
-permission:
-  edit: allow
-  bash: allow
-  task: allow
+request:
+  body:
+    temperature: 0.3
+permissions:
+  - action: edit
+    resource: "*"
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: allow
+  - action: subagent
+    resource: "*"
+    effect: allow
 ---
 
 # Feature Builder — Coordinator

package/src/monorepo/.opencode/agents/frontend-developer.md

@@ -1,10 +1,16 @@
 ---
 description: "Build user interfaces, implement components, handle state management, and optimize frontend performance. Use for responsive, accessible, and performant web applications."
 mode: subagent
-temperature: 0.1
-permission:
-  edit: allow
-  bash: allow
+request:
+  body:
+    temperature: 0.1
+permissions:
+  - action: edit
+    resource: "*"
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: allow
 ---
 
 # Frontend Developer

package/src/monorepo/.opencode/agents/green.md

@@ -1,10 +1,16 @@
 ---
 description: "Write minimal code to make failing tests pass. Part of the TDD red-green-refactor cycle."
 mode: subagent
-temperature: 0.1
-permission:
-  edit: allow
-  bash: allow
+request:
+  body:
+    temperature: 0.1
+permissions:
+  - action: edit
+    resource: "*"
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: allow
 ---
 
 # Green Agent (TDD — Make Tests Pass)

package/src/monorepo/.opencode/agents/implementer.md

@@ -1,10 +1,16 @@
 ---
 description: "Implement code changes for a specific task. Follow TDD, write tests alongside code, and self-review before reporting completion."
 mode: subagent
-temperature: 0.1
-permission:
-  edit: allow
-  bash: allow
+request:
+  body:
+    temperature: 0.1
+permissions:
+  - action: edit
+    resource: "*"
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: allow
 ---
 
 # Implementer Agent

package/src/monorepo/.opencode/agents/planner.md

@@ -1,10 +1,16 @@
 ---
 description: "Break down feature requests into implementation tasks. Read specifications, analyze codebase patterns, and produce structured plans with dependencies."
 mode: subagent
-temperature: 0.1
-permission:
-  edit: allow
-  bash: allow
+request:
+  body:
+    temperature: 0.1
+permissions:
+  - action: edit
+    resource: "*"
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: allow
 ---
 
 # Planner Agent

package/src/monorepo/.opencode/agents/red.md

@@ -1,10 +1,16 @@
 ---
 description: "Write failing tests that define expected behavior. Part of the TDD red-green-refactor cycle."
 mode: subagent
-temperature: 0.1
-permission:
-  edit: allow
-  bash: allow
+request:
+  body:
+    temperature: 0.1
+permissions:
+  - action: edit
+    resource: "*"
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: allow
 ---
 
 # Red Agent (TDD — Write Failing Tests)

package/src/monorepo/.opencode/agents/refactor.md

@@ -1,10 +1,16 @@
 ---
 description: "Improve code quality and structure while keeping all tests passing. Part of the TDD red-green-refactor cycle."
 mode: subagent
-temperature: 0.1
-permission:
-  edit: allow
-  bash: allow
+request:
+  body:
+    temperature: 0.1
+permissions:
+  - action: edit
+    resource: "*"
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: allow
 ---
 
 # Refactor Agent (TDD — Improve Code Quality)

package/src/monorepo/.opencode/agents/researcher.md

@@ -1,10 +1,16 @@
 ---
 description: "Research codebase patterns, dependencies, and technical context. Analyze code structure, find relevant examples, and report findings without making changes."
 mode: subagent
-temperature: 0.1
-permission:
-  edit: deny
-  bash: deny
+request:
+  body:
+    temperature: 0.1
+permissions:
+  - action: edit
+    resource: "*"
+    effect: deny
+  - action: shell
+    resource: "*"
+    effect: deny
 ---
 
 # Researcher Agent

package/src/monorepo/.opencode/agents/reviewer.md

@@ -1,10 +1,16 @@
 ---
 description: "Review code changes for correctness, code quality, security, and adherence to project patterns. Provide actionable feedback with specific file and line references. Use immediately after writing or modifying code, or as a quality gate in orchestrated workflows."
 mode: subagent
-temperature: 0.1
-permission:
-  edit: deny
-  bash: allow
+request:
+  body:
+    temperature: 0.1
+permissions:
+  - action: edit
+    resource: "*"
+    effect: deny
+  - action: shell
+    resource: "*"
+    effect: allow
 ---
 
 # Reviewer Agent

package/src/monorepo/.opencode/agents/tdd.md

@@ -1,11 +1,19 @@
 ---
 description: "Implement a feature using test-driven development with red-green-refactor cycle. Coordinates specialized subagents for writing failing tests, implementing code, and refactoring."
 mode: subagent
-temperature: 0.3
-permission:
-  edit: allow
-  bash: allow
-  task: allow
+request:
+  body:
+    temperature: 0.3
+permissions:
+  - action: edit
+    resource: "*"
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: allow
+  - action: subagent
+    resource: "*"
+    effect: allow
 ---
 
 # TDD Coordinator Agent

package/src/monorepo/.opencode/opencode.jsonc

@@ -5,17 +5,15 @@
 		".opencode/rules/*.md",
 		".agents/skills/orient-to-recent-work/SKILL.md"
 	],
-	"skills": {
-		"paths": [
-			".agents/skills/**/*.md",
-			".claude/skills/**/*.md"
-		]
-	},
-	"plugin": [
+	"skills": [
+		".agents/skills",
+		".claude/skills"
+	],
+	"plugins": [
 		"opencode-mem",
 		"@tarquinen/opencode-dcp@latest",
-		"@dietrichgebert/ponytail",
-		"opentmux"
+		"@dietrichgebert/ponytail@4.12.0"
+		// "opentmux": V1-only; enable only after it supports V2.
 	],
 	"lsp": true
-}
+}

package/src/monorepo/AGENTS.md

@@ -102,6 +102,14 @@ Each app has its own `AGENTS.md` with detailed patterns:
 - `{{APP_DIR}}/{{APP_NAME_1}}/AGENTS.md` - {{APP_1_DESCRIPTION}} patterns
 - `{{APP_DIR}}/{{APP_NAME_2}}/AGENTS.md` - {{APP_2_DESCRIPTION}} patterns
 
+## OpenCode V2 Context
+
+OpenCode use with toolkit v4 requires native V2; Slim >=3.0.0 requires OpenCode >=2.0.7. Read [native setup](README.md#native-opencode-v2) before migration. All bootstrap flows run `opencode --version` before changes for confirmed OpenCode use: V1 must stop and upgrade OpenCode or remain on toolkit 3.x; missing/unparseable versions block OpenCode steps and toolkit 4.0.0 marking. Directory presence is not harness proof; other-harness-only setup is unaffected.
+
+Use `agents`/`system`, `request.body.temperature`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`), `commands`, `plugins`, directory-based `skills`, and `mcp.servers`. Preserve user models/providers/plugins and Slim's separate strict schema; do not host-migrate its `prompt`/`permission`/`variant` fields or silently upgrade the separate external starter. Templates register the author's native V2 `@dietrichgebert/ponytail@4.12.0` locally instead of a bundled Ponytail plugin; `opentmux` stays commented as V1-only. Remove only known obsolete toolkit Ponytail `.js`/`.mjs`/`.ts` copies after backup and approval, preserve unrelated local plugins, and merge/deduplicate upstream registration locally without editing global config. No local API port or bridge is used; plugin/runtime integration is untested.
+
+Ambient root/nested `AGENTS.md` works; config `instructions` entries do not load. `@refs` are ordinary text: explicitly read linked snippets. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`; use workspace lint/typecheck/compiler commands, not unavailable V2 LSP diagnostics. Back up V1 before native conversion; converted files are incompatible with V1. Activate on the next run/restart.
+
 ## Detailed Instructions
 
 ### Native Codex

package/src/monorepo/CLAUDE.md

@@ -59,5 +59,5 @@
 - Commands are in `.opencode/commands/`.
 - Rules are in `.opencode/rules/`.
 - Agents are in `.opencode/agents/`.
-- Instructions are loaded from `AGENTS.md`, `.github/instructions/`, and `.claude/rules/`.
+- Native V2 loads ambient `AGENTS.md`, not config `instructions` entries. Explicitly read referenced snippets (`@refs` are ordinary text, not attachments). See [OpenCode setup](README.md#native-opencode-v2).
 - Skills are loaded from `.agents/skills/` and `.claude/skills/`.

package/src/monorepo/README.md

@@ -50,6 +50,20 @@ This is a monorepo managed with {{BUILD_SYSTEM}}.
 
 ## Getting Started
 
+### Native OpenCode V2
+
+Toolkit v4 requires **OpenCode V2 (major >=2)** for OpenCode use; oh-my-opencode-slim >=3.0.0 requires OpenCode >=2.0.7. Bootstrap, patch, and upgrade run `opencode --version` before changes (optional leading `v` accepted). 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 confirmed/installed. Confirm harness use from runtime evidence or ask, not scaffold directories; other-harness-only setup is unaffected.
+
+The template's local `plugins` array registers the author's native V2 package `@dietrichgebert/ponytail@4.12.0`, alongside `opencode-mem` and `@tarquinen/opencode-dcp@latest`; `opentmux` remains commented as V1-only. The obsolete local Ponytail plugin is no longer bundled; no local API port or bridge is used. For existing projects, back up and obtain approval before removing only known toolkit `.opencode/plugins/ponytail.js`, `.mjs`, or `.ts` copies; preserve unrelated local plugins and merge/deduplicate upstream registration locally without editing global plugins. Native local plugins are discovered automatically; do not register them twice.
+
+With approval, merge `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally without replacing other registrations. Slim's separate strict schema retains `prompt`, `permission`, and `variant`; do not host-migrate it. The external starter is a separate package, not automatically upgraded. Plugin/runtime integration has not been tested.
+
+Use native `agents`/`system`, `request.body.temperature`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`), `commands`/`subagent`, `plugins` with `{ "package": "…", "options": {} }`, skill-directory arrays, and `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`. Follow the [V2 migration guide](https://opencode.ai/v2/docs/migrate-v1) and [plugin guide](https://opencode.ai/v2/docs/build/plugins); the published schema may describe V1 and is not V2 validation authority.
+
+Ambient root/nested `AGENTS.md` works; config `instructions` entries are not loaded. `@refs` are ordinary text: read linked snippets explicitly. `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 activating other harnesses. Back up V1, merge rather than clobber models/providers/plugins, and activate on the next run/restart. Native-converted files are incompatible with V1. Verify with installed V2; `doctor` is not runtime validation. Toolkit 4.0.0 publishing has not been executed.
+
 ### Native Codex
 
 `--env codex` includes `.codex/`, `.agents/`, and shared context, plus `.github/instructions/` and `.claude/rules-snippets/` solely to supply AGENTS-linked standards and their wrapper source content. No other harness command, agent, or config directories are installed; these references do not establish Copilot/Claude use or load automatically as Codex rules. Other harness scopes are unchanged.

package/src/repo/.claude/agents/documenter.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "Documenter"
 description: "Analyze codebases and create comprehensive documentation. Use for AGENTS.md, README files, API docs, architecture documentation, and onboarding guides."
-tools: ["Read", "Grep", "Write", "Edit", "Bash(*)"]
+tools: ["Read", "Grep", "Write"]
 user-invocable: true
 ---
 

package/src/repo/.claude/agents/planner.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "Planner"
 description: "Break down feature requests into implementation tasks. Read specifications, analyze codebase patterns, and produce structured plans with dependencies."
-tools: ["Read", "Grep", "Write", "Bash(*)"]
+tools: ["Read", "Grep", "Write"]
 user-invocable: true
 ---
 

package/src/repo/.claude/agents/researcher.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "Researcher"
 description: "Research codebase patterns, dependencies, and technical context. Analyze code structure, find relevant examples, and report findings without making changes."
-tools: ["Read", "Grep"]
+tools: ["Read", "Grep", "Write"]
 user-invocable: true
 ---
 

package/src/repo/.claude/agents/reviewer.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "Reviewer"
 description: "Review code changes for correctness, code quality, security, and adherence to project patterns. Provide actionable feedback with specific file and line references. Use immediately after writing or modifying code, or as a quality gate in orchestrated workflows."
-tools: ["Read", "Grep", "Bash(*)"]
+tools: ["Read", "Grep", "Write", "Bash(*)"]
 user-invocable: true
 ---
 

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