# Swift Source Organization Workflow

> Organize Swift source trees and files by concern, feature, and layer; split oversized files, extract extension files, normalize MARK sections, file headers, and TODO/FIXME ledgers with stricter split defaults. Use after formatting baseline is clear.

- Skill: `gaelic-ghost/swift-source-organization-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaelic-ghost/swift-source-organization-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaelic-ghost/swift-source-organization-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- License: Apache-2.0
- Author: gaelic-ghost (https://skillmd.com/u/gaelic-ghost)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gaelic-ghost/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.