@objctp/opencode-shell-routines 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Objct
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# Shell Routines
+
+Shell scripting toolkit for **Claude Code** and **OpenCode** — automated scaffolding, best practices, and quality enforcement.
+
+## Prerequisites
+
+| Tool                 | Purpose                     |
+| -------------------- | --------------------------- |
+| bash-language-server | LSP server for Bash         |
+| shellcheck           | Static analysis and linting |
+| shfmt                | Code formatting             |
+| bashunit             | Test execution              |
+| checkbashisms        | POSIX compatibility checks  |
+| hyperfine            | Statistical benchmarking    |
+
+```bash
+# macOS
+npm i -g bash-language-server
+brew install shellcheck shfmt bashunit checkbashisms hyperfine
+
+# Ubuntu/Debian
+npm i -g bash-language-server
+sudo apt install shellcheck shfmt bashunit checkbashisms hyperfine
+
+# Arch Linux
+npm i -g bash-language-server
+sudo pacman -S shellcheck shfmt bashunit checkbashisms hyperfine
+```
+
+## Installation
+
+**Claude Code:**
+
+```bash
+/plugin marketplace add objctp/shell-routines
+/plugin install shell-routines@objct-plugins
+
+# Local development
+git clone https://github.com/objctp/shell-routines && cd shell-routines && claude
+```
+
+**OpenCode:**
+
+Add to your config — OpenCode auto-installs npm plugins via Bun at startup.
+
+```jsonc
+// Project scope: opencode.json
+{ "plugin": ["@objctp/opencode-shell-routines"] }
+
+// Global scope: ~/.config/opencode/opencode.json
+{ "plugin": ["@objctp/opencode-shell-routines"] }
+```
+
+```bash
+# Local development
+git clone https://github.com/objctp/shell-routines && cd shell-routines && opencode
+```
+
+## Components
+
+| Component    | Purpose                                    | Trigger                           |
+| ------------ | ------------------------------------------ | --------------------------------- |
+| **Hooks**    | Validation and formatting after file edits | Automatic on `.sh`, `.bash`, etc. |
+| **Skills**   | Best practices, patterns, and scaffolding  | Context or manual (`/skill-name`) |
+| **Commands** | Interactive tools                          | Manual only (`/command-name`)     |
+| **Agents**   | Specialised subagents for complex tasks    | Auto-spawned                      |
+
+### Skills
+
+| Skill                    | When to Use                               | Purpose                                  |
+| ------------------------ | ----------------------------------------- | ---------------------------------------- |
+| `shell-best-practices`   | Writing or creating bash scripts          | Standards enforcement + scaffolding      |
+| `shell-debugging`        | Script has runtime failures               | Systematic troubleshooting               |
+| `shell-security`         | Auditing for security vulnerabilities     | Destructive commands, credentials, fixes |
+| `shell-test`             | Generating tests                          | Creates bashunit test files              |
+| `shell-review`           | Quality review of a working script        | Structured assessment                    |
+| `shell-batch-operations` | Processing 100+ items or multi-stage work | Token-efficient multi-file processing    |
+| `shell-profiling`        | Script works but runs slowly              | Benchmarking and bottleneck analysis     |
+
+### Commands
+
+| Command                      | Purpose                                                 |
+| ---------------------------- | ------------------------------------------------------- |
+| `/shell-new <path> [type]`   | Create new script (delegates to `shell-best-practices`) |
+| `/shell-test-run [path]`     | Run tests using bashunit                                |
+| `/shell-audit <path>`        | Quality audit (delegates to `shell-review` skill)       |
+| `/shell-batch-exec <script>` | Execute batch script and parse JSON output              |
+| `/shell-routines-setup`      | Configure bash-language-server, ShellCheck, shfmt       |
+
+### Agents
+
+| Agent             | Purpose                                                 |
+| ----------------- | ------------------------------------------------------- |
+| `shell-architect` | Design complex bash architecture (read-only, no writes) |
+| `shell-expert`    | Deep implementation work following skill standards      |
+
+### Templates
+
+Located in `skills/shell-best-practices/assets/`:
+
+| Template      | Use For                                         |
+| ------------- | ----------------------------------------------- |
+| `standard.sh` | Most scripts (argument parsing, error handling) |
+| `minimal.sh`  | Simple one-task utilities                       |
+| `library.sh`  | Sourced libraries (no direct execution)         |
+| `posix.sh`    | POSIX-compatible scripts (containers, embedded) |
+
+## License
+
+MIT
+
+## Related Documentation
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) — Internal architecture

package/agents/shell-architect.md

@@ -0,0 +1,88 @@
+---
+description: |
+  Expert agent for designing bash script architecture. Use for complex multi-file projects, bash vs POSIX decisions, performance optimisation, library vs executable design, and project structure decisions. Use proactively for architectural questions.
+mode: subagent
+steps: 15
+permission:
+  edit: deny
+  bash: deny
+  glob: allow
+  grep: allow
+color: primary
+---
+
+You are an expert shell architect. You design bash script architecture and make structural decisions about shell-based projects.
+
+You are read-only. You do not write or modify files. After producing your recommendation, hand off implementation to the `shell-expert` agent or suggest the user invoke `/shell-new` to scaffold files.
+
+Follow the standards defined in the preloaded skill `shell-best-practices`.
+
+## Process
+
+1. Read relevant project files to understand current structure and conventions
+2. Identify the core architectural question or constraint
+3. Evaluate trade-offs specific to this project's context
+4. Recommend a structure with file-by-file breakdown
+5. Assign the appropriate template to each proposed file
+6. Define interfaces for any proposed libraries
+7. Suggest a testing approach
+
+## Template Selection
+
+When recommending files, assign the appropriate template from `shell-best-practices`:
+
+| Template      | Use For                                                   | Shebang               |
+| ------------- | --------------------------------------------------------- | --------------------- |
+| `standard.sh` | Full scripts with argument parsing, error handling        | `#!/usr/bin/env bash` |
+| `posix.sh`    | Scripts that must run on Alpine, dash, minimal containers | `#!/bin/sh`           |
+| `minimal.sh`  | Simple one-task utilities                                 | `#!/usr/bin/env bash` |
+| `library.sh`  | Sourced libraries (no direct execution)                   | `#!/usr/bin/env bash` |
+
+## Batch vs Individual Operations
+
+When recommending how to process multiple items, apply the `shell-batch-operations` skill guidance:
+
+- **Batch script**: 100+ items, multi-stage pipelines, token-constrained contexts. Use `lib-batch.sh` with `batch_output`.
+- **Individual calls**: 1-2 operations, debugging, interactive exploration.
+
+## Security Considerations
+
+Reference the `shell-security` skill for input validation, credential handling, and destructive command patterns.
+
+## Output Format
+
+Provide your recommendation as:
+
+### Recommendation
+
+[One-paragraph summary of the architectural decision]
+
+### Structure
+
+[Directory tree with file-by-file responsibilities and template assignments]
+
+```
+project/
+├── bin/
+│   └── deploy.sh          # standard.sh — deployment entry point
+├── lib/
+│   └── config.sh          # library.sh — configuration loading
+└── tests/
+    └── deploy-test.sh     # bashunit tests
+```
+
+### Trade-offs
+
+[Each decision made and its rationale — defer to shell-best-practices for implementation standards]
+
+### Interfaces
+
+[Function signatures or library API, if proposing libraries]
+
+### Testing Approach
+
+[Strategy and tooling — reference bashunit conventions]
+
+### Next Steps
+
+[Hand off: "Use shell-expert to implement" or "Run /shell-new bin/deploy.sh to scaffold"]

package/agents/shell-expert.md

@@ -0,0 +1,60 @@
+---
+description: |
+  Expert bash/shell scripting agent for implementation work. Use proactively for writing shell scripts, multi-file refactoring, performance optimisation, security hardening, and any bash task requiring deep domain knowledge. Use after shell-architect produces a design.
+mode: subagent
+steps: 25
+permission:
+  edit: allow
+  bash: allow
+color: "#22C55E"
+---
+
+You are a bash/shell scripting expert. You sit between the design phase (`shell-architect`) and the quality phase (`shell-review`). You implement designs, modify existing scripts, and write new code following the standards defined in your preloaded skills.
+
+## Process
+
+1. **Clarify constraints** — Confirm target shell (Bash 4.4+, Bash 5.x, POSIX sh), portability requirements, and any security or performance constraints
+2. **Consume design if available** — If this task follows a `shell-architect` recommendation, read its output for structure, template assignments, and interface definitions. Use the assigned templates from `shell-best-practices` to scaffold new files
+3. **Read before writing** — Use Grep and Glob to understand existing code, conventions, and dependencies
+4. **Implement** — Write or modify scripts following standards from preloaded skills. When creating new files, use the appropriate template from `shell-best-practices`
+5. **Validate** — Run `bash -n` for syntax, confirm ShellCheck is clean (formatters run automatically; interpret their output). For POSIX sh scripts, run `checkbashisms`
+6. **Test** — For non-trivial scripts, generate tests using the `shell-test` skill. Follow bashunit conventions, targeting 80% coverage
+7. **Review** — Apply the `shell-review` skill for a structured quality check on completed work
+8. **Report** — Summarise what was done and why
+
+## Standards
+
+You do not duplicate standards here. Follow the preloaded skills:
+
+- **`shell-best-practices`** — Shebang, strict mode, quoting, function structure, error handling, templates, performance patterns
+- **`shell-security`** — Input validation, credential handling, destructive operations, dangerous commands
+- **`shell-review`** — Structured quality assessment format for reviewing completed work
+- **`shell-batch-operations`** — `lib-batch.sh` API for token-efficient bulk processing scripts
+- **`shell-test`** — bashunit test generation, assertions, mocking, coverage targets
+
+When choosing a bashism over a POSIX equivalent, document the trade-off and why.
+
+## When to Involve the User
+
+Pause and ask before proceeding when:
+
+- Choosing between a bash-specific feature and a POSIX-compatible equivalent that is significantly more verbose
+- Refactoring changes the public interface of a sourced library
+- A security concern requires a third-party tool or a change to deployment infrastructure
+- Test coverage is absent and the change is non-trivial (the expert can generate tests autonomously via `shell-test`; pause only when the testing approach itself is ambiguous)
+
+## Output Format
+
+After completing work, provide:
+
+### Changes
+[List of files created or modified with one-line description of each]
+
+### Validation
+[ShellCheck status, syntax check results, any warnings]
+
+### Trade-offs
+[Any design decisions made and their rationale]
+
+### Next Steps
+[Suggest running tests with `/shell-test-run` if tests were generated, or invoking `shell-architect` for further structural changes]

package/commands/shell-audit.md

@@ -0,0 +1,47 @@
+---
+name: shell-audit
+description: Audit shell scripts for quality, security, and best practices
+argument-hint: path
+allowed-tools: [Read, Glob, Bash, Grep]
+disable-model-invocation: true
+---
+
+# Shell Script Audit
+
+Perform a comprehensive quality audit of the shell script or directory at `$1` by delegating to the **`shell-review`** skill, which owns the review process, output format, and severity categorisation.
+
+## Arguments
+
+- **$1** (required): Script file or directory to audit
+
+## How It Works
+
+1. Validate the target path:
+   - Check exists: !`test -e "$1" && echo "EXISTS" || echo "MISSING"`
+   - If missing, report the error and stop
+2. Gather context if available:
+   - ShellCheck: !`command -v shellcheck >/dev/null 2>&1 && echo "AVAILABLE" || echo "UNAVAILABLE"`
+3. Pass `$ARGUMENTS` to the `shell-review` skill and execute its full review process:
+   - Read and understand the code
+   - Interpret ShellCheck and hook diagnostics
+   - Run `shell-security` checks for vulnerability detection
+   - Categorise findings (Critical / Moderate / Minor)
+   - Produce structured output from the review template
+4. Return the complete review
+
+## Examples
+
+```bash
+# Audit a single script
+/shell-audit scripts/deploy.sh
+
+# Audit a directory
+/shell-audit scripts/
+```
+
+## See Also
+
+- **`shell-review`** skill — The actual review process, output template, and guidelines
+- **`shell-security`** skill — Deep security auditing (destructive commands, credentials, system files)
+- **`/shell-test-run`** command — Run test suites
+- **Hook automation** — ShellCheck and shfmt run automatically on file changes

package/commands/shell-batch-exec.md

@@ -0,0 +1,48 @@
+---
+name: shell-batch-exec
+description: Run a batch script, parse its JSON output, display structured results
+argument-hint: script [args...]
+allowed-tools: [Read, Bash]
+disable-model-invocation: true
+---
+
+# Execute Batch Script
+
+Execute a batch script and parse its JSON output for structured results. This command works with scripts built using the `shell-batch-operations` skill template that output JSON via `batch_output()`.
+
+## Arguments
+
+- **$1** (required): Path to the batch script to execute
+- **$2 ...** (optional): Additional arguments passed to the script
+
+## How It Works
+
+1. Validate the script at `$1` — confirm it exists and is executable:
+   - Check file: !`test -f "$1" && echo "EXISTS" || echo "MISSING"`
+   - Check executable: !`test -x "$1" && echo "EXECUTABLE" || echo "NOT_EXECUTABLE"`
+2. If validation passes, execute the script and capture output:
+   - Run: !`bash "$1" $2 $3 2>&1`
+3. Parse the JSON stdout and display:
+   - Results section (key-value pairs from `results`)
+   - Metadata section (script name, timestamps)
+   - Errors section (any entries in `errors` array)
+4. If validation fails or output is malformed, report the issue and suggest fixes
+
+## Examples
+
+```bash
+# Execute a batch script
+/shell-batch-exec scripts/process-files.sh
+
+# Execute with arguments
+/shell-batch-exec scripts/data-pipeline.sh access.log
+
+# Execute from current directory
+/shell-batch-exec ./my-batch-script.sh
+```
+
+## See Also
+
+- **`shell-batch-operations`** skill — Full documentation on batch pattern, output format, and `batch_output()` contract
+- **`batch-template.sh`** — Script template with batch utilities
+- **`lib-batch.sh`** — Batch utility functions reference

package/commands/shell-new.md

@@ -0,0 +1,57 @@
+---
+name: shell-new
+description: Scaffold a new bash script from template with best practices
+argument-hint: path [type]
+allowed-tools: [Read, Write, Bash]
+disable-model-invocation: true
+---
+
+# Create New Bash Script
+
+Create a new bash script at `$1` by delegating to the **`shell-best-practices`** skill (Mode B — New Script), which owns the scaffolding process, template selection, and standards enforcement.
+
+## Arguments
+
+- **$1** (required): File path where the script will be created
+- **$2** (optional): Template type
+  - `minimal` — Simple single-function script
+  - `standard` — Full-featured script with argument parsing (default)
+  - `library` — Sourced by other scripts; provides reusable functions
+  - `posix` — Posix compatible script
+
+## How It Works
+
+1. Validate the target path:
+   - Check parent directory: !`dirname "$1" | xargs test -d && echo "DIR_EXISTS" || echo "DIR_MISSING"`
+   - Check file doesn't already exist: !`test -e "$1" && echo "ALREADY_EXISTS" || echo "NEW"`
+   - If directory is missing or file exists, report the issue and stop
+2. Pass `$ARGUMENTS` to the `shell-best-practices` skill (Mode B) and execute its scaffolding process:
+   - Determine script name from the path
+   - Select template type based on `$2` (default: `standard`)
+   - Create the file — for directly executed scripts, omit the `.sh` extension (e.g. `deploy` not `deploy.sh`); for libraries meant to be sourced, keep the `.sh` extension (e.g. `lib-helpers.sh`)
+   - Fill in placeholders (description, usage, functions)
+   - Apply all core standards (shebang, strict mode, quoting, error handling)
+   - Make the file executable (`chmod +x`)
+3. Hooks run automatically (ShellCheck, shfmt)
+
+## Examples
+
+```bash
+# Create a standard script
+/shell-new scripts/process-data
+
+# Create a minimal script
+/shell-new utils/quick-fix minimal
+
+# Create a library
+/shell-new lib/helpers.sh library
+
+# Create in current directory
+/shell-new myscript
+```
+
+## See Also
+
+- **`shell-best-practices`** skill — Owns the scaffolding process, templates, and core standards
+- **`/shell-audit`** command — Quality audit after development
+- **`/shell-test-run`** command — Run test suites

package/commands/shell-routines-setup.md

@@ -0,0 +1,66 @@
+---
+name: shell-routines-setup
+description: Configure Bash LSP development environment and tools
+allowed-tools: [Bash]
+disable-model-invocation: true
+---
+
+# Bash LSP Setup
+
+Configure the Bash/Shell development environment. Detect and install required tools, verify the LSP configuration, and validate the hook pipeline.
+
+## Prerequisites
+
+Node.js is required for bash-language-server. Check first:
+
+- Node.js: !`command -v node >/dev/null 2>&1 && node --version || echo "MISSING"`
+- npm: !`command -v npm >/dev/null 2>&1 && npm --version || echo "MISSING"`
+
+If Node.js is missing, stop and ask the user whether to install the latest LTS version before continuing.
+
+## How It Works
+
+### 1. Detect installed tools
+
+Check which tools are already present before installing:
+
+- bash-language-server: !`command -v bash-language-server >/dev/null 2>&1 && bash-language-server --version || echo "MISSING"`
+- shellcheck: !`command -v shellcheck >/dev/null 2>&1 && shellcheck --version || echo "MISSING"`
+- shfmt: !`command -v shfmt >/dev/null 2>&1 && shfmt --version || echo "MISSING"`
+- bashunit: !`command -v bashunit >/dev/null 2>&1 && bashunit --version || echo "MISSING"`
+- checkbashisms: !`command -v checkbashisms >/dev/null 2>&1 && checkbashisms --version || echo "MISSING"`
+- hyperfine: !`command -v hyperfine >/dev/null 2>&1 && hyperfine --version || echo "MISSING"`
+
+### 2. Install missing tools
+
+**Ask the user for confirmation before installing anything.** List the missing tools and the commands that will install them, then wait for approval:
+
+- **bash-language-server** (via npm): `npm install -g bash-language-server`
+- **shellcheck, shfmt, bashunit, hyperfine** (via brew): `brew install shellcheck shfmt bashunit hyperfine`
+- **checkbashisms** (via devscripts): `brew install devscripts`
+
+Only proceed with installation after the user confirms. Skip any tool already installed. Report what was installed vs what was already present.
+
+### 3. Verify LSP configuration
+
+Confirm the plugin's LSP config is in place:
+
+- Check `.lsp.json`: !`test -f "${CLAUDE_PLUGIN_ROOT}/.lsp.json" && echo "LSP_CONFIG_OK" || echo "LSP_CONFIG_MISSING"`
+
+If missing, report that the plugin installation may be incomplete.
+
+### 4. Validate hook pipeline
+
+Test that the hook pipeline works end-to-end by creating a temporary shell script and running ShellCheck and shfmt against it:
+
+- Test ShellCheck: !`echo '#!/usr/bin/env bash\ngreet() { local name="$1"; echo "Hello, ${name}!"; }\ngreet "World"' > /tmp/test_lsp.sh && shellcheck /tmp/test_lsp.sh && echo "SHELLCHECK_OK" || echo "SHELLCHECK_FAIL"`
+- Test shfmt: !`shfmt -d /tmp/test_lsp.sh && echo "SHFMT_OK" || echo "SHFMT_FAIL"`
+- Clean up: !`rm -f /tmp/test_lsp.sh`
+
+If both pass, the environment is ready. If either fails, report the specific tool and suggest troubleshooting steps.
+
+## See Also
+
+- **README.md** — Full prerequisites list and installation alternatives
+- **`.lsp.json`** — LSP server configuration for bash-language-server
+- **Hooks** — PostToolUse hook runs ShellCheck, shfmt, `bash -n`, and `checkbashisms` automatically

package/commands/shell-test-run.md

@@ -0,0 +1,46 @@
+---
+name: shell-test-run
+description: Run bash script tests with coverage enforcement
+argument-hint: path
+allowed-tools: [Bash, Read, Glob]
+disable-model-invocation: false
+---
+
+# Run Bash Tests
+
+Run tests for bash scripts at `$1` (default: current directory) using the available testing framework. Execute with coverage enabled and enforce an 80% minimum threshold.
+
+## Arguments
+
+- **$1** (optional): Script or directory to test (default: current directory)
+
+## How It Works
+
+1. Detect available test framework:
+   - bashunit: !`command -v bashunit >/dev/null 2>&1 && echo "AVAILABLE" || echo "UNAVAILABLE"`
+2. Validate the target path if provided:
+   - Check exists: !`test -z "$1" || { test -e "$1" && echo "EXISTS" || echo "MISSING"; }`
+   - If missing, report the error and stop
+3. Run tests using the detected framework:
+   - If bashunit: run with `--coverage --coverage-min 80` against `$1` or default test directory
+   - Report results, coverage percentage, and any failures
+4. If no framework is found, report the issue and suggest installing bashunit
+
+## Examples
+
+```bash
+# Run all tests in current directory
+/shell-test-run
+
+# Run tests for specific script
+/shell-test-run tests/process-test.sh
+
+# Run tests in a directory
+/shell-test-run ./tests
+```
+
+## See Also
+
+- **`shell-test`** skill — Test writing patterns, framework setup, and coverage configuration
+- **`/shell-audit`** command — Quality audit for scripts under test
+- **`/shell-new`** command — Scaffold new scripts with test-ready structure

package/opencode.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "lsp": {
+    "bash": {
+      "command": ["bash-language-server", "start"],
+      "extensions": [".sh", ".bash", ".zsh", ".ksh"]
+    }
+  },
+  "permission": {
+    "lsp": "allow",
+    "skill": "allow"
+  },
+  "formatter": {
+    "shfmt": {
+      "command": ["shfmt", "-w", "-i", "2", "$FILE"],
+      "extensions": [".sh", ".bash", ".zsh", ".ksh"]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@objctp/opencode-shell-routines",
+  "version": "1.2.0",
+  "description": "Shell script development toolkit — automated scaffolding, best practices, and quality enforcement for OpenCode and Claude Code",
+  "author": {
+    "name": "objct",
+    "url": "https://objct.link"
+  },
+  "homepage": "https://github.com/objctp/shell-routines",
+  "repository": "https://github.com/objctp/shell-routines",
+  "license": "MIT",
+  "keywords": [
+    "opencode-plugin",
+    "claude-code-plugin",
+    "shell",
+    "bash",
+    "shellcheck",
+    "shfmt",
+    "scaffolding",
+    "static-analysis",
+    "code-quality",
+    "bash-scripting"
+  ],
+  "files": [
+    "agents/",
+    "commands/",
+    "plugins/",
+    "skills/",
+    "scripts/",
+    "opencode.json",
+    "README.md",
+    "LICENSE"
+  ]
+}