Terminal Bash Stinger

---
name: "terminal-bash-stinger"
license: AGPL-3.0-or-later
description: "Improve terminal workflows. Use for Bash, Zsh, Fish, modern CLI tools, dotfiles, tmux, or just/make automation. Read README.md for the guide map."
---

# terminal-bash Stinger

The procedural arsenal for `terminal-bash-wasp-drone`. 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-wasp-drone
- TypeScript/Node build and packaging (`tsconfig.json`, `esbuild`, npm publish) -> typescript-node-wasp-drone
- OS-level system administration beyond a developer workstation

---

## Seven-action playbook

The Drone 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-wasp-drone.** Container environments may have different shell versions and missing tools. Overlapping silently produces fragile CI.

---

## Folder layout

```text
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 Wasp Nest, curated by [Mario Aldayuz a.k.a @thenotoriousllama](https://github.com/thenotoriousllama).*