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:

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):

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

Examples: Taskfile Setup

Example 1: Greenfield Node.js Project (No Taskfile)

Detection Output

{
  "task_binary": {"installed": true, "path": "/opt/homebrew/bin/task", "version": "3.40.1"},
  "taskfile": {"exists": false},
  "ecosystems": [
    {"ecosystem": "node", "package_manager": "pnpm", "root": "."}
  ],
  "env_files": [".env.local"],
  "existing_runners": {"makefile": false, "justfile": false, "package_json_scripts": true, "gradlew": false},
  "os": "macos"
}

Scaffold Session

Status: Task installed, no Taskfile found, Node.js/pnpm detected.

User chooses: Single-file pattern, task groups: dev, build, test, lint, format, check, setup, clean.

Generated Taskfile.yml

version: "3"

dotenv: [".env.local", ".env"]

tasks:
  setup:
    desc: Install dependencies
    run: once
    cmds:
      - pnpm install

  dev:
    desc: Start development server
    deps: [setup]
    cmds:
      - pnpm dev

  build:
    desc: Build for production
    deps: [setup]
    cmds:
      - pnpm build

  test:
    desc: Run tests
    deps: [setup]
    cmds:
      - pnpm test

  lint:
    desc: Run ESLint
    deps: [setup]
    cmds:
      - pnpm lint

  format:
    desc: Format code with Prettier
    cmds:
      - pnpm prettier --write .

  check:
    desc: Type-check with TypeScript
    cmds:
      - npx tsc --noEmit

  clean:
    desc: Clean build artifacts
    cmds:
      - rm -rf dist .next node_modules/.cache

---

Example 2: Monorepo with JVM + Node.js (Multi-file)

Detection Output

{
  "task_binary": {"installed": true, "path": "/opt/homebrew/bin/task", "version": "3.40.1"},
  "taskfile": {"exists": false},
  "ecosystems": [
    {"ecosystem": "node", "package_manager": "pnpm", "root": "apps/web"},
    {"ecosystem": "jvm", "build_tool": "gradle-kotlin", "root": "apps/api"},
    {"ecosystem": "docker", "has_dockerfile": true, "has_compose": true, "root": "."}
  ],
  "env_files": [],
  "existing_runners": {"makefile": false, "justfile": false, "package_json_scripts": true, "gradlew": true},
  "os": "macos"
}

Scaffold Session

Status: Task installed, no Taskfile, 3 ecosystems detected (monorepo).

User chooses: Multi-file pattern (recommended for monorepo).

Generated Files

Taskfile.yml (root):

version: "3"

includes:
  api:
    taskfile: ./taskfiles/api.yml
    dir: ./apps/api
  web:
    taskfile: ./taskfiles/web.yml
    dir: ./apps/web
  docker:
    taskfile: ./taskfiles/docker.yml

tasks:
  setup:
    desc: Full project setup
    cmds:
      - task: api:setup
      - task: web:setup

  dev:
    desc: Start all services in parallel
    deps:
      - api:dev
      - web:dev

  test:
    desc: Run all tests
    cmds:
      - task: api:test
      - task: web:test

  lint:
    desc: Run all linters
    cmds:
      - task: api:lint
      - task: web:lint

  clean:
    desc: Clean all build artifacts
    cmds:
      - task: api:clean
      - task: web:clean

taskfiles/api.yml:

version: "3"

tasks:
  setup:
    desc: API setup
    cmds:
      - echo "API dependencies managed by Gradle"

  dev:
    desc: Start API server
    cmds:
      - ./gradlew bootRun

  test:
    desc: Run API tests
    cmds:
      - ./gradlew test

  lint:
    desc: Run Kotlin linter
    cmds:
      - ./gradlew ktlintCheck

  clean:
    desc: Clean API build artifacts
    cmds:
      - ./gradlew clean

taskfiles/web.yml:

version: "3"

tasks:
  setup:
    desc: Install web dependencies
    run: once
    cmds:
      - pnpm install

  dev:
    desc: Start web dev server
    deps: [setup]
    cmds:
      - pnpm dev

  test:
    desc: Run web tests
    deps: [setup]
    cmds:
      - pnpm test

  lint:
    desc: Run ESLint
    deps: [setup]
    cmds:
      - pnpm lint

  clean:
    desc: Clean web build artifacts
    cmds:
      - rm -rf .next node_modules/.cache

taskfiles/docker.yml:

version: "3"

tasks:
  up:
    desc: Start containers
    cmds:
      - docker compose up -d

  down:
    desc: Stop containers
    cmds:
      - docker compose down

  logs:
    desc: Follow container logs
    cmds:
      - docker compose logs -f {{.CLI_ARGS}}

  clean:
    desc: Stop and remove volumes
    cmds:
      - docker compose down -v --remove-orphans

---

Example 3: Existing Taskfile with Violations

Detection Output with Audit

{
  "task_binary": {"installed": true, "path": "/opt/homebrew/bin/task", "version": "3.40.1"},
  "taskfile": {
    "exists": true, "path": "Taskfile.yml", "version": "3",
    "task_count": 12, "has_includes": false, "include_count": 0, "has_dotenv": false,
    "tasks": [
      {"name": "build", "has_desc": true, "has_preconditions": false, "has_sources": false, "has_generates": false, "has_deps": true, "has_status": false, "line": 8},
      {"name": "deploy", "has_desc": false, "has_preconditions": false, "has_sources": false, "has_generates": false, "has_deps": false, "has_status": false, "line": 15},
      {"name": "test", "has_desc": false, "has_preconditions": false, "has_sources": false, "has_generates": false, "has_deps": false, "has_status": false, "line": 22}
    ]
  },
  "env_files": [".env", ".env.local"],
  "audit": {
    "violations": [
      {"rule": "TF002", "severity": "WARNING", "message": "Task 'deploy' has no preconditions (safety-critical task)", "task": "deploy", "line": 15},
      {"rule": "TF003", "severity": "WARNING", "message": "Task 'build' has no sources/generates (no up-to-date checks)", "task": "build", "line": 8},
      {"rule": "TF005", "severity": "WARNING", "message": "Task 'deploy' is missing a 'desc:' field", "task": "deploy", "line": 15},
      {"rule": "TF005", "severity": "WARNING", "message": "Task 'test' is missing a 'desc:' field", "task": "test", "line": 22},
      {"rule": "TF006", "severity": "INFO", "message": "No 'dotenv:' config but 2 .env file(s) found"}
    ],
    "summary": {"total": 5, "errors": 0, "warnings": 4, "info": 1}
  }
}

Audit Report

## Audit Results — 5 violations (4 warnings, 1 info)

### WARNINGS
| Rule  | Message                              | Task   | Line | Fix                        |
|-------|--------------------------------------|--------|------|----------------------------|
| TF002 | No preconditions on safety task      | deploy | 15   | Add preconditions block    |
| TF003 | No sources/generates on build task   | build  | 8    | Add sources/generates      |
| TF005 | Missing desc field                   | deploy | 15   | Add desc                   |
| TF005 | Missing desc field                   | test   | 22   | Add desc                   |

### INFO
| Rule  | Message                              | Fix                                  |
|-------|--------------------------------------|--------------------------------------|
| TF006 | No dotenv, 2 .env files found       | Add dotenv: [".env.local", ".env"]   |

User selects: TF005 (both), TF006 to fix. Skips TF002 and TF003 for now.

After Fixes

• Added desc: Deploy application to deploy task
• Added desc: Run tests to test task
• Added dotenv: [".env.local", ".env"] at top level
• Re-ran detector: 2 violations remaining (TF002, TF003)

---

Example 4: Nosilha-Style Full-Stack Project

Context

Full-stack project with API (Spring Boot/Gradle), web (Next.js/pnpm), Docker Compose for PostgreSQL, and infrastructure (Terraform).

Detection Output

{
  "taskfile": {"exists": false},
  "ecosystems": [
    {"ecosystem": "node", "package_manager": "pnpm", "root": "apps/web"},
    {"ecosystem": "jvm", "build_tool": "gradle-kotlin", "root": "apps/api"},
    {"ecosystem": "docker", "has_dockerfile": true, "has_compose": true, "root": "."}
  ],
  "env_files": [],
  "existing_runners": {"makefile": false, "justfile": false, "package_json_scripts": true, "gradlew": true}
}

User Chooses Single-File Pattern

Generated Taskfile.yml

version: "3"

vars:
  API_DIR: apps/api
  WEB_DIR: apps/web
  DOCKER_COMPOSE: infrastructure/docker/docker-compose.yml

tasks:
  check:
    desc: Check prerequisites — detect missing tools
    silent: true
    cmds:
      - |
        missing=0
        check_tool() {
          if command -v "$1" &> /dev/null; then
            printf "  OK  %-10s %s\n" "$1" "$(eval "$3")"
          else
            printf "  MISSING  %-10s install with: %s\n" "$1" "$2"
            missing=$((missing + 1))
          fi
        }
        echo "Checking prerequisites..."
        echo ""
        check_tool "docker"   "brew install --cask docker"  "docker --version | head -1"
        check_tool "node"     "nvm install --lts"           "node --version"
        check_tool "pnpm"     "npm install -g pnpm"         "pnpm --version"
        check_tool "java"     "sdk install java"            "java --version 2>&1 | head -1"
        echo ""
        if [ "$missing" -gt 0 ]; then
          echo "$missing tool(s) missing."
          exit 1
        else
          echo "All prerequisites installed."
        fi

  setup:
    desc: Full-stack setup
    cmds:
      - task: setup:api
      - task: setup:web

  setup:api:
    desc: API setup — copy env template if missing
    cmds:
      - |
        if [ ! -f {{.API_DIR}}/.env.local ]; then
          cp {{.API_DIR}}/.env.local.example {{.API_DIR}}/.env.local
          echo "Created {{.API_DIR}}/.env.local from template"
        else
          echo "{{.API_DIR}}/.env.local already exists, skipping"
        fi

  setup:web:
    desc: Web setup — install dependencies
    dir: "{{.WEB_DIR}}"
    cmds:
      - pnpm install

  dev:
    desc: Start API + web in parallel
    deps:
      - dev:api
      - dev:web

  dev:api:
    desc: Start API server (auto-starts database)
    dir: "{{.API_DIR}}"
    cmds:
      - ./gradlew bootRun --args='--spring.profiles.active=local'

  dev:web:
    desc: Start web dev server
    dir: "{{.WEB_DIR}}"
    cmds:
      - pnpm dev

  dev:db:
    desc: Start database only
    cmds:
      - docker compose -f {{.DOCKER_COMPOSE}} up -d

  test:
    desc: Run all tests
    cmds:
      - task: test:api
      - task: test:web

  test:api:
    desc: Run API tests
    dir: "{{.API_DIR}}"
    cmds:
      - ./gradlew test

  test:web:
    desc: Run web tests
    dir: "{{.WEB_DIR}}"
    cmds:
      - pnpm test

  lint:
    desc: Run all linters
    cmds:
      - task: lint:api
      - task: lint:web

  lint:api:
    desc: Run Kotlin linter
    dir: "{{.API_DIR}}"
    cmds:
      - ./gradlew ktlintCheck

  lint:web:
    desc: Run ESLint
    dir: "{{.WEB_DIR}}"
    cmds:
      - pnpm lint

  stop:
    desc: Stop database container
    cmds:
      - docker compose -f {{.DOCKER_COMPOSE}} down

  clean:
    desc: Clean build artifacts
    cmds:
      - task: clean:api
      - task: clean:web

  clean:api:
    desc: Clean API build artifacts
    dir: "{{.API_DIR}}"
    cmds:
      - ./gradlew clean

  clean:web:
    desc: Clean web build artifacts
    dir: "{{.WEB_DIR}}"
    cmds:
      - rm -rf .next node_modules/.cache

---

Example 5: Already-Perfect Taskfile

Detection Output

{
  "task_binary": {"installed": true, "path": "/opt/homebrew/bin/task", "version": "3.40.1"},
  "taskfile": {
    "exists": true, "path": "Taskfile.yml", "version": "3",
    "task_count": 15, "has_includes": false, "include_count": 0, "has_dotenv": true,
    "tasks": [
      {"name": "setup", "has_desc": true, "has_preconditions": false, "has_sources": false, "has_generates": false, "has_deps": false, "has_status": false, "line": 8},
      {"name": "dev", "has_desc": true, "has_preconditions": false, "has_sources": false, "has_generates": false, "has_deps": true, "has_status": false, "line": 14},
      {"name": "test", "has_desc": true, "has_preconditions": false, "has_sources": false, "has_generates": false, "has_deps": false, "has_status": false, "line": 22},
      {"name": "build", "has_desc": true, "has_preconditions": false, "has_sources": true, "has_generates": true, "has_deps": false, "has_status": false, "line": 30}
    ]
  },
  "audit": {
    "violations": [],
    "summary": {"total": 0, "errors": 0, "warnings": 0, "info": 0}
  }
}

Result

Taskfile audit complete — no violations found.

Your Taskfile.yml follows best practices:
  - version: '3' declared
  - All 15 tasks have desc fields
  - dotenv configured
  - Build tasks have sources/generates

No changes needed.

Troubleshooting: Taskfile Setup

Installation Issues

brew install task installs Taskwarrior instead of Taskfile

Symptom: Running task shows a TODO manager instead of a task runner.

Cause: brew install task installs Taskwarrior, not Taskfile.

Fix: Uninstall and reinstall with the correct formula:

brew uninstall task
brew install go-task

Verify: task --version should show something like Task version: v3.x.x.

task command not found after install

Symptom: command not found: task after running install script.

Cause: The binary was installed to a directory not in your PATH.

Fix: 1. Check where it was installed: ls ~/.local/bin/task or ls /usr/local/bin/task 2. Add to PATH in your shell profile:

   # In ~/.zshrc or ~/.bashrc
   export PATH="$HOME/.local/bin:$PATH"

3. Restart your terminal or run source ~/.zshrc

Version too old for version: '3'

Symptom: task: Failed to parse error when running tasks.

Cause: Task version 2.x does not support version: '3' schema.

Fix: Upgrade to Task 3.x:

# macOS
brew upgrade go-task

# Linux (install script)
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin

---

Detection Issues

Ecosystems not detected

Symptom: Detector returns empty ecosystems array despite project files existing.

Causes:

• Running from wrong directory — pass explicit project root
• Deeply nested project structure (detector only checks root + one level deep)

Fix:

# Specify the project root explicitly
python3 ${CLAUDE_SKILL_DIR}/scripts/detect_taskfile.py /path/to/project

Audit reports false positives

TF008 (deps for sequential): The detector flags deps: usage as INFO-level. However, deps: is intentionally parallel in many cases (e.g., dev: running API + web simultaneously). This is an informational hint, not a bug.

TF005 (missing desc): Internal tasks (prefixed with underscore like _helper) conventionally omit desc: to hide from task --list. The detector currently flags these. Skip these violations when reviewing.

TF007 (absolute paths): Comments containing file paths may trigger this rule. The detector skips comment lines starting with #, but inline comments are not filtered.

YAML parsing misses tasks

Symptom: Detector reports fewer tasks than expected.

Cause: The stdlib-only parser uses line-level indentation tracking. Complex YAML constructs may not be recognized:

• YAML anchors and aliases (<<: *defaults)
• Flow-style mappings ({key: value})
• Multi-line strings with unusual indentation

Workaround: The audit results are best-effort. Review the full Taskfile manually for any missed tasks. The detector's primary purpose is ecosystem detection and common-pattern auditing.

---

Scaffold Issues

Generated Taskfile has wrong tool paths

Symptom: task dev fails because pnpm or ./gradlew is not at the expected location.

Cause: The scaffold used default directory names that don't match your project structure.

Fix: Edit the vars: section in your Taskfile.yml:

vars:
  API_DIR: backend          # Was: apps/api
  WEB_DIR: frontend         # Was: apps/web

Include files not found

Symptom: task: Taskfile "taskfiles/api.yml" not found.

Cause: The included Taskfile path is relative to the root Taskfile's location.

Fix: Ensure paths are correct relative to the root Taskfile:

includes:
  api:
    taskfile: ./taskfiles/api.yml    # Relative to root Taskfile
    dir: ./apps/api                  # Working directory for tasks

dotenv not loading in included Taskfiles

Symptom: Environment variables from .env are not available in included Taskfile tasks.

Cause: This is a known Taskfile limitation — dotenv: declarations only work in the root Taskfile. They cannot be declared in included Taskfiles.

Fix: Define dotenv: only at the root level:

# Root Taskfile.yml — this works
version: "3"
dotenv: [".env.local", ".env"]

includes:
  api:
    taskfile: ./taskfiles/api.yml
    # env vars from dotenv ARE available in included tasks

---

Runtime Issues

task: command not found in CI

Symptom: CI pipeline fails because task is not installed.

Cause: Task is not installed in the CI environment by default.

Fix for GitHub Actions:

- name: Install Task
  uses: go-task/setup-task@v1
  with:
    version: '3.x'

Fix for other CI: Add install step:

sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin

Tasks run multiple times

Symptom: A setup task runs every time even though it only needs to run once.

Cause: Missing run: once on idempotent tasks.

Fix: Add run: once to tasks that should only execute once per invocation:

tasks:
  setup:
    run: once
    desc: Install dependencies
    cmds:
      - pnpm install

Variables not available in included Taskfiles

Symptom: {{.MY_VAR}} is empty in an included Taskfile's tasks.

Cause: Variables from the root Taskfile don't automatically propagate to includes.

Fix: Pass variables explicitly:

includes:
  api:
    taskfile: ./taskfiles/api.yml
    dir: ./apps/api
    vars:
      PROFILE: "{{.PROFILE}}"
      ENV: "{{.ENV}}"

Or define variables in the included Taskfile itself.

Workflow: Taskfile Setup

Decision Flow

USER invokes taskfile-setup
    |
    v
Run detect_taskfile.py on project root
    |
    ├── task_binary.installed = false?
    │   └── Go to "Install Task"
    |
    ├── taskfile.exists = true?
    │   └── Go to "Phase 1: Audit"
    │
    └── taskfile.exists = false?
        └── Go to "Phase 2: Scaffold"

---

Install Task

Show commands based on os field from detector:

Important: On macOS, brew install task may install taskwarrior instead. Always use brew install go-task.

After install, verify:

task --version

Re-run detector to confirm installation.

---

Phase 1: Audit

Step 1: Present Status Table

Display detection results as a formatted table:

| Component       | Status     | Detail                          |
|-----------------|------------|---------------------------------|
| task binary     | installed  | v3.40.1 at /opt/homebrew/bin/task |
| Taskfile        | found      | Taskfile.yml (version: 3)       |
| Tasks           | 18 tasks   | no includes                     |
| Ecosystems      | 3 detected | node (pnpm), jvm (gradle), docker |
| dotenv          | not config | 2 .env files found              |
| Existing runners| 2 found    | package.json scripts, gradlew   |

Step 2: Present Violations

Group by severity (ERROR first, then WARNING, then INFO):

## Audit Results

### ERRORS
| Rule | Message | Task | Line | Fix |
|------|---------|------|------|-----|
| TF001 | Missing version: '3' | — | — | Add version declaration |

### WARNINGS
| Rule | Message | Task | Line | Fix |
|------|---------|------|------|-----|
| TF002 | No preconditions | deploy | 42 | Add preconditions |
| TF005 | Missing desc | build | 12 | Add desc field |

### INFO
| Rule | Message | Task | Line | Fix |
|------|---------|------|------|-----|
| TF006 | No dotenv config | — | — | Add dotenv declaration |

Step 3: Offer Fixes

Use AskUserQuestion (multiSelect: true) listing each violation with its fix. User selects which to apply.

Step 4: Per-Rule Fix Strategies

TF001 — Missing version: '3' Add at the top of the file:

version: "3"

TF002 — No preconditions on deploy/publish tasks Add preconditions block:

tasks:
  deploy:
    desc: Deploy to production
    preconditions:
      - sh: "test -n \"$ENV\""
        msg: "ENV must be set (staging or production)"
      - sh: "git diff --quiet"
        msg: "Uncommitted changes — commit or stash first"
    cmds:
      - # existing commands

TF003 — No sources/generates on build tasks Add sources and generates:

tasks:
  build:
    desc: Build the application
    sources:
      - "src/**/*"
    generates:
      - "dist/**/*"
    cmds:
      - # existing commands

TF004 — Too many tasks in single file Propose splitting into includes. Show the suggested structure:

Taskfile.yml              # Root with includes + global vars
taskfiles/
  api.yml                 # API/backend tasks
  web.yml                 # Frontend tasks
  docker.yml              # Docker/compose tasks
  db.yml                  # Database tasks

Convert the root Taskfile:

version: "3"

includes:
  api:
    taskfile: ./taskfiles/api.yml
    dir: ./api
  web:
    taskfile: ./taskfiles/web.yml
    dir: ./web
  docker:
    taskfile: ./taskfiles/docker.yml

tasks:
  dev:
    desc: Start all services in parallel
    deps:
      - api:dev
      - web:dev

TF005 — Missing desc field Generate a desc from the task name and commands:

tasks:
  lint:
    desc: Run linters
    cmds:
      - # existing commands

TF006 — No dotenv config when .env files exist Add dotenv declaration at top level:

version: "3"

dotenv: [".env.local", ".env"]

Note: dotenv is only supported in the root Taskfile, not in included files.

TF007 — Hard-coded absolute paths Replace with variables:

# Before
tasks:
  deploy:
    cmds:
      - /usr/local/bin/kubectl apply -f /home/user/k8s/

# After
vars:
  KUBECTL: kubectl
  K8S_DIR: ./k8s

tasks:
  deploy:
    cmds:
      - "{{.KUBECTL}} apply -f {{.K8S_DIR}}/"

TF008 — deps used for sequential tasks This is INFO-level because deps: may be intentionally parallel. If the user confirms they want sequential ordering:

# Before (parallel — may cause issues if order matters)
tasks:
  ci:
    deps: [lint, test, build]

# After (sequential — guaranteed order)
tasks:
  ci:
    desc: Run CI pipeline
    cmds:
      - task: lint
      - task: test
      - task: build

Step 5: Verify

Re-run detector to confirm violations are resolved.

---

Phase 2: Scaffold

Step 1: Choose Pattern

Use AskUserQuestion to present options:

Single-file (recommended for < 15 tasks):

• All tasks in one Taskfile.yml
• Flat namespace with : separators (e.g., dev:api, test:web)
• Top-level vars: for directory paths
• Easy to discover all tasks at a glance
• Follows the Nosilha project pattern

Multi-file (recommended for 15+ tasks or monorepos):

• Root Taskfile.yml with includes:
• Per-concern files in taskfiles/ directory
• Better separation of concerns
• Avoids namespace collisions in large projects

Step 2: Choose Task Groups

Based on detected ecosystems, offer task groups via AskUserQuestion (multiSelect: true). Pre-select groups matching detected ecosystems.

Step 3: Generate Taskfile

Single-File Pattern (Nosilha-style)

version: "3"

vars:
  API_DIR: apps/api      # Adjust based on detected project structure
  WEB_DIR: apps/web

tasks:
  check:
    desc: Check prerequisites — detect missing tools
    silent: true
    cmds:
      - |
        missing=0
        check_tool() {
          if command -v "$1" &> /dev/null; then
            printf "  OK  %s\n" "$1"
          else
            printf "  MISSING  %s — install with: %s\n" "$1" "$2"
            missing=$((missing + 1))
          fi
        }
        echo "Checking prerequisites..."
        # Add check_tool calls per detected ecosystem
        if [ "$missing" -gt 0 ]; then
          echo "$missing tool(s) missing."
          exit 1
        else
          echo "All prerequisites installed."
        fi

  setup:
    desc: Full project setup
    cmds:
      - task: setup:deps
      # Add per-ecosystem setup subtasks

  setup:deps:
    desc: Install project dependencies
    cmds:
      - # Per-ecosystem install commands

  dev:
    desc: Start development servers
    deps:
      # Per-ecosystem dev tasks run in parallel

  test:
    desc: Run all tests
    cmds:
      # Per-ecosystem test tasks run sequentially

  lint:
    desc: Run all linters
    cmds:
      # Per-ecosystem lint tasks run sequentially

  clean:
    desc: Clean build artifacts
    cmds:
      # Per-ecosystem clean tasks

Multi-File Pattern

Root Taskfile.yml:

version: "3"

includes:
  api:
    taskfile: ./taskfiles/api.yml
    dir: ./apps/api
  web:
    taskfile: ./taskfiles/web.yml
    dir: ./apps/web
  docker:
    taskfile: ./taskfiles/docker.yml

tasks:
  check:
    desc: Check prerequisites
    cmds:
      - task: api:check
      - task: web:check

  setup:
    desc: Full project setup
    cmds:
      - task: api:setup
      - task: web:setup

  dev:
    desc: Start all services in parallel
    deps:
      - api:dev
      - web:dev

  test:
    desc: Run all tests
    cmds:
      - task: api:test
      - task: web:test

  lint:
    desc: Run all linters
    cmds:
      - task: api:lint
      - task: web:lint

  clean:
    desc: Clean all build artifacts
    cmds:
      - task: api:clean
      - task: web:clean

---

Ecosystem Templates

Node.js / pnpm

# For single-file, prefix with namespace (e.g., dev:web, test:web)
# For multi-file, these are standalone tasks in taskfiles/web.yml

tasks:
  dev:
    desc: Start dev server
    cmds:
      - pnpm dev

  build:
    desc: Build for production
    cmds:
      - pnpm build

  test:
    desc: Run tests
    cmds:
      - pnpm test

  lint:
    desc: Run ESLint
    cmds:
      - pnpm lint

  format:
    desc: Format code with Prettier
    cmds:
      - pnpm prettier --write .

  check:
    desc: Type-check with TypeScript
    cmds:
      - npx tsc --noEmit

Adjust commands for detected package manager (yarn, npm).

JVM / Gradle

tasks:
  build:
    desc: Build the project
    cmds:
      - ./gradlew build

  test:
    desc: Run tests
    cmds:
      - ./gradlew test

  lint:
    desc: Run linter checks
    cmds:
      - ./gradlew ktlintCheck    # Kotlin
      # or: ./gradlew checkstyleMain  # Java

  check:
    desc: Run all checks
    cmds:
      - ./gradlew check

  run:
    desc: Run the application
    cmds:
      - ./gradlew bootRun        # Spring Boot
      # or: ./gradlew run        # Plain application

  clean:
    desc: Clean build artifacts
    cmds:
      - ./gradlew clean

For Maven, replace ./gradlew with ./mvnw (or mvn).

Python / uv

tasks:
  setup:
    desc: Install dependencies
    run: once
    cmds:
      - uv sync --all-extras --dev

  dev:
    desc: Run development server
    deps: [setup]
    cmds:
      - uv run python -m app

  test:
    desc: Run tests with coverage
    deps: [setup]
    cmds:
      - uv run pytest -v --cov=src

  lint:
    desc: Lint and format code
    deps: [setup]
    cmds:
      - uv run ruff check --fix .
      - uv run ruff format .

  check:
    desc: Type-check with mypy
    deps: [setup]
    cmds:
      - uv run mypy src

  clean:
    desc: Clean Python artifacts
    cmds:
      - rm -rf dist/ build/ *.egg-info .pytest_cache .mypy_cache

For pipenv/poetry, adjust commands accordingly.

Docker / Docker Compose

vars:
  COMPOSE_FILE: docker-compose.yml    # Adjust path if needed

tasks:
  up:
    desc: Start containers
    cmds:
      - docker compose -f {{.COMPOSE_FILE}} up -d

  down:
    desc: Stop containers
    cmds:
      - docker compose -f {{.COMPOSE_FILE}} down

  logs:
    desc: Follow container logs
    cmds:
      - docker compose -f {{.COMPOSE_FILE}} logs -f {{.CLI_ARGS}}

  ps:
    desc: List running containers
    cmds:
      - docker compose -f {{.COMPOSE_FILE}} ps

  restart:
    desc: Restart containers
    cmds:
      - docker compose -f {{.COMPOSE_FILE}} restart {{.CLI_ARGS}}

  clean:
    desc: Stop and remove volumes
    cmds:
      - docker compose -f {{.COMPOSE_FILE}} down -v --remove-orphans

  build:
    desc: Build Docker images
    cmds:
      - docker compose -f {{.COMPOSE_FILE}} build

Generic (Always Available)

tasks:
  setup:
    desc: Full project setup — install tools and dependencies
    cmds:
      - echo "Add setup steps for your project"

  check:
    desc: Check prerequisites
    silent: true
    cmds:
      - |
        echo "Checking prerequisites..."
        # Add checks here

  clean:
    desc: Clean build artifacts
    cmds:
      - echo "Add clean steps for your project"

---

Verification

After scaffold or audit fixes:

1. Re-run detector:

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

2. List tasks:

   task --list

3. Show confirmation summary:

   | Step | Action | Result |
   |------|--------|--------|
   | Tool | task v3.40.1 | installed |
   | File | Taskfile.yml | created |
   | Tasks | 12 tasks | generated |
   | dotenv | .env.local, .env | configured |

4. Suggest next steps:

• task --list to see all available tasks
• task check to verify prerequisites
• task setup to run initial setup
• Commit Taskfile.yml (and taskfiles/ if multi-file) to git