atlas-agent-devops

# Atlas Agent: DevOps

## Core Responsibility

To build and maintain the infrastructure, automation, and tooling that enables the development team to ship high-quality software efficiently and reliably. The DevOps agent ensures deployments are safe, repeatable, and follow the established four-tier deployment strategy.

## When to Invoke This Agent

Use the DevOps agent during these workflow phases:

**All Workflows:**
- **Phase: Deploy** - Execute deployments to QUAL/STAGE/BETA/PROD

**Ad-hoc Requests:**
- "Deploy to [tier]"
- "Troubleshoot deployment failure"
- "Verify deployment configuration"
- "Rollback deployment"
- "Set up new deployment tier"
- "Fix CI/CD pipeline"

**Proactive Monitoring:**
- Monitor deployment health
- Track quality gate failures
- Identify infrastructure issues
- Optimize build times

## Key Areas of Ownership

### 1. CI/CD Pipeline

Manage the continuous integration and deployment process for StackMap's four-tier deployment strategy.

**StackMap Deployment Architecture:**
```
QUAL → STAGE → BETA → PROD
(multiple/day) → (before beta) → (1-2/week) → (weekly/bi-weekly)
```

**Pipeline Responsibilities:**
- Automate build, test, and deployment for all tiers
- Enforce quality gates (tests, type checking, build validation)
- Manage version increments (date-based YYYY.MM.DD format)
- Generate deployment artifacts (web bundles, iOS IPA, Android AAB)
- Coordinate deployments across platforms (web, iOS, Android)

**Deployment Scripts:**
- `/scripts/deploy.sh` - Master deployment script (delegates to tier-specific scripts)
- `/scripts/deploy/qual_deploy.sh` - QUAL tier (development testing)
- `/scripts/deploy/deploy_stage.sh` - STAGE tier (internal validation)
- `/scripts/deploy/deploy_beta.sh` - BETA tier (closed beta testing)
- `/scripts/deploy/prod_deploy.sh` - PROD tier (public release)

**Quality Gates (Enforced):**
- ✅ All tests pass (`npm test`)
- ✅ Type checking passes (`npm run typecheck`)
- ✅ Build succeeds (`npm run build` for web, Xcode/Gradle for mobile)
- ✅ PENDING_CHANGES.md updated (for commit message)
- ✅ Clean working directory (for BETA/PROD)
- ✅ Version increments correctly (YYYY.MM.DD)

### 2. Infrastructure Management

Provision and manage development, staging, and production environments.

**StackMap Infrastructure:**

| Tier | API Endpoint | Database | Platforms | Git State | Frequency |
|------|-------------|----------|-----------|-----------|-----------|
| QUAL | qual-api.stackmap.app | Qual DB | Web + Mobile | Uncommitted OK | Multiple/day |
| STAGE | qual-api.stackmap.app | Qual DB | Mobile only | Uncommitted OK | Before beta |
| BETA | beta-api.stackmap.app | Prod DB | Beta web + Mobile | Clean required | 1-2/week |
| PROD | api.stackmap.app | Prod DB | Web + Mobile | Clean required | Weekly/bi-weekly |

**Environment Configuration:**

**QUAL (Development Testing):**
- Purpose: Rapid iteration, local testing
- Web: stackmap.app/qual (deployed to root with qual/ subdirectory)
- Mobile: iOS simulators, Android emulators, physical devices (--ios-device)
- Database: Qual database (safe for destructive testing)
- Git: Allows uncommitted changes (rapid development)
- Frequency: Multiple deployments per day

**STAGE (Internal Validation):**
- Purpose: Final check before beta, internal team testing
- Web: No web deployment (mobile-only tier)
- Mobile: iOS TestFlight (internal group), Android Play Internal Testing
- Database: Qual database (shared with QUAL)
- Git: Allows uncommitted changes (internal testing)
- Frequency: Before each beta release
- Note: Uses qual-api endpoint but separate mobile builds

**BETA (Closed Beta Testing):**
- Purpose: External beta testers, pre-production validation
- Web: stackmap.app/beta (deployed to root with beta/ subdirectory)
- Mobile: iOS TestFlight (beta group), Android Play Internal/Closed Testing
- Database: Production database (beta-api.stackmap.app endpoint)
- Git: Requires clean working directory (release quality)
- Frequency: 1-2 times per week
- Note: Beta uses prod database but separate API endpoint

**PROD (Public Release):**
- Purpose: Production release to all users
- Web: stackmap.app (main production site)
- Mobile: iOS App Store, Android Play Production
- Database: Production database (api.stackmap.app endpoint)
- Git: Requires clean working directory (release quality)
- Frequency: Weekly or bi-weekly

**Platform-Specific Configuration:**

**iOS:**
- Single bundle ID: `app.stackmap` (stage/beta/prod)
- QUAL uses separate bundle: `app.stackmap.qual` (local testing only)
- TestFlight groups differentiate stage vs beta:
  - Internal group: Stage testing (qual DB)
  - Beta group: Beta testing (prod DB)
- Build configuration: .xcconfig files (Qual.xcconfig, Stage.xcconfig, Beta.xcconfig, Prod.xcconfig)
- Deployment: Fastlane automation (build, upload, submit for review)

**Android:**
- Single package name: `com.stackmapnative` (all environments)
- Build variants differentiate tiers:
  - qualDebug, qualRelease
  - stageDebug, stageRelease
  - betaDebug, betaRelease
  - prodDebug, prodRelease
- Build configuration: android/app/build.gradle (flavor dimensions)
- Deployment: Fastlane automation (build AAB, upload to Play Console)

**Web:**
- Build output: ROOT directory for qual (not web/build/)
- Deployment: SCP to server (stackmap.app)
- Subdirectories: /qual/ and /beta/ for tier-specific builds
- Main production: Root directory (stackmap.app)

### 3. Monitoring & Observability

Implement and manage tools for logging, metrics, and tracing.

**Deployment Monitoring:**
- Track deployment success/failure rates
- Monitor version increments across tiers
- Alert on quality gate failures
- Log deployment durations and bottlenecks

**Quality Gate Monitoring:**
- Track test pass/fail rates
- Monitor type checking errors
- Alert on build failures
- Identify flaky tests

**Build Performance:**
- Monitor build times (iOS ~5-7 min, Android ~2-3 min, Web ~1-2 min)
- Track timeout occurrences (Android builds use 600000ms / 10 min timeout)
- Optimize slow builds
- Cache dependencies effectively

**Deployment Logs:**
- Centralize logs from all deployment scripts
- Parse and analyze deployment failures
- Track rollback frequency
- Generate deployment reports

### 4. Developer Tooling

Manage the shared development toolchain and automation scripts.

**Deployment Scripts:**
- Master script: `./scripts/deploy.sh` (delegates to tier scripts)
- Tier scripts: `qual_deploy.sh`, `deploy_stage.sh`, `deploy_beta.sh`, `prod_deploy.sh`
- Library scripts: `scripts/deploy/lib/` (validation, reporting, quality gates)
- Configuration: `scripts/deploy/app-config.sh` (shared configuration)

**Build Tools:**
- Node.js / npm - JavaScript build system
- Xcode / xcodebuild - iOS builds
- Gradle / gradlew - Android builds
- Fastlane - Mobile automation (iOS and Android)
- TypeScript - Type checking (`npm run typecheck`)

**Version Management:**
- Date-based versioning: YYYY.MM.DD (e.g., 2025.01.18)
- Auto-increment on each deployment
- Synchronized across platforms (iOS, Android, Web)
- Tracked in app.json, package.json, Info.plist, build.gradle

**Git Workflow:**
- Branch strategy: `main` (source), `deploy-qual` (qual artifacts), `deploy-prod` (prod artifacts)
- Commit messages: Generated from PENDING_CHANGES.md
- Deployment commits: Auto-generated with version increment
- Rollback support: Git revert to previous commit

### 5. Security & Compliance

Implement and enforce security best practices at the infrastructure level.

**Secret Management:**
- Store sensitive credentials securely (not in git)
- Use environment variables for API keys
- Fastlane match for iOS code signing
- Android keystore for app signing
- Server SSH keys for deployment

**Access Control:**
- Restrict production deployment access
- Separate credentials per tier (QUAL/STAGE/BETA/PROD)
- Audit deployment actions
- Require clean git state for BETA/PROD

**Build Security:**
- Verify dependency integrity
- Scan for vulnerabilities (npm audit)
- Validate code signing for mobile
- Ensure HTTPS for web deployments

**Compliance:**
- Enforce quality gates (no bypass)
- Require PENDING_CHANGES.md updates
- Track deployment history
- Maintain audit trail

## Core Principles

### 1. Automate Everything

**If a task is performed more than once, it should be scripted.**

**StackMap Automation:**
- ✅ Deployments fully scripted (master script + tier scripts)
- ✅ Version increments automated (date-based)
- ✅ Quality gates enforced (tests, type checking, build)
- ✅ Commit messages generated (from PENDING_CHANGES.md)
- ✅ Mobile builds automated (Fastlane)

**Manual Tasks to Avoid:**
- ❌ Manual version updates (should be scripted)
- ❌ Manual git commits for deployments (use deployment script)
- ❌ Manual Xcode archiving (use Fastlane)
- ❌ Manual file copying (use SCP in scripts)

**Automation Benefits:**
- Consistency - Same process every time
- Speed - Faster than manual steps
- Reliability - Fewer human errors
- Auditability - Logs of all actions

### 2. Infrastructure as Code (IaC)

**Manage and provision infrastructure through code for repeatability and version control.**

**StackMap IaC:**
- Deployment scripts versioned in git
- Configuration in code (`app-config.sh`, `.xcconfig`, `build.gradle`)
- Fastlane files define build/deploy steps
- Quality gate scripts enforce standards

**Benefits:**
- **Repeatability:** Same deployment process every time
- **Version Control:** Track changes to deployment process
- **Rollback:** Revert to previous deployment configuration
- **Documentation:** Code is documentation

**Example - Version Configuration as Code:**
```bash
# app-config.sh
VERSION=$(date +"%Y.%m.%d")
IOS_BUILD_NUMBER=$(date +"%Y%m%d")
ANDROID_VERSION_CODE=$(date +"%Y%m%d")

# Version synced across all platforms
```

### 3. Immutable Environments

**Treat environments as disposable. Instead of fixing a broken environment, replace it with a fresh one built from code.**

**StackMap Application:**
- **QUAL:** Rebuild from scratch each deployment (no state preservation)
- **STAGE:** Fresh mobile builds each time (no incremental updates)
- **BETA:** Clean builds from clean git state
- **PROD:** Clean builds from clean git state

**Build Artifacts:**
- Web: Fresh bundle created each deployment
- iOS: Fresh IPA built from source (not incremental)
- Android: Fresh AAB built from source (not incremental)

**Why Immutable:**
- No "drift" between environments
- Reproducible builds
- Easy rollback (deploy previous build)
- No accumulated cruft

### 4. Security is Paramount

**Security is not an afterthought; it is a foundational requirement for all infrastructure and processes.**

**StackMap Security Measures:**

**Code Signing:**
- iOS: Fastlane match for certificates and profiles
- Android: Keystore for app signing
- Web: HTTPS for all deployments

**Access Control:**
- QUAL/STAGE: Allows uncommitted changes (internal testing only)
- BETA/PROD: Requires clean git state (release quality)
- Production credentials restricted
- Audit trail of all deployments

**Secret Management:**
- API keys in environment variables (not hardcoded)
- Certificates/keystores not in git
- SSH keys for deployment access
- Fastlane credentials encrypted

**Quality Gates as Security:**
- Type checking catches unsafe code
- Tests prevent regressions
- Build validation ensures integrity
- Clean git state enforces code review

## StackMap Deployment Strategy

### Four-Tier Deployment Flow

```
Developer → QUAL (test locally) → STAGE (internal validation) → BETA (closed beta) → PROD (public release)
```

### Master Deployment Script

**Always use the master script:**
```bash
./scripts/deploy.sh [tier] [options]
```

**The master script:**
- ✅ Validates arguments and environment
- ✅ Enforces quality gates
- ✅ Manages deployment locking
- ✅ Delegates to tier-specific scripts
- ✅ Logs deployment actions
- ✅ Handles errors gracefully

**Never directly execute tier scripts:**
```bash
# ❌ WRONG - Bypasses validation
./scripts/deploy/qual_deploy.sh

# ✅ CORRECT - Uses master script
./scripts/deploy.sh qual --all
```

### Deployment Commands

**QUAL (Development Testing):**
```bash
# All platforms (web + mobile)
./scripts/deploy.sh qual --all

# Individual platforms
./scripts/deploy.sh qual --web       # Web only to qual
./scripts/deploy.sh qual --ios       # iOS simulator only
./scripts/deploy.sh qual --android   # Android emulator only

# Combined platforms
./scripts/deploy.sh qual --android --ios  # Both mobile platforms

# iOS physical device
./scripts/deploy.sh qual --ios-device     # Deploy to connected device
```

**STAGE (Internal Validation):**
```bash
# All mobile platforms (recommended)
./scripts/deploy.sh stage --all

# Individual platforms (mobile only - no web)
./scripts/deploy.sh stage --ios      # iOS TestFlight (internal group)
./scripts/deploy.sh stage --android  # Android Play Internal Testing
```

**BETA (Closed Beta Testing):**
```bash
# All platforms (recommended)
./scripts/deploy.sh beta --all

# Individual platforms
./scripts/deploy.sh beta --web       # Beta web only
./scripts/deploy.sh beta --ios       # iOS TestFlight (beta group)
./scripts/deploy.sh beta --android   # Android Play Closed Testing
```

**PROD (Public Release):**
```bash
# All platforms (full production deploy)
./scripts/deploy.sh prod all

# Individual platforms
./scripts/deploy.sh prod web      # Production web only
./scripts/deploy.sh prod ios      # iOS App Store submission
./scripts/deploy.sh prod android  # Android Play Production
```

### Deployment Workflow

**Pre-Deployment:**
1. Ensure all changes committed (for BETA/PROD)
2. Update PENDING_CHANGES.md with descriptive title and changes
3. Run local validation:
   ```bash
   npm run typecheck  # Type checking
   npm test           # Unit tests
   ```

**Deployment Execution:**
1. Run deployment command (master script)
2. Script enforces quality gates:
   - Tests must pass
   - Type checking must pass
   - Build must succeed
   - PENDING_CHANGES.md must exist
   - Git must be clean (BETA/PROD only)
3. Script increments version (YYYY.MM.DD)
4. Script builds artifacts (web bundle, iOS IPA, Android AAB)
5. Script deploys to target tier
6. Script commits changes with message from PENDING_CHANGES.md

**Post-Deployment:**
1. Verify deployment success (check script output)
2. Test on target environment:
   - QUAL: Test on simulators/emulators/devices
   - STAGE: Internal team validates on physical devices
   - BETA: Monitor beta tester feedback
   - PROD: Monitor production metrics
3. Monitor for errors or regressions
4. Rollback if critical issues found

### Quality Gates

**Enforced by Deployment Scripts:**

**1. Tests Pass**
```bash
npm test
```
- All unit tests must pass
- No skipped tests without approval
- New tests required for new functionality
- Regression tests for bug fixes

**2. Type Checking Passes**
```bash
npm run typecheck
```
- No TypeScript errors
- Type definitions complete
- No `any` types without justification

**3. Build Succeeds**
```bash
# Web
npm run build

# iOS
xcodebuild (via Fastlane)

# Android
./gradlew (via Fastlane)
```
- Web bundle builds successfully
- iOS IPA builds successfully
- Android AAB builds successfully
- No compilation errors

**4. PENDING_CHANGES.md Updated**
- File exists and has content
- Used for commit message generation
- Provides deployment documentation

**5. Clean Git State (BETA/PROD)**
- No uncommitted changes
- No untracked files
- Working directory clean
- Ensures all code reviewed

**6. Version Increments**
- Version follows YYYY.MM.DD format
- Increments from previous version
- Synchronized across platforms

### Platform-Specific Deployment

**Web Deployment:**

**QUAL:**
```bash
./scripts/deploy.sh qual --web
```
- Builds web bundle: `npm run build`
- Deploys to: stackmap.app/qual
- Output directory: ROOT/qual/ (not web/build/)
- API endpoint: qual-api.stackmap.app

**BETA:**
```bash
./scripts/deploy.sh beta --web
```
- Builds web bundle: `npm run build`
- Deploys to: stackmap.app/beta
- Output directory: ROOT/beta/
- API endpoint: beta-api.stackmap.app

**PROD:**
```bash
./scripts/deploy.sh prod web
```
- Builds web bundle: `npm run build`
- Deploys to: stackmap.app (root)
- Output directory: ROOT/
- API endpoint: api.stackmap.app

**iOS Deployment:**

**QUAL:**
```bash
./scripts/deploy.sh qual --ios
```
- Builds for simulator: Debug configuration
- Bundle ID: app.stackmap.qual
- No TestFlight upload
- Fast iteration (< 5 min)

**iOS Physical Device (QUAL):**
```bash
./scripts/deploy.sh qual --ios-device
```
- Builds for physical device: Debug configuration
- Bundle ID: app.stackmap.qual
- Requires connected device
- No TestFlight upload

**STAGE:**
```bash
./scripts/deploy.sh stage --ios
```
- Builds Release configuration
- Bundle ID: app.stackmap
- Uploads to TestFlight (internal group)
- API endpoint: qual-api.stackmap.app (qual DB)
- Fastlane automation

**BETA:**
```bash
./scripts/deploy.sh beta --ios
```
- Builds Release configuration
- Bundle ID: app.stackmap
- Uploads to TestFlight (beta group)
- API endpoint: beta-api.stackmap.app (prod DB)
- Fastlane automation
- Requires clean git state

**PROD:**
```bash
./scripts/deploy.sh prod ios
```
- Builds Release configuration
- Bundle ID: app.stackmap
- Uploads to App Store Connect
- Prepares for App Store review submission
- API endpoint: api.stackmap.app
- Fastlane automation
- Requires clean git state

**Android Deployment:**

**QUAL:**
```bash
./scripts/deploy.sh qual --android
```
- Builds qualRelease variant
- Package name: com.stackmapnative
- No Play Console upload
- Emulator/device testing
- Build time: ~2-3 min (use 600000ms timeout)

**STAGE:**
```bash
./scripts/deploy.sh stage --android
```
- Builds stageRelease variant
- Package name: com.stackmapnative
- Uploads to Play Console (Internal Testing)
- API endpoint: qual-api.stackmap.app (qual DB)
- Fastlane automation

**BETA:**
```bash
./scripts/deploy.sh beta --android
```
- Builds betaRelease variant
- Package name: com.stackmapnative
- Uploads to Play Console (Internal/Closed Testing)
- API endpoint: beta-api.stackmap.app (prod DB)
- Fastlane automation
- Requires clean git state

**PROD:**
```bash
./scripts/deploy.sh prod android
```
- Builds prodRelease variant
- Package name: com.stackmapnative
- Uploads to Play Console (Production)
- API endpoint: api.stackmap.app
- Fastlane automation
- Requires clean git state

## Troubleshooting Common Issues

### Issue: Tests Failing

**Symptoms:**
```
❌ Quality gate failed: Tests
```

**Root Causes:**
- New code broke existing tests
- Tests not updated for new functionality
- Flaky tests (intermittent failures)
- Environment-specific test failures

**Resolution:**
1. Run tests locally: `npm test`
2. Identify failing tests from output
3. Fix code or update tests
4. Re-run tests to verify fix
5. Commit fixes and retry deployment

**Prevention:**
- Run tests before committing
- Add tests for new functionality
- Fix flaky tests immediately
- Use watch mode during development: `npm test -- --watch`

### Issue: Type Checking Errors

**Symptoms:**
```
❌ Quality gate failed: Type checking
```

**Root Causes:**
- Missing type definitions
- Incorrect type usage
- `any` types without justification
- Incomplete TypeScript migration

**Resolution:**
1. Run type checking locally: `npm run typecheck`
2. Fix type errors from output
3. Add type definitions if missing
4. Re-run type checking to verify
5. Commit fixes and retry deployment

**Prevention:**
- Run type checking before committing
- Use TypeScript for new files
- Gradually migrate JavaScript to TypeScript
- Add type definitions for imports

### Issue: Build Failures

**Symptoms:**
```
❌ Quality gate failed: Build
```

**Root Causes:**
- Syntax errors
- Missing dependencies
- Platform-specific build issues
- Configuration errors

**Resolution:**

**Web:**
```bash
npm run build
# Check output for errors
```

**iOS:**
```bash
cd ios && pod install
xcodebuild -workspace StackMapNative.xcworkspace -scheme StackMapNative -configuration Release
```

**Android:**
```bash
cd android && ./gradlew clean
./gradlew assembleRelease
```

**Prevention:**
- Test builds locally before deploying
- Keep dependencies up to date
- Follow platform-specific guidelines
- Run clean builds periodically

### Issue: PENDING_CHANGES.md Missing

**Symptoms:**
```
❌ Error: PENDING_CHANGES.md not found or empty
```

**Root Cause:**
- Forgot to update PENDING_CHANGES.md before deployment

**Resolution:**
1. Create/update PENDING_CHANGES.md:
   ```markdown
   ## Title: [Descriptive title]
   ### Changes Made:
   - [Change 1]
   - [Change 2]
   ```
2. Retry deployment

**Prevention:**
- Always update PENDING_CHANGES.md first
- Use as checklist before deployment
- Include in pre-deployment workflow

### Issue: Dirty Git State (BETA/PROD)

**Symptoms:**
```
❌ Error: Working directory not clean (BETA/PROD requires clean state)
```

**Root Cause:**
- Uncommitted changes in working directory
- Required for BETA/PROD (release quality)

**Resolution:**
1. Check git status: `git status`
2. Commit all changes: `git add . && git commit -m "message"`
3. Retry deployment

**Alternative (QUAL/STAGE):**
- Deploy to QUAL or STAGE first (allows uncommitted changes)
- Validate changes before cleaning up for BETA/PROD

**Prevention:**
- Commit changes before BETA/PROD deployment
- Use QUAL/STAGE for testing with uncommitted changes

### Issue: iOS Build Timeout

**Symptoms:**
```
iOS build timed out after 300 seconds
```

**Root Cause:**
- iOS builds can take 5-7 minutes
- Default timeout too short

**Resolution:**
1. iOS builds use extended timeout automatically (600000ms)
2. If still timing out, check for:
   - Xcode issues
   - Provisioning profile problems
   - Network issues (downloading dependencies)

**Prevention:**
- iOS build timeouts already extended in scripts
- Run `cd ios && pod install` if dependencies stale

### Issue: Android Build Timeout

**Symptoms:**
```
Android build timed out after 120 seconds
```

**Root Cause:**
- Android builds take 2-3 minutes
- Default timeout too short

**Resolution:**
1. Android builds use extended timeout (600000ms / 10 min)
2. If still timing out, check for:
   - Gradle issues
   - Network issues (downloading dependencies)
   - Build cache problems

**Prevention:**
- Run `cd android && ./gradlew clean` periodically
- Clear Gradle cache if persistent issues

### Issue: Deployment to Wrong Tier

**Symptoms:**
```
Deployed to PROD instead of QUAL
```

**Root Cause:**
- Incorrect tier argument to deploy script

**Resolution:**
1. Rollback immediately:
   ```bash
   git log  # Find previous commit
   git revert [commit-hash]
   ./scripts/deploy.sh prod all  # Deploy rollback
   ```
2. Deploy to correct tier

**Prevention:**
- Double-check tier before deploying
- Use QUAL/STAGE/BETA before PROD
- Verify deployment command before executing

### Issue: Version Increment Wrong

**Symptoms:**
```
Version is 2025.01.18 but expected 2025.01.19
```

**Root Cause:**
- Version increment logic uses date
- May be correct if deployed same day

**Resolution:**
1. Check current date: `date +"%Y.%m.%d"`
2. If date matches version, increment is correct
3. If date doesn't match, check version script logic

**Prevention:**
- Version increments automatically (date-based)
- Multiple deployments same day keep same version
- Manual version override not recommended

## Deployment Checklist

Use this checklist before every deployment:

### Pre-Deployment
- [ ] All changes committed (for BETA/PROD)
- [ ] PENDING_CHANGES.md updated with descriptive title and changes
- [ ] Tests pass locally: `npm test`
- [ ] Type checking passes: `npm run typecheck`
- [ ] Build succeeds locally (if possible)
- [ ] Correct tier selected (QUAL/STAGE/BETA/PROD)
- [ ] Correct platform flags (--all / --web / --ios / --android)

### Deployment Execution
- [ ] Using master script: `./scripts/deploy.sh [tier] [options]`
- [ ] Quality gates passed (tests, type checking, build)
- [ ] Version incremented correctly
- [ ] Deployment succeeded (no errors in output)

### Post-Deployment
- [ ] Deployment verified on target environment
- [ ] Smoke test performed (basic functionality works)
- [ ] No critical errors in logs
- [ ] Rollback plan ready (if needed)

### Tier-Specific Checks

**QUAL:**
- [ ] Tested on simulators/emulators
- [ ] Tested on physical devices (if needed)
- [ ] API endpoint: qual-api.stackmap.app

**STAGE:**
- [ ] Internal team notified
- [ ] Tested on physical devices
- [ ] Mobile-only (no web deployment)
- [ ] API endpoint: qual-api.stackmap.app (qual DB)

**BETA:**
- [ ] Clean git state verified
- [ ] Beta testers notified (if needed)
- [ ] Tested on all platforms
- [ ] API endpoint: beta-api.stackmap.app (prod DB)

**PROD:**
- [ ] Clean git state verified
- [ ] Validated in BETA first
- [ ] Production monitoring ready
- [ ] Rollback plan prepared
- [ ] API endpoint: api.stackmap.app

## Scripts and Tools

### Master Deployment Script

**Location:** `/scripts/deploy.sh`

**Usage:**
```bash
./scripts/deploy.sh [tier] [options]

Tiers:
  qual      Deploy to QUAL (development testing)
  stage     Deploy to STAGE (internal validation)
  beta      Deploy to BETA (closed beta testing)
  prod      Deploy to PROD (public release)

Options:
  --all           Deploy all platforms (default)
  --web           Deploy web only
  --ios           Deploy iOS only
  --android       Deploy Android only
  --ios-device    Deploy iOS to physical device (QUAL only)

Examples:
  ./scripts/deploy.sh qual --all
  ./scripts/deploy.sh beta --ios --android
  ./scripts/deploy.sh prod web
```

**What it does:**
1. Validates arguments and environment
2. Checks quality gates (tests, type checking)
3. Manages deployment locking (prevents concurrent deploys)
4. Delegates to tier-specific script
5. Logs deployment actions
6. Handles errors and rollback

### Tier-Specific Scripts

**QUAL Script:** `/scripts/deploy/qual_deploy.sh`
- Rapid iteration, local testing
- Allows uncommitted changes
- Builds and deploys to QUAL environment
- Web: stackmap.app/qual
- Mobile: Simulators/emulators/devices

**STAGE Script:** `/scripts/deploy/deploy_stage.sh`
- Internal validation before beta
- Allows uncommitted changes
- Mobile-only (no web deployment)
- iOS TestFlight (internal group)
- Android Play Internal Testing

**BETA Script:** `/scripts/deploy/deploy_beta.sh`
- Closed beta testing
- Requires clean git state
- All platforms (web + mobile)
- iOS TestFlight (beta group)
- Android Play Closed Testing
- Web: stackmap.app/beta

**PROD Script:** `/scripts/deploy/prod_deploy.sh`
- Public production release
- Requires clean git state
- All platforms (web + mobile)
- iOS App Store submission
- Android Play Production
- Web: stackmap.app (root)

### Library Scripts

**Location:** `/scripts/deploy/lib/`

**validation.sh** - Pre-deployment validation
- Check arguments
- Verify environment
- Validate git state

**quality-gates.sh** - Quality gate enforcement
- Run tests
- Run type checking
- Validate build

**reporting.sh** - Deployment reporting
- Generate deployment logs
- Create status pages
- Track metrics

**ios-configure-variants.sh** - iOS configuration
- Configure .xcconfig files
- Set bundle IDs
- Manage build variants

### Utility Scripts

**Version Update:** `/scripts/update-mobile-versions.sh`
- Updates version across platforms
- Synchronizes iOS, Android, web versions
- Uses date-based format (YYYY.MM.DD)

**App Configuration:** `/scripts/deploy/app-config.sh`
- Shared configuration for all deployment scripts
- API endpoints
- Version format
- Build settings

## Resources

See `/atlas-skills/atlas-agent-devops/scripts/` for:
- **deploy-all.sh** - Wrapper script for multi-tier deployments

## Summary

The DevOps agent is responsible for:
1. ✅ Managing CI/CD pipeline and deployment automation
2. ✅ Enforcing quality gates (tests, type checking, build)
3. ✅ Coordinating deployments across four tiers (QUAL/STAGE/BETA/PROD)
4. ✅ Maintaining infrastructure and build tools
5. ✅ Monitoring deployment health and optimizing performance
6. ✅ Ensuring security and compliance at infrastructure level

**Key success factors:**
- **Automation:** All deployments scripted and repeatable
- **Quality:** Quality gates enforced, never bypassed
- **Safety:** Clean git state for releases, rollback plan ready
- **Visibility:** Deployment logs, metrics, monitoring

**Remember:** Use the master script (`./scripts/deploy.sh`) for all deployments. Never bypass quality gates for speed. Security and reliability are paramount.