iphone-duo-readiness git:20261030.98cdb7cA

Immutable. This exact content never changes and is served at /api/v1/blob/77cedd34cc83eb64.

---
name: iphone-duo-readiness
description: >-
  End-to-end readiness workflow for iPhone Duo, Apple's foldable iPhone with an
  outer display and a regular-by-regular inner display. Use when a developer wants
  to prepare, audit, plan or test a SwiftUI or UIKit iOS app for iPhone Duo, the
  iOS 27 / 27.1 SDK resizable-app changes, foldable poses and the hinge, vertical
  bars, Device Hub pose simulation, Apple's "Prepare your app for iPhone Duo"
  guidance, or what an iPhone Duo submission owes App Store Connect (screenshots for
  both displays, the April 2027 deadlines). Runs a read-only scan and SDK check
  first, produces a tiered plan with session citations, changes code only after
  itemized approval by delegating to the iphone-duo specialist skills, and verifies
  against a pose matrix.
---

# iPhone Duo readiness

Coordinates the four specialist skills. It owns the order of work, the approval
gate and the final report; the specialists own the details.

| Specialist | Owns |
| --- | --- |
| `iphone-duo-adaptivity-audit` | Scene lifecycle, main screen, idiom, orientation, screen bounds, global window state, Face ID assumptions |
| `iphone-duo-bars` | Vertical bars: containers, ordering, titles and symbols, axis, overflow, priority, sheets, opt-out |
| `iphone-duo-layout` | Size classes, standard navigation, safe areas, corners, reserved regions, displacement, arrangements |
| `iphone-duo-displays` | Hinge, Split View multitasking, multiple scenes, scene accessories, cameras, StandBy presence |

## Contract

- **Phase 1 is read-only.** Scanning, SDK checks, reading code and writing the plan
  change nothing in the project. Keep scan output in a temporary directory, not the
  repository.
- **No edits without approval of item IDs** (see `references/recommendation-format.md`).
  "Make my app ready for iPhone Duo" before a plan exists is a request for the plan.
- **The SDK decides what can be written.** Run `scripts/sdk_api_check.py` before
  proposing any API from a talk. Never write code against a symbol the selected SDK
  lacks; mark it *blocked* with the SDK that introduces it
  (`references/api-availability.md`).
- **Cite a session and timestamp for every item** (`references/sources.md`).
- **Report verification honestly.** A green build proves it compiles. Only a pose
  run on the iPhone Duo simulator — set in Device Hub, or from a script with the
  third-party `hinge` CLI (`references/pose-test-matrix.md`) — or on a device proves
  layout, and only for the poses actually run.

## Phase 1 — Recommend

### 1. Preflight

```bash
xcodebuild -version
xcrun --sdk iphoneos --show-sdk-version
xcrun simctl list devicetypes | grep -i duo     # empty: no iPhone Duo simulator in this Xcode
xcrun simctl list runtimes | grep -i "iOS 27.1" # the device type needs the 27.1 runtime
```

Xcode 27.1 (beta 27A9269 on 2026-09-18, RC on 2026-10-05) ships the iOS 27.1 SDK, the
`iPhone Duo` simulator device type (`iPhone19,4`) and the iOS 27.1 runtime, so the
27.1 APIs are ordinarily available rather than blocked — the question becomes the
deployment target, not the toolchain. App Store Connect has accepted Xcode 27.1 builds
optimized for iPhone Duo since 2026-10-05.
If either command above matches nothing, the installed Xcode is older: say so in the
report and plan accordingly. `references/api-availability.md` says what each linked
SDK gets on the device and `references/sources.md` keeps the calendar.

Identify the app targets, UI framework mix (SwiftUI, UIKit, both), deployment target,
and how the project is generated (Xcode project, Tuist, XcodeGen, SwiftPM). Read the
project's own agent instructions (`AGENTS.md`, `CLAUDE.md`) — documented decisions
about orientation, idiom or layout forks outrank a scanner match.

Check whether Xcode ships Apple's own modernization skill, which already performs
careful UIKit rewrites (`UIScreen.main`, orientation, scene lifecycle, safe areas):

```bash
out="$(mktemp -d)" && xcrun agent skills export --output-dir "$out" >/dev/null 2>&1; ls "$out"
```

Xcode 27.0 exports it as `uikit-app-modernization`. Xcode 27.1 ships it as
`app-resizability`, with task references for idiom, orientation, safe areas, scene
lifecycle and `UIScreen` — its safe-area task already points at
`traitCollection.verticalBarEdge` and `@Environment(\.toolbarVerticalEdge)`.
Xcode 27.1 also ships `device-interaction`, a subagent skill for driving a simulator
or device, which complements the pose matrix rather than replacing it. Note what
exists and remove the temporary directory when done.
When `app-resizability` is installed as an agent skill, it triggers on the same
request ("get my app ready for iPhone Duo") and applies every task in its registry.
Run this workflow first: the scan and the tiers decide the scope.
Then hand the approved UIKit rewrites to Apple's skill.

### 2. Scan

```bash
python3 scripts/duo_scan.py <project-root> --format json > "$TMPDIR/duo-scan.json"
python3 scripts/duo_scan.py <project-root> --format markdown      # human summary
python3 scripts/sdk_api_check.py                                   # what this SDK can compile
```

`duo_scan.py` skips dependencies (`Pods`, SwiftPM checkouts, `vendor`) and hidden
directories such as worktrees; pass `--include-dependencies` only when the developer
owns that code. Its matches are heuristics — every one needs the surrounding code read
before it becomes a recommendation. Use the `inventory` block to size the bar and
layout work (how many toolbars, split views, custom bar items, camera sessions).

### 3. Triage into tiers

| Tier | Contents | Why first |
| --- | --- | --- |
| 0 — Blockers | App lifecycle without scenes (`DUO005`), no launch screen (`DUO022`) | The app does not launch when built with the latest SDK; without a launch screen, App Store Connect rejects the upload (`ITMS-90870`). |
| 1 — Correctness | Main screen, screen bounds, orientation and idiom layout forks, symmetric safe-area math, content under the vertical bar, bar offsets, keyboard frames, global window state, Face ID copy (`DUO001–004`, `006`, `009`, `013–017`) | Wrong layout on the inner display, in Split View, in iPhone Mirroring and on iPad; wrong words on a Touch ID device. |
| 2 — Bars | Standalone bars, titles/symbols, ordering, overflow, priority, hand-built tab bars and back buttons (`DUO007`, `DUO011`, inventory) | Bars move to the side on the inner display with the 27.1 SDK; items without titles or with text-only labels land badly; a custom bar never moves by itself. |
| 3 — Richer adoption | Sidebar placement, reserved regions for top custom controls, collection-view sections and web content clear of the fold (`compositional layout`, `web views` in the inventory), arrangements, hinge effects, scene accessories, camera direction handling, multiple windows, a widget or Live Activity for StandBy on the outer display, App Store screenshots for both displays, required from April 2027 (`references/device-geometry.md` › App Store assets) | Makes the app good on iPhone Duo rather than merely correct; most of it compiles on Xcode 27.1 and is blocked only on Xcode 27.0. StandBy cannot be verified in the iPhone Duo simulator (Xcode 27.1 known issues 187708663, 187708767). |

Two App Store Connect requirements start in April 2027.
Builds must use the iOS 27 SDK or later.
Submissions must include iPhone Duo screenshots: per the screenshot specifications,
apps using the iOS 27.1 SDK or later; per Apple's news of 2026-10-05, every app.
Date the screenshot item in the plan, and say which wording you quote
(`references/sources.md` › Release calendar).

Inside every tier, put items that compile with the installed SDK first and mark the
rest *blocked*. A toolchain upgrade is a prerequisite note on the blocked items, not a
step in front of work the team can ship today — waiting for Xcode 27.1 should never
delay removing `UIScreen.main` or adopting scene lifecycle.

If the app ships a Mac Catalyst target, adopting any 27.1 API is a Tier 1 build risk:
iOS 27.1 APIs do not compile for Catalyst (Xcode 27.1 known issue 185924957) and a
target on iOS 27.1 loses its Catalyst run destination (187046347). Plan the
`#if !targetEnvironment(macCatalyst)` or the Catalyst 27.0 minimum deployment with
the item, not after it.

Some code looks like work and is not. A scene delegate that saves and restores a fold
state, a device check for iPhone Duo, or a sheet dismissed when the device folds is a
finding to remove, not a pattern to extend: a fold is a trait and geometry change of
the same scene (`references/sources.md` › Developer Forums Q&A, 848035, 847775,
848034).

Hand each tier to its specialist skill for the detailed recommendations. Classify
legitimate uses as **kept** with the reason (for example an orientation read that
answers a physical question no geometry can, documented in the code).

### 4. Present the plan

Write the report with the skeleton in `references/recommendation-format.md`: toolchain,
tiers, *kept*, *blocked*, *not verified*. Ask the developer which IDs to apply.

When the developer says "just do it" for something the SDK cannot compile, the useful
answer is still concrete: show the compiler error or SDK check that blocks it, apply or
offer the nearest change that does compile (for example size-class driven layout
instead of an arrangement), and keep the blocked change as a plan item.

## Phase 2 — Apply and verify

1. Apply approved items **one tier at a time**, through the owning specialist skill.
   For large UIKit legacy-API migrations, prefer Apple's exported modernization skill
   if present and review its diff against the plan.
2. Stay in scope: change only lines the approved items name. No drive-by reformatting.
3. Build after each tier with the project's own build command. Fix what you broke
   before moving on.
4. Re-run `duo_scan.py`; confirm resolved findings are gone and nothing new appeared.
5. Run the pose matrix (`references/pose-test-matrix.md`) for the screens touched, if
   an iPhone Duo simulator exists. Otherwise list the poses as *not run* and why.
   With the third-party `hinge` CLI (0.3.0 or later) installed, `scripts/duo_pose.py shoot <dir>
   --relaunch <bundle id>` covers P1–P6, rotated poses included, with a
   screenshot of each display; ask before running it, since it moves the
   simulator's hinge and orientation.
   UI tests cannot rotate the device (`XCUIDevice.shared.orientation` does nothing
   there), so set the pose first, then run them.
6. Update each item's status and hand back the report.

## Guardrails

- Do not "fix" orientation, idiom or screen reads that a project documents as
  deliberate; report them as *kept* and let the developer decide.
- Do not wrap missing 27.1 symbols in `#available` hoping it compiles.
- Do not opt out of vertical bars (`toolbarVerticalBehavior(.disabled)`) to make a
  layout problem disappear; opt-out is for the cases in `iphone-duo-bars`.
- Snapshot references and UI tests may move when layouts change; say which ones and
  why rather than re-recording blind.