taskfiles

---

A curated collection of reusable Taskfile include modules. Each module ships as a single YAML file under src/ and consumers wire it remotely through Taskfile's remote-taskfiles experiment. There is no build step and no runtime artefact—the YAML files themselves are the product.

Module	Tasks	Key variables
mkdocs	start	MKDOCS_PORT
kind	start, destroy, recreate	KIND_CREATE_EXTRA_ARGS
pre-commit	install, start	PYTHON_VENVS_BASEDIR
k8s	bootstrap, install-argocd	ARGOCD_EXTRA_ARGS, KUBECTL_TIMEOUT

Every task in every module sets dir: '{{.USER_WORKING_DIR}}', so commands run in the consumer project's working directory, never in this repository.

Usage

Wire the collection into a consumer Taskfile:

version: '3'

vars:
  TASK_COLLECTION_BASE: https://raw.githubusercontent.com/nolte/taskfiles/main/src

includes:
  mkdocs: "{{.TASK_COLLECTION_BASE}}/taskfile-include-mkdocs.yaml"
  kind: "{{.TASK_COLLECTION_BASE}}/taskfile-include-kind.yaml"
  pre-commit: "{{.TASK_COLLECTION_BASE}}/taskfile-include-pre-commit.yaml"
  k8s: "{{.TASK_COLLECTION_BASE}}/taskfile-include-k8s.yaml"

Run any wired task from the consumer's working directory, for example:

task mkdocs:start
task kind:recreate
task pre-commit:install
task k8s:bootstrap

Prerequisites

• go-task CLI on the PATH.
• For mkdocs:*, a Python virtual environment at ~/.venvs/docs.
• For pre-commit:*, a Python virtual environment at ~/.venvs/development.
• For kind:* and k8s:*, the underlying kind, kubectl, and helm binaries on the PATH.

The nolte/workstation playbook provisions both Python virtual environments. When a venv is missing, the affected task fails the first time it runs—provision it before invoking the task.

Pin strategy

The preceding example pins to main, which is convenient for local experimentation but exposes consumers to drift. For repeatable behaviour, pin every include to a released tag instead:

vars:
  TASK_COLLECTION_BASE: https://raw.githubusercontent.com/nolte/taskfiles/<tag>/src

Replace <tag> with a released version from the GitHub releases page. Renovate-style consumers can group every TASK_COLLECTION_BASE bump into a single pull request because all four module paths share the same base address.

Per-module overrides

Each module exposes a small set of vars: defaults. Override them with the long-form includes: syntax:

includes:
  mkdocs:
    taskfile: "{{.TASK_COLLECTION_BASE}}/taskfile-include-mkdocs.yaml"
    vars:
      MKDOCS_PORT: 8080

The rendered module pages document every task, every variable, and a copy-paste example per module.

Contributing

The full module conventions live in CLAUDE.md (intended both for humans and for AI-assisted edits) and, in narrative form, on the Contributing page of the rendered docs. The short version:

• Filenames are taskfile-include-<area>.yaml. The <area> segment is the key consumers wire under includes:.
• Every task sets dir: '{{.USER_WORKING_DIR}}' so behaviour stays anchored to the consumer's working directory.
• Tunable inputs go through vars: with a default that works out of the box.
• Python-backed tasks activate venvs at ~/.venvs/docs or ~/.venvs/development rather than installing dependencies themselves.

Pull requests run through the reusable nolte/gh-plumbing workflows. Merges are squash-only and automerge once checks pass.

Governance and specs

This repository follows the portfolio conventions shipped by nolte/claude-shared (project structure, branching model, release automation, audience identification) and consumes the reusable workflows from nolte/gh-plumbing at a pinned tag. Dependency bumps land through Renovate, which extends nolte/gh-plumbing//renovate-configs/common.

For the recorded audience analysis that drives the documentation structure, see AUDIENCES.md.

Links

• nolte/workstation: workstation configuration that provisions the Python virtual environments listed under Prerequisites.
• Taskfile.dev: upstream documentation for go-task, including the remote-taskfiles experiment.