Structure Swift Sources

Structure Swift Sources

Purpose

Use this skill as the top-level workflow for structural cleanup inside existing Swift components. It governs file splitting, file moves, section grouping, plain-language file headers, and TODO or FIXME ledger extraction. scripts/run-workflow.fsx classifies the cleanup, loads policy, and hands off only DocC content or Xcode-owned membership operations. It is not the formatter or linter integration authority, and it is not the DocC authoring authority.

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 high-signal // MARK: sections, declaration grouping, or view-modifier extraction in SwiftUI code.
• Use this skill when the user wants consistent block-comment file headers that describe a file's purpose and area of concern in plain terms.
• Use this skill when the user wants structured project-and-file banner headers with deterministic project, filename, copyright, and optional cross-reference fields.
• Use this skill when the user wants TODO or FIXME text moved out of source files into repo ledger files.
• 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 author-swift-docc-docs when the task becomes symbol documentation, DocC article work, landing-page structure, topic groups, or DocC-oriented review.
• Recommend swift-package-build-run-workflow or swift-package-testing-workflow when structural cleanup turns into ordinary package execution or SwiftPM validation.
• Recommend xcode-build-run-workflow when structural cleanup turns into active Xcode execution, scheme validation, file-membership follow-through, or guarded project mutation work.
• Recommend xcode-testing-workflow when structural cleanup turns into active Xcode test validation or test-target diagnosis.
• Recommend bootstrap-xcode-workspace --operation align for product guidance alignment. A deliberately standalone package uses its own explicit repository-maintenance contract.

Single-Path Workflow

Inputs

• cleanup_kind: one of the request classes above
• 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
• todo_fixme_mode: optional; use values such as report-only, rewrite-ledgers, or normalize-existing
• file_header_mode: optional; use values such as advisory or required
• file_header_style: optional; currently project-banner
• 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 the project-and-file banner header described in references/file-headers.md

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 cleanup kind
• path_type
  • primary: the documented structure path completed
  • fallback: a narrower safe pass was chosen
• output
  • cleanup_kind
  • recommended_path
  • layout_targets
  • split_targets
  • ledger_files
  • header_policy
  • helper_scripts
  • 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 treat file-header automation as permission to invent vague or generic purpose text. Header content must come from the actual code understanding or an explicit inventory.
• Do not make end users reverse-engineer the file-header inventory shape from prose or tests. Point them at references/file-header-inventory.template.yaml when --apply --inventory is the right path.
• Do not rewrite TODO or FIXME comments into ledger IDs unless the ledger files are updated in the same pass.
• Do not absorb symbol-doc or DocC-content work; hand that off to author-swift-docc-docs.
• Stop with blocked when the cleanup kind or target scope is too ambiguous to mutate safely.
• Stop with handoff when project-file mutation or Xcode membership updates need guarded execution through xcode-build-run-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 the request becomes symbol-doc or DocC-content work, hand off to author-swift-docc-docs.
• If Xcode project integrity must be revalidated after file moves, hand off to xcode-build-run-workflow.
• scripts/run-workflow.fsx is the top-level runtime entrypoint and converts component inspection plus request inference into the documented JSON contract.
• Recommend bootstrap-xcode-workspace --operation align when the request is really about durable product rules.

Fixed Policy

• scripts/run-workflow.fsx uses the managed header policy and fixed split thresholds.

References

Workflow References

• references/glossary.md
• references/layout-rules.md
• references/source-organization-rules.md
• references/file-headers.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/run-workflow.fsx
• scripts/normalize-swift-structure.fsx
• scripts/normalize-swift-structure.fsx
• references/file-header-inventory.template.yaml