mise Tasks Orchestration

<!-- ADR: 2025-12-08-mise-tasks-skill -->

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

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

---

Level 1-2: Basic Tasks

Minimal Task

[tasks.hello]
run = "echo 'Hello, World!'"

With Description

[tasks.test]
description = "Run test suite"
run = "pytest tests/"

With Alias

[tasks.test]
description = "Run test suite"
alias = "t"
run = "pytest tests/"

Now mise run t works.

Working Directory

[tasks.frontend]
dir = "packages/frontend"
run = "npm run build"

Task-Specific Environment

[tasks.test]
env = { RUST_BACKTRACE = "1", LOG_LEVEL = "debug" }
run = "cargo test"

Note: env values are NOT passed to dependency tasks.

GitHub Token Verification Task

For multi-account GitHub setups, add a verification task:

[tasks._verify-gh-auth]
description = "Verify GitHub token matches expected account"
hide = true  # Hidden helper task
run = """
expected="${GH_ACCOUNT:-}"
if [ -z "$expected" ]; then
  echo "GH_ACCOUNT not set - skipping verification"
  exit 0
fi
actual=$(gh api user --jq '.login' 2>/dev/null || echo "")
if [ "$actual" != "$expected" ]; then
  echo "ERROR: GH_TOKEN authenticates as '$actual', expected '$expected'"
  exit 1
fi
echo "✓ GitHub auth verified: $actual"
"""

[tasks.release]
description = "Create semantic release"
depends = ["_verify-gh-auth"]  # Verify before release
run = "npx semantic-release --no-ci"

See mise-configuration skill for GH_TOKEN setup.

SSH ControlMaster Warning: If using multi-account SSH, ensure ControlMaster no is set for GitHub hosts in ~/.ssh/config. Cached connections can authenticate with the wrong account.

Multi-Command Tasks

[tasks.setup]
run = [
  "npm install",
  "npm run build",
  "npm run migrate"
]

---

Level 3-4: Dependencies & Orchestration

Pre-Execution Dependencies

[tasks.deploy]
depends = ["test", "build"]
run = "kubectl apply -f deployment.yaml"

Tasks test and build run BEFORE deploy.

Post-Execution Tasks

[tasks.release]
depends = ["test"]
depends_post = ["notify", "cleanup"]
run = "npm publish"

After release succeeds, notify and cleanup run automatically.

Soft Dependencies

[tasks.migrate]
wait_for = ["database"]
run = "./migrate.sh"

If database task is already running, wait for it. Otherwise, proceed.

Task Chaining Pattern

[tasks.ci]
description = "Full CI pipeline"
depends = ["lint", "test", "build"]
depends_post = ["coverage-report"]
run = "echo 'CI passed'"

Single command: mise run ci executes entire chain.

Parallel Dependencies

Dependencies without inter-dependencies run in parallel:

[tasks.validate]
depends = ["lint", "typecheck", "test"]  # These can run in parallel
run = "echo 'All validations passed'"

---

Level 5: Hidden Tasks & Organization

Hidden Tasks

[tasks._check-credentials]
description = "Verify credentials are set"
hide = true
run = '''
if [ -z "$API_KEY" ]; then
  echo "ERROR: API_KEY not set"
  exit 1
fi
'''

[tasks.deploy]
depends = ["_check-credentials"]
run = "deploy.sh"

Hidden tasks don't appear in mise tasks output but can be dependencies.

View hidden tasks: mise tasks --hidden

Colon-Prefixed Namespacing

[tasks.test]
run = "pytest"

[tasks."test:unit"]
run = "pytest tests/unit/"

[tasks."test:integration"]
run = "pytest tests/integration/"

[tasks."test:e2e"]
run = "playwright test"

Run all test tasks: mise run 'test:*'

Wildcard Patterns

mise run 'test:*'      # All tasks starting with test:
mise run 'db:**'       # Nested: db:migrate:up, db:seed:test

---

Level 6: Task Arguments

Usage Specification (Preferred Method)

[tasks.deploy]
description = "Deploy to environment"
usage = '''
arg "<environment>" help="Target environment" {
  choices "dev" "staging" "prod"
}
flag "-f --force" help="Skip confirmation"
flag "--region <region>" default="us-east-1" env="AWS_REGION"
'''
run = '''
echo "Deploying to ${usage_environment}"
[ "$usage_force" = "true" ] && echo "Force mode enabled"
echo "Region: ${usage_region}"
'''

Argument Types

Required positional:

usage = 'arg "<file>" help="Input file"'

Optional positional:

usage = 'arg "[file]" default="config.toml"'

Variadic (multiple values):

usage = 'arg "<files>" var=#true'

Flag Types

Boolean flag:

usage = 'flag "-v --verbose"'
# Access: ${usage_verbose:-false}

Flag with value:

usage = 'flag "-o --output <file>" default="out.txt"'
# Access: ${usage_output}

Environment-backed flag:

usage = 'flag "--port <port>" env="PORT" default="8080"'

Accessing Arguments

In run scripts, arguments become usage_<name> environment variables:

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
${usage_environment}      # Required arg value
${usage_verbose:-false}   # Boolean flag with default
${usage_output}           # Flag with value
SKILL_SCRIPT_EOF

DEPRECATION WARNING: The Tera template method ({{arg(name="...")}}) will be removed in mise 2026.11.0. Use usage spec instead.

For complete argument syntax, see: arguments.md

---

Level 7: File Tracking & Caching

Source Files

[tasks.build]
sources = ["Cargo.toml", "src/**/*.rs"]
run = "cargo build"

Task re-runs only when source files change.

Output Files

[tasks.build]
sources = ["Cargo.toml", "src/**/*.rs"]
outputs = ["target/release/myapp"]
run = "cargo build --release"

If outputs are newer than sources, task is skipped.

Force Execution

mise run build --force  # Bypass caching

Auto Output Detection

[tasks.compile]
outputs = { auto = true }  # Default behavior
run = "gcc -o app main.c"

---

Level 8: Advanced Execution

Confirmation Prompts

[tasks.drop-database]
confirm = "This will DELETE all data. Continue?"
run = "dropdb myapp"

Output Control

[tasks.quiet-task]
quiet = true   # Suppress mise's output (not task output)
run = "echo 'This still prints'"

[tasks.silent-task]
silent = true  # Suppress ALL output
run = "background-job.sh"

[tasks.silent-stderr]
silent = "stderr"  # Only suppress stderr
run = "noisy-command"

Raw Mode (Interactive)

[tasks.edit-config]
raw = true  # Direct stdin/stdout/stderr
run = "vim config.yaml"

Warning: raw = true disables parallel execution.

Task-Specific Tools

[tasks.legacy-test]
tools = { python = "3.9", node = "18" }
run = "pytest && npm test"

Use specific tool versions for this task only.

Custom Shell

[tasks.powershell-task]
shell = "pwsh -c"
run = "Get-Process | Select-Object -First 5"

---

Level 9: Watch Mode

Basic Watch

mise watch build  # Re-run on source changes

Requires watchexec: mise use -g watchexec@latest

Watch Options

mise watch build --debounce 500ms  # Wait before re-run
mise watch build --restart          # Kill and restart on change
mise watch build --clear            # Clear screen before run

On-Busy Behavior

mise watch build --on-busy-update=queue    # Queue changes
mise watch build --on-busy-update=restart  # Restart immediately
mise watch build --on-busy-update=do-nothing  # Ignore (default)

---

Level 10: Monorepo (Experimental)

Requires: MISE_EXPERIMENTAL=1 and experimental_monorepo_root = true

Path Syntax

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

Wildcards

mise run '//projects/...:build'       # Build all under projects/
mise run '//projects/frontend:*'      # All tasks in frontend

Discovery

Tasks in subdirectories are auto-discovered with path prefix:

• packages/api/.mise.toml tasks → packages/api:taskname

For complete monorepo documentation, see: advanced.md

---

Integration with [env]

Tasks automatically inherit [env] values:

[env]
DATABASE_URL = "postgresql://localhost/mydb"
_.file = ".env"  # Load additional env vars

[tasks.migrate]
run = "diesel migration run"  # $DATABASE_URL available

Credential Loading Pattern

[env]
_.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"

---

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 description	Poor discoverability	Always add descriptions

---

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 Patterns - Real-world task examples
• Task Arguments - Complete usage spec reference
• Advanced Features - Monorepo, watch, experimental