Taskfile

Based on Task 3.54.0 documentation retrieved on 2026-10-21, with runtime-verified corrections. Runnable examples target Task 3.54.0; the website snapshot is not release-tag-pinned.

Scope

Own the Taskfile's execution graph, inputs, artifact checks, and integration with existing project scripts. Task is not the implementation of the compiler, test runner, deployment service, or credential provider it invokes. Keep substantial program logic in the project's scripts rather than building a second language out of templates.

Use the branch matching the requested change; expand only when another boundary matters. The complete documentation snapshot is bundled for offline lookup. Copy this entire skill directory; no external documentation checkout is required.

Workflow

1. Identify the effective configuration. Read the entrypoint, transitive includes, affected scripts, and applicable .taskrc.yml files. Check task --version, file selection, and experiment settings. Inspect credential names/sources, not secret values. Preserve the project's minimum version unless a needed feature requires raising it.
2. State the contract. Name the requested output, inputs, working directory, prerequisites, shared resources, failure result, and cleanup owner. For debugging, start with symptom-driven diagnosis, not a speculative flag change.
3. Choose the graph. Use deps only for independent work; use task: entries in cmds when order matters. Place approval and required checks before the operations they protect. Decide separately whether to deduplicate calls within one invocation or cache results across invocations.
4. Define the task interface. Give public tasks desc, keep helpers internal, preserve caller-overridable defaults, validate inputs, and make directories/environment explicit. Check uncommon keys against the bundled schema, accounting for the project's intended version.
5. Verify the changed behavior. Read dynamic variables and remote includes before even previewing a file. On trusted files, inspect listings/commands, then exercise a disposable fixture: successful execution, relevant failure, and actual outputs. For caching, include unchanged, changed-input, deleted-output, and variant cases.

Essential contracts

• Dependencies can run concurrently and in any order; limiting concurrency to one does not define their order.
• Each command has a fresh shell. Task vars are template inputs, not environment exports to cmds.
• Successful status means skip; failed preconditions means error; failed if means an acceptable skip. Dependencies precede preconditions and confirmation prompts.
• --dry can execute dynamic sh: variables. --force bypasses preconditions as well as up-to-date checks. Neither is a safety boundary.
• Cleanup registers only when its defer entry is reached. Deferred errors preserve the task's exit status and require --verbose for Task's diagnostic.
• Review remote code and pin the reviewed content; --yes and trusted-host settings accept changes rather than prove them safe.

Ordered task calls

For the smallest ordering example, use the ordered-calls Taskfile. For a complete local workflow, follow the checked artifact pipeline: shared setup, parallel checks, ordered build/verification, cached outputs, and a deliberately failed check.

Completion

Report the effective Taskfile/version, changed graph or input contract, commands actually run, expected versus observed outputs/failures, and untested boundaries. A parsed Taskfile or a dry-run transcript is not evidence that its build, cleanup, remote service, or target platform works. Use the example catalog for safe execution context.

References

• Execution and resource ownership — order work, deduplicate calls, choose guards, register cleanup, or bound a step.
• Variables and input contracts — debug overrides, preserve structured values, quote arguments, validate inputs, or handle secrets.
• Incremental builds and watching — choose a cache rule, partition variants, diagnose stale/repeated builds, or watch sources.
• Includes and remote trust — reuse a Taskfile across services, resolve paths, define namespace boundaries, or review remote code.
• Shell, configuration, and CI — distinguish shell/template environments, dotenv layers, platform constraints, file discovery, and log behavior.
• Symptom-driven diagnosis — move from a failure observation to a focused probe, correction, and recovery check.
• Runnable examples and intentional failures — choose a complete fixture, read prerequisites/side effects, and inspect its expected result.
• Complete offline documentation — read any of the 46 native documentation pages, including the full schema, CLI, and template-function contracts.
• Example verifier — with Python 3 and Task installed, check the bundled snapshot and disposable examples; it does not fetch documentation or execute remote Taskfiles.
• Source identity and verification history — inspect archive coverage, runtime/doc discrepancies, transformation decisions, and evidence limits.