# Stage overlays

Source: https://codeherder.com/docs/stage-overlays/

Add instructions, a model tier, skills or verifications to a stage you inherit without copying it. Edit it in Settings → Stages or with the CLI.

Say your workspace inherits the `code` stage from a parent group, and you want its agents to follow one extra rule. You could copy the stage into your workspace and edit the copy. Then you own that copy, and you stop getting changes to the original.

A **stage overlay** avoids that. It is a small set of additions that your workspace puts on top of a stage it inherits. The stage itself stays shared and keeps updating. Your additions ride along.

An overlay can add four things:

- **Additional instructions.** Text added to the end of the stage’s prompt.
- **A model tier.** `haiku`, `sonnet` or `opus`, for the agents that work this stage.
- **Extra skills.** Skills the stage’s sessions get on top of its own list.
- **Extra verifications.** Checks the stage runs, with a kind of `test`, `lint`, `typecheck` or `goal-gate`.

An overlay only adds. It has no setting for whether the stage can commit code, its image, isolation, environment or network access. Those stay as the stage defines them, so an overlay can’t loosen a stage.

Each workspace has at most one overlay per stage. The overlay applies to every workflow that uses that stage.

## Overlay or configuration overlay?

The stage library page also mentions a *configuration overlay*. That one is different. It switches one verification on or off for **one workflow**. A stage overlay adds to a **stage** for your whole workspace. See [Changing a stage’s verifications for one workflow](https://codeherder.com/docs/stage-library/#changing-a-stages-verifications-for-one-workflow) for the other kind.

## How layers stack

Overlays can exist at every level of your hierarchy. A group can have an overlay on a stage, and so can each workspace below it. CodeHerder applies them from the top group down to your workspace:

- **Instructions** from every layer appear one after another. Each layer’s text sits under a heading that names the workspace it came from, such as “Additional instructions — Platform team”.
- **The model tier** comes from the layer closest to your workspace that sets one. Layers that leave it as inherited don’t count.
- **Skills and verifications** add up across layers. If two layers add a verification with the same ID, CodeHerder keeps the first and drops the later one.

Two cases where an addition has no effect:

- An extra skill does nothing when the stage doesn’t narrow its skills. Such a stage already uses every skill your workspace has switched on. See [Which skills a stage gets](https://codeherder.com/docs/stage-skills/).
- If your workspace owns its own copy of the stage, overlays set in the groups above it don’t apply. Your copy is the base. Your workspace’s own overlay still does.

A model tier sets what the stage needs from an agent, so an agent whose launch config covers that tier has to be available to work it. See [Which model your agents run](https://codeherder.com/docs/agent-models/). CodeHerder can still move a stage to a stronger model after rework. See [How work flows](https://codeherder.com/docs/how-work-flows/#automatic-model-escalation-on-rework).

A change applies when CodeHerder starts the next session in that stage. It doesn’t reach a session already running.

## Edit an overlay in the web app

Open **Settings → Stages** and click a stage. Its page has a **Stage overlay** section with these fields:

- **Additional instructions.** Free text, up to 16 KiB.
- **Model tier.** Choose a tier, or leave it on **Inherited**.
- **Extra skills.** One skill slug per line, up to 64. Each must be a skill your workspace can see.
- **Extra verifications.** A JSON array, up to 16 items. Each item has an `id`, a `kind`, a `required` flag and, for every kind except `goal-gate`, an optional `command`. A `goal-gate` check runs no command.

```
[
  { "id": "unit", "kind": "test", "required": true, "command": "make test" }
]
```

Choose **Save changes** to save. CodeHerder refuses the save if a skill is unknown, if an ID matches a verification the stage or an inherited overlay already has, or if a field is over its limit. The error names the field.

**Delete** removes the overlay, and the stage goes back to what it inherits. The overlay’s version history stays, so you can bring an earlier version back with the CLI (below).

An overlay written by an outside tool shows a **managed by** badge. The badge is a notice. You can still edit the overlay.

## See the result

The same stage page has a **Compiled prompt** section. It lists the base prompt and each overlay in the order they apply, then what the stage ends up with: the model tier, the skills, the verifications, anything dropped, and the final prompt text. Check it after a change, and whenever a parent group’s overlay surprises you.

From the CLI:

```
ch stage compiled-prompt code
```

## Manage overlays with the CLI

List every overlay your workspace has, or show one:

```
ch stage overlay show
ch stage overlay show code
```

Create or change an overlay with `set`. Pass the instructions in a file, not inline:

```
ch stage overlay set code --prompt-file extra.md --model-tier sonnet
ch stage overlay set code --skill go-style --skill sql-style
ch stage overlay set code --verifications-file extra-checks.json
```

`set` changes only what its flags name. The other parts of the overlay keep their value. So `--model-tier haiku` leaves your instructions alone. A few details:

- `--skill` replaces the whole skill list. Repeat it for each skill. `--clear-skills` removes them all.
- `--verifications-file` replaces the whole verification list, and an empty array `[]` clears it. `--verifications` takes the JSON directly, or `-` to read it from standard input.
- `--model-tier none` goes back to inheriting the tier.
- `--change-note` records a short note against the version.
- `--expected-version <n>` makes the save fail if someone else changed the overlay since you read it. Without it, `set` still refuses a change that raced with another edit.

Every save is a new version. To see the history, or roll back:

```
ch stage overlay versions code
ch stage overlay revert code 2
ch stage overlay delete code
```

`revert` writes version 2’s content as a new version, so nothing is lost. It also brings back an overlay you deleted. You can’t revert to a version that records a delete. `delete` keeps the history too. `revert` runs the same checks as `set`. If version 2 names a skill that is gone, or a verification id that is now taken, the revert is refused with the reason, and nothing is written.

## Who can do what

Any member of the workspace can read overlays and the compiled prompt. Changing an overlay (`set`, `delete`, `revert`, or **Save changes** in the web app) needs a workspace **owner or admin**. A credential tied to a running session is refused, even when its owner holds an admin role. A member without that role sees the overlay section read-only.

## Related guides

- [The stage library](https://codeherder.com/docs/stage-library/) — the shared stages an overlay builds on
- [Which skills a stage gets](https://codeherder.com/docs/stage-skills/) — narrow a stage to a list of skills
- [Which model your agents run](https://codeherder.com/docs/agent-models/) — how a model tier turns into a model
- [Customising workflows](https://codeherder.com/docs/task-types/) — a workflow’s stages, gates and fields
- [Version history](https://codeherder.com/docs/version-history/) — how versions and reverts work across CodeHerder
