docs(skills): add domain map and skill spec artifacts

Author: tannerlinsley

domain_map.yaml

@@ -0,0 +1,284 @@
+# domain_map.yaml
+# Generated by skill-domain-discovery
+# Library: TanStack CLI
+# Version: 0.61.0
+# Date: 2026-03-02
+# Status: reviewed
+
+library:
+  name: "@tanstack/cli"
+  version: "0.61.0"
+  repository: "https://github.com/TanStack/cli"
+  description: "CLI for scaffolding TanStack apps, adding add-ons, and retrieving machine-readable TanStack/ecosystem context."
+  primary_framework: "framework-agnostic"
+
+domains:
+  - name: "Scaffold new applications"
+    slug: "scaffold-new-applications"
+    description: "Choosing mode/framework/template/add-ons/toolchain/deployment and generating the initial project."
+  - name: "Evolve existing applications"
+    slug: "evolve-existing-applications"
+    description: "Applying add-ons to an existing repo while preserving and extending current project structure."
+  - name: "Fetch support context for agents"
+    slug: "fetch-support-context"
+    description: "Using CLI discovery/doc commands to retrieve structured context for support and coding agents."
+  - name: "Select ecosystem integrations"
+    slug: "select-ecosystem-integrations"
+    description: "Translating ecosystem partner data and add-on metadata into concrete integration choices."
+  - name: "Author and iterate custom extensions"
+    slug: "author-custom-extensions"
+    description: "Building and live-iterating custom add-ons/templates and syncing generated outputs during development."
+
+skills:
+  - name: "Create app scaffold"
+    slug: "create-app-scaffold"
+    domain: "scaffold-new-applications"
+    description: "Scaffold a new app with the right mode/framework/template/toolchain/deployment/add-on combination."
+    type: "core"
+    covers:
+      - "tanstack create"
+      - "--framework"
+      - "--template / --template-id"
+      - "--toolchain"
+      - "--deployment"
+      - "--add-ons"
+      - "--router-only"
+    tasks:
+      - "Create a React or Solid app with selected add-ons"
+      - "Create router-only compatibility scaffold"
+      - "Generate app from local or remote template"
+    subsystems:
+      - name: "Framework adapters"
+        package: "@tanstack/create"
+        config_surface: "framework id (react/solid) and mode compatibility"
+      - name: "Deployment providers"
+        package: "@tanstack/create"
+        config_surface: "exclusive deploy add-ons (cloudflare/netlify/railway/nitro)"
+      - name: "Toolchains"
+        package: "@tanstack/create"
+        config_surface: "exclusive linter choice (eslint/biome)"
+    reference_candidates:
+      - topic: "create flag compatibility matrix"
+        reason: "Many interacting flags and compatibility branches (router-only/template/add-ons/deployment/toolchain)."
+    failure_modes:
+      - mistake: "Pass --add-ons without explicit ids"
+        mechanism: "In non-interactive runs this can complete without selecting add-ons, so output differs from user intent."
+        source: "https://github.com/TanStack/cli/issues/234"
+        priority: "HIGH"
+        status: "fixed-but-legacy-risk"
+        version_context: "Observed in older releases and still generated by agents trained on older examples."
+      - mistake: "Assume --no-tailwind is still supported"
+        mechanism: "Tailwind opt-out flags are deprecated/ignored, so generated scaffold still includes Tailwind and requires manual cleanup."
+        source: "packages/cli/src/command-line.ts"
+        priority: "HIGH"
+        status: "active"
+        version_context: "Current behavior; maintainers recommend scaffold then remove Tailwind manually."
+      - mistake: "Combine router-only with template/deployment/add-ons"
+        mechanism: "Router-only compatibility mode silently ignores template, deployment, and add-on intents and proceeds with base scaffold."
+        source: "packages/cli/src/command-line.ts"
+        priority: "CRITICAL"
+        status: "active"
+        version_context: "Current behavior; maintainer preference is proceed and explicitly drop incompatible intents."
+        skills: ["create-app-scaffold", "choose-ecosystem-integrations"]
+    compositions:
+      - library: "Cloudflare"
+        skill: "choose-ecosystem-integrations"
+      - library: "Netlify"
+        skill: "choose-ecosystem-integrations"
+      - library: "Railway"
+        skill: "choose-ecosystem-integrations"
+
+  - name: "Add add-ons to existing app"
+    slug: "add-addons-existing-app"
+    domain: "evolve-existing-applications"
+    description: "Apply one or more add-ons to an existing project and reconcile file/package changes."
+    type: "core"
+    covers:
+      - "tanstack add"
+      - "@tanstack/create addToApp"
+      - ".cta.json persisted project options"
+      - "add-on dependency resolution"
+    tasks:
+      - "Add auth/database/tooling add-ons to an existing app"
+      - "Resolve add-on dependency chains"
+      - "Handle add-on option defaults and prompts"
+    failure_modes:
+      - mistake: "Run tanstack add without .cta.json"
+        mechanism: "Older or non-CLI projects fail because persisted scaffold metadata is required to reconstruct options."
+        source: "packages/create/src/custom-add-ons/shared.ts"
+        priority: "CRITICAL"
+        status: "active"
+        version_context: "Still supported for now but likely to be replaced by skills/playbook-led approach (maintainer interview)."
+        skills: ["add-addons-existing-app", "maintain-custom-addons-dev-watch"]
+      - mistake: "Use invalid add-on id"
+        mechanism: "Resolution throws add-on not found (with suggestion), blocking apply flow until corrected id is provided."
+        source: "packages/create/src/add-ons.ts"
+        priority: "HIGH"
+        status: "active"
+        version_context: "Current behavior."
+      - mistake: "Ignore add-on dependency requirements"
+        mechanism: "Selecting add-ons without required dependencies can trigger dependency-not-found failures during finalization."
+        source: "packages/create/src/add-ons.ts"
+        priority: "HIGH"
+        status: "active"
+        version_context: "Current behavior; common with custom/remote add-ons."
+      - mistake: "Assume old Windows path bug still present"
+        mechanism: "Agents may avoid tanstack add on Windows due to old path resolution failures that were fixed in later versions."
+        source: "https://github.com/TanStack/cli/issues/329"
+        priority: "MEDIUM"
+        status: "fixed-but-legacy-risk"
+        version_context: "Fixed after issue #329; older snippets still circulate."
+    compositions:
+      - library: "Clerk"
+        skill: "choose-ecosystem-integrations"
+      - library: "Drizzle"
+        skill: "choose-ecosystem-integrations"
+      - library: "Prisma"
+        skill: "choose-ecosystem-integrations"
+
+  - name: "Query docs and library metadata"
+    slug: "query-docs-library-metadata"
+    domain: "fetch-support-context"
+    description: "Use CLI discovery commands to retrieve machine-readable TanStack docs/library information for agents and support."
+    type: "core"
+    covers:
+      - "tanstack libraries --json"
+      - "tanstack doc"
+      - "tanstack search-docs --json"
+      - "tanstack create --list-add-ons --json"
+      - "tanstack create --addon-details --json"
+    tasks:
+      - "Enumerate TanStack libraries and versions"
+      - "Fetch a specific docs page in markdown"
+      - "Search docs for a targeted implementation topic"
+    reference_candidates:
+      - topic: "discovery command output schemas"
+        reason: "Multiple JSON payload shapes consumed by agents (libraries, docs pages, search hits, add-on metadata)."
+    failure_modes:
+      - mistake: "Use removed tanstack mcp command"
+        mechanism: "Command no longer exists, so agent setup scripts based on older docs fail and provide no tools."
+        source: "packages/cli/CHANGELOG.md"
+        priority: "CRITICAL"
+        status: "removed"
+        version_context: "Removed in v0.52.0; legacy examples still appear in historical threads."
+      - mistake: "Use invalid library id/version/path for doc fetch"
+        mechanism: "doc command throws explicit not-found errors when id/version/path does not match registry metadata."
+        source: "packages/cli/src/cli.ts"
+        priority: "HIGH"
+        status: "active"
+        version_context: "Current behavior."
+      - mistake: "Rely on deprecated create alias for discovery"
+        mechanism: "Older alias-based invocations (eg create-tsrouter-app --list-add-ons) have produced confusing or empty outputs."
+        source: "https://github.com/TanStack/cli/issues/93"
+        priority: "MEDIUM"
+        status: "fixed-but-legacy-risk"
+        version_context: "Resolved, but agent corpora still include old alias patterns."
+
+  - name: "Choose ecosystem integrations"
+    slug: "choose-ecosystem-integrations"
+    domain: "select-ecosystem-integrations"
+    description: "Use ecosystem and add-on metadata to choose compatible auth/database/deployment/tooling integrations for a target scaffold."
+    type: "composition"
+    covers:
+      - "tanstack ecosystem --json"
+      - "tanstack create --list-add-ons --json"
+      - "tanstack create --addon-details <id> --json"
+      - "add-on category/exclusive/dependsOn/option surfaces"
+    tasks:
+      - "Map user requirements to candidate ecosystem partners"
+      - "Translate partner choice to concrete add-on ids"
+      - "Resolve exclusive categories and option prompts before create/add"
+    subsystems:
+      - name: "Authentication providers"
+        package: "@tanstack/create"
+        config_surface: "exclusive auth add-ons (clerk/workos/better-auth)"
+      - name: "Data layer providers"
+        package: "@tanstack/create"
+        config_surface: "database/orm exclusivity and optionized providers (prisma/drizzle/convex/neon)"
+      - name: "Deployment targets"
+        package: "@tanstack/create"
+        config_surface: "exclusive deploy target selection"
+    failure_modes:
+      - mistake: "Treat ecosystem partner id as add-on id"
+        mechanism: "ecosystem output includes partners not installable as CLI add-ons, leading to add-on-not-found errors later."
+        source: "tanstack ecosystem --json output + tanstack create --list-add-ons --json output"
+        priority: "HIGH"
+        status: "active"
+        version_context: "Current behavior; requires explicit mapping step."
+      - mistake: "Skip addon-details before choosing provider"
+        mechanism: "Optionized add-ons (eg prisma/drizzle database provider) default silently, producing wrong DB stack for the intended integration."
+        source: "tanstack create --addon-details prisma --json"
+        priority: "HIGH"
+        status: "active"
+        version_context: "Current behavior with option defaults."
+      - mistake: "Select multiple exclusive integrations together"
+        mechanism: "Combining providers from exclusive categories causes one choice to be dropped/replaced, diverging from explicit intent."
+        source: "packages/create/src/frameworks/*/*/info.json"
+        priority: "HIGH"
+        status: "active"
+        version_context: "Current add-on metadata model uses exclusive categories."
+      - mistake: "Assume router-only supports deployment integration"
+        mechanism: "In router-only compatibility mode deployment intent is ignored, so ecosystem choice never lands in generated output."
+        source: "packages/cli/src/command-line.ts"
+        priority: "CRITICAL"
+        status: "active"
+        version_context: "Current behavior."
+        skills: ["choose-ecosystem-integrations", "create-app-scaffold"]
+
+  - name: "Maintain custom add-ons in dev watch"
+    slug: "maintain-custom-addons-dev-watch"
+    domain: "author-custom-extensions"
+    description: "Initialize, compile, and live-watch custom add-ons/templates while syncing generated assets into a target app."
+    type: "lifecycle"
+    covers:
+      - "tanstack add-on init"
+      - "tanstack add-on compile"
+      - "tanstack add-on dev"
+      - "tanstack dev --dev-watch"
+      - "FileSyncer sync/delete behavior"
+    tasks:
+      - "Bootstrap custom add-on metadata and compiled output"
+      - "Run continuous add-on rebuild while editing source files"
+      - "Sync watched package output into local target app"
+    failure_modes:
+      - mistake: "Use --dev-watch with --no-install"
+        mechanism: "The command throws because dev watch requires installation to validate and execute watched package output."
+        source: "packages/cli/src/dev-watch.ts"
+        priority: "HIGH"
+        status: "active"
+        version_context: "Current behavior."
+      - mistake: "Start dev-watch without valid package entry"
+        mechanism: "Missing watch path/package.json/entrypoint fails early with setup errors before sync loop starts."
+        source: "packages/cli/src/dev-watch.ts"
+        priority: "HIGH"
+        status: "active"
+        version_context: "Current behavior."
+      - mistake: "Author add-on from code-router project"
+        mechanism: "Custom add-on init exits because add-on authoring expects file-router project mode."
+        source: "packages/create/src/custom-add-ons/add-on.ts"
+        priority: "CRITICAL"
+        status: "active"
+        version_context: "Current behavior."
+      - mistake: "Run add-on workflows without scaffold metadata"
+        mechanism: "Custom add-on/template workflows depend on .cta.json and fail in projects lacking persisted options."
+        source: "packages/create/src/custom-add-ons/shared.ts"
+        priority: "HIGH"
+        status: "active"
+        version_context: "Current behavior; may be replaced in future architecture."
+        skills: ["maintain-custom-addons-dev-watch", "add-addons-existing-app"]
+
+tensions:
+  - name: "Compatibility mode vs explicit intent"
+    skills: ["create-app-scaffold", "choose-ecosystem-integrations"]
+    description: "Router-only compatibility keeps legacy flows easy but silently drops template/deployment/add-on intent."
+    implication: "Agents optimize for command success and miss that requested integrations were never applied."
+  - name: "Backwards support vs deterministic automation"
+    skills: ["add-addons-existing-app", "maintain-custom-addons-dev-watch"]
+    description: "Legacy .cta.json-based support helps old projects but creates hidden preconditions for automation."
+    implication: "Agents assume add/author flows are universal and fail when metadata preconditions are absent."
+  - name: "Single-command convenience vs integration precision"
+    skills: ["create-app-scaffold", "query-docs-library-metadata", "choose-ecosystem-integrations"]
+    description: "Fast scaffolding encourages one-shot commands, while robust integration requires preflight metadata discovery."
+    implication: "Agents skip discovery and produce plausible defaults that do not match user architecture constraints."
+
+gaps: []