| name | asc-ops-handoff |
| description | Use when planning, scoping, or executing user-owned App Store Connect / TestFlight / Apple Developer operations for the repo apps (Sudoku / Minesweeper) — IAP product registration, App Privacy questionnaire, AdMob console linkage, sandbox tester provisioning, TestFlight upload + review, ASC submission, App Metadata uploads. Codifies which steps are user-owned (require Apple ID / 2FA / web UI) vs Leader-orderable (via ASC API + ASCRegister CLI), and the canonical doc + verification checklist for each. |
ASC Ops Handoff
When to invoke
- Planning a release ship (current target: v2.6 first App Store release, both apps) → which steps are user vs Leader-orderable
- Subagent asks "should I do X" where X involves ASC web UI
- Drafting a release readiness checklist for user
- User says "I'm about to submit to App Store — what do I need to check"
- Code Reviewer flags an Apple-platform-ops question
- An
ASCRegister apply run returns ENTITY_ERROR.<CODE> → see asc-entity-error-recipes.md
Canonical doc
docs/v2/v2.5-readiness.md is the authoritative ops checklist as of v2.5 (a v2.6 readiness doc should supersede it at submission time). This skill explains WHO does WHAT and HOW; the readiness doc is WHAT'S DONE / OUTSTANDING.
Pre-submission preflight (run this FIRST, every time)
A real v2.6 submission attempt (2026-07-28) hit nine ASC-side prerequisites
one at a time — each discovered only when a mutating call was already
rejected, because nothing in this repo tracked them: releaseType left at
the auto-release default, no build attached, empty copyright, no app price
schedule (STATE_ERROR.APP_PRICING_REQUIRED), an unanswered age rating
questionnaire, no content rights declaration, a missing App Review contact
record, screenshots for only 2 of 7 locales, and a stray non-cancellable
reviewSubmissions record.
mise run preflight:submission <app|all> <ios|macos|all> (read-only) checks
all nine plus version/editable-state, screenshot-coverage-per-locale, and IAP
review-screenshot presence, printing a PASS/BLOCK/MANUAL-VERIFY table and
exiting non-zero on any BLOCK. --fix auto-fills ONLY copyright (from
app-meta.yaml), releaseType=MANUAL, and attaching the newest processed
build — never pricing/availability, age rating, content rights, or
review-contact details (those are decisions or PII, and stay user-owned).
See docs/app-store/SUBMISSION-CHECKLIST.md Step 0 and
asc-entity-error-recipes.md for the per-item recipes. Run it before
starting the manual checklist AND again immediately before clicking Submit.
Operation taxonomy
🙋 User-owned (require human + Apple ID + 2FA)
Cannot be subagent-driven. Document in v2.5-readiness.md as - [ ] items; track via GitHub issue (e.g. #132).
| Op | Where | Notes |
|---|
| Apple Developer Program enrolment / annual renewal | developer.apple.com | One-time + yearly |
| Generate ASC API Key (.p8 + Key ID + Issuer ID) | App Store Connect → Users and Access → Keys | Required for ASCRegister + Xcode Cloud signing |
| App Privacy questionnaire | ASC web UI → My Apps → Sudoku → App Privacy | No REST API exists (verified 2026-05-23) — must align manually with PrivacyInfo.xcprivacy |
IAP pricing tier + Ready to Submit | ASC → My Apps → … → In-App Purchases | Product creation, per-locale localization, AND the review screenshot are now automated (ASCRegister iap apply / iap screenshots, see Leader-orderable table); what remains web-UI is the price/availability and flipping status to Ready to Submit |
| Sandbox tester account | ASC → Users and Access → Sandbox | One per region you want to test |
| AdMob console linkage | apps.admob.com | Link to ASC App ID; create banner ad unit |
| Create the ASC app record | Developer Portal (App ID) + ASC web UI (My Apps → +) | ASCRegister consumes --app-id — it cannot create the app; do this first, then feed the app-id to the tools |
| App Store nutrition labels | ASC web UI → App Privacy | Must align with PrivacyInfo |
| TestFlight build promotion to production | ASC → TestFlight → Build → Distribute | Tap "Submit for Review" |
| Apple Review response (rejection / approval) | ASC → App Store → Submission | Reply to Apple's notes |
| Production AdMob ID swap (paired with IAP unit) | App/Info.plist GADApplicationIdentifier + LiveAdMobBridge.swift Release branch | Triggered AT v2.5.3 submit; must be paired flip (see v2.5-readiness.md §v2.5.3) |
🤖 Leader-orderable (via ASCRegister CLI + ASC REST API)
Subagent-driveable. Document as "automated by ASCRegister X mode".
| Op | Tool | Status |
|---|
| Register Game Center leaderboards (3) | tools/ASCRegister | ✅ shipped (v1) |
| Register Game Center achievements (8) | tools/ASCRegister | ✅ shipped (v1) |
| Register IAP product | ASCRegister iap plan|apply | ✅ SHIPPED — iap subcommand creates/updates the IAP from metadata xcstrings (the 2026-05-26 cancellation was later reversed; confirm via ASCRegister --help). Requires the ASC app record to already exist (--app-id). |
| Upload IAP review screenshot | ASCRegister iap screenshots --iap-id <id> --screenshot <png> --i-am-sure | ✅ SHIPPED — reserve→PUT→commit to /v1/inAppPurchaseAppStoreReviewScreenshots, idempotent (GET→skip-if-matching / evict-and-replace-on-drift); WRITE gated behind --i-am-sure. Verified live on both apps 2026-07-20. Screenshot source: any accepted portrait dimension (e.g. 1290×2796) showing the Remove Ads purchase point — mise run ui:tour emits a Settings frame. |
| Upload App Metadata (description / keywords / screenshots / what's new) | ASCRegister metadata plan|apply|set-version|screenshots | ✅ SHIPPED — metadata subcommand uploads listings + screenshots per locale (the 2026-05-26 backlog item was implemented; screenshots gated behind --i-am-sure). |
🤝 Hybrid (Leader prepares; user pushes the button)
| Op | Leader does | User does |
|---|
| Xcode Cloud signing | Pin Xcode version in .mise.toml; ci_post_clone.sh writes Tuist/Signing.xcconfig from $CI_TEAM_ID | One-time: connect ASC to Xcode Cloud, configure team |
Branch protection on main | Methodology doc + workflow yml | Settings → Branches → required status checks |
| GitHub App bot identity (audit-trail clean) | scripts/bot-gh-token.sh JWT helper; .gitignore + foundations §7 | Create the GitHub App, install on repo, save .pem |
When subagent asks "can I do X for ASC?"
Cross-reference the taxonomy above. If user-owned → respond "this is user step, add to the appropriate *-readiness.md checklist and surface to user". If Leader-orderable → confirm tool exists or scope the CLI extension. If hybrid → split the work in dispatch prompt.
Documentation pointers
docs/v2/v2.5-readiness.md — current ship checklist; user-owned items as - [ ]docs/v2/plan.md §v2.5 — phase summary; defers to readiness doc for detailtools/ASCRegister/ (project source: Packages/ASCRegisterKit/Sources/ASCRegister/) — existing CLIdocs/app-store/metadata/README.md — yaml schema consumed by ASCRegister metadata mode (shipped)docs/foundations.md §Backlog — ASC API ops backlog entriesdocs/v2/design.md §Backlog — historical CANCELLED/BACKLOG ASC ops (note: the IAP + metadata modes listed there were later implemented — ASCRegister --help is current truth)
Anti-patterns
- "The App Review contact email/phone live in
secrets/.env" — NO (corrected
2026-07-29). docs/app-store/metadata/<app>/app-meta.yaml and the
review/<app>-v2.6-review-information.md contact tables previously claimed
ASC_REVIEW_EMAIL/ASC_REVIEW_PHONE keys existed in secrets/.env; they do
not, and never did — the 2026-07-28 submission got the contact name/email/
phone from the user directly, typed into the ASC web UI at submission time.
Don't invent or expect those env keys; don't try to script the contact fields.
- "IAP is fully automated, no user step" — NO.
ASCRegister iap apply creates the product + localizations and iap screenshots uploads the review screenshot, but pricing/availability and the final Ready to Submit flip remain web-UI (user-owned) — there is no ASC REST API for IAP price schedules in this tool. Automate creation + localization + review screenshot; hand price + submit to the user.
- "We'll fill App Privacy questionnaire later via API" — NO. There is no API. Verified 2026-05-23.
- Shipping with test AdMob IDs in production: paired flip exists for a reason. Per RCA #149 Fix N1, Release build with test app ID + production ad unit ID will silently no-fill at best.
- Conflating "ASCRegister handles Game Center" with "ASCRegister handles everything": explicit mode-by-mode tracking required. Game Center / IAP / metadata modes are all SHIPPED (
ASCRegister --help is the source of truth). The one thing ASCRegister does NOT do is create the app record — it consumes --app-id, so the ASC app must be created in the web UI first (user-owned).
Example application
User asks: "Should we automate the v2.5.3 production AdMob ID swap?"
Cross-reference:
- The swap touches
App/Info.plist + LiveAdMobBridge.swift — both source-controlled
- Trigger: user-owned (decides WHEN to flip)
- Execution: Leader-orderable (it's just a 2-file PR)
- Verification: user-owned (TestFlight + real-device test ads run by user per
v2.5-readiness.md §v2.5.2)
Verdict: hybrid. Recommend: at v2.5.3 user-says-ready, dispatch a subagent to do the 2-file flip in one PR, user merges + uploads TestFlight build.
