nitm-ai-dev-toolkit 3.0.22 → 4.0.0

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

@@ -2,6 +2,24 @@ 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.
+
+- Identify the actual running harness from session/runtime information or ask which harnesses the user uses. Directory presence alone is not evidence: the default installer scaffolds every supported harness.
+- Codex uses root and more-specific nested `AGENTS.md` instructions and `.agents/skills/*/SKILL.md` natively. Customize app/package instructions for their scopes. Read linked standards when relevant; Claude snippets and `.github/instructions/` are not automatically loaded as Codex rules.
+- `.codex/config.toml` is optional and comment-only. Preserve inherited defaults and existing user settings. Project config is loaded only after the user explicitly trusts the project; never write self-trust or change model/provider, approvals, sandbox, security, or feature settings during bootstrap.
+- Codex MCP uses native `[mcp_servers.name]` TOML, not `.mcp.json`. Treat other harness MCP templates as references only; do not activate servers, copy credentials, or install hooks automatically.
+- Update and audit only confirmed harness targets. For Codex-only setup, the native targets are root/nested `AGENTS.md`, `.agents/skills/`, and `.codex/config.toml`. `--env codex` also includes `.github/instructions/` and `.claude/rules-snippets/` solely as AGENTS-linked standards and their wrapper sources, not automatically loaded rules or evidence of Copilot/Claude use; other harness command, agent, and config directories are excluded. Tool-specific steps below are conditional.
+
 ## Your Task
 
 1. **Analyze the Monorepo**:
@@ -123,8 +141,12 @@ 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)
+   - `.codex/config.toml` (optional Codex config; retain comment-only inherited defaults)
    - `.github/copilot-instructions.md` (include PM context)
    - `.github/instructions/*.instructions.md`
    - `.github/prompts/*.prompt.md`
@@ -136,27 +158,36 @@ You are helping to bootstrap AI instructions for this monorepo by analyzing the
    - `.claude/rules-snippets/*.md` (rules content — source of truth)
    - `.claude/prompt-snippets/*.md` (prompt content — source of truth)
    - `.claude/agents-snippets/*.md` (agent definitions — source of truth)
-   - `.opencode/opencode.jsonc` (OpenCode configuration — ⚠️ see schema validation below)
+   - `.opencode/opencode.jsonc` (OpenCode configuration — see native V2 checks below)
    - `.opencode/commands/*.md` (OpenCode commands)
    - `.opencode/rules/*.md` (OpenCode rules)
    - `.opencode/agents/*.md` (OpenCode agents)
    - `.toolkit-version` (version tracking)
    - `CLAUDE.md` (if it contains placeholders)
 
-   **⚠️ OpenCode `opencode.jsonc` Schema Validation:**
+   **OpenCode native V2 checks (only for confirmed OpenCode use):**
 
-   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.
+   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.
 
-   **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`
+   - 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.
 
-   **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).
+   **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.
+   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.
@@ -239,7 +270,9 @@ For multi-app monorepos with different frameworks, list all with app context (e.
 
 #### Agent Tool & Permission Calibration
 
-The `tools:` block (Claude Code, GitHub Copilot) and `permission:` block (OpenCode) must match each agent's role **and** the detected project. Templates ship with defaults, but calibrate them during bootstrap so every agent can do its job without being over-provisioned.
+The `tools:` block (Claude Code, GitHub Copilot) and ordered `permissions:` rules (OpenCode V2) must match each agent's role **and** the detected project. Inspect actual defaults before proposing changes; calibrate without over-provisioning.
+
+**Codex native calibration:** customize project instructions and skills, not Claude/Copilot `tools:` frontmatter or OpenCode `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:
 
@@ -254,22 +287,22 @@ The `tools:` block (Claude Code, GitHub Copilot) and `permission:` block (OpenCo
 
 **2. Translate the baseline to each platform's syntax:**
 
-| Capability         | Claude Code     | GitHub Copilot                         | OpenCode (`permission:`) | Cursor  |
+| Capability         | Claude Code     | GitHub Copilot                         | OpenCode (`permissions:` rule) | Cursor  |
 | ------------------ | --------------- | -------------------------------------- | ------------------------ | ------- |
 | read               | `Read`          | `read`                                 | default                  | default |
 | search             | `Grep`          | `search`                               | default                  | default |
-| write / edit files | `Write`, `Edit` | `edit`                                 | `edit: allow`            | default |
-| terminal           | `Bash(*)`       | `runInTerminal`, `terminalLastCommand` | `bash: allow`            | default |
-| spawn subagents    | `agent`         | n/a                                    | `task: allow`            | default |
+| write / edit files | `Write`, `Edit` | `edit`                                 | `{action: edit, resource: "*", effect: allow}` | default |
+| terminal           | `Bash(*)`       | `runInTerminal`, `terminalLastCommand` | `{action: shell, resource: "*", effect: allow}` | default |
+| spawn subagents    | `agent`         | n/a                                    | `{action: subagent, resource: "*", effect: allow}` | default |
 
 > **Cursor note:** these templates declare no `tools:` field, so Cursor subagents inherit the full default toolset. Read-only intent (Researcher, Reviewer) is enforced by the agent's instructions, not tool gating. If your Cursor version supports per-agent tool restriction, add a `tools:` field to match the baseline.
 
 **3. Project-driven adjustments** (widen or narrow from the baseline):
 
-- **Planner** — If plans are persisted to files (e.g. `docs/plans/`, `docs/features/`), it MUST have write + terminal. The Copilot default is read-only (`["read","search"]`) and the OpenCode default denies `edit`/`bash` — **widen both** to the baseline. The Claude default already has `Write` but lacks `Bash(*)` — add it so the planner can run `git log` / discover tests.
-- **Documenter** — Always needs edit (updates existing docs); needs terminal when the project uses doc generators (mkdocs, typedoc, sphinx, docusaurus). The OpenCode default denies `edit`/`bash` and the Claude default omits `Edit`/`Bash(*)` — **widen both** to the baseline. The Copilot default is already correct.
+- **Planner** — Persisted plans need write + terminal. If Copilot is read-only (`["read","search"]`), widen to the baseline. If Claude lacks `Bash(*)`, add it for `git log` / test discovery. For OpenCode, inspect ordered rules and propose `edit`/`shell` allows only when missing and approved.
+- **Documenter** — Needs edit for docs, terminal for doc generators. If Claude omits `Edit`/`Bash(*)`, propose them. For OpenCode, inspect ordered `edit`/`shell` rules against this baseline, not presumed legacy defaults.
 - **Researcher** — Must stay read-only on every platform. The Claude Code default currently grants `Write` — **remove it** (`["Read","Grep"]`).
-- **Reviewer** — Read + terminal only; never grant write/edit. The OpenCode default denies `bash` — **allow `bash`** (keep `edit: deny`) so it can run `git diff` / tests. The Claude default grants `Write` — **remove it** (keep `Bash(*)`).
+- **Reviewer** — Read + terminal only; never grant write/edit. OpenCode ordered rules should allow `shell` and deny `edit` for this baseline. If Claude grants `Write`, remove it (keep `Bash(*)`).
 - **Worker agents** (Planner, Implementer, Red, Green, Refactor) — in a monorepo keep `user-invocable: false`; they are coordinator-dispatched only.
 
 **4. Apply:** for each agent file (`.claude/agents/*.agent.md`, `.github/agents/*.agent.md`, `.opencode/agents/*.md`), compare the declared tools/permissions to the calibrated baseline and adjust. List the changes, then confirm before applying.
@@ -278,16 +311,16 @@ Present the replacements and confirm before applying.
 
 9. **Detect Installed AI Agents**:
 
-   Before recommending skills, detect which AI agent directories exist in the workspace. Supported agents are located here: https://github.com/vercel-labs/skills?tab=readme-ov-file#available-agents:
+   Before recommending skills, identify the running harness from session/runtime information and confirm additional harnesses with the user. Consult supported installer IDs at https://github.com/vercel-labs/skills?tab=readme-ov-file#available-agents.
 
-   **Note:** `.agents/` directory is used by multiple agents: `amp`, `codex`, `gemini-cli`, `github-copilot`, `opencode`, `replit`. If only `.agents/` exists, default to `codex` or `github-copilot` based on other indicators.
+   **Note:** `.agents/` is shared by multiple agents. Neither it nor scaffolded `.codex/`, `.claude/`, `.cursor/`, or `.github/` directories proves a harness is installed or used. If runtime evidence is unavailable, ask rather than defaulting to an agent.
 
-   **Note:** `.claude/` directory indicates Claude Code is installed. Add `-a claude-code` to agent flags.
+   **Codex:** the skills installer supports agent ID `codex`; confirmed Codex use maps to `-a codex` and native `.agents/skills/`.
 
    **Build the agent flags string:**
-   - For each detected agent, add `-a <agent>` to the command
-   - Example: If `.cursor/`, `.claude/`, and `.github/` exist → use `-a cursor -a claude-code -a github-copilot`
-   - If no agents detected, omit `-a` flags (CLI will prompt)
+   - For each confirmed harness, add `-a <supported-agent-id>` to the command
+   - Example: confirmed Cursor, Claude Code, and Copilot → `-a cursor -a claude-code -a github-copilot`
+   - If no harness is confirmed, ask before installing (or let the CLI prompt); do not infer from scaffold directories
 
 10. **Recommend and Install AI Agent Skills**:
 
@@ -303,11 +336,11 @@ Based on detected ecosystem and frameworks, recommend relevant skills from [skil
 | `trailofbits/skills`       | Security analysis, Semgrep, property-based testing |
 | `softaworks/agent-toolkit` | README writing, clear documentation                |
 
-**Example commands** (replace `<detected-agents>` with the actual flags from step 9, e.g., `-a cursor -a github-copilot`):
+**Example commands** (replace `{{AGENT_FLAGS}}` with confirmed harness flags from step 9, e.g., `-a codex`):
 
 ```bash
-npx -y skills add <detected-agents> obra/superpowers --skill '*' --agent github-copilot cursor
-npx -y skills add <detected-agents> trailofbits/skills --skill '*' --agent github-copilot cursor
+npx -y skills add {{AGENT_FLAGS}} obra/superpowers --skill '*'
+npx -y skills add {{AGENT_FLAGS}} trailofbits/skills --skill '*'
 ```
 
 **Issue Tracker Skills Health Check (if {{ISSUE_TRACKER}} is configured):**
@@ -361,25 +394,25 @@ When recommending framework-specific skills, include the detected agent flags. E
 
 | Language/Framework | Skill Repository                      | Install Command                                                                                          |
 | ------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| PHP                | `vapvarun/claude-backup` (php)        | `npx -y skills add <detected-agents> vapvarun/claude-backup --skill "php"`                               |
-| Laravel            | `vapvarun/claude-backup` (laravel)    | `npx -y skills add <detected-agents> vapvarun/claude-backup --skill "laravel"`                           |
-| Python             | `siviter-xyz/dot-agent` (python)      | `npx -y skills add <detected-agents> siviter-xyz/dot-agent --skill "python"`                             |
-| Django             | `vintasoftware/django-ai-plugins`     | `npx -y skills add <detected-agents> vintasoftware/django-ai-plugins --skill "django-expert"`            |
-| Next.js            | `sickn33/antigravity-awesome-skills`  | `npx -y skills add <detected-agents> sickn33/antigravity-awesome-skills --skill "nextjs-best-practices"` |
-| React              | `vercel-labs/agent-skills`            | `npx -y skills add <detected-agents> vercel-labs/agent-skills --skill "vercel-react-best-practices"`     |
-| Vue                | `onmax/nuxt-skills` (vue)             | `npx -y skills add <detected-agents> onmax/nuxt-skills --skill "vue"`                                    |
-| Nuxt               | `onmax/nuxt-skills` (nuxt)            | `npx -y skills add <detected-agents> onmax/nuxt-skills --skill "nuxt"`                                   |
-| Expo               | `expo/skills`                         | `npx -y skills add <detected-agents> expo/skills --skill '*' --agent github-copilot cursor`              |
-| TypeScript         | `pproenca/dot-skills` (typescript)    | `npx -y skills add <detected-agents> pproenca/dot-skills --skill '*' --agent github-copilot cursor`      |
-| Advanced Types     | `wshobson/agents` (ts-advanced-types) | `npx -y skills add <detected-agents> wshobson/agents --skill '*' --agent github-copilot cursor`          |
+| PHP                | `vapvarun/claude-backup` (php)        | `npx -y skills add {{AGENT_FLAGS}} vapvarun/claude-backup --skill "php"` |
+| Laravel            | `vapvarun/claude-backup` (laravel)    | `npx -y skills add {{AGENT_FLAGS}} vapvarun/claude-backup --skill "laravel"` |
+| Python             | `siviter-xyz/dot-agent` (python)      | `npx -y skills add {{AGENT_FLAGS}} siviter-xyz/dot-agent --skill "python"` |
+| Django             | `vintasoftware/django-ai-plugins`     | `npx -y skills add {{AGENT_FLAGS}} vintasoftware/django-ai-plugins --skill "django-expert"` |
+| Next.js            | `sickn33/antigravity-awesome-skills`  | `npx -y skills add {{AGENT_FLAGS}} sickn33/antigravity-awesome-skills --skill "nextjs-best-practices"` |
+| React              | `vercel-labs/agent-skills`            | `npx -y skills add {{AGENT_FLAGS}} vercel-labs/agent-skills --skill "vercel-react-best-practices"` |
+| Vue                | `onmax/nuxt-skills` (vue)             | `npx -y skills add {{AGENT_FLAGS}} onmax/nuxt-skills --skill "vue"` |
+| Nuxt               | `onmax/nuxt-skills` (nuxt)            | `npx -y skills add {{AGENT_FLAGS}} onmax/nuxt-skills --skill "nuxt"` |
+| Expo               | `expo/skills`                         | `npx -y skills add {{AGENT_FLAGS}} expo/skills --skill '*'` |
+| TypeScript         | `pproenca/dot-skills` (typescript)    | `npx -y skills add {{AGENT_FLAGS}} pproenca/dot-skills --skill '*'` |
+| Advanced Types     | `wshobson/agents` (ts-advanced-types) | `npx -y skills add {{AGENT_FLAGS}} wshobson/agents --skill '*'` |
 
 **Skill Creation for Unsupported Frameworks:**
 
-Use `npx -y skills add <detected-agents> anthropics/skills --skill '*' --agent github-copilot cursor` (includes `skill-creator`) to create custom skills.
+Use `npx -y skills add {{AGENT_FLAGS}} anthropics/skills --skill '*'` (includes `skill-creator`) to create custom skills.
 
 **Monorepo-Specific Considerations:**
 
-- Install skills at workspace root (`.cursor/skills/{skill-name}/` or `.github/skills/{skill-name}/`)
+- Install skills at workspace root (Codex: `.agents/skills/{skill-name}/`); verify the installer's reported paths for other harnesses
 - Skills are installed by skill name, not org/repo path (e.g., `superpowers/` not `obra/superpowers/`)
 - Consider per-app skills if apps use different frameworks
 - Update root `AGENTS.md` to reference installed skills
@@ -397,9 +430,9 @@ Using flags: {{AGENT_FLAGS}}
 Based on your monorepo ({{BUILD_SYSTEM}}/{{LANGUAGE}}):
 
 Core Skills (recommended for all projects):
-npx -y skills add {{AGENT_FLAGS}} obra/superpowers --skill '*' --agent github-copilot cursor
-npx -y skills add {{AGENT_FLAGS}} trailofbits/skills --skill '*' --agent github-copilot cursor
-npx -y skills add {{AGENT_FLAGS}} softaworks/agent-toolkit --skill '*' --agent github-copilot cursor
+npx -y skills add {{AGENT_FLAGS}} obra/superpowers --skill '*'
+npx -y skills add {{AGENT_FLAGS}} trailofbits/skills --skill '*'
+npx -y skills add {{AGENT_FLAGS}} softaworks/agent-toolkit --skill '*'
 
 Issue Tracker Skills (bundled — {{ISSUE_TRACKER}}):
 ✅ .agents/skills/issue-tracker/SKILL.md (shared strategy)
@@ -407,49 +440,42 @@ Issue Tracker Skills (bundled — {{ISSUE_TRACKER}}):
 ⚠️ Prune any issue-tracker CLI skills that do not match {{ISSUE_TRACKER}} (if any)
 
 Framework-Specific Skills:
-- web (Next.js): npx -y skills add {{AGENT_FLAGS}} vercel-labs/agent-skills --skill '*' --agent github-copilot cursor
-- api (Hono): npx -y skills add {{AGENT_FLAGS}} elysiajs/skills --skill '*' --agent github-copilot cursor
+- web (Next.js): npx -y skills add {{AGENT_FLAGS}} vercel-labs/agent-skills --skill '*'
+- api (Hono): npx -y skills add {{AGENT_FLAGS}} elysiajs/skills --skill '*'
 
 Install All? (Y/n)
 ```
 
 **Example with detected agents:**
 
-- If `.cursor/` and `.github/` exist: `AGENT_FLAGS="-a cursor -a github-copilot"`
-- If only `.cursor/` exists: `AGENT_FLAGS="-a cursor"`
-- Commands become: `npx -y skills add -a cursor -a github-copilot obra/superpowers --skill '*' --agent github-copilot cursor`
+- If Cursor and Copilot are confirmed: `AGENT_FLAGS="-a cursor -a github-copilot"`
+- If only Codex is confirmed: `AGENT_FLAGS="-a codex"`
+- Codex-only command: `npx -y skills add -a codex obra/superpowers --skill '*'`
 
 **On Confirmation:**
 
 - Run skill installation commands at workspace root
-- Skills installed to `.cursor/skills/`
+- Verify the installer's reported paths; Codex uses `.agents/skills/`
 - Update root `AGENTS.md` to reference installed skills
 - Add skill references to relevant app `AGENTS.md` files
 
 10. **Report Completion**:
 
+Populate this example with only files actually changed and skills actually installed. Omit unconfirmed harness targets; for Codex, include native targets and shared reference standards only when changed. This is a change inventory, not proof of runtime loading or trust.
+
 ```
 ✅ Monorepo Bootstrap Complete!
 
 Ecosystem: {{LANGUAGE}} / {{BUILD_SYSTEM}}
 
 Root Files Updated:
-- AGENTS.md
-- .github/copilot-instructions.md
-- .github/instructions/*.instructions.md
-- .cursor/rules/*.mdc
-- .cursor/commands/*.md
-- .claude/rules/*.md (thin wrappers)
-- .claude/commands/*.md (thin wrappers)
-- .claude/agents/*.agent.md (thin wrappers)
-- .claude/rules-snippets/*.md (rules content)
-- .claude/prompt-snippets/*.md (prompt content)
-- .claude/agents-snippets/*.md (agent content)
-- .opencode/opencode.jsonc
-- .opencode/commands/*.md
-- .opencode/rules/*.md
-- .opencode/agents/*.md
-- .toolkit-version
+- AGENTS.md (if changed)
+- .agents/skills/*/SKILL.md (if changed)
+- .codex/config.toml (Codex; if changed)
+- .github/instructions/*.instructions.md (linked standards or confirmed Copilot; if changed)
+- .claude/rules-snippets/*.md (reference sources; if changed)
+- Other confirmed harness files actually changed (list exact paths)
+- .toolkit-version (if changed)
 
 App Files Created/Updated:
 - {{APP_DIR}}/{{APP_1}}/AGENTS.md
@@ -459,9 +485,9 @@ Package/Library Files Updated:
 - {{PACKAGES_DIR}}/{{PACKAGE_1}}/README.md
 
 Installed Skills:
-- obra/superpowers - Development workflow
-- trailofbits/skills - Security & quality
-- {{FRAMEWORK_SKILL}} - Framework patterns
+- obra/superpowers - Development workflow (only if installed)
+- trailofbits/skills - Security & quality (only if installed)
+- {{FRAMEWORK_SKILL}} - Framework patterns (only if installed)
 
 Next Steps:
 1. Review root AGENTS.md for accuracy
@@ -475,7 +501,7 @@ Next Steps:
 9. **Review Installed Skills**:
 
    After completion, audit all installed skills:
-   - Scan `.github/skills/` and `.cursor/skills/` directories
+   - Scan `.agents/skills/` and confirmed harness skill directories, including `.github/skills/` and `.cursor/skills/` if used
    - Compare each skill against detected ecosystems and frameworks
    - Flag skills that don't match any app's tech stack
 
@@ -507,8 +533,12 @@ Next Steps:
 
     Check for required instruction files at root and app levels:
 
+    For Codex, verify root/app/package `AGENTS.md` instructions and `.agents/skills/*/SKILL.md`; parse optional `.codex/config.toml` as TOML and confirm inherited defaults are preserved. The Copilot-specific audit below applies only when Copilot is confirmed in use; do not create Copilot instructions merely to satisfy a Codex audit.
+
+    **Copilot Audit Example (only if Copilot is confirmed in use):**
+
     ```
-    ## 📋 Instruction Files Audit
+    ## 📋 Copilot Instruction Files Audit — confirmed Copilot use only
 
     ### ✅ Found ({{N}} files)
     | File | Purpose | Status |
@@ -523,48 +553,54 @@ Next Steps:
     | fastapi.instructions.md | FastAPI patterns | api app uses FastAPI |
     | testing.instructions.md | Test conventions | Multiple frameworks |
 
-    Create missing instruction files? (Y/n)
+    Create missing Copilot instruction files? (confirmed Copilot use only; Y/n)
     ```
 
-    **On Confirmation:**
-    - Generate instruction files with appropriate templates
+    **On Confirmation (only if Copilot is confirmed in use):**
+    - Generate missing Copilot instruction files with appropriate templates; skip creation for a Codex-only audit even when shared reference standards are present
     - Include app-specific scoping (applyTo paths)
     - Include framework-specific patterns from skills
     - Report created files
 
 11. **Final Verification Report**:
 
+    Report only actual changes and checks for confirmed harnesses. For Codex, distinguish file inspection and TOML validation from runtime instruction/skill discovery, project trust, and config loading. Mark runtime behavior unverified unless directly confirmed; file presence alone proves none of these. Remove inapplicable rows and mark checklist items complete only after performing the check.
+
     ```
-    ## ✅ Bootstrap Complete & Verified!
+    ## Bootstrap Verification Report
 
     ### Summary
     | Category | Count | Status |
     |----------|-------|--------|
-    | Root files updated | {{N}} | ✓ |
-    | App files created | {{N}} | ✓ |
-    | Package files updated | {{N}} | ✓ |
-    | Skills installed | {{N}} | ✓ |
-    | Skills removed | {{N}} | ✓ |
-    | Instructions created | {{N}} | ✓ |
+    | Root files updated | {{N}} | Report actual result |
+    | App files created | {{N}} | Report actual result |
+    | Package files updated | {{N}} | Report actual result |
+    | Skills installed | {{N}} | Report actual result |
+    | Skills removed | {{N}} | Report actual result |
+    | Instructions created | {{N}} | Report actual result |
 
     ### Quality Checks
-    - [x] Placeholders replaced
-    - [x] Skills match tech stack
-    - [x] No duplicate skills
-    - [x] All apps have AGENTS.md
-    - [x] Instructions cover all frameworks
-    - [x] Snippet directories created
-    - [x] Thin wrappers reference correct snippets
-    - [x] .opencode/ directory configured
-    - [x] .toolkit-version file created
-
-    ### Your Monorepo is Ready! 🎉
-
-    GitHub Copilot and Cursor understand:
-    - Monorepo structure
-    - App-specific frameworks
-    - Shared packages
-    - Cross-cutting patterns
+    - [ ] Placeholders replaced (list any remaining)
+    - [ ] Skills match tech stack
+    - [ ] No duplicate skills
+    - [ ] Applicable apps/packages have scoped AGENTS.md
+    - [ ] Instructions cover applicable frameworks
+    - [ ] Required reference snippet sources present and links resolve
+    - [ ] Thin wrappers reference correct snippets (if applicable)
+    - [ ] OpenCode configuration validated (only if OpenCode is confirmed in use)
+    - [ ] .toolkit-version file created or checked
+
+    ### Native Codex Check Example (only if Codex is confirmed in use)
+
+    | Target | Check to report | Result |
+    | ------ | --------------- | ------ |
+    | Root/app/package `AGENTS.md` | Contents, scopes, and linked standards inspected | Actual inspection result |
+    | `.agents/skills/*/SKILL.md` | Skill contents and relevance inspected | Actual inspection result; runtime discovery unverified unless confirmed |
+    | `.codex/config.toml` (if present) | TOML syntax and inherited defaults inspected | Actual validation result; user trust and native loading unverified unless confirmed |
+
+    ### Next Steps for Confirmed Harnesses
+
+    List the confirmed harnesses, checks actually performed, remaining issues, and runtime checks still needed. Do not infer Copilot/Cursor readiness or Codex trust/loading from scaffold files.
 
     Try asking:
     - "Create an endpoint in apps/api using our patterns"

package/src/monorepo/.codex/config.toml

@@ -0,0 +1,6 @@
+# Codex project configuration (optional).
+# Instructions: AGENTS.md; reusable skills: .agents/skills/.
+# Intentionally comment-only: inherit the user's Codex defaults.
+# Codex loads project config only after the user explicitly trusts the project.
+# Configure optional MCP servers in native [mcp_servers.name] TOML, not .mcp.json.
+# Reference: https://learn.chatgpt.com/docs/config-file/config-basic

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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