nitm-ai-dev-toolkit 3.0.22 → 4.0.0

package/CHANGELOG.md

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

package/README.md

@@ -11,6 +11,7 @@ This repository serves as a **template source** for AI development instructions
 - **GitHub Copilot instructions** (`.github/copilot-instructions.md`)
 - **GitHub prompts** (`.github/prompts/`) for reusable prompt templates
 - **AGENTS.md** files for AI agent context
+- **Native Codex setup** using `AGENTS.md`, `.agents/skills/`, and an optional comment-only `.codex/config.toml`
 - **Skills recommendations** from [skills.sh](https://skills.sh/) for enhanced AI capabilities
 
 ## Repository Structure
@@ -19,6 +20,7 @@ This repository serves as a **template source** for AI development instructions
 /
 ├── src/
 │   ├── repo/           # Templates for single repositories
+│   │   ├── .codex/     # Optional native Codex config (comment-only)
 │   │   ├── .cursor/    # Cursor IDE configuration
 │   │   │   ├── agents/ # Custom agent templates (subagents)
 │   │   │   ├── rules/  # IDE behavior rules
@@ -39,6 +41,7 @@ This repository serves as a **template source** for AI development instructions
 │   │   └── README.md   # Project README template
 │   │
 │   └── monorepo/       # Templates for monorepos
+│       ├── .codex/     # Optional native Codex config (comment-only)
 │       ├── .cursor/    # Root-level Cursor config
 │       │   ├── agents/ # Custom agent templates (subagents)
 │       │   ├── rules/  # IDE behavior rules
@@ -62,7 +65,7 @@ This repository serves as a **template source** for AI development instructions
 ├── .cursor/            # This toolkit's own Cursor config
 ├── .github/            # This toolkit's own GitHub config
 ├── .opencode/          # This toolkit's own OpenCode config
-│   └── plugins/        # OpenCode plugins (ponytail mode manager, etc.)
+│   └── plugins/        # Other local OpenCode plugins (Ponytail uses upstream)
 ├── hooks/              # Claude Code / Copilot activation hooks (ponytail, etc.)
 └── AGENTS.md           # This toolkit's agent context
 ```
@@ -77,6 +80,8 @@ This repository serves as a **template source** for AI development instructions
 cp -r src/repo/.cursor /path/to/your/project/
 cp -r src/repo/.github /path/to/your/project/
 cp -r src/repo/.agents /path/to/your/project/
+cp -r src/repo/.claude /path/to/your/project/ # Shared snippet sources
+cp -r src/repo/.codex /path/to/your/project/  # Optional Codex config
 cp src/repo/AGENTS.md /path/to/your/project/
 ```
 
@@ -88,6 +93,7 @@ Open your project in Cursor IDE or VS Code with GitHub Copilot, then run:
 
 - **Cursor IDE**: Use the `/bootstrap` command
 - **GitHub Copilot**: Use the `bootstrap.prompt.md` prompt (`/bootstrap`)
+- **Codex**: Ask it to read and follow `.claude/prompt-snippets/bootstrap.md` as a task document (manual copies have no `.nitm/BOOTSTRAP.md`). Do not use `/bootstrap` as a native Codex command.
 
 The bootstrap process will:
 
@@ -108,6 +114,8 @@ After bootstrapping, review the generated files and add any project-specific pat
 cp -r src/monorepo/.cursor /path/to/your/project/
 cp -r src/monorepo/.github /path/to/your/project/
 cp -r src/monorepo/.agents /path/to/your/project/
+cp -r src/monorepo/.claude /path/to/your/project/ # Shared snippet sources
+cp -r src/monorepo/.codex /path/to/your/project/  # Optional Codex config
 cp src/monorepo/AGENTS.md /path/to/your/project/
 # Optionally copy app/package templates
 cp -r src/monorepo/apps/app-template /path/to/your/project/apps/
@@ -122,6 +130,7 @@ Open your project in Cursor IDE or VS Code with GitHub Copilot, then run:
 
 - **Cursor IDE**: Use the `/bootstrap` command
 - **GitHub Copilot**: Use the `bootstrap.prompt.md` prompt (`/bootstrap`)
+- **Codex**: Ask it to read and follow `.claude/prompt-snippets/bootstrap.md` as a task document (manual copies have no `.nitm/BOOTSTRAP.md`). Do not use `/bootstrap` as a native Codex command.
 
 The bootstrap process will:
 
@@ -142,7 +151,7 @@ After bootstrapping:
 
 ## CLI (npx)
 
-Scaffold AI agent config into any repo, then hand off to your AI agent to finish setup (replace `{{PLACEHOLDER}}`s, calibrate agent tools). The CLI scaffolds config for **all** supported harnesses (Claude Code, GitHub Copilot, Cursor, OpenCode); the `/bootstrap` command auto-detects your environment at runtime, so you normally don't need `--env`. `install` aborts if files already exist — use `--force` to overwrite, or `patch` to add only missing files.
+Scaffold AI agent config into any repo, then hand off to your AI agent to finish setup (replace `{{PLACEHOLDER}}`s, calibrate native instructions). The CLI scaffolds config for **all** supported harnesses (Claude Code, GitHub Copilot, Cursor, OpenCode, Codex) by default, so you normally don't need `--env`. Scaffolding does not prove a harness is installed or active: bootstrap uses actual runtime information or asks which harnesses you use. `install` aborts if files already exist — use `--force` to overwrite, or `patch` to add only missing files.
 
 ```bash
 # Scaffold AI config into the current repo (auto-detects repo vs monorepo)
@@ -155,6 +164,7 @@ npx nitm-ai-dev-toolkit install --repo
 
 # Optional: scaffold only one harness (e.g. you only use Cursor)
 npx nitm-ai-dev-toolkit install --env cursor
+npx nitm-ai-dev-toolkit install --env codex
 
 # Add only missing files (never overwrites existing ones) + re-emit the bootstrap handoff
 npx nitm-ai-dev-toolkit patch
@@ -169,7 +179,49 @@ npx nitm-ai-dev-toolkit upgrade
 npx nitm-ai-dev-toolkit omo-slim-starter install
 ```
 
-After `install`, run `/bootstrap` from whatever harness you're in — it auto-detects your environment. You can also read `.nitm/BOOTSTRAP.md` and ask your AI agent to run the bootstrap flow. Use `doctor` to verify the result.
+After `install`, ask your AI agent to read and follow `.nitm/BOOTSTRAP.md`. Harnesses that supply a toolkit `/bootstrap` wrapper can also use it; **Codex has no native toolkit `/bootstrap` command**. Use `doctor` to verify the result.
+
+### Native OpenCode V2 (toolkit 4.0.0)
+
+Toolkit v4 requires **OpenCode V2 (major >=2)** for OpenCode use; **oh-my-opencode-slim >=3.0.0** requires **OpenCode >=2.0.7**. All repo/monorepo bootstrap, patch, and upgrade flows run `opencode --version` before changes, accepting an optional leading `v`. V1 must stop before OpenCode customization/migration or marking toolkit 4.0.0: upgrade OpenCode or remain on toolkit 3.x. A missing CLI or unparseable version stops OpenCode steps and version marking until the user confirms/installs a supported version. Confirm harness use from runtime evidence or ask; scaffold directories are not proof. Other-harness-only setup is unaffected.
+
+Publishing 4.0.0 has not been executed. The external `nitm-opencode-starter` is a separate package, not automatically upgraded.
+
+With user approval, merge this reproducible registration without replacing user/global plugins:
+
+```jsonc
+{ "plugins": ["oh-my-opencode-slim@3.0.0"] }
+```
+
+The toolkit root deliberately omits `plugins` to inherit user/global registrations; its existing upstream Ponytail registration is unchanged. Both target templates register the author's native V2 package `@dietrichgebert/ponytail@4.12.0` in their local `plugins` arrays, alongside `opencode-mem` and `@tarquinen/opencode-dcp@latest`; `opentmux` remains commented as V1-only. The local `ponytail.mjs` files are removed from the toolkit root and both templates; no local API port or bridge replaces them.
+
+For existing targets, back up and obtain approval before removing only known obsolete toolkit `.opencode/plugins/ponytail.js`, `.mjs`, or `.ts` copies. Preserve unrelated local plugins; merge/deduplicate upstream package registration locally where appropriate, without editing or overwriting global plugins. Native local plugins are discovered automatically, so do not register them twice. Slim's separate strict schema keeps its own `prompt`, `permission`, and `variant`: do not host-migrate plugin-owned fields. The root's no-`plugins` policy is specific to this toolkit repository, not target templates.
+
+| Setting | Native V2 form |
+| --- | --- |
+| Agents | `agents`, JSON `system` (Markdown body for file agents), `request.body.temperature`, model `provider/model#variant` |
+| Permissions | Ordered `permissions` with `action`, `resource`, `effect`; `shell`/`subagent` actions; last match wins |
+| Commands | `commands`; delegated commands use `subagent` |
+| Plugins | `plugins`; options use `{ "package": "…", "options": {} }` |
+| Skills | Directory-path array, e.g. `[".agents/skills"]`, not Markdown globs |
+| MCP | `mcp.servers`; `disabled` inverts legacy `enabled`; `timeout.catalog`/`timeout.execution` |
+
+Follow official V2 [migration](https://opencode.ai/v2/docs/migrate-v1), [config](https://opencode.ai/v2/docs/config), [agents](https://opencode.ai/v2/docs/agents), and [plugins](https://opencode.ai/v2/docs/build/plugins) docs. The published `https://opencode.ai/config.json` schema may describe V1; it is not native V2 validation authority.
+
+**Runtime limits:** config `instructions` entries are accepted but not loaded; ambient `AGENTS.md` works. `@refs` are ordinary text, not automatic attachments: agents must read referenced snippets explicitly. `request.body.temperature` remains in config, but the current runner does not send it. Plugin/runtime integration has not been tested. Preserve `lsp: true`, but V2 currently exposes no LSP tools or diagnostics: use project lint/typecheck/compiler commands.
+
+`--env opencode` includes minimal shared references for wrappers and AGENTS-linked standards without activating other harnesses. Merge, don't clobber: back up V1, preserve models/providers and user/global plugins, and ask before changes. Native-converted files are **incompatible with V1**. Activate on the next run/restart, then check behavior with the installed V2 runtime. `doctor` checks scaffold files/placeholders, not runtime behavior; do not substitute a V1 API/schema fetch or claim checks that were not run.
+
+### Native Codex
+
+- `--env codex` includes `.codex/`, `.agents/`, and shared context, plus `.github/instructions/` and `.claude/rules-snippets/` solely to supply the standards linked from `AGENTS.md` and those standards' wrapper source content. It does not install other harness command, agent, or config directories. These reference files neither establish Copilot/Claude use nor load automatically as Codex rules; other harness scopes are unchanged.
+- Codex reads `AGENTS.md` and discovers `.agents/skills/*/SKILL.md` natively. Monorepos can use more-specific nested `AGENTS.md` files for app/package guidance. Linked standards are references to read as needed, not automatically loaded Claude/Copilot rules.
+- The optional `.codex/config.toml` is deliberately comment-only: it preserves the user's inherited defaults. Codex loads project config only after the user explicitly trusts the project; the toolkit does not grant trust or set model/provider, approval, sandbox, security, or feature overrides.
+- For manual copies without `.nitm/`, provide `.claude/prompt-snippets/bootstrap.md` to Codex directly. For incremental AI-guided merges, provide `.claude/prompt-snippets/bootstrap-patch.md` as a task document; the CLI `patch` command only adds missing files.
+- Codex MCP configuration uses native `[mcp_servers.name]` TOML in Codex config, **not `.mcp.json`**. No MCP servers are activated by the Codex template. Configure only user-approved servers using the native docs; do not copy credentials or activate other harness hooks automatically.
+- Existing `.claude/agents/`, `.github/agents/`, and `.opencode/agents/` formats are tool-specific, not Codex custom agents. This toolkit does not translate their frontmatter or permissions into Codex configuration. Use only delegation capabilities actually available in your running harness.
+
+Official Codex docs: [basic configuration](https://learn.chatgpt.com/docs/config-file/config-basic) · [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference) · [AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md) · [skills](https://learn.chatgpt.com/docs/build-skills) · [MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).
 
 ## Placeholder Reference
 
@@ -680,7 +732,7 @@ This toolkit includes **32 pre-installed universal skills** in the `.agents/skil
 
 **These skills are ready to use immediately after copying the templates.** No `npx -y skills add -a <agent> <owner/repo> --skill '*' --agent github-copilot cursor` commands needed.
 
-The **ponytail** skill bundle is an integrated optional skill set from [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) that adds YAGNI/stdlib/native/one-line/minimum discipline to your AI agents. It includes 6 skills, 6 commands, an OpenCode plugin, 7 activation hooks, and ambient agent rules — all pre-configured and ready to use.
+The **ponytail** skill bundle is an integrated optional skill set from [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) that adds YAGNI/stdlib/native/one-line/minimum discipline to your AI agents. It includes 6 skills, 6 commands, 7 activation hooks, and ambient agent rules. OpenCode uses the author's upstream `@dietrichgebert/ponytail@4.12.0` package, not a bundled local plugin. See [native setup](#native-opencode-v2-toolkit-400); scaffolding alone does not establish activation.
 
 ### Additional Recommended Skills
 

package/bin/cli.js

@@ -13,15 +13,20 @@ const { execSync, spawnSync } = require('child_process');
 const PKG_ROOT = path.join(__dirname, '..');
 const SRC_DIR = path.join(PKG_ROOT, 'src');
 
-// Platform config dirs per harness. `.agents` is Claude-only (universal skills).
+// Platform config dirs per harness. Claude and Codex share `.agents` (universal skills).
 const ENV_DIRS = {
   claude: ['.claude', '.agents'],
+  codex: ['.codex', '.agents', path.join('.github', 'instructions'), path.join('.claude', 'rules-snippets')],
   copilot: ['.github', '.vscode'],
   cursor: ['.cursor'],
-  opencode: ['.opencode'],
+  // Shared reference sources, not other harnesses' active config/agent wrappers.
+  opencode: ['.opencode', path.join('.agents', 'skills'),
+    path.join('.claude', 'agents-snippets'), path.join('.claude', 'prompt-snippets'),
+    path.join('.claude', 'rules-snippets'), path.join('.github', 'instructions')],
 };
 const ENV_INFO = {
   claude: { name: 'Claude Code', command: '/bootstrap (Claude Code command in .claude/commands/)' },
+  codex: { name: 'OpenAI Codex', command: 'read and follow .nitm/BOOTSTRAP.md' },
   copilot: { name: 'GitHub Copilot', command: '/bootstrap (Copilot prompt in .github/prompts/bootstrap.prompt.md)' },
   cursor: { name: 'Cursor', command: '/bootstrap (Cursor command in .cursor/commands/)' },
   opencode: { name: 'OpenCode', command: 'the bootstrap command in .opencode/commands/' },
@@ -84,9 +89,12 @@ function templateFiles(type) {
 function scopeFiles(files, env) {
   if (!env || !ENV_DIRS[env]) return files;
   const allowed = new Set([...SHARED_ROOT, ...SHARED_DIRS, ...ENV_DIRS[env]]);
+  const dirs = [...SHARED_DIRS, ...ENV_DIRS[env]].map((dir) => path.normalize(dir));
   return files.filter((rel) => {
-    const top = rel.split(path.sep)[0];
-    return allowed.has(top) || allowed.has(rel);
+    const normalized = path.normalize(rel);
+    const top = normalized.split(path.sep)[0];
+    return allowed.has(top) || allowed.has(normalized)
+      || dirs.some((dir) => normalized.startsWith(dir + path.sep));
   });
 }
 
@@ -137,8 +145,10 @@ function envHeader(type, env) {
       '2. Calibrate each agent\'s tools for your environment (see the Agent Tool & Permission Calibration section).',
       '3. Verify with `npx nitm-ai-dev-toolkit doctor`.',
       '',
-      'The `/bootstrap` command auto-detects your harness (Claude Code, GitHub Copilot, Cursor, or OpenCode),',
-      'so you do not need to specify it — just run `/bootstrap` from whatever environment you are in.',
+      'The default scaffold includes Claude Code, OpenAI Codex, GitHub Copilot, Cursor, and OpenCode.',
+      'Ask your AI agent to read and follow `.nitm/BOOTSTRAP.md`.',
+      'Claude Code, GitHub Copilot, Cursor, and OpenCode also have harness-specific bootstrap commands.',
+      'For OpenAI Codex, use the handoff file directly; no native `/bootstrap` command is provided.',
       '',
       'The full bootstrap procedure follows.',
     ].join('\n');
@@ -147,7 +157,7 @@ function envHeader(type, env) {
   return [
     `# Bootstrap handoff — environment: ${info.name}`,
     '',
-    `Run the bootstrap via: ${info.command}`,
+    `Bootstrap entry point: ${info.command}`,
     '',
       'Then ask your AI agent to run the full bootstrap flow (procedure below). Key steps:',
       '1. Replace all `{{PLACEHOLDER}}` values in the AI instruction files.',
@@ -168,12 +178,15 @@ function handoff(type, cwd, env) {
   fs.writeFileSync(path.join(nitmDir, 'BOOTSTRAP.md'), header + '\n\n' + body);
   if (env && ENV_INFO[env]) {
     info(`Scaffold complete (tailored to ${ENV_INFO[env].name}). Hand off to your AI agent:`);
-    console.log(`    Run ${ENV_INFO[env].command}`);
+    console.log(`    Bootstrap entry point: ${ENV_INFO[env].command}`);
   } else {
     info('Scaffold complete. Hand off to your AI agent to finish setup:');
   }
-  console.log('    1. Run `/bootstrap` from your AI environment (it auto-detects your harness),');
-  console.log('       OR hand `.nitm/BOOTSTRAP.md` to your AI agent to run the full bootstrap flow.');
+  console.log('    1. Ask your AI agent to read and follow `.nitm/BOOTSTRAP.md`.');
+  if (!env || !ENV_INFO[env]) {
+    console.log('       Includes Claude Code, OpenAI Codex, GitHub Copilot, Cursor, and OpenCode.');
+    console.log('       Other harnesses also have bootstrap commands; Codex uses the handoff file directly.');
+  }
   console.log('    2. Run `npx nitm-ai-dev-toolkit doctor' + (env ? ` --env ${env}` : '') + '` to verify the install.');
 }
 
@@ -319,7 +332,7 @@ function usage() {
   console.log(`nitm-ai-dev-toolkit — scaffold AI agent config into any repo, then hand off to your AI agent.
 
 Usage:
-  npx nitm-ai-dev-toolkit install [--monorepo|--repo] [--env <claude|copilot|cursor|opencode>] [--force]
+  npx nitm-ai-dev-toolkit install [--monorepo|--repo] [--env <claude|codex|copilot|cursor|opencode>] [--force]
       Scaffold AI config into the current repo (auto-detects repo vs monorepo),
       tailored to your harness, then hand off to your AI agent to run the bootstrap flow.
       If files already exist, install aborts (use --force to overwrite, or \`patch\` to add missing).
@@ -341,9 +354,11 @@ Usage:
 
 Options:
   --env <env>  Optional. Limit the scaffold to ONE harness:
-               claude | copilot | cursor | opencode
-               Omit to scaffold ALL environments (cross-compatible). The /bootstrap
-               command auto-detects your harness at runtime, so --env is rarely needed.
+               claude | codex | copilot | cursor | opencode
+               Omit to scaffold ALL environments, including OpenAI Codex.
+               Ask your agent to read and follow .nitm/BOOTSTRAP.md.
+               Other harnesses also have bootstrap commands; Codex uses the handoff
+               file directly (no native /bootstrap command is provided).
   --monorepo   Force monorepo template
   --repo       Force single-repo template
   --force      Overwrite existing files

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nitm-ai-dev-toolkit",
-  "version": "3.0.22",
-  "description": "Scaffold AI agent config (Cursor, GitHub Copilot, Claude Code, OpenCode) into any repo, then hand off to your AI agent to finish setup.",
+  "version": "4.0.0",
+  "description": "Scaffold AI agent config (Cursor, GitHub Copilot, Claude Code, OpenCode, Codex) into any repo, then hand off to your AI agent to finish setup.",
   "bin": {
     "nitm-ai-dev-toolkit": "bin/cli.js"
   },
@@ -22,6 +22,7 @@
     "cursor",
     "copilot",
     "opencode",
+    "codex",
     "bootstrap",
     "subagents"
   ],

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,9 +1,17 @@
-You are helping to patch AI instructions in this project by comparing against the latest templates from the ai-assisted-dev-toolkit repository and applying any updates.
+You are helping to patch AI instructions by comparing against supported toolkit v4.x templates from the ai-assisted-dev-toolkit repository's `v4.x` branch and merging updates into this project.
+
+## OpenCode version preflight (before any changes)
+
+- Confirm OpenCode use from actual session/runtime evidence or ask the user; directory presence alone is not proof. If only other harnesses are used, skip this preflight and all OpenCode steps.
+- For confirmed OpenCode use, run `opencode --version` before any project writes. Trim output and parse numeric major/minor/patch components, accepting an optional leading `v`; toolkit 4.x requires `major >= 2`.
+- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as `4.0.0`. Ask the user to upgrade OpenCode to V2 or remain on toolkit 3.x.
+- If the CLI is missing, fails, or output is unparseable, **STOP OpenCode steps** and leave the version marker unchanged; ask the user to confirm/install a supported OpenCode version, then rerun this check. Never assume V2.
+- If oh-my-opencode-slim >=3.0.0 is used or planned, require OpenCode >=2.0.7 (compare version components numerically); otherwise **STOP** before changes and ask to upgrade. Proceed only after this gate passes.
 
 ## Orchestrator Checkpoint
 
 > **🛑 Before starting**: This command involves fetching, diffing, and applying changes across many files.
-> Dispatch parallel subagents for independent file groups (rules, commands, prompts, instructions, skills, agents).
+> Complete Step 1's source/version gates before dispatching parallel diff agents for independent file groups (rules, commands, prompts, instructions, skills, agents).
 > See `.claude/rules-snippets/subagent-workflow.md` for patterns.
 
 ## Usage
@@ -17,15 +25,22 @@ You are helping to patch AI instructions in this project by comparing against th
 
 ## Process
 
+**Codex invocation and scope:** `/bootstrap-patch` is not a native Codex command. Ask Codex to read and follow this snippet as a task document. Identify the actual harness from session/runtime evidence or ask; scaffold directories do not prove use. Codex targets root/nested `AGENTS.md`, `.agents/skills/`, and optional `.codex/config.toml`. Include `.github/instructions/` and `.claude/rules-snippets/` solely as AGENTS-linked standards and their wrapper sources for Codex-scoped installs, not automatically loaded rules or evidence of Copilot/Claude use. Only include other harness command, agent, and config categories when those harnesses are confirmed in use.
+
+**Codex merge guardrails:** preserve existing TOML and inherited user defaults. The shipped `.codex/config.toml` is comment-only; parse it as TOML, do not add model/provider, approval, sandbox, security, feature, self-trust, or active MCP settings. Project config is loaded only after explicit user trust. MCP uses native `[mcp_servers.name]` TOML, not `.mcp.json`; do not migrate or activate servers automatically. Claude/Copilot frontmatter and OpenCode permission blocks are not Codex agent definitions; no Codex custom-agent format is shipped here.
+
 1.  **Fetch Latest Templates**:
 
-    Clone or fetch the latest ai-assisted-dev-toolkit templates:
+    Fetch only the supported `v4.x` source branch:
 
     ```bash
+    set -e
     TOOLKIT_TEMP=$(mktemp -d)
-    git clone --depth 1 https://github.com/ninjasitm/ai-assisted-dev-toolkit.git "$TOOLKIT_TEMP"
+    git clone --depth 1 --branch v4.x https://github.com/ninjasitm/ai-assisted-dev-toolkit.git "$TOOLKIT_TEMP"
     ```
 
+    **Source availability gate:** If the clone fails or `v4.x` is unavailable (for example, not yet published), **STOP** before diff/apply/version marking. Do not fall back to the default branch or V3, and do not push/publish a branch to unblock this task; ask for an approved available v4.x source.
+
     Determine the correct source path based on project structure:
     - **Single repo**: Use `$TOOLKIT_TEMP/src/repo/`
     - **Monorepo**: Use `$TOOLKIT_TEMP/src/monorepo/`
@@ -38,9 +53,11 @@ You are helping to patch AI instructions in this project by comparing against th
 
     Check for a `.toolkit-version` file in the project root:
     - If exists: Read the version string (e.g., `2.0.10`, `3.0.0`)
-    - If missing: Assume legacy version (pre-3.0.0)
+    - If missing: Verify the installed version or legacy state with the user; absence alone does not prove a pre-3.0 installation
+
+    Read the toolkit's version from the `version` field in `$TOOLKIT_TEMP/package.json` to compare; `.toolkit-version` tracks the target project's installed version.
 
-    Read the toolkit's version from `$TOOLKIT_TEMP/.toolkit-version` to compare.
+    **Source version guard (before diff/apply/version marking):** Parse source/target versions as SemVer and compare them (major/minor/patch numerically). If the fetched package's major is not `4`, or its version is older than the target `.toolkit-version`, **STOP** without diffing, applying changes, or updating the marker. Unknown/unparseable versions must also **STOP** and ask rather than guess. Never auto-downgrade.
 
     **Version Comparison:**
     - **Same version**: No structural changes expected
@@ -63,6 +80,7 @@ You are helping to patch AI instructions in this project by comparing against th
     | **Claude Agents**          | `.claude/agents/*.agent.md`              | `src/{type}/.claude/agents/*.agent.md`              |
     | **Skills**                 | `.agents/skills/*/SKILL.md`              | `src/{type}/.agents/skills/*/SKILL.md`              |
     | **AGENTS.md**              | `AGENTS.md`                              | `src/{type}/AGENTS.md`                              |
+    | **Codex Config**           | `.codex/config.toml`                     | `src/{type}/.codex/config.toml`                     |
     | **CLAUDE.md**              | `CLAUDE.md`                              | `src/{type}/CLAUDE.md`                              |
     | **Claude Rules Snippets**  | `.claude/rules-snippets/*.md`            | `src/{type}/.claude/rules-snippets/*.md`            |
     | **Claude Prompt Snippets** | `.claude/prompt-snippets/*.md`           | `src/{type}/.claude/prompt-snippets/*.md`           |
@@ -71,20 +89,20 @@ You are helping to patch AI instructions in this project by comparing against th
     | **OpenCode Commands**      | `.opencode/commands/*.md`                | `src/{type}/.opencode/commands/*.md`                |
     | **OpenCode Rules**         | `.opencode/rules/*.md`                   | `src/{type}/.opencode/rules/*.md`                   |
     | **OpenCode Agents**        | `.opencode/agents/*.md`                  | `src/{type}/.opencode/agents/*.md`                  |
-    | **OpenCode Plugins**       | `.opencode/plugins/*.mjs`                | `src/{type}/.opencode/plugins/*.mjs`                |
+    | **OpenCode Local Plugins** | `.opencode/plugins/*.{js,mjs,ts}`        | Inventory only; preserve unrelated plugins         |
     | **Hooks**                  | `hooks/*.{js,sh,ps1}`                    | `src/{type}/hooks/*.{js,sh,ps1}`                    |
     | **Agent Rules**            | `.agents/rules/*.md`                     | `src/{type}/.agents/rules/*.md`                     |
-    | **Toolkit Version**        | `.toolkit-version`                       | `.toolkit-version` (root of toolkit)                |
-
-    **⚠️ OpenCode `opencode.jsonc` Schema Validation:**
-
-    When patching `.opencode/opencode.jsonc`, **only add or modify supported top-level keys**. The schema is defined at `https://opencode.ai/config.json`. Do NOT add unsupported keys.
+    | **Toolkit Version**        | `.toolkit-version`                       | `package.json` `version` (toolkit root)             |
 
-    **Supported top-level keys:** `$schema`, `instructions`, `skills`, `agent`, `default_agent`, `model`, `small_model`, `provider`, `mcp`, `tools`, `permission`, `lsp`, `formatter`, `server`, `shell`, `command`, `plugin`, `watcher`, `snapshot`, `share`, `autoupdate`, `compaction`, `attachment`, `logLevel`, `disabled_providers`, `enabled_providers`, `tool_output`, `enterprise`, `experimental`
+    **OpenCode native V2 merge checks (confirmed OpenCode use only):**
 
-        **Do NOT add** keys like `rules`, `agents`, `commands`, `prompts` as top-level keys — OpenCode uses the `.opencode/` directory structure and `instructions` array instead.
+    Follow official V2 [migration](https://opencode.ai/v2/docs/migrate-v1), [config](https://opencode.ai/v2/docs/config), [agents](https://opencode.ai/v2/docs/agents), and [plugins](https://opencode.ai/v2/docs/build/plugins) docs. The published schema may describe V1; neither it nor a V1 API fetch validates native V2. Plural keys are intentional.
 
-    > **Watch out:** the ponytail template uses the `plugin` key (singular). If you see `plugins` (plural) in your `opencode.jsonc`, that's a typo and the plugin won't load.
+    - Use `agents`/`system`, `request.body.temperature`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`, last match wins), `commands`/`subagent`, `plugins` with `{ "package": "…", "options": {} }`, skill-directory arrays, and `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`.
+    - The version preflight must pass before changes. Back up V1 before native conversion (converted files are incompatible with V1). Preserve models/providers/user-global plugins. Only with approval, merge `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally. Slim's separate strict schema keeps `prompt`/`permission`/`variant`; do not host-migrate it or silently upgrade the separate external starter.
+    - **Ponytail replacement (plan here; apply after backup and approval in Step 5):** Remove only known obsolete toolkit-owned `.opencode/plugins/ponytail.js`, `.opencode/plugins/ponytail.mjs`, and `.opencode/plugins/ponytail.ts` copies. Preserve unrelated local plugins. Merge/deduplicate the author's native V2 `@dietrichgebert/ponytail@4.12.0` registration in the local `plugins` array where appropriate, retaining other registrations/options; do not edit global config. Keep `opentmux` commented as V1-only. Do not port local APIs or add bridges; runtime integration is untested. Native local discovery needs no duplicate registration.
+    - `instructions` entries are accepted but not loaded; ambient root/nested `AGENTS.md` works. `@refs` are ordinary text: explicitly read snippets. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`; use workspace lint/typecheck/compiler commands (no V2 LSP tools/diagnostics currently).
+    - `--env opencode` supplies minimal shared references without other harness activation. Activate on the next run/restart and report only installed-V2 checks actually run, not assumed runtime validation. Publishing 4.0.0 has not been executed.
 
 3.  **Diff Analysis** (parallelizable — dispatch one subagent per category):
 
@@ -95,7 +113,7 @@ You are helping to patch AI instructions in this project by comparing against th
     - **📝 Updated**: Exists in both but template has newer content → candidate for merge
     - **✅ Current**: Exists in both and content matches → no action needed
     - **🔧 Customized**: Exists in both, project version has non-placeholder customizations → careful merge
-    - **⚠️ Missing in Template**: Exists in project but not in template → project-specific, keep as-is
+    - **⚠️ Missing in Template**: Exists in project but not in template → project-specific, keep as-is except the approved obsolete toolkit Ponytail removal above
 
     b. **For updated files, generate a structured diff**:
     - Preserve project-specific `{{PLACEHOLDER}}` replacements (already-bootstrapped values)
@@ -156,7 +174,9 @@ You are helping to patch AI instructions in this project by comparing against th
       a. **New files**: Copy directly from template
       b. **Updated files (no customization)**: Replace with template version
       c. **Updated files (customized)**: Apply structural additions while preserving project values
-      d. **Git commit**: Stage and commit all changes with message:
+      d. **OpenCode plugins**: Apply only the approved Ponytail replacement above after backing up the known obsolete toolkit copies and local config; preserve all unrelated local/global plugins.
+      e. **Toolkit version**: Update `.toolkit-version` to the fetched toolkit version (`4.0.0` for this migration) only after the approved migration and OpenCode preflight pass (or OpenCode is confirmed out of scope).
+      f. **Git commit**: Stage and commit all changes with message:
       ```bash
       git add -A
       git commit -m "chore: patch AI instructions from toolkit [$(date +%Y-%m-%d)]"