Agent Skills: Justfile Author

Justfile Author

Overview

Generate a justfile (and matching Makefile + tx-start helpers) following Nick's project conventions: zsh shell, DRY parameterized helpers, svc-* tmux service family wired through cortex tmux, and standard quality recipes (build, lint, dev, test, typecheck, ci, clean).

When to use this skill

• A repo lacks a justfile and the user wants one.
• A justfile exists but is missing the svc-* family, the Makefile wrapper, or the standard quality recipes.
• The user asks to add a new service window (e.g., svc-worker) to an existing justfile.
• The user asks to refactor a justfile to be more DRY or to align with the conventions captured here.

Skip this skill when:

• Editing third-party / open-source justfiles (their conventions own).
• The user has explicitly chosen make, npm scripts, or another runner for this project.

Reference example

/Users/nick/Developer/Facet/justfile and /Users/nick/Developer/Facet/Makefile are the canonical reference. When in doubt, mirror their shape.

Workflow

Step 1 — Inspect the project

Before writing anything, read the project to determine:

1. Project slug — derive from the repo directory basename.
2. Stack and package manager — what language(s), which lockfile.
3. Service catalog — what long-running processes the dev runs locally.
4. Existing tooling — what build/test/lint commands the project already uses (do not invent new ones).
5. Runtime activation needs — nvm, asdf, uv, etc.

Consult references/inspection-checklist.md for the full detection table and the exact slug-normalization rules.

Step 2 — Choose the recipe block

Pull the right language reference into context:

| Stack | Reference | | ------ | ----------------------------- | | Node | references/recipes-node.md | | Rust | references/recipes-rust.md | | Python | references/recipes-python.md| | Go | references/recipes-go.md |

For polyglot repos, read multiple references and combine. For stacks not listed, mirror the structure of the closest listed stack and substitute the native commands.

Step 3 — Choose the service catalog

Consult references/service-patterns.md for the full svc-* surface area and the rules for when to add a new service window. Every detected service gets a parallel pair of recipes (foreground + svc-) and a tx-start-<role>.sh wrapper.

Step 4 — Emit the files

Use assets/justfile.tmpl, assets/Makefile.tmpl, and assets/tx-start.sh.tmpl as the structural starting points. These are not literal templates — read them, then write the project's actual files with the inspection results substituted and the irrelevant scaffolding deleted.

Required substitutions in justfile.tmpl:

| Placeholder | Value | | ------------------- | ------------------------------------------------------ | | {{PROJECT_TITLE}} | Human-readable project name (e.g., Facet). | | {{PROJECT_SLUG}} | Normalized slug (lowercase, underscores). | | {{INSTALL_CMD}} | From the language recipe block. | | {{DEV_CMD}} | From the language recipe block. | | {{BUILD_CMD}} | From the language recipe block. | | {{TYPECHECK_CMD}} | From the language recipe block. | | {{LINT_CMD}} | From the language recipe block (omit if not configured).| | {{TEST_CMD}} | From the language recipe block. | | {{TEST_FILE_CMD}} | From the language recipe block. | | {{TEST_WATCH_CMD}}| From the language recipe block. | | {{CLEAN_CMD}} | Project-specific build artifacts. |

In Makefile.tmpl, also keep the .PHONY list and the passthrough recipe block in sync with the recipes actually emitted in the justfile — the catch-all rule pattern is intentionally NOT used; an explicit list keeps make help honest.

For each service, copy tx-start.sh.tmpl to scripts/tx-start-<role>.sh, uncomment the relevant runtime activation block, and replace {{SERVICE_CMD}} with the actual launch command. Make the script executable: chmod +x scripts/tx-start-<role>.sh.

Step 5 — Validate

After writing the files, run these checks before declaring completion:

1. just --list — must succeed and show every recipe.
2. make help — must show the passthrough list.
3. For each svc-<role> recipe: confirm a matching tx-start-<role>.sh exists, is executable, and has the right activation block uncommented.
4. just ci — should be runnable end-to-end (don't actually run it unless the user wants to; just confirm the deps resolve).
5. Confirm set shell := ["zsh", "-c"] is present and that no recipe uses bash-specific syntax that would break under zsh.

If any check fails, fix it before reporting done.

Style rules (non-negotiable)

These rules apply to every justfile produced by this skill:

• Header: comment block with project name, install hint, usage hint.
• Settings: set dotenv-load := false and set shell := ["zsh", "-c"].
• Project identity: a project justfile variable holding the normalized slug, used to derive svc_session (via env("TMUX_SESSION", project)) and every tmux_<role>_window variable. Do NOT hardcode the session name as a string literal — go through project so renaming the project means changing one line.
• Default recipe: default: @just --list.
• DRY service recipes: every svc-<role> delegates to _svc-start; every svc-stop-<role> delegates to _svc-stop. Do not inline the tmux logic into individual service recipes.
• Standard targets: install, dev, build, typecheck, lint, test, test-file, test-watch, ci, clean — emit every one that the project's tooling supports; omit the rest with no placeholder.
• ci recipe: composes the static-check recipes — at minimum typecheck, lint, test (add fmt-check for Rust/Go projects).
• Comments: one short line per recipe explaining intent. Skip if the recipe name is self-explanatory (e.g., clean:).

Style rules for the Makefile

• SHELL := /bin/bash and JUST_DEST ?= $(HOME)/bin.
• default: help showing every passthrough target.
• Single block listing every passthrough recipe; read -p prompt to install just on first use.
• test-file (and any other arg-bearing recipe) gets its own block that forwards FILE=... as a positional just arg.
• install-just cascade: brew → cargo → snap → official curl script, with JUST_DEST PATH advice if falling back to the script.

Style rules for tx-start scripts

• #!/usr/bin/env bash and set -euo pipefail.
• Resolve ROOT_DIR from ${BASH_SOURCE[0]} so the script works from any cwd.
• Activate the runtime if the project requires a specific version (otherwise leave the block commented and let the inherited shell win).
• Set env defaults via ${VAR:-default} so the parent shell or .env always wins.
• End with exec <command> (not just <command>) so the wrapper PID becomes the service PID.

Anti-patterns to avoid

• Using bash as the just shell. The project standard is zsh; use set shell := ["zsh", "-c"].
• Hardcoding the tmux session name as a string. Go through project.
• Inlining the tmux logic in every svc-* recipe. Use the _svc-start helper instead.
• Calling tmux capture-pane, tmux kill-window, etc. directly. Always go through cortex tmux.
• Putting nvm/asdf activation in the justfile. That belongs in the tx-start-*.sh wrapper.
• Adding a lint recipe when the project has no linter configured. Omit the recipe entirely; do not emit one that will fail.
• Using && chains where dependent recipes would be clearer (e.g., ci: typecheck lint test, not ci: && just typecheck && just lint && just test).
• Catch-all %: rules in the Makefile. Keep the passthrough list explicit so make help stays an honest reference.

Resources

• assets/justfile.tmpl — canonical justfile structure with svc-* family.
• assets/Makefile.tmpl — passthrough wrapper with install-just cascade.
• assets/tx-start.sh.tmpl — service launch script pattern.
• references/inspection-checklist.md — slug rules, stack detection, service catalog detection.
• references/recipes-node.md — pnpm/npm/yarn/bun command map.
• references/recipes-rust.md — cargo recipes.
• references/recipes-python.md — uv/poetry/pip recipes.
• references/recipes-go.md — go recipes.
• references/service-patterns.md — svc-* family, cortex tmux CLI, internal helper pattern.