taskfile

name	taskfile
description	Taskfile discovery and execution — use before running any project command when the project may use go-task. Invoke when the user asks: "run the tests", "build the project", "start the dev server", "run lint/fmt/bench/ci/clean", "what task should I run for X", "task [name] is failing", "how do I pass args to task", or when a Taskfile.yaml/Taskfile.dist.yaml is present. Always read the Taskfile before guessing ecosystem commands — prevents npm-vs-yarn mistakes, wrong test wrappers (cargo test vs nextest), and missed env vars or dep chains. Covers task field inspection, nested includes, CLI_ARGS passthrough, and manual fallback when task is unavailable. Use taskfile-authoring when creating or updating Taskfiles.
version	2.1.0
tags	["taskfile","task","go-task","build","dev-workflow","automation"]
execution	{"plan":{"allow":["inspect Taskfiles","inspect included Taskfiles","map task names to user intent","infer manual fallback commands from Taskfile definitions"],"deny":["execute project commands","install tooling"]},"code":{"allow":["execute tasks via the task runner","reproduce task commands manually when task runner is unavailable","add or update Taskfiles (apply taskfile-authoring rules)"]}}

Taskfile: Discovery, Inspection, and Execution

The Core Idea

Taskfile is the project's ecosystem-agnostic command vocabulary.

task build, task test, task fmt, task lint, task bench, task clean — these names work regardless of whether the project is Rust/cargo, Node/yarn/pnpm/npm, .NET/dotnet, Java/Maven/Gradle, Python, CMake, or anything else.

Always try the Taskfile vocabulary first. Never reach for cargo test, yarn dev, or npm run lint before checking what the Taskfile actually says — the Taskfile may wrap those commands with env vars, deps, flags, or tool selections that matter.

---

Discovery

Search for Taskfiles in the project root in this order (stop at first match):

1. Taskfile.yaml
2. Taskfile.yml
3. Taskfile.dist.yaml
4. Taskfile.dist.yml

Then read includes to find nested Taskfiles (e.g. web/Taskfile.dist.yaml).

If Taskfile.yaml or Taskfile.yml is in .gitignore, a Taskfile.dist.yaml likely exists alongside it as the tracked baseline — check for both.

---

Reading a Task

Before executing or reproducing any task, inspect all of these fields:

Field	What it tells you
deps	Tasks that run first — never skip in manual fallback
cmds	The actual commands
vars	Variable definitions — may control package manager, build profile, output paths
env	Environment overrides (e.g. RUST_LOG: disabled)
dotenv	Env files loaded before execution (.env.local, .env)
preconditions	Required tools or env state
requires	Required variable values (with optional enum)
sources / generates	Inputs/outputs for incremental skipping
status	Shell conditions under which the task is skipped
internal	If true, this is a helper — use the user-facing entry point instead
dir	Working directory override
aliases	Alternative names the user might type

vars determines the package manager. A task running {{.RUN}} dev where vars: RUN: "yarn" runs yarn dev — not npm run dev. Read vars before constructing any command.

deps are not optional. If test depends on fmt, skipping fmt in manual fallback changes behavior. Reproduce the full dep chain.

---

Canonical Vocabulary

Map user intent to these task names (try in order):

Intent	Try first	Then
Run the app	run, dev	serve, start
Build	build	build:release, build:*
Test	test	test:* for narrower scope
Lint	lint	lint:fix, fix
Format	fmt	format
Benchmark	bench	benchmark, bench:*
Full CI check	check, ci
Clean	clean	sweep, gc (lighter)
Docs	docs	docs:open
Fuzz	fuzz, fuzz:smoke	fuzz:list, fuzz:run, fuzz:build
Docker	docker:up, up	docker:down, down
Migrate DB	migrate:up, migrate	migrate:*
Database	db:*, sqlx:*

If both run and dev exist, check desc fields to distinguish them.

---

Execution

Preferred forms

task <name>
task <name> -- extra args       # passes into {{.CLI_ARGS}}
task <name> VAR=value           # sets a variable
task -t path/to/Taskfile <name> # target a specific Taskfile
task --list                     # list all non-internal tasks
task --list --sort=none         # preserve definition order

Manual fallback when task is unavailable

1. Find the matching task.
2. Load dotenv files in order.
3. Resolve vars (including sh: commands).
4. Run deps in the correct order.
5. Apply env to the shell environment.
6. Run cmds in sequence, in the correct dir.
7. Skip tasks whose status condition is already true.

Do not reduce task test to a bare ecosystem command. Reproduce the full defined behavior.

---

Includes and Nesting

When a root Taskfile includes sub-Taskfiles, tasks are namespaced:

includes:
  web:
    taskfile: web/Taskfile.dist.yaml
    dir: web

This makes web:build, web:clean, etc. available. A root clean that depends on web:clean must execute both — do not treat the root Taskfile as complete in isolation.

---

Anti-Patterns

• Guessing npm when the Taskfile uses yarn or pnpm
• Running cargo test when the Taskfile wraps nextest with special handling
• Skipping deps during manual fallback
• Ignoring env, vars, or dotenv files
• Calling internal: true tasks directly
• Treating the root Taskfile as complete without checking includes

---

Reference

• Official docs: https://taskfile.dev
• Quick reference and examples: see the taskfile-authoring skill