Skip to content

Commit bf1d078

Browse files
KyleAMathewsclaudeautofix-ci[bot]
authored
feat: add Intent agent skills for TanStack DB (#1330)
* feat: add Intent agent skills for TanStack DB Scaffold 12 SKILL.md files across 7 packages to guide AI coding agents. Covers core DB concepts (collections, queries, mutations, custom adapters), 5 framework bindings (React, Vue, Svelte, Solid, Angular), meta-framework integration (Start, Next, Remix, Nuxt, SvelteKit), and offline transactions. Includes 9 reference files for adapter details, operators, and transaction API. Updates package.json files arrays to publish skills with packages. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: apply code review and simplification fixes to skills - Fix incorrect offline transaction API usage (tx.mutate pattern) - Remove phantom ne operator, document not(eq(...)) pattern - Fix Vue template variable reference (data → todos) - Add export * from @tanstack/db to angular-db source - Remove nonexistent math functions from skill_tree.yaml - Remove no-op !skills/_artifacts exclusion from db/package.json - Add isIdle/isCleanedUp to Angular and React SKILL.md - Document deprecated query.data in Solid SKILL.md - Promote Svelte deps mistake severity to CRITICAL Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * chore: add changeset for intent agent skills Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * ci: apply automated fixes * docs: apply feedback from issues #1333 and #1332 - Document schema-vs-parser dual path for Electric collections - Add Postgres-to-Electric type mapping table - Add TanStack Start createServerFn example for write path - Document z.coerce.date() as Zod-specific simpler alternative - Add duplicate @tanstack/db instance guidance with Vite alias fix - Fix Nuxt template variable reference (data → todos) - Update Electric complete example with schema-first + parser Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: add Electric client skills reference to electric-adapter Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * ci: apply automated fixes * docs: remove redundant sections from meta-framework skill The TanStack Start server functions section duplicates what's already in electric-adapter.md. The duplicate @tanstack/db instances section isn't meta-framework specific. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: apply feedback from issues #1334, #1335, #1336 - Add duplicate @tanstack/db troubleshooting to react-db skill (pnpm ls diagnostic, pnpm overrides fix, Vite alias fix) - Reframe localOnlyCollectionOptions: use specified backend directly, only fall back to local-only when no backend exists - Add schema to Electric example in collection-setup (without schema, collection types as Record<string, unknown>) - Add server-side integration pointer to meta-framework skill - Add Electric proxy route pattern to electric-adapter reference Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * ci: apply automated fixes --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
1 parent 495839d commit bf1d078

File tree

34 files changed

+6417
-7
lines changed

34 files changed

+6417
-7
lines changed

‎.changeset/add-intent-agent-skills.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
'@tanstack/angular-db': patch
3+
'@tanstack/db': patch
4+
'@tanstack/react-db': patch
5+
'@tanstack/vue-db': patch
6+
'@tanstack/svelte-db': patch
7+
'@tanstack/solid-db': patch
8+
'@tanstack/offline-transactions': patch
9+
---
10+
11+
Add Intent agent skills (SKILL.md files) to guide AI coding agents. Include skills for core DB concepts, all 5 framework bindings, meta-framework integration, and offline transactions. Also add `export * from '@tanstack/db'` to angular-db for consistency with other framework packages.

‎_artifacts/skill_tree.yaml‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
# _artifacts/skill_tree.yaml
2+
library:
3+
name: '@tanstack/db'
4+
version: '0.5.30'
5+
repository: 'https://github.com/TanStack/db'
6+
description: 'Reactive client store with normalized collections, sub-millisecond live queries, and instant optimistic mutations'
7+
generated_from:
8+
domain_map: 'domain_map.yaml'
9+
skill_spec: 'skill_spec.md'
10+
generated_at: '2026-03-04'
11+
12+
skills:
13+
# ─── Core overview (entry point) ───
14+
- name: 'db-core'
15+
slug: 'db-core'
16+
type: 'core'
17+
domain: 'collection-setup'
18+
path: 'skills/db-core/SKILL.md'
19+
package: 'packages/db'
20+
description: >
21+
TanStack DB core concepts: createCollection, live queries via query builder,
22+
optimistic mutations with draft proxy, transaction lifecycle. Entry point
23+
for all TanStack DB skills with sub-skill routing table.
24+
sources:
25+
- 'TanStack/db:docs/overview.md'
26+
- 'TanStack/db:packages/db/src/index.ts'
27+
28+
# ─── Core sub-skills ───
29+
- name: 'Collection Setup'
30+
slug: 'db-core/collection-setup'
31+
type: 'sub-skill'
32+
domain: 'collection-setup'
33+
path: 'skills/db-core/collection-setup/SKILL.md'
34+
package: 'packages/db'
35+
description: >
36+
Creating typed collections with createCollection, queryCollectionOptions,
37+
electricCollectionOptions, powerSyncCollectionOptions, rxdbCollectionOptions,
38+
trailbaseCollectionOptions, localOnlyCollectionOptions, localStorageCollectionOptions.
39+
CollectionConfig (getKey, schema, sync, gcTime, autoIndex, syncMode).
40+
StandardSchema validation with Zod/Valibot/ArkType. Collection lifecycle
41+
(idle/loading/ready/error/cleaned-up). Adapter-specific sync patterns.
42+
requires:
43+
- 'db-core'
44+
sources:
45+
- 'TanStack/db:docs/overview.md'
46+
- 'TanStack/db:docs/guides/schemas.md'
47+
- 'TanStack/db:docs/collections/query-collection.md'
48+
- 'TanStack/db:docs/collections/electric-collection.md'
49+
- 'TanStack/db:docs/collections/powersync-collection.md'
50+
- 'TanStack/db:docs/collections/rxdb-collection.md'
51+
- 'TanStack/db:docs/collections/trailbase-collection.md'
52+
- 'TanStack/db:docs/collections/local-only-collection.md'
53+
- 'TanStack/db:docs/collections/local-storage-collection.md'
54+
- 'TanStack/db:packages/db/src/collection/index.ts'
55+
subsystems:
56+
- 'TanStack Query adapter'
57+
- 'ElectricSQL adapter'
58+
- 'PowerSync adapter'
59+
- 'RxDB adapter'
60+
- 'TrailBase adapter'
61+
- 'Local-only'
62+
- 'localStorage'
63+
references:
64+
- 'references/query-adapter.md'
65+
- 'references/electric-adapter.md'
66+
- 'references/powersync-adapter.md'
67+
- 'references/rxdb-adapter.md'
68+
- 'references/trailbase-adapter.md'
69+
- 'references/local-adapters.md'
70+
- 'references/schema-patterns.md'
71+
72+
- name: 'Live Queries'
73+
slug: 'db-core/live-queries'
74+
type: 'sub-skill'
75+
domain: 'live-queries'
76+
path: 'skills/db-core/live-queries/SKILL.md'
77+
package: 'packages/db'
78+
description: >
79+
Query builder fluent API: from, where, join, leftJoin, rightJoin, innerJoin,
80+
fullJoin, select, fn.select, groupBy, having, orderBy, limit, offset, distinct,
81+
findOne. Operators: eq, gt, gte, lt, lte, like, ilike, inArray, isNull,
82+
isUndefined, and, or, not. Aggregates: count, sum, avg, min, max. String
83+
functions: upper, lower, length, concat, coalesce. Math: add.
84+
$selected namespace. createLiveQueryCollection for
85+
standalone queries. Derived collections. Predicate push-down. IVM via
86+
differential dataflow (d2ts).
87+
requires:
88+
- 'db-core'
89+
sources:
90+
- 'TanStack/db:docs/guides/live-queries.md'
91+
- 'TanStack/db:packages/db/src/query/builder/index.ts'
92+
- 'TanStack/db:packages/db/src/query/compiler/index.ts'
93+
- 'TanStack/db:packages/db-ivm/src/index.ts'
94+
references:
95+
- 'references/operators.md'
96+
97+
- name: 'Mutations & Optimistic State'
98+
slug: 'db-core/mutations-optimistic'
99+
type: 'sub-skill'
100+
domain: 'mutations-optimistic'
101+
path: 'skills/db-core/mutations-optimistic/SKILL.md'
102+
package: 'packages/db'
103+
description: >
104+
collection.insert, collection.update (Immer-style draft proxy),
105+
collection.delete. createOptimisticAction (onMutate + mutationFn).
106+
createPacedMutations with debounceStrategy, throttleStrategy, queueStrategy.
107+
createTransaction, getActiveTransaction, ambient transaction context.
108+
Transaction lifecycle (pending/persisting/completed/failed). Mutation merging
109+
(insert+update→insert, insert+delete→cancel). onInsert/onUpdate/onDelete
110+
handlers. PendingMutation (original, modified, changes, globalKey).
111+
Transaction.isPersisted promise. TanStack Pacer integration.
112+
requires:
113+
- 'db-core'
114+
sources:
115+
- 'TanStack/db:docs/guides/mutations.md'
116+
- 'TanStack/db:packages/db/src/transactions.ts'
117+
- 'TanStack/db:packages/db/src/optimistic-action.ts'
118+
- 'TanStack/db:packages/db/src/paced-mutations.ts'
119+
- 'TanStack/db:packages/db/src/collection/mutations.ts'
120+
references:
121+
- 'references/transaction-api.md'
122+
123+
- name: 'Custom Adapter Authoring'
124+
slug: 'db-core/custom-adapter'
125+
type: 'sub-skill'
126+
domain: 'custom-adapter'
127+
path: 'skills/db-core/custom-adapter/SKILL.md'
128+
package: 'packages/db'
129+
description: >
130+
Building custom collection adapters. SyncConfig interface: sync function
131+
receiving begin, write, commit, markReady, truncate primitives. ChangeMessage
132+
format. loadSubset for on-demand sync. LoadSubsetOptions (where, orderBy,
133+
limit, cursor). Expression parsing: parseWhereExpression,
134+
parseOrderByExpression, extractSimpleComparisons, parseLoadSubsetOptions.
135+
Collection options creator pattern. Subscription lifecycle and cleanup.
136+
requires:
137+
- 'db-core'
138+
- 'db-core/collection-setup'
139+
sources:
140+
- 'TanStack/db:docs/guides/collection-options-creator.md'
141+
- 'TanStack/db:packages/db/src/collection/sync.ts'
142+
- 'TanStack/db:packages/db/src/query/ir.ts'
143+
144+
# ─── Framework skills (one per adapter package) ───
145+
- name: 'React DB'
146+
slug: 'react-db'
147+
type: 'framework'
148+
domain: 'framework-integration'
149+
path: 'skills/react-db/SKILL.md'
150+
package: 'packages/react-db'
151+
description: >
152+
React bindings for TanStack DB. useLiveQuery hook with dependency arrays
153+
and 8 overloads (query function, config object, pre-created collection,
154+
disabled state). useLiveSuspenseQuery for React Suspense with Error Boundaries.
155+
useLiveInfiniteQuery for cursor-based pagination (pageSize, fetchNextPage,
156+
hasNextPage). usePacedMutations for debounced React state. Return shape:
157+
data, state, collection, status, isLoading, isReady, isError.
158+
requires:
159+
- 'db-core'
160+
sources:
161+
- 'TanStack/db:docs/framework/react/overview.md'
162+
- 'TanStack/db:packages/react-db/src/useLiveQuery.ts'
163+
- 'TanStack/db:packages/react-db/src/useLiveInfiniteQuery.ts'
164+
- 'TanStack/db:packages/react-db/src/usePacedMutations.ts'
165+
166+
- name: 'Vue DB'
167+
slug: 'vue-db'
168+
type: 'framework'
169+
domain: 'framework-integration'
170+
path: 'skills/vue-db/SKILL.md'
171+
package: 'packages/vue-db'
172+
description: >
173+
Vue bindings for TanStack DB. useLiveQuery composable with
174+
MaybeRefOrGetter query functions and ComputedRef return values.
175+
Reactive deps via Vue refs and computed properties.
176+
requires:
177+
- 'db-core'
178+
sources:
179+
- 'TanStack/db:docs/framework/vue/overview.md'
180+
- 'TanStack/db:packages/vue-db/src/useLiveQuery.ts'
181+
182+
- name: 'Svelte DB'
183+
slug: 'svelte-db'
184+
type: 'framework'
185+
domain: 'framework-integration'
186+
path: 'skills/svelte-db/SKILL.md'
187+
package: 'packages/svelte-db'
188+
description: >
189+
Svelte 5 bindings for TanStack DB. useLiveQuery with Svelte 5 runes
190+
($state reactivity). Dependency arrays with getter functions for props.
191+
requires:
192+
- 'db-core'
193+
sources:
194+
- 'TanStack/db:docs/framework/svelte/overview.md'
195+
- 'TanStack/db:packages/svelte-db/src/useLiveQuery.svelte.ts'
196+
197+
- name: 'Solid DB'
198+
slug: 'solid-db'
199+
type: 'framework'
200+
domain: 'framework-integration'
201+
path: 'skills/solid-db/SKILL.md'
202+
package: 'packages/solid-db'
203+
description: >
204+
SolidJS bindings for TanStack DB. useLiveQuery with fine-grained
205+
reactivity (Accessor, createSignal). Signal reads must happen inside
206+
the query function for tracking.
207+
requires:
208+
- 'db-core'
209+
sources:
210+
- 'TanStack/db:docs/framework/solid/overview.md'
211+
- 'TanStack/db:packages/solid-db/src/useLiveQuery.ts'
212+
213+
- name: 'Angular DB'
214+
slug: 'angular-db'
215+
type: 'framework'
216+
domain: 'framework-integration'
217+
path: 'skills/angular-db/SKILL.md'
218+
package: 'packages/angular-db'
219+
description: >
220+
Angular bindings for TanStack DB. injectLiveQuery with Angular Signals.
221+
Must be called in injection context. Supports reactive params via
222+
{ params: () => T, query: ({ params, q }) => QueryBuilder } pattern.
223+
Uses inject(DestroyRef) for cleanup.
224+
requires:
225+
- 'db-core'
226+
sources:
227+
- 'TanStack/db:docs/framework/angular/overview.md'
228+
- 'TanStack/db:packages/angular-db/src/inject-live-query.ts'
229+
230+
# ─── Composition skills ───
231+
- name: 'Meta-Framework Integration'
232+
slug: 'meta-framework'
233+
type: 'composition'
234+
domain: 'meta-framework'
235+
path: 'skills/meta-framework/SKILL.md'
236+
package: 'packages/db'
237+
description: >
238+
Client-side preloading of TanStack DB collections in route loaders.
239+
collection.preload(), stateWhenReady(), toArrayWhenReady(), onFirstReady().
240+
Pre-creating createLiveQueryCollection in loaders. Setting ssr: false on
241+
routes (SSR not yet supported). TanStack Start and TanStack Router loader
242+
patterns. Coordinating collection lifecycle with route transitions.
243+
requires:
244+
- 'db-core'
245+
- 'db-core/collection-setup'
246+
sources:
247+
- 'TanStack/db:docs/guides/live-queries.md'
248+
- 'TanStack/db:examples/react/projects/src/routes/_authenticated/project/$projectId.tsx'
249+
- 'TanStack/db:examples/react/projects/README.md'
250+
251+
# ─── Offline skill ───
252+
- name: 'Offline Transactions'
253+
slug: 'offline'
254+
type: 'composition'
255+
domain: 'offline'
256+
path: 'skills/offline/SKILL.md'
257+
package: 'packages/offline-transactions'
258+
description: >
259+
Offline-first transaction queueing with @tanstack/offline-transactions.
260+
OfflineExecutor, startOfflineExecutor, OfflineConfig (collections,
261+
mutationFns, storage, maxConcurrency). Storage adapters (IndexedDBAdapter,
262+
LocalStorageAdapter). Retry policies (DefaultRetryPolicy, BackoffCalculator,
263+
NonRetriableError). Leader election (WebLocksLeader, BroadcastChannelLeader).
264+
Online detection (WebOnlineDetector). OutboxManager, KeyScheduler,
265+
TransactionSerializer. React Native support via @react-native-community/netinfo.
266+
requires:
267+
- 'db-core'
268+
- 'db-core/mutations-optimistic'
269+
sources:
270+
- 'TanStack/db:packages/offline-transactions/src/index.ts'
271+
- 'TanStack/db:packages/offline-transactions/src/offline-executor.ts'
272+
- 'TanStack/db:packages/offline-transactions/src/outbox.ts'
273+
- 'TanStack/db:packages/offline-transactions/src/leader/'

0 commit comments

Comments
 (0)