Conformance Tasks

xtarterize applies conformance configuration through discrete, independently applicable tasks. Each task detects whether it’s needed and only applies changes if necessary.

Linting & Formatting

Task ID	Description	Applicable When
`lint/biome`	Install Biome, write `biome.json` with framework-aware parser options	Always (TS/JS projects)

Framework-Aware Biome Config

When Tailwind CSS is detected, the generated biome.json includes:

{
  "css": {
    "parser": {
      "tailwindDirectives": true
    }
  }
}

This enables Biome to parse Tailwind v4 directives like @theme without errors. See css.parser.tailwindDirectives in Biome’s configuration reference.

TypeScript

Task ID	Description	Applicable When
`ts/strict`	Patch `tsconfig.json` with `strict: true` (skips if explicitly `false`)	TypeScript detected
`ts/paths`	Patch `tsconfig.json` with `baseUrl` and `paths` aliases (`@/` → `./src/`)	TypeScript detected
`ts/incremental`	Patch `tsconfig.json` with `incremental: true` and `tsBuildInfoFile: ".tsbuildinfo"`	TypeScript detected
`gitignore/tsbuildinfo`	Add `*.tsbuildinfo` and `.tsbuildinfo/` to `.gitignore`	TypeScript detected

Vite Plugins

Task ID	Description	Applicable When
`vite/checker`	Inject `vite-plugin-checker` (`checker()`) into `vite.config.ts` via AST	Bundler is Vite
`vite/visualizer`	Inject `rollup-plugin-visualizer` (`visualizer()`) into `vite.config.ts` via AST	Bundler is Vite

CI/CD

Task ID	Description	Applicable When
`ci/release`	Write `.github/workflows/release.yml` — triggers on `push.tags`	GitHub detected
`ci/auto-update`	Write `.github/workflows/auto-update.yml` — `schedule.cron` for weekly dependency updates	GitHub detected
`ci/ci`	Write `.github/workflows/ci.yml` — lint, typecheck, test on `pull_request`	GitHub detected

Conditional pnpm Setup

For projects using pnpm, CI workflows automatically include pnpm/action-setup@v4 with package_json_file before actions/setup-node@v6. This ensures reproducible pnpm versions across runs. npm and yarn projects are unaffected.

Dependencies

Task ID	Description	Applicable When
`deps/renovate`	Write `renovate.json` with `extends: ["config:base"]`, `automerge`, and `stabilityDays: 2`	Always

Release

Task ID	Description	Applicable When
`release/commitlint`	Install commitlint with `@commitlint/config-conventional`, write `commitlint.config.ts`	Git detected
`release/czg`	Install czg (Commitizen adapter), add `commit` script to `package.json`	Always
`release/cat-version`	Install commit-and-tag-version, write `.versionrc`	Always
`release/git-hooks`	Install simple-git-hooks, wire `commit-msg` hook to commitlint, add `prepare` script	Always

Code Quality

Task ID	Description	Applicable When
`quality/knip`	Install Knip, write `knip.json` with framework-aware `entry` and `project` paths	Always (JSON format if no TypeScript)
`quality/lint-staged`	Install lint-staged, write `.lintstagedrc.json` running Biome on staged files	Always

Code Generation

Task ID	Description	Applicable When
`codegen/plop`	Install Plop, write `plopfile.ts` with framework-specific generators	Always

Monorepo

Task ID	Description	Applicable When
`monorepo/turbo`	Install Turborepo, write `turbo.json` with `pipeline` for build/lint/test	Monorepo detected

Editor

Task ID	Description	Applicable When
`editor/editorconfig`	Write `.editorconfig` with consistent indentation, charset, and line endings	Always
`editor/vscode`	Write/merge `.vscode/settings.json` and `.vscode/extensions.json`	Always

Additive Extension Merging

When .vscode/extensions.json already exists, xtarterize adds its recommended extensions to your existing recommendations array rather than replacing them. Your custom extensions are always preserved.

Agent

Task ID	Description	Applicable When
`agent/agents-md`	Write `AGENTS.md` with framework-specific AI agent instructions	Always
`agent/skills`	Scaffold `.agents/skills/` directory with project context	TypeScript detected
`agent/skills-install`	Install relevant agent skills via `npx skills@latest add` for your stack	TypeScript detected

Skills Install

The agent/skills-install task automatically installs agent skills from the open ecosystem based on your detected stack. It reads your existing skills-lock.json and local skill directories to avoid reinstalling already-present skills.

Stack	Skills Installed
Web Frontend (all browser/edge projects)	`frontend-design`, `web-design-guidelines`, `baseline-ui`, `fixing-accessibility`, `fixing-metadata`, `fixing-motion-performance`
React (including Next.js)	`vercel-react-best-practices`, `vercel-composition-patterns`, `react-dev`, `react-useeffect`
Next.js	`next-best-practices`, `next-cache-components`, `next-upgrade`
Vue	`vue`, `vue-best-practices`
Nuxt	`nuxt`
Expo / React Native	`expo-tailwind-setup`, `expo-cicd-workflows`, `expo-deployment`, `expo-dev-client`, `building-native-ui`, `native-data-fetching`, `expo-module`, `upgrading-expo`, `vercel-react-native-skills`
Shadcn UI	`shadcn`
Ultracite	`ultracite`
Vite	`vite`
Vitest	`vitest`
tsdown	`tsdown`
Turborepo	`turborepo`
Supabase / Postgres	`supabase-postgres-best-practices`
Drizzle	`postgres-drizzle`
Redis	`redis-best-practices`
Better Auth	`better-auth-best-practices`, `create-auth-skill`
AI SDK	`ai-sdk`
Remotion	`remotion-best-practices`

Scripts

Task ID	Description	Applicable When
`scripts/package-scripts`	Patch `package.json` `scripts` with `lint`, `format`, `typecheck`, etc.	Always
`scripts/nvmrc`	Write `.nvmrc` with `lts/*` to pin Node.js version	Always
`scripts/npmrc`	Write `.npmrc` with `save-exact`, `strict-peer-dependencies`, and `auto-install-peers`	Always

Idempotency

Each task implements check(), dryRun(), and apply():

check() — Returns new, patch, skip, or conflict based on current state
dryRun() — Returns exact diffs without writing anything
apply() — Writes changes, backing up files first

Smart Equivalence Detection

xtarterize doesn’t just check key names — it also detects when an equivalent value already exists under a different key. This prevents redundant entries:

Scenario	Existing	xtarterize Action
Script name alias	`"type:check": "tsc --noEmit"`	Skips adding `"typecheck": "tsc --noEmit"`
Config extends format	`"extends": "config:base"`	Treats same as `"extends": ["config:base"]`
VS Code extensions	`["biomejs.biome"]`	Adds `"ms-vscode.vscode-typescript-next"`, keeps existing

If the exact same command, value, or configuration already exists somewhere, xtarterize skips adding a duplicate.

Task Gating

Tasks only run when their conditions are met:

Vite plugin tasks only run when bundler === 'vite'
Monorepo tasks only run when monorepo === true
CI tasks only run when hasGitHub === true
TypeScript tasks only run when typescript === true

References