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

skill_spec.md

122 lines8.5 KB

@tanstack/cli — Skill Spec

@tanstack/cli is a project scaffolding and management tool for TanStack Start/Router applications. It generates new projects from a base framework template combined with user-selected add-ons (auth, database, deployment, monitoring, etc.), manages integration layering into existing projects, and supports custom add-on and template authoring workflows. A first-class --json output mode makes all discovery commands agent-friendly.

Domains

DomainDescriptionSkills
Scaffolding appsCreating new TanStack Start/Router projects with correct flags, framework, toolchain, and deploymentcreate-app-scaffold
Managing integrationsSelecting, validating, and applying add-ons at creation time or into existing projectschoose-ecosystem-integrations, add-addons-existing-app
Discovering metadataQuerying machine-readable CLI output to resolve ids, docs, and partner mappingsquery-docs-library-metadata
Authoring add-onsBuilding, iterating, and publishing custom add-ons and templatesmaintain-custom-addons-dev-watch

Skill Inventory

SkillTypeDomainWhat it coversFailure modes
create-app-scaffoldcorescaffoldingtanstack create flags, --router-only, --template, toolchain/deployment selection, non-interactive mode4
choose-ecosystem-integrationscompositionintegrationsecosystem/list-add-ons discovery, exclusive categories, --addon-details, --add-on-config4
add-addons-existing-appcoreintegrationstanstack add, .cta.json precondition, id resolution, dependsOn chains3
query-docs-library-metadatacorediscoverytanstack libraries/doc/search-docs/list-add-ons/addon-details --json, output schema parsing4
maintain-custom-addons-dev-watchlifecycleaddon-authoringadd-on init/compile/dev, tanstack create --dev-watch, validateAddOnSetup, path validation5

Failure Mode Inventory

create-app-scaffold (4 failure modes)

#MistakePrioritySourceCross-skill?
1Pass --add-ons without explicit idsHIGHgithub.com/TanStack/cli/issues/234—
2Use deprecated --no-tailwind expecting opt-out to workHIGHcommand-line.ts:369—
3Combine --router-only with add-ons, deployment, or templateCRITICALcommand-line.ts:343choose-ecosystem-integrations
4Use JavaScript/JSX template valueHIGHcommand-line.ts:381—

choose-ecosystem-integrations (4 failure modes)

#MistakePrioritySourceCross-skill?
1Use ecosystem partner id directly as add-on idHIGHcli.ts output comparisonadd-addons-existing-app
2Skip --addon-details before choosing a configurable providerHIGHprisma/info.json—
3Select multiple add-ons from the same exclusive categoryHIGHtypes.ts AddOnBaseSchema—
4Assume --router-only supports deployment integrationCRITICALcommand-line.ts:349create-app-scaffold

add-addons-existing-app (3 failure modes)

#MistakePrioritySourceCross-skill?
1Run tanstack add outside a TanStack CLI-scaffolded projectCRITICALcustom-add-ons/shared.tsmaintain-custom-addons-dev-watch
2Use a misspelled or invalid add-on idHIGHadd-ons.ts:44—
3Add an add-on without its required dependenciesHIGHadd-ons.ts:48—

query-docs-library-metadata (4 failure modes)

#MistakePrioritySourceCross-skill?
1Use --library / --version flags on tanstack docHIGHcli.ts:727—
2Include /docs/ prefix in doc path argumentMEDIUMcli.ts:765—
3Use deprecated create-tsrouter-app alias for discoveryMEDIUMgithub.com/TanStack/cli/issues/93—
4Treat --list-add-ons --json output as wrapped objectHIGHcli.ts:268—

maintain-custom-addons-dev-watch (5 failure modes)

#MistakePrioritySourceCross-skill?
1Run add-on init from a code-router projectCRITICALcustom-add-ons/add-on.ts:106—
2Use --dev-watch on the dev subcommand instead of createHIGHcli.ts:511—
3Pass --no-install to dev-watch createHIGHdev-watch.ts—
4Point --dev-watch at a path without framework structureHIGHcommand-line.ts:599—
5Run add-on workflows without .cta.json in working directoryHIGHcustom-add-ons/shared.tsadd-addons-existing-app

Tensions

TensionSkillsAgent implication
Compatibility mode vs explicit intentcreate-app-scaffold ↔ choose-ecosystem-integrationsAgent optimizing for a working command uses --router-only and silently drops all integration intent
Single-command convenience vs integration precisioncreate-app-scaffold ↔ query-docs-library-metadata ↔ choose-ecosystem-integrationsAgent skipping discovery runs tanstack create with plausible-but-wrong ids, wrong defaults, or mutually exclusive add-ons
Automation portability vs scaffold metadata dependencyadd-addons-existing-app ↔ maintain-custom-addons-dev-watchAgent treating tanstack add as a general-purpose command applies it to arbitrary projects and fails on missing .cta.json

Cross-References

FromToReason
create-app-scaffoldchoose-ecosystem-integrationsScaffold flag construction needs valid add-on ids from discovery first
create-app-scaffoldquery-docs-library-metadataSingle-command scaffolds that skip docs pick wrong defaults
choose-ecosystem-integrationsquery-docs-library-metadataPartner mapping and option inspection both use --json discovery commands
add-addons-existing-appchoose-ecosystem-integrationsChoosing which add-ons to apply requires understanding exclusive categories and dependency chains
maintain-custom-addons-dev-watchadd-addons-existing-appCustom add-on authoring assumes familiarity with add-on application patterns

Subsystems & Reference Candidates

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

Remaining Gaps

SkillQuestionStatus
create-app-scaffoldWhat is the full list of built-in template ids? Is the registry URL (CTA_REGISTRY) documented anywhere for public use?open
maintain-custom-addons-dev-watchIs tanstack template init/compile a distinct workflow from add-on init/compile, and what are the key differences?open
  • Core skills: create-app-scaffold, add-addons-existing-app, query-docs-library-metadata (framework-agnostic, apply to React and Solid alike)
  • Framework skills: none currently — add-on sets differ by framework but the CLI surface is identical
  • Lifecycle skills: maintain-custom-addons-dev-watch (the add-on authoring journey)
  • Composition skills: choose-ecosystem-integrations (bridges discovery and scaffold)
  • Reference files: create-app-scaffold/references/ (compatibility matrix, adapters, providers, toolchains), query-docs-library-metadata/references/ (output schemas)

Composition Opportunities

LibraryIntegration pointsComposition skill needed?
TanStack RouterPrimary routing layer in every scaffolded appNo — covered by doc discovery skill
TanStack StartDefault full-stack target; add-ons depend on itNo — covered by scaffold skill
Drizzle / PrismaORM add-ons with per-provider configuration surfacesNo — covered by choose-ecosystem-integrations
Clerk / WorkOS / Better AuthExclusive auth add-ons with env var requirementsNo — covered by choose-ecosystem-integrations
shadcn/uiStyling add-on installed via shadcn CLI post-scaffoldNo — reference in framework-adapters suffices