oh-my-codex 0.10.2 → 0.10.4

package/scripts/smoke-packed-install.mjs

@@ -1,22 +1,147 @@
 import { createServer } from 'node:http';
-import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
 import { chmodSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { pathToFileURL } from 'node:url';
 
+const REQUIRED_NODE_MODULE_MARKERS = [
+  join('typescript', 'package.json'),
+  join('@iarna', 'toml', 'package.json'),
+  join('@modelcontextprotocol', 'sdk', 'package.json'),
+  join('zod', 'package.json'),
+];
+
 function usage() {
   return [
-    'Usage: node scripts/smoke-packed-install.mjs [--release-assets-dir <dir>]',
+    'Usage: node scripts/smoke-packed-install.mjs [--release-assets-dir <dir>] [--require-no-fallback]',
     '',
     'Creates an npm tarball, installs it into an isolated prefix, and smoke tests the installed omx CLI.',
     'When --release-assets-dir is provided, native hydration is also exercised using a local HTTP server.',
   ].join('\n');
 }
 
+function hasNodeModulesPath(nodeModulesPath) {
+  try {
+    lstatSync(nodeModulesPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function hasUsableNodeModules(repoRoot) {
+  return REQUIRED_NODE_MODULE_MARKERS.every((marker) => existsSync(join(repoRoot, 'node_modules', marker)));
+}
+
+export function resolveGitCommonDir(cwd, gitRunner = spawnSync) {
+  const result = gitRunner('git', ['rev-parse', '--git-common-dir'], {
+    cwd,
+    encoding: 'utf-8',
+  });
+  if (result.status !== 0) {
+    return null;
+  }
+  const value = (result.stdout || '').trim();
+  if (!value) {
+    return null;
+  }
+  return resolve(cwd, value);
+}
+
+export function resolveReusableNodeModulesSource(repoRoot, gitRunner = spawnSync) {
+  const commonDir = resolveGitCommonDir(repoRoot, gitRunner);
+  if (!commonDir || basename(commonDir) !== '.git') {
+    return null;
+  }
+
+  const primaryRepoRoot = dirname(commonDir);
+  if (resolve(primaryRepoRoot) === resolve(repoRoot)) {
+    return null;
+  }
+
+  if (!hasUsableNodeModules(primaryRepoRoot)) {
+    return null;
+  }
+
+  return join(primaryRepoRoot, 'node_modules');
+}
+
+function formatCommandFailure(cmd, args, result) {
+  return [
+    `Command failed: ${cmd} ${args.join(' ')}`,
+    result.stdout?.trim() ? `stdout:\n${result.stdout.trim()}` : '',
+    result.stderr?.trim() ? `stderr:\n${result.stderr.trim()}` : '',
+  ].filter(Boolean).join('\n\n');
+}
+
+export function ensureRepoDependencies(repoRoot, options = {}) {
+  const {
+    gitRunner = spawnSync,
+    install = (cwd) => {
+      const result = spawnSync('npm', ['ci'], {
+        cwd,
+        encoding: 'utf-8',
+        stdio: 'pipe',
+      });
+      if (result.status !== 0) {
+        throw new Error(formatCommandFailure('npm', ['ci'], result));
+      }
+    },
+    remove = rmSync,
+    symlink = symlinkSync,
+    log = () => {},
+    platformName = process.platform,
+  } = options;
+
+  if (hasUsableNodeModules(repoRoot)) {
+    return {
+      strategy: 'existing',
+      nodeModulesPath: join(repoRoot, 'node_modules'),
+    };
+  }
+
+  const targetNodeModules = join(repoRoot, 'node_modules');
+  if (hasNodeModulesPath(targetNodeModules)) {
+    remove(targetNodeModules, { recursive: true, force: true });
+  }
+
+  const reusableNodeModules = resolveReusableNodeModulesSource(repoRoot, gitRunner);
+  if (reusableNodeModules) {
+    symlink(reusableNodeModules, targetNodeModules, platformName === 'win32' ? 'junction' : 'dir');
+    log(`[smoke:packed-install] Reusing node_modules from ${reusableNodeModules}`);
+    return {
+      strategy: 'symlink',
+      nodeModulesPath: targetNodeModules,
+      sourceNodeModulesPath: reusableNodeModules,
+    };
+  }
+
+  log('[smoke:packed-install] Installing repo dependencies with npm ci');
+  install(repoRoot);
+  return {
+    strategy: 'installed',
+    nodeModulesPath: targetNodeModules,
+  };
+}
+
+export function hasSparkShellFallbackBanner(stderr) {
+  return /GLIBC-incompatible native sidecar detected/i.test(String(stderr || ''));
+}
+
 function parseArgs(argv) {
   let releaseAssetsDir;
+  let requireNoFallback = false;
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index];
     if (token === '--help' || token === '-h') {
@@ -30,9 +155,13 @@ function parseArgs(argv) {
       index += 1;
       continue;
     }
+    if (token === '--require-no-fallback') {
+      requireNoFallback = true;
+      continue;
+    }
     throw new Error(`Unknown argument: ${token}\n${usage()}`);
   }
-  return { releaseAssetsDir };
+  return { releaseAssetsDir, requireNoFallback };
 }
 
 function run(cmd, args, options = {}) {
@@ -42,11 +171,7 @@ function run(cmd, args, options = {}) {
     ...options,
   });
   if (result.status !== 0) {
-    throw new Error([
-      `Command failed: ${cmd} ${args.join(' ')}`,
-      result.stdout?.trim() ? `stdout:\n${result.stdout.trim()}` : '',
-      result.stderr?.trim() ? `stderr:\n${result.stderr.trim()}` : '',
-    ].filter(Boolean).join('\n\n'));
+    throw new Error(formatCommandFailure(cmd, args, result));
   }
   return result;
 }
@@ -153,7 +278,7 @@ export function rewriteManifestDownloadUrls(manifestPath, baseUrl) {
 }
 
 async function main() {
-  const { releaseAssetsDir } = parseArgs(process.argv.slice(2));
+  const { releaseAssetsDir, requireNoFallback } = parseArgs(process.argv.slice(2));
   const repoRoot = process.cwd();
   const tempRoot = mkdtempSync(join(tmpdir(), 'omx-packed-install-'));
   const prefixDir = join(tempRoot, 'prefix');
@@ -166,6 +291,10 @@ async function main() {
   let server;
   let tarballPath;
   try {
+    ensureRepoDependencies(repoRoot, {
+      log: (message) => console.log(message),
+    });
+
     const pack = run('npm', ['pack', '--json'], { cwd: repoRoot });
     const packOutput = JSON.parse(pack.stdout.slice(pack.stdout.indexOf('[')));
     const tarballName = packOutput[0]?.filename;
@@ -192,6 +321,9 @@ async function main() {
       };
 
       const sparkshell = run(omxPath, ['sparkshell', 'node', '--version'], { cwd: repoRoot, env });
+      if (requireNoFallback && hasSparkShellFallbackBanner(sparkshell.stderr)) {
+        throw new Error(`Unexpected sparkshell fallback stderr:\n${sparkshell.stderr}`);
+      }
       if (!/v\d+\./.test(sparkshell.stdout)) {
         throw new Error(`Unexpected sparkshell stdout:\n${sparkshell.stdout}`);
       }

package/skills/ai-slop-cleaner/SKILL.md

@@ -22,6 +22,12 @@ Use this skill when:
 - Keep using inspection, tests, diagnostics, and verification until the cleanup is grounded.
 - Proceed automatically through clear, reversible cleanup steps; ask only when a choice materially changes scope or behavior.
 
+## Scoped File Lists and Ralph Workflow
+
+- This skill can accept a **file list scope** instead of a whole feature area.
+- When the caller provides a changed-files list (for example, Ralph session-owned edits), keep the cleanup strictly bounded to those files.
+- In the **Ralph workflow**, the mandatory deslop pass should run this skill on Ralph's changed files only, in standard mode unless the caller explicitly requests otherwise.
+
 ## Procedure
 
 1. **Lock behavior with regression tests first**
@@ -32,6 +38,7 @@ Use this skill when:
 2. **Create a cleanup plan before code**
    - List the specific smells to remove
    - Bound the pass to the requested files/scope
+   - If a file list scope is provided, keep the pass restricted to that changed-files list
    - Order fixes from safest/highest-signal to riskiest
    - Do not start coding until the cleanup plan is explicit
 

package/skills/deep-interview/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: deep-interview
 description: Socratic deep interview with mathematical ambiguity gating before execution
-argument-hint: "<idea or vague description>"
+argument-hint: "[--quick|--standard|--deep] [--autoresearch] <idea or vague description>"
 ---
 
 <Purpose>
@@ -30,8 +30,13 @@ Execution quality is usually bottlenecked by intent clarity, not just missing im
 - **Quick (`--quick`)**: fast pre-PRD pass; target threshold `<= 0.30`; max rounds 5
 - **Standard (`--standard`, default)**: full requirement interview; target threshold `<= 0.20`; max rounds 12
 - **Deep (`--deep`)**: high-rigor exploration; target threshold `<= 0.15`; max rounds 20
+- **Autoresearch (`--autoresearch`)**: same interview rigor as Standard, but specialized for `omx autoresearch` launch readiness and `.omx/specs/` mission/sandbox artifact handoff
 
 If no flag is provided, use **Standard**.
+
+<Mode_Flags>
+- **`--autoresearch`**: switch the interview into autoresearch-intake mode for `omx autoresearch` handoff. In this mode, the interview should converge on a launch-ready research mission, write canonical artifacts under `.omx/specs/`, and preserve the explicit `refine further` vs `launch` boundary for downstream CLI intake.
+</Mode_Flags>
 </Depth_Profiles>
 
 <Execution_Policy>
@@ -194,6 +199,30 @@ Spec should include:
 - Technical context findings
 - Full or condensed transcript
 
+### Autoresearch specialization
+
+When the clarified task is specifically about `omx autoresearch`, or the skill is invoked with `--autoresearch`, keep the interview domain-specific and emit launch-consumable artifacts without skipping clarification.
+
+- **Accepted seed inputs:** `topic`, `evaluator`, `keep-policy`, `slug`, existing mission draft text, and prior evaluator examples/templates
+- **Required interview focus:** mission clarity, evaluator readiness, keep policy, slug/session naming, and whether the draft is ready to launch now or should refine further
+- **Canonical artifact path:** `.omx/specs/deep-interview-autoresearch-{slug}.md`
+- **Launch artifact bundle:** `.omx/specs/autoresearch-{slug}/mission.md`, `.omx/specs/autoresearch-{slug}/sandbox.md`, and `.omx/specs/autoresearch-{slug}/result.json`
+- **Launch artifact directory:** `.omx/specs/autoresearch-{slug}/`
+- **Required artifact sections:**
+  - `Mission Draft`
+  - `Evaluator Draft`
+  - `Launch Readiness`
+  - `Seed Inputs`
+  - `Confirmation Bridge`
+- **Required launch artifacts under `.omx/specs/autoresearch-{slug}/`:**
+  - `mission.md`
+  - `sandbox.md`
+  - `result.json`
+- **Launch-readiness rule:** mark the draft as **not launch-ready** while the evaluator command still contains placeholder markers such as `<...>`, `TODO`, `TBD`, `REPLACE_ME`, `CHANGEME`, or `your-command-here`
+- **Structured result contract:** `result.json` should point to the draft + mission/sandbox artifacts and carry the finalized `topic`, `evaluatorCommand`, `keepPolicy`, `slug`, `launchReady`, and `blockedReasons` fields so `omx autoresearch` can consume it directly
+- **Confirmation bridge:** after artifact generation, offer at least `refine further` and `launch`; do not launch detached tmux until the user explicitly confirms `launch`
+- **Handoff rule:** downstream execution must preserve the clarified mission intent, evaluator expectations, decision boundaries, and launch-readiness status from this artifact rather than bypassing the draft review step
+
 ## Phase 5: Execution Bridge
 
 Present execution options after artifact generation using explicit handoff contracts. Treat the deep-interview spec as the current requirements source of truth and preserve intent, non-goals, decision boundaries, acceptance criteria, and any residual-risk warnings across the handoff.

package/skills/omx-setup/SKILL.md

@@ -42,8 +42,8 @@ Supported setup flags (current implementation):
 - Local project orchestration file is `./AGENTS.md` (project root).
 - If `AGENTS.md` exists and `--force` is not used, interactive TTY runs ask whether to overwrite. Non-interactive runs preserve the file.
 - Scope targets:
-  - `user`: user directories (`~/.codex`, `~/.agents/skills`, `~/.omx/agents`)
-  - `project`: local directories (`./.codex`, `./.agents/skills`, `./.omx/agents`)
+  - `user`: user directories (`~/.codex`, `~/.codex/skills`, `~/.omx/agents`)
+  - `project`: local directories (`./.codex`, `./.codex/skills`, `./.omx/agents`)
 - If persisted scope is `project`, `omx` launch automatically uses `CODEX_HOME=./.codex` unless user explicitly overrides `CODEX_HOME`.
 - With `--force`, AGENTS overwrite may still be skipped if an active OMX session is detected (safety guard).
 - Legacy persisted scope values (`project-local`) are automatically migrated to `project` with a one-time warning.

package/skills/ralph/SKILL.md

@@ -78,6 +78,15 @@ Complex tasks often fail silently: partial implementations get declared "done",
    - Standard changes: STANDARD tier (architect role)
    - >20 files or security/architectural changes: THOROUGH tier (architect role)
    - Ralph floor: always at least STANDARD, even for small changes
+7.5 **Mandatory Deslop Pass**:
+   - After Step 7 passes, run `oh-my-codex:ai-slop-cleaner` on **all files changed during the Ralph session**.
+   - Scope the cleaner to **changed files only**; do not widen the pass beyond Ralph-owned edits.
+   - Run the cleaner in **standard mode** (not `--review`).
+   - If the prompt contains `--no-deslop`, skip Step 7.5 entirely and proceed with the most recent successful verification evidence.
+7.6 **Regression Re-verification**:
+   - After the deslop pass, re-run all tests/build/lint and read the output to confirm they still pass.
+   - If post-deslop regression fails, roll back cleaner changes or fix and retry. Then rerun Step 7.5 and Step 7.6 until the regression is green.
+   - Do not proceed to completion until post-deslop regression is green (unless `--no-deslop` explicitly skipped the deslop pass).
 8. **On approval**: Run `/cancel` to cleanly exit and clean up all state files
 9. **On rejection**: Fix the issues raised, then re-verify at the same tier
 </Steps>
@@ -170,6 +179,8 @@ Why bad: These are independent tasks that should run in parallel, not sequential
 - [ ] Fresh build output shows success
 - [ ] lsp_diagnostics shows 0 errors on affected files
 - [ ] Architect verification passed (STANDARD tier minimum)
+- [ ] ai-slop-cleaner pass completed on changed files (or --no-deslop specified)
+- [ ] Post-deslop regression tests pass
 - [ ] `/cancel` run for clean state cleanup
 </Final_Checklist>
 
@@ -181,6 +192,10 @@ When the user provides the `--prd` flag, initialize a Product Requirements Docum
 ### Detecting PRD Mode
 Check if `{{PROMPT}}` contains `--prd` or `--PRD`.
 
+### Detecting `--no-deslop`
+Check if `{{PROMPT}}` contains `--no-deslop`.
+If `--no-deslop` is present, skip the deslop pass entirely after Step 7 and continue using the latest successful pre-deslop verification evidence.
+
 ### Visual Reference Flags (Optional)
 Ralph execution supports visual reference flags for screenshot tasks:
 - Repeatable image inputs: `-i <image-path>` (can be used multiple times)

package/skills/skill/SKILL.md

@@ -15,19 +15,19 @@ Meta-skill for managing oh-my-codex skills via CLI-like commands.
 Show all local skills organized by scope.
 
 **Behavior:**
-1. Scan user skills at `~/.agents/skills/`
-2. Scan project skills at `.agents/skills/`
+1. Scan user skills at `~/.codex/skills/`
+2. Scan project skills at `.codex/skills/`
 3. Parse YAML frontmatter for metadata
 4. Display in organized table format:
 
 ```
-USER SKILLS (~/.agents/skills/):
+USER SKILLS (~/.codex/skills/):
 | Name              | Triggers           | Quality | Usage | Scope |
 |-------------------|--------------------|---------|-------|-------|
 | error-handler     | fix, error         | 95%     | 42    | user  |
 | api-builder       | api, endpoint      | 88%     | 23    | user  |
 
-PROJECT SKILLS (.agents/skills/):
+PROJECT SKILLS (.codex/skills/):
 | Name              | Triggers           | Quality | Usage | Scope   |
 |-------------------|--------------------|---------|-------|---------|
 | test-runner       | test, run          | 92%     | 15    | project |
@@ -51,8 +51,8 @@ Interactive wizard for creating a new skill.
 4. **Ask for argument hint** (optional)
    - Example: "<file> [options]"
 5. **Ask for scope:**
-   - `user` → `~/.agents/skills/<name>/SKILL.md`
-   - `project` → `.agents/skills/<name>/SKILL.md`
+   - `user` → `~/.codex/skills/<name>/SKILL.md`
+   - `project` → `.codex/skills/<name>/SKILL.md`
 6. **Create skill file** with template:
 
 ```yaml
@@ -105,7 +105,7 @@ Triggers (comma-separated): log, logger, logging
 Argument hint (optional): <level> [message]
 Scope (user/project): user
 
-✓ Created skill at ~/.agents/skills/custom-logger/SKILL.md
+✓ Created skill at ~/.codex/skills/custom-logger/SKILL.md
 → Edit with: /skill edit custom-logger
 ```
 
@@ -117,13 +117,13 @@ Remove a skill by name.
 
 **Behavior:**
 1. **Search for skill** in both scopes:
-   - `~/.agents/skills/<name>/SKILL.md`
-   - `.agents/skills/<name>/SKILL.md`
+   - `~/.codex/skills/<name>/SKILL.md`
+   - `.codex/skills/<name>/SKILL.md`
 2. **If found:**
    - Display skill info (name, description, scope)
    - **Ask for confirmation:** "Delete '<name>' skill from <scope>? (yes/no)"
 3. **If confirmed:**
-   - Delete entire skill directory (e.g., `~/.agents/skills/<name>/`)
+   - Delete entire skill directory (e.g., `~/.codex/skills/<name>/`)
    - Report: "✓ Removed skill '<name>' from <scope>"
 4. **If not found:**
    - Report: "✗ Skill '<name>' not found in user or project scope"
@@ -135,7 +135,7 @@ Remove a skill by name.
 User: /skill remove old-logger
 Assistant: Found skill 'old-logger' in user scope:
   Description: Legacy logging utility
-  Scope: user (~/.agents/skills/)
+  Scope: user (~/.codex/skills/)
 
 Delete 'old-logger' skill? (yes/no)
 
@@ -251,13 +251,13 @@ Show detailed information about a skill.
 
 ```
 Skill: custom-logger
-Scope: user (~/.agents/skills/custom-logger/)
+Scope: user (~/.codex/skills/custom-logger/)
 Description: Enhanced logging with structured output
 Triggers: log, logger, logging
 Argument Hint: <level> [message]
 Quality: 95% (if available)
 Usage Count: 42 times (if available)
-File Path: /home/user/.agents/skills/custom-logger/SKILL.md
+File Path: /home/user/.codex/skills/custom-logger/SKILL.md
 
 --- FULL CONTENT ---
 [entire markdown content]
@@ -272,7 +272,7 @@ Assistant: Skill: custom-logger
 Scope: user
 Description: Enhanced logging with structured output
 Triggers: log, logger, logging
-File: ~/.agents/skills/custom-logger/SKILL.md
+File: ~/.codex/skills/custom-logger/SKILL.md
 
 --- CONTENT ---
 # Custom Logger Skill
@@ -290,8 +290,8 @@ Sync skills between user and project scopes.
 
 **Behavior:**
 1. **Scan both scopes:**
-   - User skills: `~/.agents/skills/`
-   - Project skills: `.agents/skills/`
+   - User skills: `~/.codex/skills/`
+   - Project skills: `.codex/skills/`
 2. **Compare and categorize:**
    - User-only skills (not in project)
    - Project-only skills (not in user)
@@ -339,7 +339,7 @@ Assistant: Found 5 user-only skills and 2 project-only skills.
 
 Copy 'error-handler' from user to project? (yes/no/skip)
 User: yes
-Assistant: ✓ Copied 'error-handler' to .agents/skills/
+Assistant: ✓ Copied 'error-handler' to .codex/skills/
 
 Copy 'api-builder' from user to project? (yes/no/skip)
 User: skip
@@ -360,7 +360,7 @@ First, check if skill directories exist and create them if needed:
 
 ```bash
 # Check and create user-level skills directory
-USER_SKILLS_DIR="$HOME/.agents/skills"
+USER_SKILLS_DIR="$HOME/.codex/skills"
 if [ -d "$USER_SKILLS_DIR" ]; then
   echo "User skills directory exists: $USER_SKILLS_DIR"
 else
@@ -369,7 +369,7 @@ else
 fi
 
 # Check and create project-level skills directory
-PROJECT_SKILLS_DIR=".agents/skills"
+PROJECT_SKILLS_DIR=".codex/skills"
 if [ -d "$PROJECT_SKILLS_DIR" ]; then
   echo "Project skills directory exists: $PROJECT_SKILLS_DIR"
 else
@@ -384,15 +384,15 @@ Scan both directories and show a comprehensive inventory:
 
 ```bash
 # Scan user-level skills
-echo "=== USER-LEVEL SKILLS (~/.agents/skills/) ==="
-if [ -d "$HOME/.agents/skills" ]; then
-  USER_COUNT=$(find "$HOME/.agents/skills" -name "*.md" 2>/dev/null | wc -l)
+echo "=== USER-LEVEL SKILLS (~/.codex/skills/) ==="
+if [ -d "$HOME/.codex/skills" ]; then
+  USER_COUNT=$(find "$HOME/.codex/skills" -name "*.md" 2>/dev/null | wc -l)
   echo "Total skills: $USER_COUNT"
 
   if [ $USER_COUNT -gt 0 ]; then
     echo ""
     echo "Skills found:"
-    find "$HOME/.agents/skills" -name "*.md" -type f -exec sh -c '
+    find "$HOME/.codex/skills" -name "*.md" -type f -exec sh -c '
       FILE="$1"
       NAME=$(grep -m1 "^name:" "$FILE" 2>/dev/null | sed "s/name: //")
       DESC=$(grep -m1 "^description:" "$FILE" 2>/dev/null | sed "s/description: //")
@@ -408,15 +408,15 @@ else
 fi
 
 echo ""
-echo "=== PROJECT-LEVEL SKILLS (.agents/skills/) ==="
-if [ -d ".agents/skills" ]; then
-  PROJECT_COUNT=$(find ".agents/skills" -name "*.md" 2>/dev/null | wc -l)
+echo "=== PROJECT-LEVEL SKILLS (.codex/skills/) ==="
+if [ -d ".codex/skills" ]; then
+  PROJECT_COUNT=$(find ".codex/skills" -name "*.md" 2>/dev/null | wc -l)
   echo "Total skills: $PROJECT_COUNT"
 
   if [ $PROJECT_COUNT -gt 0 ]; then
     echo ""
     echo "Skills found:"
-    find ".agents/skills" -name "*.md" -type f -exec sh -c '
+    find ".codex/skills" -name "*.md" -type f -exec sh -c '
       FILE="$1"
       NAME=$(grep -m1 "^name:" "$FILE" 2>/dev/null | sed "s/name: //")
       DESC=$(grep -m1 "^description:" "$FILE" 2>/dev/null | sed "s/description: //")
@@ -467,8 +467,8 @@ Ask user to provide either:
 - **Paste content**: Paste skill markdown content directly
 
 Then ask for scope:
-- **User-level** (~/.agents/skills/) - Available across all projects
-- **Project-level** (.agents/skills/) - Only for this project
+- **User-level** (~/.codex/skills/) - Available across all projects
+- **Project-level** (.codex/skills/) - Only for this project
 
 Validate the skill format and save to the chosen location.
 
@@ -715,7 +715,7 @@ When invoked without arguments, run the full guided wizard.
 
 **Automatic Application**: Codex detects triggers and applies skills automatically - no need to remember or search for solutions.
 
-**Version Control**: Project-level skills (.agents/skills/) are committed with your code, so the whole team benefits.
+**Version Control**: Project-level skills (.codex/skills/) are committed with your code, so the whole team benefits.
 
 **Evolving Knowledge**: Skills improve over time as you discover better approaches and refine triggers.
 
@@ -760,8 +760,8 @@ Good skills are:
 > /skill list
 
 Checking skill directories...
-✓ User skills directory exists: ~/.agents/skills/
-✓ Project skills directory exists: .agents/skills/
+✓ User skills directory exists: ~/.codex/skills/
+✓ Project skills directory exists: .codex/skills/
 
 Scanning for skills...
 

package/skills/team/SKILL.md

@@ -9,6 +9,12 @@ description: N coordinated agents on shared task list using tmux-based orchestra
 
 This skill is operationally sensitive. Treat it as an operator workflow, not a generic prompt pattern.
 
+## Team vs Native Subagents
+
+- Use **Codex native subagents** for bounded, in-session parallelism where one leader thread can fan out a few independent subtasks and wait for them directly.
+- Use **`omx team`** when you need durable tmux workers, shared task state, mailbox/dispatch coordination, worktrees, explicit lifecycle control, or long-running parallel execution that must survive beyond one local reasoning burst.
+- Native subagents can complement team/ralph execution, but they do **not** replace the tmux team runtime's stateful coordination contract.
+
 ## What This Skill Must Do
 
 ## GPT-5.4 Guidance Alignment

package/skills/worker/SKILL.md

@@ -20,8 +20,8 @@ Example: `alpha/worker-2`
 When a worker inbox tells you to load this skill, resolve the first existing path:
 
 1. `${CODEX_HOME:-~/.codex}/skills/worker/SKILL.md`
-2. `~/.agents/skills/worker/SKILL.md`
-3. `<leader_cwd>/.agents/skills/worker/SKILL.md`
+2. `~/.codex/skills/worker/SKILL.md`
+3. `<leader_cwd>/.codex/skills/worker/SKILL.md`
 4. `<leader_cwd>/skills/worker/SKILL.md` (repo fallback)
 
 ## Startup Protocol (ACK)