Agent Skills: SwiftUI Modular MVVM-C Architecture

SwiftUI Modular MVVM-C Architecture

Opinionated architecture enforcement for SwiftUI clinic-style apps. This skill aligns to the iOS 26 / Swift 6.2 clinic architecture: modular MVVM-C in local SPM packages, concrete coordinators and route shells in the App target, pure Domain protocols, and Data as the only I/O layer.

Mandated Architecture Stack

┌───────────────────────────────────────────────────────────────┐
│ App target: DependencyContainer, Coordinators, Route Shells   │
├───────────────┬───────────────┬───────────────┬──────────────┤
│ Feature* SPM  │ Feature* SPM  │ Feature* SPM  │ Feature* SPM │
│ View + VM     │ View + VM     │ View + VM     │ View + VM    │
├───────────────────────────────────────────────────────────────┤
│ Data SPM: repository impls, remote/local, retry, sync queue   │
├───────────────────────────────────────────────────────────────┤
│ Domain SPM: models, repository protocols, coordinator protocols│
│ and ErrorRouting/AppError                                      │
├───────────────────────────────────────────────────────────────┤
│ Shared SPMs: DesignSystem, SharedKit                           │
└───────────────────────────────────────────────────────────────┘

Dependency Rule: Feature modules import Domain + DesignSystem only. Features never import Data or other features. App target is the only convergence point.

Clinic Architecture Contract (iOS 26 / Swift 6.2)

All guidance in this skill assumes the clinic modular MVVM-C architecture:

• Feature modules import Domain + DesignSystem only (never Data, never sibling features)
• App target is the convergence point and owns DependencyContainer, concrete coordinators, and Route Shell wiring
• Domain stays pure Swift and defines models plus repository, *Coordinating, ErrorRouting, and AppError contracts
• Data owns SwiftData/network/sync/retry/background I/O and implements Domain protocols
• Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes
• ViewModels call repository protocols directly (no default use-case/interactor layer)

When to Apply

Reference these guidelines when:

• Building or refactoring feature modules under local SPM packages
• Wiring coordinators, route shells, and dependency container factories
• Defining Domain protocols for repositories, coordinators, and error routing
• Enforcing Data-only ownership of networking, persistence, and sync
• Reviewing stale-while-revalidate reads and optimistic queued writes

Non-Negotiable Constraints (iOS 26 / Swift 6.2)

• @Observable for ViewModels/coordinators, ObservableObject / @Published never
• No dedicated use-case/interactor layer: ViewModels call Domain repository protocols directly
• Coordinator protocols live in Domain; concrete coordinators own NavigationPath in App target
• Route shells live in App target and own .navigationDestination mapping
• AppError + ErrorRouting drive presentation policy; ViewModels do not hardcode global error UI
• SwiftData / URLSession / retry / sync queue logic stays in Data package only

Rule Categories by Priority

| Priority | Category | Impact | Prefix | Rules | |----------|----------|--------|--------|-------| | 1 | View Identity & Diffing | CRITICAL | diff- | 6 | | 2 | State Architecture | CRITICAL | state- | 7 | | 3 | View Composition | HIGH | view- | 6 | | 4 | Navigation & Coordination | HIGH | nav- | 5 | | 5 | Layer Architecture | HIGH | layer- | 6 | | 6 | Dependency Injection | MEDIUM-HIGH | di- | 4 | | 7 | List & Collection Performance | MEDIUM | list- | 4 | | 8 | Async & Data Flow | MEDIUM | data- | 5 |

Quick Reference

1. View Identity & Diffing (CRITICAL)

• diff-equatable-views - Apply @Equatable macro to every SwiftUI view
• diff-closure-skip - Use @SkipEquatable for closure/handler properties
• diff-reference-types - Never store reference types without Equatable conformance
• diff-identity-stability - Use stable O(1) identifiers in ForEach
• diff-avoid-anyview - Never use AnyView — use @ViewBuilder or generics
• diff-printchanges-debug - Use _printChanges() to diagnose unnecessary re-renders

2. State Architecture (CRITICAL)

• state-observable-class - Use @Observable classes for all ViewModels
• state-ownership - @State for owned data, plain property for injected data
• state-single-source - One source of truth per piece of state
• state-scoped-observation - Leverage @Observable property-level tracking
• state-binding-minimal - Pass @Binding only for two-way data flow
• state-environment-global - Use @Environment for app-wide shared dependencies
• state-no-published - Never use @Published or ObservableObject

3. View Composition (HIGH)

• view-body-complexity - Maximum 10 nodes in view body
• view-extract-subviews - Extract computed properties/helpers into separate View structs
• view-no-logic-in-body - Zero business logic in body
• view-minimal-dependencies - Pass only needed properties, not entire models
• view-viewbuilder-composition - Use @ViewBuilder for conditional composition
• view-no-init-sideeffects - Never perform work in View init

4. Navigation & Coordination (HIGH)

• nav-coordinator-pattern - Every feature has a coordinator owning NavigationStack
• nav-routes-enum - Define all routes as a Hashable enum
• nav-deeplink-support - Coordinators must support URL-based deep linking
• nav-modal-sheets - Present modals via coordinator, not inline
• nav-no-navigationlink - Never use NavigationLink(destination:) — use navigationDestination(for:)

5. Layer Architecture (HIGH)

• layer-dependency-rule - Domain layer has zero framework imports
• layer-usecase-protocol - Do not add a use-case layer; keep orchestration in ViewModel + repository protocols
• layer-repository-protocol - Repository protocols in Domain, implementations in Data
• layer-model-value-types - Domain models are structs, never classes
• layer-no-view-repository - Views never access repositories directly; ViewModel calls repository protocols
• layer-viewmodel-boundary - ViewModels expose display-ready state only

6. Dependency Injection (MEDIUM-HIGH)

• di-environment-injection - Inject container-managed protocol dependencies via @Environment
• di-protocol-abstraction - All injected dependencies are protocol types
• di-container-composition - Compose DependencyContainer in App target and expose VM factories
• di-mock-testing - Every protocol dependency has a mock for testing

7. List & Collection Performance (MEDIUM)

• list-constant-viewcount - ForEach must produce constant view count per element
• list-filter-in-model - Filter/sort in ViewModel, never inside ForEach
• list-lazy-stacks - Use LazyVStack/LazyHStack for unbounded content
• list-id-keypath - Provide explicit id keyPath — never rely on implicit identity

8. Async & Data Flow (MEDIUM)

• data-task-modifier - Use .task(id:) as the primary feature data-loading trigger
• data-async-init - Never perform async work in init
• data-error-loadable - Model loading states as enum, not booleans
• data-combine-avoid - Prefer async/await over Combine for new code
• data-cancellation - Use .task automatic cancellation — never manage Tasks manually

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files

| File | Description | |------|-------------| | references/_sections.md | Category definitions and ordering | | assets/templates/_template.md | Template for new rules | | metadata.json | Version and reference information |