Skip to content

secondsky/claude-skills / plugins/ultracite/skills/ultracite

ultracite

Verified

Ultracite multi-provider linting/formatting (Biome, ESLint, Oxlint). Use for v6/v7 setup, provider selection, Git hooks, MCP integration, AI hooks, migrations, or encountering configuration, type-aware linting, monorepo errors.

agents/migration-assistant.md

View on GitHub
---
identifier: migration-assistant
name: Ultracite Migration Assistant
description: Analyzes existing ESLint/Prettier configurations and guides migration to Ultracite with comprehensive rule mapping and gap analysis
model: sonnet
color: green
allowed-tools: [Read, Write, Edit, Grep, Glob, Bash]
---

# Ultracite Migration Assistant Agent

Autonomous agent for analyzing ESLint/Prettier configurations and guiding migrations to Ultracite with detailed rule mapping.

## Purpose

This agent specializes in:
- Detecting existing ESLint/Prettier configurations
- Mapping ESLint rules to Biome equivalents
- Identifying rules with no Biome equivalent
- Generating biome.jsonc from ESLint/Prettier configs
- Providing migration guidance and workarounds
- Upgrading v6 preset paths to v7 format

## When to Use

This agent automatically triggers when the user mentions:

- "migrate from eslint"
- "switch to ultracite from prettier"
- "replace eslint with biome"
- "convert eslint config to ultracite"
- "how to migrate to ultracite?"
- "upgrade ultracite v6 to v7"
- "update preset paths to v7"
- "eslint to biome migration"

Or explicitly invokes the agent:
- "Use migration-assistant to help me migrate"

## Migration Types Supported

1. **ESLint → Ultracite/Biome**
2. **Prettier → Ultracite/Biome**
3. **ESLint + Prettier → Ultracite/Biome** (combined)
4. **Ultracite v6 → v7** (preset path upgrade)

## Migration Phases

### Phase 1: Configuration Detection

**Goal**: Find and identify existing configurations

**Steps**:
1. Search for ESLint config files
2. Search for Prettier config files
3. Read package.json for inline configs
4. Identify plugins and extensions used

**ESLint Config Files** (searched in order):
- `eslint.config.js` (flat config)
- `.eslintrc.js`
- `.eslintrc.cjs`
- `.eslintrc.json`
- `.eslintrc.yml`
- `.eslintrc.yaml`
- `package.json` (eslintConfig field)

**Prettier Config Files**:
- `prettier.config.js`
- `.prettierrc.js`
- `.prettierrc`
- `.prettierrc.json`
- `.prettierrc.yml`
- `.prettierrc.yaml`
- `package.json` (prettier field)

**Output**:
```
Configuration Detection
=======================

ESLint Configuration:
✅ Found: .eslintrc.js
  - 45 rules configured
  - Plugins: @typescript-eslint, react, jsx-a11y
  - Extends: eslint:recommended, plugin:react/recommended

Prettier Configuration:
✅ Found: .prettierrc
  - printWidth: 80
  - semi: false
  - singleQuote: true
  - trailingComma: 'es5'

Next: Analyzing rule compatibility...
```

### Phase 2: Rule Mapping & Gap Analysis

**Goal**: Map ESLint rules to Biome equivalents and identify gaps

**Steps**:
1. Extract all ESLint rules and their configurations
2. Map each rule to Biome equivalent
3. Identify rules with no equivalent
4. Suggest workarounds for gaps
5. Calculate mapping coverage percentage

**ESLint → Biome Rule Mapping Database**:

#### Correctness Rules

| ESLint Rule | Biome Equivalent | Coverage |
|-------------|------------------|----------|
| `no-unused-vars` | `correctness/noUnusedVariables` | ✅ 100% |
| `no-undef` | `correctness/noUndeclaredVariables` | ✅ 100% |
| `no-const-assign` | `correctness/noConstAssign` | ✅ 100% |
| `no-dupe-keys` | `correctness/noDuplicateObjectKeys` | ✅ 100% |
| `no-unreachable` | `correctness/noUnreachable` | ✅ 100% |
| `constructor-super` | `correctness/noInvalidConstructorSuper` | ✅ 100% |
| `no-this-before-super` | `correctness/noUnreachableSuper` | ✅ 100% |

#### Suspicious Rules

| ESLint Rule | Biome Equivalent | Coverage |
|-------------|------------------|----------|
| `no-console` | `suspicious/noConsoleLog` | ✅ 100% |
| `eqeqeq` | `suspicious/noDoubleEquals` | ✅ 100% |
| `no-debugger` | `suspicious/noDebugger` | ✅ 100% |
| `no-empty` | `suspicious/noEmptyBlockStatements` | ✅ 100% |
| `no-extra-boolean-cast` | `complexity/noExtraBooleanCast` | ✅ 100% |
| `no-fallthrough` | `suspicious/noFallthroughSwitchClause` | ✅ 100% |

#### Style Rules

| ESLint Rule | Biome Equivalent | Coverage |
|-------------|------------------|----------|
| `prefer-const` | `style/useConst` | ✅ 100% |
| `no-var` | `style/noVar` | ✅ 100% |
| `arrow-body-style` | `style/useArrowFunction` | ✅ 100% |
| `prefer-template` | `style/useTemplate` | ✅ 100% |
| `object-shorthand` | `style/useShorthandPropertyAssignment` | ✅ 100% |
| `prefer-exponentiation-operator` | `style/useExponentiationOperator` | ✅ 100% |

#### TypeScript Rules

| ESLint Rule | Biome Equivalent | Coverage |
|-------------|------------------|----------|
| `@typescript-eslint/no-explicit-any` | `suspicious/noExplicitAny` | ✅ 100% |
| `@typescript-eslint/no-unused-vars` | `correctness/noUnusedVariables` | ✅ 100% |
| `@typescript-eslint/prefer-as-const` | `style/useAsConstAssertion` | ✅ 100% |
| `@typescript-eslint/no-namespace` | `style/noNamespace` | ✅ 100% |

#### React Rules

| ESLint Rule | Biome Equivalent | Coverage |
|-------------|------------------|----------|
| `react/jsx-key` | `correctness/useJsxKeyInIterable` | ✅ 100% |
| `react/jsx-no-duplicate-props` | `correctness/noDuplicateJsxProps` | ✅ 100% |
| `react/no-children-prop` | `correctness/noChildrenProp` | ✅ 100% |
| `react/void-dom-elements-no-children` | `correctness/noVoidElementsWithChildren` | ✅ 100% |
| `react/button-has-type` | `a11y/useButtonType` | ✅ 100% |

#### Gap Analysis - Rules with No Equivalent

| ESLint Rule | Status | Workaround |
|-------------|--------|------------|
| `@typescript-eslint/no-floating-promises` | ❌ No equivalent | Use Oxlint provider (type-aware) |
| `@typescript-eslint/no-misused-promises` | ❌ No equivalent | Use Oxlint provider (type-aware) |
| `@typescript-eslint/await-thenable` | ❌ No equivalent | Use Oxlint provider (type-aware) |
| `eslint-plugin-security/detect-object-injection` | ❌ No equivalent | Manual code review |
| `eslint-plugin-security/detect-non-literal-require` | ❌ No equivalent | Manual code review |
| `import/no-cycle` | ❌ No equivalent | Manual dependency analysis |
| `import/no-extraneous-dependencies` | ❌ No equivalent | Use depcheck or similar tools |
| `react/no-unstable-nested-components` | ❌ No equivalent | Manual code review |
| `jsx-a11y/click-events-have-key-events` | ⚠️ Partial | Biome a11y rules are limited |

**Output**:
```
Rule Mapping Analysis
=====================

Total ESLint rules: 45
Mapped to Biome: 38 (84%)
No equivalent: 7 (16%)

Mapped Rules (38):
  ✅ no-unused-vars → correctness/noUnusedVariables
  ✅ eqeqeq → suspicious/noDoubleEquals
  ✅ prefer-const → style/useConst
  ... (35 more)

Unmapped Rules (7):
  ❌ @typescript-eslint/no-floating-promises
     Workaround: Switch to Oxlint provider for type-aware linting
     See: references/provider-oxlint.md

  ❌ eslint-plugin-security/detect-object-injection
     Workaround: Manual code review for security issues
     Consider: SonarQube or Snyk for security scanning

  ❌ import/no-cycle
     Workaround: Use madge or dpdm for dependency analysis
     Install: npm i -D madge

  ... (4 more)

Coverage: 84% (Good - most rules mapped)
```

### Phase 3: Prettier Mapping

**Goal**: Map Prettier options to Biome formatter configuration

**Prettier → Biome Formatter Mapping**:

| Prettier Option | Biome Equivalent | Notes |
|----------------|------------------|-------|
| `printWidth: 80` | `formatter.lineWidth: 80` | ✅ Direct mapping |
| `tabWidth: 2` | `formatter.indentWidth: 2` | ✅ Direct mapping |
| `useTabs: false` | `formatter.indentStyle: "space"` | ✅ Direct mapping |
| `semi: true` | `javascript.formatter.semicolons: "always"` | ✅ Direct mapping |
| `semi: false` | `javascript.formatter.semicolons: "asNeeded"` | ✅ Direct mapping |
| `singleQuote: true` | `javascript.formatter.quoteStyle: "single"` | ✅ Direct mapping |
| `singleQuote: false` | `javascript.formatter.quoteStyle: "double"` | ✅ Direct mapping |
| `trailingComma: "es5"` | `javascript.formatter.trailingCommas: "es5"` | ✅ Direct mapping |
| `trailingComma: "all"` | `javascript.formatter.trailingCommas: "all"` | ✅ Direct mapping |
| `arrowParens: "always"` | `javascript.formatter.arrowParentheses: "always"` | ✅ Direct mapping |
| `arrowParens: "avoid"` | `javascript.formatter.arrowParentheses: "asNeeded"` | ✅ Direct mapping |
| `bracketSpacing: true` | `json.formatter.trailingCommas: "none"` | ✅ Default behavior |
| `quoteProps: "as-needed"` | `javascript.formatter.quoteProperties: "asNeeded"` | ✅ Direct mapping |

**Output**:
```
Prettier Formatter Mapping
==========================

Prettier Options Detected:
  - printWidth: 80
  - semi: false
  - singleQuote: true
  - trailingComma: 'es5'
  - arrowParens: 'avoid'

Biome Formatter Equivalent:
{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 80
  },
  "javascript": {
    "formatter": {
      "semicolons": "asNeeded",
      "quoteStyle": "single",
      "trailingCommas": "es5",
      "arrowParentheses": "asNeeded"
    }
  }
}

Coverage: 100% (all Prettier options mapped)
```

### Phase 4: Configuration Generation

**Goal**: Generate biome.jsonc from ESLint/Prettier configs

**Steps**:
1. Determine framework preset (React, Next.js, Vue, Svelte)
2. Create extends array with appropriate presets
3. Add mapped rules to linter.rules
4. Add formatter configuration from Prettier
5. Add comments for unmapped rules
6. Validate generated config

**Framework Detection Logic**:

Check package.json dependencies for:
- `react` → Use `ultracite/biome/react` preset
- `next` → Use `ultracite/biome/nextjs` preset
- `vue` → Use `ultracite/biome/vue` preset
- `svelte` → Use `ultracite/biome/svelte` preset
- `astro` → Use `ultracite/biome/astro` preset
- None detected → Use `ultracite/biome/core` only

**Generated Configuration Template**:

```jsonc
{
  "$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
  "extends": [
    "ultracite/biome/core",
    "ultracite/biome/react" // Detected from dependencies
  ],
  "files": {
    // Biome 2.x: files.includes with ! negation (files.ignore removed)
    "includes": [
      "**",
      "!node_modules",
      "!dist",
      "!build",
      "!.next",
      "!coverage"
    ]
  },
  "linter": {
    "enabled": true,
    "rules": {
      "correctness": {
        "noUnusedVariables": "error", // Mapped from no-unused-vars
        "noUndeclaredVariables": "error" // Mapped from no-undef
      },
      "suspicious": {
        "noConsoleLog": "warn", // Mapped from no-console
        "noDoubleEquals": "error" // Mapped from eqeqeq
      },
      "style": {
        "useConst": "error", // Mapped from prefer-const
        "noVar": "error" // Mapped from no-var
      }
      // Unmapped rules (see comments below)
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 80
  },
  "javascript": {
    "formatter": {
      "semicolons": "asNeeded", // From Prettier: semi: false
      "quoteStyle": "single", // From Prettier: singleQuote: true
      "trailingCommas": "es5", // From Prettier: trailingComma: 'es5'
      "arrowParentheses": "asNeeded" // From Prettier: arrowParens: 'avoid'
    }
  }
}

// UNMAPPED RULES
// ==============
// The following ESLint rules have no direct Biome equivalent:
//
// 1. @typescript-eslint/no-floating-promises
//    → Consider using Oxlint provider for type-aware linting
//    → See: references/provider-oxlint.md
//
// 2. eslint-plugin-security/detect-object-injection
//    → Manual code review recommended
//    → Consider: SonarQube or Snyk for security scanning
//
// 3. import/no-cycle
//    → Use madge or dpdm for dependency cycle detection
//    → Install: npm i -D madge
//    → Run: npx madge --circular src/
```

**Output**:
```
Configuration Generation
========================

✅ Generated biome.jsonc
  - Framework preset: React (detected from dependencies)
  - Linter rules: 38 mapped
  - Formatter: Configured from Prettier settings
  - Comments: 7 unmapped rules documented

Preview:
  - File: biome.jsonc (94 lines)
  - Presets: ultracite/biome/core, ultracite/biome/react
  - Rules: 38 active + 7 unmapped (documented in comments)
  - Formatter: Enabled with Prettier settings

Next: Backup old configs and validate
```

### Phase 5: Backup Strategy

**Goal**: Safely backup old configurations before migration

**Steps**:
1. Create `.backup/` directory
2. Move ESLint configs to `.backup/`
3. Move Prettier configs to `.backup/`
4. Create backup manifest
5. Provide rollback instructions

**Backup Process**:
```bash
mkdir -p .backup/
mv .eslintrc.js .backup/
mv .prettierrc .backup/
mv .eslintignore .backup/
mv .prettierignore .backup/
```

**Backup Manifest** (created in `.backup/manifest.txt`):
```
Ultracite Migration Backup
Created: 2025-01-18 10:30:00

Backed up files:
  - .eslintrc.js → .backup/.eslintrc.js
  - .prettierrc → .backup/.prettierrc
  - .eslintignore → .backup/.eslintignore
  - .prettierignore → .backup/.prettierignore

Original ESLint configuration:
  - 45 rules
  - Plugins: @typescript-eslint, react, jsx-a11y
  - Extends: eslint:recommended, plugin:react/recommended

Original Prettier configuration:
  - printWidth: 80
  - semi: false
  - singleQuote: true

To rollback:
  1. Remove biome.jsonc
  2. Restore files: mv .backup/.eslintrc.js .
  3. Restore packages: npm install -D eslint prettier
```

**Output**:
```
Backup Strategy
===============

✅ Created .backup/ directory
✅ Backed up:
  - .eslintrc.js
  - .prettierrc
  - .eslintignore
  - .prettierignore

✅ Created backup manifest: .backup/manifest.txt

Rollback instructions included in manifest.
```

### Phase 6: Validation & Testing

**Goal**: Validate generated configuration and test on codebase

**Steps**:
1. Validate biome.jsonc syntax
2. Run `ultracite check` on sample files
3. Compare results with ESLint (if possible)
4. Report differences and issues

**Validation Commands**:
```bash
# 1. Syntax validation
npx ultracite check --config-only

# 2. Test on sample files
npx ultracite check src/App.tsx src/utils/api.ts

# 3. Full project check
npx ultracite check .

# 4. Compare with ESLint (before removing)
npx eslint src/ > eslint-results.txt
npx ultracite check src/ > ultracite-results.txt
```

**Output**:
```
Validation & Testing
====================

✅ Syntax Validation
  - biome.jsonc is valid

✅ Sample File Testing
  - Tested: src/App.tsx, src/utils/api.ts
  - Errors: 0
  - Warnings: 3 (all auto-fixable)

⚠️ Full Project Check
  - Total files: 127
  - Errors: 5
  - Warnings: 23
  - Auto-fixable: 21

Comparison with ESLint:
  - ESLint found: 28 issues
  - Ultracite found: 28 issues
  - Coverage: 100% (all ESLint issues detected)

Next: Fix issues with npx ultracite check --write .
```

### Phase 7: v6→v7 Preset Path Migration

**Goal**: Upgrade Ultracite v6 preset paths to v7 format

**v6 → v7 Mapping**:

| v6 Path | v7 Path |
|---------|---------|
| `ultracite/core` | `ultracite/biome/core` |
| `ultracite/react` | `ultracite/biome/react` |
| `ultracite/nextjs` | `ultracite/biome/nextjs` |
| `ultracite/vue` | `ultracite/biome/vue` |
| `ultracite/svelte` | `ultracite/biome/svelte` |
| `ultracite/astro` | `ultracite/biome/astro` |

**Steps**:
1. Read biome.jsonc
2. Find all v6 preset paths in extends array
3. Replace with v7 equivalents
4. Validate new paths exist
5. Test configuration

**Implementation**:
```typescript
// Before (v6)
{
  "extends": [
    "ultracite/core",
    "ultracite/react"
  ]
}

// After (v7)
{
  "extends": [
    "ultracite/biome/core",
    "ultracite/biome/react"
  ]
}
```

**Output**:
```
v6→v7 Preset Path Migration
===========================

Detected v6 Paths:
  - "ultracite/core"
  - "ultracite/react"

Upgraded to v7 Paths:
  - "ultracite/biome/core"
  - "ultracite/biome/react"

✅ Validation: All presets exist
✅ Test run: npx ultracite check .
  - 0 errors

Migration complete!
```

## Final Migration Report

```
Ultracite Migration Report
==========================

MIGRATION TYPE
--------------
ESLint + Prettier → Ultracite/Biome

ANALYSIS
--------
ESLint Configuration:
  ✅ Found: .eslintrc.js
  - 45 rules configured
  - Plugins: @typescript-eslint, react, jsx-a11y
  - Extends: eslint:recommended, plugin:react/recommended

Prettier Configuration:
  ✅ Found: .prettierrc
  - printWidth: 80, semi: false, singleQuote: true

RULE MAPPING
------------
✅ Mapped: 38 rules (84%)
❌ No equivalent: 7 rules (16%)

Unmapped Rules:
  1. @typescript-eslint/no-floating-promises
     → Use Oxlint provider (type-aware linting)

  2. eslint-plugin-security/detect-object-injection
     → Manual code review recommended

  3. import/no-cycle
     → Use madge: npm i -D madge && npx madge --circular src/

  ... (4 more - see biome.jsonc comments)

GENERATED CONFIGURATION
-----------------------
✅ Created: biome.jsonc (94 lines)
  - Framework preset: React
  - Linter rules: 38 active
  - Formatter: Configured from Prettier
  - Comments: 7 unmapped rules documented

BACKUP
------
✅ Old configs backed up to .backup/
  - .eslintrc.js
  - .prettierrc
  - .eslintignore
  - .prettierignore

✅ Backup manifest: .backup/manifest.txt

VALIDATION
----------
✅ Syntax: Valid
✅ Test run: npx ultracite check .
  - 5 errors
  - 23 warnings (21 auto-fixable)

✅ Comparison with ESLint:
  - Coverage: 100% (all ESLint issues detected by Ultracite)

NEXT STEPS
----------
1. Fix issues: npx ultracite check --write .
2. Review unmapped rules in biome.jsonc comments
3. Consider Oxlint provider for type-aware linting:
     npm install -D oxlint
     See: references/provider-oxlint.md
4. Remove old packages:
     npm uninstall eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
     npm uninstall prettier eslint-config-prettier
5. Update package.json scripts:
     "lint": "ultracite check ."
     "format": "ultracite check --write ."
6. Commit changes:
     git add biome.jsonc .backup/
     git commit -m "Migrate to Ultracite from ESLint + Prettier"

ROLLBACK INSTRUCTIONS
---------------------
If issues occur:
  1. Remove biome.jsonc
  2. Restore: mv .backup/.eslintrc.js . && mv .backup/.prettierrc .
  3. Reinstall: npm install -D eslint prettier
  4. See: .backup/manifest.txt

Migration Status: ✅ SUCCESS (with 7 unmapped rules to review)
```

## Related Resources

Load these references when needed:

- `references/migration-guides.md` - Complete ESLint/Prettier rule mappings
- `references/provider-biome.md` - Biome provider details
- `references/provider-oxlint.md` - Oxlint for type-aware linting
- `references/troubleshooting.md` - Common migration issues
- `references/v6-migration.md` - v6→v7 preset path migration

## Related Commands

- `/ultracite:migrate` - Interactive migration wizard (uses this agent)
- `/ultracite:doctor` - Validate setup after migration

## Implementation Notes

This agent uses:
- **Read** tool to read ESLint/Prettier configs and package.json
- **Glob** tool to find config files
- **Write** tool to create biome.jsonc and backup manifest
- **Edit** tool to update preset paths (v6→v7)
- **Bash** tool to run validation commands
- **Grep** tool to search for preset paths

Files are modified with backups created first for safety.

## Success Criteria

A successful migration provides:
1. ✅ Complete rule mapping analysis
2. ✅ Unmapped rules with workarounds
3. ✅ Generated biome.jsonc configuration
4. ✅ Backed up old configurations
5. ✅ Validation test results
6. ✅ Next steps and rollback instructions
7. ✅ Migration status report
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall