oh-my-customcodex 0.5.1 → 0.5.3

package/templates/.claude/rules/MUST-orchestrator-coordination.md

@@ -10,6 +10,40 @@ The main conversation is the **sole orchestrator**. It uses routing skills to de
 
 **The orchestrator MUST NEVER directly write, edit, or create files. ALL file modifications MUST be delegated to appropriate subagents.**
 
+## Codex-Native Meta-File Boundary
+
+Treat orchestration meta-files as delegated surfaces, not direct-orchestrator edit targets. This includes:
+
+- `AGENTS.md`
+- `.codex/rules/*.md`
+- `.codex/skills/*/SKILL.md`
+- `templates/AGENTS.md.*`
+- `templates/.claude/rules/*.md`
+
+If the change touches routing policy, guide indexes, mirrored templates, or release-time instructions, delegate the edit to the specialist that owns the surface. `mgr-creator` handles new structure and path scaffolding; `arch-documenter` or `mgr-updater` can handle content sync.
+
+### Self-Check Before Editing Meta Files
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  BEFORE CHANGING A META FILE, ASK YOURSELF:                     ║
+║                                                                   ║
+║  1. Is the target AGENTS.md or under .codex/ / templates/?      ║
+║     YES → delegate; do not edit directly                         ║
+║                                                                   ║
+║  2. Is this a one-line policy, index, or routing tweak?         ║
+║     YES → still delegate; there are no small exceptions          ║
+║                                                                   ║
+║  3. Does the change need mirrored Codex + template updates?     ║
+║     YES → delegate the pair together, then verify parity         ║
+║                                                                   ║
+║  4. Am I calling it "temporary" or "debugging" to justify it?   ║
+║     YES → stop; meta-file edits are never direct from orchestrator ║
+║                                                                   ║
+║  If any answer points to a problem → route the edit first       ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
 <!-- DETAIL: Self-Check (Before File Modification)
 ```
 ╔══════════════════════════════════════════════════════════════════╗
@@ -147,6 +181,20 @@ Key violations to avoid (file writes, git commands, bundled operations — all m
 ```
 -->
 
+### Meta-File Examples
+
+```
+❌ WRONG: Main conversation edits AGENTS.md directly
+   Main conversation → Write("AGENTS.md", content)
+
+✓ CORRECT: Main conversation → Agent(mgr-creator) → update AGENTS.md and mirrored template files
+
+❌ WRONG: Main conversation patches .codex/rules/MUST-intent-transparency.md directly
+   Main conversation → Edit(".codex/rules/MUST-intent-transparency.md", content)
+
+✓ CORRECT: Main conversation → Agent(arch-documenter) → revise the rule text, then verify the mirrored template file
+```
+
 ## Historical Sensitive-Path Bypass
 
 **Status**: deprecated as of Claude Code v2.1.121 for `.claude/skills/`, `.claude/agents/`, and `.claude/commands/`; fully deprecated in `bypassPermissions` as of v2.1.126 for broader protected paths.
@@ -166,6 +214,20 @@ Claude Code v2.1.141+ preserves the current permission mode when a session is de
 
 For this Codex port, native Codex/OMX subagents still follow the active Codex runtime tool policy. Claude compatibility prompts should keep delegated write authority explicit when a workflow relies on unattended edits, but v2.1.141+ no longer needs an extra `/bg` permission-mode workaround.
 
+## Agent Capability Pre-Check
+
+Before delegating work, compare the task requirements with the target agent frontmatter:
+
+| Requirement in prompt | Required frontmatter |
+|-----------------------|----------------------|
+| Shell, CLI, GitHub CLI, package manager, test, build, or script execution | `tools` includes `Bash` |
+| Any `gh`, `git`, `npm`, `bun`, `pnpm`, `yarn`, `python`, `node`, `curl`, `jq`, `make`, or `docker` command | `tools` includes `Bash`; `disallowedTools` does not include `Bash` |
+| Documentation-only synthesis from provided evidence | Bash is not required |
+
+Known limitation: `arch-documenter` has `disallowedTools: [Bash]`. Do not ask it to inspect GitHub issues, run shell commands, or collect command output. Pre-collect that evidence with a Bash-capable lane, then delegate the writing task.
+
+The `agent-capability-precheck.sh` hook blocks obvious mismatches so the orchestrator re-routes before spawning an agent that cannot execute the requested work.
+
 <!-- DETAIL: Autonomous Execution Mode
 
 ## Autonomous Execution Mode

package/templates/.claude/rules/MUST-sync-verification.md

@@ -35,10 +35,24 @@ Also run: mgr-claude-code-bible:verify (official spec compliance)
 | Missing pages | Source entities without wiki pages → run `/omcustomcodex:wiki` |
 | Stale pages | Source modification date newer than wiki `updated` field → run `/omcustomcodex:wiki ingest <path>` |
 | Broken cross-refs | Wiki links pointing to non-existent pages → run `/omcustomcodex:wiki lint` |
-| index.md accuracy | Wiki index page count matches actual page count |
+| wiki/index.yaml accuracy | Wiki index page count and indexed file entries match actual page files |
 
 Wiki verification is also enforced by CI (`.github/workflows/wiki-sync.yml`).
 
+### Structural Migration Verification
+
+Directory restructuring, template flattening, branch-strategy changes, generated-file relocation, and package-surface moves require a clean-checkout migration audit before they are considered complete.
+
+Required checks:
+
+1. Run the relevant verification from a clean checkout or isolated worktree, not only from a developer tree with untracked files.
+2. Confirm old paths are no longer referenced by CI, docs validators, template validators, install/init output, and release workflows.
+3. Confirm new paths are tracked by git and present in packaged templates or generated output where users will rely on them.
+4. Verify allowlists, `.gitignore`, and template sync checks do not hide missing files.
+5. Add or update regression tests that fail on the old path assumption.
+
+This section is specifically intended to catch migrations where local untracked files or stale CI path references make a release appear healthy while a clean checkout fails.
+
 ### Phase 4: Fix all discovered issues
 
 ### Phase 5: Commit via mgr-gitnerd

package/templates/.claude/rules/MUST-tool-identification.md

@@ -13,6 +13,25 @@ Every tool call MUST be prefixed with agent and model identification:
 
 For parallel calls: list ALL identifications BEFORE the tool calls.
 
+## Short Response Discipline
+
+Brief diagnostics and quick checks are not exempt. If a visible response will be followed by a tool call, include the tool prefix first even when the natural-language update is one sentence.
+
+Anti-pattern:
+
+```text
+확인하겠습니다.
+<tool call>
+```
+
+Correct:
+
+```text
+[Codex][gpt-5.5] → Tool: Bash
+[Codex][gpt-5.5] → Target: git status --short
+<tool call>
+```
+
 ### Common Violations to Avoid
 
 ```

package/templates/.claude/rules/SHOULD-memory-integration.md

@@ -361,7 +361,7 @@ MCP tools (searchable memory backends, episodic-memory) are **orchestrator-scope
 
 ### Session-End Self-Check (MANDATORY)
 
-(1) sys-memory-keeper updated MEMORY.md? (2) searchable memory save attempted when a backend is available? Both are required before confirming session-end to the user. See full self-check via Read tool.
+(1) sys-memory-keeper updated MEMORY.md? (2) searchable memory save attempted when a backend is available? (3) If `omcustomcodex-feedback` skill is active, prompt user to trigger it? All three are required before confirming session-end to the user. See full self-check via Read tool.
 
 <!-- DETAIL: Session-End Self-Check (MANDATORY)
 ```
@@ -376,10 +376,15 @@ MCP tools (searchable memory backends, episodic-memory) are **orchestrator-scope
 ║     YES → Continue (even if it failed)                           ║
 ║     NO  → ToolSearch + save now                                  ║
 ║                                                                   ║
+║  3. Is omcustomcodex-feedback skill available in this project?   ║
+║     YES → Ask user: "이번 세션 피드백을 omcustomcodex-feedback로 ║
+║          기록하시겠습니까?" — accept skip                        ║
+║     NO  → Skip                                                    ║
+║                                                                   ║
 ║  Note: episodic-memory auto-indexes conversations after session  ║
 ║  ends. No manual action needed — do NOT search as "verification" ║
 ║                                                                   ║
-║  BOTH steps must be completed before confirming to user.         ║
+║  ALL applicable steps must be completed before confirming to user.║
 ║  "Attempted" means called the tool — failure is OK, skipping     ║
 ║  is NOT.                                                          ║
 ╚══════════════════════════════════════════════════════════════════╝

package/templates/.claude/skills/systematic-debugging/SKILL.md

@@ -27,6 +27,7 @@ user-invocable: false
 4. **한 번에 하나의 가설만 검증한다.**
 5. **수정 시 "while I'm here" 리팩터링을 금지한다.**
 6. **수정 시도가 3번 실패하면 추가 패치 전에 구조적 문제를 의심한다.**
+7. **retry/cache/timeout을 변경하기 전에 false-fix 가능성을 점검한다.**
 
 이 과정을 어기는 것은 디버깅 실패로 본다.
 
@@ -64,6 +65,38 @@ user-invocable: false
 
 반드시 아래 순서로 진행한다.
 
+### Phase 0. Blocker Triage (Pre-Debug Gate)
+
+**Trigger**: When any external dependency, tool, or resource appears unavailable.
+
+Before declaring a task blocked or unsolvable, exhaust this checklist:
+
+| # | Workaround Path | Check |
+|---|----------------|-------|
+| 1 | Environment bypass | Can the dependency be bypassed in the current environment? |
+| 2 | Alternative tool | Is there an alternative tool, library, or approach? |
+| 3 | Partial solution | Can the task be partially completed without the dependency? |
+| 4 | Install/configure | Can the dependency be installed or configured now? |
+| 5 | Existing credentials | Are related tokens, auth files, or configs already present? |
+
+**Rules**:
+- Minimum 3 workaround paths MUST be explored before declaring "blocked"
+- Each explored path must be documented with outcome
+- "Session unsolvable" declarations MUST include the list of attempted workaround paths
+- If a workaround is found, proceed with debugging using that workaround
+
+**Output format**:
+```
+[Blocker Triage]
+├── Dependency: {what is unavailable}
+├── Path 1: {attempted} → {outcome}
+├── Path 2: {attempted} → {outcome}
+├── Path 3: {attempted} → {outcome}
+└── Verdict: {proceed with workaround N | genuinely blocked — reason}
+```
+
+If verdict is "genuinely blocked", escalate to user with full triage report. Do NOT silently abandon the task.
+
 ### Phase 1. Define The Problem
 
 먼저 문제를 축약한다.
@@ -286,3 +319,14 @@ This skill includes reference documents for specific debugging techniques:
 - `condition-based-waiting.md` — Replacing arbitrary delays with condition-based polling
 - `find-polluter.sh` — Bisection script for finding test pollution sources
 - `condition-based-waiting-example.ts` — Complete implementation of condition-based waiting utilities
+
+## Extended Phases
+
+These phase guides are mandatory when the debugging shape matches the trigger:
+
+| Phase guide | Trigger | Gate |
+|-------------|---------|------|
+| `phases/timeline-correlation.md` | Incident timing, deployment timing, or config drift may explain the failure | Correlate event time against code, deploy, config, data, and dependency timelines before patching. |
+| `phases/retry-cache-timeout-audit.md` | Proposed fix changes retry, cache, timeout, pooling, or backoff behavior | Prove the change fixes the root cause rather than suppressing symptoms. |
+| `phases/amplification-detection.md` | Traffic spikes, retry storms, queue growth, or cascading failures are possible | Identify amplification loops before increasing capacity or broadening retries. |
+| `phases/fault-injection.md` | The fix claims resilience against external failure modes | Inject the fault in a bounded environment and verify predicted behavior. |

package/templates/.claude/skills/systematic-debugging/phases/amplification-detection.md

@@ -0,0 +1,25 @@
+# Amplification Detection Phase
+
+Use this phase when the failure may cascade: retries, queues, background jobs, fan-out calls, polling loops, webhook delivery, cron overlap, or connection pools.
+
+## Required Checks
+
+1. Identify the trigger that starts the loop or fan-out.
+2. Count how many downstream operations one failing input can create.
+3. Check retry/backoff behavior and whether retries duplicate side effects.
+4. Check queue depth, worker concurrency, pool limits, and timeout alignment.
+5. Verify cancellation, dedupe, idempotency, and dead-letter behavior.
+
+## Output
+
+```text
+Amplification:
+- Trigger:
+- Fan-out factor:
+- Retry behavior:
+- Shared limit affected:
+- Dedupe/idempotency:
+- Verdict: {amplification present | no amplification evidence}
+```
+
+If amplification is present, stop widening retries or capacity until the loop has an owner and a guard.

package/templates/.claude/skills/systematic-debugging/phases/fault-injection.md

@@ -0,0 +1,31 @@
+# Fault Injection Phase
+
+Use this phase when a fix claims resilience against dependency failure, network failure, timeout, cancellation, corrupt input, clock skew, partial writes, or process restart.
+
+## Preconditions
+
+- The injected fault is bounded to local, test, or staging scope.
+- The expected behavior is written before running the injection.
+- Rollback is known and immediate.
+
+## Procedure
+
+1. State the fault and predicted behavior.
+2. Inject the smallest fault that exercises the claim.
+3. Record logs, exit code, response, retries, and cleanup behavior.
+4. Remove the fault and verify recovery.
+5. Convert the injection into a repeatable test when practical.
+
+## Output
+
+```text
+Fault Injection:
+- Fault:
+- Prediction:
+- Injection method:
+- Observed behavior:
+- Recovery:
+- Verdict: {claim proven | claim rejected | more instrumentation needed}
+```
+
+Do not run destructive or production fault injection without explicit authority.

package/templates/.claude/skills/systematic-debugging/phases/retry-cache-timeout-audit.md

@@ -0,0 +1,27 @@
+# Retry, Cache, Timeout Audit
+
+Use this phase before changing retries, caches, timeouts, pools, backoff, debounce, or rate limits.
+
+## Hard Gate
+
+A retry/cache/timeout change is invalid unless it explains why the original failure happened and proves the new behavior removes the root cause rather than hiding the symptom.
+
+## Audit Questions
+
+1. Is the proposed change reducing visible error rate without proving the failing operation now succeeds?
+2. Could it increase load, fan-out, duplicate side effects, or queue latency?
+3. Does it make the failure slower and harder to observe?
+4. Is the old timeout/cache/retry value actually wrong for the measured dependency behavior?
+5. Is there a smaller root-cause fix in input validation, ownership, ordering, or lifecycle?
+
+## Acceptable Evidence
+
+- Before/after traces showing the same request now reaches the intended success path.
+- Load or retry-count evidence proving amplification does not increase.
+- A failing guard that fails before the root-cause fix and passes after it.
+
+## Rejection Pattern
+
+```text
+Rejected: increased timeout/cache/retry | only suppresses the symptom; root cause remains unproven
+```

package/templates/.claude/skills/systematic-debugging/phases/timeline-correlation.md

@@ -0,0 +1,26 @@
+# Timeline Correlation Phase
+
+Use this phase when a failure has a meaningful time dimension: deployment time, config change time, traffic shift, data import, queue spike, cron run, dependency incident, or first customer report.
+
+## Required Steps
+
+1. Record the incident window in UTC and local time if available.
+2. List code, deploy, config, data, dependency, and traffic events around that window.
+3. Mark each event as before, during, or after first failure.
+4. Prefer events that happened before the first failure and changed the failing path.
+5. Write one falsifiable hypothesis that connects timing evidence to the symptom.
+
+## Output
+
+```text
+Timeline:
+- First failure:
+- Code/deploy events:
+- Config/data/dependency events:
+- Traffic or cron events:
+
+Hypothesis:
+<single root-cause hypothesis tied to the timeline>
+```
+
+Do not patch from chronology alone. Use the timeline to choose the next evidence-gathering step.

package/templates/.claude/statusline.sh

@@ -15,7 +15,13 @@
 #     "rate_limits": {                          (v2.1.80+, optional)
 #       "five_hour": { "used_percentage": 10, "resets_at": 1773979200 },
 #       "seven_day": { "used_percentage": 90, "resets_at": 1773979200 }
-#     }
+#     },
+#     "gh": {                                   (v2.1.145+, optional)
+#       "repo": "owner/repo",
+#       "pr_number": 160,
+#       "pr_state": "OPEN"
+#     },
+#     "agents": [ ... ]                         (v2.1.144+, optional)
 #   }
 
 # ---------------------------------------------------------------------------
@@ -61,14 +67,15 @@ fi
 
 # Debug logging for CTX investigation
 if [[ -n "${STATUSLINE_DEBUG}" ]]; then
-    printf '%s\n' "$json" >> "/tmp/.claude-statusline-debug-${PPID}.jsonl"
+    printf '%s\n' "$json" >> "/tmp/.codex-statusline-debug-${PPID}.jsonl"
 fi
 
 # ---------------------------------------------------------------------------
 # 4. Single jq call — extract all fields as TSV
-#    Fields: model_name, project_dir, ctx_pct, ctx_size, cost_usd, rl_5h_pct, rl_7d_pct, rl_5h_resets, rl_7d_resets
+#    Fields: model_name, project_dir, ctx_pct, ctx_size, cost_usd, rl_5h_pct, rl_7d_pct,
+#            rl_5h_resets, rl_7d_resets, gh_repo, gh_pr_number, gh_pr_state, agent_count
 # ---------------------------------------------------------------------------
-IFS=$'\t' read -r model_name project_dir ctx_pct ctx_size cost_usd rl_5h_pct rl_7d_pct rl_5h_resets rl_7d_resets <<< "$(
+IFS=$'\t' read -r model_name project_dir ctx_pct ctx_size cost_usd rl_5h_pct rl_7d_pct rl_5h_resets rl_7d_resets gh_repo gh_pr_number gh_pr_state agent_count <<< "$(
     printf '%s' "$json" | jq -r '[
         (.model.display_name // "unknown"),
         (.workspace.current_dir // ""),
@@ -78,14 +85,25 @@ IFS=$'\t' read -r model_name project_dir ctx_pct ctx_size cost_usd rl_5h_pct rl_
         (.rate_limits.five_hour.used_percentage // -1),
         (.rate_limits.seven_day.used_percentage // -1),
         (.rate_limits.five_hour.resets_at // -1),
-        (.rate_limits.seven_day.resets_at // -1)
+        (.rate_limits.seven_day.resets_at // -1),
+        (if (.gh.repo // "") == "" then "_" else .gh.repo end),
+        (if (.gh.pr_number // "") == "" then "_" else (.gh.pr_number | tostring) end),
+        (if (.gh.pr_state // "") == "" then "_" else .gh.pr_state end),
+        (if (.agents | type) == "array" then (.agents | length) else 0 end)
     ] | @tsv'
 )"
 
+[[ "$gh_repo" == "_" ]] && gh_repo=""
+[[ "$gh_pr_number" == "_" ]] && gh_pr_number=""
+[[ "$gh_pr_state" == "_" ]] && gh_pr_state=""
+if ! [[ "$agent_count" =~ ^[0-9]+$ ]]; then
+    agent_count=0
+fi
+
 # ---------------------------------------------------------------------------
 # 4b. Cost & context data bridge — write to temp file for hooks
 # ---------------------------------------------------------------------------
-COST_BRIDGE_FILE="/tmp/.claude-cost-${PPID}"
+COST_BRIDGE_FILE="/tmp/.codex-cost-${PPID}"
 _tmp="${COST_BRIDGE_FILE}.tmp.$$"
 printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$cost_usd" "$ctx_pct" "$(date +%s)" "$rl_5h_pct" "$rl_7d_pct" "$rl_5h_resets" "$rl_7d_resets" > "$_tmp" 2>/dev/null && mv -f "$_tmp" "$COST_BRIDGE_FILE" 2>/dev/null || true
 
@@ -232,7 +250,12 @@ fi
 # 8. PR number — cached by branch to avoid gh call on every refresh
 # ---------------------------------------------------------------------------
 pr_display=""
-if [[ -n "$git_branch" ]] && command -v gh >/dev/null 2>&1; then
+if [[ -n "$gh_pr_number" ]]; then
+    pr_display="PR #${gh_pr_number}"
+    if [[ -n "$gh_pr_state" && "$gh_pr_state" != "OPEN" ]]; then
+        pr_display="${pr_display} ${gh_pr_state}"
+    fi
+elif [[ -n "$git_branch" ]] && command -v gh >/dev/null 2>&1; then
     cache_file="/tmp/statusline-pr-${project_name}"
     cached_branch=""
     cached_pr=""
@@ -360,6 +383,12 @@ if [[ -n "$wl_display" ]]; then
     wl_segment=" | ${wl_color}${wl_display}${COLOR_RESET}"
 fi
 
+# Build the active agent count segment from statusline JSON when available.
+agent_segment=""
+if [[ "$agent_count" -gt 0 ]]; then
+    agent_segment=" | A:${agent_count}"
+fi
+
 # Build the RTK segment from the session-env bridge if available.
 rtk_segment=""
 env_status_file="/tmp/.codex-env-status-${PPID}"
@@ -380,22 +409,24 @@ if [[ -f "$env_status_file" ]]; then
 fi
 
 if [[ -n "$git_branch" ]]; then
-    printf "${cost_color}%s${COLOR_RESET} | %s | %s%s%s%s%s | ${ctx_color}%s${COLOR_RESET}\n" \
+    printf "${cost_color}%s${COLOR_RESET} | %s | %s%s%s%s%s%s | ${ctx_color}%s${COLOR_RESET}\n" \
         "$cost_display" \
         "$project_name" \
         "$branch_display" \
         "$pr_segment" \
         "$rl_segment" \
         "$wl_segment" \
+        "$agent_segment" \
         "$rtk_segment" \
         "$ctx_display"
 else
-    printf "${cost_color}%s${COLOR_RESET} | %s%s%s%s%s | ${ctx_color}%s${COLOR_RESET}\n" \
+    printf "${cost_color}%s${COLOR_RESET} | %s%s%s%s%s%s | ${ctx_color}%s${COLOR_RESET}\n" \
         "$cost_display" \
         "$project_name" \
         "$pr_segment" \
         "$rl_segment" \
         "$wl_segment" \
+        "$agent_segment" \
         "$rtk_segment" \
         "$ctx_display"
 fi

package/templates/AGENTS.md.en

@@ -135,7 +135,7 @@ project/
 |   +-- contexts/                # Context files (ecomode)
 +-- .agents/
 |   +-- skills/                  # Installed skills (123 directories)
-+-- guides/                      # Reference docs (48 topics)
++-- guides/                      # Reference docs (50 topics)
 ```
 
 ## Orchestration

package/templates/AGENTS.md.ko

@@ -135,7 +135,7 @@ project/
 |   +-- contexts/                # 컨텍스트 파일 (ecomode)
 +-- .agents/
 |   +-- skills/                  # 설치된 스킬 (123 디렉토리)
-+-- guides/                      # 레퍼런스 문서 (48 토픽)
++-- guides/                      # 레퍼런스 문서 (50 토픽)
 ```
 
 ## 오케스트레이션

package/templates/CLAUDE.md

@@ -120,7 +120,7 @@ project/
 |   +-- contexts/                # 컨텍스트 파일 (ecomode)
 +-- .agents/
 |   +-- skills/                  # 스킬 (123 디렉토리)
-+-- guides/                      # 레퍼런스 문서 (48 토픽)
++-- guides/                      # 레퍼런스 문서 (50 토픽)
 ```
 
 ## 오케스트레이션

package/templates/CLAUDE.md.en

@@ -137,7 +137,7 @@ project/
 |   +-- rules/                   # Global rules (22 files)
 |   +-- hooks/                   # Hook scripts (security, validation, HUD)
 |   +-- contexts/                # Context files (4 files)
-+-- guides/                      # Reference docs (48 topics)
++-- guides/                      # Reference docs (50 topics)
 ```
 
 ## Orchestration

package/templates/CLAUDE.md.ko

@@ -137,7 +137,7 @@ project/
 |   +-- rules/                   # 전역 규칙 (22 파일)
 |   +-- hooks/                   # 훅 스크립트 (보안, 검증, HUD)
 |   +-- contexts/                # 컨텍스트 파일 (4 파일)
-+-- guides/                      # 레퍼런스 문서 (48 토픽)
++-- guides/                      # 레퍼런스 문서 (50 토픽)
 ```
 
 ## 오케스트레이션

package/templates/README.md

@@ -48,11 +48,11 @@ templates/
 |   +-- agents/                       # agent definitions (49 files)
 |   +-- skills/                       # skill modules (123 SKILL.md files)
 |   +-- rules/                        # global rules (22 files)
-|   +-- hooks/                        # hook registry and scripts (38 scripts)
+|   +-- hooks/                        # hook registry and scripts (40 scripts)
 |   +-- contexts/                     # context files
 |   +-- ontology/                     # ontology and routing metadata
 |   +-- schemas/                      # tool input schemas
-+-- guides/                           # reference docs (48 topics)
++-- guides/                           # reference docs (50 topics)
 ```
 
 ## Components
@@ -77,13 +77,13 @@ Reusable workflow and reference skill modules. During Codex installation these l
 
 Global agent behavior rules. During Codex installation these land under `.codex/rules/`.
 
-### Guides (48)
+### Guides (50)
 
 `templates/guides/*/`
 
 Reference documentation directories copied to installed projects as `guides/`.
 
-### Hooks (38)
+### Hooks (40)
 
 `templates/.claude/hooks/scripts/*.sh`
 

package/templates/guides/agent-teams/troubleshooting.md

@@ -0,0 +1,53 @@
+# Agent Teams Shutdown and tmux Fallback Troubleshooting
+
+This guide ports the old Claude Code shutdown flow into Codex/OMX terms. Use it when an Agent Teams session stops making forward progress during shutdown, cleanup, or handoff.
+
+## Typical Failure Signs
+
+| Symptom | Likely cause | Action |
+| --- | --- | --- |
+| `TeamDelete` refuses to complete | One or more members are still active | Send a final shutdown request, then retry once |
+| Idle notifications repeat without exit | A member saw the request but did not stop | Wait briefly, then fall back to stale-session cleanup |
+| The team looks done but the pane is still attached | The worker is still owned by tmux | Reclaim the owned tmux pane or session before declaring cleanup complete |
+| Progress stops after a member blocks | The member is waiting on a dependency | Reassign or wait silently instead of polling forever |
+
+## Recovery Order
+
+1. Send one explicit shutdown message to the team member or team lead.
+2. Wait for a short, fixed interval.
+3. Try `TeamDelete` again.
+4. If `TeamDelete` still fails and the session is clearly stale, clean up the owned tmux pane or session.
+5. Re-check `.omx/state/` and confirm the active mode is gone.
+
+## Fallback Rules
+
+- Prefer graceful shutdown first: `SendMessage` with a shutdown request, then `TeamDelete`.
+- Use tmux fallback only for stale local cleanup, not as the default path.
+- Do not kill a pane or session that still contains live user work.
+- After fallback cleanup, clear any stale `omx` runtime state that still claims the team is active.
+
+## Codex/OMX Surface Map
+
+| Need | Default surface | Compatibility note |
+| --- | --- | --- |
+| Ask the team to stop | `SendMessage` | Legacy Claude Code shutdown flows may use analogous `/bg` or background-session signals |
+| Remove a finished team | `TeamDelete` | Treat refusal as a state problem, not as permission to spin forever |
+| Kill a stale worker pane | OMX-managed `tmux` session or pane | Claude-specific socket names are compatibility-only references |
+| Clear lingering session state | `.omx/state/` and related runtime files | Do not rely on the pane alone as the source of truth |
+
+## Example Recovery Sequence
+
+```text
+1. SendMessage(team-member, "shutdown request")
+2. Wait for the member to stop producing work
+3. TeamDelete(team)
+4. If TeamDelete still reports active members and the session is stale, kill the owned tmux pane
+5. Re-run the state check and confirm no active OMX mode remains
+```
+
+## Escalate When
+
+- The pane or session is not owned by the current task.
+- Cleanup would interrupt active user work.
+- The same stale team keeps reappearing after cleanup.
+- A shared infra tmux socket or background process is involved.

package/templates/guides/autonomous-challenge-lessons/README.md

@@ -0,0 +1,43 @@
+# Autonomous Challenge Lessons
+
+This guide captures repeatable lessons from long autonomous runs where the agent must inspect an existing challenge environment, produce a fix, and verify the result without frequent human steering.
+
+## Start With Ground Truth
+
+Before implementing a guessed mechanism, check whether the environment already contains an answer artifact, compiled fix, reference binary, fixture, or expected-output file.
+
+Required first-pass questions:
+
+1. Is there a supplied fix artifact, golden output, or reference implementation?
+2. Which runtime version and mapping namespace are actually present?
+3. Which identifiers are proven by code inspection rather than inferred from memory?
+4. Which launcher or environment flags are being used, and what do they mean?
+
+## Repeated Failure Discipline
+
+If the same critical error appears twice, stop repeating the launch or tool call. Re-check the option, permission, process state, or single-instance constraint that may make the command invalid.
+
+Examples:
+
+- Tool permission denial: do not repeat the exact same tool call; switch evidence path.
+- Launcher flag failure: read the flag meaning before another launch.
+- Single-instance process collision: check and clean the process state before relaunch.
+- Background command output loss: locate the output file or rerun through a managed log path.
+
+## Parallel Work Heuristic
+
+When a single command is about to process dozens of independent files, downloads, or checks, split it into bounded parallel lanes instead of making one long opaque shell run.
+
+Use this when:
+
+- There are about 30 or more independent units.
+- Failures can be isolated by chunk.
+- Results can be merged deterministically.
+
+## QA Evidence
+
+QA reports must quote identifiers from the target code before using them. Selectors, `data-testid` values, mapping names, CLI flags, and config keys are not valid unless read or grepped from the project.
+
+## GUI Verification
+
+For visual or interactive tasks, collect direct browser, screenshot, or runtime evidence when possible. If only indirect evidence is available, label it as indirect and explain what could not be captured.