zekzekus/dotfiles/authoring-repo-tasks

Authoring repo-local tasks

In a Babashka-based repository, task implementation (build, test, lint, run, format, release) lives in one source of truth — `bb.edn` — with a thin `Makefile` command facade. Logic goes in the bb task; the Makefile target is a one-line shim that calls it. Never duplicate real logic across the two.

When this applies

• Adding a task runner to a repo that has none, after Babashka has been selected

by local guidance or explicitly requested.

• The user explicitly asks to adopt Babashka tasks in a repo that currently has

only a Makefile.

• Task definitions are duplicated between bb.edn and Makefile and have drifted.

Do not introduce Babashka merely because a repository has a Makefile. Follow the repository's existing command architecture unless the user requests a change.

First: detect what exists

ls bb.edn Makefile deps.edn flake.nix

• bb.edn present → add/adjust tasks there; keep the Makefile a pure mirror.
• Only Makefile → preserve it unless the user explicitly requested Babashka;

if requested, move each recipe's logic into a bb.edn task and reduce the Makefile target to bb <task>.

• Neither → create both only when Babashka is the chosen local task runner.

The pattern

bb.edn — the source of truth

Every task carries a :doc. Use babashka.tasks/shell for shell commands and clojure for clj -T/-M/-X invocations. Guard for run and uberjar with :override-builtin true (they shadow bb builtins). Set :dir when a task runs in a subdirectory.

{:tasks {:requires ([babashka.fs :as fs]
                    [babashka.tasks :refer [shell]])
 
         run     {:doc  "starts the app"
                  :override-builtin true
                  :task (clojure {:dir "."} "-M:dev")}
 
         test    {:doc  "runs tests"
                  :task (clojure {:dir "."} "-M:test")}
 
         lint    {:doc  "lints src and test"
                  :task (shell "clj-kondo --lint src test")}
 
         uberjar {:doc  "builds the uberjar"
                  :override-builtin true
                  :task (clojure {:dir "."} "-T:build all")}
 
         format  {:doc  "formats codebase"
                  :task (shell {:dir "src"} "cljstyle fix")}
 
         clean   {:doc  "removes build output"
                  :task (fs/delete-tree "target")}}}

List available tasks with their docs:

bb tasks

Makefile — the mirror

Each target is a one-line bb <task> shim. The bb task name and the make target match.

.PHONY: clean run test lint uberjar format
 
clean:
	bb clean
 
run:
	bb run
 
test:
	bb test
 
lint:
	bb lint
 
uberjar:
	bb uberjar
 
format:
	bb format

Conventions

• One source of truth. Real logic lives in the bb task; the Makefile target

is a one-line bb <task> shim. If you change a task, you change bb.edn.

• Names match between the bb task and the Makefile target.
• Every bb task has a `:doc` so bb tasks is self-documenting.
• `:override-builtin true` on tasks that shadow bb builtins such as run

and uberjar.

• `:dir` for tasks that run in a subdirectory (e.g. test/e2e, src).
• Prefer task dependencies, babashka.tasks/run, or Clojure/Babashka functions

for multi-step logic. Reuse a maintained project script only when scripts are already an established architectural boundary or the logic independently warrants a maintained module; do not create one-off scripts to escape task composition.

• Don't add Makefile-only targets that carry task logic — promote them to bb

tasks first.

Verify

bb tasks            # all tasks listed with docs
bb test             # the bb path works
make test           # the mirror reaches the same task

If local guidance or inspection establishes that a flake dev shell owns the environment, run these inside it (load the running-in-nix-flake skill) so bb, clojure, and clj-kondo come from the pinned environment.