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