Skip to content

Latest commit

 

History

History
108 lines (84 loc) · 7.41 KB

skill_spec.md

File metadata and controls

108 lines (84 loc) · 7.41 KB

TanStack CLI — Skill Spec

TanStack CLI is a framework-agnostic command-line tool for creating TanStack application scaffolds, layering add-ons into existing projects, and retrieving machine-readable ecosystem/docs context. It is backed by @tanstack/create for generation logic and exposes both developer-facing and agent-facing discovery workflows. This spec targets @tanstack/cli v0.61.0.

Domains

Domain Description Skills
Scaffold new applications Choose mode/framework/template/toolchain/deployment/add-ons and generate an initial app. create-app-scaffold
Evolve existing applications Apply add-ons to existing repositories with dependency/metadata reconciliation. add-addons-existing-app
Fetch support context for agents Retrieve structured docs/library/add-on metadata from CLI discovery commands. query-docs-library-metadata
Select ecosystem integrations Turn ecosystem data into concrete, compatible integration choices. choose-ecosystem-integrations
Author and iterate custom extensions Build and live-watch custom add-ons/templates during maintainer workflows. maintain-custom-addons-dev-watch

Skill Inventory

Skill Type Domain What it covers Failure modes
create-app-scaffold core scaffold-new-applications tanstack create, mode/framework/template/toolchain/deployment/add-on flag interactions 3
add-addons-existing-app core evolve-existing-applications tanstack add, add-on resolution/dependencies, .cta.json preconditions 4
query-docs-library-metadata core fetch-support-context libraries, doc, search-docs, --list-add-ons, --addon-details JSON workflows 3
choose-ecosystem-integrations composition select-ecosystem-integrations ecosystem + add-on metadata mapping, exclusivity, optionized providers 4
maintain-custom-addons-dev-watch lifecycle author-custom-extensions add-on init/compile/dev and tanstack dev --dev-watch sync loop 4

Failure Mode Inventory

Create app scaffold (3 failure modes)

# Mistake Priority Source Cross-skill?
1 Pass --add-ons without explicit ids HIGH issue #234 —
2 Assume --no-tailwind is still supported HIGH packages/cli/src/command-line.ts —
3 Combine router-only with template/deployment/add-ons CRITICAL packages/cli/src/command-line.ts choose-ecosystem-integrations

Add add-ons to existing app (4 failure modes)

# Mistake Priority Source Cross-skill?
1 Run tanstack add without .cta.json CRITICAL packages/create/src/custom-add-ons/shared.ts maintain-custom-addons-dev-watch
2 Use invalid add-on id HIGH packages/create/src/add-ons.ts —
3 Ignore add-on dependency requirements HIGH packages/create/src/add-ons.ts —
4 Assume old Windows path bug still present MEDIUM issue #329 —

Query docs and library metadata (3 failure modes)

# Mistake Priority Source Cross-skill?
1 Use removed tanstack mcp command CRITICAL packages/cli/CHANGELOG.md —
2 Use invalid library id/version/path for doc HIGH packages/cli/src/cli.ts —
3 Rely on deprecated alias for discovery commands MEDIUM issue #93 —

Choose ecosystem integrations (4 failure modes)

# Mistake Priority Source Cross-skill?
1 Treat ecosystem partner id as add-on id HIGH ecosystem --json + --list-add-ons --json —
2 Skip --addon-details for optionized providers HIGH --addon-details prisma --json —
3 Select multiple exclusive integrations together HIGH packages/create/src/frameworks/*/*/info.json —
4 Assume router-only supports deployment integration CRITICAL packages/cli/src/command-line.ts create-app-scaffold

Maintain custom add-ons in dev watch (4 failure modes)

# Mistake Priority Source Cross-skill?
1 Use --dev-watch with --no-install HIGH packages/cli/src/dev-watch.ts —
2 Start dev-watch without valid package entry HIGH packages/cli/src/dev-watch.ts —
3 Author add-on from code-router project CRITICAL packages/create/src/custom-add-ons/add-on.ts —
4 Run add-on workflows without scaffold metadata HIGH packages/create/src/custom-add-ons/shared.ts add-addons-existing-app

Tensions

Tension Skills Agent implication
Compatibility mode vs explicit intent create-app-scaffold ↔ choose-ecosystem-integrations Agents optimize for successful command execution and miss silently dropped user intent.
Backwards support vs deterministic automation add-addons-existing-app ↔ maintain-custom-addons-dev-watch Agents assume universal workflows and fail on hidden metadata preconditions.
Single-command convenience vs integration precision create-app-scaffold ↔ query-docs-library-metadata ↔ choose-ecosystem-integrations Agents skip preflight metadata discovery and choose plausible but wrong defaults.

Subsystems & Reference Candidates

Skill Subsystems Reference candidates
create-app-scaffold framework adapters, deployment providers, toolchains create flag compatibility matrix
add-addons-existing-app — —
query-docs-library-metadata — discovery command output schemas
choose-ecosystem-integrations authentication providers, data layer providers, deployment targets —
maintain-custom-addons-dev-watch — —

Recommended Skill File Structure

  • Core skills: create-app-scaffold, add-addons-existing-app, query-docs-library-metadata
  • Framework skills: none required (framework selection is embedded in scaffold flow)
  • Lifecycle skills: maintain-custom-addons-dev-watch
  • Composition skills: choose-ecosystem-integrations
  • Reference files: create-app-scaffold (flag matrix), query-docs-library-metadata (JSON output schemas)

Composition Opportunities

Library Integration points Composition skill needed?
Clerk auth add-on selection and exclusive auth category yes — choose-ecosystem-integrations
Better Auth auth add-on selection and framework/mode compatibility yes — choose-ecosystem-integrations
WorkOS auth add-on selection and enterprise auth workflows yes — choose-ecosystem-integrations
Prisma ORM add-on with provider options (postgres/sqlite/mysql) yes — choose-ecosystem-integrations
Drizzle ORM add-on with provider options (postgresql/sqlite/mysql) yes — choose-ecosystem-integrations
Convex database add-on with exclusivity interactions yes — choose-ecosystem-integrations
Cloudflare deployment add-on selection in exclusive deploy category yes — choose-ecosystem-integrations
Netlify deployment add-on selection in exclusive deploy category yes — choose-ecosystem-integrations
Railway deployment add-on selection in exclusive deploy category yes — choose-ecosystem-integrations