terminal-bash Stinger

The procedural arsenal for terminal-bash-worker-bee. This stinger encodes the opinionated playbooks for every layer of the terminal productivity stack: shell runtime, modern CLI tooling, scripting safety, dotfile architecture, terminal multiplexer setup, and task automation.

When invoked, read SKILL.md first, then the relevant guide(s) for the task at hand. Research files confirm every factual claim; cite them when answering questions.

---

Scope and non-scope

In scope:

• Bash, Zsh, Fish shell configuration and migration
• Modern CLI tool adoption: ripgrep, fd, fzf, bat, eza, zoxide
• Shell scripting: safety patterns, quoting, error handling, trapping, getopts
• Dotfile architecture: XDG layout, bootstrap scripts, idempotency
• Terminal multiplexers: tmux 3.4+, Zellij 0.40+
• Task automation: just 1.30+, make (migration and coexistence)
• Shell prompts: Starship, p10k, tide (secondary - see guides/00-principles.md)

Not in scope:

• CI/CD pipelines running inside containers -> ci-release-worker-bee
• TypeScript/Node build and packaging (tsconfig.json, esbuild, npm publish) -> typescript-node-worker-bee
• OS-level system administration beyond a developer workstation

---

Seven-action playbook

The Bee performs seven distinct actions. Each maps to a guide:

Action	Guide
Audit shell configuration	guides/01-shell-audit.md
Adopt modern CLI tools	guides/02-modern-cli-tools.md
Review and fix shell scripts	guides/03-shell-scripting.md
Design dotfile structure	guides/03-shell-scripting.md (dotfile section)
Set up tmux or Zellij	guides/04-tmux-zellij.md
Set up or migrate task automation	guides/05-task-automation.md
Author findings report	templates/findings-report.md

---

Critical directives (from Command Brief)

These are non-negotiables. Full justifications in guides/00-principles.md.

1. Check portability first. Before writing Bash-specific syntax, determine whether the script must run on POSIX sh. Always ask or default to POSIX-safe unless context is clearly Bash-only.
2. Never set -e alone. The full trio is set -euo pipefail. Half-measures leave pipeline failures and unbound variables silent.
3. Quote every variable expansion. "$var" not $var. Exception: arithmetic contexts $((...)).
4. Explain tool trade-offs. ripgrep ignores hidden files by default. fd skips dotfiles. bat is not a drop-in pipe replacement. Always surface the gotcha when recommending.
5. Keep dotfile changes idempotent. Bootstrap scripts run repeatedly; source-guarding and mkdir -p patterns prevent accumulation.
6. Escalate container scripts to ci-release-worker-bee. Container environments may have different shell versions and missing tools. Overlapping silently produces fragile CI.

---

Folder layout

terminal-bash-stinger/
├── SKILL.md                       (this file - master index)
├── README.md                      (human overview)
├── guides/
│   ├── 00-principles.md           (portability tiers, escalation rules, shellcheck policy)
│   ├── 01-shell-audit.md          (how to audit .bashrc/.zshrc/config.fish)
│   ├── 02-modern-cli-tools.md     (replacement matrix + init snippets)
│   ├── 03-shell-scripting.md      (set -euo pipefail, quoting, traps, dotfiles)
│   ├── 04-tmux-zellij.md          (config, plugins, session persistence)
│   └── 05-task-automation.md      (just vs make, justfile patterns)
├── examples/
│   ├── happy-path.md              (full dotfile setup from scratch)
│   └── script-review.md          (review of a real-world shell script)
├── templates/
│   ├── bash-script-template.sh    (safe Bash script skeleton)
│   ├── justfile-template.md       (documented justfile starter)
│   └── findings-report.md        (report shape for terminal audits)
├── reports/
│   └── README.md                  (past run summaries accumulate here)
└── research/                      (authored by scripture-historian - DO NOT MODIFY)
    ├── research-plan.md
    ├── research-summary.md
    ├── index.md
    ├── internal/
    └── external/

---

Quick reference: the modern CLI stack

Legacy	Modern	Key gotcha
grep	rg (ripgrep)	Ignores hidden files by default; use --hidden
find	fd	Skips dotfiles by default; use -H
cat	bat	Not a drop-in for pipes; use --plain --no-pager
ls	eza	Not in all distro repos; may need cargo install
cd	zoxide	Requires visit-history; z won't work on unvisited dirs
Ctrl-R	fzf	Preview spawns subshell; expensive in large repos

---

Part of The Hive, curated by Mario Aldayuz a.k.a @thenotoriousllama.