From 26a15aa3bcfd9ac76557fbbf4d7b27e66e08728a Mon Sep 17 00:00:00 2001 From: Gary Date: Sat, 10 Jan 2026 22:54:52 +1100 Subject: [PATCH] add AI Coding Agent instructions for slackecho --- .github/copilot-instructions.md | 48 +++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..71a9393 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,48 @@ +# 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 +```bash +slackecho [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