Run detector
    |
    ├── task_binary.installed = false → Install Task first
    |
    ├── taskfile.exists = true → Phase 1: Audit
    |
    └── taskfile.exists = false → Phase 2: Scaffold

Phase 1: Audit (Existing Taskfile)

Summarize findings — show a status table:

Component	Status	Detail
task binary	installed/missing	version, path
Taskfile	found/not found	path, variant
Tasks	N tasks	count, has includes
Ecosystems	N detected	list
dotenv	configured/missing	.env files found

Present audit violations grouped by severity (ERROR > WARNING > INFO):
- Show rule ID, message, task name, line number, fix hint
- Violations include: missing version, no preconditions on deploy tasks, no sources/generates on build tasks, missing desc, too many tasks in single file, no dotenv, hard-coded paths
Use AskUserQuestion (multiSelect: true) — ask which violations to fix
Apply selected fixes — see WORKFLOW.md for per-rule fix strategies
Re-run detector to verify fixes were applied

Phase 2: Scaffold (No Taskfile)

Install task if missing — show commands based on os field:
- macOS: brew install go-task
- Linux: sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin
- Verify: task --version
Review detected ecosystems — show what was found
Choose Taskfile pattern — use AskUserQuestion:
- Single-file (flat namespace with : separators) — recommended for < 15 tasks
- Multi-file (root + taskfiles/ with includes) — recommended for 15+ tasks or monorepos

Choose task groups — use AskUserQuestion (multiSelect: true):

Ecosystem	Available Groups
Node.js/pnpm	`dev`, `build`, `test`, `lint`, `format`, `check`
JVM/Gradle	`build`, `test`, `lint`, `check`, `run`
Python/uv	`dev`, `test`, `lint`, `format`, `check`
Docker	`up`, `down`, `logs`, `build`, `clean`
Generic	`setup`, `check`, `clean`

Generate Taskfile.yml with selected groups — always include:
- version: "3"
- desc: on every task
- Top-level vars: for directory paths
- dotenv: if .env files exist
Verify — re-run detector, then run task --list

Key Rules

Never overwrite existing Taskfile.yml without asking. Offer merge/replace/skip.
Detect first — skip steps already configured.
Use AskUserQuestion for every decision. Do not assume user preferences.
Always use version: "3" — the only supported non-deprecated schema.
Add desc: to every task for task --list discoverability.
Wrap ecosystem tools (pnpm, gradlew, uv) — do not duplicate their logic.
Use variables for directory paths instead of hard-coding.
dotenv only in root — Taskfile does not support dotenv in included files.

Existing Runner Awareness

The detector reports existing runners (Makefile, justfile, package.json scripts, gradlew). When scaffolding:

Note which runners exist and what they cover
Suggest Taskfile as a unifying layer that wraps existing tools
Do not duplicate what existing runners already do well

References

Workflow: See WORKFLOW.md for detailed per-step flows and templates
Examples: See EXAMPLES.md for example setup and audit sessions
Troubleshooting: See TROUBLESHOOTING.md for common issues
Detection Script: See scripts/detect_taskfile.py for detection logic

taskfile-setup

Taskfile Setup

Pre-flight

Decision Flow