nitm-ai-dev-toolkit 5.0.0 → 5.0.1

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

@@ -1,12 +1,12 @@
-# Bootstrap Upgrade to v4.0
+# Bootstrap Upgrade to toolkit <version>
 
-Upgrade 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 and clean up duplicate skills. Only modify confirmed harness targets; preserve unrelated harness/Codex behavior.
+Upgrade to toolkit <version> (the installed package version), including native OpenCode V2 for confirmed OpenCode users (toolkit 4.0.0 and later). For pre-3.0 installations, also migrate inline content to snippet-based architecture and clean up duplicate skills. 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.
+- 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.0.0 and later require `major >= 2`.
+- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as 4.0.0 or later. 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.
 
@@ -21,7 +21,7 @@ Read `.toolkit-version` and select the route before dispatching agents or changi
 
 ## 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.
+Back up V1; native-converted files are incompatible with V1. Preserve models/providers/user-global plugins. The OpenCode Ponytail plugin (`@dietrichgebert/ponytail`) is installed globally by the operator and is never registered by templates or project config; obsolete toolkit-local Ponytail copies are removed 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.
 
 ## Usage
 
@@ -56,7 +56,7 @@ Run all checks before making any changes:
 3. **Confirm migration scope**:
 
    ```markdown
-   ## 🔄 Bootstrap Upgrade: toolkit v4.0.0
+   ## 🔄 Bootstrap Upgrade: toolkit <version>
 
     **Project type**: repo | monorepo
     **Current version**: <version or "none (legacy)">
@@ -68,7 +68,7 @@ Run all checks before making any changes:
     2.  Confirmed OpenCode only: merge native V2 host files and approved missing wrappers (Step 7)
     3.  Verified legacy only: approved hook installation and verified identical duplicate skill cleanup (Steps 8–10); preserve custom skills
     4.  Merge only applicable missing documentation and validate the selected route; v3 keeps existing snippet bodies/frontmatter unchanged
-    5.  Create `.toolkit-version` with `4.0.0` after the approved migration
+    5.  Keep the `.toolkit-version` the CLI writes (installed package version, 4.0.0 or later) after the approved migration
     6.  Commit all changes
 
    Proceed? (Y/n)
@@ -176,18 +176,17 @@ For the v3 route, merge only relevant native OpenCode host fields; preserve exis
      "$schema": "https://opencode.ai/config.json",
       "instructions": ["AGENTS.md", ".opencode/rules/*.md"],
       "skills": [".agents/skills"],
-      "plugins": ["@dietrichgebert/ponytail@4.12.0"],
       "lsp": true
    }
    ```
 
    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`.
 
-   `instructions` entries are accepted but not loaded; ambient `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 project 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.
+   Ambient `AGENTS.md` works. `instructions` entries load only when the runtime injects them (OpenChamber does; other hosts may not), so do not rely on them: write explicit "Read and follow" wrappers regardless. `@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 project 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. **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.
+   - The OpenCode Ponytail plugin (`@dietrichgebert/ponytail`) is installed globally by the operator. Never add or pin it in the local `plugins` array. Check whether it is installed globally; if not, tell the operator to install it globally. Do not edit global config or overwrite global plugins. Keep `opentmux` commented as V1-only; do not copy local Ponytail source, port APIs, or introduce bridges. Runtime integration remains untested.
 
 3. **Create wrappers with explicit snippet-read instructions** — one file per snippet:
 
@@ -252,12 +251,13 @@ If `CLAUDE.md` is an applicable confirmed harness target and a thin redirect to
 
 See existing `CLAUDE.md` in the toolkit template (`src/repo/CLAUDE.md`) for the exact format.
 
-### 12. Create `.toolkit-version` File
+### 12. Check `.toolkit-version` File
 
 Only after the approved migration and OpenCode preflight pass (or OpenCode is confirmed out of scope):
 
 ```bash
-echo "4.0.0" > .toolkit-version
+# Keep the value the CLI wrote (the installed package version). If it is missing, record it with the CLI:
+npx nitm-ai-dev-toolkit patch
 ```
 
 ### 13. Validation
@@ -277,13 +277,13 @@ If `--verbose`: log each check result with file paths.
 
 ### 14. Generate Upgrade Report
 
-Output the report to stdout (and optionally to `docs/upgrade-report-v4.md`). 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:
+Output the report to stdout (and optionally to `docs/upgrade-report-<version>.md`). 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
 ## 🚀 Bootstrap Upgrade Report
 
 **From**: detected installed version (include inline extraction only for pre-3.0)
-**To**: 4.0.0 (native V2 for confirmed OpenCode use; snippet conversion only for verified legacy)
+**To**: <version> (toolkit 4.0.0 or later; native V2 for confirmed OpenCode use; snippet conversion only for verified legacy)
 **Selected route**: verified legacy | v3 native OpenCode
 **Date**: {{DATE}}
 **Dry run**: yes | no
@@ -317,7 +317,7 @@ Output the report to stdout (and optionally to `docs/upgrade-report-v4.md`). Inc
 
 ### Files Created
 
-- `.toolkit-version` — 4.0.0
+- `.toolkit-version` — installed package version (written by the CLI)
 
 ### Validation
 
@@ -337,7 +337,7 @@ If not `--dry-run`, stage and commit all changes:
 
 ```bash
 git add -A
-git commit -m "chore: upgrade AI instructions to toolkit v4.0.0"
+git commit -m "chore: upgrade AI instructions to toolkit <version>"
 ```
 
 If `--dry-run`: skip commit, note in report: "Dry run — no changes committed."

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

@@ -5,8 +5,8 @@ Analyze the project structure and customize AI instruction templates for this co
 ## 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.
+- 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.0.0 and later require `major >= 2`.
+- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as 4.0.0 or later. 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.
 
@@ -126,9 +126,9 @@ Map discovered information to template variables:
 | `{{PROJECT_KEY}}`           | Project ID or workspace ID (if applicable)                                                                                                                                                                 |
 | `{{PM_ISSUE_KEY}}`          | Issue key format (e.g., PROJ-###)                                                                                                                                                                          |
 | `{{DEFAULT_BRANCH}}`        | `git symbolic-ref --short refs/remotes/origin/HEAD`, minus `origin/`; else `main`                                                                                                                          |
-| `{{FACTORY_PORT_BASE}}`     | Default `5100`                                                                                                                                                                                             |
-| `{{APPROVAL_MODE}}`         | Default `human`                                                                                                                                                                                            |
-| `{{FACTORY_REVIEW_LENSES}}` | Default `code, security`; add `ux, ui` only if the project has a UI and a browser tool is configured (for example a browser MCP server)                                                                    |
+| `{{FACTORY_PORT_BASE}}`     | Only if Factory is installed. Default `5100`                                                                                                                                                                                             |
+| `{{APPROVAL_MODE}}`         | Only if Factory is installed. Default `human`                                                                                                                                                                                            |
+| `{{FACTORY_REVIEW_LENSES}}` | Only if Factory is installed. Default `code, security`; add `ux, ui` only if the project has a UI and a browser tool is configured (for example a browser MCP server)                                                                    |
 | `{{NEW_RELEVANT_VARIABLE}}` | ...other inferred values...                                                                                                                                                                                |
 
 ### Step 2.5: Project Management Detection
@@ -252,23 +252,23 @@ Follow the official [V2 migration](https://opencode.ai/v2/docs/migrate-v1), [con
 
 - After the version preflight passes, use `agents` with JSON `system` or Markdown bodies; `request.body.temperature`; ordered `permissions` rules (`action`, `resource`, `effect`; `shell`/`subagent`; last match wins); `commands` with `subagent`; `plugins` with `{ "package": "…", "options": {} }`; `skills` as directory-path arrays; `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`.
 - Back up V1; native-converted files are incompatible with V1. Merge, don't clobber models/providers/user-global plugins. With approval only, merge pinned `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally. Slim's separate strict schema retains its own `prompt`, `permission`, and `variant`; do not host-migrate it or upgrade the separate external starter silently.
-- 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 accepted but not loaded; ambient `AGENTS.md` works. `@refs` are ordinary text: explicitly read referenced snippet docs. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`, but use project lint/typecheck/compiler commands (no current V2 LSP tools/diagnostics).
-- `--env opencode` supplies minimal shared references without activating other harnesses. Activate on the next run/restart and report only checks actually run using installed V2; scaffold/placeholder checks are not runtime validation. Publishing 4.0.0 has not been executed.
+- The OpenCode Ponytail plugin (`@dietrichgebert/ponytail`, the author's native V2 package) is installed globally by the operator. Templates do not register or pin it, and no local Ponytail source is bundled or ported. Keep `opentmux` commented as V1-only. Do not introduce API ports or bridges or claim tested runtime integration.
+- Ambient `AGENTS.md` works. Config `instructions` entries load only when the runtime injects them (OpenChamber does; other hosts may not), so do not rely on them: write explicit "Read and follow" wrappers regardless. `@refs` are ordinary text: explicitly read referenced snippet docs. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`, but use project lint/typecheck/compiler commands (no current V2 LSP tools/diagnostics).
+- `--env opencode` supplies minimal shared references without activating other harnesses. Activate on the next run/restart and report only checks actually run using installed V2; scaffold/placeholder checks are not runtime validation.
 
 **Ponytail pre-activation cleanup (confirmed OpenCode use only):**
 
 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.
+3. Never add `@dietrichgebert/ponytail` to project `.opencode/opencode.jsonc`. Check whether it is installed globally; if not, tell the operator to install it globally and leave global and project 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 only after the OpenCode preflight and Ponytail cleanup gate pass (or OpenCode is confirmed out of scope):
+Confirm `.toolkit-version` in the project root. The CLI writes it on install and patch with the installed package version. For toolkit 4.0.0 or later, keep the value the CLI wrote; do not write it by hand or overwrite it with a hard-coded version. If it is missing, run `npx nitm-ai-dev-toolkit patch` only after the OpenCode preflight and Ponytail cleanup gate pass (or OpenCode is confirmed out of scope). Expected form:
 
 ```
-4.0.0
+<installed package version, for example 5.0.0>
 ```
 
 This file enables `bootstrap-patch` to detect version changes and apply migrations automatically.

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

@@ -1,5 +1,5 @@
 ---
-description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, local merge"
+description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, merge (local, or a merge request on the forge)"
 ---
 
 You are the factory orchestrator for this session. Arguments: $ARGUMENTS
@@ -9,12 +9,12 @@ Follow the [factory orchestrator skill](../../.agents/skills/factory/SKILL.md) e
 Ground rules:
 
 - Run the orchestrator in this session. Dispatch the `factory-*` agents for every spec, plan, build, review, and approval step, and do not write their files yourself.
-- Only write `job.json`, `intake.md`, `spec-<k>.md`, `plan-<k>.md`, `rework-<k>.md`, the escalation `decision.md`, `merge-conflict.md`, the ticket keys in `tasks.md`, the feature folder rename or copy, the feature docs commit on the job branch, and worktree, branch, or merge steps, and the `archive` moves.
+- Only write `job.json`, `intake.md`, `spec-<k>.md`, `plan-<k>.md`, `rework-<k>.md`, the escalation `decision.md`, `merge-conflict.md`, `bootstrap.md`, the ticket keys in `tasks.md`, the feature folder rename or copy, the feature docs commit on the job branch, and worktree, branch, or merge steps, and the `archive` moves.
 - Intake asks in chat before any folder, job, or spec exists. Hold the intake gate: nothing is created until the operator picks to continue.
 - Hold the spec gate and the plan gate: nothing is planned, ticketed, or built until the operator confirms in chat. The spec cannot be confirmed while a `[PRODUCT DECISION]` item is open.
 - `--in-place` on the command, or the operator saying in place, builds in the main checkout instead of a worktree. Only a new job takes it.
 - `abandon <job-id>` closes a job without merging it. Ask first when an agent may still be running.
-- Never push. Merges stay local.
+- Local merges never push. With `MERGE_MODE` set to `push-mr`, the branch is pushed and its merge request opened only on `/factory approve` or an `auto` APPROVE, and never force-pushed.
 - `archive` moves closed jobs only, to `factory/archive/`. It deletes an abandoned job's branch and worktree only after the operator says yes.
-- `prune` permanently deletes closed jobs from `factory/jobs/` and `factory/archive/`, after one confirmation in chat: merged jobs by default, and abandoned jobs too with `--abandoned`. It never touches an open job or `docs/features/`.
+- `prune` permanently deletes closed jobs from `factory/jobs/` and `factory/archive/`, after one confirmation in chat: merged jobs by default, and abandoned jobs too with `--abandoned`. It never touches an open job or the feature folders.
 - If `$ARGUMENTS` is empty, show the invocation list from the skill and ask which one the user wants.

package/src/repo/.claude/prompt-snippets/implement-feature.md

@@ -85,7 +85,9 @@ Implement a feature by completing tasks sequentially with proper tracking.
    git commit -m "feat({{SCOPE}}): {{DESCRIPTION}}"
    ```
 
-   f. **Mark Task Complete**: tick `- [x]` for the task in `tasks.md`
+   f. **Mark Task Complete**:
+   - Slim `tasks.md`: tick `- [x]` on the task's line
+   - Legacy `tasks.md`: tick `- [x]` only on checkboxes under the current task's heading (until the next heading). Never tick checkboxes under other headings. If that heading has no checkboxes, report "no checkboxes under <heading>; nothing ticked" and continue
 
 5. **Post-Implementation Review**:
    - Dispatch **Reviewer** agent on all changes before proceeding

package/src/repo/.claude/rules-snippets/subagent-workflow.md

@@ -103,8 +103,8 @@ Before executing any task list, the orchestrator MUST run this analysis:
    - **Mixed** → Dispatch independent group in parallel, then continue sequential chain
 
 ```
-Example: 5 tasks → T001 (setup) → T002 [P] (backend API) + T003 [P] (frontend UI) + T004 [P] (docs) → T005 (integration tests)
-         Dispatch: T001 sequential → T002+T003+T004 parallel → T005 sequential
+Example: 5 tasks → T1 (setup) → T2 [P] (backend API) + T3 [P] (frontend UI) + T4 [P] (docs) → T5 (integration tests)
+         Dispatch: T1 sequential → T2+T3+T4 parallel → T5 sequential
 ```
 
 ## Quality Gates

package/src/repo/.cursor/commands/factory.md

@@ -1,5 +1,5 @@
 ---
-description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, local merge"
+description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, merge (local, or a merge request on the forge)"
 argument-hint: "[--in-place] <feature request> | start [--in-place] <request | KEY | slug | job-id> | approve <job-id> | rework <job-id> <note> | abandon <job-id> | status [--all] | watch [--all] | archive [--all] [--dry-run] | prune [--all] [--abandoned] [--dry-run]"
 ---
 

package/src/repo/.github/prompts/factory.prompt.md

@@ -1,5 +1,5 @@
 ---
-description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, local merge"
+description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, merge (local, or a merge request on the forge)"
 tools: ["agent", "edit", "search", "read", "runInTerminal", "terminalLastCommand"]
 argument-hint: "[--in-place] <feature request> | start [--in-place] <request | KEY | slug | job-id> | approve <job-id> | rework <job-id> <note> | abandon <job-id> | status [--all] | watch [--all] | archive [--all] [--dry-run] | prune [--all] [--abandoned] [--dry-run]"
 ---

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

@@ -17,4 +17,4 @@ permissions:
 
 Build administrator portals with RBAC, system dashboards, reporting, analytics, and operational tooling.
 
-@.claude/agents-snippets/admin-portal.md
+Read and follow `.claude/agents-snippets/admin-portal.md` before performing this role.

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

@@ -17,4 +17,4 @@ permissions:
 
 Design and implement API architecture, documentation, and developer experience.
 
-@.claude/agents-snippets/api-specialist.md
+Read and follow `.claude/agents-snippets/api-specialist.md` before performing this role.

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

@@ -17,4 +17,4 @@ permissions:
 
 Design APIs, databases, and server-side architecture.
 
-@.claude/agents-snippets/backend-architect.md
+Read and follow `.claude/agents-snippets/backend-architect.md` before performing this role.

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

@@ -17,4 +17,4 @@ permissions:
 
 Analyze codebases and create comprehensive documentation.
 
-@.claude/agents-snippets/documenter.md
+Read and follow `.claude/agents-snippets/documenter.md` before performing this role.

package/src/repo/.opencode/agents/factory-approver.md

@@ -17,4 +17,4 @@ permissions:
 
 Decide whether a factory job is approved for merge or escalated to a human.
 
-@.claude/agents-snippets/factory-approver.md
+Read and follow `.claude/agents-snippets/factory-approver.md` before performing this role.

package/src/repo/.opencode/agents/factory-builder.md

@@ -17,4 +17,4 @@ permissions:
 
 Build a factory job's feature inside its git worktree, following TDD, and log results in build.md.
 
-@.claude/agents-snippets/factory-builder.md
+Read and follow `.claude/agents-snippets/factory-builder.md` before performing this role.

package/src/repo/.opencode/agents/factory-reviewer-code.md

@@ -17,4 +17,4 @@ permissions:
 
 Review a factory job's branch for correctness, simplicity, reuse, conventions, and docs, and run the project's checks.
 
-@.claude/agents-snippets/factory-reviewer-code.md
+Read and follow `.claude/agents-snippets/factory-reviewer-code.md` before performing this role.

package/src/repo/.opencode/agents/factory-reviewer-security.md

@@ -17,4 +17,4 @@ permissions:
 
 Audit a factory job's branch diff for security problems in a fresh context.
 
-@.claude/agents-snippets/factory-reviewer-security.md
+Read and follow `.claude/agents-snippets/factory-reviewer-security.md` before performing this role.

package/src/repo/.opencode/agents/factory-reviewer-ui.md

@@ -17,4 +17,4 @@ permissions:
 
 Review a factory job's feature at its build location for design-system consistency, spacing, typography, contrast, and responsive layout, without signing in or writing to real services.
 
-@.claude/agents-snippets/factory-reviewer-ui.md
+Read and follow `.claude/agents-snippets/factory-reviewer-ui.md` before performing this role.

package/src/repo/.opencode/agents/factory-reviewer-ux.md

@@ -17,4 +17,4 @@ permissions:
 
 Review a factory job's feature at its build location for flows, states, copy, accessibility, and mobile, without signing in or writing to real services.
 
-@.claude/agents-snippets/factory-reviewer-ux.md
+Read and follow `.claude/agents-snippets/factory-reviewer-ux.md` before performing this role.

package/src/repo/.opencode/agents/factory-spec-writer.md

@@ -17,4 +17,4 @@ permissions:
 
 Write a testable spec.md for a factory job from a feature request, after inspecting the real code.
 
-@.claude/agents-snippets/factory-spec-writer.md
+Read and follow `.claude/agents-snippets/factory-spec-writer.md` before performing this role.

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

@@ -20,4 +20,4 @@ permissions:
 
 Coordinate end-to-end feature development using subagents for planning, implementation, and review.
 
-@.claude/agents-snippets/feature-builder.md
+Read and follow `.claude/agents-snippets/feature-builder.md` before performing this role.

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

@@ -17,4 +17,4 @@ permissions:
 
 Build user interfaces, implement components, handle state management, and optimize frontend performance.
 
-@.claude/agents-snippets/frontend-developer.md
+Read and follow `.claude/agents-snippets/frontend-developer.md` before performing this role.

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

@@ -17,4 +17,4 @@ permissions:
 
 Write minimal code to make failing tests pass. Part of the TDD red-green-refactor cycle.
 
-@.claude/agents-snippets/green.md
+Read and follow `.claude/agents-snippets/green.md` before performing this role.

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

@@ -17,4 +17,4 @@ permissions:
 
 Implement code changes for a specific task. Follow TDD, write tests alongside code, and self-review before reporting completion.
 
-@.claude/agents-snippets/implementer.md
+Read and follow `.claude/agents-snippets/implementer.md` before performing this role.

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

@@ -17,4 +17,4 @@ permissions:
 
 Break down feature requests into implementation tasks. Read specifications, analyze codebase patterns, and produce structured plans with dependencies.
 
-@.claude/agents-snippets/planner.md
+Read and follow `.claude/agents-snippets/planner.md` before performing this role.

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

@@ -17,4 +17,4 @@ permissions:
 
 Write failing tests that define expected behavior. Part of the TDD red-green-refactor cycle.
 
-@.claude/agents-snippets/red.md
+Read and follow `.claude/agents-snippets/red.md` before performing this role.

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

@@ -17,4 +17,4 @@ permissions:
 
 Improve code quality and structure while keeping all tests passing. Part of the TDD red-green-refactor cycle.
 
-@.claude/agents-snippets/refactor.md
+Read and follow `.claude/agents-snippets/refactor.md` before performing this role.

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

@@ -17,4 +17,4 @@ permissions:
 
 Research codebase patterns, dependencies, and technical context. Analyze code structure, find relevant examples, and report findings without making changes.
 
-@.claude/agents-snippets/researcher.md
+Read and follow `.claude/agents-snippets/researcher.md` before performing this role.

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

@@ -17,4 +17,4 @@ permissions:
 
 Review code changes for correctness, code quality, security, and adherence to project patterns.
 
-@.claude/agents-snippets/reviewer.md
+Read and follow `.claude/agents-snippets/reviewer.md` before performing this role.

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

@@ -20,4 +20,4 @@ permissions:
 
 Implement a feature using test-driven development with red-green-refactor cycle.
 
-@.claude/agents-snippets/tdd.md
+Read and follow `.claude/agents-snippets/tdd.md` before performing this role.

package/src/repo/.opencode/commands/assign-tasks.md

@@ -13,4 +13,4 @@ description: "Create {{ISSUE_TRACKER}} tickets from requirements or task files"
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/assign-tasks.md
+Read and follow `.claude/prompt-snippets/assign-tasks.md` before executing this command.

package/src/repo/.opencode/commands/bootstrap-patch.md

@@ -15,4 +15,4 @@ description: "Patch AI instructions by fetching updates from the toolkit repo an
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/bootstrap-patch.md
+Read and follow `.claude/prompt-snippets/bootstrap-patch.md` before executing this command.

package/src/repo/.opencode/commands/bootstrap-upgrade.md

@@ -15,4 +15,4 @@ description: "Upgrade AI instructions from pre-3.0 inline pattern to 3.0+ snippe
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/bootstrap-upgrade.md
+Read and follow `.claude/prompt-snippets/bootstrap-upgrade.md` before executing this command.

package/src/repo/.opencode/commands/bootstrap.md

@@ -15,4 +15,4 @@ description: "Bootstrap AI instructions by inferring project details and customi
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/bootstrap.md
+Read and follow `.claude/prompt-snippets/bootstrap.md` before executing this command.

package/src/repo/.opencode/commands/commit-push.md

@@ -11,6 +11,6 @@ description: "Commit and push changes with conventional commit messages"
 
 Commit and push changes using conventional commit format.
 
-@.claude/prompt-snippets/commit-push.md
+Read and follow `.claude/prompt-snippets/commit-push.md` before executing this command.
 
 $ARGUMENTS

package/src/repo/.opencode/commands/constitution.md

@@ -15,4 +15,4 @@ description: "Create or update the project constitution defining core principles
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/constitution.md
+Read and follow `.claude/prompt-snippets/constitution.md` before executing this command.

package/src/repo/.opencode/commands/create-skill.md

@@ -13,4 +13,4 @@ description: "Create a new agent skill following VS Code and agentskills.io spec
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/create-skill.md
+Read and follow `.claude/prompt-snippets/create-skill.md` before executing this command.

package/src/repo/.opencode/commands/factory.md

@@ -26,4 +26,4 @@ Subcommands: `[--in-place] <feature request>` · `start [--in-place] <request |
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/factory.md
+Read and follow `.claude/prompt-snippets/factory.md` before executing this command.

package/src/repo/.opencode/commands/implement-feature.md

@@ -15,4 +15,4 @@ description: "Implement a feature by completing tasks sequentially"
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/implement-feature.md
+Read and follow `.claude/prompt-snippets/implement-feature.md` before executing this command.

package/src/repo/.opencode/commands/implement-fixes.md

@@ -17,4 +17,4 @@ argument-hint: "bug description or fix requirements"
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/implement-fixes.md
+Read and follow `.claude/prompt-snippets/implement-fixes.md` before executing this command.

package/src/repo/.opencode/commands/implement.md

@@ -15,4 +15,4 @@ description: "Execute implementation tasks from a task list or specification"
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/implement.md
+Read and follow `.claude/prompt-snippets/implement.md` before executing this command.

package/src/repo/.opencode/commands/plan.md

@@ -15,4 +15,4 @@ description: "Create an implementation plan from a feature specification or requ
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/plan.md
+Read and follow `.claude/prompt-snippets/plan.md` before executing this command.

package/src/repo/.opencode/commands/playwright-test.md

@@ -13,4 +13,4 @@ description: "Run or create E2E tests using Playwright"
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/playwright-test.md
+Read and follow `.claude/prompt-snippets/playwright-test.md` before executing this command.

package/src/repo/.opencode/commands/ponytail-audit.md

@@ -7,4 +7,4 @@ description: "Whole-repo audit for over-engineering. Scans entire codebase for w
 > **Recommended agent:** `oracle`
 > Whole-repo over-engineering analysis
 
-@.claude/prompt-snippets/ponytail-audit.md
+Read and follow `.claude/prompt-snippets/ponytail-audit.md` before executing this command.

package/src/repo/.opencode/commands/ponytail-debt.md

@@ -7,4 +7,4 @@
 > **Recommended agent:** `fixer`
 > Debt ledger harvesting
 
-@.claude/prompt-snippets/ponytail-debt.md
+Read and follow `.claude/prompt-snippets/ponytail-debt.md` before executing this command.

package/src/repo/.opencode/commands/ponytail-gain.md

@@ -7,4 +7,4 @@
 > **Recommended agent:** `fixer`
 > Impact scoreboard display
 
-@.claude/prompt-snippets/ponytail-gain.md
+Read and follow `.claude/prompt-snippets/ponytail-gain.md` before executing this command.

package/src/repo/.opencode/commands/ponytail-help.md

@@ -7,4 +7,4 @@
 > **Recommended agent:** `fixer`
 > Quick-reference display
 
-@.claude/prompt-snippets/ponytail-help.md
+Read and follow `.claude/prompt-snippets/ponytail-help.md` before executing this command.

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

@@ -7,4 +7,4 @@
 > **Recommended agent:** `oracle`
 > Diff-level over-engineering review
 
-@.claude/prompt-snippets/ponytail-review.md
+Read and follow `.claude/prompt-snippets/ponytail-review.md` before executing this command.

package/src/repo/.opencode/commands/ponytail.md

@@ -7,4 +7,4 @@ description: "Forces the laziest solution that actually works — YAGNI, stdlib,
 > **Recommended agent:** `fixer`
 > Apply YAGNI/stdlib discipline
 
-@.claude/prompt-snippets/ponytail.md
+Read and follow `.claude/prompt-snippets/ponytail.md` before executing this command.

package/src/repo/.opencode/commands/release-notes.md

@@ -13,4 +13,4 @@ description: "Generate release notes from git commits (web, git tag, or document
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/release-notes.md
+Read and follow `.claude/prompt-snippets/release-notes.md` before executing this command.

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

@@ -13,6 +13,6 @@ description: "Review pull request for code quality and best practices"
 
 Conduct comprehensive code review for pull requests.
 
-@.claude/prompt-snippets/review-pr.md
+Read and follow `.claude/prompt-snippets/review-pr.md` before executing this command.
 
 $ARGUMENTS

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

@@ -13,6 +13,6 @@ description: "Review code for quality, consistency, and adherence to project pat
 
 Review code for quality, security, and adherence to project patterns.
 
-@.claude/prompt-snippets/review.md
+Read and follow `.claude/prompt-snippets/review.md` before executing this command.
 
 $ARGUMENTS

package/src/repo/.opencode/commands/specify.md

@@ -15,4 +15,4 @@ description: "Create a feature specification from a natural language description
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/specify.md
+Read and follow `.claude/prompt-snippets/specify.md` before executing this command.

package/src/repo/.opencode/commands/tasks.md

@@ -13,4 +13,4 @@ description: "Generate an actionable task list from a specification or plan"
 
 $ARGUMENTS
 
-@.claude/prompt-snippets/tasks.md
+Read and follow `.claude/prompt-snippets/tasks.md` before executing this command.

package/src/repo/.opencode/opencode.jsonc

@@ -11,8 +11,7 @@
 	],
 	"plugins": [
 		"opencode-mem",
-		"@tarquinen/opencode-dcp@latest",
-		"@dietrichgebert/ponytail@4.12.0"
+		"@tarquinen/opencode-dcp@latest"
 		// "opentmux": V1-only; enable only after it supports V2.
 	],
 	"lsp": true