claude-foundations/claude/scripting-conventions.md

Scripting Conventions

Bash safety

• Open every script with set -euo pipefail — fail fast on errors, unset vars, and pipeline failures.
• grep exits 1 on no match — under set -e use grep ... || true; under pipefail, beware grep ... | head triggering SIGPIPE (use || true on the grep side).
• One stdin per process — never pipe into a command that also reads a heredoc; pick one input source.
• Validate JSON before consuming: jq empty <file> or python3 -m json.tool <file>. Especially before dispatch loops that iterate over JSON state.
• Quote all expansions: "$var", "${array[@]}". Bare expansions split on whitespace.
• Edit-tool replace_all is a substring match — a short old_string like 2 will corrupt 24 → 244. Make old_string unique (add surrounding context) or use individual targeted edits.

Conventions

• All scripts live in scripts/ and run from the repository root
• Scripts should be idempotent and safe to re-run
• Use colour output for pass/fail indicators in verification scripts
• Verification scripts should check for default/insecure credentials and print remediation instructions on failure
• Scripts should exit non-zero on failure so && chains work naturally
• Never hardcode secrets, tokens, or access keys in scripts. Accept them via environment variables, stdin, or @file references. If a script needs a secret at runtime, read it from ~/dev/claude/secrets/ or accept it as a parameter — never embed it.