oh-my-customcodex 0.5.0 → 0.5.2

package/templates/guides/claude-code/14-token-efficiency.md

@@ -22,12 +22,16 @@ Use R013 ecomode and existing runtime guards when you want to compress active-se
 
 This layer changes how the session behaves while work is running.
 
-## Layer 3: Tool-Specific Compression
+## Layer 3: Retrieval and Tool-Specific Compression
+
+Use semantic code search or graph retrieval before broad file reads when the problem is repository exploration. Prefer Semble when an indexed semantic MCP is connected, and prefer CRG/code-review-graph when the task needs impact radius or dependency context. Fall back to `rg` and targeted reads when those tools are unavailable.
 
 Use `playwright-compress` when the problem is not the whole session, but one extremely verbose browser tool result.
 
 This layer is intentionally narrow:
 
+- use Semble for high-recall code search over large repositories
+- use CRG for `get_minimal_context`, `get_impact_radius`, and trust-boundary graph queries
 - compress verbose Playwright MCP output after the tool succeeds
 - preserve `ref=` tokens and URLs for follow-up interaction
 - keep browser evidence actionable without keeping the full raw payload in context
@@ -64,6 +68,7 @@ Typical settings-level levers:
 |------|------------|
 | Protect cache value across pauses | Layer 1 |
 | Compress runtime behavior in large sessions | Layer 2 |
+| Reduce broad code-search reads | Layer 3 |
 | Compress one noisy browser interaction | Layer 3 |
 | Reduce baseline token spend from configuration | Layer 4 |
 

package/templates/guides/claude-code/15-version-compatibility.md

@@ -2,6 +2,75 @@
 
 This guide records Claude Code release-note impact that affects the Claude compatibility template. The Codex-native runtime still uses `.codex/**` and OMX as the primary surface.
 
+## v2.1.146
+
+Published: 2026-05-21.
+
+Source: upstream oh-my-customcode #1205, Codex port #1364.
+
+| Change | Impact on oh-my-customcodex | Action |
+|--------|------------------------------|--------|
+| `/simplify` was renamed to `/code-review` and accepts effort levels such as `/code-review high` | Native Claude command naming is now closer to review workflows, but this package still exposes its own `dev-review` skill. | No runtime rename. Keep user-facing docs clear that `dev-review` is the package skill and `/code-review` is the native Claude command. |
+| Auto mode no longer suppresses `AskUserQuestion` when the user or a skill explicitly relies on it | Ambiguity-gated compatibility workflows can ask explicit questions even in auto mode. | No Codex tool change. Keep `request_user_input`/question usage limited to genuinely branching cases. |
+| MCP `resources/list`, `resources/templates/list`, and `prompts/list` pagination was fixed | Large memory or ontology MCP servers are less likely to hide resources after page 1. | No package change; treat complete paginated MCP lists as more reliable evidence. |
+| `CLAUDE_CODE_SUBAGENT_MODEL` is forwarded to child processes in multi-agent sessions | Claude compatibility sessions with model env overrides now preserve child-process model intent. | No Codex model override. Codex-native child agents still follow repo model routing and inherited defaults. |
+| `/background` accepts skill-only or custom-slash-only input and background sessions preserve granted tool permissions | Long-running Claude compatibility sessions are less likely to stall on already granted permissions. | No Codex change. Keep permission expectations explicit in workflow prompts. |
+| Agent SDK streaming end-of-session exception was fixed | Agent SDK plugin experiments should be less noisy at stream completion. | Monitor only; no package change. |
+
+## v2.1.145
+
+Published: 2026-05-19.
+
+Source: upstream oh-my-customcode #1191, Codex port #1353.
+
+| Change | Impact on oh-my-customcodex | Action |
+|--------|------------------------------|--------|
+| Statusline input includes structured GitHub fields such as `gh.repo`, `gh.pr_number`, and `gh.pr_state` | Removes the need to call `gh pr view` on every refresh when Claude compatibility statusline JSON already carries PR context. | Ported. `statusline.sh` now prefers native `gh.*` fields and falls back to the cached `gh pr view` path only when they are absent. |
+| Additional statusline fields may be empty strings | Empty fields can collapse TSV parsing if not normalized. | Ported. Empty native GitHub fields are normalized before Bash reads them. |
+| Stability fixes for statusline and background sessions are additive | No Codex runtime change beyond template compatibility. | Keep `.codex/**` behavior primary and mirror compatibility docs. |
+
+## v2.1.144
+
+Published: 2026-05-18.
+
+Source: upstream oh-my-customcode #1187, Codex port #1349.
+
+| Change | Impact on oh-my-customcodex | Action |
+|--------|------------------------------|--------|
+| `claude agents --json` exposes structured background-agent state | Claude compatibility statusline and monitoring can show active agent counts without parsing display text. | Ported. Statusline JSON `agents` arrays render as `A:N` when active agents exist. |
+| Stop/SubagentStop input can include `background_tasks` and `session_crons` | Session-end hooks can detect dangling background work and cron state. | Ported. `session-reflection.sh` records counts and summaries when those fields are present. |
+| Background-agent status handling became more reliable | Reduces false stale-agent diagnostics for Claude compatibility users. | Keep existing Codex/OMX agent tracking and treat Claude JSON as optional compatibility evidence. |
+
+## v2.1.143
+
+Published: 2026-05-17.
+
+Source: upstream oh-my-customcode #1166, Codex port #1348.
+
+| Change | Impact on oh-my-customcodex | Action |
+|--------|------------------------------|--------|
+| Hook/session lifecycle payloads became richer for background work | The compatibility template can capture more useful session-end evidence without blocking shutdown. | Ported through the advisory `session-reflection.sh` Stop/SubagentStop hook. |
+| Background session handling received additional fixes | Helps Claude compatibility workflows that run long-lived agents. | No Codex runtime change; document behavior and keep OMX-native orchestration as primary. |
+| Release-note changes are Claude-template oriented | The package must avoid redesigning Codex-native flow for Claude-only payload additions. | Mirror the compatibility guide and add tests that lock template/source docs together. |
+
+## v2.1.142
+
+Published: 2026-05-14.
+
+Source: upstream oh-my-customcode #1158, Codex port #1329.
+
+| Change | Impact on oh-my-customcodex | Action |
+|--------|------------------------------|--------|
+| `claude agents` added `--add-dir`, `--settings`, `--mcp-config`, `--plugin-dir`, `--permission-mode`, `--model`, `--effort`, and `--dangerously-skip-permissions` | Useful for Claude compatibility sessions that need CLI-level overrides for background agents. Codex-native child agents still use the Codex tool surface and repo model contract. | No Codex runtime change. Keep unattended Claude-template prompts explicit about permission mode. |
+| Fast Mode now defaults to Opus 4.7 | Only affects Claude compatibility users running Fast Mode with `model: opus` agents. | Pin with `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1` only when a compatibility session needs old behavior. |
+| Root-level plugin `SKILL.md` is surfaced as a skill | Does not change this repo's packaged `.claude/skills/<name>/SKILL.md` layout. | No template migration. |
+| `/plugin details` shows plugin LSP servers | Improves plugin inventory visibility for compatibility users. | No package change. |
+| `/web-setup` warns before replacing an existing GitHub App connection | UX safety improvement outside this harness. | No action. |
+| `MCP_TOOL_TIMEOUT` now raises remote HTTP/SSE MCP request timeout as intended | Helpful for slow remote memory or ontology MCP servers. | Set `MCP_TOOL_TIMEOUT` in affected environments only. |
+| Background sessions can edit existing git worktrees | Stabilizes Claude compatibility workflows that use git worktrees for parallel branches. | No Codex-side change. |
+| Background sessions survive macOS sleep/wake more reliably | Improves long-running Claude compatibility sessions. | No action. |
+| `--dangerously-skip-permissions` persists across retire/wake cycles | Reduces unattended permission-mode drops for Claude compatibility sessions. | Keep explicit permission guidance in workflow prompts. |
+
 ## v2.1.141
 
 Published: 2026-05-13.
@@ -50,6 +119,23 @@ Published: 2026-05-11.
 | Native `/goal` | The packaged workflow uses `/omcustomcodex:goal`; native `/goal` stays available for Claude Code completion tracking. |
 | `claude agents`, `/scroll-speed`, `claude plugin details <name>`, `/mcp` reconnect | Documented in the CLI, MCP, AGENTS, and CLAUDE template guidance. |
 
+## Known Limitations
+
+### Parent `.gitignore` nested plan pattern
+
+Source: upstream oh-my-customcode #1147, Codex port #1326.
+
+The parent package documented a future-proofing limitation for this pattern:
+
+```gitignore
+docs/superpowers/plans/*
+!docs/superpowers/plans/*.md
+```
+
+That pattern only tracks direct-child Markdown files. Git cannot re-include a file inside a directory that was already excluded by a broader parent pattern unless the directory path is also re-included.
+
+Current Codex-port status: not applicable. This repository does not ignore `docs/superpowers/plans/`, and existing nested plan documents are trackable. If a future ignore rule reintroduces that parent pattern, add explicit subdirectory re-includes before relying on nested plan files.
+
 ## Compatibility Rules
 
 1. Keep `.codex/**` as the source of truth for the Codex package.

package/templates/guides/claude-code-tracking.md

@@ -0,0 +1,51 @@
+# Background Agent Progress Tracking
+
+This is the Codex/OMX replacement for the old Claude Code background-agent tracking pattern. Use it when a subagent, team member, or delegated task keeps running while the main conversation moves on.
+
+## What To Track
+
+| Field | Purpose | Suggested source |
+| --- | --- | --- |
+| `agent_id` | Identify the worker unambiguously | Team member label or agent name |
+| `task` | Record what the worker is doing | The delegated prompt or issue title |
+| `state` | Show the current lifecycle stage | `queued`, `running`, `blocked`, `done`, `cleaned` |
+| `last_update` | Detect stale work | Timestamp from the latest status write |
+| `owner` | Tie progress to the current session | Branch, run, or team lead |
+| `next_action` | Make the next step obvious | `wait`, `retry`, `cleanup`, or `handoff` |
+
+## Preferred Surfaces
+
+- `.omx/state/` for durable session state.
+- `.omx/notepad.md` for lightweight progress notes.
+- `.omx/logs/` for execution traces and failure evidence.
+- `tracker-checkpoint` when you need a dedicated checkpoint agent to own progress bookkeeping.
+
+## Minimal Progress Loop
+
+1. Register the background task before it starts.
+2. Write a start record with the task and owner.
+3. Update the state when the worker changes phase.
+4. Mark the worker blocked instead of polling forever.
+5. Mark the worker done, then clean stale state if anything remains attached.
+
+## Recommended Status Format
+
+```text
+agent: tracker-checkpoint
+task: mirror rule and guide updates
+state: running
+last_update: 2026-05-24T12:00:00+09:00
+owner: release/v0.5.2-auto-dev
+next_action: wait_for_mirror_sync
+```
+
+## Staleness Rule
+
+If a background worker stops updating, treat it as stale after a short, defined window. Do not keep polling indefinitely. Either re-plan the task, hand it off, or clean it up.
+
+## Codex/OMX Notes
+
+- The main conversation should read the newest state file, not a stale log excerpt, before deciding what to do next.
+- If the worker is a team member, the progress record should make the team lead and branch obvious.
+- A background task that has already completed should not keep emitting progress noise.
+- Legacy Claude Code background-session references can remain as compatibility notes, but the default progress surface here is `.omx/state/`.

package/templates/guides/index.yaml

@@ -8,6 +8,18 @@ guides:
     source:
       type: internal
 
+  - name: agent-teams
+    description: Agent Teams shutdown and tmux fallback troubleshooting for Codex/OMX sessions
+    path: ./agent-teams/troubleshooting.md
+    source:
+      type: internal
+
+  - name: claude-code-tracking
+    description: Background agent progress tracking and stale-state handling for Codex/OMX sessions
+    path: ./claude-code-tracking.md
+    source:
+      type: internal
+
   # Frontend
   - name: impeccable-design
     description: AI design language reference — typography, color, motion, and UX writing for production-grade UI

package/templates/manifest.json

@@ -1,11 +1,11 @@
 {
-  "version": "0.5.0",
+  "version": "0.5.2",
   "requiresCC": ">=2.1.121",
   "claudeCode": {
     "minimumVersion": "2.1.121",
     "protectedPathBypassVersion": "2.1.126"
   },
-  "lastUpdated": "2026-04-28T00:01:33.302Z",
+  "lastUpdated": "2026-05-20T00:00:00.000Z",
   "components": [
     {
       "name": "rules",
@@ -23,13 +23,13 @@
       "name": "skills",
       "path": ".agents/skills",
       "description": "Reusable skill modules (project-scoped repo skills)",
-      "files": 119
+      "files": 123
     },
     {
       "name": "guides",
       "path": "guides",
       "description": "Reference documentation",
-      "files": 48
+      "files": 50
     },
     {
       "name": "hooks",

package/templates/tests/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "types": ["bun-types"]
+  },
+  "include": ["**/*.ts"]
+}

package/templates/workflows/auto-dev.yaml

@@ -13,28 +13,77 @@ observability:
     report_before: followup
 
 steps:
+  - name: preflight-sync
+    prompt: |
+      Phase 0 — Sync local repository and detect stale issue context before triage.
+
+      1. Run `git fetch --all --tags --prune`.
+      2. Compute `behind=$(git rev-list --count HEAD..origin/$(git rev-parse --abbrev-ref HEAD))`.
+      3. If behind > 0 and the worktree is clean, run `git pull --ff-only` and report synced commits.
+      4. If behind > 0 and the worktree is dirty, halt with a manual reconcile message.
+      5. Report latest tag, local HEAD, and synced/behind state.
+      6. Compare open issue body `vX.Y.Z` references against local git tags and warn on references to missing tags.
+      7. Create required lifecycle labels idempotently: in-progress, verify-ready, needs-review, decision-needed.
+    description: Sync remote state, detect stale version references, and ensure lifecycle labels
+
   - name: issue-analysis
+    depends_on: preflight-sync
     parallel:
       - name: pre-triage
         skill: professor-triage
-        description: Run professor-triage on open issues that lack verify-done label, including release-monitor labels codex-release and oh-my-codex-release
+        description: Run professor-triage on open issues that lack verify-done label, including release-monitor labels codex-release and oh-my-codex-release; never terminate from an empty verify-done query alone while release-monitor issues remain
         condition: "open issues without label:verify-done exist OR open release-monitor issues with label:codex-release or label:oh-my-codex-release exist"
       - name: triage
         skill: professor-triage
         description: Analyze verify-done and release-monitor issues against current codebase and perform automated triage
 
-  - name: plan
+  - name: scope-selection
     depends_on: issue-analysis
+    prompt: |
+      Select one bounded release scope and protect against stale milestone reuse.
+
+      Milestone pre-check:
+      - Query all milestones, open and closed, before creating vX.Y.Z.
+      - If the target milestone already exists and is closed, halt and require a version bump or manual reopen.
+      - If it exists and is open, reuse it.
+      - If it does not exist, create it and assign scoped issues.
+
+      Label semantics:
+      - Reference `.codex/skills/pipeline/labels.md`.
+      - Exclude blocked_by_decision, decision-needed, needs-review, verify-done, manual-action, and in-progress issues.
+      - Prefer verify-ready, codex-release, oh-my-codex-release, claude-code-release, and documentation issues.
+      - Sort by P1, P2, P3, then dependency order; cap a release unit at 7 issues.
+
+      Output a release manifest with issue number, title, prerequisite, effort, and labels.
+    description: Milestone state pre-check, label filter, and bounded release scope selection
+
+  - name: compression-mode-eval
+    depends_on: scope-selection
+    prompt: |
+      Evaluate docs-only compression mode.
+
+      Use `compression_mode=docs-only` only when:
+      - scope size is 3 or fewer issues
+      - every scoped issue has at least one of documentation, automated, codex-release, oh-my-codex-release, claude-code-release, or enhancement-yaml-only
+
+      In docs-only mode, replace heavyweight triage/plan/deep-plan/deep-verify spawns with direct summaries plus local self-review. Otherwise use standard mode.
+      Output the selected compression_mode for downstream steps.
+    description: Evaluate docs-only compression eligibility
+
+  - name: plan
+    depends_on: compression-mode-eval
     skill: release-plan
-    description: Group triaged issues into release units by priority and size
+    description: Group triaged issues into release units by priority and size; skipped if compression_mode=docs-only
     input: triage-results
 
   - name: deep-plan
+    depends_on: plan
     skill: deep-plan
-    description: Create detailed implementation plan for each release group
+    description: Create detailed implementation plan for each release group; skipped if compression_mode=docs-only
     foreach: release-group
 
   - name: implement
+    depends_on: deep-plan
     prompt: |
       Execute implementation plan with appropriate agents.
 
@@ -46,14 +95,40 @@ steps:
     description: Execute implementation plan with appropriate agents
     foreach: planned-issue
 
+  - name: verify-build
+    depends_on: implement
+    prompt: |
+      Project-specific build + test verification.
+
+      For Node/Bun projects:
+      1. Run `bun install` and halt on lockfile drift.
+      2. Run `bun run lint` when available.
+      3. Run `bun run typecheck` when available.
+      4. Run `bun test` mandatorily; do not silently skip tests.
+      5. Adopt the prior version's test result as the dynamic baseline. Current Codex baseline is 0 failures after #1328 verification.
+      6. Halt if current failures exceed baseline; otherwise report pass/fail counts and delta.
+      7. Run `bun run build` when available.
+
+      Halt on lint errors, typecheck errors, new test failures, build failure, or lockfile drift.
+    description: Auto-detected build + test verification with mandatory bun test baseline delta guard
+
   - name: verify
+    depends_on: verify-build
     skill: deep-verify
-    description: Multi-angle release quality verification
+    description: Multi-angle release quality verification; self-review checklist only if compression_mode=docs-only
 
   - name: release
+    depends_on: verify
     prompt: |
       Create release branch and pull request.
 
+      Required version preflight for npm package releases:
+      - Determine NEW_VERSION before creating a release branch, PR, or tag.
+      - Update `package.json` and `templates/manifest.json` to NEW_VERSION in the same commit.
+      - Use same-directory temporary files for generated JSON writes; do not write through `/tmp`.
+      - Run `bash .github/scripts/verify-version-sync.sh` after the bump and before tag or PR creation.
+      - Commit the bump with `chore(release): bump to v{NEW_VERSION}` before any release tag is created.
+
       Before creating `release/v*`, check whether a local branch named exactly
       `release` exists. Git stores refs as files/directories, so
       `refs/heads/release` blocks `refs/heads/release/vX.Y.Z`.