Project Detection

Detection is the first step in every xtarterize command. It reads the project directory and builds a project profile that drives which conformance tasks apply.

What the profile contains

• Framework and framework version, bundler, router, and styling
• TypeScript usage, runtime target, and Node version
• Package manager and whether the project uses Vite+
• Monorepo status, monorepo tool, and whether the current directory is the workspace root
• Git and GitHub presence
• Existing configuration files, such as Biome, ESLint, tsconfig, Renovate, commitlint, knip, Vite config, and GitHub workflows

How detection works

Detection runs on every invocation; there is no profile cache. Each run inspects package.json, root config files, lockfiles, config directories, and ancestor markers, then computes a fresh profile.

Signals come from two sources:

• Dependencies: framework, bundler, router, and styling packages in package.json
• Filesystem: TypeScript config presence, lockfiles, monorepo markers, bundler config files, and a .github/ directory

Framework, router, styling, runtime, and Vite+ detection run inline. Bundler, monorepo, and package manager detection consume shared declarations from the detection registry, which also supplies lockfile checks for diagnostics. New keyed detectors belong in the registry.

Precedence and edge cases

When both react and react-native (or expo) are present in dependencies, detection reports react-native; there is no prompt to disambiguate. The framework is null only when the project has no package.json.

workspaceRoot is true when the current directory contains monorepo markers such as pnpm-workspace.yaml or turbo.json. It is false inside a workspace package discovered by walking up parent directories. In non-monorepos it matches monorepo.

Detection stays a plain async function and does not compose Effects. The engine lifts it at the nearest orchestration seam.

See the configuration guide for the user-facing detection summary.