[jdx]

A task template can hold a usage spec, but a task that extended it and declared any flag of its own lost every flag the template defined — usage was the one field where the template's value was used only when the task had none. Tasks that share a set of flags had to copy the whole spec into each one and keep the copies in sync, which is especially painful for choice flags.

The template's spec is now prepended to the task's:

[task_templates.deploy]
usage = """
flag "--env <env>" help="Target environment"
flag "--dry-run" help="Print what would happen"
"""

[tasks.deploy-api]
extends = "deploy"
usage = 'flag "--replicas <n>" help="How many to run"'
run = 'echo "env=$usage_env replicas=$usage_replicas"'

$ mise run deploy-api --help
Usage: deploy-api [FLAGS]

Flags:
      --env <env>       Target environment
      --dry-run         Print what would happen
      --replicas <n>    How many to run
  -h, --help            Print help

$ mise run deploy-api --env prod --replicas 3
env=prod replicas=3

Shared flags come first so --help reads shared-then-specific, and so a template's positional args stay ahead of the task's. Both halves are joined before rendering, so Tera in either still resolves. A task with no usage of its own inherits the template's unchanged, as before.

Only for a template named with extends

Workspace-root task defaults go through the same merge, where their job is to fill what a task left unset. Composing there could prepend a required positional argument to a task that has its own spec and break a command line that parsed fine before, so a workspace default's usage is still used only when the task has none.

Compatibility

A task that sets both usage and extends now also accepts the template's flags, where before it accepted only its own. Nothing that parsed before stops parsing, but a flag declared in both places is two declarations and is listed twice in --help — declare each flag in one place. For the case where a task genuinely needs to replace an inherited flag, usage flagsets are the better tool: put the shared declarations in a .usage.kdl file and use them where they belong.

Validation

• new e2e test e2e/tasks/test_task_template_usage covers composition, --help ordering, a task with no spec of its own, unset inherited flags, choices enforced through a template, and Tera in both halves. The ordering check compares the three flags as one ordered list; I confirmed it fails when the concatenation is reversed.
• four unit tests for the merge rule, including that a workspace default only fills
• existing e2e/tasks/test_task_templates, cargo test --bin mise task:: and config::, mise run lint, and cargo clippy --workspace --all-features --all-targets -- -D warnings all pass

Closes the main ask in #9637.

AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5; version: unavailable.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Extended task templates now combine template and task usage specifications, with template options listed first.
  • Tasks without their own usage specification inherit the template’s options.
  • Help output displays inherited and task-specific options together.

• Bug Fixes

  • Usage validation, option choices, and templating now work consistently across combined specifications.

• Documentation

  • Added guidance and examples for shared arguments, option ordering, and duplicate declarations.

---

Note

Medium Risk
Changes CLI parsing and --help for tasks with both extends and local usage (more flags accepted; duplicate declarations if the same flag appears in template and task).

Overview
Tasks that extends a template now merge usage specs instead of treating local usage as a full replacement. The template’s declarations are prepended to the task’s (template first in --help), then Tera runs on the combined string; tasks with no local usage still take the template’s spec unchanged.

Workspace-root task defaults keep the old fill-only rule via merge_template vs merge_extended_template for explicit extends, so defaults don’t inject extra required args into tasks that already define their own flags.

Docs add the usage row to the merge table and a shared-arguments example; e2e and unit tests cover composition, ordering, choices, and Tera.

^{Reviewed by Cursor Bugbot for commit 3e7546e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: CHILL

Plan: Advanced

Run ID: 153aa21f-4a30-4c6c-8a4e-5196553dcfd6

📥 Commits

Reviewing files that changed from the base of the PR and between 4c450a6 and 3e7546e.

📒 Files selected for processing (4)

• docs/tasks/templates.md
• e2e/tasks/test_task_template_usage
• src/config/mod.rs
• src/task/task_template.rs

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/tasks/templates.md

Included review availability: Your plan provides up to 10 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

Changes

Named task templates prepend their usage specification to the extending task’s specification. Workspace task defaults only fill missing usage. Unit tests, end-to-end tests, and documentation cover merge behavior, validation, ordering, and templating.

Task template usage

Layer / File(s)	Summary
Implement usage merge modes src/task/task_template.rs, src/config/mod.rs	Named extensions use composed usage. Workspace defaults use fill-only usage. Unit tests cover both modes.
Validate composed usage at runtime e2e/tasks/test_task_template_usage	End-to-end tests cover combined flags, inheritance, ordering, choices, unset values, and Tera rendering.
Document usage merge semantics docs/tasks/templates.md	The documentation describes concatenation, flag ordering, and duplicate declarations.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Suggested reviewers: risu729

Sequence Diagram(s)

sequenceDiagram
  participant resolve_task_template
  participant Task
  participant TaskTemplate
  resolve_task_template->>Task: resolve task with extends
  Task->>TaskTemplate: merge_extended_template
  TaskTemplate-->>Task: compose template usage before task usage

Loading

Merge Risk: ⚪ Minimal · up to 3e754

The named-template and workspace-default merge paths are separated as intended, with coverage for the documented usage behavior.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: task templates now provide inherited usage flags.
Docstring Coverage	✅ Passed	Docstring coverage is 90.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 2 files. (2 skipped: 2 …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the previous findings are resolved and no actionable new defect remains.

Summary

This PR makes tasks that explicitly extend a named template inherit and compose the template’s usage declarations while preserving fill-only behavior for workspace defaults.

• Prepends template usage declarations so shared flags and positional arguments appear before task-specific declarations.
• Keeps workspace-root defaults from injecting usage into tasks that already define their own interface.
• Adds focused unit and end-to-end coverage for inheritance, ordering, choices, unset flags, and Tera rendering.
• Documents the composition behavior and duplicate-declaration tradeoff.

_{Reviews (4) · Last reviewed commit: "Merge branch 'main' of https://github.co..."}