Platform-Aware Verification Commands

Problem Solved: Task generator creates iOS task. Embeds npm test. iOS developer cannot run it. Feature appears unverified.

Solution: A multi-platform verification command system that automatically selects appropriate commands based on the project’s target platform.

Quick Start

1. Ensure Registry Has Platform Configuration

Check specs/_defaults/registry.yaml for these keys:

target_platform:
  primary: mobile          # web | mobile | desktop | both
  mobile_platforms: ios    # ios | android | both
  mobile_framework: native # native | react-native | flutter

backend:
  language: typescript     # For backend-only projects

2. Task Generator Detects Platform

During /atomicspec.tasks, Section 4.2.4 automatically:

1. Reads platform from registry
2. Falls back to file pattern scanning if no registry
3. Selects appropriate verification templates

3. Generated Tasks Include Correct Commands

iOS Task gets:

xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15' \
  -only-testing:MyAppTests/AuthServiceTests | xcpretty

NOT:

npm test -- --grep "AuthService"  # WRONG!

Files Created

Platform Support Matrix

Fallback Strategy

Every verification command should include fallbacks:

## Verification Command

**Primary** (full test):
```bash
xcodebuild test -scheme MyApp -only-testing:MyAppTests/AuthServiceTests | xcpretty
```

**Fallback** (compile check):
```bash
xcodebuild build -scheme MyApp | xcpretty
```

**Expected Output**: Test Succeeded or Build Succeeded

See Verification fallback logic for complete fallback chains per platform.

Platform Detection Logic

Priority 1: Registry Values

# From specs/_defaults/registry.yaml
target_platform.primary: mobile
target_platform.mobile_platforms: ios
target_platform.mobile_framework: native

Priority 2: File Pattern Scanning

Priority 3: User Prompt

If platform is ambiguous, ask via AskUserQuestion.

Using verification-commands.yaml

Structure

[platform]:
  [verification_type]:
    primary:
      tool: "tool_name"
      command: "command with {{PLACEHOLDERS}}"
      expected_output: "success text"
    alternatives:
      - tool: "alt_tool"
        command: "..."
    fallback:
      command: "minimal check"

Available Placeholders

Example: Generating iOS Unit Test Command

# From verification-commands.yaml
ios:
  unit_tests:
    primary:
      tool: "xcodebuild"
      command: |
        xcodebuild test \
          -scheme {{SCHEME}} \
          -destination 'platform=iOS Simulator,name=iPhone 15' \
          -only-testing:{{MODULE}}Tests/{{TEST_NAME}} \
          | xcpretty
      expected_output: "Test Succeeded"

Replace placeholders:

• {{SCHEME}} -> MyApp
• {{MODULE}} -> MyApp
• {{TEST_NAME}} -> AuthServiceTests

Result:

xcodebuild test \
  -scheme MyApp \
  -destination 'platform=iOS Simulator,name=iPhone 15' \
  -only-testing:MyAppTests/AuthServiceTests \
  | xcpretty

CI/CD Considerations

GitHub Actions (macOS runner for iOS)

jobs:
  test-ios:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run iOS Tests
        run: |
          xcodebuild test \
            -scheme MyApp \
            -destination 'platform=iOS Simulator,name=iPhone 15' \
            | xcpretty

GitHub Actions (Linux runner - iOS unavailable)

When iOS tools are unavailable, fallback commands should verify what is possible:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint Swift (using swiftlint Docker)
        run: |
          docker run --rm -v $(pwd):/work ghcr.io/realm/swiftlint:latest

Hybrid Projects

For projects with both web and mobile:

1. Set registry correctly:

   target_platform:
     primary: both
     mobile_platforms: ios
   backend:
     language: typescript

2. Tasks get platform-appropriate verification:

   • Backend API task -> npm test, curl
   • iOS service task -> xcodebuild test, swiftlint
   • Shared model task -> Both (if code shared)

Troubleshooting

”xcodebuild: command not found”

Cause: Running on non-macOS machine Solution: Use Swift test fallback or skip iOS tests in non-macOS CI

”./gradlew: Permission denied”

Cause: Missing execute permission Solution: Run chmod +x gradlew or use gradle directly

”flutter: command not found”

Cause: Flutter not in PATH Solution: Add Flutter to PATH or use full path to flutter binary

Tests pass locally but fail in CI

Cause: CI environment differs (simulators, tools, permissions) Solution: Ensure CI has required tools, use fallback commands for CI

Example: Complete iOS Auth Task

See templates/examples/T-025-implement-auth-service-ios.md for a complete example showing:

• Platform-specific embedded context
• Correct verification commands for iOS
• Primary, alternative, and fallback commands
• Expected output for each command
• Lint verification with fallback

Summary

1. Configure registry with target_platform.* values
2. Task generator reads platform and selects appropriate templates
3. verification-commands.yaml provides platform-specific command templates
4. Fallback logic ensures verification works even when tools unavailable
5. Generated tasks include primary + fallback verification commands

Result: iOS tasks have xcodebuild commands, Android tasks have ./gradlew commands, web tasks have npm commands. No more platform mismatches.