Taskfile Migration Guide

How to bring any Ontopix repository into compliance with the Taskfile contract and ADR-0013.

Migration rule: changes happen when a repo is next touched for meaningful work, not as a big-bang. New repos MUST follow the pattern from day one.

Migration Steps

1. Namespace flat tasks

Flat task names (no colon) must be namespaced. Common renames:

Exceptions: default, help, clean, clean:deep may remain flat.

2. Replace CI rollup

If the repo uses validate:all or bare ci: as a CI rollup, replace with decomposed ci:*:

Before:

validate:all:
  cmds:
    - task: lint:all
    - task: test:all

# or

ci:
  cmds:
    - task: lint:check
    - task: test:all

After:

ci:lint:
  desc: "Run all CI lint checks"
  cmds:
    - task: lint:all
    - task: validate:structure

ci:test:
  desc: "Run all CI tests"
  cmds:
    - task: test:all

ci:all:
  desc: "Run full CI pipeline locally"
  cmds:
    - task: ci:lint
    - task: ci:test

Keep validate:* tasks that do domain validation (e.g., validate:structure, validate:schemas). Only the CI rollup role moves to ci:all.

3. Add dev:setup

If the repo lacks a first-use setup task, add one:

dev:setup:
  desc: "First-use setup: install deps, configure env, validate structure"
  cmds:
    - |
      if [ ! -f .env ]; then
        cp .env.example .env
        echo "Created .env from .env.example — review and adjust values."
      fi
    - task: dev:install
    - task: validate:structure
    - echo ""
    - echo "Setup complete. Next steps:"
    - echo "  1. Review .env and set any required values"
    - echo "  2. task dev:run    — start the application"
    - echo "  3. task --list     — see all available operations"

4. Fix environment variable handling

Replace hardcoded values with overridable defaults:

Before:

env:
  AWS_PROFILE: ontopix-dev

After:

dotenv: ['.env']

vars:
  AWS_PROFILE: '{{.AWS_PROFILE | default "ontopix-dev"}}'

Ensure .env.example exists with all supported variables documented.

5. Fix sandbox naming

If the repo uses sandbox:up / sandbox:down, rename to sandbox:start / sandbox:stop.

6. Fix infra:fmt

Ensure infra:fmt uses -recursive:

infra:fmt:
  desc: Check Terraform formatting
  dir: .infra
  cmds:
    - terraform fmt -check -recursive

7. Fix CodeArtifact login

If the repo uses aws codeartifact login --tool npm (method B), replace with the token-based approach:

deps:login:npm:
  desc: "Get CodeArtifact token for npm/pnpm — use: eval $(task deps:login:npm)"
  silent: true
  cmds:
    - |
      TOKEN=$(aws codeartifact get-authorization-token \
        --domain ontopix \
        --region {{.AWS_REGION}} \
        --query authorizationToken \
        --output text)
      echo "export NPM_TOKEN=$TOKEN"

8. Add release:* for library repos

If the repo publishes packages to an artifact registry (CodeArtifact, npm, PyPI), add the release:* namespace:

release:publish:
  desc: "Publish built artifacts to registry"
  cmds:
    - task: deps:login:npm
    - |
      for pkg in {{.PACKAGES}}; do
        pnpm publish --no-git-checks {{.PACKAGES_DIR}}/${pkg}
      done
  preconditions:
    - sh: test -d {{.PACKAGES_DIR}}
      msg: "Packages not built. Run 'task build:dist' first."

release:version:
  desc: "Sync VERSION to package manifests and rebuild"
  cmds:
    - |
      VERSION=$(cat VERSION)
      sed -i '' 's/^version = .*/version = "'"${VERSION}"'"/' pyproject.toml
    - task: build:dist

release:all:
  desc: "Full release pipeline: sync version, build, publish"
  cmds:
    - task: release:version
    - task: release:publish

release:all chains build:dist so artifacts are always rebuilt from the current version before publishing.

9. Update CI workflows

Ensure GitHub Actions workflows call task ci:all (or decomposed ci:lint, ci:test, ci:build) instead of invoking tools directly.

10. Update AGENTS.md

Ensure the repo's AGENTS.md references the current task names and namespaces.

Compliance Checklist

Run this checklist against any repo to verify compliance. All MUST items are required; SHOULD items are recommended.

Structure

• Taskfile.yaml exists at repo root (MUST)
• dotenv: ['.env'] is set in Taskfile (MUST)
• .env.example exists with documented variables (MUST)
• .env is in .gitignore (MUST)
• All operational tasks are namespaced (no flat names except default, help, clean) (MUST)
• All tasks have desc: field (MUST)

Naming

• Task names follow namespace:action or namespace:action:target format (MUST)
• Maximum 3 segments per task name (MUST)
• Hyphens for multi-word segments, no abbreviations (MUST)

Developer Lifecycle

• dev:setup exists and is idempotent (MUST)
• dev:install exists (MUST)
• dev:run exists (MUST, if the repo has a runnable application)

CI Pipeline

• ci:all exists and runs the full CI pipeline (MUST)
• ci:lint exists (MUST)
• ci:test exists (MUST)
• ci:build exists (SHOULD, if repo produces artifacts)
• task ci:all passing locally guarantees CI will pass (MUST)

Code Quality

• lint:check exists (MUST)
• lint:fix exists (MUST)
• lint:all exists as composite (MUST, if more than one lint task)
• test:unit exists (MUST, if tests exist)
• test:all exists (MUST)

Sandbox

• sandbox:start / sandbox:stop exist (MUST, if sandbox is applicable)
• Uses start/stop naming, not up/down (MUST)

Infrastructure

• infra:fmt uses terraform fmt -check -recursive (MUST, if infra exists)
• infra:plan / infra:apply exist (MUST, if infra exists)

Environment

• Variables use vars: with default, not hardcoded env: (MUST)
• ENV variable with precondition for environment-scoped tasks (MUST)
• Destructive operations omit ENV default to force explicit choice (SHOULD)

Release (library repos)

• release:publish exists (MUST, if repo publishes packages)
• release:version exists (SHOULD, if repo uses VERSION file)
• release:all chains build:dist before publish (SHOULD)

Dependencies

• CodeArtifact login uses token-based approach, not aws codeartifact login --tool (MUST)
• deps:login:npm outputs eval-able export (SHOULD)