baldart 4.79.0 → 4.80.1

package/CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.80.1] - 2026-06-29
+
+**Self-heal payload drift on an already-current install + a Codex-correct "agent not found" message.** Shipping v4.80.0 surfaced two gaps in the field, both from the same incident: a consumer's Codex session emitted the AGENTS.md STOP message for `codebase-architect`, yet the framework was already at v4.80.0. Two root causes:
+
+1. **CLI↔framework skew left the consumer stuck even after the framework reached 4.80.0.** The consumer's subtree was pulled to v4.80.0, but the `update` that pulled it ran with an **older global CLI** (4.76.x) whose `codex.agentsDir()` was still `null` — so the new Codex-agent payload was silently skipped, and `.codex/agents/` was never created. Worse, *re-running* `update` after aligning the CLI hit the **`Already up to date!` early-exit** (line ~893), which returned BEFORE the symlink/merge reconciliation block — so the version-aligned install never self-healed the missing payload (recoverable only via `baldart doctor`). Fix: the `isAligned` branch now runs the idempotent, additive per-item merges (skills/agents/commands/workflows/output-styles) **before** declaring "up to date". They stay silent when nothing is missing and emit a one-line "Reconciled N newly-shipped item(s)" when they heal real drift — so a CLI-skew victim self-heals on the next `update`, not only via `doctor`. This generalises: ANY future payload-kind addition (a new `MERGE_KINDS` entry) is now reconciled on version-aligned installs too.
+2. **The "agent not found" STOP message told a Codex user to "riavvia Claude Code".** The v4.80.0 AGENTS.md edit gave the Codex branch the Claude verbatim message. Fix: a **Codex-specific** message — *"Agent `<name>` non trovato tra i custom agent di Codex (`.codex/agents/<name>.toml`) — allinea la CLI (`npm i -g baldart@latest`), esegui `npx baldart update` (o `npx baldart doctor`), assicurati che il progetto sia trusted in Codex, poi riavvia la sessione Codex"* — encoding the exact remediation (CLI align → update → trust → restart; Codex loads `.codex/agents/` only in **trusted** projects, and discovers agents at session start).
+
+**PATCH** — script bugfix (update self-heals payload drift) + AGENTS.md message correction; no behaviour change on the happy path, no new config key. Existing v4.80.0 consumers should `npm i -g baldart@latest` (kill the skew at the source) then `npx baldart update`; the Codex session must be restarted to discover the newly-installed agents.
+
+### Changed
+
+- **`src/commands/update.js`** — the `Already up to date!` (`status.isAligned`) branch now runs the per-item merges before the early exit (self-heal of payload drift from a prior CLI-skew update), reports the healed count, and adds `reconciled_items` to the `already-current` JSON event.
+- **`framework/AGENTS.md`** — the no-silent-substitution rule's Codex branch now carries its own verbatim "agent not found" remediation message (was reusing the Claude "riavvia Claude Code" text).
+
+## [4.80.0] - 2026-06-29
+
+**Codex-native subagents — the 32 BALDART agents are now installed for Codex, not just Claude.** A portability bug surfaced in the field: a skill running on Codex delegated to `codebase-architect` (*"invoke the codebase-architect agent"*), but the agent did not exist in the Codex tree and there was no obvious mechanism to spawn it, so the model **improvised** a generic explorer sub-agent. Root cause (confirmed against the OpenAI Codex docs, June 2026): the framework treated subagents as Claude-only — the Codex tool adapter declared `supportsSubagents() === false` / `agentsDir() === null`, so the agent definitions under `framework/.claude/agents/` were **never installed into a Codex tree**. But **Codex now has custom agents** (subagents) — they were simply in a different shape than Claude's, and BALDART had not yet mapped them. This release closes that gap.
+
+Because a Codex custom agent is a **different on-disk artifact** than a Claude subagent — a TOML file at `.codex/agents/<name>.toml` with `name` / `description` / `developer_instructions` (+ optional `model_reasoning_effort`), spawned **by name** — the skill-style "one source, two symlinks" model does not apply. Instead the same `framework/.claude/agents/<name>.md` stays the **single SSOT** and BALDART **transpiles** it to `.toml` on install/update (new `src/utils/codex-agent-transpiler.js`): frontmatter `name`/`description` → same, body → `developer_instructions`, `effort` (low|medium|high|xhigh|max) → `model_reasoning_effort` (xhigh/max clamp to high), `model` **omitted on purpose** (opus/sonnet/haiku have no 1:1 Codex model → inherit the parent session). The generated `.toml` is a real file (you cannot symlink `.md` → `.toml`) carrying a `# baldart-generated:` marker, so an `update` regenerates it idempotently and a user fork (no marker) is never clobbered. Overlays apply **first** (the markdown `## [OVERRIDE]/[APPEND]/[PREPEND]` overlay is merged, then transpiled) — Codex agents honour `.baldart/overlays/agents/<name>.md` exactly like Claude. The transpile rides on the **existing** `MERGE_KINDS` machinery via one new adapter hook, `transpilerFor(kind)` (`codex` returns a transpiler for `agent`; `claude` returns null), so nothing else in the merge path changed and Claude is byte-for-byte unaffected. Existing Codex consumers pick it up on the next `npx baldart update`. AGENTS.md's "MUST invoke codebase-architect" + no-silent-fallback rules are now tool-aware (the agent exists on both tools; spawn by name on Codex). Verified end-to-end: all 32 real agents transpile to valid TOML (parsed with `@iarna/toml`), idempotency / source-change-regen / user-fork-protection / overlay-aware-transpile all pass.
+
+**Standing convention** (the user's explicit ask: *every agent from now on is natively Codex-compatible*): any new agent is auto-portable — drop a `.md` under `framework/.claude/agents/`, keep `name`+`description` frontmatter, put behaviour in the body (→ `developer_instructions`), and don't rely on an agent spawning a further agent (Codex `agents.max_depth: 1`, consistent with BALDART's `## Role boundary`). Skills were already Codex-native (identical format). Authoritative design: [`framework/docs/CODEX-AGENTS.md`](framework/docs/CODEX-AGENTS.md).
+
+**MINOR** — additive capability (Codex consumers gain 32 agents; existing Claude installs unchanged). **No new `baldart.config.yml` key** — rides on `tools.enabled` containing `codex`, so the schema-change propagation rule does NOT apply. Slash commands / dynamic workflows / output styles stay Claude-only (`commandsDir`/`workflowsDir`/`outputStylesDir` remain null for Codex — no Codex equivalent).
+
+### Added
+
+- **`src/utils/codex-agent-transpiler.js`** — pure `.md` → `.toml` transpiler (`mdAgentToToml`, `isGeneratedToml`, `mapEffort`). Emits `developer_instructions` as a TOML multi-line **literal** (`'''…'''`) so arbitrary markdown survives byte-for-byte, with an escaped `"""…"""` fallback only when the body itself contains `'''`.
+- **`framework/docs/CODEX-AGENTS.md`** — design + field-mapping table + the per-agent authoring contract.
+
+### Changed
+
+- **`src/utils/tool-adapters/codex.js`** — `agentsDir()` → `.codex/agents` (was null), `supportsSubagents()` → true (was false), new `transpilerFor(kind)` hook returning the TOML transpiler for `agent`. Header comment corrected (Codex DOES have custom agents now).
+- **`src/utils/tool-adapters/claude.js`** — added `transpilerFor()` → null (explicit no-op: Claude consumes every payload in its native format).
+- **`src/utils/symlinks.js`** — `_mergeBulkDir` routes a kind through the new `_installTranspiledFile` (generate tool-native file, overlay-merged first when present) when the adapter declares a transpiler; `verifySymlinks` recognises transpiled `.toml` (via `isGeneratedToml`) as framework-managed alongside symlinks and overlay-generated `.md`.
+- **`framework/AGENTS.md`** — the "MUST invoke `codebase-architect`" and no-silent-substitution rules are now tool-aware: the agent exists on both tools (Claude → Task/`subagent_type`; Codex → spawn by name at `.codex/agents/codebase-architect.toml`); the #56869 specifics stay Claude-scoped, the principle stays universal.
+- **`framework/.claude/agents/REGISTRY.md`** + **`CLAUDE.md`** — document the Codex-native subagent convention + the authoring contract.
+
 ## [4.79.0] - 2026-06-29
 
 **New skill `/ds-handoff` — the field-level, 1:1 Claude Design handoff brief.** When `/prd` reached the "hand off to Claude Design" branch, the prompt it produced described each screen only coarsely — *purpose / states / actions / data shown* — and never the exact fields. With no field-level contract, Claude Design **imagines** control types, required-ness, validation, defaults and enum values to cover the gap, so the result is never 1:1. The root cause: BALDART had **no mandatory phase** that enumerated a screen's real fields, and **no coverage gate** verifying them before the prompt was emitted (field discovery was manual discovery-questions). `/ds-handoff` fixes this end-to-end: it (1) identifies each screen's backing data entities, (2) **grounds the field inventory in the project's real schemas** (Zod / TS types / form schemas) by composing existing retrieval (code-graph → LSP → `codebase-architect` → Grep — **no new AST/Zod parser**, an over-scoped fragility the design refused), (3) reconciles fields↔screens (which fields show / are editable / group into which card), (4) runs a **coverage gate** that **BLOCKS** emission in interactive mode when a backed screen's `{control, required}` are unverified — degrading gracefully to user-confirmation when no formal schema exists (portable / Codex), (5) renders the **mandatory field-level template** (a 9-column field-inventory table per screen + actions / states / responsive). It becomes the **single SSOT** for the Claude Design prompt: `/prd` Step 3.0 Branch B now **delegates** to it (graceful inline-coarse fallback when the skill is unavailable), and the old inline `/prd` template is **retired**. Usable standalone via `/ds-handoff <screens-or-feature>` (e.g. an ad-hoc orchestrator + `ui-expert` run). A THIN orchestrator — it **cites** `design-system-protocol.md` (Functional Traceability Gate `backed/decorative/orphan` vocabulary + Reference Tables numbers) and **reads** `discovery-phase.md`'s `mockup_analysis` as input, never duplicating their rules (no dual-SSOT).

package/VERSION

@@ -1 +1 @@
-4.79.0
+4.80.1

package/framework/.claude/agents/REGISTRY.md

@@ -2,7 +2,9 @@
 
 Quick-reference for all custom agents. Use this to route tasks to the right specialist.
 
-**Location**: `.claude/agents/<name>.md` | **Invoke via**: `Task` tool with `subagent_type="<name>"`
+**Location**: `.claude/agents/<name>.md` | **Invoke via**: `Task` tool with `subagent_type="<name>"` (Claude) — or **by name** as a Codex custom agent (Codex)
+
+> **Codex-native (since v4.80.0)**: every agent here is portable to Codex. The same `<name>.md` is **transpiled** to `.codex/agents/<name>.toml` on install/update (`name`/`description` → same, body → `developer_instructions`, `effort` → `model_reasoning_effort`, `model` omitted). Authoring stays single-source: drop a `.md`, it auto-installs for both tools. Keep `name`+`description` frontmatter, put behaviour in the body, and don't rely on an agent spawning a further agent (Codex `agents.max_depth: 1`). Design: [`framework/docs/CODEX-AGENTS.md`](../../docs/CODEX-AGENTS.md).
 
 > **Machine-readable source of truth (since v3.20.0)**: the filesystem directory `framework/.claude/agents/` is authoritative for the list of BALDART agents. The `agent-discovery-gate.js` PreToolUse hook, the `agent-discovery-info.sh` SessionStart hook, and `baldart doctor` enumerate the directory directly (every `<name>.md` except this file is an agent — no manifest JSON is shipped). Adding a new agent means dropping `<name>.md` here; no other touchpoint.
 

package/framework/AGENTS.md

@@ -103,8 +103,8 @@ Conflict steps (must follow in order):
 ### 4.a — Universal MUST (apply to every project)
 
 - MUST treat `AGENTS.md` as authoritative for agent rules.
-- MUST invoke `codebase-architect` agent (via Task tool) whenever you need to understand codebase structure, existing patterns, or code architecture before planning or implementing changes; do not proceed with planning or implementation without first understanding the existing system through codebase-architect.
-- MUST NOT silently fall back when an `Agent` (a.k.a. `Task`) tool call returns empty (`0 tool uses · Done`), times out, or fails with `permissionDecision: deny`. This pattern indicates a Claude Code sub-agent failure (see anthropics/claude-code#56869) or a discovery miss / blocked agent (see #20931 and BALDART's own `agent-discovery-gate` PreToolUse hook), NOT a signal to substitute another agent. STOP, report to the user verbatim: "Agent `<name>` non discoverato o fallito in questa sessione — riavvia Claude Code e verifica con `npx baldart doctor`", and wait for direction. Never auto-route to `feature-dev:*`, `general-purpose`, or any other marketplace/built-in agent as a replacement. **This rule is the ONLY defense against bug #56869 (which BALDART cannot patch from outside Claude Code); deviating from it reintroduces the exact failure mode the rule exists to prevent.**
+- MUST invoke the `codebase-architect` agent whenever you need to understand codebase structure, existing patterns, or code architecture before planning or implementing changes; do not proceed with planning or implementation without first understanding the existing system through codebase-architect. **The agent exists on both tools** — Claude Code spawns it via the Task/Agent tool with `subagent_type: "codebase-architect"`; Codex spawns the `codebase-architect` custom agent **by name** (BALDART installs it at `.codex/agents/codebase-architect.toml`, transpiled from the same `.md` source). Only if your environment genuinely exposes NEITHER subagent mechanism (a stripped tool host) do you degrade — explicitly — to inline structural retrieval (code-graph → LSP → Grep → direct file reads per `agents/code-search-protocol.md`), and SAY SO; never silently skip the understanding step.
+- MUST NOT silently substitute a *different* agent when an agent invocation returns empty (`0 tool uses · Done`), times out, or fails with `permissionDecision: deny`. On **Claude Code** this pattern indicates a sub-agent failure (see anthropics/claude-code#56869) or a discovery miss / blocked agent (see #20931 and BALDART's own `agent-discovery-gate` PreToolUse hook): STOP, report to the user verbatim: "Agent `<name>` non discoverato o fallito in questa sessione — riavvia Claude Code e verifica con `npx baldart doctor`", and wait for direction. Never auto-route to `feature-dev:*`, `general-purpose`, or any other marketplace/built-in agent as a replacement. **This rule is the ONLY defense against bug #56869 (which BALDART cannot patch from outside Claude Code); deviating from it reintroduces the exact failure mode the rule exists to prevent.** On **Codex** the equivalent is spawning the custom agent by name; the same no-silent-substitution rule holds — but the remediation differs, so STOP and report the **Codex-specific** message verbatim: "Agent `<name>` non trovato tra i custom agent di Codex (`.codex/agents/<name>.toml`) — allinea la CLI (`npm i -g baldart@latest`), esegui `npx baldart update` (o `npx baldart doctor`), assicurati che il progetto sia *trusted* in Codex, poi riavvia la sessione Codex", and wait for direction. (The #56869 specifics are Claude-only; the no-silent-substitution principle is universal.)
 - MUST NOT work on files/components already claimed by another agent; multiple agents allowed if working on independent areas.
 - MUST perform a mandatory clarity analysis before fixing any issue labeled `bug`; confirm that the issue description, proposed correct behavior, and edge cases are unambiguous, document any resolved doubts, and only start fix work once every zone of uncertainty is covered.
 - MUST mark missing info as UNKNOWN and ask the user; if blocked, set `BLOCKED` with a blocker.

package/framework/docs/CODEX-AGENTS.md

@@ -0,0 +1,111 @@
+# Codex-native subagents
+
+> **Status:** shipped in v4.80.0. Claude + Codex. No new `baldart.config.yml` key —
+> rides on `tools.enabled` containing `codex`.
+
+## The problem this fixes
+
+BALDART's skills delegate code-understanding, review, and planning to named
+**subagents** (`codebase-architect`, `code-reviewer`, `plan-auditor`, …). For a
+long time those agents were treated as a Claude-only construct: the Codex tool
+adapter declared `supportsSubagents() === false` and `agentsDir() === null`, so
+the 32 agent definitions under `framework/.claude/agents/` were **never installed
+into a Codex tree**.
+
+The result, on Codex: a skill said *"invoke the `codebase-architect` agent"*, the
+agent did not exist, there was no obvious mechanism to spawn it, and the model
+**improvised** — e.g. falling back to a generic "explorer" sub-agent. Not a
+comprehension failure; a missing portability contract.
+
+Meanwhile Codex shipped **custom agents** (subagents). So the fix is not "degrade
+on Codex" — it is "install the agents on Codex, in Codex's own format".
+
+## Why a transpiler, not a symlink
+
+Skills are portable by **symlink** because the on-disk format is identical for
+both tools (`SKILL.md` + frontmatter). One source, two symlinks, zero
+duplication.
+
+A subagent is **not** identical across tools:
+
+| | Claude Code | Codex |
+|---|---|---|
+| Location | `.claude/agents/<name>.md` | `.codex/agents/<name>.toml` |
+| Format | Markdown + YAML frontmatter | TOML |
+| Required fields | `name`, `description` + body | `name`, `description`, `developer_instructions` |
+| Effort knob | `effort: low\|…\|max` | `model_reasoning_effort: low\|medium\|high` |
+| Invocation | Task/Agent tool, `subagent_type` | spawned **by `name`** |
+| Nesting | (orchestrator spawns) | `agents.max_depth: 1` (no deeper nesting) |
+
+Because the format differs, the same `framework/.claude/agents/<name>.md` stays
+the **single source of truth** and BALDART **generates** the `.toml` from it on
+install/update. The generated file is a real file (you cannot symlink a `.md`
+source onto a `.toml` target), carrying a `# baldart-generated:` marker so:
+
+- a later `update` regenerates it safely (idempotent — unchanged source → no rewrite),
+- a user fork (a `.toml` without the marker) is **never clobbered** (recorded as a conflict).
+
+## Field mapping (`.md` → `.toml`)
+
+Implemented in [`src/utils/codex-agent-transpiler.js`](../../src/utils/codex-agent-transpiler.js):
+
+| Claude frontmatter / body | Codex TOML | Notes |
+|---|---|---|
+| `name` | `name` | spawn identity; source of truth |
+| `description` | `description` | collapsed to a single line |
+| markdown body | `developer_instructions` | the agent's system prompt; emitted as a TOML multi-line **literal** (`'''…'''`) so backslashes/quotes survive byte-for-byte (falls back to escaped `"""…"""` only if the body itself contains `'''`) |
+| `effort: low\|medium\|high\|xhigh\|max` | `model_reasoning_effort: low\|medium\|high` | `xhigh`/`max` clamp to `high` |
+| `model: opus\|sonnet\|haiku` | *(omitted)* | no 1:1 Codex model → inherit the parent session model (the safe default) |
+
+Overlays apply **first**: when `.baldart/overlays/agents/<name>.md` exists the
+markdown overlay is merged (the normal `## [OVERRIDE]/[APPEND]/[PREPEND]`
+machinery), then the merged markdown is transpiled — so Codex agents honour
+overlays exactly like Claude agents. The overlay's HTML-comment marker is
+stripped before it can leak into `developer_instructions`.
+
+## How it is wired
+
+The transpile rides on the **existing** per-item merge machinery
+(`SymlinkUtils._mergeBulkDir`) through one new adapter hook:
+
+```js
+// codex.js
+agentsDir() { return '.codex/agents'; }   // was null
+supportsSubagents() { return true; }       // was false
+transpilerFor(kind) {                      // NEW
+  if (kind !== 'agent') return null;
+  const t = require('../codex-agent-transpiler');
+  return { outExt: '.toml', transform: t.mdAgentToToml, isGenerated: t.isGeneratedToml };
+}
+```
+
+When `_mergeBulkDir` sees a non-null `transpilerFor(kind)` it routes that kind
+through `_installTranspiledFile` (generate `.toml`) instead of the symlink /
+overlay path. `claude.transpilerFor()` returns null, so Claude is unchanged
+(agents still symlinked `.md`). `commandsDir`/`workflowsDir`/`outputStylesDir`
+stay null for Codex — slash commands, dynamic workflows, and output styles have
+no Codex equivalent.
+
+Existing Codex consumers pick this up automatically on the next
+`npx baldart update` (which calls `mergeAgents`), and `baldart doctor`'s
+`mergeAgents` backfill covers any drift.
+
+## The authoring contract (for every new agent, from now on)
+
+Any new agent is **auto-portable** — just drop a `.md` under
+`framework/.claude/agents/`. To keep it clean across both tools:
+
+1. **Keep `name` + `description` in the frontmatter.** `name` is the spawn
+   identity on both tools; `description` is how Codex chooses which agent to spawn.
+2. **Put the agent's behaviour in the body** — it becomes `developer_instructions`.
+3. **Set `effort:`** if the agent needs a non-default reasoning tier; it maps to
+   `model_reasoning_effort`.
+4. **Do not rely on a subagent spawning a further subagent.** Codex caps
+   `agents.max_depth` at 1 — consistent with BALDART's own `## Role boundary`
+   ("no Task/Agent tool") convention and the "nested subagents not available"
+   reality on Claude. Orchestration belongs to the skill, not the agent.
+5. **Avoid Claude-only tool references in the body that have no Codex analogue.**
+   Prefer the portable retrieval cascade (code-graph → LSP → Grep → reads).
+
+Nothing else is required — no per-agent Codex file, no registry entry beyond the
+usual `REGISTRY.md` row.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.79.0",
+  "version": "4.80.1",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/update.js

@@ -891,11 +891,33 @@ async function update(options = {}, unknownArgs = []) {
     // VERSION-compare authority. Subtree-merge commit count is noise; never
     // use behind > 0 as the up-to-date signal (root cause of v3.24.x bug).
     if (status.isAligned) {
+      // Even when the VERSION is aligned, the per-item PAYLOAD may be stale.
+      // The failure class: a consumer updates with an OLDER CLI (CLI↔framework
+      // skew) → gets the new framework content but the old reconciliation logic,
+      // so a newly-added payload kind (e.g. Codex agents in v4.80.0, where
+      // `codex.agentsDir()` flipped from null to `.codex/agents`) is silently
+      // skipped. Later aligning the CLI and re-running `update` hit this early
+      // "already current" exit and NEVER reconciled — leaving the consumer
+      // stuck (recoverable only via `doctor`). The per-item merges are
+      // idempotent + additive and stay SILENT when nothing is missing, so run
+      // them here: an up-to-date install now self-heals payload drift too.
+      const alignedTools = readEnabledTools();
+      const reconciled = [
+        symlinks.mergeSkills({ tools: alignedTools }),
+        symlinks.mergeAgents({ tools: alignedTools }),
+        symlinks.mergeCommands({ tools: alignedTools }),
+        symlinks.mergeWorkflows({ tools: alignedTools }),
+        symlinks.mergeOutputStyles({ tools: alignedTools })
+      ].reduce((n, r) => n + ((r.linked && r.linked.length) || 0) + ((r.generated && r.generated.length) || 0), 0);
+      if (reconciled > 0) {
+        UI.info(`Reconciled ${reconciled} newly-shipped item(s) into per-tool dir(s) — payload drift from a prior CLI-skew update, now healed.`);
+      }
       UI.success(`Already up to date! (v${status.installedVersion})`);
       emitUpdateJson({ ok: true, action: 'already-current',
         installed_before: status.installedVersion,
         installed_after: status.installedVersion,
-        remote_version: status.remoteVersion }, 0);
+        remote_version: status.remoteVersion,
+        reconciled_items: reconciled }, 0);
     }
 
     UI.warning(`Update available: v${status.installedVersion} → v${status.remoteVersion}`);

package/src/utils/codex-agent-transpiler.js

@@ -0,0 +1,139 @@
+const yaml = require('js-yaml');
+
+/**
+ * Codex agent transpiler — turns a BALDART Claude subagent definition
+ * (`.claude/agents/<name>.md`, YAML frontmatter + markdown body) into a Codex
+ * custom-agent definition (`.codex/agents/<name>.toml`).
+ *
+ * Why a transpiler and not a symlink (the model used for skills): a skill has
+ * the SAME on-disk format for Claude and Codex, so one source file is linked
+ * into two places. A subagent does NOT — Codex custom agents are TOML files
+ * with a different field set, living under a different root (`.codex/agents/`,
+ * not `.agents/skills/`). So the SAME source `.md` is the SSOT and we *generate*
+ * the `.toml` from it on install/update. Edit the `.md`; never hand-edit the
+ * generated `.toml`.
+ *
+ * Field mapping (Claude frontmatter → Codex TOML):
+ *   name        → name                    (source of truth for spawn identity)
+ *   description → description             (single-lined)
+ *   <body>      → developer_instructions  (the agent's system prompt)
+ *   effort      → model_reasoning_effort  (low|medium|high — see mapEffort)
+ *   model       → (OMITTED on purpose)    opus/sonnet/haiku have no 1:1 Codex
+ *                                          model; inheriting the parent session
+ *                                          model is the safe, correct default.
+ *
+ * Codex docs: developers.openai.com/codex/subagents — required fields are
+ * `name`, `description`, `developer_instructions`; optional `model`,
+ * `model_reasoning_effort`, `sandbox_mode`, `nickname_candidates`,
+ * `mcp_servers`, `skills.config`. Agents are spawned by their `name`.
+ */
+
+const TOML_MARKER_PREFIX = '# baldart-generated:';
+
+/**
+ * Map a BALDART effort tier (low|medium|high|xhigh|max — see
+ * framework/agents/effort-protocol.md) onto Codex's `model_reasoning_effort`,
+ * which only accepts low|medium|high. xhigh/max clamp to high (the ceiling).
+ * Returns null when there's nothing to map (omit the key → inherit parent).
+ */
+function mapEffort(effort) {
+  if (!effort) return null;
+  const e = String(effort).trim().toLowerCase();
+  if (e === 'low') return 'low';
+  if (e === 'medium') return 'medium';
+  if (e === 'high' || e === 'xhigh' || e === 'max') return 'high';
+  return null;
+}
+
+/** Split leading YAML frontmatter from the markdown body. */
+function splitFrontmatter(md) {
+  let rest = String(md).replace(/^/, '');
+  const m = rest.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (m) return { frontmatter: m[1], body: rest.slice(m[0].length) };
+  return { frontmatter: '', body: rest };
+}
+
+/**
+ * Strip a leading `<!-- baldart-generated: … -->` HTML-comment marker. Present
+ * only when the source markdown was overlay-merged (the marker sits right after
+ * the frontmatter); it must not leak into developer_instructions.
+ */
+function stripHtmlMarker(body) {
+  return String(body).replace(/^\s*<!--\s*baldart-generated:[\s\S]*?-->\s*\n/, '');
+}
+
+/** Emit a TOML basic (single-line) string with the required escapes. */
+function tomlBasicString(s) {
+  return '"' + String(s)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/[\r\n\t]+/g, ' ')
+    .trim() + '"';
+}
+
+/**
+ * Emit a TOML multi-line string for an arbitrary markdown body.
+ *
+ * Prefer a multi-line LITERAL string (`'''…'''`): it processes no escapes, so
+ * markdown full of backslashes and double-quotes survives byte-for-byte. The
+ * only thing it cannot contain is `'''`, so fall back to a multi-line BASIC
+ * string (`"""…"""`) with escaping when the body has a triple-single-quote.
+ * A leading newline (trimmed by the TOML spec) keeps the body starting exactly
+ * as authored; a trailing newline keeps a body-final quote from abutting the
+ * closing delimiter.
+ */
+function tomlMultiline(s) {
+  const body = String(s).replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  if (!body.includes("'''")) {
+    return "'''\n" + body + "\n'''";
+  }
+  const esc = body.replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"');
+  return '"""\n' + esc + '\n"""';
+}
+
+/**
+ * Transpile one Claude agent `.md` into Codex `.toml` text.
+ * @param {string} markdown - raw `.md` content (frontmatter + body)
+ * @param {{name?: string, frameworkVersion?: string}} [opts]
+ * @returns {string} TOML content (ends with a trailing newline)
+ */
+function mdAgentToToml(markdown, opts = {}) {
+  const { frontmatter, body } = splitFrontmatter(markdown);
+  let meta = {};
+  if (frontmatter) {
+    try { meta = yaml.load(frontmatter) || {}; }
+    catch (_) { meta = {}; }
+  }
+
+  const name = String(meta.name || opts.name || '').trim();
+  if (!name) {
+    throw new Error('codex-agent-transpiler: agent has no `name` (neither frontmatter nor filename provided one)');
+  }
+  const description = String(meta.description || '').replace(/\s+/g, ' ').trim();
+  const instructions = stripHtmlMarker(body).replace(/^\n+/, '').replace(/\n+$/, '\n');
+  const effort = mapEffort(meta.effort);
+
+  const lines = [];
+  lines.push(`${TOML_MARKER_PREFIX} kind=agent name=${name} v=${opts.frameworkVersion || 'unknown'}`);
+  lines.push(`# Transpiled from .claude/agents/${name}.md by BALDART — edit the source, not this file.`);
+  lines.push(`name = ${tomlBasicString(name)}`);
+  if (description) lines.push(`description = ${tomlBasicString(description)}`);
+  if (effort) lines.push(`model_reasoning_effort = ${tomlBasicString(effort)}`);
+  lines.push(`developer_instructions = ${tomlMultiline(instructions)}`);
+
+  return lines.join('\n') + '\n';
+}
+
+/** True when a TOML file was generated by BALDART (safe to overwrite/regenerate). */
+function isGeneratedToml(content) {
+  return typeof content === 'string' && content.includes(TOML_MARKER_PREFIX);
+}
+
+module.exports = {
+  mdAgentToToml,
+  isGeneratedToml,
+  mapEffort,
+  splitFrontmatter,
+  tomlMultiline,
+  TOML_MARKER_PREFIX
+};

package/src/utils/symlinks.js

@@ -425,6 +425,18 @@ class SymlinkUtils {
         const overlayAbs = path.join(this.cwd, overlayRel);
         const hasOverlay = cfg.overlay && fs.existsSync(overlayAbs);
 
+        // Transpile path: when the adapter declares a transpiler for this kind
+        // (e.g. Codex agents → TOML), do NOT symlink the `.md` source — generate
+        // the tool-native file from it (overlay-merged first when present).
+        const transpiler = (typeof adapter.transpilerFor === 'function') ? adapter.transpilerFor(kind) : null;
+        if (transpiler) {
+          this._installTranspiledFile({
+            kind, baseName, fwAbsolute, overlayAbs, hasOverlay,
+            targetRel, transpiler, adapter, frameworkVersion, aggregate
+          });
+          continue;
+        }
+
         // Inspect what currently lives at the link path (if anything).
         let lstat = null;
         try { lstat = fs.lstatSync(linkPath); } catch (_) { /* absent */ }
@@ -525,6 +537,77 @@ class SymlinkUtils {
     });
   }
 
+  /**
+   * Install a transpiled payload for a tool whose on-disk format differs from
+   * the framework source (currently: Codex agents, `.md` → `.toml`).
+   *
+   * The framework `.md` stays the single SSOT; the `.toml` is *generated* (a
+   * real file, never a symlink — you can't symlink a `.md` source to a `.toml`
+   * target). When an overlay exists it is merged FIRST (reusing the markdown
+   * overlay machinery), so Codex agents honour overlays exactly like Claude
+   * agents do, then the merged markdown is transpiled. The output carries a
+   * `# baldart-generated:` marker so a later update can safely regenerate it
+   * and a user fork (no marker) is never clobbered.
+   */
+  _installTranspiledFile({ kind, baseName, fwAbsolute, overlayAbs, hasOverlay, targetRel, transpiler, adapter, frameworkVersion, aggregate }) {
+    const outName = `${baseName}${transpiler.outExt}`;
+    const outPath = path.join(this.cwd, targetRel, outName);
+    const relOut = path.join(targetRel, outName);
+
+    // Effective markdown = overlay-merged when an overlay exists, else the base.
+    const baseContent = fs.readFileSync(fwAbsolute, 'utf8');
+    let effectiveMd = baseContent;
+    if (hasOverlay) {
+      try {
+        const { mergeOverlay } = require('./overlay-merger');
+        const overlayContent = fs.readFileSync(overlayAbs, 'utf8');
+        const merged = mergeOverlay({ kind, name: baseName, baseContent, overlayContent, frameworkVersion });
+        effectiveMd = merged.generated;
+        (merged.warnings || []).forEach((w) => {
+          UI.warning(`[${adapter.label}] ${kind} ${baseName}: ${w}`);
+          aggregate.warnings.push({ tool: adapter.name, kind, name: baseName, warning: w });
+        });
+      } catch (_) { effectiveMd = baseContent; /* fail-safe: transpile the base */ }
+    }
+
+    let outContent;
+    try {
+      outContent = transpiler.transform(effectiveMd, { name: baseName, frameworkVersion });
+    } catch (err) {
+      UI.warning(`[${adapter.label}] ${kind} ${baseName}: transpile failed (${err.message}) — skipped.`);
+      aggregate.warnings.push({ tool: adapter.name, kind, name: baseName, warning: `transpile-failed: ${err.message}` });
+      return;
+    }
+
+    let lstat = null;
+    try { lstat = fs.lstatSync(outPath); } catch (_) { /* absent */ }
+    if (lstat) {
+      if (lstat.isSymbolicLink()) {
+        // Stale symlink from an earlier layout — replace with the generated file.
+        fs.unlinkSync(outPath);
+      } else {
+        const existing = fs.readFileSync(outPath, 'utf8');
+        if (!transpiler.isGenerated(existing)) {
+          UI.warning(`[${adapter.label}] ${kind} ${baseName}: ${relOut} exists without a baldart-generated marker — NOT overwriting (user fork?).`);
+          aggregate.conflicts.push({
+            tool: adapter.name, kind, name: baseName,
+            local_path: relOut, reason: 'manual-edit-no-marker',
+            detected_at: new Date().toISOString()
+          });
+          return;
+        }
+        if (existing === outContent) {
+          aggregate.skipped.push({ tool: adapter.name, kind, name: baseName, reason: 'already-generated' });
+          return;
+        }
+      }
+    }
+
+    fs.writeFileSync(outPath, outContent);
+    UI.success(`[${adapter.label}] ${kind} transpiled: ${relOut}`);
+    aggregate.generated.push({ tool: adapter.name, kind, name: baseName });
+  }
+
   _generateOverlayedFile({ kind, name, fwAbsolute, overlayAbs, linkPath, lstat, frameworkVersion, aggregate, adapter, targetRel }) {
     const { mergeOverlay, isGeneratedFile, computeBaseFileSha, ensureBaseFileShaInOverlay, refreshOverlayVersionPin } = require('./overlay-merger');
     const baseContent = fs.readFileSync(fwAbsolute, 'utf8');
@@ -706,12 +789,16 @@ class SymlinkUtils {
           allValid = false;
         } else {
           const { isGeneratedFile } = require('./overlay-merger');
+          const { isGeneratedToml } = require('./codex-agent-transpiler');
           const entries = fs.readdirSync(full);
           const frameworkOwned = entries.filter((n) => {
             const p = path.join(full, n);
             try {
               if (fs.lstatSync(p).isSymbolicLink()) return true;
-              return isGeneratedFile(fs.readFileSync(p, 'utf8'));
+              // Symlinked (Claude .md) OR transpiled-generated (Codex .toml) OR
+              // overlay-generated (Claude .md with HTML marker).
+              const c = fs.readFileSync(p, 'utf8');
+              return isGeneratedFile(c) || isGeneratedToml(c);
             } catch { return false; }
           });
           if (frameworkOwned.length === 0) {

package/src/utils/tool-adapters/claude.js

@@ -35,6 +35,13 @@ class ClaudeAdapter {
   /** Where this tool reads output-style definitions from (null if unsupported). */
   outputStylesDir() { return '.claude/output-styles'; }
 
+  /**
+   * Per-kind transpiler hook. Claude consumes every payload in its native
+   * on-disk format, so nothing is transpiled — the merge machinery symlinks
+   * the source verbatim. (Codex returns a transpiler for `agent`.)
+   */
+  transpilerFor(/* kind */) { return null; }
+
   /** Whether this tool consumes subagent definitions (`.claude/agents/`). */
   supportsSubagents() { return true; }
 

package/src/utils/tool-adapters/codex.js

@@ -19,9 +19,16 @@ const os = require('os');
  * Codex reads from `.agents/skills/<x>`, and both follow the symlink to
  * the single source under `.framework/framework/.claude/skills/<x>/`.
  *
- * Codex does NOT have an equivalent of Claude subagents (`.claude/agents/`)
- * or slash commands (custom prompts are deprecated in favor of skills).
- * AGENTS.md at the repo root IS read by Codex — same convention as Claude.
+ * Codex DOES have custom agents (since the subagents feature shipped), but in
+ * a different shape than Claude: TOML files under `.codex/agents/` (project) or
+ * `~/.codex/agents/` (personal), with fields name / description /
+ * developer_instructions (+ optional model_reasoning_effort, sandbox_mode, …),
+ * spawned by `name`. Because the format differs from Claude's markdown
+ * subagents, BALDART does not symlink them — it *transpiles* the same `.md`
+ * source into `.toml` via `codex-agent-transpiler` (see `transpilerFor`).
+ * Slash commands have no Codex equivalent (custom prompts are deprecated in
+ * favor of skills). AGENTS.md at the repo root IS read by Codex — same
+ * convention as Claude.
  */
 class CodexAdapter {
   constructor(cwd = process.cwd()) {
@@ -33,13 +40,27 @@ class CodexAdapter {
 
   skillsDir() { return '.agents/skills'; }
 
-  // Codex has no equivalent of Claude subagents or slash commands (custom
-  // prompts are deprecated in favor of skills). Returning null disables the
-  // per-item merge for those kinds — adapters that DO support them return
-  // the target directory string.
-  agentsDir() { return null; }
+  // Codex custom agents live under `.codex/agents/` as TOML files. They are
+  // NOT symlinked from the `.md` source (the format differs) — the merge
+  // machinery routes this kind through `transpilerFor('agent')` to *generate*
+  // a `.toml` from each source `.md`. Slash commands have no Codex equivalent
+  // (custom prompts are deprecated in favor of skills) → null disables that merge.
+  agentsDir() { return '.codex/agents'; }
   commandsDir() { return null; }
 
+  /**
+   * Per-kind transpiler. The merge machinery (`SymlinkUtils._mergeBulkDir`)
+   * calls this for every merge kind; a non-null return means "do NOT symlink
+   * the `.md` source — generate `outExt` content from it via `transform`".
+   * Only `agent` is transpiled (markdown subagent → Codex TOML); every other
+   * kind returns null (and Codex already disables them via a null dirGetter).
+   */
+  transpilerFor(kind) {
+    if (kind !== 'agent') return null;
+    const t = require('../codex-agent-transpiler');
+    return { outExt: '.toml', transform: t.mdAgentToToml, isGenerated: t.isGeneratedToml };
+  }
+
   // Codex has no equivalent of Claude Code dynamic workflows (the JS
   // orchestration runtime is Claude-only). Returning null disables the
   // per-item workflow merge for Codex — the same source workflow scripts are
@@ -51,7 +72,7 @@ class CodexAdapter {
   // Codex — the source style files are simply never linked into a Codex tree.
   outputStylesDir() { return null; }
 
-  supportsSubagents() { return false; }
+  supportsSubagents() { return true; }
   supportsSlashCommands() { return false; }
   supportsHooks() { return false; }