mise-expert

What this skill does

# Mise Expert Skill

## Purpose

Specialized skill for mise - a unified development environment manager combining tool version management (asdf replacement), environment variable management (direnv replacement), and task running (make/npm scripts replacement).

## When to Use This Skill

### Tool & Runtime Management
- Installing and managing runtime versions (node, python, go, ruby, rust, etc.)
- Setting up project-specific tool versions for reproducibility
- Switching between multiple language versions in polyglot projects
- Managing global vs project-local tool installations
- Migrating from asdf, nvm, pyenv, rbenv, or similar version managers
- Troubleshooting tool version conflicts

### Project Setup & Onboarding
- Bootstrapping new project development environments
- Creating mise.toml for team consistency
- Setting up monorepo tool configurations
- Configuring per-directory environment switching
- Establishing project development standards
- Simplifying onboarding for new team members

### Task Runner & Build Systems
- Creating or optimizing mise.toml task configurations
- Designing task workflows with dependency chains
- Implementing parallel task execution strategies
- Adding intelligent caching with sources/outputs
- Converting from make, npm scripts, just, or other task runners
- Building cross-platform compatible task systems
- Optimizing build performance with incremental builds

### Environment Management
- Configuring per-directory environment variables
- Managing secrets and configuration across environments
- Setting up development/staging/production environment switching
- Replacing direnv with mise
- Loading environment from .env files
- Creating environment-specific task behaviors

### CI/CD Integration
- Setting up mise in GitHub Actions, GitLab CI, CircleCI
- Ensuring consistent environments between local and CI
- Optimizing CI builds with mise caching
- Managing tool versions in containerized environments

### Troubleshooting & Optimization
- Debugging mise task execution issues
- Diagnosing tool version problems
- Resolving environment variable loading issues
- Optimizing task caching and performance
- Fixing cross-platform compatibility issues

## Core Capabilities

<capabilities>
- **Tool Version Management**: Install, configure, and switch between runtime versions
- **Task Design**: Create efficient, cacheable, and maintainable task configurations
- **Environment Setup**: Configure tools, variables, and per-directory environments
- **Workflow Optimization**: Design parallel execution and intelligent dependency chains
- **Migration Support**: Convert from asdf, make, npm, direnv, and other tools
- **Troubleshooting**: Diagnose and resolve mise configuration issues
- **Best Practices**: Apply mise patterns for modern development workflows
- **CI/CD Integration**: Configure mise for continuous integration pipelines
</capabilities>

## Operational Guidelines

### Task Configuration Principles

<task_design_principles>
1. **Caching First**: Always define `sources` and `outputs` for cacheable tasks
2. **Parallel by Default**: Use `depends` arrays for parallel execution
3. **Single Responsibility**: Each task should have one clear purpose
4. **Namespacing**: Group related tasks with prefixes (e.g., `db:migrate`, `test:unit`)
5. **Idempotency**: Tasks should be safe to run multiple times
6. **Platform Awareness**: Use `run_windows` for cross-platform compatibility
7. **Watch Mode Ready**: Design tasks compatible with `mise watch`
</task_design_principles>

### Decision Framework

<when_to_use_mise>
**Choose mise for:**
- Multi-language projects requiring version management (Python + Node + Go)
- Projects needing per-directory environment variables
- Cross-platform development teams (Linux/Mac/Windows)
- Replacing complex Makefiles or npm scripts
- Projects with parallel task execution needs
- Teams wanting consistent dev environments (new dev onboarding)
- Replacing multiple tools (asdf + direnv + make) with one
- CI/CD pipelines requiring reproducible builds

**Skip mise for:**
- Single-language projects with simple build steps
- Projects where npm scripts are sufficient
- Teams unfamiliar with TOML and no bandwidth for learning
- Projects with existing, working task systems and no pain points
- Embedded systems or constrained environments
</when_to_use_mise>

### Tool Version Management Patterns

<tool_installation_patterns>
**Project-Specific Tools**
```toml
# mise.toml - Project root configuration
[tools]
# Exact versions for reproducibility
node = "20.10.0"
python = "3.11.6"
go = "1.21.5"
terraform = "1.6.6"

# Read from version file
ruby = { file = ".ruby-version" }
java = { file = ".java-version" }

# Latest patch version
postgres = "16"
redis = "7"

# Multiple versions (switch with mise use)
# mise use node@18 (temporarily override)
```

**Global Development Tools**
```bash
# Install globally useful CLI tools
mise use -g ripgrep@latest      # Better grep
mise use -g bat@latest          # Better cat
```

**Version File Migration**
```bash
# Migrate from existing version files
echo "20.10.0" > .node-version
echo "3.11.6" > .python-version

# mise.toml
[tools]
node = { file = ".node-version" }
python = { file = ".python-version" }
```
</tool_installation_patterns>

### Project Setup Workflows

<project_setup_patterns>
**New Project Bootstrap**
```toml
# mise.toml
[tools]
node = "20"
python = "3.11"

[env]
PROJECT_ROOT = "{{cwd}}"
LOG_LEVEL = "debug"

[vars]
project_name = "my-app"

[tasks.setup]
description = "Setup development environment"
run = [
  "mise install",
  "npm install",
  "pip install -r requirements.txt",
  "cp .env.example .env"
]

[tasks.dev]
alias = "d"
description = "Start development server"
depends = ["setup"]
env = { NODE_ENV = "development" }
run = "npm run dev"
```

**Monorepo Configuration**
```toml
# Root mise.toml
[tools]
node = "20"
go = "1.21"

[tasks.install]
description = "Install all dependencies"
run = [
  "cd frontend && npm install",
  "cd backend && go mod download"
]

# frontend/mise.toml
[tasks.dev]
dir = "{{cwd}}/frontend"
run = "npm run dev"

# backend/mise.toml
[tools]
go = "1.21"

[tasks.dev]
dir = "{{cwd}}/backend"
run = "go run main.go"
```
</project_setup_patterns>

### Configuration Patterns

<common_patterns>
**Development Workflow**
```toml
[tasks.dev]
alias = "d"
description = "Start development server with hot reload"
env = { NODE_ENV = "development", DEBUG = "true" }
run = "npm run dev"

[tasks.dev-watch]
description = "Watch and rebuild on changes"
run = "mise watch build"
```

**Build Pipeline with Caching**
```toml
[tasks.clean]
description = "Remove build artifacts"
run = "rm -rf dist"

[tasks.build]
alias = "b"
description = "Build production bundle"
depends = ["clean"]
sources = ["src/**/*", "package.json", "tsconfig.json"]
outputs = ["dist/**/*"]
env = { NODE_ENV = "production" }
run = "npm run build"

[tasks.build-watch]
description = "Rebuild on source changes"
run = "mise watch build"
```

**Testing Suite**
```toml
[tasks.test]
alias = "t"
description = "Run all tests"
depends = ["test:unit", "test:integration"]  # Runs in parallel

[tasks."test:unit"]
description = "Run unit tests"
sources = ["src/**/*.ts", "tests/unit/**/*.ts"]
run = "npm test -- --testPathPattern=unit"

[tasks."test:integration"]
description = "Run integration tests"
sources = ["src/**/*.ts", "tests/integration/**/*.ts"]
run = "npm test -- --testPathPattern=integration"

[tasks."test:watch"]
description = "Run tests in watch mode"
run = "npm test -- --watch"

[tasks."test:coverage"]
description = "Generate coverage report"
run = "npm test -- --coverage"

[tasks."test:e2e"]
description = "Run end-to-end tests"
depends = ["build"]
run = "playwright test"
```

**Database Workflow**
```toml
[tasks."db:migrate"]
description = "Run database migrations"
run = "npx prisma migrate deploy"

[tasks."db:seed"]
description = "Seed database with test data"
depends = ["db:migrate"]
run = "npx prisma db seed"

[