HA Legacy GSM SMS Development Rules

Critical development guidelines for the ha-legacy-gsm-sms Home Assistant addon repository. This skill ensures proper handling of multiple addon variants, preserves custom test configurations, and enforces complete feature implementation across all required files.

Repository Structure

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

Critical Rule: 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. Copying entire files will overwrite intentional configuration differences.

Surgical Editing Workflow

1. **Read the target file first** using file reading tools 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

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

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

config.yaml Customizations

support.py Customizations

Contains custom debug logging with `🔍 DEBUG:` prefixes. Do NOT overwrite with production version.

Tuned Values - Do NOT Change

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

Feature Implementation Checklist

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

**Don't mark a task as complete until all four are updated.**

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

Version Bumping

Both should be bumped together when features are added.

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)

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

When in Doubt

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: Surgical Edit vs File Copy

**❌ WRONG - Copying entire file:**

```bash

cp addon-gsm-gateway/config.yaml addon-test-current/config.yaml

```

**✅ CORRECT - Surgical edit:**

```bash

Read both files, identify the specific change needed

Edit only the relevant lines in addon-test-current/config.yaml

Preserve test-specific settings (name prefix, version suffix, slug, image comment)

```

Constraints