slackecho/.github/copilot-instructions.md

AI Coding Agent Instructions for slackecho

Project Overview

slackecho is a minimal bash shell script that sends messages to Slack via incoming webhooks using curl. The project intentionally keeps scope small: message delivery only, no dependencies beyond curl.

Architecture & Key Components

• Single Script: slackecho - standalone bash executable with no external modules
• Integration Method: Slack Incoming Webhooks (posts JSON payload via HTTP POST)
• Minimal Scope: Script handles message delivery; does not manage authentication, logging, or retries

Key Design Decision: This is a "do one thing well" utility meant for shell script integration (e.g., reporting from cron jobs or CI/CD pipelines). Avoid adding features that expand scope beyond message transmission.

Setup & Execution

1. Configuration: Currently hardcoded SLACKURL in the script (TODO: move to external config file)
2. Installation: Copy slackecho to a system binary path (e.g., /usr/local/bin/)
3. Dependency: Requires curl to be installed

Command Signature

slackecho <message> [username] [channel] [icon]

• message (required): Text to send
• username: Slack display name (default: "slackecho-user")
• channel: Target channel (default: "general")
• icon: Emoji icon (default: ":robot_face:")

Patterns & Conventions

• Parameter Handling: Arguments passed positionally; optional parameters checked with empty string tests ([ "$2" = "" ])
• Curl Usage: Single POST request with URL-encoded JSON payload; output suppressed to /dev/null
• Error Handling: Currently minimal—no validation of Slack URL or message content; POST failures silently ignored
• Default Values: All four parameters have sensible defaults defined within script

Common Modifications

When adding features, maintain the philosophy of simplicity:

• Configuration File: TODO item suggests moving hardcoded SLACKURL to external config
• Tests: Currently N/A; any test framework should be lightweight (e.g., BATS for bash)
• Logging: Not currently implemented; if added, should be optional/minimal

Important TODOs

1. Create external configuration file (move SLACKURL and defaults)
2. Add test framework (likely bash-based)
3. Add code review process
4. Document contribution guidelines

References

• Slack Incoming Webhooks: Uses Slack's webhook JSON format with channel, username, text, icon_emoji fields
• Repository Maintainer: gary@hansenit.solutions