domain_map.yaml

# 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: []