nitm-ai-dev-toolkit 3.0.23 → 5.0.0

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
 

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.
@@ -41,19 +49,28 @@ You are helping to bootstrap AI instructions for this monorepo by analyzing the
 
 2. **Infer Root-Level Variables**:
 
-   | Variable                  | How to Infer                                       |
-   | ------------------------- | -------------------------------------------------- |
-   | `{{PROJECT_NAME}}`        | Root config name or directory name                 |
-   | `{{PROJECT_DESCRIPTION}}` | Root config description                            |
-   | `{{LANGUAGE}}`            | Detected ecosystem                                 |
-   | `{{PACKAGE_MANAGER}}`     | Lock file or config (pnpm, composer, dotnet, etc.) |
-   | `{{BUILD_SYSTEM}}`        | Build tool (Turborepo, Nx, MSBuild, Maven, etc.)   |
-   | `{{DEFAULT_BRANCH}}`      | Git config or assume "main"                        |
-   | `{{TEST_FRAMEWORK}}`      | Common test framework across packages              |
-   | `{{ISSUE_TRACKER}}`       | Detected project management tool                   |
-   | `{{PM_URL}}`              | Project management URL (if applicable)             |
-   | `{{PROJECT_KEY}}`         | Project/workspace ID (if applicable)               |
-   | `{{PM_ISSUE_KEY}}`        | Issue key format (e.g., PROJ-###, #42)             |
+   | Variable                    | How to Infer                                                                                                                                    |
+   | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+   | `{{PROJECT_NAME}}`          | Root config name or directory name                                                                                                              |
+   | `{{PROJECT_DESCRIPTION}}`   | Root config description                                                                                                                         |
+   | `{{LANGUAGE}}`              | Detected ecosystem                                                                                                                              |
+   | `{{PACKAGE_MANAGER}}`       | Lock file or config (pnpm, composer, dotnet, etc.)                                                                                              |
+   | `{{SETUP_COMMAND}}`         | Root install from the lock file (`pnpm install --frozen-lockfile`, `npm ci`, `yarn install --immutable`); a root `setup` script wins if present |
+   | `{{BUILD_SYSTEM}}`          | Build tool (Turborepo, Nx, MSBuild, Maven, etc.)                                                                                                |
+   | `{{DEFAULT_BRANCH}}`        | `git symbolic-ref --short refs/remotes/origin/HEAD`, minus `origin/`; else `main`                                                               |
+   | `{{TEST_FRAMEWORK}}`        | Common test framework across packages                                                                                                           |
+   | `{{DEV_COMMAND}}`           | Root dev script or task (`turbo run dev`, `nx run-many -t serve`)                                                                               |
+   | `{{DEV_PORT_FLAG}}`         | Port flag or env var the root dev command passes to apps (`--port <port>`, `PORT=<port>`); check each app config. Ask if none                   |
+   | `{{TEST_COMMAND}}`          | Root test script or task (`turbo run test`, `nx run-many -t test`)                                                                              |
+   | `{{LINT_COMMAND}}`          | Root lint script or task (`turbo run lint`, `nx run-many -t lint`)                                                                              |
+   | `{{BUILD_COMMAND}}`         | Root build script or task (`turbo run build`, `nx run-many -t build`)                                                                           |
+   | `{{ISSUE_TRACKER}}`         | Detected project management tool                                                                                                                |
+   | `{{PM_URL}}`                | Project management URL (if applicable)                                                                                                          |
+   | `{{PROJECT_KEY}}`           | Project/workspace ID (if applicable)                                                                                                            |
+   | `{{PM_ISSUE_KEY}}`          | Issue key format (e.g., PROJ-###, #42)                                                                                                          |
+   | `{{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)         |
 
 3. **Analyze Apps**:
 
@@ -133,6 +150,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 +167,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 +279,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 +296,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/.claude/prompt-snippets/factory.md

@@ -0,0 +1,20 @@
+---
+description: "Run an opt-in factory job: intake, spec and plan gates, build in a worktree or in place, reviews, approval, local merge"
+---
+
+You are the factory orchestrator for this session. Arguments: $ARGUMENTS
+
+Follow the [factory orchestrator skill](../../.agents/skills/factory/SKILL.md) exactly. It defines every invocation (`<request>` for intake, `start`, `approve`, `rework`, `abandon`, `status [--all]`, `watch [--all]`, `archive [--all] [--dry-run]`, `prune [--all] [--abandoned] [--dry-run]`), intake questions, feature folder resolution, the job layout, the spec and plan gates, tickets, the stages, the verdict rules, the paths block, and the merge procedure.
+
+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.
+- 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.
+- `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/`.
+- If `$ARGUMENTS` is empty, show the invocation list from the skill and ask which one the user wants.

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

@@ -56,7 +56,7 @@ Implement a feature by completing tasks sequentially with proper tracking.
 
    c. **Implement (TDD required)**:
 
-   - Follow acceptance criteria exactly
+   - Follow the acceptance criteria in `spec.md` for this task's deliverable
    - Use patterns from `AGENTS.md`
    - **Write a failing test first** — one behavior per test, clear name, real code
    - **Verify it fails** — watch it fail for the right reason (feature missing, not error)
@@ -79,7 +79,7 @@ Implement a feature by completing tasks sequentially with proper tracking.
    git commit -m "feat({{SCOPE}}): {{DESCRIPTION}}"
    ```
 
-   f. **Mark Task Complete**
+   f. **Mark Task Complete**: tick `- [x]` for the task in `tasks.md`
 
 5. **Post-Implementation Review**:
    - Dispatch **Reviewer** agent on all changes before proceeding