← ClaudeAtlas

hcs-schema-changelisted

Change an HCS entity schema correctly — Zod source, generated JSON Schema, docs, tests, and fixtures all move together in a single PR.
jefahnierocks/host-capability-substrate · ★ 0 · API & Backend · score 65
Install: claude install-skill jefahnierocks/host-capability-substrate
# Skill: Change a schema Use when adding, modifying, or removing an entity in `packages/schemas/`. Schema drift is the most expensive early mistake (per research plan §18 regression corpus); this skill enforces the "schema + docs + JSON Schema + tests move together" discipline. ## Inputs - The entity to change (e.g., `HostProfile`, `OperationShape`, `Evidence`) - The nature of the change (add field, remove field, change type, add new entity) - The reason (cite an ADR, a policy need, or an observed failure) ## Procedure 1. Read `packages/schemas/src/entities/<entity>.ts` — the Zod source. 2. Read `docs/host-capability-substrate/ontology.md` — the human-facing description. 3. Read any tests under `packages/schemas/tests/` or `packages/fixtures/` covering the entity. 4. Read the generated JSON Schema at `packages/schemas/generated/<entity>.schema.json` (if present). 5. Determine whether the change is: - **Additive with defaults** — no `schema_version` bump; backward-compatible - **Breaking** — `schema_version` must bump; consumers may need migration 6. Make the change in the Zod source. 7. Update `docs/host-capability-substrate/ontology.md` in the same commit. 8. Regenerate JSON Schema in the same commit (`just generate-schemas`). 9. Update tests to cover the new shape, including edge cases. 10. Update fixtures if the entity is used in test data. ## Rules - **One PR per schema change.** Do not bundle schema changes with unrelated kernel work. - **`schema_version` bu