@adobe/data-ai 0.9.84 → 0.9.86

package/.claude/rules/features/data/state.md

@@ -10,6 +10,8 @@ pure, fully-tested source of truth for the feature. Modelling everything as
 a single value keeps each transform a small, trivially-testable function of
 state: collections of entity sub-types plus scalar fields.
 
+Every feature that has ECS resources or transactions owns a `State` — including
+a host whose aggregate is a single scalar (`{ playing: boolean }`) or even when there is no state in which case use `{}`. 
 ```ts
 // state.ts — the aggregate, plus the namespace of transforms/derivations.
 export type State = {

package/.claude/rules/features/ecs/conformance.md

@@ -8,9 +8,11 @@ paths:
 The bridge that keeps the ecs implementation honest against the `data/` spec.
 **Test-only**: imported solely by `*.test.ts` and in no facet barrel, so it never
 enters the runtime bundle (test-support may import the test framework — it is not
-a runtime declaration). **Feature-level**: one projection per feature, reused by
-every transaction test and the system tick-loop test — don't nest it under
-`transaction-database/`.
+a runtime declaration). **Never call `fromState` / `toState` (or a shared
+clear-all + reinsert helper used only for that projection) from systems,
+transactions, or UI** — that is a full-store rewrite, not an O(1) ECS update.
+**Feature-level**: one projection per feature, reused by every transaction test
+and the system tick-loop test — don't nest it under `transaction-database/`.
 
 The property, per `{ before, args, after }` case:
 `toState(apply(fromState(before), args)) ≡ spec(before, args)`.

package/.claude/rules/features/ecs/systems.md

@@ -63,9 +63,8 @@ const plugin = Database.Plugin.create({
   HUD) are notified. Reserve direct `db.store` writes for the hot per-row paths
   (movement, aging) that run on every entity every frame and shouldn't pay
   per-entity transaction overhead.
-- **The step math lives in `data/`.** A system is the ecs wiring: it reads store
-  rows, calls a pure `data/` step/derive function, writes the result back — same
-  spec↔implementation discipline as transactions. No physics/game math inline.
+- **Optimize for execution speed in systems** if there are multiple items, then make sure we are using efficient store queries and reading/writing minimal data columns. If this is not hot path, then the simplified data functions can be used, but in hot paths we only consider data functions to be specification. (ie: only use them if it's clearly not a hot path or you cannot write anything more performant by directly using ecs store) 
+- **The step math may live in `data/`.** but only for non-hot path
 - **Iterate archetypes per `archetypes.md`.** Express selection with
   `queryArchetypes(include, { exclude })`; when a system destroys/migrates rows
   (bullets expiring, entities dying) iterate **tail → head** so hole-fills don't
@@ -96,8 +95,8 @@ const plugin = Database.Plugin.create({
 - Games or simulations with immediate mode rendering may want to store a session
   resource of the canvas and render to it within a system. @adobe/data-gpu provides
   example patterns for doing this.
-- All or simulation systems should be optimized for performance.
-  Avoid allocatin intermediate objects if possible, read directly from store.
+- All simulation systems should be optimized for performance.
+  Avoid allocating intermediate objects if possible; read/write columns directly if hot-path. You can use transactions if needed, for instance if we are writing non hot path things which we have other things observing. (Only transactions are observable, not direct writes)
 
 ## Driving the loop — the scheduler
 

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adobe-data-ai",
-  "version": "0.9.84",
+  "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

@@ -18,15 +18,22 @@ It installs two things:
 
 ## Install — Claude Code
 
-Skills load as a marketplace plugin; rules install into the project.
+Skills load as a marketplace plugin; rules install into the project. Run these
+three from a shell (agent-runnable):
 
 ```
-/plugin marketplace add adobe/data
-/plugin install adobe-data-ai@adobe-data-skills
+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
 ```
 
-- Skills → the `adobe-data-ai` plugin. **Update:** `/plugin` → update `adobe-data-ai`.
+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).
+
+- 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 — Cursor (and Codex / other `.agents` agents)
@@ -58,3 +65,16 @@ by name when you want a single phase or a specialized flow: `build-data`,
 `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).
+
+## One-liner: install + build an app
+
+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.
+
+This presumes you are already running the agent within the directory you want to use as your project root.
+
+```
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-ai",
-  "version": "0.9.84",
+  "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,
@@ -29,12 +29,12 @@
     "skills"
   ],
   "peerDependencies": {
-    "@adobe/data": "0.9.84"
+    "@adobe/data": "0.9.86"
   },
   "devDependencies": {
     "typescript": "^5.8.3",
     "vitest": "^1.6.0",
-    "@adobe/data": "0.9.84"
+    "@adobe/data": "0.9.86"
   },
   "license": "MIT",
   "scripts": {

package/skills/build-actions/SKILL.md

@@ -1,10 +1,12 @@
 ---
 name: build-actions
-description: Build a feature's ecs action-database — async orchestration over services and transactions. If the feature has async flows.
+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.

package/skills/build-application/SKILL.md

@@ -5,6 +5,8 @@ input: app
 output: app
 ---
 
-/build-feature (base — features/main)
-|> /build-feature (each peer feature)
-|> /build-app-entry
+/graph-execute
+    /build-feature (base — features/main)
+    for each sub feature
+        /build-feature
+    /build-app-entry

package/skills/build-computed/SKILL.md

@@ -5,6 +5,8 @@ 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.

package/skills/build-data/SKILL.md

@@ -11,6 +11,10 @@ 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/`.
 

package/skills/build-feature/SKILL.md

@@ -1,21 +1,18 @@
 ---
 name: build-feature
-description: Build a complete feature by piping the per-layer build-* skills bottom-up.
+description: Build a complete feature step by step
 input: feature
 output: feature
 ---
 
-/build-data
-|> /build-services
-|> /build-core-database
-|> /build-indexes
-|> /build-transactions
-|> /build-computed
-|> /build-systems
-|> /build-service-database
-|> /build-actions
-|> /build-ui
-
-Run with /x-execute. Each step is a no-op for a layer the feature doesn't use
-(`build-systems` only for real-time features; `build-services` / `build-service-database` /
-`build-actions` only when the feature has async flows).
+/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

@@ -15,5 +15,7 @@ transactions = moves/spawns, computed = score/status/winner, ui = view + input.
   (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. This is where components, archetypes, indexes, and systems all
-  carry real weight — see `features/ecs/systems.md`.
+  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

@@ -5,6 +5,8 @@ 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.

package/skills/build-services/SKILL.md

@@ -5,6 +5,8 @@ input: feature
 output: feature
 ---
 
+Skip if this feature doesn't contain or require services.
+
 Create the feature's `services/` layer: one `<name>-service/` namespace folder per async
 contract — an `interface` (validated with `AsyncDataService.IsValid`), async-only members,
 and `create*` factories.

package/skills/build-systems/SKILL.md

@@ -5,6 +5,9 @@ input: feature
 output: feature
 ---
 
+Skip if this feature doesn't contain or require systems.
+Most games that use a canvas will use systems but most applications will not.
+
 Create `ecs/system-database/system-database.ts`: `Database.Plugin.create({ extends:
 Database.Plugin.combine(ComputedDatabase.plugin, scheduler), systems })` where the `systems`
 map is declared **inline** (see `features/ecs/systems.md` — inline is required for `db` to be
@@ -14,9 +17,6 @@ per-frame body helpers).
 - A system is a `SystemDeclaration`: `{ create, schedule?: { before?, after?, during? } }`.
   `create(db)` runs once (capture queries / index handles / closures); the returned function
   advances the world one tick. Return `void` for an init-only system (seeding entities).
-- The step math lives in `data/`; each system reads store rows, calls the pure `data/` step,
-  writes back — via `db.store` (writable) for hot per-row work, or `db.transactions.*` for
-  discrete events. Iterate archetypes per `archetypes.md` (tail→head when destroying rows).
 - Order under `schedule` (mirror the `data/` step's internal sequence); drive the loop by
   combining `scheduler` (rAF), gated by the `schedulerState` resource.
 

package/skills/graph-execute/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: graph-execute
+description: executes a graph of steps
+input: piped function calls
+---
+
+The input is a set of piped function calls where each call is represented by a slash skill invocation.
+
+Each step must be completed independently before moving on to the next.
+
+The output of each phase is generally either a returned result or written to the file system. You can pass some context including any previous result to the next phase, but you must never read the subsequent phases in advance.
+
+Call each of these phases in a subagent so that they are not even aware that future phases will take place.