Swift Source Organization Workflow

Swift Source Organization Workflow

Purpose

Keep Swift source trees small, navigable, and organized around real responsibility boundaries.

Use swift-format-style-workflow before structural edits and again afterward. Hand off to apple-dev-skills when file moves require Xcode target membership, project-file mutation, previews, schemes, or build/run validation.

Workflow

1. Establish or confirm the formatting baseline.
2. Resolve repo shape:
   • Swift package
   • Xcode app project
   • mixed package plus app
   • server-side Swift service
3. Inventory source shape:
   • large files
   • mixed concerns
   • broad extensions
   • unclear access-control boundaries
   • nested types that block reuse
   • long TODO/FIXME comments
   • redundant or missing // MARK: sections
4. Split by concern:
   • strongly consider splitting around 250 to 300 lines when two or more concerns are present
   • treat 500 to 600 lines as a hard split signal unless the file is generated or has a documented exception
   • prefer complete passes over tiny partial splits when adjacent files are part of the same concern cleanup
5. Choose the split shape:
   • TypeName+Models.swift
   • TypeName+Validation.swift
   • TypeName+Pipeline.swift
   • TypeName+Formatting.swift
   • feature directories for independent user-facing or domain areas
   • layer directories when a package has clear API, domain, persistence, transport, or UI boundaries
6. Preserve behavior:
   • keep access control intentional
   • keep generated files untouched
   • update package manifests or Xcode project membership through the owning workflow
   • run formatting after moves

MARK Guidance

• Add // MARK: - <Heading> only when it improves navigation.
• Name the responsibility boundary, not the declaration kind.
• Avoid filler headings in short files.
• Avoid comments that repeat obvious method or type names.

File Header And Ledger Guidance

• Preserve existing license banners.
• Use file headers only when the repository already requires them or the task explicitly includes header normalization.
• Keep file-header purpose and concern text plain, specific, and non-generic.
• Move long TODO and FIXME prose into ledgers when the repo uses ledger files; keep source comments short and traceable.

Output Shape

Return:

1. Organization state: repo shape and largest concern problems.
2. Split plan: files to split, target names, and reason for each split.
3. Moves: directories or manifests that need updates.
4. Handoffs: Apple Dev, Server-Side Swift, or package validation needs.
5. Validation: formatting, build, test, or project-integrity checks.

Guardrails

• Do not split files purely by line count when the file is coherent and generated files are excluded.
• Do not invent abstraction layers just to make files shorter.
• Do not move files across Xcode-managed boundaries without project-membership follow-through.
• Do not leave duplicate helpers behind after extraction.
• Do not use // MARK: as decoration.