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.