Taskfile setup

Taskfile Setup

Install Taskfile and scaffold or audit Taskfile.yml configurations with ecosystem-aware templates.

Pre-flight

Run the detection script to understand current state:

python3 ${CLAUDE_SKILL_DIR}/scripts/detect_taskfile.py <project-root>

Decision Flow

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)

1. 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

2. 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

3. Use AskUserQuestion (multiSelect: true) — ask which violations to fix

4. Apply selected fixes — see WORKFLOW.md for per-rule fix strategies

5. Re-run detector to verify fixes were applied

Phase 2: Scaffold (No Taskfile)

1. 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

2. Review detected ecosystems — show what was found

3. 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

4. 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

5. 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

6. 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