oh-my-customcodex 0.5.0 → 0.5.2

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

@@ -134,8 +134,8 @@ project/
 |   +-- hooks/                   # Hook scripts (security, validation, HUD)
 |   +-- contexts/                # Context files (ecomode)
 +-- .agents/
-|   +-- skills/                  # Installed skills (119 directories)
-+-- guides/                      # Reference docs (27 topics)
+|   +-- skills/                  # Installed skills (123 directories)
++-- guides/                      # Reference docs (50 topics)
 ```
 
 ## Orchestration
@@ -226,6 +226,7 @@ Task tool + routing skills remain the fallback for simple/cost-sensitive tasks.
 | Server | Purpose |
 |--------|---------|
 | omx-memory | Session memory persistence (Chroma-based) |
+| semble | Semantic code search MCP for high-recall repository exploration |
 | context7 | Library documentation lookup MCP server when a project needs it |
 
 ### Setup Commands
@@ -234,6 +235,9 @@ Task tool + routing skills remain the fallback for simple/cost-sensitive tasks.
 # MCP setup (omx-memory)
 npm install -g omx-memory
 omx-memory setup
+
+# Optional semantic code search
+uv tool install semble
 ```
 
 ### Claude Code Compatibility Note

package/templates/AGENTS.md.ko

@@ -134,8 +134,8 @@ project/
 |   +-- hooks/                   # 훅 스크립트 (보안, 검증, HUD)
 |   +-- contexts/                # 컨텍스트 파일 (ecomode)
 +-- .agents/
-|   +-- skills/                  # 설치된 스킬 (119 디렉토리)
-+-- guides/                      # 레퍼런스 문서 (27 토픽)
+|   +-- skills/                  # 설치된 스킬 (123 디렉토리)
++-- guides/                      # 레퍼런스 문서 (50 토픽)
 ```
 
 ## 오케스트레이션
@@ -226,6 +226,7 @@ Codex CLI의 Agent Teams 기능이 활성화되어 있으면 (`OMCODEX_AGENT_TEA
 | 서버 | 용도 |
 |------|------|
 | omx-memory | 세션 메모리 영속성 (Chroma 기반) |
+| semble | 대규모 저장소 탐색용 semantic code search MCP |
 | context7 | 라이브러리 문서 조회용 MCP 서버 (프로젝트 필요 시 설정) |
 
 ### 설치 명령어
@@ -234,6 +235,9 @@ Codex CLI의 Agent Teams 기능이 활성화되어 있으면 (`OMCODEX_AGENT_TEA
 # MCP 설정 (omx-memory)
 npm install -g omx-memory
 omx-memory setup
+
+# 선택: semantic code search
+uv tool install semble
 ```
 
 ### Claude Code 호환 참고

package/templates/CLAUDE.md

@@ -119,8 +119,8 @@ project/
 |   +-- hooks/                   # 훅 스크립트 (보안, 검증, HUD)
 |   +-- contexts/                # 컨텍스트 파일 (ecomode)
 +-- .agents/
-|   +-- skills/                  # 스킬 (119 디렉토리)
-+-- guides/                      # 레퍼런스 문서 (40 토픽)
+|   +-- skills/                  # 스킬 (123 디렉토리)
++-- guides/                      # 레퍼런스 문서 (50 토픽)
 ```
 
 ## 오케스트레이션
@@ -244,6 +244,7 @@ Codex CLI의 Agent Teams 기능이 활성화되어 있으면 (`OMCODEX_AGENT_TEA
 | 서버 | 용도 |
 |------|------|
 | omx-memory | 세션 메모리 영속성 |
+| semble | 대규모 저장소 탐색용 semantic code search MCP |
 
 ### 설치 명령어
 
@@ -267,6 +268,9 @@ claude agents
 
 # MCP 설정 (omx-memory)
 omx memory doctor
+
+# 선택: semantic code search
+uv tool install semble
 ```
 
 <!-- omcodex:git-workflow -->

package/templates/CLAUDE.md.en

@@ -133,11 +133,11 @@ project/
 +-- AGENTS.md                    # Entry point
 +-- .codex/
 |   +-- agents/                  # Subagent definitions (49 files)
-|   +-- skills/                  # Skills (119 directories)
+|   +-- skills/                  # Skills (123 directories)
 |   +-- rules/                   # Global rules (22 files)
 |   +-- hooks/                   # Hook scripts (security, validation, HUD)
 |   +-- contexts/                # Context files (4 files)
-+-- guides/                      # Reference docs (40 topics)
++-- guides/                      # Reference docs (50 topics)
 ```
 
 ## Orchestration
@@ -240,6 +240,7 @@ Install in Claude Code via `/plugin install <name>`:
 | Server | Purpose |
 |--------|---------|
 | omx-memory | Session memory persistence |
+| semble | Semantic code search MCP for high-recall repository exploration |
 
 ### Claude Code Setup Commands
 
@@ -263,6 +264,9 @@ claude agents
 
 # MCP setup (omx-memory)
 omx memory doctor
+
+# Optional semantic code search
+uv tool install semble
 ```
 
 <!-- omcodex:git-workflow -->

package/templates/CLAUDE.md.ko

@@ -133,11 +133,11 @@ project/
 +-- AGENTS.md                    # 진입점
 +-- .codex/
 |   +-- agents/                  # 서브에이전트 정의 (49 파일)
-|   +-- skills/                  # 스킬 (119 디렉토리)
+|   +-- skills/                  # 스킬 (123 디렉토리)
 |   +-- rules/                   # 전역 규칙 (22 파일)
 |   +-- hooks/                   # 훅 스크립트 (보안, 검증, HUD)
 |   +-- contexts/                # 컨텍스트 파일 (4 파일)
-+-- guides/                      # 레퍼런스 문서 (40 토픽)
++-- guides/                      # 레퍼런스 문서 (50 토픽)
 ```
 
 ## 오케스트레이션
@@ -240,6 +240,7 @@ Claude Code 환경에서 `/plugin install <이름>`으로 설치:
 | 서버 | 용도 |
 |------|------|
 | omx-memory | 세션 메모리 영속성 |
+| semble | 대규모 저장소 탐색용 semantic code search MCP |
 
 ### Claude Code 설치 명령어
 
@@ -263,6 +264,9 @@ claude agents
 
 # MCP 설정 (omx-memory)
 omx memory doctor
+
+# 선택: semantic code search
+uv tool install semble
 ```
 
 <!-- omcodex:git-workflow -->

package/templates/README.md

@@ -0,0 +1,110 @@
+# templates/
+
+> **oh-my-customcodex distribution directory**
+>
+> Source files copied or transformed when `omcustomcodex init` installs the harness into a project.
+
+## Purpose
+
+`templates/` is the packaged distribution snapshot for oh-my-customcodex.
+
+The installer maps the Claude-compatible template tree into the Codex-native runtime layout:
+
+```text
+oh-my-customcodex source repo
+  templates/
+    .claude/                  # compatibility template source
+    guides/                   # reference documentation
+    AGENTS.md.en              # Codex entry template
+    AGENTS.md.ko
+
+installed project
+  .codex/                     # Codex-native agents, rules, hooks, contexts, ontology
+  .agents/skills/             # installed runtime skills
+  guides/                     # reference documentation
+  AGENTS.md                   # project entrypoint
+```
+
+The repository keeps `.codex/**` as the authoring surface. `templates/.claude/**` remains a compatibility source that the installer maps into the target Codex layout.
+
+## Main README Relationship
+
+| Document | Audience | Purpose |
+|----------|----------|---------|
+| [`/README.md`](../README.md) | Users of the npm package | Project overview, install command, philosophy |
+| `templates/README.md` | Maintainers | Distribution layout, component counts, sync checks |
+
+## Directory Structure
+
+```text
+templates/
++-- README.md                         # this file
++-- AGENTS.md.en                      # Codex entry template, English
++-- AGENTS.md.ko                      # Codex entry template, Korean
++-- CLAUDE.md*                        # Claude compatibility entry templates
++-- manifest.json                     # packaged component metadata
++-- workflows/                        # project-level pipeline definitions
++-- .claude/
+|   +-- agents/                       # agent definitions (49 files)
+|   +-- skills/                       # skill modules (123 SKILL.md files)
+|   +-- rules/                        # global rules (22 files)
+|   +-- hooks/                        # hook registry and scripts (40 scripts)
+|   +-- contexts/                     # context files
+|   +-- ontology/                     # ontology and routing metadata
+|   +-- schemas/                      # tool input schemas
++-- guides/                           # reference docs (50 topics)
+```
+
+## Components
+
+The counts below should stay aligned with `templates/manifest.json`, README component headings, and CI template validation.
+
+### Agents (49)
+
+`templates/.claude/agents/*.md`
+
+Flat agent definition files. During Codex installation these land under `.codex/agents/`.
+
+### Skills (123)
+
+`templates/.claude/skills/*/SKILL.md`
+
+Reusable workflow and reference skill modules. During Codex installation these land under `.agents/skills/`.
+
+### Rules (22)
+
+`templates/.claude/rules/*.md`
+
+Global agent behavior rules. During Codex installation these land under `.codex/rules/`.
+
+### Guides (50)
+
+`templates/guides/*/`
+
+Reference documentation directories copied to installed projects as `guides/`.
+
+### Hooks (40)
+
+`templates/.claude/hooks/scripts/*.sh`
+
+Lifecycle hook scripts copied into `.codex/hooks/scripts/`.
+
+## Local Verification
+
+Run the checks below before publishing a template-affecting change:
+
+```bash
+bash .github/scripts/verify-version-sync.sh
+bun test tests/unit/core/template-validation.test.ts
+```
+
+The CI template-sync job also verifies source/template counts for agents, skills, rules, guides, hook scripts, hook matchers, schemas, and skill scripts.
+
+## Maintainer Notes
+
+When adding or removing an agent, skill, rule, guide, hook, or workflow:
+
+1. Update the source surface under `.codex/**`, `.agents/skills/**`, `guides/**`, or `workflows/**`.
+2. Mirror packaged content under `templates/**` according to the provider mapping.
+3. Update `templates/manifest.json` and visible documentation counts.
+4. Add or update a regression test when the drift could recur.

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.