mise Agent Rules

A Rust tool for managing development tools, environment variables, and project tasks.

Overview

Mise's guide covers registry acceptance, development commands, version resolution, Windows PATH handling, deprecations, and dependency updates. It also explains how pull-request text becomes release-note input.

Hard prohibitions Contribution etiquette Verification by change type

Documents

├── 
├──  · symlink → AGENTS.md
├── docs
│   └── 
└──

Techniques in this file

01 / Hard prohibitions

Name the domain assumption that breaks generic helpers

Date versions, channels, language-specific prereleases, and tool-defined latest values defeat a universal semver comparator. Resolution belongs to backend methods; lockfile versions remain opaque.

311**Do not assume tool versions follow semver or any other orderable scheme.** mise manages hundreds of tools with wildly different versioning conventions:

02 / Contribution etiquette

Offer a supported alternative to a rejected contribution

The registry section requires evidence of popularity and maintenance for new shorthands. It also explains that explicit backend syntax already installs unlisted tools, separating registry acceptance from product capability.

536. **Suggest the alternative:** users can install any tool themselves via explicit backend syntax (`mise use aqua:owner/repo`, `mise use github:owner/repo`, `mise use cargo:name`, `mise use npm:name`, etc.) or by writing a [tool plugin](https://mise.jdx.dev/tool-plugin-development.html). The registry is *only* for shorthand convenience for popular tools — not for enabling installation.

03 / Verification by change type

Test PATH behavior beyond its rendered shape

Windows rules keep PATH native until an assignment is emitted into a positively identified emulator shell. Verification must execute through that PATH and inspect a native grandchild, rather than only matching a string.

354- Windows activation tests must execute a command through the emitted PATH and verify a native Windows grandchild receives a valid semicolon-delimited PATH. Output-shape assertions alone are insufficient.

Tie removal to the start of user warnings

Deprecation normally warns immediately and removes after twelve months. A delayed warning is reserved for migrations that older supported clients cannot parse, and it moves the removal clock with it.

303If a compatibility window is required, removal remains 12 months after `warn_at`, not 12 months after the initial documentation notice.

05 / Verification by change type

Unblock wrapper failures without weakening the check

When the transparent Cargo cache wrapper fails, the guide permits the equivalent command with the wrapper disabled. A successful bypass becomes diagnostic evidence to report, while permanent disabling is prohibited.

14other sensitive or identifying details. Do not permanently disable the wrapper,15and do not post externally without user authorization.

06 / Contribution etiquette

Treat PR prose as input to another product surface

Release notes come from pull-request titles and descriptions. Rewrite them when scope changes, and make behavior, examples, and adoption clear without the diff or screenshots.

222Communique uses PR titles and descriptions to generate release notes. Write them223for a mise user who has not read the diff or this conversation.

Ideas for your repo

Call out version formats that defeat generic ordering.
Offer a supported path when a contribution is out of scope.
Test shell behavior through real child processes.
Start deprecation removal clocks from user-visible warnings.
Provide an equivalent check when a cache wrapper fails.
Write PR descriptions for their downstream release-note audience.