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.

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:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. 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.