cclaw-cli 0.38.0 → 0.39.0

package/README.md

@@ -127,8 +127,10 @@ Plus harness-specific shims:
 - `.claude/commands/cc*.md` + `.claude/hooks/hooks.json`
 - `.cursor/commands/cc*.md` + `.cursor/hooks.json` + `.cursor/rules/cclaw-workflow.mdc`
 - `.opencode/commands/cc*.md` + `.opencode/plugins/cclaw-plugin.mjs`
-- `.codex/commands/cc*.md` + `.codex/hooks.json`
-- `AGENTS.md` with a managed routing block
+- `.agents/skills/cclaw-cc*/SKILL.md` (Codex; activated via `/use cclaw-cc`
+  or description-based auto-matching — Codex no longer reads `.codex/commands/`
+  or `.codex/hooks.json`, and `cclaw sync` cleans those up if present)
+- `AGENTS.md` with a managed routing block (includes a Codex-specific note)
 
 `.cclaw/config.yaml` holds every tunable key (prompt guard strictness,
 TDD enforcement, git-hook guards, language rule packs, track heuristics).
@@ -355,7 +357,7 @@ closes every real gap with a documented fallback — not a silent waiver.
 | Claude Code | full (named subagents) | `native` | full | `AskUserQuestion` | [`claude-playbook.md`](./src/content/harness-playbooks.ts) |
 | Cursor | generic Task dispatcher | `generic-dispatch` | full | `AskQuestion` | `cursor-playbook.md` |
 | OpenCode | plugin / in-session | `role-switch` | plugin | plain-text | `opencode-playbook.md` |
-| OpenAI Codex | in-session only | `role-switch` (evidenceRefs required) | full | plain-text | `codex-playbook.md` |
+| OpenAI Codex | in-session only | `role-switch` (evidenceRefs required) | none (no hooks API) | plain-text | `codex-playbook.md` |
 
 What the fallbacks mean:
 
@@ -378,6 +380,17 @@ What the fallbacks mean:
   harness declares it. Currently unused — v0.33 removed the old
   Codex-only auto-waiver path.
 
+> **Codex note (v0.39+).** Codex CLI deprecated custom prompts and the
+> `.codex/hooks.json` API, so cclaw installs Codex entry points as
+> native **skills** under `.agents/skills/cclaw-cc*/SKILL.md`. Invoke
+> them with `/use cclaw-cc`, `/use cclaw-cc-next`, `/use cclaw-cc-view`,
+> `/use cclaw-cc-ops`, `/use cclaw-cc-ideate`, or just say something
+> like *"run cc for payments refund fix"* — Codex auto-matches skills
+> from their description. Hook-driven checks (prompt-guard, stop-save,
+> post-tool context monitor) are substituted in the `cclaw-cc*` skill
+> bodies as explicit agent steps; run `cclaw doctor` to see what's
+> missing and how the playbook compensates.
+
 The full capability matrix lives in
 [`docs/harnesses.md`](./docs/harnesses.md). Per-harness playbooks are
 generated into `.cclaw/references/harnesses/` on every install and

package/dist/cli.js

@@ -151,7 +151,12 @@ function buildInitSurfacePreview(harnesses) {
     ];
     for (const harness of harnesses) {
         const adapter = HARNESS_ADAPTERS[harness];
-        lines.push(`${adapter.commandDir}/cc*.md`);
+        if (adapter.shimKind === "skill") {
+            lines.push(`${adapter.commandDir}/cclaw-cc*/SKILL.md`);
+        }
+        else {
+            lines.push(`${adapter.commandDir}/cc*.md`);
+        }
         if (harness === "claude") {
             lines.push(".claude/hooks/hooks.json");
         }
@@ -159,9 +164,9 @@ function buildInitSurfacePreview(harnesses) {
             lines.push(".cursor/hooks.json");
             lines.push(".cursor/rules/cclaw-workflow.mdc");
         }
-        if (harness === "codex") {
-            lines.push(".codex/hooks.json");
-        }
+        // Codex has no hooks file — it reads skills from `.agents/skills/` only
+        // (v0.39.0+). Legacy `.codex/commands/*` and `.codex/hooks.json` are
+        // auto-cleaned on sync.
         if (harness === "opencode") {
             lines.push(".opencode/plugins/cclaw-plugin.mjs");
             lines.push("opencode.json(.c) plugin registration");

package/dist/constants.d.ts

@@ -14,7 +14,7 @@ export declare const EVALS_ROOT = ".cclaw/evals";
 export declare const EVALS_CONFIG_PATH = ".cclaw/evals/config.yaml";
 export declare const EVALS_DIRS: readonly [".cclaw/evals", ".cclaw/evals/corpus", ".cclaw/evals/rubrics", ".cclaw/evals/baselines", ".cclaw/evals/reports"];
 export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/contexts", ".cclaw/templates", ".cclaw/artifacts", ".cclaw/worktrees", ".cclaw/state", ".cclaw/runs", ".cclaw/rules", ".cclaw/adapters", ".cclaw/agents", ".cclaw/hooks", ".cclaw/custom-skills", ".cclaw/evals", ".cclaw/evals/corpus", ".cclaw/evals/rubrics", ".cclaw/evals/baselines", ".cclaw/evals/reports"];
-export declare const REQUIRED_GITIGNORE_PATTERNS: readonly ["# cclaw generated artifacts", ".cclaw/", "# cclaw evals: user-owned, track in git", "!.cclaw/evals/", "!.cclaw/evals/config.yaml", "!.cclaw/evals/corpus/", "!.cclaw/evals/corpus/**", "!.cclaw/evals/rubrics/", "!.cclaw/evals/rubrics/**", "!.cclaw/evals/baselines/", "!.cclaw/evals/baselines/**", ".claude/commands/cc-*.md", ".claude/commands/cc.md", ".cursor/commands/cc-*.md", ".cursor/commands/cc.md", ".opencode/commands/cc-*.md", ".opencode/commands/cc.md", ".codex/commands/cc-*.md", ".codex/commands/cc.md", ".claude/hooks/hooks.json", ".cursor/hooks.json", ".codex/hooks.json", ".opencode/plugins/cclaw-plugin.mjs", ".cursor/rules/cclaw-workflow.mdc"];
+export declare const REQUIRED_GITIGNORE_PATTERNS: readonly ["# cclaw generated artifacts", ".cclaw/", "# cclaw evals: user-owned, track in git", "!.cclaw/evals/", "!.cclaw/evals/config.yaml", "!.cclaw/evals/corpus/", "!.cclaw/evals/corpus/**", "!.cclaw/evals/rubrics/", "!.cclaw/evals/rubrics/**", "!.cclaw/evals/baselines/", "!.cclaw/evals/baselines/**", ".claude/commands/cc-*.md", ".claude/commands/cc.md", ".cursor/commands/cc-*.md", ".cursor/commands/cc.md", ".opencode/commands/cc-*.md", ".opencode/commands/cc.md", ".agents/skills/cclaw-cc/SKILL.md", ".agents/skills/cclaw-cc-*/SKILL.md", ".claude/hooks/hooks.json", ".cursor/hooks.json", ".opencode/plugins/cclaw-plugin.mjs", ".cursor/rules/cclaw-workflow.mdc"];
 export declare const COMMAND_FILE_ORDER: FlowStage[];
 export declare const UTILITY_COMMANDS: readonly ["learn", "next", "ideate", "view", "status", "tree", "diff", "ops", "feature", "tdd-log", "retro", "compound", "archive", "rewind"];
 export declare const SUBAGENT_SKILL_FOLDERS: readonly ["subagent-dev", "parallel-dispatch"];

package/dist/constants.js

@@ -91,11 +91,12 @@ export const REQUIRED_GITIGNORE_PATTERNS = [
     ".cursor/commands/cc.md",
     ".opencode/commands/cc-*.md",
     ".opencode/commands/cc.md",
-    ".codex/commands/cc-*.md",
-    ".codex/commands/cc.md",
+    // Codex uses skill-kind shims under `.agents/skills/cclaw-cc*/` since
+    // v0.39.0; legacy `.codex/commands/*` is auto-cleaned on sync.
+    ".agents/skills/cclaw-cc/SKILL.md",
+    ".agents/skills/cclaw-cc-*/SKILL.md",
     ".claude/hooks/hooks.json",
     ".cursor/hooks.json",
-    ".codex/hooks.json",
     ".opencode/plugins/cclaw-plugin.mjs",
     ".cursor/rules/cclaw-workflow.mdc"
 ];

package/dist/content/harness-playbooks.js

@@ -192,28 +192,43 @@ has either a \`completed\` row with evidenceRefs (role-switch) or a
 const CODEX_PLAYBOOK = `---
 harness: codex
 fallback: role-switch
-description: "OpenAI Codex has no subagent dispatch primitive. cclaw uses role-switch with evidenceRefs; silent auto-waiver is explicitly disabled."
+description: "OpenAI Codex has no subagent dispatch and no hooks. cclaw ships entry points as skills under .agents/skills/; mandatory delegations fall back to role-switch with evidenceRefs."
 ---
 
 # OpenAI Codex — Parity Playbook
 
-**Fallback: role-switch.** Codex has no subagent dispatch — neither named
-nor generic. cclaw used to silently auto-waive mandatory delegations on
-Codex; v0.33 disables that shortcut. The agent must role-switch in-session
-and record evidence, or the delegation gate blocks stage completion.
-
-## Role-switch protocol
-
-Identical to OpenCode. Key requirements:
+Codex CLI exposes **neither a custom slash-command system nor a hooks
+API**. cclaw v0.39.0 acknowledged this and rewired the codex harness:
+
+- **Entry points are skills.** \`/cc\`, \`/cc-next\`, \`/cc-ideate\`,
+  \`/cc-view\`, \`/cc-ops\` are generated as skills at
+  \`.agents/skills/cclaw-cc/SKILL.md\` (and \`cclaw-cc-next/\`, etc.). They
+  activate via Codex's native \`/use <skillName>\` command or
+  automatically when the user's prompt mentions any of the
+  \`/cc\`-style tokens (skill descriptions include them verbatim).
+- **No hooks.** Everything that Claude/Cursor get from
+  \`SessionStart\` / \`PreToolUse\` / \`PostToolUse\` / \`Stop\` /
+  \`PreCompact\` must run as explicit agent steps. The session rehydration,
+  prompt-guard, workflow-guard, context-monitor, and stop-checkpoint
+  behaviors are documented in \`.cclaw/skills/using-cclaw/SKILL.md\`.
+- **Legacy paths are dead.** \`.codex/commands/*\` and \`.codex/hooks.json\`
+  are removed on every \`cclaw sync\`. Do not restore them by hand —
+  Codex CLI never read either path.
+
+## Fallback: role-switch
+
+Codex has no subagent dispatch — neither named nor generic. Mandatory
+delegations must be role-switched in-session. Silent auto-waiver was
+disabled in v0.33 and remains off.
 
 1. **Explicit announce.** Before performing the role, emit a single
    message naming the role and citing \`.cclaw/agents/<agent>.md\`.
-2. **No role interleaving.** Do not mix, for example, reviewer and
-   test-author work into the same turn — close one delegation before
-   opening another.
-3. **EvidenceRefs are mandatory.** Under Codex's role-switch fallback a
-   \`completed\` row without \`evidenceRefs\` is treated as
-   \`missingEvidence\` by \`cclaw doctor\` and blocks the gate.
+2. **No role interleaving.** Close one delegation before opening
+   another; never mix, for example, reviewer and test-author work in
+   the same turn.
+3. **EvidenceRefs are mandatory.** A \`completed\` row without
+   \`evidenceRefs\` is treated as \`missingEvidence\` by \`cclaw doctor\`
+   and blocks the stage gate.
 
 ## Stage-specific role maps
 
@@ -226,23 +241,37 @@ Identical to OpenCode. Key requirements:
 | review     | \`reviewer\`, \`security-reviewer\` | \`.cclaw/artifacts/07-review.md\`  |
 | ship       | \`doc-updater\`                  | \`.cclaw/artifacts/08-ship.md\`      |
 
-## Why no auto-waiver anymore?
+## Invocation cheatsheet
 
-Silent auto-waiver on Codex let entire stages complete without any
-reviewer or test-author work. That defeats cclaw's hard gates. v0.33
-replaces it with an explicit role-switch obligation: the agent still gets
-a path forward, but the path is visible in the delegation log.
+- \`/use cclaw-cc\` — open the \`/cc\` skill and pick a track.
+- \`/use cclaw-cc-next\` — advance the flow one stage.
+- \`/use cclaw-cc-ops\` — compound / archive / rewind.
+- Typing \`/cc …\` or \`/cc-next …\` in plain text also works: Codex
+  matches the skill descriptions (which spell out these tokens) and
+  auto-loads the right skill body.
+- Use Codex's built-in \`/skill\` UI to enable or disable
+  cclaw skills per session.
 
-If a team genuinely wants to skip a delegation on Codex, they must
-manually append a \`status: "waived"\` row with a one-line
-\`waiverReason\` — the same audit trail any Claude/Cursor install would
-need.
+## Hook substitution matrix
+
+| Hook intent | Codex substitute |
+|-------------|------------------|
+| SessionStart rehydration | On first turn, the agent reads \`.cclaw/state/flow-state.json\` and \`.cclaw/knowledge.jsonl\` explicitly before acting. |
+| PreToolUse prompt-guard | The \`/cc\` skill body enforces task classification before writes. |
+| PreToolUse workflow-guard | The active stage skill enforces TDD / artifact gates before writes. |
+| PostToolUse context-monitor | End-of-turn budget check lives in \`.cclaw/references/protocols/ethos.md\`. |
+| Stop checkpoint | Stage-completion protocol updates \`.cclaw/state/flow-state.json\` in the same turn. |
+| PreCompact digest | Manual \`/cc-view status\` before \`/compact\`; the user triggers this. |
 
 ## Verification
 
-\`cclaw doctor\` passes when every mandatory agent for the active stage
-has a \`completed\` row with \`fulfillmentMode: "role-switch"\` and at
-least one \`evidenceRef\`.
+\`cclaw doctor\` on a codex-enabled install checks:
+
+- \`shim:codex:cclaw-cc:present\` and \`frontmatter\` (plus the four
+  utility skills).
+- No legacy \`.codex/commands/\` or \`.codex/hooks.json\` lingering.
+- Every mandatory agent for the active stage has a \`completed\` row
+  with \`fulfillmentMode: "role-switch"\` and at least one \`evidenceRef\`.
 `;
 const PLAYBOOK_BY_HARNESS = {
     claude: CLAUDE_PLAYBOOK,

package/dist/content/harnesses-doc.js

@@ -112,7 +112,7 @@ Harness-specific additions:
 - \`claude\`: \`.claude/commands/cc*.md\`, \`.claude/hooks/hooks.json\`
 - \`cursor\`: \`.cursor/commands/cc*.md\`, \`.cursor/hooks.json\`, \`.cursor/rules/cclaw-workflow.mdc\`
 - \`opencode\`: \`.opencode/commands/cc*.md\`, \`.opencode/plugins/cclaw-plugin.mjs\`, opencode plugin registration
-- \`codex\`: \`.codex/commands/cc*.md\`, \`.codex/hooks.json\`
+- \`codex\`: \`.agents/skills/cclaw-cc/SKILL.md\`, \`.agents/skills/cclaw-cc-next/SKILL.md\`, \`.agents/skills/cclaw-cc-ideate/SKILL.md\`, \`.agents/skills/cclaw-cc-view/SKILL.md\`, \`.agents/skills/cclaw-cc-ops/SKILL.md\` (Codex CLI reads \`.agents/skills/\` on startup; \`.codex/*\` was never consumed by the CLI and is auto-cleaned on sync)
 
 ## Runtime observability
 

package/dist/content/hook-events.js

@@ -32,11 +32,10 @@ export const HOOK_EVENTS_BY_HARNESS = {
         precompact_digest: "plugin session.cleared/session.resumed hooks"
     },
     codex: {
-        session_rehydrate: "SessionStart matcher startup|resume|clear|compact",
-        pre_tool_prompt_guard: "PreToolUse -> prompt-guard.sh",
-        pre_tool_workflow_guard: "PreToolUse -> workflow-guard.sh",
-        post_tool_context_monitor: "PostToolUse -> context-monitor.sh",
-        stop_checkpoint: "Stop -> stop-checkpoint.sh",
-        precompact_digest: "PreCompact -> pre-compact.sh"
+    // Codex CLI has no hooks primitive. cclaw substitutes via skills
+    // under `.agents/skills/cclaw-cc*/SKILL.md` plus explicit in-turn
+    // agent steps (see codex playbook). All semantic events are
+    // intentionally unmapped here so `harness-gaps.json` exposes them
+    // honestly.
     }
 };

package/dist/content/hooks.js

@@ -1205,16 +1205,18 @@ export default function cclawPlugin(ctx) {
 export function hooksAgentsMdBlock() {
     return `### Hooks (real lifecycle integration)
 
-Cclaw generates real hook integrations across harnesses:
-- **Claude/Cursor/Codex:** lifecycle rehydration + PreToolUse/PostToolUse + Stop
+Cclaw generates real hook integrations for every harness that exposes a
+hook primitive:
+- **Claude/Cursor:** lifecycle rehydration + PreToolUse/PostToolUse + Stop
 - **OpenCode:** session lifecycle + system transform rehydration + bootstrap parity (digest/warnings/knowledge snapshot)
+- **Codex:** *no hooks API exists in Codex CLI* — substitution happens via skills (\`.agents/skills/cclaw-cc*/SKILL.md\`) and explicit in-turn agent steps. See \`.cclaw/references/harnesses/codex-playbook.md\`.
 
 | Harness | Hook file | Events |
 |---------|-----------|--------|
 | Claude Code | \`.claude/hooks/hooks.json\` | SessionStart(startup/resume/clear/compact), PreToolUse, PostToolUse, Stop |
 | Cursor | \`.cursor/hooks.json\` | sessionStart/sessionResume/sessionClear/sessionCompact, preToolUse, postToolUse, stop |
-| Codex | \`.codex/hooks.json\` | SessionStart(startup/resume/clear/compact), PreToolUse, PostToolUse, Stop |
 | OpenCode | \`${RUNTIME_ROOT}/hooks/opencode-plugin.mjs\` | session.created/updated/resumed/cleared/compacted/idle, tool.execute.before/after, system transform |
+| Codex | *none* | skill-description matching + in-turn agent steps (no hooks API) |
 
 Hook state files:
 - \`${RUNTIME_ROOT}/state/stage-activity.jsonl\`

package/dist/doctor.js

@@ -8,7 +8,7 @@ import { CCLAW_AGENTS } from "./content/core-agents.js";
 import { readConfig } from "./config.js";
 import { exists } from "./fs-utils.js";
 import { gitignoreHasRequiredPatterns } from "./gitignore.js";
-import { HARNESS_ADAPTERS, CCLAW_MARKER_START, CCLAW_MARKER_END, harnessShimFileNames } from "./harness-adapters.js";
+import { HARNESS_ADAPTERS, CCLAW_MARKER_START, CCLAW_MARKER_END, harnessShimFileNames, harnessShimSkillNames } from "./harness-adapters.js";
 import { policyChecks } from "./policy.js";
 import { readFlowState } from "./runs.js";
 import { skippedStagesForTrack } from "./flow-state.js";
@@ -474,13 +474,17 @@ export async function doctorChecks(projectRoot, options = {}) {
             });
             continue;
         }
-        for (const shim of harnessShimFileNames()) {
-            const shimPath = path.join(projectRoot, adapter.commandDir, shim);
-            checks.push({
-                name: `shim:${harness}:${shim.replace(".md", "")}`,
-                ok: await exists(shimPath),
-                details: shimPath
-            });
+        // For command-kind harnesses we check flat files; skill-kind (codex) is
+        // validated in the codex-specific block below (`shim:codex:<name>:*`).
+        if (adapter.shimKind === "command") {
+            for (const shim of harnessShimFileNames()) {
+                const shimPath = path.join(projectRoot, adapter.commandDir, shim);
+                checks.push({
+                    name: `shim:${harness}:${shim.replace(".md", "")}`,
+                    ok: await exists(shimPath),
+                    details: shimPath
+                });
+            }
         }
         const playbookFile = path.join(projectRoot, RUNTIME_ROOT, ...HARNESS_PLAYBOOKS_DIR.split("/"), harnessPlaybookFileName(harness));
         checks.push({
@@ -631,15 +635,16 @@ export async function doctorChecks(projectRoot, options = {}) {
             });
         }
     }
-    // Hook JSON files per harness
+    // Hook JSON files per harness. Codex is absent because Codex CLI has no
+    // hooks primitive — cclaw stopped writing `.codex/hooks.json` in v0.39.0.
+    // OpenCode ships hooks through its plugin system (covered below).
     const hookPaths = {
         claude: ".claude/hooks/hooks.json",
-        cursor: ".cursor/hooks.json",
-        codex: ".codex/hooks.json"
+        cursor: ".cursor/hooks.json"
     };
     for (const harness of configuredHarnesses) {
         const hp = hookPaths[harness];
-        if (!hp && harness !== "opencode") {
+        if (!hp && harness !== "opencode" && harness !== "codex") {
             checks.push({
                 name: `hook:json:${harness}`,
                 ok: false,
@@ -656,7 +661,7 @@ export async function doctorChecks(projectRoot, options = {}) {
                 ok: hookOk,
                 details: fullPath
             });
-            if (harness === "claude" || harness === "cursor" || harness === "codex") {
+            if (harness === "claude" || harness === "cursor") {
                 const schema = validateHookDocument(harness, parsed);
                 checks.push({
                     name: `hook:schema:${harness}`,
@@ -757,29 +762,55 @@ export async function doctorChecks(projectRoot, options = {}) {
         });
     }
     if (configuredHarnesses.includes("codex")) {
-        const file = path.join(projectRoot, ".codex/hooks.json");
-        const parsed = await readHookDocument(file);
-        const hooks = toObject(parsed?.hooks) ?? {};
-        const sessionStart = hooks.SessionStart;
-        const ok = JSON.stringify(sessionStart ?? "").includes("startup|resume|clear|compact");
+        // Codex CLI has no hooks primitive and no slash-command discovery
+        // (`.codex/commands/*` was never read). cclaw ships codex shims as
+        // skills under `.agents/skills/cclaw-cc*/SKILL.md`. Every required
+        // skill must exist with the expected frontmatter `name`.
+        const skillsRoot = path.join(projectRoot, ".agents/skills");
+        for (const skillName of harnessShimSkillNames()) {
+            const skillPath = path.join(skillsRoot, skillName, "SKILL.md");
+            let ok = false;
+            let frontmatterOk = false;
+            if (await exists(skillPath)) {
+                ok = true;
+                const content = await fs.readFile(skillPath, "utf8");
+                frontmatterOk = new RegExp(`^---[\\s\\S]*?\\nname: ${skillName}\\b`, "u").test(content);
+            }
+            checks.push({
+                name: `shim:codex:${skillName}:present`,
+                ok,
+                details: skillPath
+            });
+            checks.push({
+                name: `shim:codex:${skillName}:frontmatter`,
+                ok,
+                details: frontmatterOk
+                    ? `${skillPath} has \`name: ${skillName}\` frontmatter`
+                    : ok
+                        ? `${skillPath} present but \`name: ${skillName}\` frontmatter is missing`
+                        : `${skillPath} absent; cannot validate frontmatter`
+            });
+        }
+        // Warn if legacy `.codex/commands/*` or `.codex/hooks.json` is still
+        // around — cclaw syncs should have removed these, but a botched
+        // upgrade or a manual restore could leave them dangling.
+        const legacyCommandsDir = path.join(projectRoot, ".codex/commands");
+        const legacyCommandsPresent = await exists(legacyCommandsDir);
         checks.push({
-            name: "lifecycle:codex:rehydration_matcher",
-            ok,
-            details: `${file} must include SessionStart matcher startup|resume|clear|compact`
+            name: "warning:codex:legacy_commands_dir",
+            ok: true,
+            details: legacyCommandsPresent
+                ? `warning: ${legacyCommandsDir} still present; Codex never read this directory — run \`cclaw sync\` to remove it.`
+                : `no legacy ${legacyCommandsDir} detected`
         });
-        const sessionCommands = collectHookCommands(hooks.SessionStart);
-        const preCommands = collectHookCommands(hooks.PreToolUse);
-        const postCommands = collectHookCommands(hooks.PostToolUse);
-        const stopCommands = collectHookCommands(hooks.Stop);
-        const wiringOk = sessionCommands.some((cmd) => cmd.includes("session-start.sh")) &&
-            preCommands.some((cmd) => cmd.includes("prompt-guard.sh")) &&
-            preCommands.some((cmd) => cmd.includes("workflow-guard.sh")) &&
-            postCommands.some((cmd) => cmd.includes("context-monitor.sh")) &&
-            stopCommands.some((cmd) => cmd.includes("stop-checkpoint.sh"));
+        const legacyHooks = path.join(projectRoot, ".codex/hooks.json");
+        const legacyHooksPresent = await exists(legacyHooks);
         checks.push({
-            name: "hook:wiring:codex",
-            ok: wiringOk,
-            details: `${file} must wire session-start/prompt-guard/workflow-guard/context-monitor/stop-checkpoint`
+            name: "warning:codex:legacy_hooks_json",
+            ok: true,
+            details: legacyHooksPresent
+                ? `warning: ${legacyHooks} still present; Codex CLI has no hooks API — run \`cclaw sync\` to remove it.`
+                : `no legacy ${legacyHooks} detected`
         });
     }
     if (configuredHarnesses.includes("opencode")) {

package/dist/harness-adapters.d.ts

@@ -21,9 +21,32 @@ export type SubagentFallback =
  * under `waiverReason: "harness_limitation"`.
  */
  | "waiver";
+/**
+ * How a harness discovers cclaw's `/cc*` entry points.
+ *
+ * - `command` — harness has a native custom slash-command system and reads
+ *   flat markdown files from `<commandDir>/<fileName>.md` (Claude Code,
+ *   Cursor, OpenCode).
+ * - `skill` — harness ignores flat commands and reads SKILL.md from
+ *   directories under a skills root (Codex CLI ≥0.89, Jan 2026). cclaw
+ *   writes `<commandDir>/<skillName>/SKILL.md` and the agent invokes it
+ *   either via `/use <skillName>` or via automatic description matching
+ *   when the user's text mentions `/cc`, `/cc-next`, etc.
+ */
+export type ShimKind = "command" | "skill";
 export interface HarnessAdapter {
     id: HarnessId;
+    /**
+     * Root directory where cclaw writes `/cc*` entry points.
+     *
+     * - For `shimKind: "command"` this is the directory containing flat
+     *   markdown files (`<commandDir>/cc.md`, `<commandDir>/cc-next.md`, …).
+     * - For `shimKind: "skill"` this is the skills root that contains
+     *   per-skill subdirectories (`<commandDir>/<skillName>/SKILL.md`).
+     */
     commandDir: string;
+    /** See {@link ShimKind}. Defaults to `"command"` if unspecified at a callsite. */
+    shimKind: ShimKind;
     capabilities: {
         /**
          * Level of native subagent dispatch:
@@ -45,6 +68,8 @@ export interface HarnessAdapter {
     };
 }
 export declare function harnessShimFileNames(): string[];
+/** Skill folder names cclaw writes under `<commandDir>` for skill-kind harnesses. */
+export declare function harnessShimSkillNames(): string[];
 export declare const HARNESS_ADAPTERS: Record<HarnessId, HarnessAdapter>;
 export type HarnessTier = "tier1" | "tier2" | "tier3";
 export declare function harnessTier(harnessId: HarnessId): HarnessTier;

package/dist/harness-adapters.js

@@ -14,29 +14,35 @@ const RUNTIME_AGENTS_BLOCK_GLOBAL_PATTERN = new RegExp(RUNTIME_AGENTS_BLOCK_SOUR
 const UTILITY_SHIMS = [
     {
         fileName: "cc-next.md",
+        skillName: "cclaw-cc-next",
         command: "next",
         skillFolder: "flow-next-step",
         commandFile: "next.md"
     },
     {
         fileName: "cc-ideate.md",
+        skillName: "cclaw-cc-ideate",
         command: "ideate",
         skillFolder: "flow-ideate",
         commandFile: "ideate.md"
     },
     {
         fileName: "cc-view.md",
+        skillName: "cclaw-cc-view",
         command: "view",
         skillFolder: "flow-view",
         commandFile: "view.md"
     },
     {
         fileName: "cc-ops.md",
+        skillName: "cclaw-cc-ops",
         command: "ops",
         skillFolder: "flow-ops",
         commandFile: "ops.md"
     }
 ];
+/** Skill-kind shim name for the root `/cc` entry point. */
+const ENTRY_SHIM_SKILL_NAME = "cclaw-cc";
 /**
  * Shims that older cclaw versions installed as top-level slash commands but
  * which we now treat as internal (skill-only, invoked by the agent, never
@@ -47,10 +53,15 @@ const LEGACY_HARNESS_SHIMS = ["cc-learn.md"];
 export function harnessShimFileNames() {
     return ["cc.md", ...UTILITY_SHIMS.map((shim) => shim.fileName)];
 }
+/** Skill folder names cclaw writes under `<commandDir>` for skill-kind harnesses. */
+export function harnessShimSkillNames() {
+    return [ENTRY_SHIM_SKILL_NAME, ...UTILITY_SHIMS.map((shim) => shim.skillName)];
+}
 export const HARNESS_ADAPTERS = {
     claude: {
         id: "claude",
         commandDir: ".claude/commands",
+        shimKind: "command",
         capabilities: {
             nativeSubagentDispatch: "full",
             hookSurface: "full",
@@ -61,6 +72,7 @@ export const HARNESS_ADAPTERS = {
     cursor: {
         id: "cursor",
         commandDir: ".cursor/commands",
+        shimKind: "command",
         capabilities: {
             // Cursor has a real Task tool with subagent_type (generalPurpose,
             // explore, shell, browser-use, …) but no user-defined named
@@ -75,6 +87,7 @@ export const HARNESS_ADAPTERS = {
     opencode: {
         id: "opencode",
         commandDir: ".opencode/commands",
+        shimKind: "command",
         capabilities: {
             nativeSubagentDispatch: "partial",
             hookSurface: "plugin",
@@ -84,10 +97,17 @@ export const HARNESS_ADAPTERS = {
     },
     codex: {
         id: "codex",
-        commandDir: ".codex/commands",
+        // Codex CLI reads skills from the universal `.agents/skills/` path
+        // (OpenAI Codex 0.89, Jan 2026; legacy `~/.codex/skills/` also
+        // supported). It has no native `.codex/commands/` slash-command
+        // discovery and no `.codex/hooks.json` primitive — v0.39.0 migrated
+        // cclaw to write skill-kind shims here and stops generating the
+        // dead `.codex/*` surfaces.
+        commandDir: ".agents/skills",
+        shimKind: "skill",
         capabilities: {
             nativeSubagentDispatch: "none",
-            hookSurface: "full",
+            hookSurface: "none",
             structuredAsk: "plain-text",
             subagentFallback: "role-switch"
         }
@@ -193,6 +213,22 @@ If the same approach fails three times in a row (same command, same finding, sam
 - Detailed operating procedures live in \`.cclaw/skills/using-cclaw/SKILL.md\`.
 - Preamble budget and cooldown rules live in \`.cclaw/references/protocols/ethos.md\`.
 - Subagent orchestration patterns: \`.cclaw/skills/subagent-dev/SKILL.md\` and \`.cclaw/skills/parallel-dispatch/SKILL.md\`.
+
+### Codex users
+
+OpenAI Codex CLI has **no native \`/cc\` slash command** and **no hooks API**. The
+\`/cc\`, \`/cc-next\`, \`/cc-ideate\`, \`/cc-view\`, \`/cc-ops\` tokens above describe
+intent — in Codex they map onto skills cclaw installs at
+\`.agents/skills/cclaw-cc*/SKILL.md\`. Activate one of two ways:
+
+- Type \`/use cclaw-cc\` (or \`cclaw-cc-next\`, etc.) at Codex's prompt.
+- Type \`/cc …\` as plain text — Codex matches the skill \`description\`
+  frontmatter (which spells out the token verbatim) and loads the right
+  skill body automatically.
+
+Legacy \`.codex/commands/*\` and \`.codex/hooks.json\` are removed on
+\`cclaw sync\` — Codex CLI never consumed either path. See
+\`.cclaw/references/harnesses/codex-playbook.md\` for the hook-substitution matrix.
 ${CCLAW_MARKER_END}`;
 }
 /** Removes the cclaw AGENTS.md block. */
@@ -266,6 +302,143 @@ Load and execute:
 This is a utility command (not a flow stage). It does not advance flow state.
 `;
 }
+/**
+ * Frontmatter `description` that triggers the skill when the user types any
+ * of the classic cclaw slash-tokens. Codex's skill matcher runs on the skill
+ * description verbatim, so we spell out every vocabulary Codex users type
+ * instead of relying on semantics.
+ */
+function codexSkillDescription(command) {
+    switch (command) {
+        case "cc":
+            return `Entry point for the cclaw 8-stage workflow (brainstorm → scope → design → spec → plan → tdd → review → ship). Use whenever the user types \`/cc\`, \`/cclaw\`, or asks to "start the flow", "begin cclaw", "kick off the workflow", "classify this task", or wants to start/resume a non-trivial software change. No args = resume the active stage from \`.cclaw/state/flow-state.json\`. With a prompt = classify and pick a track (quick/medium/standard).`;
+        case "next":
+            return `Advance the cclaw flow to the next stage. Use when the user types \`/cc-next\` or asks to "move to the next stage", "continue the flow", "advance cclaw", "progress the workflow", or when the current stage skill reports completion and gates have passed.`;
+        case "ideate":
+            return `Read-only repo-improvement discovery for cclaw. Use when the user types \`/cc-ideate\` or asks to "ideate", "brainstorm improvements", "scan the repo for TODOs/tech debt", "generate a backlog", or wants a ranked list of candidate ideas before committing to a single flow. Does not mutate \`.cclaw/state/flow-state.json\`.`;
+        case "view":
+            return `Read-only router for cclaw flow views. Use when the user types \`/cc-view\`, \`/cc-view status\`, \`/cc-view tree\`, \`/cc-view diff\`, or asks to "show cclaw status", "show the flow tree", "diff flow state", or wants a snapshot without mutation.`;
+        case "ops":
+            return `Operations router for cclaw post-flow actions. Use when the user types \`/cc-ops\`, \`/cc-ops feature\`, \`/cc-ops tdd-log\`, \`/cc-ops retro\`, \`/cc-ops compound\`, \`/cc-ops archive\`, \`/cc-ops rewind\`, or asks to "archive the run", "run the retro", "compound knowledge", "rewind to an earlier stage", or manage feature worktrees.`;
+        default:
+            return `Generated cclaw skill for ${command}.`;
+    }
+}
+/**
+ * Skill body for codex-kind shims. Deliberately terse — the meat lives in
+ * `.cclaw/skills/` and `.cclaw/commands/`, and Codex's progressive-disclosure
+ * model loads skill bodies lazily, so we want a pointer plus the honest
+ * harness caveat, not a duplicated contract.
+ */
+function codexSkillBody(command, skillFolder, commandFile) {
+    const slashToken = command === "cc" ? "/cc" : `/cc-${command}`;
+    const title = command === "cc" ? "cclaw /cc (Codex adapter)" : `cclaw ${slashToken} (Codex adapter)`;
+    const extraContractHeading = command === "cc"
+        ? "If you have not already loaded the cclaw meta-skill this session, also load `.cclaw/skills/using-cclaw/SKILL.md` — it is the routing brain for stage/utility selection."
+        : "This skill is a utility entry point, not a flow stage. Do not mutate `.cclaw/state/flow-state.json` directly.";
+    return `# ${title}
+
+You are running inside the OpenAI Codex harness. Codex has **no native
+\`${slashToken}\` slash command and no \`.codex/hooks.json\` primitive** — cclaw
+ships its entry points as skills under \`.agents/skills/\` and relies on
+\`AGENTS.md\` + skill descriptions for activation. If the user typed
+\`${slashToken} …\` as plain text (or asked to perform its action in English),
+follow the steps below.
+
+## Protocol
+
+1. Read \`.cclaw/state/flow-state.json\` first to know the active stage,
+   track, and run metadata.
+2. Load and follow \`.cclaw/skills/${skillFolder}/SKILL.md\` as the
+   authoritative skill — its gates, artifacts, and delegations are
+   canonical.
+3. Load \`.cclaw/commands/${commandFile}\` for the full command contract
+   (protocol, validation, post-state expectations).
+4. ${extraContractHeading}
+
+## Honest caveats
+
+- Codex has no subagent dispatch primitive. Mandatory delegations
+  fall back to **role-switch** — announce the role, act in-session,
+  append a completed row with \`evidenceRefs\` to
+  \`.cclaw/state/delegation-log.json\`. Silent auto-waiver is disabled
+  (v0.33+).
+- Codex has no hooks. Session rehydration, prompt-guard, workflow-guard,
+  context-monitor, stop-checkpoint, and pre-compact behavior all have to
+  run as explicit agent steps. Read \`.cclaw/references/harnesses/codex-playbook.md\`
+  for the substitution matrix.
+`;
+}
+function codexSkillMarkdown(command, skillName, skillFolder, commandFile) {
+    const description = codexSkillDescription(command);
+    const frontmatter = [
+        "---",
+        `name: ${skillName}`,
+        `description: ${description}`,
+        "source: generated-by-cclaw",
+        "---",
+        ""
+    ].join("\n");
+    return `${frontmatter}${codexSkillBody(command, skillFolder, commandFile)}`;
+}
+async function writeCommandKindShims(commandDir, harness) {
+    await ensureDir(commandDir);
+    await writeFileSafe(path.join(commandDir, "cc.md"), utilityShimContent(harness, "cc", "flow-start", "start.md"));
+    for (const shim of UTILITY_SHIMS) {
+        await writeFileSafe(path.join(commandDir, shim.fileName), utilityShimContent(harness, shim.command, shim.skillFolder, shim.commandFile));
+    }
+    for (const legacy of LEGACY_HARNESS_SHIMS) {
+        const legacyPath = path.join(commandDir, legacy);
+        try {
+            await fs.unlink(legacyPath);
+        }
+        catch {
+            // fine — file may not exist (fresh install) or may be on read-only FS
+        }
+    }
+}
+async function writeSkillKindShims(commandDir) {
+    await ensureDir(commandDir);
+    await writeFileSafe(path.join(commandDir, ENTRY_SHIM_SKILL_NAME, "SKILL.md"), codexSkillMarkdown("cc", ENTRY_SHIM_SKILL_NAME, "flow-start", "start.md"));
+    for (const shim of UTILITY_SHIMS) {
+        await writeFileSafe(path.join(commandDir, shim.skillName, "SKILL.md"), codexSkillMarkdown(shim.command, shim.skillName, shim.skillFolder, shim.commandFile));
+    }
+}
+/**
+ * Legacy codex surfaces cclaw wrote before v0.39.0 that Codex CLI never
+ * actually consumed (`.codex/commands/*.md` had no discovery, `.codex/hooks.json`
+ * had no hooks API). On every sync we proactively delete these so users
+ * upgrading from older installs see a clean `.codex/` (or no `.codex/` at all).
+ */
+async function cleanupLegacyCodexSurfaces(projectRoot) {
+    const legacyCommandsDir = path.join(projectRoot, ".codex/commands");
+    try {
+        await fs.rm(legacyCommandsDir, { recursive: true, force: true });
+    }
+    catch {
+        // best-effort cleanup
+    }
+    const legacyHooksFile = path.join(projectRoot, ".codex/hooks.json");
+    try {
+        await fs.rm(legacyHooksFile, { force: true });
+    }
+    catch {
+        // best-effort cleanup
+    }
+    // If `.codex/` is now empty we drop it entirely — codex CLI doesn't need
+    // that directory anymore. Leave it alone if the user stored their own
+    // data there.
+    try {
+        const codexDir = path.join(projectRoot, ".codex");
+        const entries = await fs.readdir(codexDir);
+        if (entries.length === 0) {
+            await fs.rmdir(codexDir);
+        }
+    }
+    catch {
+        // directory absent or non-empty
+    }
+}
 async function syncAgentFiles(projectRoot) {
     const agentsDir = path.join(projectRoot, RUNTIME_ROOT, "agents");
     await ensureDir(agentsDir);
@@ -274,25 +447,20 @@ async function syncAgentFiles(projectRoot) {
     }
 }
 export async function syncHarnessShims(projectRoot, harnesses) {
+    // Legacy codex cleanup is unconditional — even installs that never enabled
+    // codex but previously did will see stale `.codex/commands/*.md` and
+    // `.codex/hooks.json` get removed on upgrade.
+    await cleanupLegacyCodexSurfaces(projectRoot);
     for (const harness of harnesses) {
         const adapter = HARNESS_ADAPTERS[harness];
-        if (!adapter) {
+        if (!adapter)
             continue;
-        }
         const commandDir = path.join(projectRoot, adapter.commandDir);
-        await ensureDir(commandDir);
-        await writeFileSafe(path.join(commandDir, "cc.md"), utilityShimContent(harness, "cc", "flow-start", "start.md"));
-        for (const shim of UTILITY_SHIMS) {
-            await writeFileSafe(path.join(commandDir, shim.fileName), utilityShimContent(harness, shim.command, shim.skillFolder, shim.commandFile));
+        if (adapter.shimKind === "skill") {
+            await writeSkillKindShims(commandDir);
         }
-        for (const legacy of LEGACY_HARNESS_SHIMS) {
-            const legacyPath = path.join(commandDir, legacy);
-            try {
-                await fs.unlink(legacyPath);
-            }
-            catch {
-                // fine — file may not exist (fresh install) or may be on read-only FS
-            }
+        else {
+            await writeCommandKindShims(commandDir, harness);
         }
     }
     await syncAgentFiles(projectRoot);

package/dist/init-detect.js

@@ -26,9 +26,14 @@ export async function detectHarnesses(projectRoot) {
     if (await anyExists(opencodeHints)) {
         detected.push("opencode");
     }
+    // Codex CLI doesn't require a persistent per-project directory. We
+    // detect via `.agents/skills/` (the universal path Codex 0.89+ reads;
+    // Jan 2026) or the legacy `.codex/` marker left by pre-v0.39 cclaw.
+    // AGENTS.md is intentionally *not* a codex hint because every other
+    // harness in cclaw's list also reads AGENTS.md.
     const codexHints = [
-        path.join(projectRoot, ".codex"),
-        path.join(projectRoot, ".codex/hooks.json")
+        path.join(projectRoot, ".agents/skills"),
+        path.join(projectRoot, ".codex")
     ];
     if (await anyExists(codexHints)) {
         detected.push("codex");

package/dist/install.js

@@ -23,7 +23,7 @@ import { archiveCommandContract, archiveCommandSkillMarkdown } from "./content/a
 import { rewindCommandContract, rewindCommandSkillMarkdown } from "./content/rewind-command.js";
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
-import { sessionStartScript, stopCheckpointScript, preCompactScript, opencodePluginJs, claudeHooksJson, cursorHooksJson, codexHooksJson } from "./content/hooks.js";
+import { sessionStartScript, stopCheckpointScript, preCompactScript, opencodePluginJs, claudeHooksJson, cursorHooksJson } from "./content/hooks.js";
 import { contextMonitorScript, promptGuardScript, workflowGuardScript } from "./content/observe.js";
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
 import { decisionProtocolMarkdown, completionProtocolMarkdown, ethosProtocolMarkdown } from "./content/protocols.js";
@@ -667,11 +667,10 @@ async function writeHooks(projectRoot, config) {
             await ensureDir(cursorDir);
             await writeMergedHookJson(projectRoot, path.join(cursorDir, "hooks.json"), cursorHooksJson());
         }
-        else if (harness === "codex") {
-            const dir = path.join(projectRoot, ".codex");
-            await ensureDir(dir);
-            await writeMergedHookJson(projectRoot, path.join(dir, "hooks.json"), codexHooksJson());
-        }
+        // Codex has no hooks primitive — v0.39.0 stopped generating
+        // `.codex/hooks.json` because Codex CLI never actually read it. Codex
+        // substitutes for hooks via explicit agent steps documented in the
+        // codex playbook.
         // OpenCode registration is auto-managed via opencode.json/opencode.jsonc.
     }
 }
@@ -906,10 +905,13 @@ async function writeCursorWorkflowRule(projectRoot, harnesses) {
 }
 async function syncDisabledHarnessArtifacts(projectRoot, harnesses) {
     const enabled = new Set(harnesses);
+    // Codex is intentionally absent — cclaw stopped generating `.codex/hooks.json`
+    // in v0.39.0 (the file was never consumed by Codex CLI). Legacy `.codex/*`
+    // files are removed unconditionally by `cleanupLegacyCodexSurfaces` during
+    // every `syncHarnessShims` pass.
     const managedHookFiles = [
         { harness: "claude", hookPath: path.join(projectRoot, ".claude/hooks/hooks.json") },
-        { harness: "cursor", hookPath: path.join(projectRoot, ".cursor/hooks.json") },
-        { harness: "codex", hookPath: path.join(projectRoot, ".codex/hooks.json") }
+        { harness: "cursor", hookPath: path.join(projectRoot, ".cursor/hooks.json") }
     ];
     for (const entry of managedHookFiles) {
         if (enabled.has(entry.harness))
@@ -1075,6 +1077,12 @@ async function cleanLegacyArtifacts(projectRoot) {
 async function cleanStaleFiles(projectRoot) {
     const expectedShimFiles = new Set(harnessShimFileNames());
     for (const adapter of Object.values(HARNESS_ADAPTERS)) {
+        // Skill-kind shims (Codex) live in per-skill directories, not flat
+        // markdown files, so the regex-based stale sweep below would never
+        // match them anyway. The legacy `.codex/commands/` cleanup happens in
+        // `cleanupLegacyCodexSurfaces` inside syncHarnessShims().
+        if (adapter.shimKind === "skill")
+            continue;
         const commandDir = path.join(projectRoot, adapter.commandDir);
         if (!(await exists(commandDir)))
             continue;
@@ -1298,6 +1306,24 @@ export async function uninstallCclaw(projectRoot) {
             // directory not present
         }
     }
+    // v0.39.0 migrated Codex shims to `.agents/skills/cclaw-cc*/SKILL.md`
+    // (Codex CLI reads `.agents/skills/`, not `.codex/commands/`). On uninstall
+    // we remove just the cclaw-owned skill folders, not the whole
+    // `.agents/skills/` directory — other tools may share it.
+    const codexSkillsRoot = path.join(projectRoot, ".agents/skills");
+    try {
+        const entries = await fs.readdir(codexSkillsRoot);
+        for (const entry of entries) {
+            if (/^cclaw-(?:cc)(?:-.*)?$/u.test(entry)) {
+                await fs.rm(path.join(codexSkillsRoot, entry), { recursive: true, force: true });
+            }
+        }
+    }
+    catch {
+        // directory not present
+    }
+    await removeIfEmpty(codexSkillsRoot);
+    await removeIfEmpty(path.join(projectRoot, ".agents"));
     for (const pluginPath of [
         path.join(projectRoot, ".opencode/plugins/viby-plugin.mjs"),
         path.join(projectRoot, ".opencode/plugins/opencode-plugin.mjs"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {