Home Assistant GSM SMS Development

This skill provides development guidelines for the ha-legacy-gsm-sms repository, which contains multiple Home Assistant addon variants for legacy GSM SMS notifications via GSM modem.

Repository Structure

The repository contains multiple addon variants with intentional differences:

Critical Development Rules

1. NEVER Copy Entire Files Between Addons

When syncing features or fixes between addon variants, you MUST make surgical, line-by-line edits to preserve custom settings. Never copy entire files from one addon to another.

2. Test Addon Custom Settings (addon-test-current/)

The test addon has intentional differences that MUST be preserved:

**config.yaml:**

**support.py:**

3. Before Editing Any Config File

Always follow this process:

1. Read the file first using `read_file` or `git show HEAD:path`

2. Identify what needs to change - only those specific lines

3. Make surgical edits - change only what's necessary

4. Verify with diff - check that only intended changes were made

4. Tuned Values - Do NOT Change

These values have been specifically tuned for this project:

5. Syncing Features Between Addons

When adding a new feature to both production and test addons:

1. Implement in production addon first (`addon-gsm-gateway/`)

2. For Python files (`mqtt_publisher.py`, `run.py`): These CAN be synced (except `support.py`)

3. For `config.yaml`: Make individual line edits - never copy the whole file

4. Always verify test addon customizations are preserved after changes

6. Version Bumping

Both should be bumped together when features are added.

7. Feature Implementation Checklist

When adding a new SMS feature, it MUST be implemented in ALL these places:

Do not mark the task as complete until all four are done.

8. Phone Number Validation

Phone numbers can contain: `+`, digits, spaces, `-`, `(`, `)`, `,`

The `+` character can appear anywhere (not just at the start) because multiple international numbers are comma-separated: `+1234567890,+0987654321`

**Correct regex:** `^[\+\d\s\-\(\),]*$`

**Wrong regex:** `^\+?[\d\s\-\(\),]*$` (only allows + at start)

9. Validation Before Completion

Before marking a task as complete:

1. Run Python syntax check on all modified `.py` files

2. Test the logic with edge cases (multiple values, empty values, special characters)

3. Verify with `git diff` that only intended changes were made

4. Check that both production AND test addons are updated (if applicable)

5. Confirm documentation matches the implementation

10. When in Doubt, Ask

If unsure whether a file has custom settings or special handling:

Upstream Reference

This project is based on [PavelVe/hassio-addons](https://github.com/PavelVe/hassio-addons). When syncing upstream features, always credit the source in CHANGELOG.md.

Example Workflow

When implementing a new feature:

1. Read the current state of all files that need modification

2. Implement in production addon first

3. Make surgical edits to test addon, preserving custom settings

4. Update all four required locations (MQTT, REST API, README, CHANGELOG)

5. Run validation checks (syntax, diff, edge cases)

6. Bump versions appropriately

7. Verify both addons work correctly