Cloudkit Deploy Schema

Deploy CloudKit schema to Production

A narrow, safety-first operational skill for one specific task: getting this app's CloudKit schema (record types, fields, indexes — never data) from the Development environment into Production. Production is what TestFlight and App Store builds actually use (see docs/tech-design-doc.md §4.3), so an undeployed or wrong schema means sync silently fails for exactly the builds that matter, with no visible error to the end user.

This skill is deliberately conservative. CloudKit Production schema changes are (practically) one-directional and permanent: fields can be added to Production at any time, but cannot be deleted once deployed (docs/tech-design-doc.md §4.3). A careless deploy bakes in cruft forever. Treat every deploy — the first one and every subsequent one — as something to slow down for, not a routine mechanical step.

Model preference

Run this skill on the latest Opus-tier model (or its contemporary equivalent), not Sonnet. Unlike the checklist-walking orchestration in appstore-prepare-for-release (deliberately Sonnet — mechanical steps, no linguistic/architectural judgment), this skill's entire job is judgment: deciding whether a schema diff is intentional or stale cruft, whether a field removed from the Swift model was ever actually synced to Development, and whether a given action is the safe direction or the destructive one. The consequence of a wrong call here is a permanent, unfixable mutation to a production system serving real users — that is exactly the profile of a release-checklist item worth the extra reasoning depth (same rationale as appstore-prepare-for-release's P1.6/P1.7/P1.8/P6.1 escalations, which this skill supersedes for schema work specifically at P3.7). If invoked from a Sonnet-orchestrated session (e.g. mid-checklist), spawn this skill's work on an Opus subagent rather than running it inline on Sonnet.

Hard rules

• Never treat this as a fire-and-forget script. Every step below that writes anything (Reset Environment, Deploy Schema Changes, cktool import-schema to either environment) requires an explicit, freshly-stated human confirmation immediately before running it — even if the user approved the overall plan earlier in the conversation. Re-confirm at the point of action, not just at the start.
• "Reset Environment" and "Deploy Schema Changes" are opposite directions — never conflate them.
  • Reset Environment (Development only) wipes Development's schema and data back to match whatever is currently in Production. If Production is empty or behind Development, this is destructive to Development's working state.
  • Deploy Schema Changes (Development → Production) is additive-only: it pushes Development's current schema to Production. It never touches data in either direction.
  • Before either action, state out loud (to the user) which direction you believe you're going and why, and get their explicit go-ahead.
• Never hand-author or hand-edit a CKSL (.ckdb) file's field types from guesswork about how SwiftData encodes a property. SwiftData's CloudKit mirroring has its own internal encoding (e.g. for Decimal, optional arrays, nested Codable structs) that isn't safe to reverse-engineer. The reliable source of truth for "what should the schema contain" is the Development schema as generated by the app's own real persistence code — never a schema file typed up by hand.
• Data and schema are entirely separate stores. Clearing/reviewing Development data has zero effect on what a schema deploy pushes to Production, and vice versa. Don't conflate a data-hygiene concern with a schema-deploy concern.
• The CloudKit Console's "Deploy Schema Changes" button is the only way to promote a schema to Production — there is no cktool equivalent, despite appearances. cktool import-schema accepts --environment production as a syntactically valid flag value (and Apple's own man page lists it without caveat), but the server-side endpoint rejects it at request time: BadRequestException: endpoint not applicable in the environment 'production' (confirmed empirically, not just documented — don't trust the flag's accepted-values list over what the API actually does). import-schema only actually works against --environment development. Budget for a manual Console click at the deploy step every time; don't try to script around it.

Preflight checks (every invocation)

Run these before touching anything, and report the results before asking for any confirmation:

1. Identify the container and team. Read com.apple.developer.icloud-container-identifiers from simple-recurring-budgets/Resources/simple_recurring_budgets.entitlements for the container id; the team id comes from the Apple Developer account in use (ask the user if not obvious from fastlane/.env or Xcode settings).
2. Confirm cktool auth. Schema management commands need a Management Token (different from the ASC API key used elsewhere in this repo):

   xcrun cktool save-token --type management
   

   This is interactive (opens a browser/prompts for the token) — tell the user to run it themselves if not already authenticated; don't attempt to script around it.
3. Snapshot both environments before changing anything:

   xcrun cktool export-schema --team-id <TEAM> --container-id <CONTAINER> --environment development --output-file tmp/schema-dev.ckdb
   xcrun cktool export-schema --team-id <TEAM> --container-id <CONTAINER> --environment production --output-file tmp/schema-prod.ckdb
   

   Show the user a summary of each (record types present, field counts) and the diff between them. This is your evidence base for every subsequent question — don't ask the user to characterize the current state from memory when you can just read it.
4. Full bidirectional model-vs-schema field audit — mandatory before every deploy, not optional. Cross-reference the Development schema (exported above) against the current Swift model source (simple-recurring-budgets/Models/*.swift) in both directions and present the result as a table (one row per @Model class):
   • Stale fields (in the CloudKit schema, absent from the current model): a candidate for removal from Development before deploying — see "Handling stale fields" below. Don't rely on memory of what used to exist; git log -p -- path/to/Model.swift is the authoritative record.
   • Missing fields (a stored property on the current model with no corresponding CD_<field> in the exported Development schema): this means the field never got a non-nil value written anywhere in whatever generated the current Development data, so CloudKit never created it — it will silently be absent from Production too if you deploy now. This is the more dangerous direction to miss, because it doesn't show up as a "diff" against anything; it's an absence. Block the deploy and go back to generating more complete Development data (see step 2 in Recipe A, or the equivalent regeneration for Recipe B) until every stored property has a corresponding field.
   • When listing "current model" properties, get the list directly from each @Model class's stored properties (var/let declarations that aren't computed), not from memory or from what a test/preview happens to touch. Exclude the model's own to-many relationship arrays from the "should appear on this record type" expectation — SwiftData represents a to-many relationship via the inverse foreign key (CD_<parentType>) on the child record type, not as a field on the parent. Confirm each relationship's inverse key is present on the child type instead of expecting it on the parent.
   • Do this for every @Model class in the schema's models array (check the VersionedSchema conformer, e.g. SchemaV1.swift, for the authoritative list), not just the ones that seem most relevant.

Recipe

A. First-ever ("greenfield") deploy for a container

Use when Production's schema is empty or near-empty (only Apple's built-in system record types, e.g. Users) and this is the first time this container's schema is being established.

1. Run the preflight checks above. Confirm with the user that Production is indeed empty/greenfield — don't assume it from a prior conversation turn.
2. Generate a complete, deterministic Development schema from real app code — do not rely on ad-hoc manual UI exercise, which risks missing a field. The reliable path:
   • Check whether a comprehensive fixture/seed routine already exists in the codebase (e.g. DebugData.seed(into:) or equivalent — search for #if DEBUG seed helpers under Models/ or Previews/). If one exists and its coverage of model fields looks complete (cross-check against the current model's stored properties), prefer reusing it.
   • Wire it to a throwaway trigger (a #if DEBUG-gated button, or a temporary call in the app-launch path) on a separate throwaway git branch that is never merged to main — never commit temporary seed-wiring to a real feature branch or main.
   • Have the user run a plain Debug/Development-signed build (Xcode Run, simulator or physical device — what matters is Development code signing, not device vs. simulator) signed into a real iCloud account with network on, and trigger the seed once.
   • Confirm the seed actually reached CloudKit (not just the local SwiftData store) — ask the user to check the CloudKit Console's Development data browser for the new records, or re-run export-schema --environment development and confirm the expected record types/fields now appear.
   • Don't delete the throwaway branch yet — keep it until the deploy is verified (step 5/7 below), in case a gap surfaces in the audit and you need to re-seed.
3. Re-export the Development schema and re-run the full field audit from preflight check 4 (not just a diff against empty Production — every model field must be confirmed present, not just "different from before"). Present the audit table and the diff against the empty Production baseline to the user. Explicit confirmation required before proceeding.
4. Deploy: tell the user to go to CloudKit Console → container → Schema → Deploy Schema Changes. This step is manual, always — cktool import-schema --environment production is not a real alternative (the API rejects it; see the hard rule above). Have the user confirm once they've clicked through the Console's diff preview and committed.
5. Verify: export-schema --environment production again, confirm it now matches Development's record types/fields.
6. Record what was deployed (record types, field count, date, method used) in the release checklist snapshot's P3.7 item (see docs/app-store-release-checklist.md) and/or docs/tech-design-doc.md §4.3 if the constraint notes need updating.
7. Clean up the throwaway branch now that the deploy is verified — don't leave it lying around "just in case." Confirm its only commits are the temporary seed-wiring (git log --oneline main..<branch>, sanity-check the diff touches only the throwaway trigger, nothing else), then delete it:

   git branch -D <throwaway-branch>
   

   (force-delete, since it was deliberately never merged — a plain -d will refuse). If it was ever pushed to a remote, delete it there too (git push origin --delete <throwaway-branch>) — though per the rule above it should have stayed local-only.

B. Incremental deploy (schema already established in Production)

Use for any release after the first, when the SwiftData model has changed (new fields/record types) since the last deploy.

1. Run the preflight checks. The diff between the two exported schemas is the change set — present it to the user explicitly, field by field.
2. If preflight check 4 flags any "missing fields" (a new stored property on the model with no corresponding field yet in Development — the normal case right after adding a field to an @Model class, before any record has ever been saved with a non-nil value for it), the same problem as Recipe A step 2 applies: don't guess, generate real data. Follow that step's method — reuse/extend a #if DEBUG seed fixture on a throwaway branch, run a Debug build signed into a real iCloud account, confirm the field materializes via a re-export — before proceeding. Skip this step only if the audit found no missing fields.
3. Confirm every new field in the diff is intentional (traces to an actual model change, not stale cruft) — cross-check against git log for the relevant model files if anything looks unexpected.
4. Explicit confirmation required before deploying, quoting the exact diff being promoted.
5. Deploy: tell the user to go to CloudKit Console → container → Schema → Deploy Schema Changes (manual, always — see the hard rule above).
6. Verify with a post-deploy export-schema --environment production.
7. Record the deploy in the current release's checklist snapshot P3.7 item.
8. If step 2 required a throwaway seeding branch, clean it up now per Recipe A step 7 (sanity-check its commits, then git branch -D).

Handling stale fields in Development

If the preflight check finds Development schema fields with no corresponding property on the current model (e.g. a renamed or removed field from an earlier development iteration):

• These can be deleted directly in the CloudKit Console (Development schema, unlike Production, supports field deletion) — confirm with the user which specific fields to remove, one by one, before doing so.
• Never use Reset Environment as a shortcut to "clean up" Development stale fields unless Production is confirmed empty/behind — Reset Environment wipes Development back to match Production's current state, which is destructive if Production isn't already a superset of what you want to keep.
• Removing a stale field from Development has no effect on Production unless it was already deployed there — in which case it's stuck permanently (Production can't lose fields) and the right move is just to stop adding data to it going forward, not to attempt removal.

Where this fits in a release

This skill is invoked from the App Store release checklist's P3.7 (docs/app-store-release-checklist.md, driven by /appstore:prepare-for-release) — that item's Note should reference back to what this skill did (deploy method, fields involved, verification result) rather than duplicating the full recipe.