kami-architecture-contract

Documents the architectural invariants and import rules governing the kami-kakushi TypeScript game codebase.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Contributors and AI agents editing the kami-kakushi codebase often make changes that compile and pass tests but quietly violate the project's architectural rules, causing save-replay breakage, preview/reality drift, and import cycles. This Skill loads the 15 load-bearing invariants, the state→intent→reduce→render flow, and the known-weak seams before any design, review, or refactoring work in src/. ## Core Features & Use Cases - Invariant Reference: Enumerates 15 enforced architectural rules (pure core, single seeded RNG, derived visibility, descriptor-based log, finish() pass ordering, DEV/PROD strip, generated fixtures, RICE/COIN/KOKU economy separation), each anchored to its ADR/FB/AC record and enforcement gate. - Subsystem Map with Import Rules: Defines what each src/ directory owns and which imports are legal, including the oxlint-enforced pure core boundary and the index.ts-only public surface. - Known-Weak Seams: Lists admitted architectural weaknesses (positional log keys, skip-blind balance sim, mutable DEV lever state, tsx-importability traps) so they are not rediscovered or silently patched. - Use Case: Before adding a pass to the reduce tail, a new RNG stream, or a stored derived value, load this Skill to check the change against the contract and route to the correct sibling skill (kami-verify-gates, kami-save-and-schema, kami-extension-recipes). ## Quick Start Load the kami-architecture-contract skill before designing or reviewing any change to src/ and check the proposed edit against the 15 invariants and subsystem import rules.

Frequently Asked Questions about kami-architecture-contract

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

FAQPage Schema
How do I check if a code change violates the kami-kakushi architecture?

Load this Skill and compare the change against the 15 invariants, such as the pure core rule, single seeded RNG, and derived-not-stored visibility. Each invariant lists its enforcement mechanism, whether an oxlint gate, a test gate, or a review norm.

What are the import rules for src/core in this TypeScript game?

src/core imports nothing from ui, app, or persistence, and consumers may only import the core public index.ts. Cross-cutting concerns flow through progress-event tokens via applyProgressEvent, never through reducer-to-reducer calls, keeping the core dependency graph acyclic.

Why can't I store derived values like visibility in GameState?

Visibility must be derived by visibleSet(state) from latched fact flags, never stored, because stored values drifted from save files and caused six-plus back-reveal patches. The state.unlocked field was deleted in the v10 to v11 migration under ADR-179.

When should I not use the architecture contract skill?

Route per-gate RED fixes to kami-verify-gates, build and dev-server mechanics to kami-build-and-env, save migrations to kami-save-and-schema, and step-by-step feature recipes to kami-extension-recipes. This Skill states what must stay true, not what to type.

What happens if I edit a *.gen.ts file directly?

Edits to generated registries vanish on regeneration, and the gen-narrative gate byte-compares the output and fails, naming the source .md file to edit instead. Story and requirement content is authored in markdown and compiled by the gen:narrative script.