Skip to content
Source
Sign inSign up
TanStack/cli
Open History to see the last commit

skill_spec.md

108 lines7.4 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

DomainDescriptionSkills
Scaffold new applicationsChoose mode/framework/template/toolchain/deployment/add-ons and generate an initial app.create-app-scaffold
Evolve existing applicationsApply add-ons to existing repositories with dependency/metadata reconciliation.add-addons-existing-app
Fetch support context for agentsRetrieve structured docs/library/add-on metadata from CLI discovery commands.query-docs-library-metadata
Select ecosystem integrationsTurn ecosystem data into concrete, compatible integration choices.choose-ecosystem-integrations
Author and iterate custom extensionsBuild and live-watch custom add-ons/templates during maintainer workflows.maintain-custom-addons-dev-watch

Skill Inventory

SkillTypeDomainWhat it coversFailure modes
create-app-scaffoldcorescaffold-new-applicationstanstack create, mode/framework/template/toolchain/deployment/add-on flag interactions3
add-addons-existing-appcoreevolve-existing-applicationstanstack add, add-on resolution/dependencies, .cta.json preconditions4
query-docs-library-metadatacorefetch-support-contextlibraries, doc, search-docs, --list-add-ons, --addon-details JSON workflows3
choose-ecosystem-integrationscompositionselect-ecosystem-integrationsecosystem + add-on metadata mapping, exclusivity, optionized providers4
maintain-custom-addons-dev-watchlifecycleauthor-custom-extensionsadd-on init/compile/dev and tanstack dev --dev-watch sync loop4

Failure Mode Inventory

Create app scaffold (3 failure modes)

#MistakePrioritySourceCross-skill?
1Pass --add-ons without explicit idsHIGHissue #234—
2Assume --no-tailwind is still supportedHIGHpackages/cli/src/command-line.ts—
3Combine router-only with template/deployment/add-onsCRITICALpackages/cli/src/command-line.tschoose-ecosystem-integrations

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

#MistakePrioritySourceCross-skill?
1Run tanstack add without .cta.jsonCRITICALpackages/create/src/custom-add-ons/shared.tsmaintain-custom-addons-dev-watch
2Use invalid add-on idHIGHpackages/create/src/add-ons.ts—
3Ignore add-on dependency requirementsHIGHpackages/create/src/add-ons.ts—
4Assume old Windows path bug still presentMEDIUMissue #329—

Query docs and library metadata (3 failure modes)

#MistakePrioritySourceCross-skill?
1Use removed tanstack mcp commandCRITICALpackages/cli/CHANGELOG.md—
2Use invalid library id/version/path for docHIGHpackages/cli/src/cli.ts—
3Rely on deprecated alias for discovery commandsMEDIUMissue #93—

Choose ecosystem integrations (4 failure modes)

#MistakePrioritySourceCross-skill?
1Treat ecosystem partner id as add-on idHIGHecosystem --json + --list-add-ons --json—
2Skip --addon-details for optionized providersHIGH--addon-details prisma --json—
3Select multiple exclusive integrations togetherHIGHpackages/create/src/frameworks/*/*/info.json—
4Assume router-only supports deployment integrationCRITICALpackages/cli/src/command-line.tscreate-app-scaffold

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

#MistakePrioritySourceCross-skill?
1Use --dev-watch with --no-installHIGHpackages/cli/src/dev-watch.ts—
2Start dev-watch without valid package entryHIGHpackages/cli/src/dev-watch.ts—
3Author add-on from code-router projectCRITICALpackages/create/src/custom-add-ons/add-on.ts—
4Run add-on workflows without scaffold metadataHIGHpackages/create/src/custom-add-ons/shared.tsadd-addons-existing-app

Tensions

TensionSkillsAgent implication
Compatibility mode vs explicit intentcreate-app-scaffold ↔ choose-ecosystem-integrationsAgents optimize for successful command execution and miss silently dropped user intent.
Backwards support vs deterministic automationadd-addons-existing-app ↔ maintain-custom-addons-dev-watchAgents assume universal workflows and fail on hidden metadata preconditions.
Single-command convenience vs integration precisioncreate-app-scaffold ↔ query-docs-library-metadata ↔ choose-ecosystem-integrationsAgents skip preflight metadata discovery and choose plausible but wrong defaults.

Subsystems & Reference Candidates

SkillSubsystemsReference candidates
create-app-scaffoldframework adapters, deployment providers, toolchainscreate flag compatibility matrix
add-addons-existing-app——
query-docs-library-metadata—discovery command output schemas
choose-ecosystem-integrationsauthentication providers, data layer providers, deployment targets—
maintain-custom-addons-dev-watch——
  • 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

LibraryIntegration pointsComposition skill needed?
Clerkauth add-on selection and exclusive auth categoryyes — choose-ecosystem-integrations
Better Authauth add-on selection and framework/mode compatibilityyes — choose-ecosystem-integrations
WorkOSauth add-on selection and enterprise auth workflowsyes — choose-ecosystem-integrations
PrismaORM add-on with provider options (postgres/sqlite/mysql)yes — choose-ecosystem-integrations
DrizzleORM add-on with provider options (postgresql/sqlite/mysql)yes — choose-ecosystem-integrations
Convexdatabase add-on with exclusivity interactionsyes — choose-ecosystem-integrations
Cloudflaredeployment add-on selection in exclusive deploy categoryyes — choose-ecosystem-integrations
Netlifydeployment add-on selection in exclusive deploy categoryyes — choose-ecosystem-integrations
Railwaydeployment add-on selection in exclusive deploy categoryyes — choose-ecosystem-integrations