Home Assistant Legacy GSM SMS Development

Development skill for maintaining the ha-legacy-gsm-sms Home Assistant addon repository. This addon provides legacy GSM SMS notifications via GSM-modem using HACS or HA Add-on options.

Repository Structure

The repository contains multiple addon variants with **intentional differences**:

Critical Development Rules

Rule 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.

**Steps for syncing features:**

1. Read both source and target files first

2. Identify the specific lines that need to change

3. Make surgical edits only to those lines

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

Rule 2: Preserve Test Addon Custom Settings

The test addon (`addon-test-current/`) has intentional differences that MUST be preserved:

**config.yaml customizations:**

**support.py customizations:**

Rule 3: Pre-Edit Verification Process

Before editing ANY config file:

1. **Read the file first** using appropriate tools

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

Rule 4: Do NOT Change Tuned Values

These values have been specifically tuned for this project and differ from upstream:

Do NOT modify these values without explicit user approval.

Rule 5: Feature Syncing Workflow

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

Rule 6: Version Management

Version format:

Both versions should be bumped together when features are added.

Rule 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 components are updated.**

Rule 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)

Rule 9: Pre-Completion Validation

Before marking any task as complete, perform these checks:

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

Rule 10: When in Doubt

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

Upstream Attribution

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.

Usage Examples

**Adding a new feature:**

1. Implement in `addon-gsm-gateway/mqtt_publisher.py`

2. Add corresponding REST endpoint in `addon-gsm-gateway/run.py`

3. Document in `addon-gsm-gateway/README.md`

4. Log changes in `addon-gsm-gateway/CHANGELOG.md`

5. Surgically sync Python changes to `addon-test-current/` (preserving support.py)

6. Update `addon-test-current/config.yaml` version (with `-test` suffix)

7. Verify test addon customizations remain intact

8. Run validation checklist before completion

**Syncing a bug fix:**

1. Fix in production addon

2. Read test addon file before editing

3. Apply only the specific fix lines to test addon

4. Verify with `git diff` that custom settings weren't overwritten

Important Constraints