AGENTS.md@packages/builds git:20261017.51cc604A

Immutable. This exact content never changes and is served at /api/v1/blob/499ffa31e292f79b.

# @shadowclone/builds

Plans and applies agent builds: the skills and preferences that a person or a repository selects. The CLI and the browser wizard share it.

<!-- package-facts:start -->

(generated by `bun run guides`; do not edit by hand)

- Package name: `@shadowclone/builds`
- Workspace dependencies: `@shadowclone/changes`, `@shadowclone/core`, `@shadowclone/environment`, `@shadowclone/redact`, `@shadowclone/skills`
- External dependencies: `zod`
- Export subpaths: `.`, `./testing`, `./browser`

<!-- package-facts:end -->

## Owns

- `src/catalog.ts`: `buildCatalog`, the list of items that a build can equip.
- `src/plan.ts` and `src/apply.ts`: `previewBuild`, `buildPlanFingerprint`, and `applyBuild`.
- `src/requirements.ts`: `sharedRequirements`, the choices that a shared build locks.
- `src/bundledUpdate.ts`, `sync.ts`, and `retirement.ts`: update, sync, and retire bundled skills.
- `src/constellation.ts`: the skill map data. Web loads it through `./browser`.

## Rules

- `applyBuild` takes the environment write lock. It fails when the managed policy is off.
- `applyBuild` fails when a file changed after the preview. Preview again before you apply.
- A private build cannot change a choice that a shared build locks.
- Retire removes a skill file only when its fingerprint matches the record. An edited copy stays, with a warning. A deleted copy stays deleted, and retire drops its record.
- Every write goes through `publishEnvironmentRevision`, so `undo` can reverse it.

## Tests

Run `bun test` in this folder, or `bun test packages/builds` from the root. The `./testing` export gives `buildFixture`. The files in `src/fixtures/` are test input, not documents.

Update this file in the same commit when you change the package purpose, public exports, dependencies, or a rule above.