Home Assistant GSM SMS Addon Development

Expert development skill for the ha-legacy-gsm-sms project, which provides legacy GSM SMS notifications via GSM modem for Home Assistant using HACS or HA Add-on options.

Critical Development Rules

Rule 1: NEVER Copy Entire Files Between Addon Variants

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

**ALWAYS** make surgical, line-by-line edits when syncing features or fixes. **NEVER** copy entire files from one addon to another.

Rule 2: Preserve Test Addon Custom Settings (`addon-test-current/`)

The test addon has these **intentional differences** that must be preserved:

#### `config.yaml`

#### `support.py`

Rule 3: Config File Editing Protocol

Before editing any config file:

1. **Read the file first** using available 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 tuned for this project and differ from upstream:

**Never modify these without explicit user approval.**

Rule 5: Feature Sync Protocol

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 Bumping Standards

Both 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 complete until all four are implemented.**

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

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

Usage Examples

Example 1: Adding a New SMS Feature

```

User: "Add support for SMS delivery reports"

Assistant workflow:

1. Implement MQTT command handling in addon-gsm-gateway/mqtt_publisher.py

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

3. Sync Python changes to addon-test-current/ (surgical edits only)

4. Update README.md with new feature documentation

5. Add entry to CHANGELOG.md

6. Bump version in both addons (e.g., 2.15.0 and 2.15.0-test)

7. Run syntax validation on all .py files

8. Verify with git diff before completion

```

Example 2: Syncing a Bug Fix

```

User: "Fix phone number validation in production addon"

Assistant workflow:

1. Fix regex in addon-gsm-gateway/mqtt_publisher.py

2. Make identical surgical edit in addon-test-current/mqtt_publisher.py

3. Verify test addon config.yaml still has TEST settings intact

4. Update CHANGELOG.md

5. Bump patch version (e.g., 2.14.1 and 2.14.1-test)

6. Validate with git diff

```

Constraints