mise-tasks

SKILL.md

mise Tasks Orchestration

Orchestrate multi-step project workflows using mise [tasks] section with dependency management, argument handling, and file tracking.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

Explicit triggers:

User mentions mise tasks, mise run, [tasks] section

User needs task dependencies: depends, depends_post

User wants workflow automation in .mise.toml

User mentions task arguments or usage spec

AI Discovery trigger (prescriptive):

When mise-configuration skill detects multi-step workflows (test suites, build pipelines, migrations), prescriptively invoke this skill to generate appropriate [tasks] definitions.

Quick Reference

Task Definition

[tasks.build]
description = "Build the project"
run = "cargo build --release"

Running Tasks

mise run build          # Run single task
mise run test build     # Run multiple tasks
mise run test ::: build # Run in parallel
mise r build            # Short form

Dependency Types

Type
Syntax
When

depends
depends = ["lint", "test"]
Run BEFORE task

depends_post
depends_post = ["notify"]
Run AFTER task succeeds

wait_for
wait_for = ["db"]
Wait only if running

Key Task Properties

Property
Purpose
Example

description
AI-agent discoverability (CRITICAL)
"Run pytest with coverage. Exits non-zero on failure."

alias
Short name
alias = "t"

dir
Working directory
dir = "packages/frontend"

env
Task-specific env vars (NOT passed to deps)
env = { LOG_LEVEL = "debug" }

hide
Hidden from mise tasks output
hide = true

sources
File tracking for caching
sources = ["src/**/*.rs"]

outputs
Skip if newer than sources
outputs = ["target/release/myapp"]

confirm
Prompt before execution
confirm = "Delete all data?"

quiet
Suppress mise output
quiet = true

silent
Suppress ALL output
silent = true

raw
Direct stdin/stdout (disables parallelism)
raw = true

tools
Task-specific tool versions
tools = { python = "3.9" }

shell
Custom shell
shell = "pwsh -c"

usage
Argument spec (preferred over Tera)
See Task Arguments

Namespacing

mise run 'test:*'      # All tasks starting with test:
mise run 'db:**'       # Nested: db:migrate:up, db:seed:test
mise tasks --hidden    # View hidden tasks (prefixed with _)

For detailed examples and patterns for all levels, see Task Levels Reference.

Level 10: Monorepo (Experimental)

Requires: MISE_EXPERIMENTAL=1 and experimental_monorepo_root = true

mise run //projects/frontend:build    # Absolute from root
mise run :build                       # Current config_root
mise run //...:test                   # All projects
mise run '//projects/...:build'       # Build all under projects/

Tasks in subdirectories are auto-discovered with path prefix (packages/api/.mise.toml tasks become packages/api:taskname).

For complete monorepo documentation, see: advanced.md

Level 11: Polyglot Monorepo with Pants + mise

For Python-heavy polyglot monorepos (10-50 packages), combine mise for runtime management with Pants for build orchestration and native affected detection.

Tool
Responsibility

mise
Runtime versions (Python, Node, Rust) + environment variables

Pants
Build orchestration + native affected detection + dependency inference

# Native affected detection (no manual git scripts)
pants --changed-since=origin/main test
pants --changed-since=origin/main lint
pants --changed-since=origin/main package

Scale
Recommendation

< 10 packages
mise + custom affected (Level 10 patterns)

10-50 packages (Python-heavy)
Pants + mise (this section)

50+ packages
Consider Bazel

See polyglot-affected.md for complete Pants + mise integration guide and tool comparison.

Integration with [env]

Tasks automatically inherit [env] values. Use _.file for external env files and redact = true for secrets.

[env]
DATABASE_URL = "postgresql://localhost/mydb"
_.file = { path = ".env.secrets", redact = true }

[tasks._check-env]
hide = true
run = '[ -n "$API_KEY" ] || { echo "Missing API_KEY"; exit 1; }'

[tasks.deploy]
depends = ["_check-env"]
run = "deploy.sh"  # $DATABASE_URL and $API_KEY available

For full env integration patterns, see Environment Integration.

Anti-Patterns

Anti-Pattern
Why Bad
Instead

Replace /itp:go with mise tasks
No TodoWrite, no ADR tracking, no checkpoints
Use mise tasks for project workflows, /itp:go for ADR-driven development

Hardcode secrets in tasks
Security risk
Use _.file = ".env.secrets" with redact = true

Giant monolithic tasks
Hard to debug, no reuse
Break into small tasks with dependencies

Skip or minimal description
AI agents cannot infer task purpose from name alone
Write rich descriptions: what it does, requires, produces, when to run

Publish without build depends
Runtime failure instead of DAG prevention
Add depends = ["build"] to publish tasks

Orchestrator without all phases
"Run X next" messages get ignored
Include all phases in release:full depends array

For release-specific anti-patterns and patterns, see Release Workflow Patterns.

Cross-Reference: mise-configuration

Prerequisites: Before defining tasks, ensure [env] section is configured.

PRESCRIPTIVE: After defining tasks, invoke mise-configuration skill to ensure [env] SSoT patterns are applied.

The mise-configuration skill covers:

[env] - Environment variables with defaults

[settings] - mise behavior configuration

[tools] - Version pinning

Special directives: _.file, _.path, _.python.venv

Additional Resources

Task Levels Reference - Levels 1-9: basic tasks, dependencies, hidden tasks, arguments, file tracking, advanced execution, watch mode

Task Patterns - Real-world task examples

Task Arguments - Complete usage spec reference

Advanced Features - Monorepo, watch, experimental

Environment Integration - [env] inheritance and credential loading

Polyglot Affected - Pants + mise integration guide and tool comparison

Bootstrap Monorepo - Autonomous polyglot monorepo bootstrap meta-prompt

Release Workflow Patterns - Release task DAG patterns, build-before-publish enforcement

Troubleshooting

Issue
Cause
Solution

Task not found
Typo or wrong mise.toml
Run mise tasks to list available tasks

Dependencies not run
Circular dependency
Check task depends arrays for cycles

Sources not working
Wrong glob pattern
Use relative paths from mise.toml location

Watch not triggering
File outside sources list
Add file pattern to sources array

Env vars not available
Task in wrong directory
Ensure mise.toml is in cwd or parent

Run fails with error
Script path issue
Use absolute path or relative to mise.toml

Post-Execution Reflection

After this skill completes, check before closing:

Did the command succeed? — If not, fix the instruction or error table that caused the failure.

Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.

Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.