swift-modularization-pro

Turn an Apple app into a thin app target over a local Swift package of small modules, or check one that already is. This is the deep companion to the always-on apple-modular-architecture.md rule. The rule steers while writing; this skill plans a graph, audits a whole package, and drives a migration one module at a time.

Pick the mode from the request:

• Plan: a new app, or an existing app before any move. Produce a module map (module · layer · purpose · dependencies) and the order to extract them, using references/module-graph.md. Start small (Core, a domain module or two, one feature, AppCore) and say which later splits you'd expect.
• Migrate: move code out of the app target, or out of an oversized module, following references/migration.md. One module per step, the app building and tests passing after each.
• Audit: an app that already has a package. Run the checks in references/audit.md, then report findings ranked by severity.

Review process (audit mode):

1. Inventory: list the modules, the app target's Swift files and line counts, and every extension target. Use references/audit.md ("Inventory").
2. Check the app target against "What stays in the app target" in references/migration.md. Any view, view model, or service there is a finding.
3. Check the graph using references/module-graph.md and the dependency script in references/audit.md: layer violations, feature→feature edges, consumers importing concrete backends, cycles, oversized or near-empty modules, undeclared reliance on @_exported.
4. Check resources and tests: Bundle.main inside modules, modules without a Tests/ target, tests that only run under xcodebuild without a reason, and whether CI runs swift test on package changes.

If doing a partial review, load only the relevant reference file.

Core Instructions

• The app target is a shell. It keeps @main, Info.plist, entitlements, assets, the privacy manifest, InfoPlist.xcstrings, and the AppShortcutsProvider with its main-bundle catalogs. Everything else belongs in a module.
• Direction is the architecture. Core ← domain ← features ← AppCore. Features never import each other; shared needs move down a layer.
• Interfaces before implementations. When a capability has interchangeable backends (AI providers, analytics, storage), consumers depend on an interface module and an umbrella picks the backend. A feature importing a concrete backend is a finding, unless the UI is specifically about that backend (a provider picker).
• Incremental, never big-bang. Every plan step leaves the app building, tests green, and the change reviewable on its own. Never propose moving every file in one pass.
• Every module is testable headless. It has a Tests/ target and passes under swift test. The exceptions are resources the SwiftPM CLI can't compile, such as .xcdatamodeld, and those are guarded and documented.
• Granularity follows real boundaries. Split a module when it has two reasons to change, a heavy dependency only part of it needs, or other targets (widgets, intents) need part of it. Don't split speculatively. A module with one tiny file and one consumer probably belongs to that consumer.
• Use the bundle's tools. Scaffold with scripts/scaffold-spm-package.sh and keep makeTargets() in the manifest (templates/Package.template.swift). Manifest settings follow apple-spm-package-conventions.md.
• Severity by cost: broken (a cycle, Bundle.main resources in a module, Siri phrases lost because the AppShortcutsProvider moved) > boundary leak (feature→feature edge, a concrete backend imported by features, logic in the app target, an @_exported hiding a missing dependency) > shape (oversized or near-empty modules, a missing graph doc in CLAUDE.md).
• Cross-reference, don't duplicate: public API and manifest details go to swift-package-pro, concurrency under the new boundaries to swift-concurrency-pro, Core Data in a package to coredata-swift6-pro, and design-system module contents to swift-design-system-pro.