nitm-ai-dev-toolkit 3.0.22 → 4.0.0

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

@@ -2,12 +2,31 @@
 
 Analyze the project structure and customize AI instruction templates for this codebase.
 
+## 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.
+
 ## Usage
 
 ```
 /bootstrap
 ```
 
+**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.
+
+### Harness selection and native Codex targets
+
+- Identify the actual running harness from session/runtime information or ask the user which harnesses they use. Directory presence alone is not evidence: the default installer scaffolds every supported harness.
+- Codex uses `AGENTS.md` (including more-specific nested instructions) and `.agents/skills/*/SKILL.md` natively. Read linked standards when relevant; `.github/instructions/` and Claude snippets are not automatically loaded as Codex rules.
+- `.codex/config.toml` is an optional, comment-only project config. 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.
+- Calibrate Codex by customizing project instructions and skills, not by translating 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.
+- 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, `AGENTS.md`, `.agents/skills/`, and `.codex/config.toml` are the native targets. `--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. The remaining tool-specific examples below are conditional.
+
 ## Process
 
 > **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.
@@ -192,11 +211,15 @@ Present inferred values and ask for missing ones:
 
 ### Step 4: Template Customization
 
+For confirmed OpenCode use, complete the Ponytail pre-activation cleanup below before customizing OpenCode files or marking the migration complete.
+
 Replace placeholders in all template files:
 
 **Files to Update:**
 
 - `AGENTS.md` - Project context and patterns (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` - Copilot configuration
 - `.github/instructions/*.instructions.md` - Context instructions
 - `.github/prompts/*.prompt.md` - Reusable prompts
@@ -207,58 +230,35 @@ Replace placeholders in all template files:
 - `.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` - Toolkit version tracking
 
-**⚠️ OpenCode `opencode.jsonc` Schema Validation:**
-
-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.
-
-**Supported top-level keys:**
-
-| Key                  | Purpose                                 |
-| -------------------- | --------------------------------------- |
-| `$schema`            | Schema reference (always include)       |
-| `instructions`       | Array of instruction file paths/globs   |
-| `skills`             | Skill folder paths and URLs             |
-| `agent`              | Custom agent configurations             |
-| `default_agent`      | Default agent name                      |
-| `model`              | Model ID (provider/model format)        |
-| `small_model`        | Lightweight model for title generation  |
-| `provider`           | Provider configurations and API keys    |
-| `mcp`                | MCP server configurations               |
-| `tools`              | Enable/disable tools                    |
-| `permission`         | Tool permission rules                   |
-| `lsp`                | LSP server configuration                |
-| `formatter`          | Code formatter configuration            |
-| `server`             | Server settings (port, hostname, CORS)  |
-| `shell`              | Default shell for terminal              |
-| `command`            | Custom command definitions              |
-| `plugin`             | Plugin list                             |
-| `watcher`            | File watcher ignore patterns            |
-| `snapshot`           | Enable/disable snapshot tracking        |
-| `share`              | Sharing behavior (manual/auto/disabled) |
-| `autoupdate`         | Auto-update settings                    |
-| `compaction`         | Context compaction settings             |
-| `attachment`         | Image attachment limits                 |
-| `logLevel`           | Log level (DEBUG/INFO/WARN/ERROR)       |
-| `disabled_providers` | Providers to disable                    |
-| `enabled_providers`  | Allowlist of providers                  |
-| `tool_output`        | Tool output truncation thresholds       |
-| `enterprise`         | Enterprise URL                          |
-| `experimental`       | Experimental features                   |
-
-**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).
+**OpenCode native V2 checks (only for confirmed OpenCode use):**
+
+Follow the 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) guides, not a V1 API/schema fetch. The published schema URL may still describe V1; do not use it to reject native plural keys.
+
+- After the version preflight passes, use `agents` with JSON `system` or Markdown bodies; `request.body.temperature`; ordered `permissions` rules (`action`, `resource`, `effect`; `shell`/`subagent`; last match wins); `commands` with `subagent`; `plugins` with `{ "package": "…", "options": {} }`; `skills` as directory-path arrays; `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`.
+- Back up V1; native-converted files are incompatible with V1. Merge, don't clobber models/providers/user-global plugins. With approval only, merge pinned `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally. Slim's separate strict schema retains its own `prompt`, `permission`, and `variant`; do not host-migrate it or upgrade the separate external starter silently.
+- Templates register the author's native V2 package `@dietrichgebert/ponytail@4.12.0` locally; no local Ponytail source is bundled or ported. Keep `opentmux` commented as V1-only. Native local discovery needs no duplicate registration; do not introduce API ports or bridges or claim tested runtime integration.
+- Config `instructions` entries are accepted but not loaded; ambient `AGENTS.md` works. `@refs` are ordinary text: explicitly read referenced snippet docs. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`, but use project lint/typecheck/compiler commands (no current V2 LSP tools/diagnostics).
+- `--env opencode` supplies minimal shared references without activating other harnesses. Activate on the next run/restart and report only checks actually run using installed V2; scaffold/placeholder checks are not runtime validation. Publishing 4.0.0 has not been executed.
+
+**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.
@@ -281,7 +281,7 @@ Use the first available method when interacting with the issue tracker:
 
 **If Jira:**
 
-1. **MCP server** (preferred): `mcp_atlassian_atl_*` tools (configured in `.mcp.json`)
+1. **MCP server** (preferred): use the actual runtime tool names (`.mcp.json` for Claude; native `[mcp_servers.name]` TOML for Codex)
 2. **CLI fallback**: [`acli`](https://developer.atlassian.com/cloud/acli/reference/commands/) — `acli jira auth login --web`
 
 **If GitHub Issues:**
@@ -291,7 +291,7 @@ Use the first available method when interacting with the issue tracker:
 
 **If Linear:**
 
-1. **MCP server** (preferred): `mcp_linear_*` tools (configured in `.mcp.json`)
+1. **MCP server** (preferred): use the actual runtime tool names (`.mcp.json` for Claude; native `[mcp_servers.name]` TOML for Codex)
 2. **CLI fallback**: [`linear`](https://github.com/linear/linear-cli) — `linear auth` or set `LINEAR_API_KEY`
 
 See the `issue-tracker` and relevant CLI skills for detailed setup and usage examples.
@@ -405,7 +405,9 @@ Customize agent definition files (`.github/agents/` and `.cursor/agents/`) based
 
 #### 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:** apply the harness-selection guidance above. Do not generate Codex 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:
 
@@ -420,22 +422,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 in the confirmation table, then proceed only on `(Y/n)`.
@@ -468,27 +470,28 @@ Detected stack: {{LANGUAGE}} / {{FRAMEWORK}}
 | Agent | Platform | Current | Calibrated |
 |-------|----------|---------|------------|
 | Planner | github-copilot | `read, search, edit, runInTerminal, terminalLastCommand` | `read, search, edit, runInTerminal, terminalLastCommand` |
-| Planner | opencode | `edit: allow, bash: allow` | `edit: allow, bash: allow` |
+| Planner | opencode | Inspect ordered rules | `permissions: [{action: edit, resource: "*", effect: allow}, {action: shell, resource: "*", effect: allow}]` |
 | Planner | claude | `Read, Grep, Write, Bash(*)` | `Read, Grep, Write, Bash(*)` |
 | Documenter | claude | `Read, Grep, Write, Edit, Bash(*)` | `Read, Grep, Write, Edit, Bash(*)` |
-| Documenter | opencode | `edit: allow, bash: allow` | `edit: allow, bash: allow` |
+| Documenter | opencode | Inspect ordered rules | `permissions: [{action: edit, resource: "*", effect: allow}, {action: shell, resource: "*", effect: allow}]` |
 | Researcher | claude | `Read, Grep` | `Read, Grep` |
 | Reviewer | claude | `Read, Grep, Bash(*)` | `Read, Grep, Bash(*)` |
-| Reviewer | opencode | `edit: deny, bash: allow` | `edit: deny, bash: allow` |
+| Reviewer | opencode | Inspect ordered rules | `permissions: [{action: edit, resource: "*", effect: deny}, {action: shell, resource: "*", effect: allow}]` |
 
 Apply agent customizations? (Y/n)
 ```
 
 ### Step 6: 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 skill 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 `.codex/`, `.claude/`, `.cursor/`, or `.github/` proves a harness is installed or in use; the toolkit scaffolds all by default. If runtime evidence is unavailable, ask rather than defaulting to an agent.
 
 **Build the agent flags string:**
-- For each detected agent, add `-a <agent>` to the command
-- Example: If `.cursor/` and `.github/` exist → use `-a cursor -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 Codex only → `{{AGENT_FLAGS}}` becomes `-a codex` (supported by the skills installer)
+- Example: confirmed Cursor and Copilot → `-a cursor -a github-copilot`
+- If no harness is confirmed, ask before installing (or let the CLI prompt); do not infer from scaffold directories
 
 ### Step 7: AI Agent Skills Recommendation
 
@@ -553,13 +556,13 @@ This template bundles issue tracker skills in `.agents/skills/`. Verify the corr
 | 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 '*' --agent github-copilot cursor`                                                        |
-| TypeScript         | `pproenca/dot-skills` (typescript)    | `npx -y skills add {{AGENT_FLAGS}} pproenca/dot-skills --skill '*' --agent github-copilot cursor`                                                |
-| Advanced Types     | `wshobson/agents` (ts-advanced-types) | `npx -y skills add {{AGENT_FLAGS}} wshobson/agents --skill '*' --agent github-copilot cursor`                                                    |
+| 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 {{AGENT_FLAGS}} 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.
 
 **Present Recommendation:**
 
@@ -574,9 +577,9 @@ Based on your project ({{FRAMEWORK}}/{{LANGUAGE}}):
 ### Core Skills (recommended for all projects)
 
 ```bash
-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}})
@@ -592,7 +595,7 @@ npx -y skills add {{AGENT_FLAGS}} softaworks/agent-toolkit --skill '*' --agent g
 ### Framework-Specific Skills
 
 ```bash
-npx -y skills add {{FRAMEWORK_SKILL_REPO}} --skill '*' --agent github-copilot cursor
+npx -y skills add {{AGENT_FLAGS}} {{FRAMEWORK_SKILL_REPO}} --skill '*'
 ```
 
 ### Install All?
@@ -604,11 +607,13 @@ Would you like to install these skills now? (Y/n)
 **On Confirmation:**
 
 - Run skill installation commands
-- Skills installed to `.github/skills/{skill-name}/` (by skill name, not org/repo)
+- Verify the installer's reported paths; Codex uses `.agents/skills/{skill-name}/` (by skill name, not org/repo)
 - Update `AGENTS.md` to reference installed skills
 
 ### Step 7: Completion Report
 
+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.
+
 ```markdown
 ## ✅ Bootstrap Complete!
 
@@ -623,27 +628,19 @@ Would you like to install these skills now? (Y/n)
 
 ### Updated Files
 
-- [x] AGENTS.md (with {{LANGUAGE}} patterns)
-- [x] .github/copilot-instructions.md
-- [x] .github/instructions/\*.instructions.md
-- [x] .cursor/rules/\*.mdc
-- [x] .cursor/commands/\*.md
-- [x] .github/prompts/\*.prompt.md
-- [x] .claude/rules/\*.md (thin wrappers)
-- [x] .claude/rules-snippets/\*.md (rules content)
-- [x] .claude/prompt-snippets/\*.md (prompt content)
-- [x] .claude/agents-snippets/\*.md (agent content)
-- [x] .opencode/opencode.jsonc
-- [x] .opencode/commands/\*.md
-- [x] .opencode/rules/\*.md
-- [x] .opencode/agents/\*.md
-- [x] .toolkit-version
+- AGENTS.md (with {{LANGUAGE}} patterns; 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)
 
 ### Installed Skills
 
-- [x] obra/superpowers - Development workflow
-- [x] trailofbits/skills - Security & quality
-- [x] {{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
 
@@ -662,7 +659,7 @@ After bootstrap completion, review all installed skills for relevance:
 **Skill Audit Process:**
 
 1. **Inventory 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
    - List all installed skill names and descriptions
    - Check each skill's SKILL.md for its purpose
 
@@ -743,7 +740,9 @@ Kept {{N}} relevant skills:
 
 Verify that all necessary instruction files exist and are properly configured:
 
-**Required Instruction Files:**
+For Codex, verify `AGENTS.md`, relevant nested `AGENTS.md` files, and `.agents/skills/*/SKILL.md`; parse `.codex/config.toml` as TOML and confirm it retains inherited defaults. The Copilot-specific audit below applies only when Copilot is confirmed in use; do not create Copilot instructions merely to satisfy a Codex audit.
+
+**Required Copilot Instruction Files (only if Copilot is confirmed in use):**
 
 | File                          | Purpose                         | Location                |
 | ----------------------------- | ------------------------------- | ----------------------- |
@@ -754,10 +753,10 @@ Verify that all necessary instruction files exist and are properly configured:
 | `testing.instructions.md`     | Testing conventions             | `.github/instructions/` |
 | `api.instructions.md`         | API conventions (if applicable) | `.github/instructions/` |
 
-**Detection & Validation:**
+**Copilot Detection & Validation Example (only if confirmed in use):**
 
 ```markdown
-## 📋 Instruction Files Audit
+## 📋 Copilot Instruction Files Audit — confirmed Copilot use only
 
 ### ✅ Found ({{N}} files)
 
@@ -783,18 +782,18 @@ Verify that all necessary instruction files exist and are properly configured:
 | `.claude/prompt-snippets/` | Prompt content (source of truth)    | ✓      |
 | `.claude/agents-snippets/` | Agent definitions (source of truth) | ✓      |
 
-### 📝 Create Missing Instruction Files?
+### 📝 Create Missing Copilot Instruction Files? (confirmed Copilot use only)
 
 These files would help AI understand your project's conventions.
 
 Create recommended instructions? (Y/n)
 ```
 
-**On Confirmation:**
+**On Confirmation (only if Copilot is confirmed in use):**
 
-Generate missing instruction files with appropriate templates:
+Generate missing Copilot instruction files with appropriate templates; skip creation for a Codex-only audit even when shared reference standards are present:
 
-**Example: Framework Instruction Template**
+**Copilot Example: Framework Instruction Template (only if confirmed in use)**
 
 ```markdown
 ---
@@ -848,7 +847,7 @@ Key packages:
 - [Project README](README.md)
 ```
 
-**Example: Testing Instruction Template**
+**Copilot Example: Testing Instruction Template (only if confirmed in use)**
 
 ```markdown
 ---
@@ -899,10 +898,10 @@ Available test utilities:
 - {{TESTING_ANTIPATTERN_2}}
 ```
 
-**Post-Creation Report:**
+**Copilot Post-Creation Report Example (only if confirmed in use and files were created):**
 
 ```markdown
-## ✅ Instruction Files Created
+## ✅ Copilot Instruction Files Created — confirmed Copilot use only
 
 Created {{N}} new instruction files:
 
@@ -922,18 +921,20 @@ All instruction files are automatically loaded by GitHub Copilot when editing ma
 
 ### Step 10: Final Verification
 
+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.
+
 ```markdown
-## ✅ Bootstrap Complete & Verified!
+## Bootstrap Verification Report
 
 ### Summary
 
 | Category                  | Count | Status |
 | ------------------------- | ----- | ------ |
-| Files updated             | {{N}} | ✓      |
-| Skills installed          | {{N}} | ✓      |
-| Skills removed            | {{N}} | ✓      |
-| Instruction files created | {{N}} | ✓      |
-| Project management        | 1     | ✓      |
+| Files updated             | {{N}} | Report actual result |
+| Skills installed          | {{N}} | Report actual result |
+| Skills removed            | {{N}} | Report actual result |
+| Instruction files created | {{N}} | Report actual result |
+| Project management        | 1     | Report actual result or not configured |
 
 ### Project Management Configuration
 
@@ -941,7 +942,7 @@ All instruction files are automatically loaded by GitHub Copilot when editing ma
 **URL:** {{PM_URL}} _(if applicable)_
 **Project Key:** {{PROJECT_KEY}} _(if applicable)_
 **Issue Format:** `{{PM_ISSUE_KEY}}`
-**Location:** Root AGENTS.md and copilot-instructions.md
+**Location:** Root AGENTS.md; include copilot-instructions.md only if Copilot is confirmed and the file was updated
 
 ### Skill Inventory
 
@@ -953,7 +954,7 @@ All instruction files are automatically loaded by GitHub Copilot when editing ma
 
 ### Instruction Files
 
-**Active Instructions ({{N}}):**
+**Inspected Instructions ({{N}}; report runtime loading separately):**
 
 - {{INSTRUCTION_1}}
 - {{INSTRUCTION_2}}
@@ -961,25 +962,28 @@ All instruction files are automatically loaded by GitHub Copilot when editing ma
 
 ### Quality Checks
 
-- [x] All placeholders replaced
-- [x] Framework patterns match detected stack
-- [x] No duplicate skills
-- [x] AGENTS.md configured
-- [x] Instruction files cover all frameworks
-- [x] Skills align with tech stack
-- [x] Snippet directories created
-- [x] Thin wrappers reference correct snippets
-- [x] .opencode/ directory configured
-- [x] .toolkit-version file created
-
-### Your Project is Ready! 🎉
-
-GitHub Copilot and Cursor will now understand:
-
-- Your project structure
-- Framework-specific patterns
-- Custom conventions
-- Testing strategies
+- [ ] All placeholders replaced (list any remaining)
+- [ ] Framework patterns match detected stack
+- [ ] No duplicate skills
+- [ ] AGENTS.md configured
+- [ ] Instruction files cover applicable frameworks
+- [ ] Skills align with tech stack
+- [ ] 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 |
+| ------ | --------------- | ------ |
+| `AGENTS.md` and relevant nested files | Contents 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:
 

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