Open History to see the last commit
1# TanStack CLI — Skill Spec
2
3TanStack 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.
4
5## Domains
6
7| Domain | Description | Skills |
8|--------|-------------|--------|
9| Scaffold new applications | Choose mode/framework/template/toolchain/deployment/add-ons and generate an initial app. | create-app-scaffold |
10| Evolve existing applications | Apply add-ons to existing repositories with dependency/metadata reconciliation. | add-addons-existing-app |
11| Fetch support context for agents | Retrieve structured docs/library/add-on metadata from CLI discovery commands. | query-docs-library-metadata |
12| Select ecosystem integrations | Turn ecosystem data into concrete, compatible integration choices. | choose-ecosystem-integrations |
13| Author and iterate custom extensions | Build and live-watch custom add-ons/templates during maintainer workflows. | maintain-custom-addons-dev-watch |
14
15## Skill Inventory
16
17| Skill | Type | Domain | What it covers | Failure modes |
18|-------|------|--------|----------------|---------------|
19| create-app-scaffold | core | scaffold-new-applications | `tanstack create`, mode/framework/template/toolchain/deployment/add-on flag interactions | 3 |
20| add-addons-existing-app | core | evolve-existing-applications | `tanstack add`, add-on resolution/dependencies, `.cta.json` preconditions | 4 |
21| query-docs-library-metadata | core | fetch-support-context | `libraries`, `doc`, `search-docs`, `--list-add-ons`, `--addon-details` JSON workflows | 3 |
22| choose-ecosystem-integrations | composition | select-ecosystem-integrations | `ecosystem` + add-on metadata mapping, exclusivity, optionized providers | 4 |
23| maintain-custom-addons-dev-watch | lifecycle | author-custom-extensions | `add-on init/compile/dev` and `tanstack dev --dev-watch` sync loop | 4 |
24
25## Failure Mode Inventory
26
27### Create app scaffold (3 failure modes)
28
29| # | Mistake | Priority | Source | Cross-skill? |
30|---|---------|----------|--------|--------------|
31| 1 | Pass `--add-ons` without explicit ids | HIGH | issue #234 | — |
32| 2 | Assume `--no-tailwind` is still supported | HIGH | `packages/cli/src/command-line.ts` | — |
33| 3 | Combine router-only with template/deployment/add-ons | CRITICAL | `packages/cli/src/command-line.ts` | choose-ecosystem-integrations |
34
35### Add add-ons to existing app (4 failure modes)
36
37| # | Mistake | Priority | Source | Cross-skill? |
38|---|---------|----------|--------|--------------|
39| 1 | Run `tanstack add` without `.cta.json` | CRITICAL | `packages/create/src/custom-add-ons/shared.ts` | maintain-custom-addons-dev-watch |
40| 2 | Use invalid add-on id | HIGH | `packages/create/src/add-ons.ts` | — |
41| 3 | Ignore add-on dependency requirements | HIGH | `packages/create/src/add-ons.ts` | — |
42| 4 | Assume old Windows path bug still present | MEDIUM | issue #329 | — |
43
44### Query docs and library metadata (3 failure modes)
45
46| # | Mistake | Priority | Source | Cross-skill? |
47|---|---------|----------|--------|--------------|
48| 1 | Use removed `tanstack mcp` command | CRITICAL | `packages/cli/CHANGELOG.md` | — |
49| 2 | Use invalid library id/version/path for `doc` | HIGH | `packages/cli/src/cli.ts` | — |
50| 3 | Rely on deprecated alias for discovery commands | MEDIUM | issue #93 | — |
51
52### Choose ecosystem integrations (4 failure modes)
53
54| # | Mistake | Priority | Source | Cross-skill? |
55|---|---------|----------|--------|--------------|
56| 1 | Treat ecosystem partner id as add-on id | HIGH | `ecosystem --json` + `--list-add-ons --json` | — |
57| 2 | Skip `--addon-details` for optionized providers | HIGH | `--addon-details prisma --json` | — |
58| 3 | Select multiple exclusive integrations together | HIGH | `packages/create/src/frameworks/*/*/info.json` | — |
59| 4 | Assume router-only supports deployment integration | CRITICAL | `packages/cli/src/command-line.ts` | create-app-scaffold |
60
61### Maintain custom add-ons in dev watch (4 failure modes)
62
63| # | Mistake | Priority | Source | Cross-skill? |
64|---|---------|----------|--------|--------------|
65| 1 | Use `--dev-watch` with `--no-install` | HIGH | `packages/cli/src/dev-watch.ts` | — |
66| 2 | Start dev-watch without valid package entry | HIGH | `packages/cli/src/dev-watch.ts` | — |
67| 3 | Author add-on from code-router project | CRITICAL | `packages/create/src/custom-add-ons/add-on.ts` | — |
68| 4 | Run add-on workflows without scaffold metadata | HIGH | `packages/create/src/custom-add-ons/shared.ts` | add-addons-existing-app |
69
70## Tensions
71
72| Tension | Skills | Agent implication |
73|---------|--------|-------------------|
74| Compatibility mode vs explicit intent | create-app-scaffold ↔ choose-ecosystem-integrations | Agents optimize for successful command execution and miss silently dropped user intent. |
75| Backwards support vs deterministic automation | add-addons-existing-app ↔ maintain-custom-addons-dev-watch | Agents assume universal workflows and fail on hidden metadata preconditions. |
76| 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. |
77
78## Subsystems & Reference Candidates
79
80| Skill | Subsystems | Reference candidates |
81|-------|------------|---------------------|
82| create-app-scaffold | framework adapters, deployment providers, toolchains | create flag compatibility matrix |
83| add-addons-existing-app | — | — |
84| query-docs-library-metadata | — | discovery command output schemas |
85| choose-ecosystem-integrations | authentication providers, data layer providers, deployment targets | — |
86| maintain-custom-addons-dev-watch | — | — |
87
88## Recommended Skill File Structure
89
90- **Core skills:** `create-app-scaffold`, `add-addons-existing-app`, `query-docs-library-metadata`
91- **Framework skills:** none required (framework selection is embedded in scaffold flow)
92- **Lifecycle skills:** `maintain-custom-addons-dev-watch`
93- **Composition skills:** `choose-ecosystem-integrations`
94- **Reference files:** `create-app-scaffold` (flag matrix), `query-docs-library-metadata` (JSON output schemas)
95
96## Composition Opportunities
97
98| Library | Integration points | Composition skill needed? |
99|---------|-------------------|--------------------------|
100| Clerk | auth add-on selection and exclusive auth category | yes — choose-ecosystem-integrations |
101| Better Auth | auth add-on selection and framework/mode compatibility | yes — choose-ecosystem-integrations |
102| WorkOS | auth add-on selection and enterprise auth workflows | yes — choose-ecosystem-integrations |
103| Prisma | ORM add-on with provider options (`postgres/sqlite/mysql`) | yes — choose-ecosystem-integrations |
104| Drizzle | ORM add-on with provider options (`postgresql/sqlite/mysql`) | yes — choose-ecosystem-integrations |
105| Convex | database add-on with exclusivity interactions | yes — choose-ecosystem-integrations |
106| Cloudflare | deployment add-on selection in exclusive deploy category | yes — choose-ecosystem-integrations |
107| Netlify | deployment add-on selection in exclusive deploy category | yes — choose-ecosystem-integrations |
108| Railway | deployment add-on selection in exclusive deploy category | yes — choose-ecosystem-integrations |