ota-updates

name	ota-updates
description	Configure over-the-air mobile updates — Shorebird for Flutter, CodePush or EAS Update for React Native — with update channels, staged rollout, forced vs optional update policies, rollback procedures, crash-rate monitoring, and CI integration
version	2.0.0
category	deploy
platforms	["CLAUDE_CODE"]

You are in AUTONOMOUS MODE. Do NOT ask questions. Do NOT pause for confirmation. Execute every phase below in sequence, making decisions based on what you find.

============================================================ PHASE 0 — INPUT

$ARGUMENTS may contain:

• A specific OTA platform: shorebird, codepush, eas-update
• A specific focus: rollback, channels, ci-integration, update-policy
• If no arguments, configure the complete OTA infrastructure for the detected framework

============================================================ PHASE 1 — FRAMEWORK DETECTION

1. Detect the mobile framework:

   • pubspec.yaml with flutter SDK -> Flutter (use Shorebird)
   • package.json with react-native -> React Native (use CodePush or EAS Update)
   • package.json with expo -> Expo (use EAS Update)
   • *.xcodeproj (native iOS) -> Custom OTA or no-code-push strategy
   • build.gradle.kts (native Android) -> Play In-App Updates API

2. Determine OTA eligibility:

   • OTA CAN update: JavaScript bundles (RN), Dart code (Flutter/Shorebird), assets, configuration
   • OTA CANNOT update: native code, new permissions, native module changes, new SDK integrations
   • Document what changes require a full store release vs OTA

============================================================ PHASE 2 — FLUTTER / SHOREBIRD SETUP

If Flutter is detected, configure Shorebird:

Initialization:

• Install Shorebird CLI
• Run shorebird init in project
• Generate shorebird.yaml with app ID and flavor-based channel definitions

Channel configuration:

• development: dev app ID
• staging: staging app ID
• production: production app ID

Release workflow:

• shorebird release android/ios --flavor production — creates a new store release baseline
• shorebird patch android/ios --flavor production — pushes OTA patch to existing release

CI integration (.github/workflows/ota-patch.yml):

• workflow_dispatch with platform and flavor inputs
• Uses shorebirdtech/setup-shorebird@v1 with SHOREBIRD_TOKEN secret
• Runs on macos-14 for iOS, ubuntu-latest for Android

============================================================ PHASE 3 — REACT NATIVE / CODEPUSH / EAS UPDATE

If React Native is detected, configure the appropriate OTA solution:

Expo (EAS Update):

• Configure eas.json with update channels per environment (development, staging, production)
• Push updates: eas update --channel staging --message "description"
• Channel promotion flow: staging -> production

Bare React Native (CodePush):

• Install react-native-code-push SDK
• Configure update check behavior:
  • checkFrequency: ON_APP_RESUME
  • installMode: ON_NEXT_RESUME (non-mandatory)
  • mandatoryInstallMode: IMMEDIATE (mandatory/critical)
  • minimumBackgroundDuration: 60 seconds

============================================================ PHASE 4 — NATIVE APPS

For native iOS/Android apps without OTA framework support:

Android — Play In-App Updates:

• Flexible update (downloads in background, non-blocking)
• Immediate update (blocks app usage until installed)
• Check updateAvailability() and isUpdateTypeAllowed() before prompting

iOS — App Store Version Check:

• Query iTunes lookup API for latest version
• Compare with current bundle version
• Prompt user to update if newer version exists

Custom OTA for config/assets:

• Firebase Remote Config for feature flags and configuration
• Asset bundles downloaded on demand
• No code changes via OTA (would violate store guidelines)

============================================================ PHASE 5 — UPDATE CHANNELS & ENVIRONMENTS

Configure update channels matching deployment environments:

Channel	Target	Update Mode	Rollout
development	Dev builds	Immediate	100%
staging	QA/staging	Immediate	100%
production-canary	5% of production	On next resume	5%
production	All production	On next resume	100%

Channel promotion flow:

1. Push patch to staging channel
2. QA verifies on staging builds
3. Promote to production-canary (5% rollout)
4. Monitor crash-free rate for 24 hours
5. If stable (crash-free > 99%), promote to production (100%)

============================================================ PHASE 6 — UPDATE POLICIES

Implement update policy logic with three severity tiers:

Critical (forced) — blocks app until installed:

• Security vulnerability fix
• Data corruption fix
• Authentication bypass fix
• API breaking change requiring client update

Important (strongly recommended) — persistent banner, dismissible once per session:

• Major bug fix
• Performance improvement
• New required feature

Optional (informational) — dismissible dialog, not shown again for this version:

• Minor improvement
• New optional feature
• UI polish

Generate a version compatibility config:

{
  "minSupportedVersion": "2.1.0",
  "latestVersion": "2.3.0",
  "forceUpdateBelow": "2.0.0"
}

============================================================ PHASE 7 — ROLLBACK STRATEGY

Document rollback procedures for each platform:

Shorebird: shorebird patch rollback android/ios --release-version 1.0.0

EAS Update: eas update:republish --group <previous-update-group-id> --channel production

CodePush: appcenter codepush rollback -a owner/AppName-Platform Production

Automated rollback trigger:

• Monitor crash-free rate after OTA push
• If crash-free rate drops below 98%, automatically rollback
• Send alert to team channel (Slack, PagerDuty)

============================================================ PHASE 8 — A/B UPDATE TESTING

Configure A/B testing for OTA updates:

1. Create two update variants targeting different user segments
2. Use rollout percentage to split traffic
3. Monitor metrics per variant: crash-free rate, session duration, feature adoption, retention
4. Promote the winning variant to 100%

============================================================ SELF-HEALING VALIDATION (max 2 iterations)

After completing deployment/infrastructure changes, validate:

1. Verify all generated files are syntactically valid (YAML, JSON, HCL, Dockerfile).
2. Run validation commands if available (terraform validate, docker build --check, kubectl dry-run).
3. Verify no secrets, credentials, or sensitive values are hardcoded.
4. If validation fails, diagnose and fix the specific syntax or config error.
5. Repeat up to 2 iterations.

IF STILL FAILING after 2 iterations:

• Document what failed and the exact error
• Include partial output if available

============================================================ OUTPUT

## OTA Update Infrastructure Complete

### Framework: {Flutter / React Native / Expo / Native}
### OTA Platform: {Shorebird / EAS Update / CodePush / Custom}

### Update Channels
| Channel | Target | Mode | Rollout |
|---------|--------|------|---------|
| {channel} | {audience} | {immediate/resume} | {%} |

### Update Policy
| Severity | Behavior | User Experience |
|----------|----------|-----------------|
| Critical | Force update | Blocks app until updated |
| Important | Recommend | Persistent banner |
| Optional | Inform | Dismissible dialog |

### Rollback Procedure
{step-by-step rollback for the configured platform}

### CI Integration
{workflow files created for automated OTA patches}

### Files Created
{list all generated files with paths}

============================================================ NEXT STEPS

1. Push your first OTA patch to the staging channel to verify the setup
2. Run deploy/mobile-ci-cd to integrate OTA patches into the CI/CD pipeline
3. Set up crash monitoring (Sentry, Crashlytics) to enable automated rollback triggers
4. Test the rollback procedure before relying on it in production

============================================================ SELF-EVOLUTION TELEMETRY

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /ota-updates — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.

============================================================ DO NOT

• Do NOT push OTA updates that include native code changes — these require store review
• Do NOT skip staging channel testing before production push
• Do NOT set all updates to force-update — this creates a poor user experience
• Do NOT deploy without a tested rollback procedure
• Do NOT push to production without monitoring crash-free rate
• Do NOT bypass store guidelines by delivering app functionality via remote config that would normally require review
• Do NOT store OTA tokens or API keys in source code