---
name: structure-swift-sources
description: Organize Swift source trees and oversized Swift files by feature, layer, and declaration group; split large files, normalize `// MARK:` sections, move TODO and FIXME text into ledger files, and add DocC comments. Use after `format-swift-sources` has established a clean formatting baseline.
---

# Structure Swift Sources

## Purpose

Use this skill as the top-level workflow for structural cleanup inside existing Swift repositories. It governs file splitting, file moves, section grouping, DocC coverage, and TODO or FIXME ledger extraction. It is not the formatter or linter integration authority; use `format-swift-sources` before this skill starts mutating source layout, and run `format-swift-sources` again after this skill finishes.

## When To Use

- Use this skill when the user wants to split oversized Swift files or move files into a clearer repo layout.
- Use this skill when the user wants consistent `// MARK:` sections, declaration grouping, or view-modifier extraction in SwiftUI code.
- Use this skill when the user wants TODO or FIXME text moved out of source files into repo ledger files.
- Use this skill when the user wants DocC comments added across Swift symbols as part of a structure or hygiene pass.
- Use this skill when a Swift package or Xcode app repo has drifted away from the intended feature-plus-layer directory shape.
- Recommend `format-swift-sources` first when formatter or linter setup is missing, unclear, or stale.
- Recommend `xcode-app-project-workflow` when structural cleanup turns into active Xcode execution, scheme validation, or guarded project mutation work.
- Recommend `sync-xcode-project-guidance` or `sync-swift-package-guidance` when the real need is repo-level `AGENTS.md` alignment rather than source-structure cleanup.

## Single-Path Workflow

1. Classify the request:
   - repo layout cleanup
   - large-file split
   - section and MARK normalization
   - TODO or FIXME ledger extraction
   - DocC coverage pass
   - combined source-hygiene pass
2. Run or confirm `format-swift-sources` first:
   - use it to establish a clean baseline before file moves or file splits
   - if the repo does not have a clear formatter or linter path yet, stop and set that up first
3. Resolve the repo shape:
   - `swift-package`
   - `xcode-app-project`
   - `mixed`
4. Read the relevant references:
   - `references/glossary.md`
   - `references/layout-rules.md`
   - `references/source-organization-rules.md`
   - `references/todo-fixme-ledgers.md`
   - `references/automation-prompts.md`
5. Apply the structure rules:
   - strongly consider splitting a file once it exceeds `400` lines and clearly holds `2` or more separate concerns
   - always split a file once it exceeds `800` lines
   - when the underlying type is still one coherent type, extract grouped concerns into extension files such as `<Original>+Models.swift` or `<Original>+<Concern>.swift`
   - group declarations into explicit `// MARK: - <Heading>` sections, then place a descriptive secondary `// MARK: <Comment>` line directly below each heading
   - ensure every symbol declaration has DocC-compliant documentation comments
   - move TODO and FIXME text into `TODO.md` and `FIXME.md`, keeping only ticket IDs in source comments
   - when the task is TODO or FIXME normalization, use `scripts/normalize_todo_fixme_ledgers.py` for the deterministic ledger rewrite pass
6. Apply repo-shape rules:
   - for Swift packages, prefer directories grouped by layer and feature, such as `API/<Feature>/<Concern>.swift` and `Features/<Feature>/<Concern>.swift`
   - for Xcode app projects, ensure important app-facing source directories such as `Views/`, `Controllers/`, and `Models/`
   - for SwiftUI views, keep view files in `Views/` and pair them with `<Name>+Model.swift` and `<Name>+Modifier.swift` files when those concerns exist
7. Finish with `format-swift-sources` again so the moved or split files end in a normalized state.

## Inputs

- `cleanup_kind`: one of the request classes above
- `repository_kind`: `swift-package`, `xcode-app-project`, or `mixed`
- `target_scope`: optional narrowed scope such as one file, one feature directory, or the whole repo
- `split_mode`: optional; use values such as `advisory`, `required`, or `full-pass`
- `docc_scope`: optional; use values such as `public-only`, `all-symbols`, or `changed-symbols`
- `todo_fixme_mode`: optional; use values such as `report-only`, `rewrite-ledgers`, or `normalize-existing`
- Defaults:
  - run `format-swift-sources` before and after structural mutation
  - prefer feature-plus-layer layout over flat buckets when the repo has meaningful feature boundaries
  - prefer extracted extensions before inventing new wrapper types
  - prefer `TODO.md` and `FIXME.md` as separate ledger files
  - prefer symbol-level DocC coverage during a full cleanup pass

## Outputs

- `status`
  - `success`: a supported structure path was selected and explained
  - `handoff`: another skill should take the next step
  - `blocked`: the request lacks a safe structural path or the repo shape is too unclear
- `path_type`
  - `primary`: the documented structure path completed
  - `fallback`: a narrower safe pass was chosen
- `output`
  - `cleanup_kind`
  - `repository_kind`
  - `recommended_path`
  - `layout_targets`
  - `split_targets`
  - `ledger_files`
  - `caveats`
  - `verification`

## Guards and Stop Conditions

- Do not split files purely by line count when the code still represents one small, coherent concern and the real problem is formatting or comments.
- Do not invent new abstraction layers just to make a file shorter.
- Do not move files across Xcode-managed boundaries without accounting for project membership and validation.
- Do not rewrite TODO or FIXME comments into ledger IDs unless the ledger files are updated in the same pass.
- Stop with `blocked` when the repo shape is too ambiguous to choose feature-first versus layer-first layout safely.
- Stop with `handoff` when project-file mutation or Xcode membership updates need guarded execution through `xcode-app-project-workflow`.

## Fallbacks and Handoffs

- If the repo lacks a clear formatter or linter baseline, hand off to `format-swift-sources` before any structural mutation.
- If a broad repo-wide cleanup is too risky, fall back to one feature directory or one oversized file at a time.
- If Xcode project integrity must be revalidated after file moves, hand off to `xcode-app-project-workflow`.
- Recommend `sync-xcode-project-guidance` or `sync-swift-package-guidance` when the request is really about durable repo rules rather than current-file cleanup.

## Customization

- This skill currently has no durable customization surface.
- Keep split thresholds, ledger names, and MARK conventions as workflow policy unless a real repeat customization need appears.

## References

### Workflow References

- `references/glossary.md`
- `references/layout-rules.md`
- `references/source-organization-rules.md`
- `references/todo-fixme-ledgers.md`

### Contract References

- `references/automation-prompts.md`

### Support References

- Recommend `format-swift-sources` first for formatter or linter setup and again after structural edits complete.
- Recommend `references/layout-rules.md` when the user needs the package-versus-app directory contract explained.

### Script Inventory

- `scripts/normalize_todo_fixme_ledgers.py`