oh-my-customcodex 0.5.0 → 0.5.1

package/README.md

@@ -13,7 +13,7 @@
 
 **[한국어 문서 (Korean)](./README_ko.md)**
 
-49 agents. 119 skills. 22 rules. One command.
+49 agents. 123 skills. 22 rules. One command.
 
 ```bash
 npm install -g oh-my-customcodex && cd your-project && omcustomcodex init
@@ -134,7 +134,7 @@ Each agent declares its tools, model, memory scope, and limitations in YAML fron
 
 ---
 
-### Skills (119)
+### Skills (123)
 
 | Category | Count | Includes |
 |----------|-------|----------|
@@ -287,7 +287,7 @@ your-project/
 │   ├── contexts/               # 4 shared context files
 │   └── ontology/               # Knowledge graph for RAG
 ├── .agents/
-│   └── skills/                 # 119 installed skill modules
+│   └── skills/                 # 123 installed skill modules
 └── guides/                     # 48 reference documents
 ```
 
@@ -325,7 +325,7 @@ bun test             # Run tests
 bun run build        # Production build
 ```
 
-Requirements: Node.js >= 18.0.0, Codex CLI.
+Requirements: Node.js >= 18.0.0, Bun, Codex CLI. GitHub CLI (`gh`) and `jq` are recommended for release automation and local hook validation.
 
 ---
 

package/dist/cli/index.js

@@ -3091,7 +3091,7 @@ var init_package = __esm(() => {
     workspaces: [
       "packages/*"
     ],
-    version: "0.5.0",
+    version: "0.5.1",
     requiresCC: ">=2.1.121",
     claudeCode: {
       minimumVersion: "2.1.121",

package/dist/index.js

@@ -2180,7 +2180,7 @@ var package_default = {
   workspaces: [
     "packages/*"
   ],
-  version: "0.5.0",
+  version: "0.5.1",
   requiresCC: ">=2.1.121",
   claudeCode: {
     minimumVersion: "2.1.121",

package/package.json

@@ -3,7 +3,7 @@
   "workspaces": [
     "packages/*"
   ],
-  "version": "0.5.0",
+  "version": "0.5.1",
   "requiresCC": ">=2.1.121",
   "claudeCode": {
     "minimumVersion": "2.1.121",

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

@@ -5,9 +5,9 @@
 ## Architecture
 
 **Primary**: Native auto memory (`memory` field in agent frontmatter). No external dependencies.
-**Supplementary**: claude-mem MCP (optional, for cross-session search and temporal queries).
+**Supplementary**: AgentMemory-compatible MCP or `omx-memory` for cross-session searchable recall; legacy `claude-mem` is fallback only.
 
-Rule: If native auto memory can handle it, do NOT use claude-mem.
+Rule: If native auto memory can handle it, do NOT use a searchable MCP backend.
 
 ## Native Auto Memory
 
@@ -22,15 +22,23 @@ Agent frontmatter `memory: project|user|local` enables persistent memory:
 | `project` | `.codex/agent-memory/<name>/` | Yes |
 | `local` | `.codex/agent-memory-local/<name>/` | No |
 
-## When to Use claude-mem
+## When to Use Searchable MCP Memory
 
-| Scenario | Native | claude-mem |
+| Scenario | Native | AgentMemory-compatible / omx-memory |
 |----------|--------|------------|
 | Agent learns project patterns | Yes | |
 | Search across sessions | | Yes |
 | Temporal queries | | Yes |
 | Cross-agent sharing | | Yes |
 
+<!-- DETAIL: Backend Selection and Split-Brain Guard
+
+Prefer MCP tools named `memory_search`, `memory_add`, `observation_add`, and `memory_read`. Treat `chroma_query_documents`, `chroma_add_documents`, and `chroma_get_documents` as legacy `claude-mem` fallbacks.
+
+If both backend families are available, warn before writing. Dual-write is acceptable only during an explicit migration window; outside that window, choose one canonical searchable backend and record which one was used in the session summary.
+
+-->
+
 ## Best Practices
 
 - Consult memory before starting work
@@ -324,20 +332,21 @@ User signals session end
        2. Update native auto-memory (MEMORY.md)
        3. Return formatted summary to orchestrator
   → Orchestrator performs MCP saves directly:
-       1. claude-mem save (if available via ToolSearch)
+       1. searchable memory save (AgentMemory-compatible or omx-memory, if available via ToolSearch)
+       2. legacy claude-mem save only when it is the configured fallback
        (episodic-memory auto-indexes after session — no action needed)
   → Orchestrator confirms to user
 ```
 
 ### Responsibility Split
 
-MCP tools (claude-mem, episodic-memory) are **orchestrator-scoped** and not inherited by subagents. Therefore:
+MCP tools (searchable memory backends, episodic-memory) are **orchestrator-scoped** and not inherited by subagents. Therefore:
 
 | Responsibility | Owner | Reason |
 |----------------|-------|--------|
 | Session summary collection | sys-memory-keeper | Domain expertise in memory formatting |
 | Native auto-memory (MEMORY.md) | sys-memory-keeper | Has Write access to memory directory |
-| claude-mem MCP save | Orchestrator | MCP tools only available at orchestrator level |
+| Searchable memory MCP save | Orchestrator | MCP tools only available at orchestrator level |
 | episodic-memory | Automatic | Conversations are auto-indexed after session ends — no manual action needed |
 
 ### Dual-System Save
@@ -345,13 +354,14 @@ MCP tools (claude-mem, episodic-memory) are **orchestrator-scoped** and not inhe
 | System | Owner | Tool | Action | Required |
 |--------|-------|------|--------|----------|
 | Native auto-memory | sys-memory-keeper | Write | Update MEMORY.md with session learnings | Yes |
-| claude-mem | Orchestrator | `mcp__plugin_claude-mem_mcp-search__save_memory` | Save session summary with project, tasks, decisions | No (best-effort) |
+| AgentMemory-compatible / omx-memory | Orchestrator | `memory_add` or `observation_add` | Save session summary with project, tasks, decisions | No (best-effort) |
+| legacy claude-mem | Orchestrator | `chroma_add_documents` or compatible save wrapper | Fallback searchable save when no preferred backend exists | No (best-effort) |
 | episodic-memory | Automatic | (auto-indexed) | No action needed — conversations are indexed automatically after session ends | N/A |
 -->
 
 ### Session-End Self-Check (MANDATORY)
 
-(1) sys-memory-keeper updated MEMORY.md? (2) claude-mem save attempted? 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? Both are required before confirming session-end to the user. See full self-check via Read tool.
 
 <!-- DETAIL: Session-End Self-Check (MANDATORY)
 ```
@@ -362,7 +372,7 @@ MCP tools (claude-mem, episodic-memory) are **orchestrator-scoped** and not inhe
 ║     YES → Continue                                               ║
 ║     NO  → Delegate to sys-memory-keeper first                    ║
 ║                                                                   ║
-║  2. Did I attempt claude-mem save?                               ║
+║  2. Did I attempt searchable memory save when available?         ║
 ║     YES → Continue (even if it failed)                           ║
 ║     NO  → ToolSearch + save now                                  ║
 ║                                                                   ║
@@ -379,5 +389,5 @@ MCP tools (claude-mem, episodic-memory) are **orchestrator-scoped** and not inhe
 ### Failure Policy
 
 - MCP saves are **non-blocking**: memory failure MUST NOT prevent session from ending
-- If claude-mem unavailable: skip, log warning
+- If no searchable memory backend is available: skip, log warning
 - episodic-memory: no action needed (auto-indexed after session)

package/templates/.claude/skills/adversarial-review/SKILL.md

@@ -12,6 +12,16 @@ Review code from an attacker's perspective using STRIDE + OWASP frameworks.
 
 ## 4-Phase Review Process
 
+### Pre-flight: CRG Attack-Surface Probe
+If a code-review graph or CRG MCP server is available, use it before manual inspection:
+
+```text
+Preferred: query_graph({ target, focus: "trust-boundaries attack-surface data-flow" })
+Fallback: get_impact_radius({ target })
+```
+
+Use the result to seed trust-boundary, data-flow, and dependency-risk analysis. If CRG tools are unavailable, continue with local `rg`, route inspection, and dependency/file reads; CRG is advisory and must not block adversarial review.
+
 ### Phase 1: Trust Boundary Analysis
 Identify where trust transitions occur:
 - External input reaching internal logic without validation → **Tampering**

package/templates/.claude/skills/dev-review/SKILL.md

@@ -85,6 +85,15 @@ If any GATE: block and suggest alternative.
 If any WARN: show warning, ask user to confirm.
 If only PASS/INFO: proceed automatically.
 
+### Guard 5: Review Graph Context Probe
+**Level**: INFO
+**Check**: If a code-review graph or CRG MCP server is available, query impact radius before selecting the expert:
+```text
+Preferred: get_impact_radius({ target })
+Fallback: get_minimal_context({ target, purpose: "dev-review" })
+```
+**Action**: Attach the returned affected files, owners, and dependency edges to the review prompt. If the CRG tools are unavailable or time out, continue with `rg`, `git diff`, and local file reads; CRG is advisory and must not block review.
+
 ## Parameters
 
 | Name | Type | Required | Description |
@@ -105,12 +114,13 @@ If only PASS/INFO: proceed automatically.
 ```
 0. Run pre-flight guards (see ## Pre-flight Guards)
 1. Detect language (or use --lang)
-2. Select appropriate expert agent
-3. Load language-specific skill
-4. Analyze code against best practices
-5. Generate review report
+2. Include CRG impact context when available
+3. Select appropriate expert agent
+4. Load language-specific skill
+5. Analyze code against best practices
+6. Generate review report
 ```
-6. **Artifact persistence** (optional): Review agent saves findings to:
+7. **Artifact persistence** (optional): Review agent saves findings to:
    ```
    .codex/outputs/sessions/{YYYY-MM-DD}/dev-review-{HHmmss}.md
 

package/templates/.claude/skills/harness-export/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: harness-export
+description: Export-plan generator for translating oh-my-customcodex assets to other agent harness formats
+scope: harness
+version: 0.1.0
+user-invocable: true
+argument-hint: "--target cursor|codex|opencode|zed|gemini|copilot [--dry-run]"
+---
+
+# Harness Export
+
+Generate a dry-run export plan from oh-my-customcodex assets into another agent harness format. This is intentionally conservative: the skill documents mapping and risks before writing any external harness files.
+
+## Boundary Decision
+
+Cross-harness export is an adapter layer, not a new core metaphor. Skills remain source, agents remain build artifacts, rules remain compiler specs, and export output is a derived compatibility artifact.
+
+Default mode is `--dry-run`. Writing export files requires a separate explicit task because target formats change independently and can create maintenance debt.
+
+## Targets
+
+| Target | Output Shape |
+|--------|--------------|
+| `cursor` | rules and agent instructions mapped to Cursor project conventions |
+| `codex` | `.codex/**` runtime assets |
+| `opencode` | command/agent guidance bundle |
+| `zed` | assistant instruction bundle |
+| `gemini` | prompt and context bundle |
+| `copilot` | repository instructions and chat modes |
+
+## Workflow
+
+1. Read `templates/manifest.json` and current asset counts.
+2. Select source assets by target capability.
+3. Produce a mapping table: source path, target path, transform, lossiness.
+4. Flag unsupported concepts such as memory scope, hooks, MCP tools, or permission mode.
+5. Emit a dry-run report and stop unless the user explicitly requested writes.
+
+## Output
+
+```text
+harness-export target=cursor mode=dry-run
+mapped: skills=18 rules=7 agents=6
+lossy: hooks, memory scope, MCP server config
+decision: export plan only
+```

package/templates/.claude/skills/instinct-extractor/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: instinct-extractor
+description: Extract reusable workflow instincts from git history, sessions, and task outcomes with confidence scoring
+scope: harness
+version: 1.0.0
+user-invocable: true
+argument-hint: "[--since <date>] [--source git|sessions|outcomes|all] [--min-confidence low|medium|high]"
+---
+
+# Instinct Extractor
+
+Find repeated operator or agent behavior that should become a rule, skill, guide, memory entry, or evaluation case.
+
+## Inputs
+
+| Source | Evidence |
+|--------|----------|
+| `git` | Commit messages, changed paths, reverted fixes, recurring file clusters |
+| `sessions` | `.codex/outputs/sessions/**`, pipeline artifacts, review reports |
+| `outcomes` | Task outcome JSONL, hook telemetry, verification failures |
+| `all` | Combined evidence with deduplication |
+
+## Confidence
+
+| Confidence | Requirement |
+|------------|-------------|
+| `low` | One clear event with plausible reuse |
+| `medium` | Two or more independent events or one tested release finding |
+| `high` | Repeated events plus passing verification or explicit user confirmation |
+
+## Workflow
+
+1. Collect bounded evidence for the requested source.
+2. Cluster repeated failures, decisions, and successful recovery patterns.
+3. Classify each candidate:
+   - `memory` for project/user behavior
+   - `rule` for durable safety constraints
+   - `skill` for repeatable workflows
+   - `guide` for reference knowledge
+   - `eval` for regression checks
+4. Assign confidence and cite concrete files, commits, or artifacts.
+5. Emit proposals only; do not create new rules or skills without an explicit follow-up task.
+
+## Output
+
+```text
+candidate: release-version-sync-preflight
+type: skill
+confidence: high
+evidence:
+  - .github/scripts/verify-version-sync.sh
+  - workflows/auto-dev.yaml
+recommendation: keep as release pipeline gate
+```

package/templates/.claude/skills/manifest-install/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: manifest-install
+description: Selective manifest-driven installation profiles for oh-my-customcodex assets
+scope: harness
+version: 1.0.0
+user-invocable: true
+argument-hint: "--profile minimal|standard|full|codex|claude [--target <dir>] [--dry-run]"
+---
+
+# Manifest Install
+
+Install only the agent-stack assets a project profile needs, while keeping the package manifest, template tree, and Codex runtime layout consistent.
+
+## Use When
+
+- A user wants a smaller install than the full template bundle.
+- Release work changes `templates/manifest.json` or component counts.
+- A project needs Codex-native assets without optional Claude compatibility mirrors.
+
+## Profiles
+
+| Profile | Includes | Excludes |
+|---------|----------|----------|
+| `minimal` | AGENTS, core rules, routing skills, status/help, git safety | specialist language packs, optional guides |
+| `standard` | minimal + common dev/review/test skills and agents | niche provider guides |
+| `full` | every packaged template asset | nothing |
+| `codex` | `.codex/**`, AGENTS, guides, workflows | `.claude/**` compatibility mirrors |
+| `claude` | Claude compatibility mirrors and CLAUDE entry files | Codex-only runtime state |
+
+## Workflow
+
+1. Read `templates/manifest.json`.
+2. Resolve profile include/exclude rules.
+3. Produce an install plan with paths, counts, and skipped components.
+4. Dry-run by default for destructive replacements.
+5. Apply by copying only planned paths and preserving user-owned files.
+6. Recount components and report drift.
+
+## Safety
+
+- Never delete user files that are outside the generated asset set.
+- Preserve `.codex/agent-memory*/`, local settings, and outputs.
+- Treat count mismatch as a halt condition unless `--dry-run` was requested.
+- Use `omcustomcodex` in operator guidance.
+
+## Output
+
+```text
+manifest-install profile=standard target=.
+planned: rules=22 agents=49 skills=123 guides=48
+skipped: compatibility mirrors, optional provider guides
+status: dry-run
+```

package/templates/.claude/skills/memory-management/SKILL.md

@@ -1,13 +1,21 @@
 ---
 name: memory-management
-description: Memory persistence operations using claude-mem
+description: Memory persistence operations using native memory plus omx-memory or AgentMemory-compatible MCP backends
 scope: core
 user-invocable: false
 ---
 
 ## Purpose
 
-Provide memory persistence operations using claude-mem for session context survival across compactions.
+Provide memory persistence operations using native `MEMORY.md` first, then a searchable MCP backend for cross-session retrieval. Prefer an AgentMemory-compatible or `omx-memory` backend exposing `memory_search`, `memory_add`, and `observation_add`; use legacy `claude-mem` only as a fallback when that is the configured backend.
+
+## Backend Order
+
+1. Native auto-memory: compact durable facts in `MEMORY.md`.
+2. AgentMemory-compatible MCP or `omx-memory`: cross-session search, shared observations, and temporal recall.
+3. Legacy `claude-mem`: fallback only when the project still exposes Chroma tools.
+
+When both legacy `claude-mem` and an AgentMemory-compatible backend are active, warn about split-brain storage. Dual-write is allowed only during an explicit migration window.
 
 ## Operations
 
@@ -15,7 +23,7 @@ Provide memory persistence operations using claude-mem for session context survi
 
 ```yaml
 operation: save
-description: Store session context in claude-mem
+description: Store session context in the configured searchable memory backend
 steps:
   1. Collect session data:
      - Tasks completed
@@ -26,8 +34,10 @@ steps:
      - Add project tag: "my-project"
      - Add session ID: {date}-{uuid}
      - Add relevant tags
-  3. Store in claude-mem:
-     - Use chroma_add_documents
+  3. Store in configured backend:
+     - Prefer memory_add for session summaries
+     - Use observation_add for atomic behavioral or project observations
+     - Legacy fallback: chroma_add_documents
      - Include metadata
 ```
 
@@ -41,8 +51,9 @@ steps:
      - Always prefix with "my-project"
      - Add user-provided search terms
      - Include date for temporal searches
-  2. Search claude-mem:
-     - Use chroma_query_documents
+  2. Search configured backend:
+     - Prefer memory_search
+     - Legacy fallback: chroma_query_documents
      - Request top N results
   3. Format results:
      - Sort by relevance
@@ -56,8 +67,9 @@ steps:
 operation: get
 description: Retrieve specific memory by ID
 steps:
-  1. Use chroma_get_documents with ID
-  2. Return full document content
+  1. Prefer memory_read or memory_search by ID
+  2. Legacy fallback: chroma_get_documents with ID
+  3. Return full document content
 ```
 
 ## Query Patterns
@@ -66,17 +78,20 @@ steps:
 
 ```python
 # Always include project name
+memory_search({ query: "my-project {search_terms}", limit: 8 })
+
+# Legacy fallback
 chroma_query_documents(["my-project {search_terms}"])
 
 # Examples:
-chroma_query_documents(["my-project authentication flow"])
-chroma_query_documents(["my-project 2025-01-24 memory system"])
+memory_search({ query: "my-project authentication flow", limit: 5 })
+memory_search({ query: "my-project 2025-01-24 memory system", limit: 5 })
 ```
 
 ### Get by ID
 
 ```python
-# When you have a specific document ID
+# When you have a specific document ID and only legacy tools are available
 chroma_get_documents(ids=["document_id"])
 ```
 
@@ -194,3 +209,47 @@ recall_errors:
   - Connection failure: Return empty with warning
   - Invalid query: Help user reformulate
 ```
+
+## MemKraft Bridge (Optional)
+
+> External integration: [MemKraft](https://github.com/seojoonkim/memkraft) — zero-dependency compound memory for AI agents.
+> Install: `pipx install memkraft`
+
+### When to Use
+
+| Capability | Searchable MCP | MemKraft |
+|-----------|-----------|----------|
+| Session persistence | ✅ (Chroma) | ✅ (Markdown) |
+| Entity tracking | ❌ | ✅ (person/org/concept) |
+| Source attribution | ❌ | ✅ (`[Source: who, when, how]`) |
+| Auto-maintenance | ❌ | ✅ (Dream Cycle) |
+| CJK entity extraction | ❌ | ✅ (Korean/Chinese/Japanese) |
+| Offline search | ❌ | ✅ (stdlib difflib) |
+
+Use MemKraft when entity tracking or source attribution is needed. Use the configured AgentMemory-compatible or `omx-memory` backend for searchable session persistence.
+
+### Commands
+
+```bash
+# Extract entities from a document
+memkraft extract <file>
+
+# Get a brief on a topic
+memkraft brief <topic>
+
+# Run maintenance cycle (dedup, prune orphans)
+memkraft dream
+```
+
+### Integration with sys-memory-keeper
+
+At session end, sys-memory-keeper can optionally run MemKraft operations:
+
+1. `memkraft extract` on session summary → builds entity graph
+2. `memkraft dream` → prunes stale entries (run weekly, not every session)
+
+### Prerequisites
+
+- Python 3.9+
+- `pipx install memkraft`
+- No API keys required (offline-only)

package/templates/.claude/skills/memory-recall/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory-recall
-description: Search and recall memories from claude-mem
+description: Search and recall memories from native memory plus omx-memory or AgentMemory-compatible backends
 scope: core
 argument-hint: "<query> [--recent] [--limit <n>]"
 user-invocable: true
@@ -8,7 +8,7 @@ user-invocable: true
 
 # Memory Recall Skill
 
-Search and recall relevant memories from claude-mem using semantic search.
+Search and recall relevant memories from native `MEMORY.md` plus the configured searchable MCP backend. Prefer AgentMemory-compatible or `omx-memory` tools (`memory_search`, `memory_read`); fall back to legacy `claude-mem` Chroma tools only when those are the configured backend.
 
 ## Parameters
 
@@ -33,8 +33,9 @@ Search and recall relevant memories from claude-mem using semantic search.
    ├── Add user query terms
    └── Include date if specified
 
-2. Search claude-mem
-   └── chroma_query_documents
+2. Search configured backend
+   ├── Prefer memory_search
+   └── Legacy fallback: chroma_query_documents
 
 3. Format results
    ├── Sort by relevance score
@@ -170,3 +171,4 @@ Suggestions:
 ## Related
 
 - memory-save - Save current context
+- memory-management - Backend selection and split-brain safeguards

package/templates/.claude/skills/memory-save/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory-save
-description: Save current session context to claude-mem
+description: Save current session context to native memory plus omx-memory or AgentMemory-compatible backends
 scope: core
 argument-hint: "[--tags <tags>] [--include-code]"
 disable-model-invocation: true
@@ -9,7 +9,7 @@ user-invocable: true
 
 # Memory Save Skill
 
-Save current session context to claude-mem for persistence across context compaction.
+Save current session context to native memory and the configured searchable MCP backend for persistence across context compaction. Prefer AgentMemory-compatible or `omx-memory` tools (`memory_add`, `observation_add`); fall back to legacy `claude-mem` only when that is the configured backend.
 
 ## Options
 
@@ -35,8 +35,10 @@ Save current session context to claude-mem for persistence across context compac
    ├── tags: [session, ...user_tags]
    └── created_at: {timestamp}
 
-3. Store in claude-mem
-   └── chroma_add_documents
+3. Store in configured backend
+   ├── Prefer memory_add for summaries
+   ├── Prefer observation_add for atomic learnings
+   └── Legacy fallback: chroma_add_documents
 
 4. Report result
 ```
@@ -112,7 +114,7 @@ Open Items:
   1. Refresh token implementation
      Status: In progress
 
-Saving to claude-mem...
+Saving to configured memory backend...
 
 Document content:
   ## Session Summary
@@ -126,3 +128,4 @@ Memory ID: mem_abc123
 ## Related
 
 - memory-recall - Search and recall memories
+- memory-management - Backend selection and migration safeguards

package/templates/.claude/skills/pipeline/labels.md

@@ -0,0 +1,55 @@
+# Pipeline Label Standards
+
+Canonical reference for GitHub issue label semantics in the auto-dev pipeline.
+Used by `scope-selection` to include or exclude issues and by `implement` for lifecycle management.
+
+## Label Definitions
+
+| Label | Meaning | scope-selection handling |
+|-------|---------|--------------------------|
+| `verify-ready` | Triage complete, ready for verification or automation | INCLUDE (preferred) |
+| `verify-done` | Triage complete but deferred, already handled, or excluded from this cycle | EXCLUDE |
+| `in-progress` | Work is claimed by another session | EXCLUDE |
+| `needs-review` | Human review is required before automation | EXCLUDE |
+| `decision-needed` | Security, policy, or product decision required | EXCLUDE |
+| `automated` | Auto-generated issue from release-monitor tooling | INCLUDE if other criteria match |
+| `codex-release` | Codex release monitor trigger | INCLUDE (preferred) |
+| `oh-my-codex-release` | oh-my-codex release monitor trigger | INCLUDE (preferred) |
+| `claude-code-release` | Claude compatibility release trigger | INCLUDE (preferred) |
+| `documentation` | Documentation-only scope | INCLUDE (preferred for docs-only release) |
+| `enhancement-yaml-only` | YAML/config-only scope change | INCLUDE (eligible for docs-only compression) |
+
+## Selection Rule
+
+```text
+EXCLUDE if:
+  - blocked_by_decision == true
+  - labels intersect {decision-needed, needs-review, verify-done, manual-action, in-progress}
+
+INCLUDE (preferred tier):
+  - labels intersect {verify-ready, codex-release, oh-my-codex-release, claude-code-release, documentation}
+
+INCLUDE (standard tier):
+  - P1/P2/P3 issues not in excluded set
+
+Tie-break priority: P1 > P2 > P3 > unclassified
+```
+
+## Compression Eligibility
+
+An issue is eligible for `docs-only` compression mode if its labels include at least one of:
+`documentation`, `automated`, `codex-release`, `oh-my-codex-release`, `claude-code-release`, `enhancement-yaml-only`.
+
+If all scoped issues are compression-eligible and scope size is 3 or fewer, the pipeline may use
+`compression_mode=docs-only` and replace heavyweight triage, planning, and verification spawns with
+direct manifest summaries plus a local self-review checklist.
+
+## Lifecycle Labels
+
+| Transition | Action |
+|------------|--------|
+| Work started | Add `in-progress`, assign the current operator |
+| Work succeeded | Remove `in-progress`, add `verify-ready` |
+| Work failed | Remove `in-progress`, add `needs-review` |
+| Released | Remove `verify-ready`, close with `Fixed in v{version}` |
+| Deferred | Add `verify-done`, label `Deferred from v{version}` |

package/templates/.claude/skills/sec-agentshield-wrapper/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: sec-agentshield-wrapper
+description: Pre-flight AgentShield-style security suite wrapper for agent harness changes
+scope: harness
+version: 1.0.0
+user-invocable: true
+argument-hint: "<path> [--strict] [--report <file>]"
+---
+
+# AgentShield Wrapper
+
+Run an AgentShield-style pre-flight review before risky agent, skill, hook, or MCP changes. This skill is a wrapper contract: use a connected AgentShield tool when available, otherwise run the local static checks that approximate the same boundary.
+
+## Checks
+
+| Area | What to Inspect |
+|------|-----------------|
+| Tool authority | Agent frontmatter tools, disallowed tools, and permission mode |
+| Prompt injection | Untrusted text flowing into tool instructions or shell commands |
+| Secret exposure | Tokens, private keys, bearer headers, and credential-like literals |
+| Path boundaries | Writes to `.git`, runtime state, templates, and compatibility mirrors |
+| MCP risk | New servers, remote URLs, timeout behavior, and tool naming collisions |
+
+## Workflow
+
+1. Identify changed files with `git diff --name-only` unless a path is supplied.
+2. Prefer an installed AgentShield scanner if one is configured.
+3. Fall back to existing repo checks:
+   - `secret-filter`
+   - schema validator guidance
+   - `adversarial-review`
+   - `cve-triage` for dependency advisories
+4. Report findings as `blocker`, `warn`, or `info`.
+5. In `--strict` mode, halt on any blocker or unreviewed MCP/tool expansion.
+
+## Output
+
+```text
+sec-agentshield-wrapper target=.codex/skills/new-skill
+blocker: 0
+warn: 1
+info: 2
+decision: proceed-with-review
+```
+
+## Notes
+
+- This wrapper complements `sec-codeql-expert`; it does not replace CodeQL or dependency audit.
+- Missing AgentShield tooling is not a failure if local fallback checks run and are reported.

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 (48 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/                      # 레퍼런스 문서 (48 토픽)
 ```
 
 ## 오케스트레이션
@@ -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/                      # 레퍼런스 문서 (48 토픽)
 ```
 
 ## 오케스트레이션
@@ -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 (48 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/                      # 레퍼런스 문서 (48 토픽)
 ```
 
 ## 오케스트레이션
@@ -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 (38 scripts)
+|   +-- contexts/                     # context files
+|   +-- ontology/                     # ontology and routing metadata
+|   +-- schemas/                      # tool input schemas
++-- guides/                           # reference docs (48 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 (48)
+
+`templates/guides/*/`
+
+Reference documentation directories copied to installed projects as `guides/`.
+
+### Hooks (38)
+
+`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/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,24 @@
 
 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.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 +68,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/manifest.json

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

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`.