diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index 4f6812e1..d6a344d4 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -1113,6 +1113,18 @@ "authentication": "ON_INSTALL" }, "category": "Productivity" + }, + { + "name": "tanstack", + "source": { + "source": "local", + "path": "./plugins/tanstack" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Framework" } ] } diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 8c7742a3..03a86dd9 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1499,6 +1499,27 @@ } } }, + { + "name": "tanstack", + "description": "Version-aware skills for the TanStack ecosystem (Query, Router, Start, Table, Form, DB, Virtual, ...) via the official @tanstack/intent CLI — loads skills shipped inside the installed npm packages", + "category": "framework", + "keywords": ["tanstack", "query", "router", "start", "table", "form", "db", "virtual", "intent"], + "tags": ["framework", "frontend"], + "source": "./plugins/tanstack", + "relevance": { + "topic": "TanStack", + "signals": { + "hosts": ["tanstack.com"], + "filesRead": ["**/routeTree.gen.ts", "**/tanstack.config.*"], + "manifestDeps": [ + { + "file": "[/\\\\]package\\.json$", + "pattern": "\"@tanstack/[a-z0-9-]+\"\\s*:" + } + ] + } + } + }, { "name": "run-verify", "description": "Run and verify code changes by driving the real app — launch it, interact with it, capture evidence. Ships run, verify, and run-skill-generator skills for Claude Code, Codex, and Antigravity.", diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index 79063db2..9b05b769 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -363,6 +363,11 @@ "name": "greptile", "source": "./plugins/greptile", "description": "Greptile agent skills for PR quality: check PR review comments and status checks, run Greptile CLI reviews on local branches, and iteratively improve PRs until they score 5/5" + }, + { + "name": "tanstack", + "source": "./plugins/tanstack", + "description": "Version-aware skills for the TanStack ecosystem (Query, Router, Start, Table, Form, DB, Virtual, ...) via the official @tanstack/intent CLI — loads skills shipped inside the installed npm packages" } ] } diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 60a28e1f..66c891cc 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -66,5 +66,6 @@ "plugins/lavish": "1.2.0", "plugins/axi": "1.2.0", "plugins/playwright-cli": "1.0.0", - "plugins/greptile": "1.1.0" + "plugins/greptile": "1.1.0", + "plugins/tanstack": "0.1.0" } diff --git a/README.md b/README.md index 5e380356..1926f21b 100644 --- a/README.md +++ b/README.md @@ -312,6 +312,11 @@ React Native and Expo best practices for building performant mobile apps. **Install:** `/plugin install react-native@pleaseai` | **Source:** [plugins/react-native](https://github.com/pleaseai/claude-code-plugins/tree/main/plugins/react-native) +#### TanStack +Version-aware skills for the TanStack ecosystem (Query, Router, Start, Table, Form, DB, Virtual, ...) — loads official skills shipped inside the installed npm packages via the [`@tanstack/intent`](https://tanstack.com/intent) CLI. + +**Install:** `/plugin install tanstack@pleaseai` | **Source:** [plugins/tanstack](https://github.com/pleaseai/claude-code-plugins/tree/main/plugins/tanstack) + #### Tiptap Helps coding agents integrate and work with the Tiptap rich text editor — extensions, collaboration, comments, AI, and document conversion. @@ -603,6 +608,7 @@ Once the marketplace is added (or files copied), the following plugins are avail /plugin install next@pleaseai /plugin install react@pleaseai /plugin install react-native@pleaseai +/plugin install tanstack@pleaseai /plugin install emulate@pleaseai /plugin install ask@pleaseai /plugin install workflow-sdk@pleaseai diff --git a/plugins/tanstack/.claude-plugin/plugin.json b/plugins/tanstack/.claude-plugin/plugin.json new file mode 100644 index 00000000..dc2e3ef1 --- /dev/null +++ b/plugins/tanstack/.claude-plugin/plugin.json @@ -0,0 +1,26 @@ +{ + "name": "tanstack", + "version": "0.1.0", + "description": "Version-aware skills for the TanStack ecosystem (Query, Router, Start, Table, Form, DB, Virtual, Store, Pacer, AI). Uses the official @tanstack/intent CLI to load skills shipped inside the installed npm packages.", + "author": { + "name": "TanStack", + "url": "https://tanstack.com" + }, + "homepage": "https://tanstack.com/intent", + "repository": "https://github.com/TanStack/intent", + "license": "MIT", + "keywords": [ + "tanstack", + "query", + "router", + "start", + "table", + "form", + "db", + "virtual", + "intent" + ], + "skills": [ + "./skills/" + ] +} diff --git a/plugins/tanstack/.codex-plugin/plugin.json b/plugins/tanstack/.codex-plugin/plugin.json new file mode 100644 index 00000000..76a08954 --- /dev/null +++ b/plugins/tanstack/.codex-plugin/plugin.json @@ -0,0 +1,38 @@ +{ + "name": "tanstack", + "version": "0.1.0", + "description": "Version-aware skills for the TanStack ecosystem (Query, Router, Start, Table, Form, DB, Virtual, Store, Pacer, AI). Uses the official @tanstack/intent CLI to load skills shipped inside the installed npm packages.", + "author": { + "name": "TanStack", + "url": "https://tanstack.com" + }, + "interface": { + "displayName": "Tanstack", + "shortDescription": "Version-aware skills for the TanStack ecosystem (Query, Router, Start, Table, Form, DB, Virtual, Store, Pacer, AI)", + "longDescription": "Version-aware skills for the TanStack ecosystem (Query, Router, Start, Table, Form, DB, Virtual, Store, Pacer, AI). Uses the official @tanstack/intent CLI to load skills shipped inside the installed npm packages.", + "developerName": "TanStack", + "category": "Framework", + "capabilities": [ + "Skill" + ], + "defaultPrompt": [ + "Help me use Tanstack for my current task." + ], + "websiteURL": "https://tanstack.com/intent" + }, + "homepage": "https://tanstack.com/intent", + "repository": "https://github.com/TanStack/intent", + "license": "MIT", + "keywords": [ + "tanstack", + "query", + "router", + "start", + "table", + "form", + "db", + "virtual", + "intent" + ], + "skills": "./skills/" +} diff --git a/plugins/tanstack/.cursor-plugin/plugin.json b/plugins/tanstack/.cursor-plugin/plugin.json new file mode 100644 index 00000000..c92cdf5d --- /dev/null +++ b/plugins/tanstack/.cursor-plugin/plugin.json @@ -0,0 +1,28 @@ +{ + "name": "tanstack", + "displayName": "Tanstack", + "description": "Version-aware skills for the TanStack ecosystem (Query, Router, Start, Table, Form, DB, Virtual, Store, Pacer, AI). Uses the official @tanstack/intent CLI to load skills shipped inside the installed npm packages.", + "version": "0.1.0", + "author": { + "name": "TanStack" + }, + "category": "Framework", + "homepage": "https://tanstack.com/intent", + "repository": "https://github.com/TanStack/intent", + "license": "MIT", + "keywords": [ + "tanstack", + "query", + "router", + "start", + "table", + "form", + "db", + "virtual", + "intent" + ], + "tags": [ + "framework", + "frontend" + ] +} diff --git a/plugins/tanstack/README.md b/plugins/tanstack/README.md new file mode 100644 index 00000000..10a970e7 --- /dev/null +++ b/plugins/tanstack/README.md @@ -0,0 +1,26 @@ +# tanstack + +Version-aware skills for the TanStack ecosystem — Query, Router, Start, Table, Form, DB, Virtual, Store, Pacer, AI, and more. Ships a single `use-tanstack` skill that drives the official [`@tanstack/intent`](https://tanstack.com/intent) CLI to load Agent Skills **shipped inside the installed npm packages**, so guidance always matches the exact library versions in the project. + +## How it works + +TanStack publishes official SKILL.md documents inside its npm packages, versioned with each release ([TanStack Intent](https://tanstack.com/intent/latest/docs/overview)). The skill instructs the agent to: + +1. `npx @tanstack/intent@latest list` — discover skills from the project's installed dependencies +2. `npx @tanstack/intent@latest load @tanstack/db#db-core/live-queries` — load the exact-version skill content for the task at hand +3. Fall back to the official markdown docs (`tanstack.com//latest/docs/.md`) for packages that don't ship skills yet + +No skill content is vendored in this plugin — everything is resolved from the project's own dependencies at run time, so there is nothing to go stale. + +## Install + +### Claude Code + +```bash +/plugin marketplace add pleaseai/claude-code-plugins +/plugin install tanstack@pleaseai +``` + +## Compatibility + +The `SKILL.md` format is shared by Claude Code, Cursor, Codex CLI, and Google Antigravity. Runtime manifests (`.codex-plugin/plugin.json`, root `plugin.json`, `.cursor-plugin/plugin.json`) are auto-generated by `bun run plugins:multi-format` — do not hand-edit them. diff --git a/plugins/tanstack/plugin.json b/plugins/tanstack/plugin.json new file mode 100644 index 00000000..6c25ddf6 --- /dev/null +++ b/plugins/tanstack/plugin.json @@ -0,0 +1,23 @@ +{ + "name": "tanstack", + "version": "0.1.0", + "description": "Version-aware skills for the TanStack ecosystem (Query, Router, Start, Table, Form, DB, Virtual, Store, Pacer, AI). Uses the official @tanstack/intent CLI to load skills shipped inside the installed npm packages.", + "author": { + "name": "TanStack", + "url": "https://tanstack.com" + }, + "homepage": "https://tanstack.com/intent", + "repository": "https://github.com/TanStack/intent", + "license": "MIT", + "keywords": [ + "tanstack", + "query", + "router", + "start", + "table", + "form", + "db", + "virtual", + "intent" + ] +} diff --git a/plugins/tanstack/skills/use-tanstack/SKILL.md b/plugins/tanstack/skills/use-tanstack/SKILL.md new file mode 100644 index 00000000..c87fc6fe --- /dev/null +++ b/plugins/tanstack/skills/use-tanstack/SKILL.md @@ -0,0 +1,86 @@ +--- +name: use-tanstack +description: 'Answer questions and write code for TanStack libraries using version-accurate, officially shipped Agent Skills instead of training data. Use when working with any @tanstack/* package or TanStack library: Query (react-query, solid-query, vue-query — useQuery, useMutation, QueryClient, queryOptions, invalidation, optimistic updates), Router (@tanstack/react-router — createFileRoute, loaders, search params, path params, type-safe navigation), Start (full-stack framework — server functions, SSR, streaming), Table (headless tables — useReactTable, columns, sorting, filtering, pagination), Form (useForm, field validation), DB (createCollection, live queries, optimistic mutations, sync adapters), Virtual (useVirtualizer, list/grid virtualization), Store, Pacer (debounce/throttle/queue), AI, Devtools, Config, or CLI. Also use when the user mentions tanstack.com docs or the @tanstack/intent CLI.' +--- + +## Core Principle: Load Official Skills, Do Not Trust Internal Knowledge + +TanStack libraries release fast and their APIs drift between minor versions. TanStack ships **official Agent Skills inside the npm packages themselves**, versioned with each release. The [`@tanstack/intent`](https://tanstack.com/intent) CLI discovers and loads the skills matching the **exact versions installed in the project** — always prefer them over recalled knowledge. + +Pick the runner matching the project's package manager: + +| Tool | Pattern | +|------|---------| +| npm | `npx @tanstack/intent@latest ` | +| pnpm | `pnpm dlx @tanstack/intent@latest ` | +| Yarn | `yarn dlx @tanstack/intent@latest ` | +| Bun | `bunx @tanstack/intent@latest ` | + +## Workflow + +**1. Discover** — from the project root (must run after dependencies are installed): + +```bash +npx @tanstack/intent@latest list +``` + +This scans `node_modules` / workspace dependencies for intent-enabled packages and prints every available skill with its description and the exact `load` command, e.g.: + +``` +@tanstack/db + db-core [core] TanStack DB core concepts: createCollection ... + Load: npx @tanstack/intent@latest load @tanstack/db#db-core + live-queries [sub-skill] Query builder fluent API: from, where, join ... + mutations-optimistic [sub-skill] collection.insert, collection.update ... +``` + +**2. Load** — start with the `[core]` skill for the library, then load only the sub-skills whose descriptions match the task: + +```bash +npx @tanstack/intent@latest load @tanstack/db#db-core +npx @tanstack/intent@latest load @tanstack/db#db-core/live-queries +``` + +The output is the SKILL.md content for the installed package version. Treat it as authoritative: verify every API name and signature against it before writing code, and prefer it over any conflicting memory of the API. + +**3. Re-check on version changes** — skills are pinned to the installed version. If dependencies are updated mid-session, re-run `list`/`load`. + +Notes: + +- `list` only scans local project dependencies by default; pass `--global` to include globally installed packages. +- `load --path` prints the resolved skill file path instead of its content (useful for debugging). +- The CLI may print a notice about `package.json#intent.skills` — that allowlist narrows which packages' skills are surfaced. Do not add one unless the user asks. + +## Fallback: Packages Without Shipped Skills + +Intent is rolling out across the ecosystem (newest packages first — Router, Start, DB, AI, Devtools ship skills; some stable packages like `@tanstack/react-query` may not yet). If `list` shows no skills for the library you need, check the installed version first (`npm ls @tanstack/react-query` or read the lockfile), then: + +1. **Preferred — [`ask`](https://github.com/pleaseai/ask) CLI** (check `which ask`). It fetches the library's docs/source at the exact installed version (resolved from the lockfile) and caches them locally for grepping: + + ```bash + # `ask docs` prints candidate paths one per line (installed package dir, then + # the repo docs tree). Pick the last line that is an existing directory rather + # than blindly trusting `tail -n1` — output format/notices can shift. + ASK_DOCS=$(ask docs "npm:@tanstack/react-query" | while read -r p || [ -n "$p" ]; do [ -d "$p" ] && echo "$p"; done | tail -n1) + [ -d "$ASK_DOCS" ] && rg -l "useQuery" "$ASK_DOCS" + ASK_SRC=$(ask src "npm:@tanstack/react-query" | while read -r p || [ -n "$p" ]; do [ -d "$p" ] && echo "$p"; done | tail -n1) # implementation, for API signatures + ``` + + Append `@` to pin explicitly (e.g. `npm:@tanstack/react-query@5.101.2`). Requires `ask` >= 0.4.9 — older versions cannot resolve TanStack's scoped monorepo release tags; there, fall back to `github:TanStack/query@main` (repo names match the library: `TanStack/query`, `TanStack/router`, `TanStack/table`, `TanStack/form`, `TanStack/virtual`, ...) and cross-check anything version-sensitive against the installed package's `node_modules` typings or CHANGELOG. + +2. **No `ask` — official markdown docs.** Every page on tanstack.com has a plain-markdown variant; append `.md` to the docs URL: + + ```bash + curl -fsSL https://tanstack.com/query/latest/docs/framework/react/overview.md + curl -fsSL https://tanstack.com/table/latest/docs/introduction.md + ``` + + Replace `latest` with the installed major version (e.g. `/query/v5/`) when the project is not on the latest line. + +If neither shipped skills nor version-matching docs can back an answer, say so explicitly instead of guessing. + +## Common Decision Points + +- **Which library?** Query = server-state caching/fetching; DB = client-side reactive collections with optimistic mutations and sync; Store = tiny framework-agnostic reactive store. Do not reach for DB when plain Query suffices. +- **Router vs Start**: Router is the type-safe routing library; Start is the full-stack framework built on it (server functions, SSR). A Router project is not automatically a Start project — check for `@tanstack/react-start` before suggesting server functions. +- **Framework adapters**: most libraries are headless cores with per-framework adapters (`@tanstack/react-*`, `@tanstack/vue-*`, `@tanstack/solid-*`, ...). Load skills / read docs for the adapter actually installed, not the React one by default. diff --git a/release-please-config.json b/release-please-config.json index f47c5d3d..9bbd5527 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -1193,6 +1193,32 @@ "jsonpath": "$.version" } ] + }, + "plugins/tanstack": { + "release-type": "simple", + "component": "tanstack", + "extra-files": [ + { + "type": "json", + "path": ".claude-plugin/plugin.json", + "jsonpath": "$.version" + }, + { + "type": "json", + "path": ".codex-plugin/plugin.json", + "jsonpath": "$.version" + }, + { + "type": "json", + "path": "plugin.json", + "jsonpath": "$.version" + }, + { + "type": "json", + "path": ".cursor-plugin/plugin.json", + "jsonpath": "$.version" + } + ] } }, "release-type": "node",