Shell Scripter

Shell Scripter

Generate, review, convert, and lint shell scripts. Makefile and justfile generation. References ShellCheck rule IDs with explanations but does NOT run ShellCheck.

Scope: Shell scripts (bash, zsh, fish, sh/POSIX), Makefiles, justfiles. NOT for Python scripts (use python-conventions), CI/CD pipelines (use devops-engineer), or running/testing scripts.

Dispatch

Auto-Detection Heuristic

1. Path to .sh/.bash/.zsh/.fish file + modification verb (review, check, fix, audit, lint) -> review
2. Path to .sh file + "to zsh/fish/bash" -> convert
3. Path to .sh file + "posix" or "portable" -> posix
4. "makefile" or "make targets" in input -> makefile
5. "justfile" or "just recipes" in input -> justfile
6. Describes desired script behavior -> create
7. Ambiguous -> ask which mode

Mode: Create

Generate a shell script from a natural language description.

Generation Process

1. Determine target dialect (default: bash)
2. Run uv run python scripts/dialect-converter.py --list-features <dialect> to confirm available features
3. Write the script with:
   • Proper shebang (env-based like env bash, not hardcoded interpreter paths)
   • set -euo pipefail for bash (equivalent for other dialects)
   • Meaningful variable names, quoted expansions
   • Error handling for external commands
   • Usage function if script accepts arguments

Validation

4. Run uv run python scripts/script-analyzer.py --stdin <<< "$SCRIPT" on the generated script
5. Fix any issues found, present final script

Mode: Review

Audit a shell script for common pitfalls. Reference ShellCheck rule IDs.

Analysis

1. Read the target script
2. Run uv run python scripts/script-analyzer.py <path>
3. Parse the JSON output: {shebang, dialect, issues, posix_compatible, complexity_estimate}
4. For each issue, load references/shellcheck-rules.md to explain the rule ID

Findings Report

5. Group findings by severity: error > warning > info > style
6. Present findings with:
   • ShellCheck rule ID (e.g., SC2086)
   • Line number and code snippet
   • Explanation of WHY it is a problem
   • Concrete fix
7. If no issues found, state this explicitly

Severity mapping:

Mode: Convert

Convert shell syntax between bash, zsh, and fish.

1. Read the source script
2. Identify source dialect (from shebang or --from flag)
3. Run uv run python scripts/dialect-converter.py <path> --from <source> --to <target>
4. Parse the JSON output: {converted_script, changes, warnings}
5. Present the converted script with a change summary table
6. Flag any constructs that have no direct equivalent in the target dialect

Mode: POSIX

Check a script for POSIX compliance at the pattern level.

1. Read the target script
2. Run uv run python scripts/script-analyzer.py <path> --posix
3. Identify bash-isms: [[ ]], (( )), arrays, local, source, process substitution, {a..z}, $'...'
4. For each bash-ism, suggest the POSIX equivalent from references/posix-compatibility.md
5. Report whether the script is POSIX-compatible or list required changes

Mode: Makefile

Generate a Makefile from task descriptions.

1. Parse task descriptions from $ARGUMENTS
2. Determine dependencies between tasks
3. Generate Makefile with:
   • .PHONY declarations for non-file targets
   • .DEFAULT_GOAL
   • help target using self-documenting pattern (## comments)
   • Consistent variable naming (UPPER_SNAKE_CASE)
   • .ONESHELL when multi-line recipes need shared state
4. Follow conventions from references/makefile-justfile.md

Mode: Justfile

Generate a justfile from task descriptions.

1. Parse task descriptions from $ARGUMENTS
2. Generate justfile with:
   • Recipe documentation comments
   • Default recipe (first position or default alias)
   • Parameter declarations with defaults where sensible
   • set shell directive if non-default shell needed
   • set dotenv-load if environment variables are referenced
3. Follow conventions from references/makefile-justfile.md

Canonical Vocabulary

Use these terms exactly throughout:

Reference Files

Load ONE reference at a time. Do not preload all references into context.

Critical Rules

1. Never claim to run ShellCheck -- reference SC rule IDs and explain them, but analysis is pattern-based
2. Always use env-based shebangs (e.g., env bash), never hardcoded interpreter paths
3. Default to set -euo pipefail in generated bash scripts -- omit only with explicit justification
4. Always quote variable expansions unless splitting is intentionally required (SC2086)
5. Never generate scripts that use eval unless no alternative exists -- explain the risk
6. Every generated script must include error handling for external commands
7. Generated Makefiles must include a .PHONY declaration and a help target
8. Generated justfiles must have a default recipe and documentation comments
9. Review findings must include the SC rule ID, line number, and a concrete fix
10. Never modify the script being reviewed -- review is read-only
11. Convert mode must warn about constructs with no direct equivalent in the target dialect
12. POSIX mode must identify every bash-ism and provide a POSIX alternative