---
description: "Pre-submission store readiness for a built package, iOS and Android, local-only. Three symmetric gates per platform: a static package audit, the store's own authoritative validation, and a policy review against repo source. Separate verdict per gate, a skipped gate never counted as a pass. Validates only, never ships a build. Use when a build is about to go to TestFlight or a Play track, or when a submission was rejected and the reason is not obvious."
description-tr: "Üretilmiş paketin yükleme öncesi store hazırlığı, iOS + Android, yalnızca lokal. Platform başına üç simetrik kapı: statik paket denetimi, store'un kendi doğrulayıcısı, ve kaynağa karşı politika incelemesi. Kapı başına ayrı verdict, atlanan kapı asla pass sayılmaz. Sadece doğrular, build'i asla yayına göndermez."
argument-hint: "[repo]  -  empty = pick; repo name or path; --ipa= | --archive= | --aab= | --apk=; --skip-sweep; --resume"
parameters: [{"name":"repo","kind":"text"},{"name":"--ipa","kind":"path"},{"name":"--archive","kind":"path"},{"name":"--aab","kind":"path"},{"name":"--apk","kind":"path"},{"name":"--skip-sweep","kind":"flag"},{"name":"--resume","kind":"flag"}]
gui: form
destructive: false
confirm: none
allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, AskUserQuestion, Skill, mcp__multi-agent-toolkit__ios_app_store_audit, mcp__multi-agent-toolkit__ios_export_ipa, mcp__multi-agent-toolkit__ios_testflight_validate, mcp__multi-agent-toolkit__ios_xcodebuild, mcp__multi-agent-toolkit__ios_xcresult, mcp__multi-agent-toolkit__android_apk_audit, mcp__multi-agent-toolkit__store_status, mcp__multi-agent-toolkit__store_asc_apps, mcp__multi-agent-toolkit__store_asc_next_build_number, mcp__multi-agent-toolkit__store_play_validate_bundle, mcp__multi-agent-toolkit__ios_screenshot, mcp__multi-agent-toolkit__ios_get_ui_tree, mcp__multi-agent-toolkit__ios_set_appearance, mcp__multi-agent-toolkit__ios_set_content_size, mcp__multi-agent-toolkit__android_screenshot, mcp__multi-agent-toolkit__android_get_ui_tree, mcp__multi-agent-toolkit__android_set_dark_mode, mcp__multi-agent-toolkit__android_set_font_scale
---

# /multi-agent:store-ready  -  pre-submission validation, iOS + Android

Catch, before you upload, what App Store Connect or the Play Console would send
back after you do.

**Local-only.** No commits, no push, no PR, no channels unless you ask at the end.
A worktree, when needed, only archives without touching your working tree.

**It never ships.** iOS runs `--validate-app`, never `--upload-app`. Android
never commits a Play edit: when Google Play is onboarded, Gate 2 uploads the
bundle into a throwaway edit that is validated and deleted, and only after the
user approves that plan. A validation run must not be able to ship a build by
accident.

**Input**: $ARGUMENTS

## Gotchas

- A skipped gate is reported as skipped with its reason, never folded into a pass: a green static audit says nothing about what the store's validator will say.
- The Play throwaway edit is deleted whether validation passes or fails.
- Gate 3 reads source, not the binary: a policy finding cites `file:line` in the repo the package was built from.

## Why three gates, and why the same three on both platforms

Each gate sees what the others cannot, so no single one is "the check". The
failure modes are the same on both platforms: a malformed package, a package the
store refuses, a policy a human enforces.

| Gate | Sees | Blind to |
|---|---|---|
| **1. Static** | package structure, manifests, signing, declared APIs and SDKs | anything depending on the store account |
| **2. Authoritative** | what the store's own validator says about this exact binary | written policy  -  no validator reads it |
| **3. Policy** | consent flows, deletion paths, purchase routing, disclosures | anything not visible in source |

### Gate matrix

| Gate | iOS | Android |
|---|---|---|
| 1 Static | `ios_app_store_audit({archive_path, rules: "all"})`  -  18 rules with real ITMS codes. Needs an `.xcarchive`. Reference: `apple-archive-compliance` skill | `android_apk_audit` plus the `google-play-compliance` skill's 21 rules: `bundletool validate` + manifest dump, `aapt2 dump badging`, `apksigner verify`, ABI / native scan. Needs an `.aab` (an `.apk` narrows it, see Step 3) |
| 2 Authoritative | `ios_testflight_validate({ipa_path, platform: "ios", <credentials>})` → `xcrun altool --validate-app`, plus `store_asc_next_build_number` for whether the build number is already used. Needs an `.ipa` + credentials | With `google_play` onboarded: `store_play_validate_bundle({package_name, bundle_path})`  -  Google validates the `.aab` in a throwaway Publishing API edit that is then deleted, never committed. Without it, Play's check exists only server-side and nothing local reproduces it, so this gate reports `SKIPPED (no local Play validator)` with the reason `Google Play not onboarded`. Do not substitute `bundletool validate`  -  that is Gate 1 |
| 3 Policy | `ai-ios-toolkit:app-store-review` skill vs repo source | `ai-android-toolkit:play-store-review` skill vs repo source |

Gate 2's asymmetry is reported, not smoothed over. On iOS it is the only gate that
catches a version+build pair already used. On Android it runs only with Google Play
onboarded and the throwaway-edit upload approved; without both, an Android run
clears at most 2 of 3 gates and never prints `passed`.

The `store_*` tools need `@mmerterden/multi-agent-toolkit-mcp` ≥ v3.17.0. On an
older server they are absent, and each branch below that uses one falls back to
the behaviour it has without the credential.

## Step 0  -  parse input, detect platform

| Input | Meaning |
|---|---|
| (empty) | ask which repo (Step 1) |
| `my-app` or a path | that repo |
| `--archive=<path>` | iOS, build supplied; all three gates can run |
| `--ipa=<path>` | iOS, build supplied; Gate 1 reports `SKIPPED (needs .xcarchive)` |
| `--aab=<path>` | Android, build supplied; Gate 1 + 3 run |
| `--apk=<path>` | Android; Gate 1 runs the subset that does not need a bundle, and says which rules it could not apply |
| `--skip-sweep` | skip Step A, when no simulator / emulator is available or only the package matters |
| `--resume` | continue the last run from its state file |

Platform detection when no build flag is given:

```
cwd or repo contains .xcodeproj / .xcworkspace / Package.swift   -> iOS
cwd or repo contains build.gradle / build.gradle.kts             -> Android
both                                                            -> ask which
neither -> halt: "store-ready needs an iOS or Android project"
```

State lives at `$HOME/.claude/logs/multi-agent/<task_id>/agent-state.json` with
`taskId = SR-<repo>-<yyyymmddHHMM>`. Register phases with the tracker
(`$HOME/.claude/multi-agent-refs/tracker-contract.md`) so `:resume` and `:status`
work like any other run.

## Step 1  -  pickers (native, always)

Use `AskUserQuestion` for every step  -  never a numbered text menu. Questions and
descriptions render in `prefs.global.outputLanguage`; `label` and `header` stay
English, per `$HOME/.claude/multi-agent-refs/picker-contract.md`. Print the
`Step <i>/<n>: <what this decides>` breadcrumb for each.

1. **Repo**  -  from `prefs.projects` matching the detected platform. A single match
   auto-resolves (say so in the breadcrumb, do not silently skip the step).
2. **Branch**  -  the branch to validate. Run `git fetch --prune` first, capturing
   **stderr**. **If the fetch fails, do not silently fall back to a cached ref**, and
   **classify before naming a cause** (credential / network / wrong remote), printing
   the observed stderr line next to the classification. A credential failure never
   gets the cached-ref fallback. Then offer the current branch, the default branch,
   and any `release/*` / `tkdevelop/*` heads.
   Full procedure: `$HOME/.claude/multi-agent-refs/store-ready/preflight.md`. Read it for the fetch-failure table.
3. **Mode**  -  how the build is obtained:
   - `Supply a build` (Mode B, default)  -  fastest, no signing needed in-run.
   - `Build from this branch` (Mode A)  -  iOS needs a distribution certificate and
     profile in the keychain; Android needs the release signing config. Takes as
     long as a real release build.

## Step 2  -  pre-flight, before anything expensive

Report every line; a missing prerequisite is a halt, not a warning.

**iOS**: `altool` and `xcodebuild` must resolve. Then resolve credentials and
**state which tier is active in the report**: tier 1 ASC API key (`store_status`
reports `appStoreConnect.configured`), tier 2 Apple ID + app-specific password,
tier 3 neither, where **Gate 2 reports `SKIPPED`, and the run says so in the verdict
line**. Multi-provider accounts need `--provider-public-id`; ask when it is not in prefs.

**Android**: `bundletool`, `aapt2` and `apksigner` must resolve.

Full procedure: `$HOME/.claude/multi-agent-refs/store-ready/preflight.md`. Read it for Step 2 (commands, tier table, provider lookup).

Then resolve whether Android Gate 2 can run. Call `store_status` (no probe) and read
`googlePlay.configured`:

| State | Gate 2 |
|---|---|
| `googlePlay.configured: true` and `MULTI_AGENT_UNATTENDED` unset | runs `store_play_validate_bundle`, after the user approves the upload (Step 5) |
| `googlePlay.configured: true` and `MULTI_AGENT_UNATTENDED=1` | `SKIPPED (no local Play validator)`, reason: the toolkit refuses the upload in an unattended run |
| not configured, or no `store_status` tool | `SKIPPED (no local Play validator)`, reason: `Google Play not onboarded` (`/multi-agent:setup` Step 3d) |

Say which one it is.

Credentials come from `/multi-agent:setup`; never prompt for a secret value in
chat.

## Step A  -  running-app sweep (unless `--skip-sweep`)

The gates read a package; this reads the app. A build can be structurally perfect
and still ship an unreadable screen, so the sweep stays part of store readiness
rather than being a separate errand.

Requires a booted simulator / emulator. When none is available, report
`Sweep: SKIPPED (no booted device)` and continue to the gates  -  never halt the
package validation for it, and never silently omit the line.

Delegate to the UI Bug Hunter flow (`$HOME/.claude/commands/sim-test.md`) for the
mechanics, running the light + dark + large-text passes over every screen. Merge
its findings into the single report at Step 7, severity-grouped alongside the gate
findings.

## Step 3  -  obtain the build

Mode B (supply a build) and Mode A (build from the branch). Full procedure:
`$HOME/.claude/multi-agent-refs/store-ready/build.md`. Read it for Step 3. Rules that hold either way:

- **iOS `.ipa` only** → **Gate 1 is `SKIPPED (needs .xcarchive)`**; never present a
  two-gate run as a full pass. An Android `.apk` **lists the rules it could not apply**.
- Never validate an artifact whose provenance you did not state; print which one you picked.
- Mode A worktree at `{projectRoot}/.worktrees/{taskId}`, **never under `$HOME`**, never
  a direct checkout of the main working tree.
- iOS archives with `destination: "generic/platform=iOS"`. Android with no release
  signing config halts; never audit a debug artifact.
- Leave `allow_provisioning_updates` off unless the user asks.
- A failed build or export halts with the parsed errors.

## Step 4  -  Gate 1, static package audit

- **iOS**: `ios_app_store_audit({archive_path, rules: "all"})`, per the
  `apple-archive-compliance` skill. The direct-package fallback runs only when the
  tool is genuinely absent, and the report says which path ran. An archive with no
  dSYM (`<archive>/dSYMs/*.dSYM` count zero) is a blocking `[SYMBOLS]` finding.
- **Android**: `android_apk_audit` plus the `google-play-compliance` skill's 21 rules.
  A `minifyEnabled true` module whose build produced no `mapping.txt` is a blocking
  `[SYMBOLS]` finding.

Full procedure: `$HOME/.claude/multi-agent-refs/store-ready/gate-1-static.md`. Read it for Gate 1.

`error` findings are blocking; `warning` is advisory. Group by severity and keep
each finding's ITMS / Play policy code  -  Gate 2 may return the same code on iOS,
and seeing it in both places tells the user it is real rather than a heuristic.

## Step 5  -  Gate 2, the store's own validation

**iOS**: `ios_testflight_validate({ipa_path, platform: "ios", <credential args>})`.
Render the verdict exactly as returned:

- `PASS`  -  Apple accepted the binary for delivery.
- `FAIL`  -  list each issue with its ITMS code, the mapped guideline, and the hint.
- `SKIPPED`  -  print the reason. **Never render this as a pass.**

Gate 2 is the only gate that catches a build number already used  -  so when it
fails on that, say so plainly and name the next free build number.

**Build number** (App Store Connect onboarded, `store_status` reports
`appStoreConnect.configured`): find the app with `store_asc_apps` by the archive's
bundle id, then `store_asc_next_build_number({app_id, version: <CFBundleShortVersionString>})`.
Report the archive's `CFBundleVersion` as `already used` (not above the highest
uploaded one, with the suggested next) or `free`. Read-only; it never changes the
project. Without the credential, skip this line and say why.

**Android**, by the state resolved in Step 2:

- **Google Play onboarded, attended run.** Call
  `store_play_validate_bundle({package_name: <applicationId>, bundle_path: <.aab>})`
  without `confirm`. It returns the plan only: it would open an edit, upload the
  bundle, validate the edit, then delete it, committing nothing and changing no
  track. Show that plan to the user and ask (picker, `question` / `description` in
  `outputLanguage`, `header` `Play check`, labels `Validate on Play` / `Skip`).
  Only on **Validate on Play**, call it again with `confirm: true`. Render the
  verdict from `valid`: `true` → `PASS`, `false` → `FAIL` with the returned
  `error`. On **Skip**, report `SKIPPED (no local Play validator)` with the reason
  `user declined the upload`.
- **Otherwise** (unattended, or not onboarded) do not call the tool: report
  `SKIPPED (no local Play validator)` with the reason from the Step 2 table.

`bundletool validate` is Gate 1 in every case; reporting it here would fake a
cleared gate.

Google does not document whether an upload into a discarded edit reserves its
`versionCode`; fastlane's `validate_only` runs the same sequence as a pre-release
check. If the real upload is later refused as "already used", raise `versionCode`.

## Step 6  -  Gate 3, policy review

Load the platform's review skill and review the repo against it. This is the gate
that catches what a human reviewer rejects, so it reads source, not the binary.

**iOS**  -  `ai-ios-toolkit:app-store-review`; **Android**  -  `ai-android-toolkit:play-store-review`.
Both cover a `Crash symbolication` row (dSYM upload step / `mapping.txt` upload).
Full procedure: `$HOME/.claude/multi-agent-refs/store-ready/gate-3-policy.md`. Read it for Gate 3 (the per-platform area tables).

For each: `pass` / `fail` / `not-applicable` with the evidence path that justifies
it. `not-applicable` needs a reason  -  an unexamined area is not a pass.

## Step 7  -  report

Write to `~/StoreChecks/<platform>-<repo>-<branch>-<timestamp>/report.md` and print
a summary: verdict line, per-gate status, Blocking / Advisory / Not run / Open
questions, and the `Before rollout` block (phased rollout, `Halt thresholds`,
rollback / forward-fix owner, forward-fix plan).
Full procedure: `$HOME/.claude/multi-agent-refs/store-ready/report.md`. Read it for Step 7 (the report layout).

Rules for the report:

- A skipped gate is never folded into the pass count. The verdict line states the
  skip. An Android run whose Gate 2 did not run therefore reads
  `2 of 3 gates cleared, 1 skipped` at best.
- Every blocking finding carries a file path or a store code. A finding the user
  cannot act on is noise.
- The `Before rollout` block is filled by a human, never inferred. When it is
  left unfilled the verdict line gains the suffix `, rollout plan missing`.
- Humanize via `--lang en` by default (`promptLanguage` is locked to `"en"`); pass
  `--lang=tr` explicitly to opt into Turkish.
- No AI or assistant attribution anywhere, per
  `$HOME/.claude/rules/git-conventions.md`.
- Real newlines, no HTML entities, per
  `$HOME/.claude/multi-agent-refs/rules.md "External System Outputs"`.

## Step 8  -  offer the next action, do not take it

Print, and stop:

- the exact upload command for when the gates are clear, so uploading stays an
  explicit human act:
  - iOS: `xcrun altool --upload-app ...`
  - Android: the Play Console upload, or the `gradle publish` task the project
    declares  -  never run it
- `/multi-agent:store-ready --resume` to re-run after fixes
- `/multi-agent:channels` to land the findings in Jira / Confluence / Wiki / PR
- the enabled stack plugin's `fix-bug` skill (`ai-ios-toolkit:fix-bug` or the stack equivalent) when Gate 3 produced code-level findings

Never upload a build for release, never commit a Play edit, never bump the build number, never commit.

## Related surfaces

`/multi-agent:testflight-validation` is a thin alias onto this command, kept so the
iOS-only name keeps working; it resolves here with the platform pinned to iOS.
`/multi-agent:test "store-ready"` also resolves here. There is one implementation.
