cmux package architecture, refactor layering, dependency inversion, file organization, DocC documentation, package design discipline, testability, and Swift 6 concurrency rules. Use before adding or meaningfully rewriting Swift files, Swift packages, coordinators, services, repositories, or public package APIs.
Expands the package extraction and layering rules in ../SKILL.md.
Domain names vs slice names
Good (a domain): CmuxSettings, CmuxSettingsUI, CmuxAppearance, CmuxWorkspaces, CmuxBrowser, CmuxControlSocket.
Weak (a slice): CmuxAppearanceMath, CmuxWorkspaceModel, CmuxFooFormatting, CmuxFooLogic, CmuxFooState. Slices force callers to depend on several sibling packages any time they touch the real domain.
Extract leaf-first
Extracting the package with no internal dependencies first keeps the migration incremental: fewer dependency edges, fewer project-file entries, simpler tests, a clearer rollback path. It also avoids needing several downstream packages to exist before one package compiles.
Composition root
The executable app target names concrete services and repositories and injects them. No global containers, no runtime-state singletons, no static let shared, no service lookups from package internals. SwiftUI Environment carries already-constructed observable models down a view tree, never service wiring.
Executable target boundary
A lower package cannot extend a higher-owned type without inverting the dependency direction, so AppDelegate+* / cmuxApp+* extensions do not move down. Extract the behavior into a Coordinator/Service/Repository, inject it into the god object or composition root, and reduce the original extension to a one-line forward.
pbxproj wiring
cmux.xcodeproj lists package dependencies explicitly. Adding Packages/CmuxFoo means mirroring an existing package's entries:
one XCLocalSwiftPackageReference in the project's packageReferences
one XCSwiftPackageProductDependency
one PBXBuildFile linked in the Frameworks phase of every target that imports it
App-target packages link into bothcmux and cmux-unit so tests can import and inject them. A package linked by the app but not cmux-unit compiles the app and fails the test target. Copy a recent leaf package for the exact shape, then run:
