Setup Swift Repository

This documentation was generated with the assistance of AI. Please report any inaccuracies.

End-to-end bootstrap for a Swift repository of either flavor — a SwiftPM library or a native Apple app. It collects the project’s identity and pipeline parameters once, resolves which flavor and branching model apply, and orchestrates six other skills in a fixed order so nothing is asked twice.

Purpose

iru-setup-swift-repository is the top-level entry point (standalone, or as the Swift/Apple branch of iru-setup-repository) for starting or catching up a Swift repository, whichever of its two flavors it is: a redistributable SwiftPM library, or a native iOS/iPadOS/macOS/watchOS/visionOS app generated from an XcodeGen or Tuist manifest, with SwiftUI or programmatic UIKit for its iOS/iPadOS target and an MVVM or MVC core (a macOS-only app is pointed to Setup macOS Repository instead). Rather than duplicating the flavor’s own scaffold logic, documentation scaffolding, .gitignore setup, CI/CD workflows, changelog bootstrapping, and README generation, it gathers the shared inputs — project identity (package name or app name/bundle-id prefix, license, developer name/email/organization URL), flavor-specific inputs (platforms, minimum deployment targets, generator, signing, and for an app ui/architecture), and pipeline parameters (branching model, integration/stable branch, macOS runner, open-source/visibility/publish/distribution/sonar, and the cost-aware CI choices ci, ci-tests and pages) — once, and passes each downstream skill only the args keys its own Step 0 accepts. It announces up front whether it is setting the repository up from scratch or updating an existing one (with an absent/present/partial inventory of every component it owns). It never skips the scaffold itself: every sub-skill warns about and asks Update / Keep as is / Replace for each pre-existing file it owns (or applies on-existing from args in scripted runs), and the final report states per component whether it was created, updated, replaced, kept as is, or skipped (ci: no). Because macOS runner minutes cost roughly 10x Linux minutes on private repositories, the CI questions are asked with visibility-aware cost guidance.

Purpose group

Swift/Apple Bootstrap

Plugin

Shipped by the iru-swift plugin of the ai-catalog marketplace (install with /plugin install iru-swift@ai-catalog; see Plugins).

Invocation

/iru-setup-swift-repository

Inputs

Argument Required Description Default

flavor

No

library (a SwiftPM package) or app (an XcodeGen/Tuist-generated native app). Detected from Package.swift/project.yml/Project.swift on disk when absent, else asked via AskUserQuestion.

Detected, else asked

branching

No

gitflow (integration + stable branch, sync.yml bumps the post-release version) or main-only (a single stable branch, no sync.yml).

gitflow, asked to confirm

mode

No

new or existing. Defaults to existing (confirmed) when the flavor’s scaffold manifest already exists at the repository root, otherwise new without asking. No longer decides what happens to individual files: any owned artifact already on disk is handled by its owning sub-skill’s Update / Keep as is / Replace question.

Detected, else new

package-name (library) / app-name + bundle-id-prefix (app)

Yes

Free-text project-identity fields specific to the resolved flavor, asked in Step 2 using exactly the key names the scaffold skill reads. Skipped entirely in mode: existing when the scaffold manifest is on disk (identity is read from it).

None

license, developer-name, developer-email, organization-url

Yes

Shared identity fields for both flavors, resolved once via AskUserQuestion for the license (Apache 2.0 recommended for library, MIT for app, No license, or Other) and plain conversation for the rest.

None — user must choose

platforms

Yes

Flavor-specific vocabulary: ios, ipados, macos, watchos, tvos, visionos, linux for library; ios, ipados, macos, watchos, visionos for app (tvOS refused). AskUserQuestion multi-select (visionOS as a follow-up), at least one required; an args-supplied list is not re-asked for an app, while a library still gets the tvOS/visionOS/Linux follow-up. A macOS-only app selection offers to switch to iru-setup-macos-repository — only when the user picked the platforms here, never when platforms arrived via args.

None

ui (app only)

No

swiftui (recommended) or uikit (programmatic UIKit with a scene delegate, no storyboards) for the iOS/iPadOS target; asked only when ios or ipados is selected. watchOS, visionOS and macOS targets stay SwiftUI. In mode: existing it is detected instead (Targets/iOS/Sources/SceneDelegate.swift or a UIWindowSceneDelegate with no SwiftUI App → uikit) and confirmed, or omitted so iru-setup-apple-app detects it.

Asked when ios/ipados selected (detected in mode: existing)

architecture (app only)

No

mvvm or mvc. ui: swiftui resolves to mvvm without asking; ui: uikit asks MVC (recommended) or MVVM. In mode: existing it is detected from Packages/Core/Sources/Core/Controllers/ (mvc) vs …/ViewModels/ (mvvm) and confirmed, or omitted for iru-setup-apple-app to detect.

mvvm for SwiftUI; asked for UIKit (detected in mode: existing)

min-deployment-targets (library) / min-deployment-target (app)

No

Per-platform OS versions for a library (no universal default, asked directly); for an app the iOS deployment target, which iru-setup-apple-app maps per platform (18.0 → macOS 15 / watchOS 11 / visionOS 2; identical numbers from 26 on), deliberately left for iru-setup-apple-app to resolve from local simulator runtimes unless supplied.

Asked (library) / resolved downstream (app)

generator (app only)

Yes

xcodegen (recommended for a single-target/platform app) or tuist (for a modular app), via AskUserQuestion.

None

signing (app only)

Yes

fastlane-match, api-key, or none, asked alongside distribution in Step 4.

none when distribution: none, else asked

integration-branch, stable-branch, runner

No

CI pipeline parameters consumed by iru-setup-swift-github-workflows. Integration branch skipped entirely for main-only. For an app, xcode-27 (preview image, with xcode-version: 27.1, the Xcode the scaffold was verified with) is offered next to the GA macos-26 runner.

develop, main, macos-26

open-source, publish (library), distribution (app), sonar (+ detail keys)

No

Shared open-source-driven pipeline vocabulary, resolved via AskUserQuestion with open-source-dependent recommended defaults; passed through unchanged to Steps 5 and 8. sonar: cloud is recommended only for a public open-source repository (SonarCloud needs a paid plan for private projects); with ci: no it recommends none.

publish/distribution default yes/store when open source; sonar defaults cloud when open source and public, otherwise asked with none recommended

visibility

No

public, private or internal (behaves like private for every cost decision). Taken from args, else detected with gh repo view --json visibility, else asked (Public recommended when open source). Warns when an open-source project is private/internal.

Detected, else asked

ci

No

yes/no — whether GitHub Actions workflows are generated at all. Asked with the cost facts (free on public repositories; included minutes on private ones; macOS minutes about 10x Linux). no skips Step 8 entirely (no workflows, security.yml, Dependabot config or sync_versions.py) and ci-tests/pages are not asked.

yes recommended for public; asked for private

ci-tests

No

unit (unit-test targets only; UI-test bundles/integration targets stay local) or full (adds UI tests). Only meaningful when ci: yes.

full recommended for public, unit for private/internal

pages

No

yes/no — deploy the DocC + Antora site to GitHub Pages, or only upload it as a workflow artifact. Only meaningful when ci: yes. Defaulted to yes without asking for public repositories; private asks with no recommended (Pages on private repos needs a paid plan and the site is public).

yes public; asked for private

accessibility

No

enforce, report, off or none — app flavor only (ignored for library): the level of the UI tests' automated accessibility checks (performAccessibilityAudit()), written by iru-setup-apple-app to .ui-quality.yml. Asked in Step 4 ("Support accessibility and assistive technologies?") with Enforce recommended; none opts out entirely (no accessibility rules, checks or docs) and, in mode: existing, is pre-selected from iru-explore’s `Accessibility: line. Forwarded to the scaffold skill. See Building user interfaces.

Asked for app

on-existing

No

ask/keep/update/replace — how every sub-skill treats prior setup it finds. Never asked here; forwarded to the sub-skills only when supplied via args.

ask (each sub-skill asks)

xcode-version, release-please, formatter, package-resolved, security-* opt-outs

No

Pass-through toggles never asked by this orchestrator — each downstream skill resolves or asks its own default when the key isn’t supplied.

Resolved downstream

Outputs

  • A "Setup mode" announcement (from scratch vs. updating, with a component inventory) before any question.

  • The flavor’s own scaffold: Package.swift + Sources//Tests/ (via iru-setup-swift-library), or the generator manifest + Packages/Core + Targets/ + fastlane/Fastfile (via iru-setup-apple-app) — always invoked; the scaffold skill decides per existing file whether to update, keep or replace it.

  • For the app flavor, .ui-quality.yml at the repository root (reported by the scaffold with the chosen accessibility level); the scaffold’s UI tests capture the sample screen into the gitignored .ui-screenshots/, which CI uploads as a 7-day artifact.

  • A scaffolded Antora documentation site under docs/ (via iru-setup-antora).

  • A root .gitignore covering .build/, DerivedData/, .xcresult, generated .xcodeproj/*.xcworkspace, signing material, and the Antora build output (via iru-setup-swift-gitignore).

  • build.yml/release.yml (+ sync.yml and .github/scripts/sync_versions.py for gitflow), security.yml, and .github/dependabot.yml (via iru-setup-swift-github-workflows) — all skipped when ci: no.

  • A root CHANGELOG.md backfilled from git tag/GitHub Release history (via iru-setup-changelog).

  • A root README.md with badges, a project-status table, documentation links, and installation instructions (via iru-setup-readme).

  • A final report summarizing the resolved flavor/branching/mode, identity/license/pipeline parameters (visibility, ci, ci-tests, pages included), a per-component table of whether each was created, updated, replaced, kept as is (with any listed mismatches) or skipped (ci: no), the Sonar coverage conversion (lcov_to_sonar_generic.py for both flavors), the consolidated required-secrets/settings table (including APPLE_TEAM_ID for a distributed app), every decision made on the user’s behalf, and explicit warnings to review every generated file before building, committing, or relying on CI.

Execution flow

flowchart TD A[Start /iru-setup-swift-repository] --> B["Step 0: Parse args\n(key: value lines)"] B --> C["Step 1: Resolve flavor,\nbranching and mode;\nprint Setup mode announcement\n(from scratch or update + inventory)"] C --> D{"mode existing and\nscaffold manifest on disk?"} D -- yes --> D1["Step 2: Skip identity questions\n(read from manifest)"] D -- no --> D2["Step 2: Collect project identity\n(package-name or app-name/bundle-id,\nlicense, developer info)"] D1 --> E D2 --> E["Step 3: Collect flavor-specific inputs\n(platforms, min-deployment-target(s),\ngenerator for app; visionOS follow-up)"] E --> E2{"app with macOS only?"} E2 -- "yes, platforms\nasked here" --> E3["Offer to switch to\niru-setup-macos-repository"] E2 -- "no, or platforms\nfrom args" --> E4["app: ui swiftui/uikit (iOS/iPadOS only) and\narchitecture; detected + confirmed in\nmode existing, else asked (swiftui means\nmvvm, uikit asks mvc/mvvm)"] E3 -- "declined" --> E4 E4 --> F["Step 4: Collect shared pipeline parameters\n(branches, runner, open-source, visibility,\npublish/distribution, signing, ci, sonar,\nci-tests, pages, accessibility for app)"] F --> I["Step 5: Run flavor's scaffold skill\n(iru-setup-swift-library or\niru-setup-apple-app, via sub-agent;\nasks Update / Keep / Replace per file)"] I -- "user chose stop,\nno manifest on disk" --> J[Stop entire pipeline; report] I -- "ok, or stop but\nmanifest exists" --> K["Step 6: Run setup-antora\n(documentation site, via sub-agent)"] K --> L["Step 7: Run setup-swift-gitignore\n(root .gitignore, via sub-agent)"] L --> M{"Step 8: ci is no?"} M -- yes --> M1["Skip workflows entirely;\nrecord skipped (ci: no)"] M -- no --> M2["Run setup-swift-github-workflows\n(CI/CD + security workflows, via sub-agent)"] M2 -- "workflows existed,\nuser chose stop" --> N["Note in report;\nSteps 5-7 still valid"] M2 -- ok --> O N --> O M1 --> O["Step 9: Run setup-changelog\n(root CHANGELOG.md, via sub-agent)"] O --> P["Step 10: Run setup-readme\n(root README.md, via sub-agent)"] P --> Q["Step 11: Report per-component outcome,\nsecrets table, decisions and warnings"]

Dependencies

Invokes

Each of the following is invoked via the iru-isolated-skill-executor agent rather than a direct Skill call — every sub-skill re-derives what it needs straight from the filesystem this orchestrator has just written to, so only a short completion summary needs to come back, keeping each sub-skill’s own exploration/file reads (and the two scaffold skills' very long template listings) out of this orchestrator’s own context. Every sub-agent runs with run_in_background: false since each step depends on the previous one’s files being on disk:

  • Setup Swift Library — Step 5, flavor: library: writes Package.swift and the source folders, passing Steps 2–4’s answers (package-name, platforms, min-deployment-targets, license, developer fields, open-source, publish, sonar + detail keys, formatter if supplied, visibility, ci, on-existing if supplied, mode) as args. Always invoked, even when Package.swift already exists.

  • Setup Apple App — Step 5, flavor: app: writes the generator manifest, Packages/Core, per-platform Targets/, and an optional signing/distribution-gated fastlane/Fastfile, passing the app-specific identity (app-name, bundle-id-prefix), platforms, generator, ui, architecture, distribution, signing, min-deployment-target if supplied, license, developer fields, open-source, sonar + detail keys, visibility, ci, on-existing if supplied, and mode as args. Always invoked, even when the generator manifest already exists.

  • Setup Antora — Step 6: scaffolds the Antora documentation site, invoked with no args (only on-existing when supplied) since it derives the component name/title/version directly from the manifest Step 5 just wrote (or an initial 1.0.0 if no tags/releases exist yet). Run before Step 8 so that skill’s own docs-site check finds everything in place.

  • Setup Swift Gitignore — Step 7: writes or updates the root .gitignore, passing flavor (so its Package.resolved recommendation matches the project shape) and package-resolved only if supplied, plus on-existing if supplied; mode is deliberately not passed since the skill’s own .gitignore-presence check is the more precise signal.

  • Setup Swift GitHub Workflows — Step 8, skipped entirely when ci: no: writes the CI/CD + security workflows, passing flavor, platforms, branching, integration-branch (gitflow only), stable-branch, runner, xcode-version if supplied, generator/signing (app only), release-please if supplied (library only), open-source, publish/distribution, sonar + detail keys, visibility, ci-tests, pages, security-* if supplied, on-existing if supplied, and mode as args.

  • Setup Changelog — Step 9: bootstraps the root CHANGELOG.md, invoked with no args (only on-existing when supplied) since it works from the repository’s own git tag/GitHub Release history; position relative to Steps 5–8 doesn’t matter functionally.

  • Setup Readme — Step 10, last: bootstraps the root README.md, passing sonar, ci, pages (only when ci: yes) and on-existing if supplied, and otherwise exploring the finished state left by every earlier step.

Invoked by

  • Setup Repository — Step 4, Swift library/Apple app bootstrap, via the iru-isolated-skill-executor agent; it asks its own visionOS follow-up and passes platforms in args, which this skill then doesn’t re-ask for an app.

Related agents

  • iru-isolated-skill-executor — spawned once per sub-skill (Steps 5–10), so all six sub-skills' own exploration/file-read transcripts don’t accumulate in this orchestrator’s context over the course of a single bootstrap run.

Source

SKILL.md on GitHub — the file this page was generated from.