kami-save-and-schema

Guides save persistence, schema migrations, and version bumps for the kami-kakushi game.

1|Updated Jun 29, 2026
One-click install
npx skills add https://github.com/Raynos/kami-kakushi --skill kami-save-and-schema-raynos
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: kami-save-and-schema
Source: https://github.com/Raynos/kami-kakushi/tree/main/.claude/skills/kami-save-and-schema
Command: npx skills add https://github.com/Raynos/kami-kakushi --skill kami-save-and-schema-raynos

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Changing GameState fields, renaming content ids, or bumping SCHEMA_VERSION in the kami-kakushi codebase can silently orphan old player saves, break the fixtures gate, or corrupt stored data. This Skill provides the ordered schema-bump recipe, migration test patterns, and hazard list needed to evolve the save format without losing player progress. ## Core Features & Use Cases - Schema-Bump Recipe: Step-by-step checklists for the three schema-growth rungs (additive field, rename/restructure, world reboot), including hydration defaults, identity migration steps, and the version-history doc line. - Migration Test Patterns: Guidance for hand-built inline fixtures, registry-derived assertions, MemoryBackend wiring tests, and idempotency-safe migration functions. - Hazard & Incident Knowledge: Documents known traps such as positional log keys, orphaned content ids, the renderLogLine import trap, and the missing old-save e2e gate. - Use Case: You add a new asksHeard field to GameState. The Skill walks you through adding the hydration default with numAdditive, bumping SCHEMA_VERSION, adding an identity migration step, writing the hydration test, and regenerating fixtures in the same commit. ## Quick Start Ask the assistant to walk you through adding a new field to GameState and bumping SCHEMA_VERSION using the kami-save-and-schema recipe.

Frequently Asked Questions about kami-save-and-schema

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new field to GameState without breaking old saves?

Add the field to GameState and createInitialState, register it in the _Handled ledger in validate.ts, give it a hydration default using numAdditive for numeric fields, bump SCHEMA_VERSION with an identity migration step, and regenerate fixtures in the same commit.

How do I write a save migration when renaming a content id?

Add a migration function to MIGRATIONS in migrate.ts keyed by the FROM version. Map over stored entries, rewrite keys via live registries, leave unresolvable keys untouched so the codec falls back to stored prose, and make the migration idempotent-safe.

What is the difference between SCHEMA_VERSION and APP_GENERATION?

SCHEMA_VERSION gates the within-generation migration chain and bumps on field changes. APP_GENERATION marks a world generation; older-generation saves are retired with a backup and fresh boot, never migrated, and bumping it is a human-gated decision.

Why does the fixtures verify gate go red after a state change?

Every fixture save carries schemaVersion in both the envelope and state, so any schema bump invalidates committed fixtures. Run pnpm run fixtures:regen and commit the regenerated files together with the migration and version doc line.

When should I not bump APP_GENERATION?

Never bump it autonomously. It is legitimate only for a design reset that makes old runs genuinely meaningless, like the storywave T0 rewrite. Even then, raw bytes are backed up and players get an in-fiction notice rather than a silent wipe.