Reference

Complete and dry. If you want to understand why a key exists rather than look up its spelling, that is Features.

Two formats, and which you want

	tasks.yml	workflows/*.yml
Is	a library of commands	one pipeline
Order comes from	needs: between tasks	stages:, then needs: between jobs
Run granularity	any task, alone	the whole file
version:	optional, read as 1 if absent	required
Tasks are	a map, keyed by task id	a list, run in list order
needs: on a task	how ordering works	refused — it belongs on the job

Both run through the same task executor, so env:, vars:, dotenv:, cwd:, templating, trigger:, timeout:, retries:, if:, continueOnError: and output: mean the same thing in each.

Two things tasks.yml does not have, and people assume it does: there is no list of commands under a task — one task is one run:, and several lines go in a run: | block — and the top-level key is tasks:. A file keyed on anything else parses into no tasks at all rather than reporting an error, because there is nothing there to reject.

The full schema

Every key in both formats, plus the guide to writing your own plugins, lives in REFERENCE.md in the repository — and inside the editor, where it is the fastest thing to reach:

Command Palette → Local Workflows: Schema Reference

The per-key pages that belong here are not written yet, and they are waiting on a generator rather than on someone’s afternoon: they should build from resources/schemas/*.schema.json and package.json’s contributes block, with CI failing when the committed output drifts from the source.

That is not a preference. A hand-copied schema table is how REFERENCE.md came to document a tasks: key that the parser has never accepted, in an example shaped around a cmds: list that has never existed — wrong in a way that produces an empty sidebar and no error message.