microsoft · HYS (HuYaSen) · Aug 18, 2026 · Aug 18, 2026 · Aug 18, 2026 · Aug 19, 2026
diff --git a/.github/workflows/cmind-pre-release.yml b/.github/workflows/cmind-pre-release.yml
@@ -38,6 +38,10 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Install release renderer dependency
+        if: steps.check_release.outputs.exists == 'false'
+        run: python -m pip install "pyyaml>=6.0"
+
       - name: Create release package variants
         if: steps.check_release.outputs.exists == 'false'
         run: .github/workflows/scripts/cmind/create-release-packages.sh "${{ steps.get_tag.outputs.new_version }}"

diff --git a/.github/workflows/cmind-release.yml b/.github/workflows/cmind-release.yml
@@ -41,6 +41,10 @@ jobs:
         if: steps.check_release.outputs.exists == 'false'
         run: .github/workflows/scripts/cmind/update-version.sh "${{ steps.get_tag.outputs.new_version }}"
 
+      - name: Install release renderer dependency
+        if: steps.check_release.outputs.exists == 'false'
+        run: python -m pip install "pyyaml>=6.0"
+
       - name: Create release package variants
         if: steps.check_release.outputs.exists == 'false'
         run: .github/workflows/scripts/cmind/create-release-packages.sh "${{ steps.get_tag.outputs.new_version }}"

diff --git a/.github/workflows/scripts/cmind/create-release-packages.ps1 b/.github/workflows/scripts/cmind/create-release-packages.ps1
@@ -56,6 +56,7 @@ if (-not (Test-Path $ProjectRoot)) {
     exit 1
 }
 Set-Location $ProjectRoot
+$PythonBin = if ($env:PYTHON) { $env:PYTHON } else { "python" }
 
 Write-Host "Building release packages for $Version from $ProjectRoot"
 
@@ -320,8 +321,10 @@ function Build-Variant {
             Generate-Commands -Extension 'md' -OutputDir $cmdDir
         }
         'codex' {
-            $cmdDir = Join-Path $baseDir ".codex/prompts"
-            Generate-Commands -Extension 'md' -OutputDir $cmdDir
+            & $PythonBin "src/cmind_cli/_codex_skills.py" "templates/commands" $baseDir
+            if ($LASTEXITCODE -ne 0) {
+                throw "Codex skill rendering failed with exit code $LASTEXITCODE"
+            }
         }
         'codebuddy' {
             $cmdDir = Join-Path $baseDir ".codebuddy/commands"

diff --git a/.github/workflows/scripts/cmind/create-release-packages.sh b/.github/workflows/scripts/cmind/create-release-packages.sh
@@ -230,8 +230,7 @@ SETTINGS
       mkdir -p "$base_dir/.augment/commands"
       generate_commands md "$base_dir/.augment/commands" ;;
     codex)
-      mkdir -p "$base_dir/.codex/prompts"
-      generate_commands md "$base_dir/.codex/prompts" ;;
+      "$PYTHON_BIN" src/cmind_cli/_codex_skills.py templates/commands "$base_dir" ;;
     codebuddy)
       mkdir -p "$base_dir/.codebuddy/commands"
       generate_commands md "$base_dir/.codebuddy/commands" ;;

diff --git a/CoderMind/README.md b/CoderMind/README.md
@@ -93,7 +93,7 @@ Below is part of the graph visualization generated for this repository. After ru
 - Python 3.12+
 - [uv](https://docs.astral.sh/uv/)
 - Git
-- An installed and authenticated AI coding agent CLI: [GitHub Copilot](https://docs.github.com/en/copilot) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code/setup)
+- An installed and authenticated AI coding agent CLI: [GitHub Copilot](https://docs.github.com/en/copilot), [Claude Code](https://docs.anthropic.com/en/docs/claude-code/setup), or [Codex](https://developers.openai.com/codex/cli/)
 
 ### Install CoderMind
 
@@ -219,7 +219,7 @@ cmind update
 | -------------- | --------- | ----------------------- |
 | Claude Code    | ✅        | ✅                      |
 | GitHub Copilot | ✅        | ✅                      |
-| Codex          | ⌛        | ⌛                      |
+| Codex          | ✅        | ⌛                      |
 
 **Operating system support**:
 

diff --git a/CoderMind/docs/cli-reference.md b/CoderMind/docs/cli-reference.md
@@ -16,7 +16,7 @@ cmind init . [options]
 
 | Option | Description |
 | ------ | ----------- |
-| `--ai <agent>` | AI assistant: `copilot` or `claude` |
+| `--ai <agent>` | Default encoder/decoder backend: `copilot`, `claude`, or `codex` |
 | `--script <type>` | Script type: `sh` (POSIX). `ps` (PowerShell) is not yet supported and will be added in a future release. |
 | `--here` | Initialize in current directory |
 | `--force` | Skip confirmation for non-empty current directory |
@@ -28,18 +28,21 @@ cmind init . [options]
 
 ### Supported AI Assistants
 
-| Agent | Folder | Description | Status |
-| ----- | ------ | ----------- | ------ |
-| `copilot` | `.github/`, `.vscode/` | GitHub Copilot | Verified |
-| `claude` | `.claude/` | Claude Code | Verified |
+| Agent | Folder | Invocation | Status |
+| ----- | ------ | ---------- | ------ |
+| `copilot` | `.github/`, `.vscode/` | `/cmind.*` | Verified |
+| `claude` | `.claude/` | `/cmind.*` | Verified |
+| `codex` | `.agents/skills/`, `.codex/` | `$cmind-*` or `/skills` | CLI verified |
 
-CoderMind currently supports only **GitHub Copilot** and **Claude Code** in the CLI. Additional agents may be adapted in future releases.
+All three integrations are generated together. `--ai` selects only the default
+LLM backend used by encoder/decoder pipeline calls.
 
 ### Examples
 
 ```bash
 cmind init my-project
 cmind init my-project --ai claude --script sh
+cmind init my-project --ai codex --script sh
 cmind init . --force
 cmind init . --encode
 cmind init . --force --encode
@@ -48,7 +51,9 @@ cmind init --here --ai copilot
 
 ## `cmind update`
 
-Update CoderMind template files, scripts, command definitions, MCP configuration, gitignore rules, and hooks in an existing project. The AI assistant is auto-detected from existing project configuration when possible.
+Update CoderMind template files, all agent integrations, MCP configuration,
+gitignore rules, and hooks. The active LLM backend is preserved unless `--ai`
+is passed.
 
 ```bash
 cmind update
@@ -61,7 +66,7 @@ cmind update --no-upgrade
 
 | Option | Description |
 | ------ | ----------- |
-| `--ai <agent>` | AI assistant, auto-detected if not specified |
+| `--ai <agent>` | Change the active encoder/decoder backend |
 | `--script <type>` | Script type: `sh` (POSIX). `ps` (PowerShell) is not yet supported and will be added in a future release. |
 | `--no-upgrade` | Skip the default-on CLI self-upgrade and only sync workspace files. |
 | `--no-mcp` | Skip MCP server configuration |
@@ -100,6 +105,18 @@ prints a tree of which ones are available.  Run this after
 installation to confirm the environment is ready, or whenever a
 pipeline step complains about a missing tool.
 
+## `cmind config`
+
+Inspect or switch the active encoder/decoder LLM backend without changing the
+installed Claude, Copilot, or Codex integrations.
+
+```bash
+cmind config show
+cmind config set-agent codex
+cmind config set-agent claude
+cmind config set-agent copilot
+```
+
 ## `cmind version`
 
 Display version and system information.
@@ -140,12 +157,10 @@ cmind script --list
 cmind script --where mcp_server.py
 ```
 
-The slash-command templates installed by `cmind init` (in
-`.claude/commands/` or `.github/agents/`) all use `cmind script …`
-under the hood, so AI agents invoke the pipeline through the same
+The Claude/Copilot commands and Codex skills installed by `cmind init` all use
+`cmind script …` under the hood, so every agent invokes the same pipeline
 contract.
 
 A companion console script, `cmind-mcp`, is the MCP server entry
-point and is what `.mcp.json` / `.vscode/mcp.json` register as the
-`rpg-tools` command — no absolute paths in the config, no per-machine
-edits.
+point and is what `.mcp.json`, `.vscode/mcp.json`, and
+`.codex/config.toml` register as the `rpg-tools` command.
diff --git a/CoderMind/docs/configuration.md b/CoderMind/docs/configuration.md
@@ -14,14 +14,15 @@ Currently verified assistants:
 | ----- | ------------ | ----------------------- | ----------- |
 | GitHub Copilot | `copilot` | `.github/`, `.vscode/` | Copilot CLI available and authenticated |
 | Claude Code | `claude` | `.claude/` | Claude Code CLI available and authenticated |
+| Codex | `codex` | `.agents/skills/`, `.codex/` | Codex CLI available and authenticated |
 
 Use `cmind check` to verify required local tools.
 
 ```bash
 cmind check
 ```
 
-If the selected AI assistant is not found, install and authenticate it, then rerun `cmind init` or `cmind update`.
+If the selected LLM backend is not found, install and authenticate it, then rerun `cmind init` or `cmind update`.
 
 ## Workspace Configuration (`.cmind/config.toml`)
 
@@ -66,7 +67,8 @@ The values written to `ai_cli_cmd` mirror the per-AI substitutions performed by
 | `opencode` | `opencode run` |
 | `amp` | `amp --execute` |
 
-Only `copilot` and `claude` are currently verified end-to-end; the others are scaffolded but may need integration adjustments.
+`copilot`, `claude`, and `codex` are verified end-to-end. The remaining mappings
+are scaffolded but are not exposed as supported backends.
 
 ### Other config keys
 
@@ -79,9 +81,14 @@ The `[cmind]` table currently holds only `ai_cli_cmd`. Future releases will add
 ```bash
 cmind init my-project --ai claude
 cmind init my-project --ai copilot
+cmind init my-project --ai codex
 ```
 
-If `--ai` is omitted in an interactive terminal, CoderMind prompts for a supported assistant.
+All three agent integrations are generated together. `--ai` chooses the default
+encoder/decoder backend. If omitted, CoderMind prompts in an interactive terminal
+and defaults to Copilot in non-interactive environments.
+
+Switch later with `cmind config set-agent <agent>`.
 
 ### Script type
 
@@ -109,6 +116,10 @@ cmind update --no-mcp
 
 Skipping MCP means the slash-command pipeline still works, but the AI assistant will not get the `rpg-tools` graph-query tools automatically.
 
+CoderMind writes project-scoped MCP entries for Claude (`.mcp.json`), Copilot
+(`.vscode/mcp.json`), and Codex (`.codex/config.toml`). Codex user configuration
+under `~/.codex/` and `CODEX_HOME` is never modified.
+
 ### Initial encode
 
 The MCP tools query `.cmind/data/rpg.json`. For existing codebases, that file is created by the encoder.
@@ -173,6 +184,27 @@ For Copilot, CoderMind writes agent instructions under `.github/` and VS Code MC
 
 Open the project in VS Code after initialization so the workspace MCP configuration is available to Copilot.
 
+### Codex
+
+CoderMind renders the shared workflows as repository-scoped skills:
+
+```text
+.agents/skills/
+├── cmind-encode/SKILL.md
+├── cmind-plan/SKILL.md
+└── cmind-code-gen/SKILL.md
+.codex/config.toml              # project-scoped rpg-tools MCP registration
+```
+
+CoderMind skills are explicit-only so they do not compete with ordinary coding
+requests. In Codex CLI, type `$` to select `$cmind-encode`, `$cmind-plan`, and
+the other CoderMind skills, or use `/skills` to browse them. Explicit-only skills
+are intentionally omitted from Codex's model-visible implicit skill list until
+the user invokes one.
+
+Use `$cmind-encode`, `$cmind-plan`, and the other `$cmind-*` skills. Codex also
+discovers them through `/skills`.
+
 ## Auto-approval and Scope
 
 CoderMind pre-authorizes the `rpg-tools` MCP server where the selected assistant supports project-scoped permissions. The goal is to avoid prompting on every graph query during chat.

diff --git a/CoderMind/docs/project-structure.md b/CoderMind/docs/project-structure.md
@@ -4,7 +4,7 @@
 
 CoderMind installs alongside your project code: the directory you run `cmind init` in, also called the workspace root, **is** the project repository root. There is no separate `repo/` subdirectory. This means:
 
-- `cmind init my-project` creates `my-project/` containing both your source code (`src/`, `tests/`, `docs/`) and CoderMind's in-workspace configuration files (`.cmind/config.toml`, `.claude/`, `.github/`, `.vscode/`, depending on the selected agent).
+- `cmind init my-project` creates `my-project/` containing both your source code and all Claude, Copilot, and Codex integrations. The selected `--ai` value controls the encoder/decoder backend only.
 - `cmind init --here` inside an existing git repository adds CoderMind on top of the existing code without moving the repository.
 - A single `.git` repository tracks user-owned code and any CoderMind files the user chooses to commit. **Runtime data, logs, and the inner-git snapshot repo all live outside the workspace** under `~/.cmind/workspaces/<workspace-id>/`, so generated artefacts don't pollute your repo or accidentally get committed. Only a small set of user-facing files (`.cmind/config.toml`, `.cmind/reports/*.html`) stay inside the workspace.
 
@@ -17,7 +17,7 @@ my-project/
 ├── docs/                               # Optional requirement docs for /cmind.feature_spec
 │   ├── project_charter.md              # Auto-detected when no description is provided
 │   └── ...
-├── .claude/                            # Claude Code configuration when --ai claude
+├── .claude/                            # Claude Code commands and settings
 │   ├── commands/                       # /cmind.* command definitions
 │   │   ├── cmind.feature_spec.md
 │   │   ├── cmind.feature_build.md
@@ -33,12 +33,17 @@ my-project/
 │   │   ├── cmind.encode.md
 │   │   └── cmind.update_rpg.md
 │   └── settings.json                   # Permissions and MCP auto-approval
-├── .github/                            # Copilot configuration when --ai copilot
+├── .github/                            # Copilot agents and prompts
 │   ├── agents/                         # cmind.* agent definitions
 │   └── prompts/                        # companion prompts
 ├── .vscode/                            # Copilot/VS Code configuration when applicable
 │   ├── mcp.json                        # MCP server registration
 │   └── tasks.json                      # Optional workspace tasks
+├── .agents/skills/                     # Codex project skills
+│   ├── cmind-encode/SKILL.md
+│   ├── cmind-plan/SKILL.md
+│   └── ...
+├── .codex/config.toml                  # Codex project MCP registration
 └── .cmind/
 │   ├── config.toml                     # Workspace AI / config (committed). See docs/configuration.md
 │   ├── .source                         # Provisioning channel marker: "bundle" or "legacy"
@@ -68,7 +73,8 @@ Reports (`rpg.html`, review HTML, …) stay **inside** the workspace at `<worksp
 
 > Pipeline scripts (formerly materialised into `.cmind/scripts/`) now live inside the installed `cmind-cli` wheel under `cmind_cli/core_pack/scripts/` and are invoked via the global [`cmind script <name>`](cli-reference.md) command. They are no longer copied into each workspace, so `cmind init` produces a much smaller footprint and a single source of truth per CLI install.
 
-The agent configuration directory varies by the selected AI assistant and release package. For the verified CLI path, `--ai claude` installs `.claude/commands/`, while `--ai copilot` installs `.github/agents/`, `.github/prompts/`, and `.vscode/mcp.json`.
+CoderMind always installs all verified agent integrations. `--ai` only selects
+which CLI executes encoder/decoder LLM requests.
 
 Command definitions are installed into the AI-agent-specific folder. Normal users should not need to inspect `~/.cmind/workspaces/<workspace-id>/data/` directly—run `cmind version` from the workspace to see all relevant paths.
 
@@ -79,8 +85,8 @@ Command definitions are installed into the AI-agent-specific folder. Normal user
 | Your source code | `<workspace>/` |
 | Workspace AI config | `<workspace>/.cmind/config.toml` |
 | User-facing HTML reports (`rpg.html`, …) | `<workspace>/.cmind/reports/` |
-| Agent command definitions | `<workspace>/.claude/` or `<workspace>/.github/` |
-| MCP / VS Code config | `<workspace>/.vscode/` |
+| Agent command definitions | `<workspace>/.claude/`, `.github/`, and `.agents/skills/` |
+| MCP config | `<workspace>/.mcp.json`, `.vscode/mcp.json`, and `.codex/config.toml` |
 | Git hooks (`post-commit`, `post-merge`) | `<workspace>/.git/hooks/` |
 | Generated data (`rpg.json`, `dep_graph.json`, …) | `~/.cmind/workspaces/<workspace-id>/data/` |
 | Per-stage logs | `~/.cmind/workspaces/<workspace-id>/logs/` |

diff --git a/CoderMind/pyproject.toml b/CoderMind/pyproject.toml
@@ -33,8 +33,9 @@ dependencies = [
     "tqdm",
     "openai>=1.0.0",
     "anthropic>=0.20.0",
-    "mcp>=1.0.0",
-    "pyyaml>=6.0"
+    "mcp>=1.0.0,<2",
+    "pyyaml>=6.0",
+    "tomlkit>=0.13.0"
 ]
 
 [project.scripts]

diff --git a/CoderMind/scripts/code_gen/git_ops.py b/CoderMind/scripts/code_gen/git_ops.py
@@ -59,6 +59,7 @@ def setup_batch_branch(
     batch_id: str,
     repo_path: Path,
     reuse_existing: bool = False,
+    preserve_existing: bool = False,
 ) -> Tuple[bool, str, str]:
     """Create (or reuse) a batch branch from latest main HEAD.
 
@@ -68,6 +69,8 @@ def setup_batch_branch(
         repo_path: Repo root path.
         reuse_existing: If True and branch exists, switch to it instead of
                         deleting and recreating.
+        preserve_existing: If True and branch exists, keep it and create a
+                   uniquely suffixed recovery branch from latest main.
 
     Returns:
         (success, branch_name, initial_commit)
@@ -84,6 +87,17 @@ def setup_batch_branch(
                 return False, branch_name, ""
             initial_commit = git.get_head_commit()
             return True, branch_name, initial_commit
+        elif preserve_existing:
+            recovery_index = 1
+            recovery_name = f"{branch_name}-retry-{recovery_index}"
+            while git.branch_exists(recovery_name):
+                recovery_index += 1
+                recovery_name = f"{branch_name}-retry-{recovery_index}"
+            branch_name = recovery_name
+            logger.info(
+                "Preserving failed branch and creating recovery branch '%s'",
+                branch_name,
+            )
         else:
             logger.info("Deleting stale branch '%s' (will recreate from main)", branch_name)
             git.delete_branch(branch_name, force=True)

diff --git a/CoderMind/scripts/common/git_utils.py b/CoderMind/scripts/common/git_utils.py
@@ -9,6 +9,7 @@
 - Task branch lifecycle (create / merge / abandon)
 """
 
+import hashlib
 import logging
 import re
 import subprocess
@@ -53,7 +54,13 @@ def sanitize_branch_component(
     if not safe:
         return fallback
 
-    safe = safe[:max_len].rstrip("._-")
+    if len(safe) > max_len:
+        digest = hashlib.sha256(safe.encode("utf-8")).hexdigest()[:8]
+        if max_len > len(digest) + 1:
+            prefix = safe[: max_len - len(digest) - 1].rstrip("._-")
+            safe = f"{prefix}-{digest}" if prefix else digest[:max_len]
+        else:
+            safe = digest[:max_len]
     if safe.endswith(".lock"):
         safe = safe[: -len(".lock")].rstrip("._-")