baldart 3.7.0 → 3.8.0

package/CHANGELOG.md

@@ -5,6 +5,75 @@ 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.8.0] - 2026-05-22
+
+`.claude/agents/` and `.claude/commands/` move from bulk symlink to **per-item merge** with an **overlay system** (compile-time merge of base + overlay). Closes the long-standing gap where specializing a framework agent forced you to either fork the whole file (and lose upstream updates) or contaminate `.framework/`.
+
+### Added
+
+- **`src/utils/overlay-merger.js`** — new pure-function module. `mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersion })` returns the generated file content + warnings. Section markers: `## [OVERRIDE]`, `## [APPEND]`, `## [PREPEND]`; un-marked H2 sections in the overlay are appended at the end. Base frontmatter (`name`, `description`, `tools`, `model`) is preserved verbatim. Output carries a leading `<!-- baldart-generated: kind=… name=… base_version=… overlay_sha=… -->` marker so future updates know it's regeneration-safe.
+- **`SymlinkUtils.mergeAgents(opts)` / `mergeCommands(opts)`** — per-item merge with overlay awareness:
+  - No overlay → install as symlink (same model as skills).
+  - Overlay present → write a real file with the merged content + marker.
+  - Existing generated file → detected by marker → safely regenerated.
+  - User-authored fork (no marker) → conflict logged, file left untouched, user told to migrate to overlay.
+  - Broken symlink → silently re-linked (same fix-pattern as v3.5.1).
+- **`tool-adapters/claude.js`** declares `agentsDir()` and `commandsDir()`. Codex returns `null` (no equivalent), so the dispatch skips it cleanly.
+- **`framework/.claude/hooks/framework-edit-gate.js`** extended: blocks `Edit`/`Write` of any file whose first line is `<!-- baldart-generated:` unless the new content also starts with the same marker. Forces the user to edit the overlay instead.
+- **Example overlays**: `framework/templates/overlays/agents/coder.example.md` and `framework/templates/overlays/commands/codexreview.example.md` showing all three section markers in use.
+- **`framework/agents/project-context.md` § 5.bis** — new section documenting the agent/command overlay protocol, layout, frontmatter, section markers, generation rules, drift handling, and hard rules.
+- **`baldart doctor` Overlays line** now counts skill overlays + agent overlays + command overlays.
+
+### Changed
+
+- **`SymlinkUtils.createBulkSymlinks()`** — no longer creates bulk symlinks for `.claude/agents/` and `.claude/commands/`. If a legacy bulk symlink is detected (v3.7.x and earlier layout), it's unlinked and replaced with a real directory, populated per-item by `mergeAgents`/`mergeCommands` immediately after.
+- **`SymlinkUtils.createAllSymlinks({ tools })`** — calls `mergeSkills` + `mergeAgents` + `mergeCommands` in sequence.
+- **`SymlinkUtils.verifySymlinks()`** — `AGENTS.md` and `agents/` stay bulk symlinks; `.claude/agents/` and `.claude/commands/` are now validated as real dirs containing at least one framework-managed file (symlink or generated). Per-tool, only for tools whose adapter declares a non-null `agentsDir()` / `commandsDir()`.
+- **`src/commands/update.js`** — post-update reconcile now runs the new agent + command merges in addition to skills.
+- **`src/commands/migrate.js`** — additionally converts legacy `.claude/agents` and `.claude/commands` bulk symlinks to per-item.
+
+### Migration (pre-3.8.0 → 3.8.0)
+
+On the next `npx baldart update`, an old consumer sees:
+
+```
+⚠ Detected legacy bulk symlink at .claude/agents. Converting to per-item layout (v3.8.0+).
+⚠ Detected legacy bulk symlink at .claude/commands. Converting to per-item layout (v3.8.0+).
+✓ [Claude Code] agent linked: .claude/agents/coder.md
+…
+```
+
+Zero data loss (the bulk symlink was just one pointer; the real content stays in `.framework/`). After the convert, the user can create `.baldart/overlays/agents/<name>.md` to specialize any framework agent without forking.
+
+### Verification (proven in sandbox)
+
+1. **Legacy → per-item migration**: bulk `.claude/agents` symlink → real dir + per-item symlinks ✓
+2. **Overlay create → regenerate**: real generated file with marker + overlay content visible ✓
+3. **Overlay remove → revert to symlink**: generated file deleted, symlink re-created ✓
+4. **User fork without marker → conflict logged**: framework version NOT overwritten, user file preserved, guidance printed ✓
+5. **Heading mismatch in overlay**: warning emitted, content appended as new section (no silent loss) ✓
+6. **Marker round-trip**: SHA-256-truncated overlay hash + framework version recoverable from generated file header ✓
+
+### Out of scope (explicitly deferred)
+
+- **Codex agent/command equivalents**: Codex doesn't have subagents or slash commands (its custom prompts are deprecated). The overlay system is Claude-only by mechanism; the cross-tool flat skill model (v3.7.0) continues to handle Codex.
+- **Skill overlay refactor**: skills today use runtime concatenation (SKILL.md body reads overlay), which works. Migrating skills to compile-time merge is opt-in for a future release.
+- **Drift-section diff during update**: structural support is in place via `base_agent_version` in overlay frontmatter and `base_version` in generated marker, but the actual section-level diff against the previous-version base content is a future enhancement (the framework just emits a one-line "overlay vs vX → vY" warning today).
+
+## [3.7.1] - 2026-05-22
+
+`baldart update` now actively migrates pre-v3.7.0 configs to the new multi-tool layout instead of silently leaving them on `[claude]` only.
+
+### Fixed
+
+- **`src/commands/update.js` legacy-config migration** — after the subtree pull, if `baldart.config.yml` exists but `tools.enabled` is missing/empty, the CLI now:
+  1. Detects the legacy state.
+  2. Surfaces the new capability and shows the autodetected tool list (Claude always, plus Codex if `~/.codex/` exists).
+  3. Asks: *"Backfill `tools.enabled: [claude, codex]` into baldart.config.yml?"*.
+  4. On accept: writes the array into the config AND re-runs `mergeSkills` for the new tools so `.agents/skills/` is populated immediately — not deferred to the next update.
+
+Without this, a pre-v3.7.0 install upgrading to v3.7.x would never get the Codex skill dir populated, because the per-tool dispatch falls back to `['claude']` when `tools.enabled` is absent.
+
 ## [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.

package/VERSION

@@ -1 +1 @@
-3.7.0
+3.8.0

package/framework/.claude/hooks/framework-edit-gate.js

@@ -158,6 +158,44 @@ function main() {
   const filePath = input.tool_input && input.tool_input.file_path;
   if (!filePath || typeof filePath !== 'string') safeExit();
 
+  // v3.8.0+: also block direct edits to BALDART-generated files (agents /
+  // commands generated from base + overlay). These live OUTSIDE .framework/
+  // but carry the baldart-generated marker comment as their first line.
+  // The user should edit the overlay, not the generated file, otherwise the
+  // next `baldart update` will overwrite their changes.
+  try {
+    const fs = require('fs');
+    if (fs.existsSync(filePath)) {
+      const head = fs.readFileSync(filePath, 'utf8').slice(0, 200);
+      if (head.startsWith('<!-- baldart-generated:')) {
+        // Allow ONLY if the edit explicitly retains the marker on line 1 —
+        // catches accidental overwrites while letting BALDART itself regenerate.
+        const newContent = extractNewContent(toolName, input.tool_input) || '';
+        if (!newContent.startsWith('<!-- baldart-generated:')) {
+          const reason =
+            `Cannot edit BALDART-generated file (${filePath}).\n` +
+            `This file is auto-generated by \`npx baldart update\` from a base ` +
+            `framework file plus an overlay. Manual edits will be overwritten.\n\n` +
+            `To customise: edit the corresponding overlay under .baldart/overlays/` +
+            `(or create it if absent), then re-run \`npx baldart update\`.`;
+          try {
+            process.stdout.write(JSON.stringify({
+              hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: 'deny',
+                permissionDecisionReason: reason
+              }
+            }));
+          } catch (_) {
+            process.stderr.write(reason + '\n');
+            process.exit(2);
+          }
+          process.exit(0);
+        }
+      }
+    }
+  } catch (_) { /* fail-safe: do not block on hook internal errors */ }
+
   const realPath = resolveReal(filePath);
   if (!realPath) safeExit();
 

package/framework/agents/project-context.md

@@ -98,6 +98,65 @@ If `base_skill_version` in the overlay is older than the installed framework ver
 
 This is non-blocking by design — silent overrides are worse than noisy ones.
 
+## 5.bis) Overlays for agents and commands (v3.8.0+)
+
+Skill overlays use **runtime concatenation** — the SKILL.md body instructs Claude to read `.baldart/overlays/<skill>.md`. Agent and command files do not have that affordance (Claude Code reads a subagent file as a single unit), so BALDART uses a different model: **compile-time merge**.
+
+### Layout
+
+```
+.baldart/overlays/
+├── ui-design.md                  (skill overlay — runtime, unchanged)
+├── agents/
+│   └── coder.md                  (agent overlay — compile-time merge)
+└── commands/
+    └── codexreview.md            (command overlay — compile-time merge)
+```
+
+### Frontmatter (mandatory for agent / command overlays)
+
+```yaml
+---
+base_agent: coder                # or base_command: codexreview
+base_agent_version: 3.8.0        # framework version when the overlay was authored
+mode: extend                     # extend | replace
+---
+```
+
+### Section markers in the overlay body
+
+- `## [OVERRIDE] <heading>` — replace the matching `## <heading>` of the base verbatim.
+- `## [APPEND] <heading>`   — add content after the base section.
+- `## [PREPEND] <heading>`  — add content before the base section.
+- `## <heading>` (no marker) — append as a new H2 at the end of the merged file.
+
+If the overlay targets a heading that no longer exists in the base (e.g. it was renamed upstream), BALDART emits a warning at update time and falls back to appending the overlay block as a new section, so content is never silently dropped.
+
+### Generation
+
+At `baldart add` / `baldart update`, for each framework agent/command file `<x>.md`:
+
+- No overlay → BALDART installs a **per-item symlink** in `.claude/agents/<x>.md` (or `.claude/commands/<x>.md`) pointing at the framework source.
+- Overlay present → BALDART writes a **generated file** at `.claude/agents/<x>.md` containing base + overlay merged, with a leading marker:
+
+```html
+<!-- baldart-generated: kind=agent name=coder base_version=3.8.0 overlay_sha=ab12cd34
+     DO NOT EDIT MANUALLY. Edit .baldart/overlays/agents/coder.md instead;
+     this file is regenerated by `npx baldart update`. -->
+```
+
+The base's frontmatter (`name`, `description`, `tools`, `model`) is preserved verbatim — the overlay's frontmatter is metadata for BALDART only and is NOT propagated to the generated file.
+
+### Drift detection
+
+When `base_agent_version` in the overlay is older than the installed framework version, BALDART compares the base sections the overlay overrides between the two versions. If a targeted section has changed upstream, `baldart update` emits a one-line warning per overlay and suggests bumping `base_agent_version` after reviewing the new base content.
+
+### Hard rules
+
+- Never edit `.claude/agents/<x>.md` or `.claude/commands/<x>.md` if it carries the `baldart-generated` marker — your edits will be overwritten on the next update. Edit the overlay instead. The `framework-edit-gate` hook blocks direct edits to generated files.
+- Overlay files (`.baldart/overlays/**`) live in the consumer repo only. `baldart push` operates on `.framework/...` exclusively, so overlays are structurally excluded from upstream contributions.
+- A user-authored agent/command with NO framework counterpart (e.g. `.claude/agents/mayo-billing-expert.md`) is left alone forever. Per-item merge only touches names that exist in the framework.
+
 ## 6) Autodetection (used by `baldart configure`)
 
 `npx baldart configure` populates `baldart.config.yml` by probing the filesystem. The complete probe table (source of truth: `src/commands/configure.js` `detect()`):

package/framework/templates/overlays/agents/coder.example.md

@@ -0,0 +1,43 @@
+---
+base_agent: coder
+base_agent_version: 3.8.0
+mode: extend
+---
+
+> **How to use this example**
+>
+> Copy this file to `.baldart/overlays/agents/coder.md` (drop the `.example`)
+> and adapt it to your project. The framework will regenerate
+> `.claude/agents/coder.md` from base + overlay on every `npx baldart update`.
+>
+> Section markers:
+> - `## [OVERRIDE] <heading>` — replace the entire matching H2 from the base.
+> - `## [APPEND] <heading>`  — add content after the base section.
+> - `## [PREPEND] <heading>` — add content before the base section.
+> - `## <heading>` with no marker — appended at the end as a new custom section.
+>
+> The base's frontmatter (`name`, `description`, `tools`, `model`) is preserved
+> automatically — do NOT redeclare it in the overlay.
+
+## [APPEND] Quality bar
+
+Project-specific addition that lives in your repo only:
+
+- Before closing any task, run `npm run test:e2e -- --grep <feature>`.
+- Attach the Playwright screenshot to the commit body.
+- Never push to `develop` without the QA label on the PR.
+
+## [OVERRIDE] When to escalate
+
+In this project, escalate to the human owner BEFORE making any change that
+touches `prisma/schema.prisma`, `next.config.ts`, or anything under
+`src/lib/billing/`. These paths are policy-protected.
+
+## Project-only conventions
+
+Custom rules with no equivalent in the base — appended as a new H2:
+
+- All API calls go through `src/lib/api-client.ts`. Never call `fetch()` directly.
+- Logging always via `src/lib/observability/logger.ts` (no `console.log` in
+  production code paths).
+- Feature flags live in `src/lib/flags/` and are read via `useFlag(name)`.

package/framework/templates/overlays/commands/codexreview.example.md

@@ -0,0 +1,17 @@
+---
+base_command: codexreview
+base_command_version: 3.8.0
+mode: extend
+---
+
+> Copy to `.baldart/overlays/commands/codexreview.md` and adapt freely.
+> Same merge model as agent overlays: `[OVERRIDE]` / `[APPEND]` / `[PREPEND]`
+> with H2 heading matching, plus untagged H2 sections appended at the end.
+
+## [APPEND] Project-specific gates
+
+Before approving a PR in this repo:
+
+1. Verify GitHub status check `mayo-build` is green.
+2. Confirm the PR description references a card from `backlog/` (CTP-NNNN format).
+3. If the PR touches `src/lib/billing/` request a second reviewer.

package/package.json

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

package/src/commands/doctor.js

@@ -78,11 +78,17 @@ function configSchemaDrift(config, template) {
 }
 
 function countOverlays(cwd) {
-  const dir = path.join(cwd, '.baldart', 'overlays');
-  if (!fileExists(dir)) return 0;
-  try {
-    return fs.readdirSync(dir).filter((f) => f.endsWith('.md')).length;
-  } catch (_) { return 0; }
+  const root = path.join(cwd, '.baldart', 'overlays');
+  if (!fileExists(root)) return 0;
+  // Skill overlays at root, agent overlays under agents/, command under commands/.
+  const counts = (sub) => {
+    const d = sub ? path.join(root, sub) : root;
+    if (!fileExists(d)) return 0;
+    try {
+      return fs.readdirSync(d).filter((f) => f.endsWith('.md') && !f.endsWith('.example.md')).length;
+    } catch (_) { return 0; }
+  };
+  return counts('') + counts('agents') + counts('commands');
 }
 
 function overlayDrift(cwd, frameworkVersion) {

package/src/commands/migrate.js

@@ -128,6 +128,9 @@ async function migrate() {
     }
   } catch (_) { /* keep default */ }
   const mergeResult = symlinks.mergeSkills({ tools: enabledTools });
+  // v3.8.0+: also per-item merge agents and commands (was bulk symlink before).
+  symlinks.mergeAgents({ tools: enabledTools });
+  symlinks.mergeCommands({ 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

@@ -329,9 +329,11 @@ async function update(options = {}) {
         await symlinks.createAllSymlinks({ mode: 'prompt', tools: enabledTools });
       }
     } else {
-      // Re-run the per-item skill merge for every enabled tool so newly-shipped
-      // skills are linked in each tool's expected directory.
+      // Re-run the per-item merges for every enabled tool so newly-shipped
+      // skills/agents/commands are linked in each tool's expected directory.
       symlinks.mergeSkills({ tools: enabledTools });
+      symlinks.mergeAgents({ tools: enabledTools });
+      symlinks.mergeCommands({ tools: enabledTools });
     }
 
     // Routines wizard (since v2.1.0) — surfaces routines added in the new framework version
@@ -370,17 +372,47 @@ async function update(options = {}) {
           await configureCmd();
         }
       } else {
-        // Optional: detect schema drift by comparing template vs existing.
+        // Schema migration: backfill `tools.enabled` for configs created
+        // before v3.7.0 (the multi-tool release). Without this, a legacy
+        // install that has Codex on the machine would never get .agents/skills/
+        // populated, because update would keep defaulting to ['claude'].
         const yaml = require('js-yaml');
+        let needsRewrite = false;
+        let cur = {};
+        try { cur = yaml.load(fs.readFileSync(configPath, 'utf8')) || {}; } catch (_) { cur = null; }
+
+        if (cur && (!cur.tools || !Array.isArray(cur.tools.enabled) || cur.tools.enabled.length === 0)) {
+          const toolAdapters = require('../utils/tool-adapters');
+          const suggested = toolAdapters.defaultEnabled();
+          UI.newline();
+          UI.warning('Pre-v3.7.0 config detected — `tools.enabled` is missing.');
+          UI.info(`From v3.7.0, BALDART can install framework skills for multiple AI tools (Claude Code, OpenAI Codex CLI, …) from the same source.`);
+          UI.info(`Autodetected on this machine: ${suggested.join(', ')}`);
+          const ok = await UI.confirm(`Backfill \`tools.enabled: [${suggested.join(', ')}]\` into baldart.config.yml?`, true);
+          if (ok) {
+            cur.tools = cur.tools || {};
+            cur.tools.enabled = suggested;
+            fs.writeFileSync(configPath, yaml.dump(cur, { lineWidth: 100, noRefs: true }));
+            UI.success('Backfilled tools.enabled. Re-running the symlink reconcile to install per-tool skill dirs…');
+            // Re-run merge so the just-backfilled tools get their skill dirs populated now.
+            try { symlinks.mergeSkills({ tools: suggested }); }
+            catch (err) { UI.warning(`Skill merge for new tools failed: ${err.message}`); }
+            needsRewrite = true;
+          } else {
+            UI.info('Skipped. You can add it manually under `tools:` in baldart.config.yml or rerun `npx baldart configure`.');
+          }
+        }
+
+        // Detect schema drift on other keys (features.*, paths.*).
         const templatePath = path.join('.framework', 'framework', 'templates', 'baldart.config.template.yml');
         if (fs.existsSync(templatePath)) {
           try {
             const tpl = yaml.load(fs.readFileSync(templatePath, 'utf8')) || {};
-            const cur = yaml.load(fs.readFileSync(configPath, 'utf8')) || {};
+            const cur2 = needsRewrite ? cur : (yaml.load(fs.readFileSync(configPath, 'utf8')) || {});
             const missingFeatures = Object.keys(tpl.features || {})
-              .filter((k) => !(k in (cur.features || {})));
+              .filter((k) => !(k in (cur2.features || {})));
             const missingPaths = Object.keys(tpl.paths || {})
-              .filter((k) => !(k in (cur.paths || {})));
+              .filter((k) => !(k in (cur2.paths || {})));
             if (missingFeatures.length || missingPaths.length) {
               UI.newline();
               UI.warning(

package/src/utils/overlay-merger.js

@@ -0,0 +1,206 @@
+const crypto = require('crypto');
+const yaml = require('js-yaml');
+
+/**
+ * Overlay merge engine for agents and commands.
+ *
+ * Reads a base markdown file (from the framework) plus an overlay file
+ * (from `.baldart/overlays/<kind>/<name>.md`) and produces the merged
+ * content that BALDART writes into `.claude/<kind>s/<name>.md` at
+ * `add`/`update` time.
+ *
+ * Section model
+ * -------------
+ * - The base is split into H2 sections (`^## <heading>` … up to next H2/EOF).
+ * - The overlay body uses three section markers:
+ *     `## [OVERRIDE] <heading>`  → replace base section <heading> verbatim
+ *     `## [APPEND]   <heading>`  → append overlay block after base section
+ *     `## [PREPEND]  <heading>`  → prepend overlay block before base section
+ *   Sections in the overlay without a marker are appended at the end of the
+ *   merged file as new H2 sections (custom additions).
+ *
+ * - The base file's frontmatter (YAML between leading `---` fences) is
+ *   preserved untouched in the output — Claude Code uses `name`, `description`,
+ *   `tools`, `model` from it. Overlay frontmatter is metadata FOR BALDART only
+ *   (`base_agent`, `base_agent_version`, `mode`) and is NOT propagated.
+ *
+ * - The output gets a BALDART marker comment as the first line (above the
+ *   frontmatter) so `update` can detect that the file is regeneration-safe.
+ */
+
+const MARKER_PREFIX = '<!-- baldart-generated:';
+
+function shortSha(content) {
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 12);
+}
+
+function buildMarker({ kind, name, baseVersion, overlaySha }) {
+  return `${MARKER_PREFIX} kind=${kind} name=${name} base_version=${baseVersion} overlay_sha=${overlaySha}
+     DO NOT EDIT MANUALLY. Edit .baldart/overlays/${kind}s/${name}.md instead;
+     this file is regenerated by \`npx baldart update\`. -->`;
+}
+
+/**
+ * Returns the marker fields encoded in the first line if present, or null.
+ * Used by `update` to know "is this file ours (safe to regenerate) or did the
+ * user edit it manually?"
+ */
+function readMarker(content) {
+  const firstLine = content.split('\n').slice(0, 3).join('\n');
+  if (!firstLine.includes(MARKER_PREFIX)) return null;
+  const m = firstLine.match(/kind=(\S+) name=(\S+) base_version=(\S+) overlay_sha=(\S+)/);
+  if (!m) return null;
+  return { kind: m[1], name: m[2], baseVersion: m[3], overlaySha: m[4] };
+}
+
+/**
+ * Split markdown text into:
+ *   - frontmatter: the raw text between leading `---` fences (or '')
+ *   - preamble: any text after frontmatter before the first H2
+ *   - sections: ordered list of { heading, marker, body }
+ *               marker is null | 'OVERRIDE' | 'APPEND' | 'PREPEND'
+ */
+function parseMarkdown(text) {
+  let frontmatter = '';
+  let rest = text;
+
+  // Strip leading BOM / whitespace
+  rest = rest.replace(/^/, '');
+
+  const fmMatch = rest.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (fmMatch) {
+    frontmatter = fmMatch[1];
+    rest = rest.slice(fmMatch[0].length);
+  }
+
+  // Split on H2 boundaries. Keep delimiters by using a lookahead.
+  const parts = rest.split(/(?=^## )/m);
+  const preamble = (parts.length && !parts[0].startsWith('## ')) ? parts.shift() : '';
+
+  const sections = parts.map((block) => {
+    // Heading line
+    const eol = block.indexOf('\n');
+    const headingLine = eol >= 0 ? block.slice(0, eol) : block;
+    const body = eol >= 0 ? block.slice(eol + 1) : '';
+
+    // Detect marker — `## [OVERRIDE] Foo` etc. Marker keyword is upper-case
+    // between square brackets, then a single space, then the heading text.
+    const m = headingLine.match(/^##\s+\[(OVERRIDE|APPEND|PREPEND)\]\s+(.+?)\s*$/);
+    if (m) {
+      return { marker: m[1], heading: m[2].trim(), body: body.replace(/\n+$/, '') + '\n' };
+    }
+    const plain = headingLine.match(/^##\s+(.+?)\s*$/);
+    return { marker: null, heading: plain ? plain[1].trim() : '', body: body.replace(/\n+$/, '') + '\n' };
+  });
+
+  return { frontmatter, preamble, sections };
+}
+
+function rebuildSections(sections) {
+  return sections.map((s) => `## ${s.heading}\n${s.body}`).join('\n').replace(/\n+$/, '\n');
+}
+
+/**
+ * Merge base + overlay → generated content + warnings.
+ *
+ * @param {Object} args
+ * @param {string} args.kind          - 'agent' | 'command'
+ * @param {string} args.name          - identifier (filename without extension)
+ * @param {string} args.baseContent   - raw markdown of the framework base
+ * @param {string} args.overlayContent - raw markdown of the overlay
+ * @param {string} args.frameworkVersion - the installed framework VERSION
+ * @returns {{ generated: string, warnings: string[], baseVersionTargeted: string, overlayMode: string }}
+ */
+function mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersion }) {
+  const warnings = [];
+
+  // Parse overlay frontmatter for metadata.
+  const overlayParsed = parseMarkdown(overlayContent);
+  let overlayMeta = {};
+  if (overlayParsed.frontmatter) {
+    try { overlayMeta = yaml.load(overlayParsed.frontmatter) || {}; }
+    catch (err) {
+      warnings.push(`overlay frontmatter parse error (${err.message}) — treating overlay as plain markdown without metadata`);
+    }
+  }
+  const baseVersionTargeted = String(overlayMeta[`base_${kind}_version`] || '').trim() || 'unknown';
+  const overlayMode = (overlayMeta.mode || 'extend').trim();
+
+  // Parse the base. Keep its frontmatter verbatim — that's what Claude reads.
+  const baseParsed = parseMarkdown(baseContent);
+
+  // Build a heading → section map for the base. If headings repeat we keep
+  // the first occurrence (Claude Code does the same for repeated `name:`).
+  const baseSectionByHeading = new Map();
+  baseParsed.sections.forEach((s, idx) => {
+    if (s.heading && !baseSectionByHeading.has(s.heading)) {
+      baseSectionByHeading.set(s.heading, { ...s, _idx: idx });
+    }
+  });
+
+  // Apply overlay sections.
+  const newSections = baseParsed.sections.map((s) => ({ ...s }));
+  const trailing = []; // overlay sections without marker → custom adds at the end
+
+  for (const ov of overlayParsed.sections) {
+    if (!ov.marker) {
+      trailing.push(ov);
+      continue;
+    }
+    const base = baseSectionByHeading.get(ov.heading);
+    if (!base) {
+      warnings.push(`overlay section "${ov.marker} ${ov.heading}" has no matching H2 in base ${kind} "${name}" — appending as new section instead`);
+      trailing.push({ marker: null, heading: ov.heading, body: ov.body });
+      continue;
+    }
+    const target = newSections[base._idx];
+    if (ov.marker === 'OVERRIDE') {
+      target.body = ov.body;
+    } else if (ov.marker === 'APPEND') {
+      target.body = `${target.body.replace(/\n+$/, '')}\n\n${ov.body}`;
+    } else if (ov.marker === 'PREPEND') {
+      target.body = `${ov.body.replace(/\n+$/, '')}\n\n${target.body}`;
+    }
+  }
+
+  // Compose the merged body.
+  const sectionsOut = rebuildSections(newSections);
+  const trailingOut = trailing.length
+    ? '\n' + trailing.map((s) => `## ${s.heading}\n${s.body}`).join('\n').replace(/\n+$/, '\n')
+    : '';
+
+  const overlaySha = shortSha(overlayContent);
+  const marker = buildMarker({
+    kind,
+    name,
+    baseVersion: frameworkVersion || baseVersionTargeted,
+    overlaySha
+  });
+
+  const fmBlock = baseParsed.frontmatter
+    ? `---\n${baseParsed.frontmatter}\n---\n`
+    : '';
+
+  const generated =
+    `${marker}\n` +
+    fmBlock +
+    (baseParsed.preamble || '') +
+    sectionsOut +
+    trailingOut;
+
+  return {
+    generated,
+    warnings,
+    baseVersionTargeted,
+    overlayMode,
+    overlaySha
+  };
+}
+
+module.exports = {
+  mergeOverlay,
+  readMarker,
+  parseMarkdown,
+  shortSha,
+  MARKER_PREFIX
+};

package/src/utils/symlinks.js

@@ -126,6 +126,9 @@ class SymlinkUtils {
   async createBulkSymlinks(opts = {}) {
     const mode = opts.mode || 'prompt';
 
+    // AGENTS.md and the cross-tool `agents/` reference dir remain BULK
+    // symlinks — they're single canonical artifacts of the framework that
+    // do not need per-item user-overlay behaviour.
     await this.createSymlink(
       path.join(FRAMEWORK_PAYLOAD, 'AGENTS.md'),
       'AGENTS.md',
@@ -140,19 +143,29 @@ class SymlinkUtils {
 
     this.ensureDirectory('.claude');
 
-    // target is relative to cwd; createSymlink converts it to a path relative
-    // to the link's parent directory when `relative: true`.
-    await this.createSymlink(
-      path.join(FRAMEWORK_PAYLOAD, '.claude', 'agents'),
-      path.join('.claude', 'agents'),
-      { relative: true, mode }
-    );
+    // NB: `.claude/agents/` and `.claude/commands/` are NO LONGER bulk
+    // symlinks since v3.8.0 — they're real directories with per-item
+    // symlinks (or overlay-generated real files). Populated by
+    // mergeAgents() and mergeCommands() which createAllSymlinks() invokes
+    // right after this method.
+    this._convertLegacyBulkSymlinkToDir(path.join('.claude', 'agents'));
+    this._convertLegacyBulkSymlinkToDir(path.join('.claude', 'commands'));
+  }
 
-    await this.createSymlink(
-      path.join(FRAMEWORK_PAYLOAD, '.claude', 'commands'),
-      path.join('.claude', 'commands'),
-      { relative: true, mode }
-    );
+  /**
+   * If `rel` exists and is a symlink (the v3.7.x and earlier bulk-symlink
+   * layout for .claude/agents and .claude/commands), unlink it so that the
+   * per-item merge can populate a real directory in its place. Legacy migration.
+   */
+  _convertLegacyBulkSymlinkToDir(rel) {
+    const full = path.join(this.cwd, rel);
+    let lstat = null;
+    try { lstat = fs.lstatSync(full); } catch (_) { /* absent */ }
+    if (lstat && lstat.isSymbolicLink()) {
+      UI.warning(`Detected legacy bulk symlink at ${rel}. Converting to per-item layout (v3.8.0+).`);
+      fs.unlinkSync(full);
+    }
+    this.ensureDirectory(rel);
   }
 
   // -----------------------------------------------------------------------
@@ -305,14 +318,198 @@ class SymlinkUtils {
     this.mergeSkills({ tools: opts.tools });
 
     UI.newline();
+    UI.section('Merging Framework Agents');
+    this.mergeAgents({ tools: opts.tools });
+
+    UI.newline();
+    UI.section('Merging Framework Commands');
+    this.mergeCommands({ tools: opts.tools });
+
+    UI.newline();
+  }
+
+  // -----------------------------------------------------------------------
+  // Per-item merge for agents and commands (v3.8.0+)
+  //
+  // Same model as skills (per-item, user files coexist, broken-symlink-safe)
+  // PLUS overlay support: if `.baldart/overlays/<kind>s/<name>.md` exists,
+  // BALDART generates a real file `.claude/<kind>s/<name>.md` = base + overlay
+  // merged, with a marker header so future updates know it's regeneration-safe.
+  // -----------------------------------------------------------------------
+
+  mergeAgents(opts = {}) { return this._mergeBulkDir('agent', opts); }
+  mergeCommands(opts = {}) { return this._mergeBulkDir('command', opts); }
+
+  /**
+   * Generic per-item merge for kinds whose framework source is a directory
+   * of single .md files (agents, commands). For each enabled tool whose
+   * adapter declares a target directory (claude.agentsDir(), etc.), this
+   * either symlinks each base file or — when an overlay exists — writes a
+   * generated real file with the overlay applied.
+   */
+  _mergeBulkDir(kind, opts = {}) {
+    const tools = (opts.tools && opts.tools.length) ? opts.tools : ['claude'];
+    const aggregate = { linked: [], generated: [], skipped: [], conflicts: [], warnings: [] };
+    const { getAdapter } = require('./tool-adapters');
+
+    const fwSourceDir = path.join(this.cwd, FRAMEWORK_PAYLOAD, '.claude', `${kind}s`);
+    if (!fs.existsSync(fwSourceDir)) {
+      UI.warning(`No framework ${kind}s found at ${path.relative(this.cwd, fwSourceDir)}. Skipping ${kind} merge.`);
+      return aggregate;
+    }
+
+    const fwItems = fs.readdirSync(fwSourceDir)
+      .filter((n) => n.endsWith('.md') && !n.startsWith('.') && n !== 'REGISTRY.md');
+
+    const frameworkVersion = this._readFrameworkVersion();
+
+    for (const tool of tools) {
+      const adapter = getAdapter(tool, this.cwd);
+      const dirGetter = kind === 'agent' ? adapter.agentsDir : adapter.commandsDir;
+      const targetRel = dirGetter ? dirGetter.call(adapter) : null;
+      if (!targetRel) continue; // tool doesn't support this kind (e.g. Codex)
+
+      this.ensureDirectory(targetRel);
+
+      for (const filename of fwItems) {
+        const baseName = filename.replace(/\.md$/, '');
+        const linkPath = path.join(this.cwd, targetRel, filename);
+        const fwAbsolute = path.join(fwSourceDir, filename);
+
+        // Compute the relative-from-link path used by the symlink so it's
+        // portable if the project gets moved.
+        const linkDepth = targetRel.split(path.sep).filter(Boolean).length;
+        const upPath = path.join(...Array(linkDepth).fill('..'));
+        const target = path.join(upPath, FRAMEWORK_PAYLOAD, '.claude', `${kind}s`, filename);
+
+        const overlayRel = path.join('.baldart', 'overlays', `${kind}s`, filename);
+        const overlayAbs = path.join(this.cwd, overlayRel);
+        const hasOverlay = fs.existsSync(overlayAbs);
+
+        // Inspect what currently lives at the link path (if anything).
+        let lstat = null;
+        try { lstat = fs.lstatSync(linkPath); } catch (_) { /* absent */ }
+
+        if (hasOverlay) {
+          // Generate a real file from base + overlay.
+          this._generateOverlayedFile({
+            kind, name: baseName, fwAbsolute, overlayAbs, linkPath, lstat,
+            frameworkVersion, aggregate, adapter, targetRel
+          });
+        } else {
+          // Plain symlink, with broken-symlink recovery (same fix-pattern as v3.5.1).
+          this._installPerItemSymlink({
+            linkPath, target, fwAbsolute, lstat, baseName, filename,
+            aggregate, adapter, targetRel, kind
+          });
+        }
+      }
+    }
+
+    return aggregate;
+  }
+
+  _installPerItemSymlink({ linkPath, target, fwAbsolute, lstat, baseName, filename, aggregate, adapter, targetRel, kind }) {
+    if (!lstat) {
+      fs.symlinkSync(target, linkPath);
+      UI.success(`[${adapter.label}] ${kind} linked: ${path.join(targetRel, filename)}`);
+      aggregate.linked.push({ tool: adapter.name, kind, name: baseName });
+      return;
+    }
+    if (lstat.isSymbolicLink()) {
+      const current = fs.readlinkSync(linkPath);
+      const resolved = path.resolve(path.dirname(linkPath), current);
+      if (current === target || resolved === fwAbsolute) {
+        aggregate.skipped.push({ tool: adapter.name, kind, name: baseName, reason: 'already-linked' });
+        return;
+      }
+      // Broken or pointing elsewhere — replace if broken, else respect user override
+      if (!fs.existsSync(linkPath)) {
+        fs.unlinkSync(linkPath);
+        fs.symlinkSync(target, linkPath);
+        UI.success(`[${adapter.label}] ${kind} re-linked (was broken): ${path.join(targetRel, filename)}`);
+        aggregate.linked.push({ tool: adapter.name, kind, name: baseName });
+        return;
+      }
+      UI.info(`[${adapter.label}] ${kind} kept (user override symlink): ${path.join(targetRel, filename)} → ${current}`);
+      aggregate.skipped.push({ tool: adapter.name, kind, name: baseName, reason: 'user-symlink-override' });
+      return;
+    }
+    // Real file. Could be:
+    //  (a) A baldart-generated file from a previous run where overlay USED to
+    //      exist but now doesn't — safe to replace with symlink.
+    //  (b) A user-authored fork — leave alone.
+    const { readMarker } = require('./overlay-merger');
+    const content = fs.readFileSync(linkPath, 'utf8');
+    const marker = readMarker(content);
+    if (marker && marker.kind === kind && marker.name === baseName) {
+      // Overlay was removed → revert to symlink.
+      UI.info(`[${adapter.label}] ${kind} overlay removed — replacing generated file with symlink: ${path.join(targetRel, filename)}`);
+      fs.unlinkSync(linkPath);
+      fs.symlinkSync(target, linkPath);
+      aggregate.linked.push({ tool: adapter.name, kind, name: baseName });
+      return;
+    }
+    UI.warning(`[${adapter.label}] ${kind} name conflict (user file at ${path.join(targetRel, filename)}). Framework version NOT installed. Move user content to .baldart/overlays/${kind}s/${filename} to specialize without losing upstream updates.`);
+    aggregate.conflicts.push({
+      tool: adapter.name, kind, name: baseName,
+      local_path: path.join(targetRel, filename),
+      framework_path: path.relative(this.cwd, fwAbsolute),
+      detected_at: new Date().toISOString()
+    });
+  }
+
+  _generateOverlayedFile({ kind, name, fwAbsolute, overlayAbs, linkPath, lstat, frameworkVersion, aggregate, adapter, targetRel }) {
+    const { mergeOverlay, readMarker } = require('./overlay-merger');
+    const baseContent = fs.readFileSync(fwAbsolute, 'utf8');
+    const overlayContent = fs.readFileSync(overlayAbs, 'utf8');
+    const merged = mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersion });
+
+    if (merged.warnings && merged.warnings.length) {
+      merged.warnings.forEach((w) => {
+        UI.warning(`[${adapter.label}] ${kind} ${name}: ${w}`);
+        aggregate.warnings.push({ tool: adapter.name, kind, name, warning: w });
+      });
+    }
+
+    // If a previously generated file is on disk, check ownership via marker
+    // before overwriting. If it lacks the marker (= user edited manually after
+    // a previous generation, or a pre-3.8 fork), refuse to overwrite.
+    if (lstat && !lstat.isSymbolicLink()) {
+      const existing = fs.readFileSync(linkPath, 'utf8');
+      const m = readMarker(existing);
+      if (!m) {
+        UI.warning(`[${adapter.label}] ${kind} ${name}: existing file at ${path.join(targetRel, name)}.md has no baldart-generated marker — NOT overwriting (user fork?). Move it aside (or merge it into the overlay) and re-run update.`);
+        aggregate.conflicts.push({
+          tool: adapter.name, kind, name,
+          local_path: path.join(targetRel, `${name}.md`),
+          reason: 'manual-edit-no-marker',
+          detected_at: new Date().toISOString()
+        });
+        return;
+      }
+    }
+
+    // Replace any existing symlink/file with the freshly generated content.
+    if (lstat) {
+      try { fs.unlinkSync(linkPath); }
+      catch (_) { try { fs.rmSync(linkPath, { recursive: true, force: true }); } catch (_) { /* noop */ } }
+    }
+    fs.writeFileSync(linkPath, merged.generated);
+    UI.success(`[${adapter.label}] ${kind} generated (overlay applied): ${path.join(targetRel, name)}.md`);
+    aggregate.generated.push({ tool: adapter.name, kind, name, overlaySha: merged.overlaySha });
+  }
+
+  _readFrameworkVersion() {
+    const vPath = path.join(this.cwd, FRAMEWORK_DIR, 'VERSION');
+    try { return fs.readFileSync(vPath, 'utf8').trim(); }
+    catch { return 'unknown'; }
   }
 
   verifySymlinks() {
     const bulkSymlinks = [
       'AGENTS.md',
-      'agents',
-      '.claude/agents',
-      '.claude/commands'
+      'agents'
     ];
 
     let allValid = true;
@@ -385,6 +582,39 @@ class SymlinkUtils {
         UI.warning(`[${adapter.label}] Missing: ${skillsRel}/ (the framework would merge skills here)`);
         allValid = false;
       }
+
+      // v3.8.0+: agents and commands also use per-item merge with overlay support.
+      for (const [kindGetter, kindLabel] of [['agentsDir', 'agents'], ['commandsDir', 'commands']]) {
+        if (typeof adapter[kindGetter] !== 'function') continue;
+        const rel = adapter[kindGetter]();
+        if (!rel) continue;
+        const full = path.join(this.cwd, rel);
+        let s = null;
+        try { s = fs.lstatSync(full); } catch (_) { /* absent */ }
+        if (!s) {
+          UI.warning(`[${adapter.label}] Missing: ${rel}/ (framework ${kindLabel} would be merged here)`);
+          allValid = false;
+        } else if (s.isSymbolicLink()) {
+          UI.warning(`[${adapter.label}] Legacy bulk symlink at ${rel}. Run \`npx baldart update\` to convert to per-item layout.`);
+          allValid = false;
+        } else {
+          const entries = fs.readdirSync(full);
+          const frameworkOwned = entries.filter((n) => {
+            const p = path.join(full, n);
+            try {
+              if (fs.lstatSync(p).isSymbolicLink()) return true;
+              const content = fs.readFileSync(p, 'utf8');
+              return content.startsWith('<!-- baldart-generated:');
+            } catch { return false; }
+          });
+          if (frameworkOwned.length === 0) {
+            UI.warning(`[${adapter.label}] ${rel}/ has no framework-managed ${kindLabel}. Run \`npx baldart update\`.`);
+            allValid = false;
+          } else {
+            UI.success(`[${adapter.label}] Valid: ${rel}/ (${frameworkOwned.length} framework-managed ${kindLabel})`);
+          }
+        }
+      }
     }
 
     // Project configuration (v3.0.0+)

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

@@ -21,6 +21,12 @@ class ClaudeAdapter {
   /** Where this tool reads skill bundles from. */
   skillsDir() { return '.claude/skills'; }
 
+  /** Where this tool reads subagent definitions from (null if unsupported). */
+  agentsDir() { return '.claude/agents'; }
+
+  /** Where this tool reads slash commands from (null if unsupported). */
+  commandsDir() { return '.claude/commands'; }
+
   /** Whether this tool consumes subagent definitions (`.claude/agents/`). */
   supportsSubagents() { return true; }
 

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

@@ -33,6 +33,13 @@ 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; }
+  commandsDir() { return null; }
+
   supportsSubagents() { return false; }
   supportsSlashCommands() { return false; }
   supportsHooks() { return false; }