If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/wordpress-mobile/WordPress-iOS shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 2d ago
• 9 active contributors
• Distributed ownership (top contributor 29% of recent commits)
• GPL-2.0 licensed
• CI configured
• ⚠ GPL-2.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live wordpress-mobile/WordPress-iOS repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/wordpress-mobile/WordPress-iOS.

What it runs against: a local clone of wordpress-mobile/WordPress-iOS — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in wordpress-mobile/WordPress-iOS | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch trunk exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of wordpress-mobile/WordPress-iOS. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/wordpress-mobile/WordPress-iOS.git
#   cd WordPress-iOS
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of wordpress-mobile/WordPress-iOS and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "wordpress-mobile/WordPress-iOS(\\.git)?\\b" \\
  && ok "origin remote is wordpress-mobile/WordPress-iOS" \\
  || miss "origin remote is not wordpress-mobile/WordPress-iOS (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-2.0" \\
  || miss "license drift — was GPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify trunk >/dev/null 2>&1 \\
  && ok "default branch trunk exists" \\
  || miss "default branch trunk no longer exists"

# 4. Critical files exist
test -f ".buildkite/pipeline.yml" \\
  && ok ".buildkite/pipeline.yml" \\
  || miss "missing critical file: .buildkite/pipeline.yml"
test -f ".configure" \\
  && ok ".configure" \\
  || miss "missing critical file: .configure"
test -f ".buildkite/commands/shared-set-up.sh" \\
  && ok ".buildkite/commands/shared-set-up.sh" \\
  || miss "missing critical file: .buildkite/commands/shared-set-up.sh"
test -f ".github/workflows/claude-review.yml" \\
  && ok ".github/workflows/claude-review.yml" \\
  || miss "missing critical file: .github/workflows/claude-review.yml"
test -f ".xcode-version" \\
  && ok ".xcode-version" \\
  || miss "missing critical file: .xcode-version"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/wordpress-mobile/WordPress-iOS"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

WordPress for iOS is the official native iOS application that lets users manage WordPress.com and self-hosted WordPress sites directly from iPhone/iPad. Built in Swift and Objective-C, it provides a full-featured mobile experience for publishing posts, managing media, responding to comments, and monitoring site analytics with OAuth 2.0 authentication against WordPress.com and Jetpack-enabled sites. Monolithic Xcode workspace (WordPress.xcworkspace) with main app target and separate test targets. Code organized by feature (likely under WordPress/Classes/) with build configuration in .buildkite/ orchestrating Fastlane-based release pipelines; encrypted credentials in .configure-files/ decrypted during CI; multiple schemes for WordPress/Jetpack/Alpha variants controlled via .xcode-version and Rakefile.

WordPress site owners and content creators who need to manage their blogs on iOS; mobile developers contributing to Automattic's flagship iOS app; QA engineers running integration tests against WordPress.com infrastructure.

Production-ready and actively maintained. The codebase is 18+ MB of Swift with sophisticated CI/CD pipelines (Buildkite release orchestration, code freeze workflows, UI/unit test suites), encrypted secret management, and release automation for both WordPress and Jetpack branded variants. This is a 10+ year old, heavily audited shipping app with millions of users.

Low risk for active Automattic employees, moderate risk for external contributors due to: encrypted configuration files (.configure-files/*) requiring decryption, tight coupling to WordPress.com APIs and OAuth credentials, multi-variant build complexity (WordPress + Jetpack schemes), and release process requiring maintainer access. Dependency management handled via Cocoapods and Swift Package Manager, but no visible lock file in top structure.

Active release pipeline development and CI optimization: automated code freeze workflows (.buildkite/release-pipelines/code-freeze.yml), Claude-integrated code analysis (.buildkite/commands/comment-claude-analysis.sh, .claude/ skill configs), prototype and release builds for both WordPress and Jetpack apps with staged UI/unit test execution.

1. Verify Xcode version matches .xcode-version via xcode-select --version
2. Clone: git clone https://github.com/wordpress-mobile/WordPress-iOS.git && cd WordPress-iOS
3. Install Ruby version from .ruby-version: rbenv install && rbenv rehash
4. Run rake dependencies to fetch CocoaPods, Swift packages, and configure tools
5. Run rake init:oss to set up WordPress.com OAuth credentials (requires app created at https://developer.wordpress.com/apps/)
6. Run rake xcode to open WordPress.xcworkspace with all dependencies ready
7. Select WordPress or Jetpack scheme and build to simulator/device

Daily commands: Open in Xcode: rake xcode (preferred, ensures deps are fresh), or directly open WordPress.xcworkspace. Select iPhone simulator target and scheme (WordPress, Jetpack, or Alpha), then Cmd+R to build and run. Or from CLI: xcodebuild -workspace WordPress.xcworkspace -scheme WordPress -configuration Debug -destination 'generic/platform=iOS Simulator'

• .buildkite/pipeline.yml — Main CI/CD pipeline configuration; essential for understanding how builds, tests, and releases are orchestrated
• .configure — Build configuration script that sets up dependencies and environment; must be run before building the app
• .buildkite/commands/shared-set-up.sh — Shared setup script for all CI jobs; defines common environment initialization across all build pipelines
• .github/workflows/claude-review.yml — Automated code review workflow; indicates the repository uses Claude AI for analysis in the CI process
• .xcode-version — Specifies minimum Xcode version requirement; critical for build compatibility across the development team
• .ruby-version — Defines Ruby version requirement for build tools and dependencies; essential for consistent build environment
• .buildkite/release-builds.yml — Release build pipeline configuration; governs how production builds are created and distributed

Add a new CI/CD job or test stage

1. Define the job in the main pipeline file with proper dependencies and conditions (.buildkite/pipeline.yml)
2. Create the corresponding shell script in .buildkite/commands/ directory (.buildkite/commands/run-unit-tests.sh)
3. Add setup steps if needed; most jobs should source shared-set-up.sh or shared-set-up-distribution.sh (.buildkite/commands/shared-set-up.sh)

Add a new release pipeline or deployment flow

1. Create new YAML file in .buildkite/release-pipelines/ directory following existing naming convention (.buildkite/release-pipelines/new-beta-release.yml)
2. Reference the pipeline from release-builds.yml or add to shared-pipeline-vars for environment setup (.buildkite/release-builds.yml)
3. Create associated shell commands in .buildkite/commands/ (e.g., release-build-wordpress.sh, finalize-release.sh) (.buildkite/commands/release-build-wordpress.sh)

Add a new API mock endpoint for integration tests

1. Create JSON mapping file in API-Mocks/WordPressMocks/src/main/assets/mocks/mappings/ under appropriate API category (wpcom, self-hosted, etc.) (API-Mocks/WordPressMocks/src/main/assets/mocks/mappings/wpcom/auth/oauth2_token.json)
2. Follow WireMock format with request matchers and response templates; organize in subdirectories by endpoint category (API-Mocks/WordPressMocks/src/main/assets/mocks/mappings/self-hosted/wp-json-users-me.json)
3. Update API-Mocks/README.md with documentation of new endpoint and usage example (API-Mocks/README.md)

Configure development environment for new contributor

1. Verify Xcode version matches .xcode-version file requirement (.xcode-version)
2. Verify Ruby version matches .ruby-version for consistent build tool behavior (.ruby-version)
3. Run .configure script which executes 'rake dependencies' to install all required CocoaPods and build dependencies (.configure)
4. Create WordPress.com OAuth credentials following README instructions and store in encrypted Secrets files via .configure process (.configure-files/Secrets.swift.enc)

• Buildkite CI/CD — Enables scalable, self-hosted CI pipelines with powerful parallelization and environment control for iOS builds
• Xcode & Swift — Native iOS development environment required for building WordPress-iOS app targeting iPhone and iPad
• Fastlane — Automates complex iOS release workflows including code signing, TestFlight upload, and App Store deployment
• WireMock (API Mocks) — Provides deterministic API responses for integration testing without external API dependencies or network requests
• SwiftLint & Swift Format — Enforces consistent Swift style and best practices across the codebase for maintainability and team alignment
• Ruby & Rake — Scripting language for build automation and dependency management; familiar to iOS dev community

• Self-hosted Buildkite CI instead of GitHub Actions for all jobs

  • Why: Allows greater control over build environment, faster builds with persistent runners, and custom tooling; avoids GitHub rate limits
  • Consequence: Requires infrastructure maintenance overhead and higher operational cost compared to managed GitHub Actions

• Encrypted

  • Why: undefined
  • Consequence: undefined

1. Encrypted secrets: .configure-files/*.enc files require decryption keys stored in CI/CD environment; running rake init:oss locally needs you to create real WordPress.com OAuth app credentials, not use stubs
2. Ruby version pinning: .ruby-version file is strict (likely 2.7.x or 3.x); mismatch breaks Bundler and Fastlane — use rbenv or asdf to auto-switch
3. CocoaPods + SPM mix: both package managers used; pod repo update and swift package resolve must both succeed or build fails
4. OAuth redirect URL: must be exactly https://localhost or local login fails — WordPress.com app config is strict
5. Multi-scheme complexity: WordPress, Jetpack, and Alpha schemes have different bundle IDs, entitlements, and provisioning profiles — selecting wrong scheme causes signing failures
6. Xcode version: must match .xcode-version or linker/availability errors occur; no automatic downgrade
7. UI test flakiness: .buildkite/commands/run-ui-tests.sh may fail on overloaded CI agents; uses WebDriverAgent which is notoriously fragile

• OAuth 2.0 Authorization Code Flow — The entire authentication system in this app depends on OAuth 2.0 against WordPress.com; you must understand the redirect URI dance, refresh tokens, and why Client Secret is encrypted in .configure-files/
• REST API versioning and backwards compatibility — iOS app must handle multiple WordPress.com and self-hosted API versions simultaneously; understanding API versioning (wp/v2 routes, deprecated endpoints) is critical for avoiding breaking changes
• CocoaPods dependency resolution and pod spec versioning — All Objective-C and some Swift dependencies come through CocoaPods; understanding Podfile syntax, pod repo conflicts, and version pinning is essential for unblocking build failures
• Swift Package Manager (SPM) local and remote dependencies — Modern Swift dependencies use SPM; the workspace likely uses both CocoaPods and SPM, requiring understanding of how resolution order and version constraints interact
• Xcode build schemes and configurations — WordPress/Jetpack/Alpha schemes have different bundle IDs, feature flags, and signing identities; misunderstanding build schemes causes signing failures and missed features
• Fastlane app distribution automation — Release process is fully automated via Fastlane (evident from .buildkite/commands/release-build-*.sh and .buildkite/release-pipelines/); you need to understand match (code signing), cert/sigh, and pilot (TestFlight) to debug release issues
• Encrypted secrets management in CI/CD (.configure-files/*.enc) — Credentials are stored encrypted and decrypted only during CI; understanding how .configure-files/ encryption works is crucial for rotating credentials and debugging local setup failures
• WebDriverAgent for iOS UI testing — UI tests use WebDriverAgent (evident from .claude/skills/ios-sim-navigation/scripts/wda-*.rb); understanding WDA lifecycle, simulator state, and flakiness patterns is essential for fixing CI test hangs

• wordpress-mobile/WordPress-Android — Parallel official Android app sharing similar architecture (OAuth, multi-site support, same REST APIs) — reference for cross-platform patterns
• wordpress-mobile/WordPress-FlutterFlow — Automattic's experimental Flutter-based WordPress app; shows alternative mobile strategy and shared API integration patterns
• Automattic/jetpack — Server-side Jetpack plugin that iOS app connects to for analytics, publishing, and security features — understanding Jetpack APIs is essential for full feature set
• wordpress-mobile/WordPress-iOS-SharedUI — Shared UI component library used across WordPress mobile apps; likely imported as CocoaPod/SPM dependency
• wordpress/openapi-for-wordpress — WordPress REST API specification that iOS app consumes; critical reference for understanding endpoint contracts and versioning

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Claude AI Analysis Integration Tests in .buildkite/claude-analysis.yml

The repo has Claude analysis infrastructure (.buildkite/claude-analysis.yml, .buildkite/commands/comment-claude-analysis.sh, .buildkite/commands/upload-claude-analysis.sh) but lacks corresponding unit/integration tests to validate the analysis pipeline works correctly. New contributors could add tests to ensure Claude analysis comments are properly formatted, uploaded, and don't break the build on malformed responses.

• [ ] Create new test file: Tests/Unit/BuildKite/ClaudeAnalysisTests.swift
• [ ] Test parsing and validation of .buildkite/claude-analysis.yml pipeline configuration
• [ ] Add tests for .buildkite/commands/comment-claude-analysis.sh error handling (missing API keys, network failures)
• [ ] Add integration test ensuring upload-claude-analysis.sh properly handles various response formats
• [ ] Document expected behavior in README or CONTRIBUTING.md

Add UI Tests for iOS Simulator Navigation via WDA (Web Driver Agent)

The repo contains iOS simulator navigation skills (.claude/skills/ios-sim-navigation/scripts/wda-start.rb, wda-stop.rb) but there are no specific end-to-end UI test examples demonstrating how to use WDA for app navigation testing. A new contributor could add sample UI tests that exercise the WDA navigation helpers, serving as documentation and validation.

• [ ] Create new test file: Tests/UITests/SimulatorNavigationTests.swift
• [ ] Add test cases that use WDA scripts from .claude/skills/ios-sim-navigation/scripts/ for common navigation flows
• [ ] Document WDA setup/teardown in .claude/skills/ios-sim-navigation/SKILL.md with runnable examples
• [ ] Add sample assertions for verifying app state after WDA-driven navigation
• [ ] Ensure tests work with .buildkite/commands/run-ui-tests.sh pipeline

Implement Scheme-Switching Validation Tests for Xcode Build System

The repo has a scheme-switching skill (.claude/skills/switching-xcode-scheme/) with a state management script (xcode-state.sh) but lacks validation that scheme switching doesn't corrupt project state or break dependent builds. New contributors could add tests to verify the scheme-switching logic works for all build targets (WordPress, Jetpack variants) referenced in .buildkite/release-builds.yml.

• [ ] Create test file: Tests/Unit/XcodeBuild/SchemeStateValidationTests.swift
• [ ] Parse .buildkite/release-builds.yml and .buildkite/release-pipelines/ to extract all valid schemes (WordPress, Jetpack, variants)
• [ ] Test xcode-state.sh script validation: verify it correctly identifies current active scheme without side effects
• [ ] Add tests validating scheme transitions don't conflict with .xctool-args or .xcode-version requirements
• [ ] Document in .claude/skills/switching-xcode-scheme/SKILL.md with test results showing state consistency

• Add missing unit tests for API error handling in WordPress/Classes/Services/ — several REST client classes lack tests for 401/403/5xx responses, which would improve reliability during WordPress.com outages
• Improve localization lint coverage: .buildkite/commands/lint-localized-strings-format.sh only validates format, not completeness — add a check that all supported languages have matching key counts to .buildkite/pipeline.yml
• Document the OAuth credential setup process in a dedicated CONTRIBUTING.md — currently scattered across README and rake init:oss implementation, confusing for first-time contributors unfamiliar with WordPress.com OAuth

• Critical · Encrypted Secrets Files Present in Repository — .configure-files/*.swift.enc, .configure-files/app_store_connect_fastlane_api_key.json.enc, .configure-files/google_cloud_keys.json.enc, .configure-files/project.env.enc. Multiple encrypted secrets files are committed to the repository (.configure-files directory contains .enc files including app credentials, API keys, and sensitive configuration). While encrypted, the presence of these files in version control creates risk if encryption keys are compromised or if decryption logic is exposed. Fix: 1) Use a secure secrets management system (e.g., AWS Secrets Manager, GitHub Secrets, HashiCorp Vault) instead of storing encrypted secrets in the repo. 2) Move secrets to environment variables or CI/CD platform secret storage. 3) Implement pre-commit hooks to prevent accidental secret commits. 4) Consider rotating all exposed credentials.
• High · Hardcoded OAuth Credentials in Build Configuration — .configure, .configure-files/Secrets*.swift.enc, README.md. The README and build process reference WordPress.com API credentials (Client ID and Client Secret) that appear to be used in the build configuration. The .configure script likely decrypts and uses these secrets, creating exposure if the decryption key or process is compromised. Fix: 1) Never commit Client IDs or Client Secrets to the repository. 2) Use CI/CD system environment variables or secure secret management. 3) Implement API credential rotation policies. 4) Use OAuth refresh tokens instead of long-lived secrets where possible. 5) Audit who has access to the .configure script and decryption keys.
• High · Sensitive Build Scripts with Potential Credential Exposure — .buildkite/commands/shared-set-up-distribution.sh, .buildkite/commands/shared-set-up.sh, .buildkite/commands/release-build-*.sh. Build scripts in .buildkite/commands (shared-set-up-distribution.sh, shared-set-up.sh, release-build-*.sh) likely handle sensitive operations including key management, app signing, and credential usage. If these scripts log output or have debugging enabled, credentials could be exposed in build logs. Fix: 1) Audit all build scripts to ensure credentials are never logged or printed. 2) Use set +x to disable debug logging in sections handling secrets. 3) Ensure Buildkite is configured to mask secret values in logs. 4) Review CI/CD log retention policies. 5) Use temporary credentials with short TTLs instead of long-lived secrets.
• High · Insecure API Mock Configuration — API-Mocks/WordPressMocks/src/main/assets/mocks/mappings/. API-Mocks directory contains mock mapping files for testing. These mock configurations (.json files in mappings/) could expose API endpoint structures, authentication patterns, or other implementation details if they contain real-world sensitive data examples. Fix: 1) Ensure all mock data uses sanitized/fake credentials and data. 2) Never include real API keys, tokens, or PII in mock files. 3) Review all __files and mappings for sensitive information. 4) Implement code review requirements for changes to mock data. 5) Document what data is appropriate for test mocks.
• Medium · Potential Information Disclosure Through Version Files — .xcode-version, .ruby-version, .xctool-args. .xcode-version and .ruby-version files are committed to the repository, which could help attackers identify specific tool versions and potentially known vulnerabilities in those versions. Fix: 1) While version pinning is good practice, review if tool versions need to be public. 2) Maintain a security advisory process for vulnerable tool versions. 3) Keep tools updated regularly. 4) Consider using tool version management that doesn't expose versions in the repo (if acceptable for your workflow).
• Medium · Dependency Management Without Visible Lock Files — Rakefile, .bundle/config, rake dependencies command. The repository uses Rake (Rakefile in API-Mocks and implied rake dependencies command) and Ruby gems, but no Gemfile.lock or equivalent lock file is visible in the provided structure. This could lead to inconsistent dependencies across builds. Fix: 1) Ensure Gemfile.lock is committed to enforce consistent dependency versions. 2) Implement dependency scanning tools (Dependabot already visible - ensure it's properly configured). 3) Review all

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.