loadout: Instructions file for GitHub Copilot

Shell Script Engineering Instructions (Bash, CLI wrappers, automation) 🐚

These instructions define the default engineering approach for writing production-grade shell scripts in Bash.

They must remain applicable to:

• Standalone CLI utility scripts
• Git hook scripts
• CI/CD pipeline scripts
• Tool wrapper scripts (native/Docker dual execution)
• Library scripts sourced by other scripts
• Report generation and automation scripts

They are non-negotiable unless an exception is explicitly documented (with rationale and expiry) in an ADR/decision record.

Cross-references. For Makefile orchestration conventions that call shell scripts, see makefile.instructions.md. This file focuses exclusively on shell script patterns.

Identifier scheme. Every normative rule carries a unique tag in the form [SH-<prefix>-NNN], where the prefix maps to the containing section (for example QR for Quick Reference, HDR for Header, FN for Functions, VAR for Variables, ERR for Error Handling, DOC for Documentation). Use these identifiers when referencing, planning, or validating requirements.

---

0. Quick reference (apply first) 🧠

This section exists so humans and AI assistants can reliably apply the most important rules even when context is tight.

• [SH-QR-001] Shebang and safety: start with #!/usr/bin/env bash and set -euo pipefail ([SH-HDR-001], [SH-HDR-003]).
• [SH-QR-002] Header structure: include WARNING comment, safety options, description block, and section dividers ([SH-HDR-002], [SH-HDR-004]).
• [SH-QR-003] main() entry point: use a main() function as the script entry point, called at the bottom of the file ([SH-FN-001]).
• [SH-QR-004] Kebab-case functions: name functions using kebab-case (lowercase with hyphens) ([SH-FN-002]).
• [SH-QR-005] Document all functions: provide comment blocks describing purpose and arguments ([SH-DOC-001]–[SH-DOC-004]).
• [SH-QR-006] Native/Docker dual execution: scripts should run tools natively if installed, or fall back to Docker ([SH-EXEC-001]–[SH-EXEC-005]).
• [SH-QR-007] is-arg-true() helper: use a standard boolean-parsing helper for environment flags ([SH-VAR-006]).
• [SH-QR-008] VERBOSE toggle: support VERBOSE=true to enable set -x for debugging ([SH-DBG-001]–[SH-DBG-003]).
• [SH-QR-009] Exit 0 at end: scripts must end with exit 0 after successful execution ([SH-ERR-005]).
• [SH-QR-010] Test suite patterns: use Arrange-Act-Assert structure, setup/teardown functions, and summary reporting ([SH-TST-001]–[SH-TST-015]).
• [SH-QR-011] Avoid common anti-patterns: unquoted variables, cd without error handling, hardcoded paths (§12).
• [SH-QR-012] Explicit returns: finish every function with an explicit return <status> so intent and requirements stay aligned ([SH-FN-008]).