---
name: overlay
effort: medium
description: "Guided author of .baldart/overlays/ — the per-project customisation layer for BALDART skills, agents, and commands. Use when the user says /overlay, 'customizza skill', 'modifica agente upstream', 'personalizza comando', 'crea overlay', 'extend skill X', 'override agent Y', 'overlay drift', or when the framework-edit-gate hook blocked an edit and pointed here. The skill walks the user through choosing the right canal (skill / agent / command), scaffolds the overlay with correct frontmatter and section markers via `npx baldart overlay scaffold`, validates the merge via `npx baldart overlay validate`, and surfaces drift via `npx baldart overlay drift`. Never edits `.framework/` directly and never re-implements the merger logic — the CLI is the source of truth."
contamination_scan: skip
---

# /overlay — Customise the framework, the right way

Author an overlay under `.baldart/overlays/` for a BALDART skill, agent, or command, instead of editing `.framework/` (which gets overwritten on `baldart update` and blocked by the contamination scanner).

## Execution model

This skill is a **thin guidance wrapper** around `npx baldart overlay`. The CLI is non-interactive (no prompts), so the skill can invoke it via the Bash tool. The CLI is the source of truth for:

- Path conventions (`.baldart/overlays/<name>.md` for skills, `.baldart/overlays/agents/<name>.md`, `.baldart/overlays/commands/<name>.md`).
- Frontmatter schema (`base_<kind>`, `base_<kind>_version`, `base_file_sha`, `mode`).
- Merger validation (uses `src/utils/overlay-merger.js` internally).
- Drift detection (SHA-based when `base_file_sha` is present, version-based fallback).

The skill MUST NOT re-implement any of the above. If you find yourself writing path logic or YAML manipulation, stop — invoke the CLI.

## When to use

- The user invokes `/overlay`.
- The user says "customizza skill X", "personalizza il command Y", "modifica l'agente Z per questo progetto".
- The user wants a project-specific opinion to apply (brand voice, debug entry point, stack mandate, custom workflow) without contaminating the framework upstream.
- The user follows the handoff from the `framework-edit-gate` hook message ("invoke /overlay for a guided flow").
- The user asks "is my overlay still in sync with the framework?" or "drift overlay".

## When NOT to use

- The improvement is **generic** (useful for all consumers). Send it upstream via `/baldart-push` instead.
- The user wants to install / update the framework itself (use `npx baldart` / `update`).
- The user wants to author a brand-new skill that has no base in the framework — they create it directly under `.claude/skills/<name>/`. Overlays are for *modifying* a framework primitive, not for net-new ones.
- The user wants to modify a **hook** under `.claude/hooks/`. Hooks are installed as **plain copies** (consumer-owned, no auto-update) — they do not fit the overlay model. The consumer edits them directly in their repo. If the change should benefit every consumer, edit the `.template` file under `.framework/.claude/hooks/` and push upstream via `/baldart-push`. Overlay scope is limited to skills, agents, and commands.

## Project Context

**Reads from `baldart.config.yml`:** none (overlay paths are universal).
**Gated by features:** none.
**Overlay:** this skill has no overlay (it would be paradoxical).
**On missing/empty keys:** not applicable.

## Effort

**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
reasoning depth for this run — detect it once at kickoff and strip the token
before consuming user input. Level→behavior mapping, parsing contract, and
precedence caveats: `framework/agents/effort-protocol.md`.


## Hard rules

1. **NEVER edit files under `.framework/` directly.** The contamination scanner will block the edit, and even if it didn't, `baldart update` would overwrite the change.
2. **NEVER edit a file with the marker `<!-- baldart-generated:` on line 1.** It is auto-regenerated from base + overlay. The hook blocks this. Edit the overlay instead.
3. **NEVER fabricate `base_<kind>_version` or `base_file_sha`.** Both are computed by the CLI at scaffold time. The skill never writes these by hand.
4. **NEVER write to `.baldart/overlays/` with the Edit/Write tools to *create* a new overlay.** Use `npx baldart overlay scaffold` so the frontmatter is correct. Editing the *body* of an already-scaffolded overlay with Edit/Write is fine.
5. **NEVER re-implement the section-merge logic** (`[OVERRIDE]/[APPEND]/[PREPEND]`). The merger in `overlay-merger.js` is the only place it lives.
6. **When the user's intent is clearly generic** ("we should add a Quality bar step to every coder workflow"), redirect them to `/baldart-push` instead of scaffolding an overlay.

## Workflow

### Step 0 — Pre-check

Before anything, confirm this is a consumer repo:

```
[ -d .framework ] && echo OK
```

If not OK, stop and say: "This repo is not a BALDART consumer. Run `npx baldart` to install the framework first."

Also confirm the overlays directory exists (it should, after `configure`):

```
[ -d .baldart/overlays ] || mkdir -p .baldart/overlays
```

### Step 1 — Discovery

Ask the user:

1. **What do they want to customise?** A skill, an agent, or a command?
   - **Skill**: shapes how a `/-command` workflow behaves (e.g. `/bug`, `/capture`, `/new`). Base lives at `.framework/framework/.claude/skills/<name>/SKILL.md`. Overlay is concat'd at runtime by the agent — section markers are textual conventions, not parsed.
   - **Agent**: shapes how a specialised subagent reasons (e.g. `coder`, `code-reviewer`, `qa-sentinel`). Base lives at `.framework/framework/.claude/agents/<name>.md`. Overlay is merged section-by-section via markers, producing a generated file at `.claude/agents/<name>.md`.
   - **Command**: shapes a top-level slash command (e.g. `/codexreview`, `/check`). Base lives at `.framework/framework/.claude/commands/<name>.md`. Same marker-based merge as agents.

2. **Which one?** List the available bases for the chosen kind:

   ```bash
   # for skills
   ls .framework/framework/.claude/skills/
   # for agents
   ls .framework/framework/.claude/agents/
   # for commands
   ls .framework/framework/.claude/commands/
   ```

3. **What intent?**
   - `extend` (default) — add to / tweak parts of the base.
   - `override` (skills only) — replace the entire base skill with the overlay content. Rare; use only when the base does not fit your project at all.

### Step 2 — Inspect base + existing overlay

Read the base file with the Read tool. Show the user the H2 section list (`grep '^## ' <base-file>`). This is what they can target with `[OVERRIDE]/[APPEND]/[PREPEND]` (for agent/command) or as textual landmarks (for skill).

If `.baldart/overlays/<path>` already exists:

- Show its current frontmatter and section list.
- Run drift check: `npx baldart overlay drift .baldart/overlays/<path>`.
- Switch to "extend existing" mode: the skill will guide the user to add / modify sections by **editing the file directly** (Edit tool), not by re-scaffolding.

### Step 3 — Scaffold (new overlays only)

Invoke the CLI:

```bash
npx baldart overlay scaffold <kind>/<name> [--mode override]
```

Where `<kind>` is `skill`, `agents`, or `commands` (plural for agent/command to match the overlay subdir convention). Examples:

- `npx baldart overlay scaffold agents/coder`
- `npx baldart overlay scaffold commands/codexreview`
- `npx baldart overlay scaffold bug` (no slash → skill)
- `npx baldart overlay scaffold skill/bug --mode override`

The CLI:
- Validates that the base exists in `.framework/`.
- Computes `base_file_sha` (sha256, 12 chars) from the base content.
- Reads framework `VERSION`.
- Writes `.baldart/overlays/<path>` with the correct frontmatter and a placeholder body.

If the overlay already exists, the CLI refuses (idempotent). Use Step 4 to extend it instead.

### Step 4 — Author the body

Open the scaffolded file with the Read tool, show the user the placeholder content, and ask what they want to put there. Use the Edit tool to insert their content. Examples of what each marker does:

**For agent / command overlays:**

```markdown
## [APPEND] Quality bar

- Before closing any task, run `npm run test:e2e -- --grep <feature>`.
- Attach the Playwright screenshot to the commit body.

## [OVERRIDE] When to escalate

In this project, escalate to the human owner before touching `prisma/schema.prisma`.

## Project-only conventions

(New section, appended at the end of the merged file.)
- All API calls go through `src/lib/api-client.ts`.
```

**For skill overlays** (concat model — markers are textual conventions only):

```markdown
## [APPEND] Project-specific guidance

In this project, debug entry points are in `apps/web/`. Always start
Playwright in headed mode for visual bugs.
```

Reference examples already shipped with the framework:
- `.framework/framework/templates/overlays/ui-design.fidelity-example.md` (skill, fidelity-app brand voice)
- `.framework/framework/templates/overlays/copywriting.fidelity-example.md` (skill, 4-pillar brand voice)
- `.framework/framework/templates/overlays/agents/coder.example.md` (agent, marker-based)
- `.framework/framework/templates/overlays/commands/codexreview.example.md` (command, marker-based)

### Step 5 — Validate

Run:

```bash
npx baldart overlay validate <path>
```

The CLI dry-runs the merger and reports:
- Frontmatter parse status.
- For agent/command: number of lines generated, any warnings (e.g. an overlay section whose heading does not match any base H2 — it will be appended as a new section, which may be intentional).
- Whether the base file changed since the overlay was authored (SHA comparison).

If `validate` reports errors, fix them with Edit and re-run. If it reports warnings about non-matching headings, decide with the user whether that is intentional (new custom section) or a typo to correct.

### Step 6 — Apply

- **For skills**: nothing to do. The overlay is loaded at runtime by Claude when the user invokes a `/-command` that uses the skill.
- **For agents / commands**: run `npx baldart update` to regenerate the file in `.claude/<kind>s/<name>.md` from base + overlay. The regenerated file carries the `<!-- baldart-generated: -->` marker on line 1 — do not edit it manually (the `framework-edit-gate` hook will block, anyway).

### Step 7 — Drift maintenance (periodic)

When the user updates the framework (`npx baldart update` bumps `VERSION`), the base files for their overlays may have changed. Tell them how to audit:

```bash
npx baldart overlay drift --all
```

For each drifted overlay, the user should:
1. Open the base file: `.framework/framework/.claude/<path>`.
2. Read the diff against what they expected (use `git -C .framework log -p -- framework/.claude/<path>` to see the upstream changes).
3. If the overlay still makes sense, refresh the `base_file_sha` by re-running scaffold (after backing up the overlay body) — or simply update `base_file_sha` by hand once they have confirmed the overlay still applies cleanly.
4. If the overlay no longer makes sense, edit it to align with the new base.

## Failure modes & remediation

| Symptom | Likely cause | Remediation |
|---|---|---|
| `scaffold` says "already exists" | Overlay was authored previously | Edit the existing file directly. Run `overlay drift` first to check. |
| `validate` says "frontmatter mismatch" | `base_<kind>: <name>` does not match the overlay's filename | Either fix the frontmatter or rename the file. The two MUST agree. |
| `validate` warning "overlay section has no matching H2 in base" | The user used `[OVERRIDE]` / `[APPEND]` / `[PREPEND]` with a heading that does not exist in the base file | Either fix the heading to match an existing base H2, or drop the marker (the section will become a new custom section appended at the end). |
| `drift` says "drift unknown" | Overlay was authored before `base_file_sha` existed (pre-v3.19.0) | Re-run `scaffold` on a temp path to capture the current SHA, then merge that into the overlay frontmatter manually. Or just accept the version-based fallback. |
| Hook blocked an edit to a generated file | The user tried to edit `.claude/agents/<x>.md` directly, which is BALDART-managed | Edit the overlay at `.baldart/overlays/agents/<x>.md` instead. The hook message already says this. |

## Reference

- `framework/agents/project-context.md` § 5 — overlay protocol.
- `framework/templates/overlays/README.md` — conventions and pointer to example overlays.
- `src/utils/overlay-merger.js` — merger implementation (read-only; do not duplicate in the skill).
- `src/commands/overlay.js` — CLI implementation (skill calls this via Bash).
