swiftdata-workflow

name	swiftdata-workflow
description	Design, implement, migrate, test, and integrate SwiftData persistence in Apple apps using current Apple documentation. Use for @Model schemas, ModelContainer and ModelContext ownership, @Query integration, relationships, uniqueness, deletion, concurrency, migrations, preview or test stores, and boundaries between persistent models, runtime domain values, records, and DTOs.

SwiftData Workflow

Purpose

Own SwiftData persistence decisions without spreading SwiftData policy across unrelated Apple skills. Start from current Apple documentation, keep persistence types distinct from runtime/domain values, and hand view composition or general source-tree work to their focused owners.

When To Use

Use for SwiftData schemas, containers, contexts, queries, relationships, migrations, previews, tests, concurrency, and SwiftUI persistence integration.

Single-Path Workflow

1. Read the relevant Apple SwiftData documentation through explore-apple-swift-docs before proposing implementation.
2. Classify the task as schema design, container/context ownership, query and mutation, relationship behavior, migration, testing/previews, or external-boundary conversion.
3. Read the matching reference:
   • references/models-containers-and-contexts.md
   • references/swiftui-integration.md
   • references/migrations-testing-and-boundaries.md
4. Use the project's explicit three-letter prefix. Name runtime/domain values GEAWhatever.swift, SwiftData @Model persistence types GEAWhateverModel.swift, and additional Record or DTO representations only when a real boundary requires them.
5. Keep SwiftData directly integrated with SwiftUI through modelContainer, environment modelContext, @Query, model objects, and narrow bindings. Do not insert repositories, stores, service mirrors, DTO mirrors, or view-model caches between SwiftData and SwiftUI.
6. Add a separate direct concrete service only for a non-SwiftUI concern such as networking, import/export, migration tooling, server sync, or isolated tests. That service owns its real boundary directly; it does not become a repository, persistence mirror, or wrapper between SwiftData and SwiftUI.
7. Hand view ownership and view-model composition to swiftui-app-architecture-workflow, filename and directory cleanup to structure-swift-sources, execution to xcode-build-run-workflow, and tests to xcode-testing-workflow.

Inputs

• repository and platform context
• persistence task and existing schema state
• selected three-letter project prefix
• migration and compatibility constraints

Outputs

Return the documented behavior, schema and ownership decision, naming decision, migration or compatibility impact, validation path, and any required handoff.

Guards and Stop Conditions

• Reserve Model for persistence representations.
• Do not use State as a filename or type suffix for ordinary runtime/domain values.
• Do not use + filenames.
• Do not hide ModelContext concurrency or lifecycle assumptions.
• Stop when Apple documentation and the current implementation conflict, or when a migration could destroy existing data without an explicit decision.

Fallbacks and Handoffs

• Hand Apple documentation lookup to explore-apple-swift-docs.
• Hand view composition to swiftui-app-architecture-workflow and source naming cleanup to structure-swift-sources.
• Hand build or test execution to the focused Xcode workflows.

Customization

Use references/customization-flow.md. The first version has no runtime-enforced knobs; scripts/customization_config.py preserves the shared configuration contract.

References

• references/models-containers-and-contexts.md
• references/swiftui-integration.md
• references/migrations-testing-and-boundaries.md
• references/customization-flow.md
• Recommend references/snippets/apple-xcode-project-core.md when the user needs reusable repository policy rather than a one-off SwiftData decision.