From e3c8f5a9e3648cdc9ef19643deb4d67de77edfd3 Mon Sep 17 00:00:00 2001
From: Steve Nims <sjnims@gmail.com>
Date: Sat, 13 Dec 2025 09:19:00 -0500
Subject: [PATCH] docs: add shellcheck guidance to CONTRIBUTING.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add "Shell Script Quality" section documenting:
- How to run shellcheck on plugin scripts
- How to handle intentional patterns with disable directives
- Common issues table (SC2086, SC2046, SC2034, SC2155)

This provides guidance for contributors on shell script standards.

Fixes #155

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CONTRIBUTING.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 43c50d8..94e0cec 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -167,6 +167,38 @@ Current branch: [BANG]`git branch --show-current`
 - Command files (`.claude/commands/*.md`) use actual `!` syntax
 - See [SECURITY.md](SECURITY.md#shell-pattern-escaping-with-bang-placeholder) for full details
 
+### Shell Script Quality
+
+All shell scripts should pass [shellcheck](https://www.shellcheck.net/) validation:
+
+```bash
+# Check all plugin scripts
+shellcheck plugins/plugin-dev/skills/*/scripts/*.sh
+
+# Check a specific script
+shellcheck plugins/plugin-dev/skills/hook-development/scripts/test-hook.sh
+```
+
+#### Handling Intentional Patterns
+
+If a pattern intentionally triggers a shellcheck warning, add a directive comment:
+
+```bash
+# shellcheck disable=SC2086  # Word splitting intended for arguments
+command $unquoted_var
+```
+
+Always include a comment explaining why the directive is needed.
+
+#### Common Issues
+
+| Warning | Typical Fix |
+|---------|-------------|
+| SC2086 | Quote variables: `"$var"` |
+| SC2046 | Quote command substitution: `"$(cmd)"` |
+| SC2034 | Remove unused variables or export them |
+| SC2155 | Separate declaration and assignment: `local var; var=$(cmd)` |
+
 ## Component-Specific Guidelines
 
 ### Commands (`/plugin-dev:*`)