Open History to see the last commit
1# @tanstack/cli — Skill Spec
2
3`@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.
4
5## Domains
6
7| Domain | Description | Skills |
8| ------ | ----------- | ------- |
9| Scaffolding apps | Creating new TanStack Start/Router projects with correct flags, framework, toolchain, and deployment | create-app-scaffold |
10| Managing integrations | Selecting, validating, and applying add-ons at creation time or into existing projects | choose-ecosystem-integrations, add-addons-existing-app |
11| Discovering metadata | Querying machine-readable CLI output to resolve ids, docs, and partner mappings | query-docs-library-metadata |
12| Authoring add-ons | Building, iterating, and publishing custom add-ons and templates | maintain-custom-addons-dev-watch |
13
14## Skill Inventory
15
16| Skill | Type | Domain | What it covers | Failure modes |
17| ----- | ---- | ------ | -------------- | ------------- |
18| create-app-scaffold | core | scaffolding | tanstack create flags, --router-only, --template, toolchain/deployment selection, non-interactive mode | 4 |
19| choose-ecosystem-integrations | composition | integrations | ecosystem/list-add-ons discovery, exclusive categories, --addon-details, --add-on-config | 4 |
20| add-addons-existing-app | core | integrations | tanstack add, .cta.json precondition, id resolution, dependsOn chains | 3 |
21| query-docs-library-metadata | core | discovery | tanstack libraries/doc/search-docs/list-add-ons/addon-details --json, output schema parsing | 4 |
22| maintain-custom-addons-dev-watch | lifecycle | addon-authoring | add-on init/compile/dev, tanstack create --dev-watch, validateAddOnSetup, path validation | 5 |
23
24## Failure Mode Inventory
25
26### create-app-scaffold (4 failure modes)
27
28| # | Mistake | Priority | Source | Cross-skill? |
29| - | ------- | -------- | ------ | ------------ |
30| 1 | Pass --add-ons without explicit ids | HIGH | github.com/TanStack/cli/issues/234 | — |
31| 2 | Use deprecated --no-tailwind expecting opt-out to work | HIGH | command-line.ts:369 | — |
32| 3 | Combine --router-only with add-ons, deployment, or template | CRITICAL | command-line.ts:343 | choose-ecosystem-integrations |
33| 4 | Use JavaScript/JSX template value | HIGH | command-line.ts:381 | — |
34
35### choose-ecosystem-integrations (4 failure modes)
36
37| # | Mistake | Priority | Source | Cross-skill? |
38| - | ------- | -------- | ------ | ------------ |
39| 1 | Use ecosystem partner id directly as add-on id | HIGH | cli.ts output comparison | add-addons-existing-app |
40| 2 | Skip --addon-details before choosing a configurable provider | HIGH | prisma/info.json | — |
41| 3 | Select multiple add-ons from the same exclusive category | HIGH | types.ts AddOnBaseSchema | — |
42| 4 | Assume --router-only supports deployment integration | CRITICAL | command-line.ts:349 | create-app-scaffold |
43
44### add-addons-existing-app (3 failure modes)
45
46| # | Mistake | Priority | Source | Cross-skill? |
47| - | ------- | -------- | ------ | ------------ |
48| 1 | Run tanstack add outside a TanStack CLI-scaffolded project | CRITICAL | custom-add-ons/shared.ts | maintain-custom-addons-dev-watch |
49| 2 | Use a misspelled or invalid add-on id | HIGH | add-ons.ts:44 | — |
50| 3 | Add an add-on without its required dependencies | HIGH | add-ons.ts:48 | — |
51
52### query-docs-library-metadata (4 failure modes)
53
54| # | Mistake | Priority | Source | Cross-skill? |
55| - | ------- | -------- | ------ | ------------ |
56| 1 | Use --library / --version flags on tanstack doc | HIGH | cli.ts:727 | — |
57| 2 | Include /docs/ prefix in doc path argument | MEDIUM | cli.ts:765 | — |
58| 3 | Use deprecated create-tsrouter-app alias for discovery | MEDIUM | github.com/TanStack/cli/issues/93 | — |
59| 4 | Treat --list-add-ons --json output as wrapped object | HIGH | cli.ts:268 | — |
60
61### maintain-custom-addons-dev-watch (5 failure modes)
62
63| # | Mistake | Priority | Source | Cross-skill? |
64| - | ------- | -------- | ------ | ------------ |
65| 1 | Run add-on init from a code-router project | CRITICAL | custom-add-ons/add-on.ts:106 | — |
66| 2 | Use --dev-watch on the `dev` subcommand instead of `create` | HIGH | cli.ts:511 | — |
67| 3 | Pass --no-install to dev-watch create | HIGH | dev-watch.ts | — |
68| 4 | Point --dev-watch at a path without framework structure | HIGH | command-line.ts:599 | — |
69| 5 | Run add-on workflows without .cta.json in working directory | HIGH | custom-add-ons/shared.ts | add-addons-existing-app |
70
71## Tensions
72
73| Tension | Skills | Agent implication |
74| ------- | ------ | ----------------- |
75| Compatibility mode vs explicit intent | create-app-scaffold ↔ choose-ecosystem-integrations | Agent optimizing for a working command uses --router-only and silently drops all integration intent |
76| Single-command convenience vs integration precision | create-app-scaffold ↔ query-docs-library-metadata ↔ choose-ecosystem-integrations | Agent skipping discovery runs tanstack create with plausible-but-wrong ids, wrong defaults, or mutually exclusive add-ons |
77| Automation portability vs scaffold metadata dependency | add-addons-existing-app ↔ maintain-custom-addons-dev-watch | Agent treating tanstack add as a general-purpose command applies it to arbitrary projects and fails on missing .cta.json |
78
79## Cross-References
80
81| From | To | Reason |
82| ---- | -- | ------ |
83| create-app-scaffold | choose-ecosystem-integrations | Scaffold flag construction needs valid add-on ids from discovery first |
84| create-app-scaffold | query-docs-library-metadata | Single-command scaffolds that skip docs pick wrong defaults |
85| choose-ecosystem-integrations | query-docs-library-metadata | Partner mapping and option inspection both use --json discovery commands |
86| add-addons-existing-app | choose-ecosystem-integrations | Choosing which add-ons to apply requires understanding exclusive categories and dependency chains |
87| maintain-custom-addons-dev-watch | add-addons-existing-app | Custom add-on authoring assumes familiarity with add-on application patterns |
88
89## Subsystems & Reference Candidates
90
91| Skill | Subsystems | Reference candidates |
92| ----- | ---------- | -------------------- |
93| create-app-scaffold | — | create-flag-compatibility-matrix, framework-adapters, deployment-providers, toolchains |
94| choose-ecosystem-integrations | — | authentication-providers, data-layer-providers, deployment-targets |
95| add-addons-existing-app | — | — |
96| query-docs-library-metadata | — | discovery-command-output-schemas |
97| maintain-custom-addons-dev-watch | — | — |
98
99## Remaining Gaps
100
101| Skill | Question | Status |
102| ----- | -------- | ------ |
103| create-app-scaffold | What is the full list of built-in template ids? Is the registry URL (CTA_REGISTRY) documented anywhere for public use? | open |
104| maintain-custom-addons-dev-watch | Is `tanstack template init/compile` a distinct workflow from add-on init/compile, and what are the key differences? | open |
105
106## Recommended Skill File Structure
107
108- **Core skills:** create-app-scaffold, add-addons-existing-app, query-docs-library-metadata (framework-agnostic, apply to React and Solid alike)
109- **Framework skills:** none currently — add-on sets differ by framework but the CLI surface is identical
110- **Lifecycle skills:** maintain-custom-addons-dev-watch (the add-on authoring journey)
111- **Composition skills:** choose-ecosystem-integrations (bridges discovery and scaffold)
112- **Reference files:** create-app-scaffold/references/ (compatibility matrix, adapters, providers, toolchains), query-docs-library-metadata/references/ (output schemas)
113
114## Composition Opportunities
115
116| Library | Integration points | Composition skill needed? |
117| ------- | ------------------ | ------------------------- |
118| TanStack Router | Primary routing layer in every scaffolded app | No — covered by doc discovery skill |
119| TanStack Start | Default full-stack target; add-ons depend on it | No — covered by scaffold skill |
120| Drizzle / Prisma | ORM add-ons with per-provider configuration surfaces | No — covered by choose-ecosystem-integrations |
121| Clerk / WorkOS / Better Auth | Exclusive auth add-ons with env var requirements | No — covered by choose-ecosystem-integrations |
122| shadcn/ui | Styling add-on installed via shadcn CLI post-scaffold | No — reference in framework-adapters suffices |