feat: layered database structure and AI guidance skills

.agents/skills/adobe-data-ai/.data-ai.json

@@ -0,0 +1,32 @@
+{
+  "package": "@adobe/data-ai",
+  "version": "0.9.84",
+  "skills": [
+    "build-actions",
+    "build-app-entry",
+    "build-application",
+    "build-computed",
+    "build-core-database",
+    "build-data",
+    "build-feature",
+    "build-game",
+    "build-indexes",
+    "build-service-database",
+    "build-services",
+    "build-systems",
+    "build-transactions",
+    "build-ui",
+    "meta-build",
+    "review",
+    "structure",
+    "x-alpha",
+    "x-beta",
+    "x-double",
+    "x-execute",
+    "x-log",
+    "x-pow",
+    "x-subagent",
+    "x-trace",
+    "x-validate"
+  ]
+}

.agents/skills/adobe-data-ai/CLAUDE.md

@@ -0,0 +1,9 @@
+# Externally managed — do not edit
+
+The skills in this folder are installed and managed by the `@adobe/data-ai`
+package. This entire directory is **deleted and rebuilt** on every
+`npx @adobe/data-ai install`, so any local edit here is silently discarded
+on the next reinstall or version upgrade.
+
+To change a skill, edit it upstream in the `@adobe/data-ai` package and
+publish a new version, then reinstall — do not modify these files in place.

.agents/skills/adobe-data-ai/build-actions/SKILL.md

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

.agents/skills/adobe-data-ai/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.

.agents/skills/adobe-data-ai/build-application/SKILL.md

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

.agents/skills/adobe-data-ai/build-computed/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: build-computed
+description: Build a feature's ecs computed-database — derived observable values.
+input: feature
+output: feature
+---
+
+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.

.agents/skills/adobe-data-ai/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.

.agents/skills/adobe-data-ai/build-data/SKILL.md

@@ -0,0 +1,18 @@
+---
+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.
+
+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`, `data/state.md`, and
+`namespace.md`.

.agents/skills/adobe-data-ai/build-feature/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: build-feature
+description: Build a complete feature by piping the per-layer build-* skills bottom-up.
+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).

.agents/skills/adobe-data-ai/build-game/SKILL.md

@@ -0,0 +1,19 @@
+---
+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. This is where components, archetypes, indexes, and systems all
+  carry real weight — see `features/ecs/systems.md`.

.agents/skills/adobe-data-ai/build-indexes/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: build-indexes
+description: Build a feature's ecs index-database — component/archetype indexes for O(1) lookup. As needed.
+input: feature
+output: feature
+---
+
+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.

.agents/skills/adobe-data-ai/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.

.agents/skills/adobe-data-ai/build-services/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: build-services
+description: Build a feature's services/ layer — async capability contracts (ports to the outside world). Optional.
+input: feature
+output: feature
+---
+
+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.
+
+Only if the feature talks to the outside world. Comes after `data/`, before `ecs/`.
+
+The how is in the auto-loading `features/services/index.md` rule (and `namespace.md`).

.agents/skills/adobe-data-ai/build-systems/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: build-systems
+description: Build a feature's ecs system-database — the real-time tick loop (systems the scheduler runs each frame). For real-time features only.
+input: feature
+output: feature
+---
+
+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
+typed and for system-name inference; a `systems/` folder is optional, only for extracted
+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.
+
+**Only for real-time features** (games, sims) — turn-based features skip this phase entirely.
+Comes after `build-computed`. The how is in the auto-loading `features/ecs/systems.md` rule.

.agents/skills/adobe-data-ai/build-transactions/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: build-transactions
+description: Build a feature's ecs transaction-database — atomic mutations over the store.
+input: feature
+output: feature
+---
+
+Create `ecs/transaction-database/`: `transaction-database.ts` (extends `IndexDatabase`, 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).
+
+Comes after `index-database` (or `core-database` if no indexes).
+
+The how is in the auto-loading `features/ecs/transactions.md` rule.

.agents/skills/adobe-data-ai/build-ui/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: build-ui
+description: Build a feature's ui/ layer — presentation bound to the ecs database. The final, top layer.
+input: feature
+output: feature
+---
+
+Create `ui/`: one folder per UI unit —
+`<name>/{<name>.ts (lazy wrapper), <name>-element.ts (container), <name>-presentation.ts (pure render), <name>.css.ts}`.
+The element subscribes to state and delegates to the pure presentation; no business logic here.
+
+Comes last. The how is in the auto-loading `features/ui/index.md` rule (and `element.md`,
+`lazy-element.md`, `presentation.md`).

.agents/skills/adobe-data-ai/meta-build/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: meta-build
+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:
+    target = build-application   # build command to exercise: build-application | build-game | build-feature | a single build-<phase>
+    maxIterations = 4            # attempts per phase before moving on
+---
+
+Purpose: exercise and **polish the build-* skills and the rules they reference**, using
+a concrete app/game prompt as the test case. You are improving the *general* guidance,
+not the one-off output.
+
+## Procedure
+
+1. Resolve `target` to its **ordered phases**. A composite target expands to its pipe —
+   `build-feature` → its `/build-*` layer steps; `build-application` / `build-game` →
+   `build-feature` for the base and each peer, then `build-app-entry`. A single
+   `build-<phase>` target is just that one phase.
+
+2. For each phase, in order:
+   a. **Run it in a fresh subagent** with constrained context (`/x-subagent`): give the
+      subagent only the phase skill (`/<phase>`), the app/game prompt, and the files on
+      disk from prior phases — nothing about this loop or earlier attempts, so every
+      re-run differs only by any edits you made to the guidance.
+   b. **Review** the phase output in a subagent with `/review`.
+   c. If `/review` is not OPTIMAL: fix the **root cause in the guidance** — edit the
+      phase skill or a rule it references. Keep every edit **concise and general**:
+      improve it for all apps, never encode anything specific to this prompt. (For a
+      pure `code` slip with sound guidance, just re-run.) Do **not** hand-patch the
+      generated code.
+   d. Re-run from (a), up to `maxIterations` (default 4) attempts. Move to the next
+      phase once it reviews OPTIMAL — or the cap is hit (record that it did not converge).
+   e. Record: the phase, its iteration count, and every skill/rule file you edited.
+
+3. **Final review** (read-only): run `/review` over the whole product. **Change nothing.**
+   Then summarize:
+   - per-phase iteration counts,
+   - which phase skills and which rules were edited, and why,
+   - overall outcome (which phases converged, which hit the cap).
+
+Every phase runs in its own constrained subagent so re-executions during polishing stay
+consistent — the edited skill/rule is the only variable between a phase's attempts.

.agents/skills/adobe-data-ai/review/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: review
+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
+---
+
+Read the files under the given path and assess them against the relevant `features/`
+rules (each layer's rule and the cross-cutting rules — `namespace`, `data-modelling`,
+`type-casts`, `cohesion`, …):
+
+- **Correctness** — does it typecheck and follow the layer's required shape?
+- **Adherence** — single public export per file, naming, the scope helpers
+  (`Database.components` / `resources` / `archetypes`), `satisfies` targets, barrels,
+  store-layer typing, etc.
+- **Generality** — no leaked type identities; follows the cross-cutting patterns.
+
+Report either **OPTIMAL**, or a short list of issues. Tag each issue with where the
+root-cause fix belongs:
+
+- `code` — a one-off slip in the generated files (guidance is fine),
+- `skill` — the phase skill's instructions are unclear, wrong, or incomplete,
+- `rule` — a referenced rule is unclear, wrong, or missing guidance.
+
+Do not edit anything — assessment only.

.agents/skills/adobe-data-ai/structure/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: structure
+description: Use when laying out or reasoning about a feature's file/folder structure and layer dependencies.
+---
+
+See `features/index.md` (and the per-folder `features/` rules) for how features are
+structured and layered.

.agents/skills/adobe-data-ai/x-alpha/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: x-alpha
+input: void
+output: string
+---
+
+return "alpha";

.agents/skills/adobe-data-ai/x-beta/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: x-beta
+input: void
+output: string
+---
+
+return "beta";

.agents/skills/adobe-data-ai/x-double/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: x-double
+input: number
+output: number
+---
+
+return input * 2