@adobe/data-ai 0.9.90 → 0.9.91

package/.claude/rules/README.md

@@ -13,6 +13,8 @@ folder's own `index.md` holds just enough to understand that folder; each
 child gets its own file (recursing wherever the source tree does):
 
 ```
+global/               # always-on conventions — deliberately repo-wide globs
+  namespace.md  cohesion.md  type-casts.md  function-references.md  react.md
 features/
   index.md            # the feature layering as a whole (ui → services → data)
   data/
@@ -28,12 +30,15 @@ features/
   ui/index.md         # UI (points to element / presentation / lazy-element file rules)
 ```
 
-Alongside `features/`, the rules-root `.md` files hold the **cross-cutting**
-patterns the feature rules reference — `namespace.md`, `data-modelling.md`,
-`type-casts.md`, `function-references.md`, `cohesion.md`, `archetypes.md` (row
-iteration), `plugin-modelling.md`, and the UI file rules (`element.md`,
-`lazy-element.md`, `presentation.md`). They live here so the bundle is self-contained; this repo
-symlinks them into its own `.claude/rules/` (as it does `features/`).
+The `global/` rules (`namespace.md`, `cohesion.md`, `type-casts.md`,
+`function-references.md`, `react.md`) are **intentionally repo-wide** — their
+`paths:` globs (`**/*.ts` etc.) apply everywhere, by design, so the folder name
+makes that explicit. Alongside `features/`, the remaining rules-root `.md` files
+hold the other **cross-cutting** patterns the feature rules reference —
+`data-modelling.md`, `archetypes.md` (row iteration), `plugin-modelling.md`, and
+the UI file rules (`element.md`, `lazy-element.md`, `presentation.md`). They live
+here so the bundle is self-contained; this repo symlinks them into its own
+`.claude/rules/` (as it does `features/`).
 
 Each rule's `paths:` glob is scoped to `**/features/*/<layer>/…`, so these
 rules apply only once an application opts into the feature-folder pattern

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

@@ -11,7 +11,7 @@ communication over the wire — no functions, no handles, just plain data.
 It depends on nothing but `@adobe/data` and other `data/` declarations, and
 needs no knowledge of anything built on top of it.
 
-Each data type is its own namespace folder (see `namespace.md`), holding
+Each data type is its own namespace folder (see `global/namespace.md`), holding
 its schema, its derived type, and its pure synchronous helpers together:
 
 ```

package/.claude/rules/features/index.md

@@ -106,6 +106,7 @@ current examples of this structure. `data-lit-todo` is the most complete
 See the rules under each folder: `data/`, `services/` — the `main-service/`
 subtree (components, resources, archetypes, computed, indexes, transactions,
 systems, conformance) and capability-contract services — and `ui/`.
-Cross-cutting patterns live at the rules root — `namespace.md`,
-`data-modelling.md`, `archetypes.md` (row iteration), `type-casts.md`,
-`cohesion.md`.
+Always-on conventions live in `global/` (`namespace.md`, `cohesion.md`,
+`type-casts.md`, `function-references.md`, `react.md` — deliberately repo-wide);
+other cross-cutting patterns at the rules root — `data-modelling.md`,
+`archetypes.md` (row iteration).

package/.claude/rules/features/services/index.md

@@ -22,7 +22,7 @@ its own subtree.
 
 ## Capability contracts
 
-Each is a namespace folder (`namespace.md`); the export and folder both carry the
+Each is a namespace folder (`global/namespace.md`); the export and folder both carry the
 `-service` suffix. A service is the boundary between pure feature code and the
 outside world, which is why its members are async — enabling cross-process
 portability and lazy loading (`AsyncDataService.createLazy`).

package/.claude/rules/features/services/main-service/systems.md

@@ -32,6 +32,8 @@ import { Database, scheduler } from "@adobe/data/ecs";
 import { Motion } from "../../data/motion/motion.js";
 
 const plugin = Database.Plugin.create({
+    // combine scheduler with the CURRENT TOP layer — ComputedDatabase here, but
+    // ActionDatabase / ServiceDatabase if the feature built those (systems come last).
     extends: Database.Plugin.combine(ComputedDatabase.plugin, scheduler),
     systems: {
         control: { create: (db) => () => { /* input → ship; db.transactions.fireBullet() */ } },
@@ -119,8 +121,10 @@ with no rAF and no rendering attached.
 
 ## Layer
 
-`system-database.ts` extends the previous main-service layer (usually `ComputedDatabase`),
-combined with `scheduler`, and declares the `systems` map **inline** (see above —
+`system-database.ts` extends the feature's **current top** main-service layer (`ActionDatabase` /
+`ServiceDatabase` / `ComputedDatabase` — whichever it built; systems come last in the pipeline, so
+they must sit atop any service/action layers, not a hardcoded `ComputedDatabase`), combined with
+`scheduler`, and declares the `systems` map **inline** (see above —
 this is the one facet not split one-per-file, because `create`'s `db` is only typed
 inline and standalone declarations break name inference). A `systems/` folder is
 optional: it holds extracted per-frame body helpers (`(db) => () => void`) only when

package/.claude/rules/features/services/main-service/transactions.md

@@ -41,5 +41,5 @@ export const playMove = (t: CoreDatabase.Store, { index }: PlayMoveArgs) => {
   transactions (`readShip`, `readBoard` — a `(t) => value` function) may live
   beside them in `transactions/`, but keep it **out of the barrel**, or it gets
   registered as a dispatchable transaction. (These are related helpers, so they
-  belong here, not in a separate folder — `cohesion.md`'s peer-level caution
+  belong here, not in a separate folder — `global/cohesion.md`'s peer-level caution
   doesn't apply.)

package/.claude/rules/features/ui/binding-element.md

@@ -32,7 +32,7 @@ Presentation files (`*-presentation.ts`), CSS files (`*.css.ts`), tests (`*.test
 A binding element is a thin wire between a service and a presentation. The class body contains:
 
 1. Optional static `styles` property definition
-2. Zero or more `@property` declarations (whitelisted below).
+2. Zero or more `@property` declarations (allowed below).
 3. One `render()` method whose body is: one `useObservableValues(...)` call, another lifecycle hook call (in rare cases), a null-guard, and
    `return presentation.render({ ...values, ...callbacks })`.
 
@@ -40,7 +40,7 @@ No other members. No `@state`. No private handler fields. No lifecycle methods (
 `disconnectedCallback`) except on app-entrypoint classes where the lifecycle concern is app-boot shaped but cannot be expressed as a hook
 (see `.claude/rules/hooks.md` for hook-first lifecycle).
 
-## `@property` whitelist
+## `@property` allowlist
 
 The allowed set depends on **class role**:
 

package/.claude-plugin/plugin.json

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

package/README.md

@@ -2,7 +2,7 @@
 
 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
+spec-first feature structure (`data → services → ui`) kept honest by conformance
 tests. Versioned in lockstep with the library: `@adobe/data-ai@x.y.z` targets
 `@adobe/data@x.y.z`.
 

package/bin/cli.mjs

@@ -50,8 +50,8 @@ function notice(extra) {
 
 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.
+\`npx ${PKG_NAME}@${VERSION} 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.
@@ -66,10 +66,21 @@ function writeMeta(bundleDir, noticeBody, extraMeta) {
     );
 }
 
+// Skills that author/evolve the bundle itself (the self-improvement loop and its
+// rule review). They mutate or critique the managed files, so they belong only to
+// the source repo — never a consumer install, where those files are read-only
+// managed copies. Both also carry `disable-model-invocation: true`.
+const MAINTAINER_ONLY = new Set(["meta-build", "review"]);
+
 function discoverSkills() {
     if (!existsSync(skillsSrc)) return [];
     return readdirSync(skillsSrc, { withFileTypes: true })
-        .filter((d) => d.isDirectory() && existsSync(join(skillsSrc, d.name, "SKILL.md")))
+        .filter(
+            (d) =>
+                d.isDirectory() &&
+                !MAINTAINER_ONLY.has(d.name) &&
+                existsSync(join(skillsSrc, d.name, "SKILL.md")),
+        )
         .map((d) => d.name)
         .sort();
 }
@@ -111,6 +122,41 @@ function installRules(base) {
     return bundleDir;
 }
 
+// A single managed rule (namespaced by its `adobe-data-ai-` filename prefix) telling
+// an agent to (re)install the bundle when the skills are absent — pinned to THIS
+// reviewed version, never `@latest`, so a drifted or compromised release cannot execute
+// during install. Rewritten with the matching version on every install. It sits beside
+// (not inside) the wiped bundle dir, so it survives and is simply overwritten.
+function installBootstrap(base) {
+    const file = join(base, ".claude", "rules", `${BUNDLE}-bootstrap.md`);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(
+        file,
+        `---
+paths:
+  - '**/features/*/data/**/*.ts'
+  - '**/features/*/services/**/*.ts'
+  - '**/features/*/ui/**/*.ts'
+---
+
+# ${PKG_NAME} skills — ensure installed
+
+Before using an \`@adobe/data\` build workflow, confirm the skills are present: look for
+a skill named \`build-feature\` (or \`build-application\`). If it is missing, install the
+pinned, reviewed bundle, then re-check:
+
+\`\`\`sh
+npx ${PKG_NAME}@${VERSION} install
+\`\`\`
+
+Pin the version to the reviewed bundle (never \`@latest\`) so a compromised or drifted
+release cannot execute during install. This file is regenerated with the matching
+version on every install. Package: <https://www.npmjs.com/package/${PKG_NAME}>
+`,
+    );
+    return file;
+}
+
 function parseArgs(argv) {
     const positional = [];
     const flags = new Set();
@@ -176,11 +222,13 @@ function main() {
     const base = flags.has("global") ? homedir() : dir ? resolve(dir) : process.cwd();
     const skillsDir = installSkills(base, skills);
     const rulesDir = installRules(base);
+    const bootstrapFile = installBootstrap(base);
     const ruleCount = countRules(rulesSrc);
 
     process.stdout.write(`Installed ${PKG_NAME} v${VERSION}\n`);
     process.stdout.write(`  ${skills.length} skills → ${skillsDir}\n`);
     process.stdout.write(`  ${ruleCount} rules  → ${rulesDir}\n`);
+    process.stdout.write(`  bootstrap → ${bootstrapFile}\n`);
 }
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-ai",
-  "version": "0.9.90",
+  "version": "0.9.91",
   "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.90"
+    "@adobe/data": "0.9.91"
   },
   "devDependencies": {
     "typescript": "^5.8.3",
     "vitest": "^1.6.0",
-    "@adobe/data": "0.9.90"
+    "@adobe/data": "0.9.91"
   },
   "license": "MIT",
   "scripts": {

package/skills/build-data/SKILL.md

@@ -19,4 +19,4 @@ The schema is the single source of truth; the type derives from it (`Schema.ToTy
 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`.
+`global/namespace.md`.

package/skills/build-services/SKILL.md

@@ -13,4 +13,4 @@ and `create*` factories.
 
 Only if the feature talks to the outside world. Comes after `data/`, before `services/main-service/`.
 
-The how is in the auto-loading `features/services/index.md` rule (and `namespace.md`).
+The how is in the auto-loading `features/services/index.md` rule (and `global/namespace.md`).

package/skills/build-systems/SKILL.md

@@ -9,7 +9,10 @@ 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 `services/main-service/system-database/system-database.ts`: `Database.Plugin.create({ extends:
-Database.Plugin.combine(ComputedDatabase.plugin, scheduler), systems })` where the `systems`
+Database.Plugin.combine(<currentTop>.plugin, scheduler), systems })` — combine `scheduler` with the
+feature's **current top** main-service layer (`ActionDatabase` / `ServiceDatabase` / `ComputedDatabase`,
+whichever it built), never a hardcoded `ComputedDatabase`, so systems *and* any services/actions
+compose into the one `FeatureDatabase`. The `systems`
 map is declared **inline** (see `features/services/main-service/systems.md` — inline is required for `db` to be
 typed and for system-name inference; a `systems/` folder is optional, only for extracted
 per-frame body helpers).

package/skills/build-transactions/SKILL.md

@@ -5,7 +5,8 @@ input: feature
 output: feature
 ---
 
-Create `services/main-service/transaction-database/`: `transaction-database.ts` (extends `IndexDatabase`, adds
+Create `services/main-service/transaction-database/`: `transaction-database.ts` (extends the
+preceding layer — `IndexDatabase` if the feature built indexes, else `CoreDatabase` — adds
 `transactions` from `./transactions/index.js`) plus a `transactions/` folder — one mutation per
 file + barrel. Type the store param `CoreDatabase.Store` (entities/resources/archetypes) or
 `IndexDatabase.Store` (reads an index).

package/skills/meta-build/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: meta-build
+disable-model-invocation: true
 description: Iteratively build an application or game phase-by-phase in clean subagents, reviewing each phase and refining the build-* skills / rules until each is optimal, then summarizing.
 input: a prompt describing the application or game to build
 options:

package/skills/review/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: review
+disable-model-invocation: true
 description: Review built feature/application output against the @adobe/data feature rules; report whether it is optimal and where any fix belongs. Read-only.
 input: a path to built output (a layer, a feature, or a whole app)
 output: a review — OPTIMAL, or a list of issues each tagged code | skill | rule