011-black-jack/.agents/skills/coding-conventions/references/shell.md

Shell conventions (bash)

Standard base

Bash 4 or later, POSIX test semantics through [[ ]]. Start every script with #!/usr/bin/env bash and set -euo pipefail. State the bash version and the external tools it needs in the header comment.

Naming

Element	Convention	Example
Script file	kebab-case.sh, executable	check-plan.sh, new-artifact.sh
Function	snake_case, a verb	read_registry, die
Local variable, parameter	snake_case, declared with local	msgfile, changed
Constant, environment variable	UPPER_SNAKE	PLAN_GATE, PROJECT_ROOT
Boolean	is_ / has_ prefix, value 0 or 1	is_enabled=1

• Name a script and its functions by what they do, not how.
• Do not shadow a command with a function of the same name.

Formatting

• 2 spaces, no tabs. One command per line; then and do on the same line as if and for. Keep lines near 80 characters; break long pipelines at |.
• Format with shfmt -i 2 -ci; lint with shellcheck. Commit the project's .editorconfig or .shellcheckrc with the code.

Language rules

• Quote every expansion ("$var", "${arr[@]}"); use arrays, not space-separated strings, for lists. Use [[ ]], not [ ], and $(...), not backticks.
• Declare function variables local; no globals except constants.
• Parse options with case and shift, check required arguments with "${1:?usage: ...}", and print a usage line on bad input.
• Read input with read -r; iterate files with globs or find -print0, never by parsing ls.
• Use mktemp for temporary files and remove them with trap ... EXIT; never a fixed /tmp name.

Errors and exit codes

• Errors go to standard error, start with error:, say what is wrong and what to do, and end the script with a non-zero exit code (die helper).
• 0 is success, 1 a failed check or bad input, 2 a usage error; document any other code in the header.
• Never swallow a failure with || true without a comment that says why.

Safety

• A script that changes state outside its own directory defaults to a dry run or asks for an explicit flag (--apply, --force); say so in the header.
• Never echo a token or password, put one on a command line, or commit one; read secrets from the environment or a gitignored file.
• Do not eval input; do not build a command from unvalidated text.

Tools

Formatter shfmt, linter shellcheck, syntax check bash -n. These are the recommended tools, not a pipeline: enforcing them in CI is outside this framework's scope.