@adobe/data-ai 0.9.83 → 0.9.86

package/.claude/rules/type-casts.md

@@ -0,0 +1,94 @@
+---
+paths:
+  - 'packages/**/*.ts'
+  - 'packages/**/*.tsx'
+---
+
+# Type casts — only two valid uses
+
+`as` is dangerous. It silently turns off the type checker for the cast
+expression. Every cast is a place a future refactor can break in
+silence. There are exactly two valid uses:
+
+1. **Proving a type the compiler cannot see.** A runtime invariant you
+   have established but TypeScript has no way to verify — e.g.
+   "validated JSON matches `User.schema`", "this `unknown` from a loose
+   API is `number` because the schema declared it", "this DOM node is
+   `HTMLInputElement` because the selector matched `input`".
+
+2. **Widening a literal or default to a useful container type.** A
+   resource or component default is `0` (the literal) without help.
+   `0 as F32` widens it to `F32` so the resource can hold any number,
+   not just zero. Same for `[] as User[]`, `false as boolean`,
+   `{} as State`. Without the cast, the inferred type is so narrow it
+   blocks every later assignment.
+
+Anything else is the cast hiding a real defect. Most often: an identity
+cast that neither narrows nor widens, used to make a type error go
+away without fixing the underlying type.
+
+## The acceptance test
+
+Before every `as`, articulate in one sentence which of the two it is:
+
+- **Case 1:** "I know `<expr>` is `<T>` because <runtime invariant>."
+- **Case 2:** "I'm widening `<literal>` so the container can hold any `<T>`."
+
+If your sentence reduces to "TypeScript is wrong" or "I just want this
+to compile", the cast is hiding a real defect — fix the type at its
+source, do not cast at the consumer.
+
+## Common violations
+
+### Identity casts (neither widening nor narrowing)
+
+```ts
+// ❌ `cameraAngle + delta` is already F32 (= number). Cast does nothing.
+t.resources.cameraAngle = (t.resources.cameraAngle + delta) as F32;
+
+// ✅
+t.resources.cameraAngle = t.resources.cameraAngle + delta;
+```
+
+### Casting `any` to a specific shape just to call a property
+
+```ts
+// ❌ `prev` is already any; the cast adds no information.
+const n = (prev as ArrayLike<number>).length;
+
+// ✅
+const n = prev.length;
+```
+
+### Casting wider than necessary
+
+```ts
+// ❌ Loses the value-side type for no reason.
+const map = t.componentSchemas as Record<string, any>;
+
+// ✅ Same key widening, but values stay typed as Schema.
+const map = t.componentSchemas as Record<string, Schema>;
+```
+
+### Casting to silence an error you should fix at the source
+
+```ts
+// declaration (your code)
+export const emit = (name: string, payload: unknown): void => {
+    return inner.send(name, payload);  // actually returns Promise<Ack>
+};
+
+// ❌ cast hides the lie; every caller will duplicate it
+const ack = await (emit("save", data) as Promise<Ack>);
+
+// ✅ fix the declaration once; every consumer benefits
+export const emit = (name: string, payload: unknown): Promise<Ack> => {
+    return inner.send(name, payload);
+};
+```
+
+## When the lying type is in code you control
+
+Fix the declaration. A consumer-side cast is a leaky patch every other
+caller will duplicate; one declaration change removes the cast
+everywhere and protects future call sites the compiler will now catch.

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adobe-data-ai",
-  "version": "0.9.75",
+  "version": "0.9.86",
   "description": "Architecture skills for @adobe/data — data-oriented modelling, archetype iteration, hot-path performance, and related conventions.",
   "author": {
     "name": "Adobe"

package/README.md

@@ -1,102 +1,80 @@
 # @adobe/data-ai
 
-Cross-agent architecture skills for [`@adobe/data`](https://www.npmjs.com/package/@adobe/data). One skill bundle, authored once, distributed two ways.
+AI architecture skills + rules for building applications with
+[`@adobe/data`](https://www.npmjs.com/package/@adobe/data) — a layered,
+spec-first feature structure (`data → ecs → ui`) kept honest by conformance
+tests. Versioned in lockstep with the library: `@adobe/data-ai@x.y.z` targets
+`@adobe/data@x.y.z`.
 
-Skills version in lockstep with the library: `@adobe/data-ai@x.y.z` describes `@adobe/data@x.y.z`.
+It installs two things:
 
-There are two distribution paths, one per agent family — they do **not** overlap:
+- **skills** — `build-*` commands that scaffold features and applications.
+- **rules** — the path-scoped conventions those skills follow while building.
 
-- **Claude Code → marketplace plugin** (see below). The installer never writes into `.claude/skills/`, so it can't collide with your own Claude skills.
-- **Cursor / Codex / other `.agents`-standard agents → `npx … install`** (below).
+> **For the installing agent:** find the block below that matches your host
+> (Claude Code or Cursor/other), run its commands, and stop. Each install owns a
+> namespaced folder and is a clean wipe-and-recopy, so re-running is also how you
+> **update** — it never touches files you authored.
 
-## Install (Cursor, Codex, `.agents` agents)
+## Install — Claude Code
 
-The installer copies the skill folders into a single namespaced bundle directory that agents which recurse `.agents/skills/` discover:
+Skills load as a marketplace plugin; rules install into the project. Run these
+three from a shell (agent-runnable):
 
-```sh
+```
+claude plugin marketplace add adobe/data --scope project
+claude plugin install adobe-data-ai@adobe-data-skills --scope project
 npx @adobe/data-ai@latest install
 ```
 
-This writes `.agents/skills/adobe-data-ai/<name>/SKILL.md` for each skill. The whole `adobe-data-ai/` directory belongs to this package, so a re-run is a clean wipe-and-recopy that never touches skills you authored elsewhere. Commit the result to share it with your team.
-
-Options:
+In an interactive Claude session you can instead use the slash-command form of
+the first two — `/plugin marketplace add adobe/data` then
+`/plugin install adobe-data-ai@adobe-data-skills` — but an agent driving a shell
+should use the `claude plugin …` commands above (slash commands aren't
+shell-runnable).
 
-```sh
-npx @adobe/data-ai@latest install --global      # into ~/.agents/skills/adobe-data-ai/
-npx @adobe/data-ai@latest install --dir=./sub    # into a specific base dir
-npx @adobe/data-ai@latest list                   # show bundled skills
-```
+- Skills → the `adobe-data-ai` plugin. **Update:** `claude plugin update adobe-data-ai`.
+- Rules → `.claude/rules/adobe-data-ai/`. **Update:** re-run `npx @adobe/data-ai@latest install`.
 
-## Install (Claude Code plugin)
+## Install — Cursor (and Codex / other `.agents` agents)
 
-Claude Code does not scan `.agents/`; it consumes the skills as a native plugin from the `adobe/data` marketplace — no npm needed.
+One command installs both:
 
-Interactive:
-
-```
-/plugin marketplace add adobe/data
-/plugin install adobe-data-ai@adobe-data-skills
 ```
-
-Or declaratively, so collaborators are prompted to auto-install on next launch — commit to your repo's `.claude/settings.json`:
-
-```json
-{
-  "extraKnownMarketplaces": {
-    "adobe-data-skills": {
-      "source": { "source": "github", "repo": "adobe/data" }
-    }
-  },
-  "enabledPlugins": {
-    "adobe-data-ai@adobe-data-skills": true
-  }
-}
+npx @adobe/data-ai@latest install
 ```
 
-The plugin cache is version-hashed and garbage-collected, so it is not a stable path to symlink against — prefer the `npx … install` copy model when you need a durable, cross-agent artifact.
-
----
-
-# Pragmatic Programming
+- Skills → `.agents/skills/adobe-data-ai/`.
+- Rules → `.claude/rules/adobe-data-ai/`.
+- **Update:** re-run the same command.
 
-## Target Audience
+## Use
 
-Software engineers who want to build high quality applications with a sustainable velocity.
+Ask your agent to run a build command — skills are available by name:
 
-## Goals
+- **`build-application`** — build a whole app: a base feature that hosts
+  lazily-loaded peer features.
+- **`build-feature`** — build one feature end to end. Pipes the per-layer skills
+  (`data → core-database → transactions → … → ui`), then conformance-tests the
+  result against its pure `data/` spec.
 
-The goal of effective software engineers is to generate a high rate of value per unit time.
+Both compose finer-grained skills that are installed alongside and discoverable
+by name when you want a single phase or a specialized flow: `build-data`,
+`build-core-database`, `build-indexes`, `build-transactions`, `build-computed`,
+`build-services`, `build-service-database`, `build-actions`, `build-systems`,
+`build-ui`, `build-app-entry`; plus `build-game`, `meta-build` (phase-by-phase
+in subagents), `review` (audit output against the rules), and `structure`
+(reason about layout).
 
-    rate = value / time
+## One-liner: install + build an app
 
-We can improve the rate by either increasing value or decreasing time.
+Paste one of these into a shell, replacing the quoted text with your own app
+description. It installs the bundle, then runs `build-application` headlessly on
+your prompt.
 
-- Quality: Write better applications. ▲value
-- Velocity: Write applications faster. ▼time
+This presumes you are already running the agent within the directory you want to use as your project root.
 
-### Code Priorities
-
-1. Correct: Does the job. This one is non-negotiable.
-2. Clear: Easily understood by both humans and AI.
-3. Changeable: Quickly and safely modified or extended.
-
-There is occasionally some tension between clarity and changeability. More abstraction or generic parameters may make things more changeable at the cost of some clarity.
-
-### Code Challenges
-
-- Complexity: Undermines every single one of our code priorities.
-
-Complexity is the limiting factor which defines the upper limit on how sophisticated of an application we are able to create and maintain at a practical velocity.
-
-The difficulty of dealing with complexity tends to increase at a greater than linear rate, especially once the short term context window of a human or ai agent is exceeded.
-
-### General Principles
-
-- Separation of Concerns: If two concerns can be separated then do it.
-- Avoid mutation: Immutable values are easier to reason about.
-- Use Small files: Aim for less than 200 loc. Decompose if > 500 loc.
-- Single concern per file: Export only a single declaration per file.
-- Avoid object oriented classes: Combines data concerns with functions.
-- Distinguish services from data: Services do things, data stores things.
-- Use static typing: Finds errors earlier and guides both AI and humans.
-- Avoid side effects: Pure functions are easier to comprehend and test.
+```
+Find the @adobe/data-ai package on npmjs and then install it in the current directory.
+Next use it's /build-application skill to build <promt here>
+```

package/bin/cli.mjs

@@ -1,18 +1,21 @@
 #!/usr/bin/env node
-// Installer for the @adobe/data-ai skill bundle (Cursor / Codex / .agents-standard agents).
+// Installer for the @adobe/data-ai bundle (Cursor / Codex / .agents-standard agents).
 //
-// Copies the SKILL.md folders shipped in this package into a single namespaced
-// bundle directory that agents which recurse `.agents/skills/` will discover:
+// Lays down two managed, namespaced directories the agent discovers:
 //
-//   .agents/skills/adobe-data-ai/<name>/SKILL.md
+//   .agents/skills/adobe-data-ai/<name>/SKILL.md   — the build-* skills
+//   .claude/rules/adobe-data-ai/**/*.md            — the architecture rules
 //
-// We own the `adobe-data-ai/` directory outright, so a refresh is a clean
-// wipe-and-recopy — it never touches skills you authored elsewhere.
+// We own both `adobe-data-ai/` directories outright, so a refresh is a clean
+// wipe-and-recopy — it never touches files you authored elsewhere. Re-running
+// the installer is therefore also how you update.
 //
-// Claude Code is intentionally NOT a target: it does not scan `.agents/`, and
-// copying into `.claude/skills/` could collide with a user's own skills.
-// Claude consumes these as the `adobe-data-ai` marketplace plugin instead
-// (see README).
+// Claude Code is intentionally NOT a skills target: it does not scan `.agents/`,
+// and copying into `.claude/skills/` could collide with a user's own skills — it
+// consumes the skills as the `adobe-data-ai` marketplace plugin instead. The
+// rules, however, install into `.claude/rules/adobe-data-ai/` for every agent
+// (Claude auto-injects them by their `paths:` globs; other agents read them by
+// name as their skills run). See README.
 
 import {
     cpSync,
@@ -30,12 +33,39 @@ import { fileURLToPath } from "node:url";
 const here = dirname(fileURLToPath(import.meta.url));
 const pkgRoot = resolve(here, "..");
 const skillsSrc = join(pkgRoot, "skills");
+const rulesSrc = join(pkgRoot, ".claude", "rules");
 const pkg = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf8"));
 const { name: PKG_NAME, version: VERSION } = pkg;
 
-// Namespaced bundle folder — the whole directory belongs to this package.
+// Namespaced bundle folder — the whole directory belongs to this package, under
+// each agent root.
 const BUNDLE = "adobe-data-ai";
 
+// A do-not-edit notice dropped at each bundle root. Claude Code loads nested
+// CLAUDE.md files when working in a subtree, so an agent that opens one of these
+// folders sees the notice before touching anything. `extra` adds a pointer to
+// the companion bundle.
+function notice(extra) {
+    return `# Externally managed — do not edit
+
+The files in this folder are installed and managed by the \`${PKG_NAME}\`
+package. This entire directory is **deleted and rebuilt** on every
+\`npx ${PKG_NAME} install\`, so any local edit here is silently discarded on the
+next reinstall or version upgrade.
+
+To change them, edit upstream in the \`${PKG_NAME}\` package and publish a new
+version, then reinstall — do not modify these files in place.
+${extra ? `\n${extra}\n` : ""}`;
+}
+
+function writeMeta(bundleDir, noticeBody, extraMeta) {
+    writeFileSync(join(bundleDir, "CLAUDE.md"), noticeBody);
+    writeFileSync(
+        join(bundleDir, ".data-ai.json"),
+        JSON.stringify({ package: PKG_NAME, version: VERSION, ...extraMeta }, null, 2) + "\n",
+    );
+}
+
 function discoverSkills() {
     if (!existsSync(skillsSrc)) return [];
     return readdirSync(skillsSrc, { withFileTypes: true })
@@ -44,17 +74,41 @@ function discoverSkills() {
         .sort();
 }
 
-function installTo(bundleDir, skills) {
-    // We own this directory — wipe and recopy for a clean refresh.
+// Recursively count the rule `.md` files, excluding the top-level README.md
+// (rules-authoring meta doc, not a rule — and it carries no `paths:` guard).
+function countRules(dir) {
+    let n = 0;
+    for (const d of readdirSync(dir, { withFileTypes: true })) {
+        if (d.isDirectory()) n += countRules(join(dir, d.name));
+        else if (d.name.endsWith(".md") && !(dir === rulesSrc && d.name === "README.md")) n += 1;
+    }
+    return n;
+}
+
+function installSkills(base, skills) {
+    const bundleDir = join(base, ".agents", "skills", BUNDLE);
     rmSync(bundleDir, { recursive: true, force: true });
     mkdirSync(bundleDir, { recursive: true });
     for (const name of skills) {
         cpSync(join(skillsSrc, name), join(bundleDir, name), { recursive: true });
     }
-    writeFileSync(
-        join(bundleDir, ".data-ai.json"),
-        JSON.stringify({ package: PKG_NAME, version: VERSION, skills }, null, 2) + "\n",
+    writeMeta(
+        bundleDir,
+        notice("The architecture rules these skills follow are installed at\n`.claude/rules/adobe-data-ai/` (referenced by name from each SKILL.md)."),
+        { skills },
     );
+    return bundleDir;
+}
+
+function installRules(base) {
+    const bundleDir = join(base, ".claude", "rules", BUNDLE);
+    rmSync(bundleDir, { recursive: true, force: true });
+    mkdirSync(bundleDir, { recursive: true });
+    // Copy the whole rules tree, minus the top-level README.md meta doc.
+    const readme = join(rulesSrc, "README.md");
+    cpSync(rulesSrc, bundleDir, { recursive: true, filter: (src) => src !== readme });
+    writeMeta(bundleDir, notice(), { rules: countRules(rulesSrc) });
+    return bundleDir;
 }
 
 function parseArgs(argv) {
@@ -72,19 +126,20 @@ function parseArgs(argv) {
 
 const HELP = `${PKG_NAME} v${VERSION}
 
-Install the architecture-skill bundle for Cursor, Codex, and other agents
-that scan .agents/skills/. (Claude Code uses the marketplace plugin instead.)
+Install the architecture skills + rules for Cursor, Codex, and other agents.
+(Claude Code gets the skills from the marketplace plugin; the rules install the
+same way for every agent — see README.)
 
 Usage:
   npx ${PKG_NAME}@latest install [options]
   npx ${PKG_NAME}@latest list
 
 Commands:
-  install   Copy skills into .agents/skills/${BUNDLE}/ (default).
+  install   Skills → .agents/skills/${BUNDLE}/, rules → .claude/rules/${BUNDLE}/ (default).
   list      Print the skills bundled in this package.
 
 Options:
-  --global, -g    Install into your home directory (~/.agents/skills/${BUNDLE}/)
+  --global, -g    Install into your home directory (~/.agents, ~/.claude)
                   instead of the current project.
   --dir=<path>    Base directory to install into (default: cwd).
   --help, -h      Show this help.
@@ -119,13 +174,13 @@ function main() {
     }
 
     const base = flags.has("global") ? homedir() : dir ? resolve(dir) : process.cwd();
-    const bundleDir = join(base, ".agents", "skills", BUNDLE);
-
-    installTo(bundleDir, skills);
+    const skillsDir = installSkills(base, skills);
+    const rulesDir = installRules(base);
+    const ruleCount = countRules(rulesSrc);
 
-    process.stdout.write(`Installed ${skills.length} skill(s) from ${PKG_NAME} v${VERSION}\n`);
-    process.stdout.write(`  ${bundleDir}\n`);
-    process.stdout.write(`Skills: ${skills.join(", ")}\n`);
+    process.stdout.write(`Installed ${PKG_NAME} v${VERSION}\n`);
+    process.stdout.write(`  ${skills.length} skills → ${skillsDir}\n`);
+    process.stdout.write(`  ${ruleCount} rules  → ${rulesDir}\n`);
 }
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-ai",
-  "version": "0.9.83",
+  "version": "0.9.86",
   "description": "Cross-agent architecture skills for @adobe/data — installable as a Claude Code plugin or copied into any Agent-Skills-compatible agent (Cursor, Codex).",
   "type": "module",
   "private": false,
@@ -13,6 +13,7 @@
   },
   "files": [
     "skills",
+    ".claude",
     "bin",
     ".claude-plugin",
     "README.md",
@@ -27,12 +28,18 @@
     "codex",
     "skills"
   ],
+  "peerDependencies": {
+    "@adobe/data": "0.9.86"
+  },
   "devDependencies": {
-    "vitest": "^1.6.0"
+    "typescript": "^5.8.3",
+    "vitest": "^1.6.0",
+    "@adobe/data": "0.9.86"
   },
   "license": "MIT",
   "scripts": {
     "build": "cp ../../LICENSE .",
+    "typecheck": "true",
     "test": "vitest --run --passWithNoTests",
     "publish-public": "pnpm build && pnpm publish --no-git-checks --access public"
   }

package/skills/build-actions/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: build-actions
+description: Build a feature's ecs action-database — async orchestration over services and transactions. If the feature has async flows or side effects outside of the main store.
+input: feature
+output: feature
+---
+
+Skip if this feature doesn't contain or require actions.
+
+Create `ecs/action-database/`: `action-database.ts` (extends `ServiceDatabase`, adds `actions`
+from `./actions/index.js`) plus an `actions/` folder — one async orchestrator per file. An action
+takes `db: ServiceDatabase`, awaits `services/` ports, then commits **exactly one** transaction.
+
+The top ecs layer; comes after `service-database`.
+
+The how is in the auto-loading `features/ecs/actions.md` rule.

package/skills/build-app-entry/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: build-app-entry
+description: Wire built features into a running application — import peer schemas, lazy-load peers, and mount the root UI.
+input: app
+output: app
+---
+
+- The base (`features/main`) core-database `imports` each peer feature's core-database
+  plugin, so all schemas coexist, persist, and sync while the base type stays decoupled.
+- The base reaches a peer only through a lazy element wrapper (dynamic import), so peers
+  load on demand.
+- The entry point creates the live database from `FeatureDatabase.plugin` (the base
+  feature's assembled database — see `features/ecs/index.md`) and mounts the root UI.
+
+See `features/index.md` (one-app-many-features) for the wiring rules.

package/skills/build-application/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: build-application
+description: Build an application — a base feature hosting lazily-loaded peer features.
+input: app
+output: app
+---
+
+/graph-execute
+    /build-feature (base — features/main)
+    for each sub feature
+        /build-feature
+    /build-app-entry

package/skills/build-computed/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: build-computed
+description: Build a feature's ecs computed-database — derived observable values.
+input: feature
+output: feature
+---
+
+Skip if this feature doesn't contain or require computed values.
+
+Create `ecs/computed-database/`: `computed-database.ts` (extends the previous layer, adds
+`computed` from `./computed/index.js`) plus a `computed/` folder — one `cached` derived value
+per file + barrel. Derivation logic lives in `data/`; a computed only wires a db observable to it.
+
+Comes after `transaction-database`.
+
+The how is in the auto-loading `features/ecs/computed.md` rule.

package/skills/build-core-database/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: build-core-database
+description: Build a feature's ecs schema — the core-database (components, resources, archetypes). The first ecs layer.
+input: feature
+output: feature
+---
+
+Create `ecs/core-database/` — `core-database.ts` plus one single-export file per facet
+the feature actually uses (`components`, `resources`, `archetypes` are each optional on
+`Database.Plugin.create`). Create only the facet files you need; omit the rest rather than
+shipping empty `Database.components({})` boilerplate. A feature with **no entities** (a
+singleton whose whole state is resources) is just `resources.ts` + `core-database.ts`.
+
+- `components.ts` → `Database.components({ document, settings, presence, session })` (scopes optional) — only if the feature has entities.
+- `resources.ts` → `Database.resources({ … })` (every entry needs a `default`) — for singleton / global state.
+- `archetypes.ts` → `Database.archetypes(components, { … })` — only alongside components.
+- `core-database.ts` → `Database.Plugin.create({ imports?, components?, resources?, archetypes? })`, exporting the `CoreDatabase` namespace.
+
+The schema root; comes after `data/` (and `services/`). Bind each schema from its `data/`
+type — don't author shapes here. Components use JSON schemas; resources use the
+`{ default }` convention (a schemaless aggregate binds via `{ default: State.create() }`).
+
+The how is in the auto-loading `features/ecs/index.md` + `components.md` / `resources.md` /
+`archetypes.md` rules.

package/skills/build-data/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: build-data
+description: Build a feature's data/ layer — data-type namespaces and the State spec. The first, foundational feature phase.
+input: feature
+output: feature
+---
+
+Create the feature's `data/` layer (pure spec; depends on nothing but `@adobe/data`
+and other `data/` declarations):
+
+- one namespace folder per data type — `<type>/{<type>.ts, schema.ts, public.ts, <helper>.ts}`;
+- `data/state/` — the `State` aggregate plus its pure transforms/derivations.
+
+**Always create `data/state/`** — even for a shell feature whose only field is a
+boolean or enum. A feature with ECS resources/transactions but no `State` is
+incomplete: the transaction must wrap a pure transform, not invent the logic. In rare circumstances, there may be no real state in a feature in which case the state type = {}
+
+The schema is the single source of truth; the type derives from it (`Schema.ToType`).
+Helpers are pure and unit-tested. Run this first — every other layer imports `data/`.
+
+The how is in the auto-loading rules: `features/data/index.md`, `features/data/state.md`, and
+`namespace.md`.

package/skills/build-feature/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: build-feature
+description: Build a complete feature step by step
+input: feature
+output: feature
+---
+
+/graph-execute
+    /build-data
+    /build-services
+    /build-core-database
+    /build-indexes
+    /build-transactions
+    /build-computed
+    /build-service-database
+    /build-actions
+    /build-systems
+    /build-ui

package/skills/build-game/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: build-game
+description: Build a game — an application whose features model game state, rules, and rendering.
+input: game
+output: game
+---
+
+/build-application — a game is an application.
+
+Map game concepts to feature layers: data/ = state + rules (+ per-tick step math),
+components/archetypes = entity kinds, indexes = spatial/lookup queries,
+transactions = moves/spawns, computed = score/status/winner, ui = view + input.
+
+- **Turn-based** uses the reactive transaction → computed → ui loop, no systems
+  (see data-lit-tictactoe).
+- **Real-time** adds the `build-systems` phase: a per-frame tick loop (movement,
+  collision, lifetime) driven by the scheduler, over many entities in distinct
+  archetypes. Systems must stay O(1) per touched entity — never project the whole
+  `State` into/out of the store each frame (see `features/ecs/systems.md`).
+  This is where components, archetypes, indexes, and systems all carry real
+  weight.

package/skills/build-indexes/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: build-indexes
+description: Build a feature's ecs index-database — component/archetype indexes for O(1) lookup. As needed.
+input: feature
+output: feature
+---
+
+Skip if this feature doesn't contain or require indexes.
+
+Create `ecs/index-database/`: `index-database.ts` (extends `CoreDatabase`, adds the `indexes`
+facet from `./indexes/index.js`) plus an `indexes/` folder — one index per file + an `index.ts`
+barrel.
+
+Only if the feature needs indexed lookups. Comes after `core-database`.
+
+The how is in the auto-loading `features/ecs/indexes.md` rule.

package/skills/build-service-database/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: build-service-database
+description: Build a feature's ecs service-database — db-bound service factories. If the feature exposes services.
+input: feature
+output: feature
+---
+
+Create `ecs/service-database/`: `service-database.ts` (extends the previous layer, registers the
+`services` facet). Two forms:
+
+- db-bound factories `create<Name>Service(db, …)` in `service-database/services/` (one per file + barrel), for services that read `db.observe.*` / call `db.transactions.*`; or
+- plain async ports registered straight from the feature's `services/` contracts.
+
+Comes after `computed-database`.
+
+The how is in the auto-loading `features/ecs/services.md` rule.