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 |

1. Present audit violations grouped by severity (ERROR > WARNING > INFO):
2. Show rule ID, message, task name, line number, fix hint
3. 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

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

1. Apply selected fixes — see [WORKFLOW.md](WORKFLOW.md) for per-rule fix strategies

1. Re-run detector to verify fixes were applied

Phase 2: Scaffold (No Taskfile)

1. Install task if missing — show commands based on os field:
2. macOS: brew install go-task
3. Linux: sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin
4. Verify: task --version

1. Review detected ecosystems — show what was found

1. Choose Taskfile pattern — use AskUserQuestion:
2. Single-file (flat namespace with : separators) — recommended for < 15 tasks
3. Multi-file (root + taskfiles/ with includes) — recommended for 15+ tasks or monorepos

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

1. Generate Taskfile.yml with selected groups — always include:
2. version: "3"
3. desc: on every task
4. Top-level vars: for directory paths
5. dotenv: if .env files exist

1. 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](WORKFLOW.md) for detailed per-step flows and templates
• Examples: See [EXAMPLES.md](EXAMPLES.md) for example setup and audit sessions
• Troubleshooting: See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues
• Detection Script: See [scripts/detect_taskfile.py](scripts/detect_taskfile.py) for detection logic