baldart 3.6.4 → 3.7.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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).
 
+## [3.7.0] - 2026-05-22
+
+BALDART is now AI-tool agnostic. Every framework skill is installed into both Claude Code (`.claude/skills/`) AND OpenAI Codex CLI (`.agents/skills/`) when both are enabled — same source, two symlinks, zero duplication. Codex skill format is structurally identical to Claude's (`SKILL.md` with `name` + `description` frontmatter + optional `scripts/`/`references/`/`assets/`), so the same file works for both runtimes.
+
+### Added
+
+- **`src/utils/tool-adapters/`** — new adapter registry (mirrors the existing `routine-adapters/` pattern). Each adapter declares the directory its tool reads skills from, plus capability flags (subagents, slash commands, hooks). Currently: `claude.js`, `codex.js`. Adding Cursor / Aider / Cline later is a one-file addition.
+- **`tools.enabled` in `baldart.config.yml`** — array of enabled tool names. Default: `[claude]`, plus `codex` if `~/.codex/` is detected on the user's machine. Honored by `add`, `update`, `migrate`, and `verifySymlinks`.
+- **`baldart configure` AI-tools section** — prompts per available tool with the autodetected default. Refuses to disable Claude (the framework's primary target).
+- **`AUTODETECTED` summary** now shows `AI tools: claude, codex`.
+
+### Changed
+
+- **`SymlinkUtils.mergeSkills({ tools })`** — runs the per-item merge once per enabled tool, resolving each tool's target directory via its adapter. The same source under `.framework/framework/.claude/skills/<skill>/` is linked into every enabled tool's expected location.
+- **`SymlinkUtils.createAllSymlinks({ tools })`** — accepts the tool list and passes it through to `mergeSkills`.
+- **`SymlinkUtils.verifySymlinks()`** — reads `tools.enabled` from `baldart.config.yml` and validates each tool's skills dir separately. Output lines are now tagged `[Claude Code]` / `[OpenAI Codex CLI]`.
+- **Per-item skill merge resilience** — `_mergeSkillsForTool` now detects broken symlinks via `fs.lstatSync` and re-links them silently instead of crashing on EEXIST (same fix-pattern as v3.5.1, now applied per-tool).
+
+### Why it matters
+
+Until now BALDART was Claude-Code-only by construction. A consumer using Codex saw nothing — Codex's discovery walks `.agents/skills/`, and the framework had no awareness of that path. v3.7.0 makes the install universal: declare `tools.enabled: [claude, codex]` (or both, autodetected) and Codex picks up the same 24 skills, indexed by its own discovery, with `AGENTS.md` at the root continuing to work for both as it did before. Adding more tools later (Cursor `.cursor/rules/`, Aider `CONVENTIONS.md`, Cline, etc.) only requires writing a new adapter — the rest of the install pipeline is already tool-pluggable.
+
+### Out of scope (Codex-specific limitations)
+
+- **Subagents** (Claude's `.claude/agents/<name>.md`) have no Codex equivalent. They remain Claude-only. AGENTS.md sections cover the cross-tool coordination protocol.
+- **Slash commands** (Claude's `.claude/commands/`) — Codex deprecated custom prompts in favor of skills, so `/commandX` patterns stay Claude-only. If you want a workflow callable from Codex, author it as a skill.
+- **Hooks** (Claude's `.claude/hooks/`) — Codex has no equivalent hook system. `framework-edit-gate` remains a Claude-only safety net.
+
 ## [3.6.4] - 2026-05-22
 
 Two configure-flow fixes surfaced by a real-world `mayo` install audit.

package/VERSION

@@ -1 +1 @@
-3.6.4
+3.7.0

package/framework/templates/baldart.config.template.yml

@@ -111,3 +111,17 @@ features:
 
   # LLM-wiki overlay (paths.wiki_dir + capture/wiki-curator loop).
   has_wiki_overlay: false
+
+# ─── TOOLS ───────────────────────────────────────────────────────────────
+# Which AI CLI tools should the framework target on this machine?
+# Each enabled tool gets its own per-item skill symlinks pointing at the
+# SAME source under `.framework/framework/.claude/skills/<skill>/` (no
+# duplication — Claude reads `.claude/skills/`, Codex reads `.agents/skills/`).
+#
+# Adding "codex" exposes every framework skill to OpenAI Codex CLI as well.
+# The set of supported tools is defined by adapters under
+# `src/utils/tool-adapters/`. Currently: claude, codex.
+tools:
+  enabled:
+    - claude
+    # - codex   # uncomment to also install for OpenAI Codex CLI

package/package.json

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

package/src/commands/add.js

@@ -119,8 +119,13 @@ async function add(repo, options) {
     UI.newline();
     // First-time install: 'safe' mode preserves any pre-existing user
     // customisations without prompting (no destructive backups on fresh
-    // install paths). Per-skill merge always runs.
-    await symlinks.createAllSymlinks({ mode: 'safe' });
+    // install paths). Per-skill merge runs for every enabled tool — by
+    // default `['claude']`, plus `'codex'` if `~/.codex/` is present on
+    // the user's machine (autodetected). Run `npx baldart configure` to
+    // change the selection.
+    const toolAdapters = require('../utils/tool-adapters');
+    const enabledTools = toolAdapters.defaultEnabled();
+    await symlinks.createAllSymlinks({ mode: 'safe', tools: enabledTools });
 
     UI.newline();
     symlinks.copyCustomizableFiles();

package/src/commands/configure.js

@@ -2,6 +2,7 @@ const fs = require('fs');
 const path = require('path');
 const yaml = require('js-yaml');
 const UI = require('../utils/ui');
+const toolAdapters = require('../utils/tool-adapters');
 
 const CONFIG_FILE = 'baldart.config.yml';
 // The subtree pull copies the entire BALDART repo (which itself has a
@@ -298,6 +299,9 @@ function detect(cwd = process.cwd()) {
       has_prd_workflow: exists('docs/prd'),
       has_wiki_overlay: exists('docs/wiki'),
     },
+    tools: {
+      enabled: toolAdapters.defaultEnabled(cwd)
+    },
   };
 
   // Reference walkFirst once so the dead-code linter is happy and the helper
@@ -394,6 +398,32 @@ async function interactivePrompts(merged, detected) {
     ? segments.split(',').map((s) => s.trim()).filter(Boolean)
     : [];
 
+  // ---- AI tools (which CLI tools should this install target?) -----------
+  UI.section('AI tools (which tools should consume the framework?)');
+  merged.tools = merged.tools || {};
+  const allTools = toolAdapters.listAdapters();
+  const currentEnabled = (merged.tools.enabled && merged.tools.enabled.length)
+    ? merged.tools.enabled
+    : detected.tools.enabled;
+  for (const toolName of allTools) {
+    const adapter = toolAdapters.getAdapter(toolName);
+    const currentlyOn = currentEnabled.includes(toolName);
+    const detectedHint = (toolName !== 'claude' && detected.tools.enabled.includes(toolName))
+      ? ' (detected on this machine)' : '';
+    const want = await UI.confirm(`Install for ${adapter.label}?${detectedHint}`, currentlyOn);
+    if (want && !currentEnabled.includes(toolName)) currentEnabled.push(toolName);
+    if (!want) {
+      const idx = currentEnabled.indexOf(toolName);
+      if (idx >= 0) currentEnabled.splice(idx, 1);
+    }
+  }
+  // Claude is the framework's primary target — refuse to disable it entirely.
+  if (!currentEnabled.includes('claude')) {
+    UI.warning('Claude Code cannot be disabled (primary target). Re-enabling.');
+    currentEnabled.unshift('claude');
+  }
+  merged.tools.enabled = currentEnabled;
+
   UI.section('Features (explicit yes/no — option A: always ask)');
   for (const flag of [
     ['has_design_system', 'Project has a documented design system?'],
@@ -541,6 +571,7 @@ async function configure(opts = {}) {
 
   UI.box('AUTODETECTED', [
     `Brand name:      ${detected.identity.brand_name || '—'}`,
+    `AI tools:        ${detected.tools.enabled.join(', ')}`,
     `Design system:   ${detected.features.has_design_system ? 'yes' : 'no'}`,
     `  └─ signals:    ${dsSignalLabels}`,
     `UI guidelines:   ${detected.paths.ui_guidelines || '— (none found)'}`,

package/src/commands/migrate.js

@@ -115,7 +115,19 @@ async function migrate() {
   // --- Step 2: per-item framework skill merge ----------------------------
 
   UI.section('Step 2: merge framework skills (per-item)');
-  const mergeResult = symlinks.mergeSkills();
+  // Read tools from config so migrate honors the user's per-tool selection.
+  let enabledTools = ['claude'];
+  try {
+    const yaml = require('js-yaml');
+    const cfgPath = path.join(cwd, 'baldart.config.yml');
+    if (fs.existsSync(cfgPath)) {
+      const cfg = yaml.load(fs.readFileSync(cfgPath, 'utf8'));
+      if (Array.isArray(cfg?.tools?.enabled) && cfg.tools.enabled.length) {
+        enabledTools = cfg.tools.enabled;
+      }
+    }
+  } catch (_) { /* keep default */ }
+  const mergeResult = symlinks.mergeSkills({ tools: enabledTools });
   UI.info(`Linked ${mergeResult.linked.length} framework skills, kept ${mergeResult.skipped.length} as-is, ${mergeResult.conflicts.length} conflict(s).`);
 
   // --- Step 3: restore user skills from .backup --------------------------

package/src/commands/update.js

@@ -4,6 +4,21 @@ const UI = require('../utils/ui');
 const State = require('../utils/state');
 const Hooks = require('../utils/hooks');
 
+function readEnabledTools(cwd = process.cwd()) {
+  try {
+    const fs = require('fs');
+    const path = require('path');
+    const yaml = require('js-yaml');
+    const cfgPath = path.join(cwd, 'baldart.config.yml');
+    if (!fs.existsSync(cfgPath)) return ['claude'];
+    const cfg = yaml.load(fs.readFileSync(cfgPath, 'utf8'));
+    if (Array.isArray(cfg?.tools?.enabled) && cfg.tools.enabled.length) {
+      return cfg.tools.enabled;
+    }
+  } catch (_) { /* fall through */ }
+  return ['claude'];
+}
+
 // Path prefixes BALDART itself writes during install/update. Anything outside
 // these patterns is treated as user-owned and never auto-staged.
 const BALDART_MANAGED_PATTERNS = [
@@ -297,24 +312,26 @@ async function update(options = {}) {
     UI.newline();
     UI.section('Verifying Symlinks');
 
+    // Read enabled tools from baldart.config.yml so updates respect the
+    // user's per-tool selection (Claude only / Claude + Codex / …).
+    const enabledTools = readEnabledTools();
+
     const symlinkValid = symlinks.verifySymlinks();
     if (!symlinkValid) {
       UI.info('Some symlinks are missing or out of date. The framework will:');
       UI.list([
         'Refuse to overwrite any file/dir you customised (you\'ll be asked first).',
         'Convert legacy .claude/skills/ bulk symlink (v2.0.x) into the new per-item layout.',
-        'Merge framework skills into .claude/skills/ without touching your personal skills.'
+        `Merge framework skills into per-tool skill dirs (${enabledTools.join(', ')}) without touching your personal skills.`
       ]);
       const recreate = await UI.confirm('Reconcile symlinks now?', true);
       if (recreate) {
-        // Use 'prompt' mode so any customised file (non-symlink) gets a
-        // confirmation prompt before being moved to .backup.
-        await symlinks.createAllSymlinks({ mode: 'prompt' });
+        await symlinks.createAllSymlinks({ mode: 'prompt', tools: enabledTools });
       }
     } else {
-      // Even when bulk symlinks are valid, re-run the per-item skill merge
-      // to pick up new framework skills shipped in this version.
-      symlinks.mergeSkills();
+      // Re-run the per-item skill merge for every enabled tool so newly-shipped
+      // skills are linked in each tool's expected directory.
+      symlinks.mergeSkills({ tools: enabledTools });
     }
 
     // Routines wizard (since v2.1.0) — surfaces routines added in the new framework version

package/src/utils/symlinks.js

@@ -160,93 +160,135 @@ class SymlinkUtils {
   // -----------------------------------------------------------------------
 
   /**
-   * Merge framework skills into the user's .claude/skills/ directory
-   * without ever touching user-authored skills.
+   * Merge framework skills into the user's per-tool skill directories
+   * (.claude/skills/, .agents/skills/, …) without ever touching user-
+   * authored skills. The SAME source file under
+   * `.framework/framework/.claude/skills/<skill>/` is symlinked into each
+   * enabled tool's expected directory — zero duplication, both Claude and
+   * Codex read the same content.
    *
-   * Returns { linked: [...], skipped: [...], conflicts: [...] }
+   * @param {Object} opts
+   * @param {string[]} opts.tools - List of enabled tool names (default: ['claude'])
+   * @returns {Object} { linked: [...], skipped: [...], conflicts: [...] }
    */
-  mergeSkills() {
-    const result = { linked: [], skipped: [], conflicts: [] };
+  mergeSkills(opts = {}) {
+    const tools = (opts.tools && opts.tools.length) ? opts.tools : ['claude'];
+    const aggregate = { linked: [], skipped: [], conflicts: [] };
 
-    const frameworkSkillsDir = path.join(this.cwd, FRAMEWORK_DIR, 'framework', '.claude', 'skills');
+    const frameworkSkillsDir = path.join(this.cwd, FRAMEWORK_PAYLOAD, '.claude', 'skills');
     if (!fs.existsSync(frameworkSkillsDir)) {
       UI.warning(`No framework skills found at ${path.relative(this.cwd, frameworkSkillsDir)}. Skipping skill merge.`);
-      return result;
+      return aggregate;
+    }
+
+    const frameworkSkills = fs.readdirSync(frameworkSkillsDir).filter(name => {
+      if (name.startsWith('.')) return false;
+      const full = path.join(frameworkSkillsDir, name);
+      return fs.lstatSync(full).isDirectory();
+    });
+
+    for (const tool of tools) {
+      const result = this._mergeSkillsForTool(tool, frameworkSkills, frameworkSkillsDir);
+      aggregate.linked.push(...result.linked);
+      aggregate.skipped.push(...result.skipped);
+      aggregate.conflicts.push(...result.conflicts);
+    }
+
+    if (aggregate.conflicts.length > 0) {
+      this.ensureDirectory('.baldart');
+      const conflictPath = path.join(this.cwd, CONFLICT_LOG);
+      let existing = { conflicts: [] };
+      if (fs.existsSync(conflictPath)) {
+        try { existing = JSON.parse(fs.readFileSync(conflictPath, 'utf8')); }
+        catch (_) { /* ignore parse errors, overwrite */ }
+      }
+      existing.conflicts = aggregate.conflicts;
+      existing.last_merge = new Date().toISOString();
+      fs.writeFileSync(conflictPath, JSON.stringify(existing, null, 2) + '\n');
+      UI.warning(`Recorded ${aggregate.conflicts.length} skill conflict(s) in ${CONFLICT_LOG}`);
+      UI.info('Resolve each by renaming your local skill OR confirming the framework version is the one you want, then re-run `npx baldart update`.');
     }
 
-    const userSkillsDir = path.join(this.cwd, '.claude', 'skills');
+    return aggregate;
+  }
 
-    // Handle the v2.0.x legacy case: .claude/skills is a single symlink to
-    // .framework/.../skills. Convert it back to a real directory so we can
-    // host per-item symlinks alongside user skills.
+  /**
+   * Per-tool skill merge — internal. Resolves the tool's target directory
+   * via the adapter, handles legacy bulk-symlink conversion, then per-item
+   * symlinks every framework skill into that directory.
+   */
+  _mergeSkillsForTool(toolName, frameworkSkills, frameworkSkillsDir) {
+    const { getAdapter } = require('./tool-adapters');
+    const adapter = getAdapter(toolName, this.cwd);
+    const result = { linked: [], skipped: [], conflicts: [] };
+
+    const skillsRel = adapter.skillsDir(); // e.g. ".claude/skills" or ".agents/skills"
+    const userSkillsDir = path.join(this.cwd, skillsRel);
+
+    // Legacy: if the user's skills dir is itself a bulk symlink, convert
+    // back to a real directory so per-item symlinks can coexist with user skills.
     if (fs.existsSync(userSkillsDir) && fs.lstatSync(userSkillsDir).isSymbolicLink()) {
-      UI.warning('Detected legacy v2.0.x bulk skills symlink. Converting to per-item layout…');
+      UI.warning(`[${adapter.label}] Detected legacy bulk skills symlink at ${skillsRel}. Converting to per-item layout…`);
       fs.unlinkSync(userSkillsDir);
     }
 
-    this.ensureDirectory('.claude/skills');
+    this.ensureDirectory(skillsRel);
 
-    const frameworkSkills = fs.readdirSync(frameworkSkillsDir).filter(name => {
-      // Skip hidden files (.DS_Store, etc.) and any non-skill entries
-      if (name.startsWith('.')) return false;
-      const full = path.join(frameworkSkillsDir, name);
-      return fs.lstatSync(full).isDirectory();
-    });
+    // Compute the relative path from the user's skills dir to the framework
+    // source. For ".claude/skills" or ".agents/skills" both are 2 levels deep,
+    // so the prefix is "../.." — but compute it generically to support adapters
+    // that pick different depths.
+    const skillsDirDepth = skillsRel.split(path.sep).filter(Boolean).length;
+    const upPath = path.join(...Array(skillsDirDepth).fill('..'));
 
     frameworkSkills.forEach(name => {
       const linkPath = path.join(userSkillsDir, name);
-      const target = path.join('..', '..', FRAMEWORK_DIR, 'framework', '.claude', 'skills', name);
-      const targetAbsolute = path.join(this.cwd, FRAMEWORK_DIR, 'framework', '.claude', 'skills', name);
+      const target = path.join(upPath, FRAMEWORK_PAYLOAD, '.claude', 'skills', name);
+      const targetAbsolute = path.join(this.cwd, FRAMEWORK_PAYLOAD, '.claude', 'skills', name);
+
+      // Use lstat to detect broken symlinks (fs.existsSync follows links and
+      // misclassifies broken ones as "missing", causing EEXIST on symlinkSync).
+      let lstat = null;
+      try { lstat = fs.lstatSync(linkPath); } catch (_) { /* absent */ }
 
-      if (!fs.existsSync(linkPath)) {
+      if (!lstat) {
         fs.symlinkSync(target, linkPath);
-        UI.success(`Skill linked: .claude/skills/${name}`);
-        result.linked.push(name);
+        UI.success(`[${adapter.label}] Skill linked: ${path.join(skillsRel, name)}`);
+        result.linked.push({ tool: toolName, name });
         return;
       }
 
-      const stat = fs.lstatSync(linkPath);
-      if (stat.isSymbolicLink()) {
+      if (lstat.isSymbolicLink()) {
         const current = fs.readlinkSync(linkPath);
-        if (current === target || path.resolve(path.dirname(linkPath), current) === targetAbsolute) {
-          // Already linked correctly — silent OK
-          result.skipped.push({ name, reason: 'already-linked' });
+        const resolved = path.resolve(path.dirname(linkPath), current);
+        if (current === target || resolved === targetAbsolute) {
+          result.skipped.push({ tool: toolName, name, reason: 'already-linked' });
+          return;
+        }
+        // Broken-or-misaimed symlink → replace silently with the correct one
+        if (!fs.existsSync(linkPath)) {
+          fs.unlinkSync(linkPath);
+          fs.symlinkSync(target, linkPath);
+          UI.success(`[${adapter.label}] Skill re-linked (was broken): ${path.join(skillsRel, name)}`);
+          result.linked.push({ tool: toolName, name });
           return;
         }
-        // Symlink pointing elsewhere — user override, leave alone
-        UI.info(`Skill kept (user override symlink): .claude/skills/${name} → ${current}`);
-        result.skipped.push({ name, reason: 'user-symlink-override', target: current });
+        UI.info(`[${adapter.label}] Skill kept (user override symlink): ${path.join(skillsRel, name)} → ${current}`);
+        result.skipped.push({ tool: toolName, name, reason: 'user-symlink-override', target: current });
         return;
       }
 
-      // Real file or directory under same name — NAME COLLISION
-      UI.warning(`Skill name conflict: .claude/skills/${name} already exists locally. Framework version NOT installed.`);
+      UI.warning(`[${adapter.label}] Skill name conflict: ${path.join(skillsRel, name)} already exists locally. Framework version NOT installed.`);
       result.conflicts.push({
+        tool: toolName,
         name,
-        local_kind: stat.isDirectory() ? 'directory' : 'file',
-        local_path: path.join('.claude', 'skills', name),
+        local_kind: lstat.isDirectory() ? 'directory' : 'file',
+        local_path: path.join(skillsRel, name),
         framework_path: path.relative(this.cwd, path.join(frameworkSkillsDir, name)),
         detected_at: new Date().toISOString()
       });
     });
 
-    // Persist conflicts (only when there's something to record)
-    if (result.conflicts.length > 0) {
-      this.ensureDirectory('.baldart');
-      const conflictPath = path.join(this.cwd, CONFLICT_LOG);
-      let existing = { conflicts: [] };
-      if (fs.existsSync(conflictPath)) {
-        try { existing = JSON.parse(fs.readFileSync(conflictPath, 'utf8')); }
-        catch (_) { /* ignore parse errors, overwrite */ }
-      }
-      // Replace conflicts for this run (most recent wins)
-      existing.conflicts = result.conflicts;
-      existing.last_merge = new Date().toISOString();
-      fs.writeFileSync(conflictPath, JSON.stringify(existing, null, 2) + '\n');
-      UI.warning(`Recorded ${result.conflicts.length} skill conflict(s) in ${CONFLICT_LOG}`);
-      UI.info('Resolve each by renaming your local skill OR confirming the framework version is the one you want, then re-run `npx baldart update`.');
-    }
-
     return result;
   }
 
@@ -260,7 +302,7 @@ class SymlinkUtils {
 
     UI.newline();
     UI.section('Merging Framework Skills');
-    this.mergeSkills();
+    this.mergeSkills({ tools: opts.tools });
 
     UI.newline();
   }
@@ -298,31 +340,51 @@ class SymlinkUtils {
       }
     });
 
-    // .claude/skills/ should be a real directory in v2.1.1+ (or absent).
-    const skillsDir = path.join(this.cwd, '.claude', 'skills');
-    if (fs.existsSync(skillsDir)) {
-      const stat = fs.lstatSync(skillsDir);
-      if (stat.isSymbolicLink()) {
-        UI.warning('Legacy v2.0.x layout: .claude/skills is a bulk symlink. Run `npx baldart update` (or `npx baldart migrate`) to convert to the per-item layout.');
-        allValid = false;
-      } else {
-        // Spot-check a couple of well-known framework skills
-        const sample = ['skill-creator', 'frontend-design', 'bug', 'prd', 'capture'];
-        let frameworkLinks = 0;
-        sample.forEach(name => {
-          const p = path.join(skillsDir, name);
-          if (fs.existsSync(p) && fs.lstatSync(p).isSymbolicLink()) frameworkLinks++;
-        });
-        if (frameworkLinks === 0) {
-          UI.warning('.claude/skills/ has no framework-linked skills. Run `npx baldart update` to merge them.');
+    // Per-tool skill directories. Read enabled tools from baldart.config.yml
+    // (fallback to ['claude'] if no config yet).
+    const { getAdapter } = require('./tool-adapters');
+    let enabledTools = ['claude'];
+    try {
+      const yaml = require('js-yaml');
+      const cfgPath = path.join(this.cwd, 'baldart.config.yml');
+      if (fs.existsSync(cfgPath)) {
+        const cfg = yaml.load(fs.readFileSync(cfgPath, 'utf8'));
+        if (Array.isArray(cfg?.tools?.enabled) && cfg.tools.enabled.length) {
+          enabledTools = cfg.tools.enabled;
+        }
+      }
+    } catch (_) { /* keep default */ }
+
+    for (const toolName of enabledTools) {
+      let adapter;
+      try { adapter = getAdapter(toolName, this.cwd); }
+      catch (err) { UI.warning(err.message); allValid = false; continue; }
+
+      const skillsRel = adapter.skillsDir();
+      const skillsDir = path.join(this.cwd, skillsRel);
+      if (fs.existsSync(skillsDir)) {
+        const stat = fs.lstatSync(skillsDir);
+        if (stat.isSymbolicLink()) {
+          UI.warning(`[${adapter.label}] Legacy bulk skills symlink at ${skillsRel}. Run \`npx baldart update\` to convert to per-item.`);
           allValid = false;
         } else {
-          UI.success(`Valid: .claude/skills/ (per-item merge, ${frameworkLinks}/${sample.length} sampled framework skills linked)`);
+          const sample = ['skill-creator', 'frontend-design', 'bug', 'prd', 'capture'];
+          let frameworkLinks = 0;
+          sample.forEach(name => {
+            const p = path.join(skillsDir, name);
+            if (fs.existsSync(p) && fs.lstatSync(p).isSymbolicLink()) frameworkLinks++;
+          });
+          if (frameworkLinks === 0) {
+            UI.warning(`[${adapter.label}] ${skillsRel}/ has no framework-linked skills. Run \`npx baldart update\`.`);
+            allValid = false;
+          } else {
+            UI.success(`[${adapter.label}] Valid: ${skillsRel}/ (per-item merge, ${frameworkLinks}/${sample.length} sampled framework skills linked)`);
+          }
         }
+      } else {
+        UI.warning(`[${adapter.label}] Missing: ${skillsRel}/ (the framework would merge skills here)`);
+        allValid = false;
       }
-    } else {
-      UI.warning('Missing: .claude/skills/ (the framework would merge skills here)');
-      allValid = false;
     }
 
     // Project configuration (v3.0.0+)

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

@@ -0,0 +1,41 @@
+/**
+ * Claude Code tool adapter.
+ *
+ * Claude Code consumes the framework via:
+ *   - `.claude/skills/<skill>/SKILL.md`           (skills, per-item symlinks)
+ *   - `.claude/agents/<agent>.md`                 (subagents, bulk symlink)
+ *   - `.claude/commands/<command>.md`             (slash commands, bulk symlink)
+ *   - `.claude/settings.json`                     (hooks, ide config)
+ *   - `AGENTS.md`                                 (root coordination protocol)
+ *
+ * All paths are relative to the consumer repo root.
+ */
+class ClaudeAdapter {
+  constructor(cwd = process.cwd()) {
+    this.cwd = cwd;
+  }
+
+  get name() { return 'claude'; }
+  get label() { return 'Claude Code'; }
+
+  /** Where this tool reads skill bundles from. */
+  skillsDir() { return '.claude/skills'; }
+
+  /** Whether this tool consumes subagent definitions (`.claude/agents/`). */
+  supportsSubagents() { return true; }
+
+  /** Whether this tool consumes Claude-style slash commands. */
+  supportsSlashCommands() { return true; }
+
+  /** Whether this tool consumes the Claude PreToolUse hook system. */
+  supportsHooks() { return true; }
+
+  /**
+   * Autodetection signal. We assume Claude is always intended (it's the
+   * framework's primary target). The opt-out is via `tools.enabled` in
+   * baldart.config.yml.
+   */
+  static detect(/* cwd */) { return true; }
+}
+
+module.exports = ClaudeAdapter;

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

@@ -0,0 +1,51 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/**
+ * OpenAI Codex CLI tool adapter.
+ *
+ * Codex skill format is structurally identical to Claude's: a directory
+ * with `SKILL.md` (YAML frontmatter: name + description), plus optional
+ * `scripts/`, `references/`, `assets/`. The ONLY differences from Claude:
+ *   - Lives at `.agents/skills/<skill>/` (repo-level) or
+ *     `~/.agents/skills/<skill>/` (user-level).
+ *   - May carry an optional `agents/openai.yaml` for Codex-specific
+ *     metadata (display name, icon, brand color, allow_implicit_invocation,
+ *     dependencies). Not required for the skill to load.
+ *
+ * Because the format is the same, the install model is "symlink the same
+ * source dir into two places" — Claude reads from `.claude/skills/<x>`,
+ * 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.
+ */
+class CodexAdapter {
+  constructor(cwd = process.cwd()) {
+    this.cwd = cwd;
+  }
+
+  get name() { return 'codex'; }
+  get label() { return 'OpenAI Codex CLI'; }
+
+  skillsDir() { return '.agents/skills'; }
+
+  supportsSubagents() { return false; }
+  supportsSlashCommands() { return false; }
+  supportsHooks() { return false; }
+
+  /**
+   * Heuristic: Codex is present on the user's machine if `~/.codex/` exists
+   * (created automatically by `codex` CLI on first run). Pure best-effort
+   * for the `configure` autodetect — the user can always toggle the flag.
+   */
+  static detect() {
+    try { return fs.existsSync(path.join(os.homedir(), '.codex')); }
+    catch { return false; }
+  }
+}
+
+module.exports = CodexAdapter;

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

@@ -0,0 +1,44 @@
+const ClaudeAdapter = require('./claude');
+const CodexAdapter = require('./codex');
+
+/**
+ * Tool adapter registry.
+ *
+ * Adding a new adapter (Cursor, Aider, Cline, …):
+ *   1. Create `src/utils/tool-adapters/<name>.js` exporting a class with
+ *      the same shape as ClaudeAdapter/CodexAdapter.
+ *   2. Add it to the REGISTRY below.
+ *   3. (Optional) Implement `static detect(cwd)` so `baldart configure`
+ *      can autodetect when the user already has the tool installed.
+ *
+ * Adapters do NOT translate skill content — they just declare WHERE the
+ * tool reads from. The same source file under `.framework/framework/.claude/skills/`
+ * is symlinked into each enabled tool's expected directory.
+ */
+const REGISTRY = {
+  claude: ClaudeAdapter,
+  codex:  CodexAdapter
+};
+
+function listAdapters() {
+  return Object.keys(REGISTRY);
+}
+
+function getAdapter(name, cwd) {
+  const Cls = REGISTRY[name];
+  if (!Cls) throw new Error(`Unknown tool adapter: ${name}. Available: ${listAdapters().join(', ')}`);
+  return new Cls(cwd);
+}
+
+/**
+ * Returns the list of tool names that should be enabled by default for
+ * a fresh install. Always includes `claude` (the framework's primary
+ * target). Includes `codex` if the user appears to have it installed.
+ */
+function defaultEnabled(cwd) {
+  const enabled = ['claude'];
+  if (CodexAdapter.detect(cwd)) enabled.push('codex');
+  return enabled;
+}
+
+module.exports = { REGISTRY, listAdapters, getAdapter, defaultEnabled };