oh-my-codex 0.13.2 → 0.14.1

package/src/scripts/postinstall.ts

@@ -0,0 +1,161 @@
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  isInstallVersionBump,
+  readUserInstallStamp,
+  type UserInstallStamp,
+  writeUserInstallStamp,
+} from "../cli/update.js";
+import { setup } from "../cli/setup.js";
+import { getPackageRoot } from "../utils/package.js";
+
+type PostinstallStatus =
+  | "noop-local"
+  | "noop-same-version"
+  | "noop-missing-version"
+  | "hinted"
+  | "setup-ran"
+  | "setup-failed";
+
+export interface PostinstallResult {
+  status: PostinstallStatus;
+  version: string | null;
+}
+
+interface PostinstallDependencies {
+  env: NodeJS.ProcessEnv;
+  getCurrentVersion: () => Promise<string | null>;
+  isInteractive: () => boolean;
+  log: (message: string) => void;
+  readStamp: () => Promise<UserInstallStamp | null>;
+  runSetup: typeof setup;
+  warn: (message: string) => void;
+  writeStamp: (stamp: UserInstallStamp) => Promise<void>;
+}
+
+function stripLeadingV(version: string): string {
+  return version.trim().replace(/^v/i, "");
+}
+
+function isTruthyEnv(value: string | undefined): boolean {
+  return value === "1" || value === "true";
+}
+
+export function isGlobalInstallLifecycle(env: NodeJS.ProcessEnv = process.env): boolean {
+  return isTruthyEnv(env.npm_config_global) || env.npm_config_location === "global";
+}
+
+function resolveInstallRoot(env: NodeJS.ProcessEnv): string {
+  const installPrefix = env.npm_config_prefix?.trim() || env.npm_config_local_prefix?.trim();
+  return installPrefix ? resolve(installPrefix) : process.cwd();
+}
+
+async function runSetupFromInstallRoot(
+  runSetup: typeof setup,
+  installRoot: string,
+): Promise<void> {
+  const previousCwd = process.cwd();
+  if (previousCwd === installRoot) {
+    await runSetup();
+    return;
+  }
+
+  process.chdir(installRoot);
+  try {
+    await runSetup();
+  } finally {
+    process.chdir(previousCwd);
+  }
+}
+
+async function getCurrentVersion(): Promise<string | null> {
+  try {
+    const packageJsonPath = join(getPackageRoot(), "package.json");
+    const content = await readFile(packageJsonPath, "utf-8");
+    const parsed = JSON.parse(content) as { version?: string };
+    return typeof parsed.version === "string" ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+
+const defaultDependencies: PostinstallDependencies = {
+  env: process.env,
+  getCurrentVersion,
+  isInteractive: () => Boolean(process.stdin.isTTY && process.stdout.isTTY),
+  log: (message) => console.log(message),
+  readStamp: () => readUserInstallStamp(),
+  runSetup: setup,
+  warn: (message) => console.warn(message),
+  writeStamp: (stamp) => writeUserInstallStamp(stamp),
+};
+
+export async function runPostinstall(
+  dependencies: Partial<PostinstallDependencies> = {},
+): Promise<PostinstallResult> {
+  const resolved = { ...defaultDependencies, ...dependencies };
+  const { env } = resolved;
+
+  if (!isGlobalInstallLifecycle(env)) {
+    return { status: "noop-local", version: null };
+  }
+
+  const currentVersion = await resolved.getCurrentVersion();
+  if (!currentVersion) {
+    return { status: "noop-missing-version", version: null };
+  }
+
+  const currentStampVersion = stripLeadingV(currentVersion);
+  const existingStamp = await resolved.readStamp();
+  if (!isInstallVersionBump(currentVersion, existingStamp)) {
+    return { status: "noop-same-version", version: currentStampVersion };
+  }
+
+  await resolved.writeStamp({
+    installed_version: currentStampVersion,
+    ...(typeof existingStamp?.setup_completed_version === "string"
+      ? { setup_completed_version: existingStamp.setup_completed_version }
+      : {}),
+    updated_at: new Date().toISOString(),
+  });
+
+  if (!resolved.isInteractive()) {
+    resolved.log(
+      `[omx] Installed oh-my-codex v${currentStampVersion}. Run \`omx setup\` (interactive) or \`omx update\` when you're ready.`,
+    );
+    return { status: "hinted", version: currentStampVersion };
+  }
+
+  resolved.log(
+    `[omx] Detected oh-my-codex v${currentStampVersion} install/update. Launching interactive setup...`,
+  );
+
+  try {
+    await runSetupFromInstallRoot(resolved.runSetup, resolveInstallRoot(env));
+    await resolved.writeStamp({
+      installed_version: currentStampVersion,
+      setup_completed_version: currentStampVersion,
+      updated_at: new Date().toISOString(),
+    });
+    resolved.log(`[omx] Setup refresh completed for v${currentStampVersion}.`);
+    return { status: "setup-ran", version: currentStampVersion };
+  } catch (error) {
+    resolved.warn(
+      `[omx] Postinstall setup skipped after a non-fatal error: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return { status: "setup-failed", version: currentStampVersion };
+  }
+}
+
+export async function main(): Promise<void> {
+  await runPostinstall();
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    console.warn(
+      `[omx] Postinstall setup skipped after a non-fatal error: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  });
+}

package/src/scripts/sync-prompt-guidance-fragments.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 
 async function read(path: string): Promise<string> { return await readFile(path, 'utf-8'); }
@@ -12,6 +13,7 @@ function replaceBetween(text: string, startMarker: string, endMarker: string, re
 
 async function main(): Promise<void> {
   const op = (await read('docs/prompt-guidance-fragments/core-operating-principles.md')).trim();
+  const sr = (await read('docs/prompt-guidance-fragments/leader-specialist-routing.md')).trim();
   const vs = (await read('docs/prompt-guidance-fragments/core-verification-and-sequencing.md')).trim();
   const exC = (await read('docs/prompt-guidance-fragments/executor-constraints.md')).trim();
   const exO = (await read('docs/prompt-guidance-fragments/executor-output.md')).trim();
@@ -22,8 +24,10 @@ async function main(): Promise<void> {
   const vfI = (await read('docs/prompt-guidance-fragments/verifier-investigation.md')).trim();
 
   for (const file of ['AGENTS.md', 'templates/AGENTS.md']) {
+    if (!existsSync(file)) continue;
     let text = await read(file);
     text = replaceBetween(text, '<!-- OMX:GUIDANCE:OPERATING:START -->', '<!-- OMX:GUIDANCE:OPERATING:END -->', op);
+    text = replaceBetween(text, '<!-- OMX:GUIDANCE:SPECIALIST-ROUTING:START -->', '<!-- OMX:GUIDANCE:SPECIALIST-ROUTING:END -->', sr);
     text = replaceBetween(text, '<!-- OMX:GUIDANCE:VERIFYSEQ:START -->', '<!-- OMX:GUIDANCE:VERIFYSEQ:END -->', vs);
     await writeFile(file, text);
   }

package/templates/AGENTS.md

@@ -10,6 +10,7 @@ USE CODEX NATIVE SUBAGENTS FOR INDEPENDENT PARALLEL SUBTASKS WHEN THAT IMPROVES
 You are running with oh-my-codex (OMX), a coordination layer for Codex CLI.
 This AGENTS.md is the top-level operating contract for the workspace.
 Role prompts under `prompts/*.md` are narrower execution surfaces. They must follow this file, not override it.
+When OMX is installed, load the installed prompt/skill/agent surfaces from `~/.codex/prompts`, `~/.codex/skills`, and `~/.codex/agents` (or the project-local `./.codex/...` equivalents when project scope is active).
 
 <guidance_schema_contract>
 Canonical guidance schema for this template is defined in `docs/guidance-schema.md`.
@@ -38,6 +39,11 @@ Keep runtime marker contracts stable and non-destructive when overlays are appli
 <!-- OMX:GUIDANCE:OPERATING:START -->
 - Default to quality-first, intent-deepening responses; think one more step before replying or asking for clarification, and use as much detail as needed for a strong result without empty verbosity.
 - Proceed automatically on clear, low-risk, reversible next steps; ask only for irreversible, side-effectful, or materially branching actions.
+- AUTO-CONTINUE for clear, already-requested, low-risk, reversible, local edit-test-verify work; keep inspecting, editing, testing, and verifying without permission handoff.
+- ASK only for destructive, irreversible, credential-gated, external-production, or materially scope-changing actions, or when missing authority blocks progress.
+- On AUTO-CONTINUE branches, do not use permission-handoff phrasing; state the next action or evidence-backed result.
+- Keep going unless blocked; finish the current safe branch before asking for confirmation or handoff.
+- Ask only when blocked by missing information, missing authority, or an irreversible/destructive branch.
 - Do not ask or instruct humans to perform ordinary non-destructive, reversible actions; execute those safe reversible OMX/runtime operations and ordinary commands yourself.
 - Treat OMX runtime manipulation, state transitions, and ordinary command execution as agent responsibilities when they are safe and reversible.
 - Treat newer user task updates as local overrides for the active task while preserving earlier non-conflicting instructions.
@@ -176,12 +182,25 @@ Rules:
 <model_routing>
 Match role to task shape:
 - Low complexity: `explore`, `style-reviewer`, `writer`
+- Research/discovery: `explore` for repo lookup, `researcher` for official docs/reference gathering, `dependency-expert` for SDK/API/package evaluation
 - Standard: `executor`, `debugger`, `test-engineer`
 - High complexity: `architect`, `executor`, `critic`
 
 For Codex native child agents, model routing defaults to inheritance/current repo defaults unless the caller has a concrete reason to override it.
 </model_routing>
 
+<specialist_routing>
+Leader/workflow routing contract:
+<!-- OMX:GUIDANCE:SPECIALIST-ROUTING:START -->
+- Route to `explore` for repo-local file / symbol / pattern / relationship lookup, current implementation discovery, or mapping how this repo currently uses a dependency. `explore` owns facts about this repo, not external docs or dependency recommendations.
+- Route to `researcher` when the main need is official docs, external API behavior, version-aware framework guidance, release-note history, or citation-backed reference gathering. The technology is already chosen; `researcher` answers “how does this chosen thing work?” and is not the default dependency-comparison role.
+- Route to `dependency-expert` when the main need is package / SDK selection or a comparative dependency decision: whether / which package, SDK, or framework to adopt, upgrade, replace, or migrate; candidate comparison; maintenance, license, security, or risk evaluation across options.
+- Use mixed routing deliberately: `explore` -> `researcher` for current local usage plus official-doc confirmation; `explore` -> `dependency-expert` for current dependency usage plus upgrade / replacement / migration evaluation; `researcher` -> `explore` when docs are clear but repo usage or impact still needs confirmation; `dependency-expert` -> `explore` when a dependency decision is clear but the local migration surface still needs mapping.
+- Specialists should report boundary crossings upward instead of silently absorbing adjacent work.
+- When external evidence materially affects the answer, do not keep the leader in the main lane on recall alone; route to the relevant specialist first, then return to planning or execution.
+<!-- OMX:GUIDANCE:SPECIALIST-ROUTING:END -->
+</specialist_routing>
+
 ---
 
 <agent_catalog>
@@ -193,50 +212,43 @@ Key roles:
 - `executor` — implementation and refactoring
 - `verifier` — completion evidence and validation
 
+Research/discovery specialists:
+- `explore` — first-stop repository lookup and symbol/file mapping
+- `researcher` — official docs, references, and external fact gathering
+- `dependency-expert` — SDK/API/package evaluation before adopting or changing dependencies
+
 Specialists remain available through the role catalog and native child-agent surfaces when the task clearly benefits from them.
 </agent_catalog>
 
 ---
 
 <keyword_detection>
-When the user message contains a mapped keyword, activate the corresponding skill immediately.
-Do not ask for confirmation.
+Keyword routing is implemented primarily by native `UserPromptSubmit` hooks and the generated keyword registry. Treat hook-injected routing context as authoritative for the current turn, then load the named `SKILL.md` or prompt file as instructed.
 
-Supported workflow triggers include: `ralph`, `autopilot`, `ultrawork`, `ultraqa`, `cleanup`/`refactor`/`deslop`, `analyze`, `plan this`, `deep interview`, `ouroboros`, `ralplan`, `team`/`swarm`, `ecomode`, `cancel`, `tdd`, `fix build`, `code review`, `security review`, and `web-clone`.
-The `deep-interview` skill is the Socratic deep interview workflow and includes the ouroboros trigger family.
+Fallback behavior when hook context is unavailable:
+- Explicit `$name` invocations run left-to-right and override implicit keywords.
+- Bare skill names do not activate skills by themselves; skill-name activation requires explicit `$skill` invocation. Natural-language routing phrases may still map to a workflow when they are not just the bare skill name. Examples: `analyze` / `investigate` → `$analyze` for read-only deep analysis with ranked synthesis, explicit confidence, and concrete file references; `deep interview`, `interview`, `don't assume`, or `ouroboros` → `$deep-interview`; `ralplan` / `consensus plan` → `$ralplan`; `cancel`, `stop`, or `abort` → `$cancel`.
+- Keep the detailed keyword list in `src/hooks/keyword-registry.ts`; do not duplicate that table here.
 
-| Keyword(s) | Skill | Action |
-|-------------|-------|--------|
 Runtime availability gate:
 - Treat `autopilot`, `ralph`, `ultrawork`, `ultraqa`, `team`/`swarm`, and `ecomode` as **OMX runtime workflows**, not generic prompt aliases.
-- Auto-activate those runtime workflows only when the current session is actually running under OMX CLI/runtime (for example, launched via `omx`, with OMX session overlay/runtime state available, or when the user explicitly asks to run `omx ...` in the shell).
+- Auto-activate runtime workflows only when the current session is actually running under OMX CLI/runtime (for example, launched via `omx`, with OMX session overlay/runtime state available, or when the user explicitly asks to run `omx ...` in the shell).
 - In Codex App or plain Codex sessions without OMX runtime, do **not** treat those keywords alone as activation. Explain that they require OMX CLI runtime support, and continue with the nearest App-safe surface (`deep-interview`, `ralplan`, `plan`, or native subagents) unless the user explicitly wants you to launch OMX from the shell.
+- When deep-interview is active in OMX CLI/runtime, ask interview rounds via `omx question`; do not substitute `request_user_input` or ad hoc plain-text questioning, and respect Stop-hook blocking while a deep-interview question obligation is pending.
+
+<triage_routing>
+## Triage: advisory prompt-routing context
+
+The keyword detector is the first and deterministic routing surface. Triage runs only when no keyword matches.
 
-| Keyword(s) | Skill | Action |
-|-------------|-------|--------|
-| "ralph", "don't stop", "must complete", "keep going" | `$ralph` | Runtime-only: read `~/.codex/skills/ralph/SKILL.md`, execute persistence loop only inside OMX CLI/runtime |
-| "autopilot", "build me", "I want a" | `$autopilot` | Runtime-only: read `~/.codex/skills/autopilot/SKILL.md`, execute autonomous pipeline only inside OMX CLI/runtime |
-| "ultrawork", "ulw", "parallel" | `$ultrawork` | Runtime-only: read `~/.codex/skills/ultrawork/SKILL.md`, execute parallel agents only inside OMX CLI/runtime |
-| "ultraqa" | `$ultraqa` | Runtime-only: read `~/.codex/skills/ralph/SKILL.md`, run persistent completion and verification loop only inside OMX CLI/runtime (UltraQA compatibility alias) |
-| "analyze", "investigate" | `$analyze` | Read `~/.codex/skills/analyze/SKILL.md`, run read-only deep analysis with ranked synthesis, explicit confidence, and concrete file references |
-| "plan this", "plan the", "let's plan" | `$plan` | Read `~/.codex/skills/plan/SKILL.md`, start planning workflow |
-| "interview", "deep interview", "gather requirements", "interview me", "don't assume", "ouroboros" | `$deep-interview` | Read `~/.codex/skills/deep-interview/SKILL.md`, run Ouroboros-inspired Socratic ambiguity-gated interview workflow |
-| "ralplan", "consensus plan" | `$ralplan` | Read `~/.codex/skills/ralplan/SKILL.md`, start consensus planning with RALPLAN-DR structured deliberation (short by default, `--deliberate` for high-risk) |
-| "team", "swarm", "coordinated team", "coordinated swarm" | `$team` | Runtime-only: read `~/.codex/skills/team/SKILL.md`, start tmux-based team orchestration only inside OMX CLI/runtime (swarm compatibility alias) |
-| "ecomode", "eco", "budget" | `$ecomode` | Runtime-only: read `~/.codex/skills/ultrawork/SKILL.md`, execute cost-aware parallel workflow only inside OMX CLI/runtime (ecomode compatibility alias) |
-| "cancel", "stop", "abort" | `$cancel` | Read `~/.codex/skills/cancel/SKILL.md`, cancel active modes |
-| "tdd", "test first" | `$tdd` | Read `~/.codex/prompts/test-engineer.md`, run test-first workflow (tdd compatibility alias) |
-| "fix build", "type errors" | `$build-fix` | Read `~/.codex/prompts/build-fixer.md`, fix build errors with minimal diff (build-fix compatibility alias) |
-| "review code", "code review", "code-review" | `$code-review` | Read `~/.codex/skills/code-review/SKILL.md`, run code review |
-| "security review" | `$security-review` | Read `~/.codex/skills/security-review/SKILL.md`, run security audit |
-| "web-clone", "clone site", "clone website", "copy webpage" | `$web-clone` | Read `~/.codex/skills/web-clone/SKILL.md`, start website cloning pipeline |
-
-Detection rules:
-- Keywords are case-insensitive and match anywhere in the user message.
-- Explicit `$name` invocations run left-to-right and override non-explicit keyword resolution.
-- If multiple non-explicit keywords match, use the most specific match.
-- Runtime-only keywords must pass the runtime availability gate before activation.
-- The rest of the user message becomes the task description.
+When active, triage emits **advisory prompt-routing context** — a developer-context string that the model may follow. It does not activate a skill or workflow by itself. It is a best-effort hint, not a guarantee.
+
+Note: `explore`, `executor`, and `designer` are agent role-prompt files under `prompts/`, not workflow skills.
+
+Explicit keywords remain the deterministic control surface when you want explicit, guaranteed routing — use them whenever exact behavior matters.
+
+To opt out per prompt with phrases such as `no workflow`, `just chat`, or `plain answer` — the triage layer will suppress context injection for that prompt.
+</triage_routing>
 
 Ralph / Ralplan execution gate:
 - Enforce **ralplan-first** when ralph is active and planning is not complete.
@@ -374,6 +386,8 @@ Do not cancel while recoverable work remains.
 ---
 
 <state_management>
+Hooks own normal skill-active and workflow-state persistence under `.omx/state/`.
+
 OMX persists runtime state under `.omx/`:
 - `.omx/state/` — mode state
 - `.omx/notepad.md` — session notes
@@ -383,11 +397,8 @@ OMX persists runtime state under `.omx/`:
 
 Available MCP groups include state/memory tools, code-intel tools, and trace tools.
 
-Mode lifecycle requirements:
-- Write state on start.
-- Update state on phase or iteration change.
-- Mark inactive with `completed_at` on completion.
-- Clear state on cancel/abort cleanup.
+Agents may use OMX state/MCP tools for explicit lifecycle transitions, recovery, checkpointing, cancellation cleanup, or compaction resilience.
+Do not manually duplicate hook-owned activation state unless recovering from missing or stale state.
 </state_management>
 
 ---

package/templates/catalog-manifest.json

@@ -45,6 +45,13 @@
       "core": false,
       "internalRequired": false
     },
+    {
+      "name": "autoresearch",
+      "category": "execution",
+      "status": "active",
+      "core": false,
+      "internalRequired": false
+    },
     {
       "name": "swarm",
       "category": "execution",

package/templates/model-instructions/explore-lightweight-AGENTS.md

@@ -0,0 +1,11 @@
+# OMX Explore Lightweight Instructions
+
+You are executing the `omx explore` command path.
+
+Constraints:
+- keep output concise and repository-focused
+- read-only only
+- prefer direct file/symbol/pattern lookup over orchestration
+- do not use multi-agent workflows
+- do not expand into planning/execution mode behavior
+- return only the minimal answer needed for the explore request

package/templates/model-instructions/sparkshell-lightweight-AGENTS.md

@@ -0,0 +1,10 @@
+# OMX SparkShell Lightweight Instructions
+
+You are executing the `omx sparkshell` summary path.
+
+Constraints:
+- summarize command output cheaply and concisely
+- do not broaden into repo planning or orchestration behavior
+- preserve important failures and warnings
+- prefer short factual summaries over long prose
+- do not suggest edits or implementation plans unless explicitly required by the command output