z-go-taskfile

Go Taskfile (orchestration)

Preserve the project's existing build tool and approved commands. When Make and Task coexist, let Task compose environment operations and delegate existing build/test targets to [[z-go-makefile]]. Do not add Make to a Task-only project merely to enforce this split.

Single source of truth — delegate, don't duplicate

Never re-implement a Makefile command in a task. Call make:

test:
  desc: Run all Go tests (pass GO_TEST_FLAGS="-run Foo")
  vars:
    GO_TEST_FLAGS: '{{.GO_TEST_FLAGS | default ""}}'
  cmds:
    - make test GOTESTFLAGS='{{.GO_TEST_FLAGS}}'

fmt:   { desc: Format Go code, cmds: [make fmt] }
lint:  { desc: Run linter,    cmds: [make lint] }
build: { desc: Build the app, cmds: [make build] }

A copied-out go build/golangci-lint drifts from the Makefile (missing flags, stale install step). Delegation keeps them identical. The Makefile must keep process/test timeouts and concurrency caps separate from GOTESTFLAGS, which carries optional selectors only; see [[z-go-makefile]]. A command-line assignment, even empty, overrides a Make ?= default.

Discoverability

A default that lists tasks, and a one-line desc: on every task:

version: '3'
dotenv: ['.env', '.env.example']

tasks:
  default:
    desc: List all tasks
    cmds: [task --list]

Inputs

• Optional vars with fallbacks: '{{.LIMIT | default "10"}}'.
• Mandatory vars guarded up front:

migrate:create:
  desc: Create a migration (NAME=... required)
  requires: { vars: [NAME] }
  cmds:
    - 'go tool goose -dir {{.MIGDIR | shellQuote}} create {{.NAME | shellQuote}} sql'

• Free-form passthrough to a CLI: {{.CLI_ARGS}} (everything after --):

run:
  desc: 'task run -- --source X --limit 10'
  cmds:
    - 'go run ./cmd/tool {{.CLI_ARGS}}'

• Dynamic values via sh: (computed once at parse):

vars:
  RUN_DIR: { sh: 'echo "run-$(date +%Y%m%d-%H%M%S)"' }

Dependencies and safety

• deps: [db:up] boots prerequisites (and runs them in parallel) before the task.
• prompt: gates destructive actions behind a confirmation.
• task: other composes pipelines from existing tasks.

migrate:up:
  desc: Apply migrations
  deps: [db:up]
  cmds:
    - 'go tool goose -dir {{.MIGDIR | shellQuote}} postgres "$DATABASE_URL" up'

db:nuke:
  desc: Drop the database volume (DESTRUCTIVE)
  prompt: This deletes all data. Continue?
  cmds: ['{{.COMPOSE}} down -v']

Layer split, concretely

Migration nuance: a Makefile migrate-up (bare goose, no docker — for CI/remote DBs) and a Task migrate:up (deps: [db:up] then the same goose) coexist on purpose; the Task one can still delegate the goose call to make migrate-up to avoid duplicating the command.

Do not

• Re-implement build/test/lint/fmt that the Makefile owns — delegate via make.
• Omit desc: — it's what task --list shows.
• Rename a task another tool/CI/script calls (task db:up, task migrate:up) without

updating callers.

• Hide a destructive action behind an innocuous name with no prompt:.
• Re-derive env the Makefile already loads — set dotenv: once at the top.

Verify

task --list                       # renders every task with its desc
task --dry test                   # shows it expands to `make test …`, runs nothing