Twilio to Telnyx Migration

Path convention: {baseDir} in this document is the directory containing this SKILL.md file (e.g., /path/to/skills/telnyx-twilio-migration). Substitute the absolute path before running any script shown below — do not pass the literal string {baseDir} to bash.

You MUST follow these phases in order (0 → 1 → 2 → 3 → 4 → 5 → 6). Do NOT skip phases. Each phase has prerequisites and exit criteria — do not proceed until the exit criteria are met. You MUST run the scripts specified in each phase (do not substitute your own checks). You MUST modify the user's source files to complete the migration.

Interaction model: Phase 0 collects confirmation that TELNYX_API_KEY is set securely, the destinations required by the products in scope, an ISO-2 country for each destination (or explicit opt-in to a billed lookup), and an approved maximum spend based on a current price check. A live WebRTC-to-PSTN call requires its own opt-in. Never ask the user to paste an API key into chat. Phases 1–6 run autonomously except for one scoped Phase-1 decision if discovery finds unsupported products, a new or increased paid-action approval, and a failure that persists after 3 fix attempts.

Context recovery: If you lose context (e.g. after compaction), IMMEDIATELY run bash {baseDir}/scripts/migration-state.sh status <project-root> and bash {baseDir}/scripts/migration-state.sh show <project-root> to recover your current phase and all resource IDs. Then resume from that phase.

Migration State Tracking

Track progress in migration-state.json via bash {baseDir}/scripts/migration-state.sh <command> <project-root> [args]. Commands: init, set-phase <N>, set <key> <value>, add-product <product>, add-file <product> <file>, set-commit <phase>, status, show. This preserves resource IDs across phases and enables resume after interruption. For a complete product mapping, see {baseDir}/references/product-mapping.md.

Universal Changes (All Migrations)