cmux Architecture
Sets Swift package layering, dependency rules and concurrency before edits.
Install
npx skills add manaflow-ai/cmux --skill cmux-architecture -g -a claude-code -y- Repository
- manaflow-ai/cmux28.6k
- Category
- Engineering
- Updated
- 3d ago
- License
- See repository
- Context cost
- Mediumabout 3,000 tokens
- Runs scripts
- No, instructions only
What it does
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.
cmux Architecture
Package architecture
cmux is migrating from a single app target into Swift Packages under Packages/. Every new package must be:
- Ergonomic. Default to internal access;
publiconly what downstream consumers actually use. - Acyclic. Packages form a strict DAG. Share a type by lifting it to a lower package or defining a protocol seam in the consumer. Every new dependency edge requires re-checking that the graph stays acyclic.
- Whole-domain. One package owns a full domain (settings, appearance, workspace, terminal, browser, command palette).
CmuxAppearanceMath+CmuxAppearanceTheme+CmuxAppearanceSettingsis folder structure insideCmuxAppearance, not module structure. A boundary exists because more than one consumer needs the contents, or a build/test seam must exist.
When in doubt, extract leaf-first: the package with no internal dependencies. Existing packages under Packages/ predate this policy; do not use them as design references.
Wiring a new package into cmux.xcodeproj needs explicit pbxproj entries in both the cmux and cmuxTests targets (cmuxTests is what the cmux-unit scheme runs). See references/package-boundaries.md.
Group folders. Every package lives physically under exactly one group directory: Packages/Shared/<pkg> (both apps), Packages/iOS/<pkg> (iOS only), or Packages/macOS/<pkg> (macOS only). cmux.xcworkspace/contents.xcworkspacedata mirrors that folder shape, with three groups whose container locations are those folders and every package directory as a FileRef under its folder's group. The folder is the source of truth: to move a package, git mv the directory then run python3 scripts/check-workspace-package-groups.py --write. Cross-group .package(path:) deps use ../../<Group>/<Name>. Never hand-edit workspace group membership. CI runs python3 scripts/check-workspace-package-groups.py --check and fails on drift.
