Terminal Bash Weapon

terminal-bash Weapon

The procedural arsenal for terminal-bash-guardian. This weapon 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 → devops-guardian
• Python packaging (setup.cfg, pyproject.toml, tox) → python-guardian
• OS-level system administration beyond a developer workstation

Seven-action playbook

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

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 devops-guardian. Container environments may have different shell versions and missing tools. Overlapping silently produces fragile CI.

Folder layout

terminal-bash-weapon/
├── 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

Forged by weapon-forge from terminal-bash-guardian-command-brief.md and research/. Part of the Legion AI Tools Factory by Mario Aldayuz a.k.a @thenotoriousllama.