# 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 <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