Swift Code One Task

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

Carry out a single task’s implementation, tests, and checkbox update against the real codebase — nothing else. This is the narrowest execution unit in the iru-code pipeline: iru-swift-code-one-task-group calls it once per task in a bucket (potentially many at once, in parallel agents via iru-isolated-skill-executor).

Purpose

iru-swift-code-one-task is the Swift-specific implementation worker iru-swift-code-one-task-group calls once per task. Given one task’s own text (what to build, its exact implementation_plan.md checkbox line(s), and any sub-tasks), it first detects the repository’s Swift project shape and the target the task belongs to, loads only the matching guidance from its own bundled reference/ directory, re-checks the current code state, implements exactly what’s specified, and writes/updates tests. If the task didn’t stop on a blocker, it compile-checks the touched target, then immediately checks off that task’s own checkbox (and its sub-tasks') in implementation_plan.md with a "group validation pending" note, before reporting back — so an interrupted run doesn’t re-attempt work that already landed. License headers, DocC audits, the full test suite, coverage, and code-quality checks all happen once per bucket in iru-swift-code-one-task-group, not here. It uses a medium model on purpose: the plan already carries the hard reasoning, so this skill only executes one task’s implementation against code agreements that live in reference/ rather than being re-derived per task.

For a task that adds or changes a screen, component or list in an app it also applies the catalog’s UI contract (see Building user interfaces): it writes the Screen > Region > Component decomposition first, builds leaves first with value-type state plus closures and virtualized collections over keyed view-model state, and writes the UI tests that capture every .ui-quality.yml direction x theme combination and run the accessibility audit. A command-line tool has no UI, so none of this applies there.

Package-vs-app shape and target detection

Before reading anything, Step 1 works out which of two shapes the repository is:

  • A plain Swift Package — a Package.swift at or near the root with no .xcodeproj/generator manifest alongside it. Code lives under Sources/<Target>/ and Tests/<Target>Tests/, one pair per Package.swift target. A command-line tool is a plain package whose Package.swift declares an .executableTarget depending on ArgumentParser (reported by iru-explore as Project type: cli-tool (swift)). In the iru-setup-swift-cli layout the logic lives in a Sources/<Bin>Kit/ library, Sources/<Bin>/ holds thin swift-argument-parser commands, and the tests are Tests/<Bin>KitTests/ (in-process) plus Tests/<Bin>CLITests/ (runs the built binary).

  • An Apple app project — an .xcodeproj exists or is generated, via project.yml (XcodeGen), Project.swift (Tuist), or, with neither manifest, a hand-maintained *.xcodeproj whose project.pbxproj is the source of truth. An app project frequently also has a local Packages/Core package holding testable logic behind thin, per-platform UI targets.

For an app project it also detects, once from the repository:

  • The layout and the touched target’s platform — App/Sources/ with a single macOS app target is the iru-setup-macos-app layout (a macOS-only desktop app, compile-checked with platform=macOS, no simulator); Targets/<Platform>/Sources/ is the iru-setup-apple-app multiplatform layout, where the folder names the target (Targets/iOS/ covers iPhone and iPad, plus Targets/macOS/, Targets/watchOS/, Targets/visionOS/). The platform is confirmed against the manifest (XcodeGen platform:/supportedDestinations:, Tuist destinations:) or the target’s SDKROOT. iPadOS is an iOS target whose destinations include iPad; a visionOS destination on an iOS target, or a standalone xros target, is visionOS.

  • The UI framework of the touched target — swiftui (a @main struct …​: App with some Scene), uikit (a UIApplicationDelegate/UIWindowSceneDelegate with UIViewController subclasses and no SwiftUI App) or appkit (an NSApplicationDelegate with NSWindowController/NSViewController subclasses). Hosted content in the other framework doesn’t change the answer; visionOS and watchOS targets are SwiftUI.

  • The architecture from the layout contract (Packages/Core/Sources/Core/ViewModels/ → MVVM, …​/Controllers/ → MVC; neither → MV for SwiftUI, MVC for UIKit/AppKit; both → decided per target, UIKit/AppKit targets in Controllers/ and SwiftUI targets in ViewModels/, the scaffolded UIKit-MVC + SwiftUI-platforms mix). SwiftUI uses MVVM or MV, UIKit/AppKit MVC or MVVM; a task never switches it. The 80% coverage bar covers Packages/Core only; the app targets are "not measured".

Logic an app task adds goes to Packages/Core (Foundation + Observation only, no SwiftUI/UIKit/AppKit import) in the detected architecture’s folder; only views, view controllers, window/scene controllers, menus/commands, the composition root (App, AppDelegate, SceneDelegate), background-task/notification registration, and protocol implementations that must touch a UI or platform framework belong in the app target.

In a command-line tool, logic, output and errors go to <Bin>Kit; a new subcommand’s thin struct (flags, command metadata and one call into the Kit) goes to Sources/<Bin>/ and is registered in the root’s subcommands:.

It then works out which target the task’s file paths or description name — a path under Sources/<Target>/ or Packages/Core/Sources/<Target>/ names that target directly; a path under a per-platform app target directory (read from the manifest’s targets:/Target(…​) list rather than guessed) names that target; otherwise the skill infers from the described behavior (reusable logic with no UI import vs. a SwiftUI/UIKit/AppKit view for one platform), defaulting to the package’s main target (or Packages/Core) when genuinely ambiguous. This package/app choice, plus the target, decides both which reference/ files apply and Step 5’s compile-check command (swift build --build-tests vs. xcodebuild build-for-testing -scheme <AppName>-<Platform> with -destination 'generic/platform=<P> Simulator' for an iOS/iPadOS, watchOS or visionOS target, or platform=macOS for a macOS one). The generic destination needs no installed simulator runtime, so a missing visionOS runtime never makes the compile-check "unavailable".

The bundled reference library

This skill ships a reference/ directory alongside its SKILL.md, holding this catalog’s general Swift 6 code agreements. It is read by progressive disclosure: reference/README.md routes to the rest, reference/code-style.md is always read, and the others only when the task’s shape calls for them.

File Read when Covers

code-style.md

Always

Swift 6 strict concurrency (Sendable, actors, @MainActor, structured concurrency, nonisolated, avoiding @unchecked Sendable), value types first, guard early exits, access control (public/package/internal), typed throws with enum: Error error types, naming per the Swift API Design Guidelines, and member ordering (// MARK: sections).

docc.md

The task adds or changes a type, or any public/package/internal member

DocC documentation comment conventions.

testing.md

The task writes or updates tests — nearly every task

Swift Testing/XCTest conventions: Swift Testing by default, XCTest only for XCUITest and measure; logic tests in Packages/Core with fake services and passive views; macOS XCUITest on the real desktop session; iOS/iPadOS/visionOS XCUITest on a simulator (--uitesting launch arguments, accessibility identifiers, SpringBoard permission alerts, performAccessibilityAudit).

swiftui.md

The task adds or changes a SwiftUI View or view model

SwiftUI view composition conventions, plus pointers to macos.md, ios.md, visionos.md and architecture.md for platform scenes and view-model placement.

architecture.md

The task adds or changes a view model, an MVC controller or its view protocol, a service protocol/test double, or decides whether logic goes in Packages/Core or the app target — every app task (macOS, iOS/iPadOS, visionOS) not confined to one existing function

Layout/platform detection table, MVVM vs. MVC contract, the UI-free Packages/Core boundary, fakes and passive views for testing.

macos.md

The task touches a macOS app target: scenes/windows, menus/commands/shortcuts, Settings, MenuBarExtra, file access (panels, sandbox, security-scoped bookmarks), entitlements/hardened runtime

Mac-only scene, menu, file-access and sandbox conventions.

appkit.md

The task adds or changes AppKit code: NSWindowController/NSViewController/NSView, target-action, delegates/data sources, NSMenu, Auto Layout in code, AppKit MVVM via Observation tracking, NSHostingView

AppKit conventions for macOS apps.

ios.md

The task touches an iOS/iPadOS app target: scenePhase/lifecycle, background tasks, notifications, permission prompts, the privacy manifest, widgets/App Intents, iPad windows/menu bar/pointer/keyboard, size classes, Dynamic Type, Keychain secrets

iOS/iPadOS conventions: suspension model, BGTaskScheduler/background URLSession, Info.plist usage-description keys, PrivacyInfo.xcprivacy required-reason APIs, accessibility.

uikit.md

The task adds or changes UIKit code: app/scene delegates, UIViewController/UIView, Auto Layout in code, navigation/tab/split containers, diffable collection views, traits, UIKit MVVM via Observation tracking, UIHostingController interop

Programmatic scene-based UIKit conventions, diffable data sources with compositional layout, UIAction, MVC over a UI-free Core controller and MVVM via Observation tracking (updateProperties() on iOS 26+, UIObservationTrackingEnabled on iOS 18).

visionos.md

The task touches a visionOS target or destination: windows, volumes, immersive spaces, ornaments, hover effects, RealityView/Model3D

SwiftUI-only visionOS conventions: ImmersiveSpace/openImmersiveSpace, ornaments, hover effects, RealityView basics.

cli.md

The package is a command-line tool and the task adds or changes a command, flag, output, error/exit code, prompt, signal/cleanup, child process or the CLI tests

Where code goes (<Bin>Kit vs thin commands), swift-argument-parser patterns, implementing the contract in a new command, testing the executable, Linux portability.

cli-contract.md

With cli.md, whenever a CLI task changes what a caller observes: stdout/stderr, exit codes, --format/JSON, colour, prompts, --dry-run/--yes, schema/help

The catalog’s shared, language-agnostic CLI contract (streams, exit codes, TTY/colour, machine output, safety and idempotency, configuration, self-description, startup).

ui-contract.md

The task adds or changes a screen, component, list or other UI (any UI framework)

The catalog-wide UI rules: decomposition, composition, inputs/events, virtualized collections, UI tests, screenshots and accessibility.

ui-implementation.md

With ui-contract.md, always for UI tasks; never for a command-line tool

The contract mapped onto SwiftUI/UIKit/AppKit, XCUITest and the shared UIScreenshots.swift helper.

package-api.md

The task changes a public declaration in a library package’s target

Semver-stable package API conventions, availability, Package.swift hygiene.

app-structure.md

The task adds a new app target, touches the generator manifest, or wires shared logic between Packages/Core and a platform target

Per-platform app structure conventions.

A new screen in a SwiftUI macOS app reads architecture.md + macos.md + swiftui.md; one in an AppKit app reads architecture.md + macos.md + appkit.md (plus swiftui.md only when it hosts SwiftUI content). A new screen in a SwiftUI iOS app reads architecture.md + ios.md + swiftui.md; in a UIKit iOS app architecture.md + ios.md + uikit.md (plus swiftui.md only when it hosts SwiftUI); a visionOS scene reads architecture.md + visionos.md + swiftui.md. A new command in a command-line tool reads cli.md + cli-contract.md + testing.md (and docc.md for its Kit types), never the app files.

Every file states the same override: the rules are the default for new code, and a file that consistently does something else wins — the divergence is reported in Step 8 rather than silently restyled. If reference/ is missing entirely, the skill falls back to this repository’s own CLAUDE.md conventions and the surrounding code’s style, and says so in its report.

Purpose group

Swift Development Tooling

Plugin

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

Invocation

/iru-swift-code-one-task <task description>

Inputs

Argument Required Description Default

task description

Yes

The task’s full text as written in implementation_plan.md — what to build, the named file(s)/type(s)/ function(s), the described behavior, its exact implementation_plan.md checkbox line(s) for itself and its sub-tasks, and any sub-tasks, plus any relevant "Current code state" context. Normally supplied by iru-swift-code-one-task-group dispatching one task in a bucket at a time.

None — this skill has nothing to do without a task description.

reference/

No

The skill’s own bundled reference directory (README.md, code-style.md, docc.md, testing.md, swiftui.md, package-api.md, app-structure.md, architecture.md, macos.md, appkit.md, ios.md, uikit.md, visionos.md, cli.md, cli-contract.md, ui-contract.md, ui-implementation.md). If missing, the skill falls back to CLAUDE.md and the surrounding code’s style, and says so in its report rather than guessing at what the reference would have said.

Bundled with the skill

Outputs

  • Source and test files created/modified per the task, following the bundled reference/ agreements — strict-concurrency-clean Swift 6, value types first, narrow access control, typed throws, // MARK:-grouped member order, full DocC on public/package members — plus this repository’s own CLAUDE.md conventions where they are more specific, and the surrounding file’s existing style wherever it consistently differs.

  • Swift Testing (or XCTest where warranted) tests added/updated covering the new/changed behavior, including a case per documented - Throws: — not run by this skill; the caller runs the suite once for the whole bucket.

  • For a UI task: component tests per visual state capturing each .ui-quality.yml direction x theme (UIScreenshots.render/capture), screen/flow XCUITests with --fixture data and captures, and the screen’s performAccessibilityAudit() test honouring the configured level; the shared UIScreenshots.swift helper is added to the test target when missing. Captures land under .ui-screenshots/<kind>/<Id>/<state>--<direction>--<theme>.png when the group’s UI stage runs them.

  • A compile-check of the touched target (swift build --build-tests — also for a command-line tool, or xcodebuild build-for-testing against platform=macOS or a generic generic/platform=<P> Simulator destination for iOS/visionOS/watchOS, after regenerating the project if the manifest changed) — passed, fixed, found unrelated to this task, or reported unavailable.

  • implementation_plan.md with this task’s own checkbox (and its sub-tasks') checked off and a "group validation pending" note, written immediately once the task finishes cleanly — before this skill reports back. Left untouched if the task stopped on a blocker.

  • A short summary handed back to the caller: project shape and target detected (plus, for an app, the layout, the target’s platform — macOS / iOS-iPadOS / visionOS —, its UI framework and the architecture), reference file(s) read, file(s) touched, tests added/updated, compile-check result, for a UI task the decomposition (one line per component: inputs, events, new or reused) and the UI tests and screenshot paths added, whether the run stopped on a blocker, and any deliberate deviation from reference/.

Execution flow

flowchart TD A["Start /iru-swift-code-one-task\n(task description)"] --> B["Step 1: detect package vs. app shape\nand target (app: layout, platform macOS/iOS/\nvisionOS, SwiftUI/UIKit/AppKit, MVVM/MVC);\nread only needed reference/ files"] B -- "reference/ missing" --> B2["Fall back to CLAUDE.md +\nsurrounding style; report it"] B2 --> C B --> C["Step 2: re-check current code state;\nnote existing concurrency/access/ordering style"] C --> D["Step 3: implement exactly what the task\nspecifies (concurrency, access control, DocC, order;\nUI task: write the decomposition first)"] D --> E["Step 4: write/update Swift Testing/XCTest\ntests (UI task: capture and accessibility\ntests too; not run here)"] E --> F["Step 5: compile-check the touched target\n(swift build / xcodebuild build-for-testing)"] F -- "fails on this task's own code" --> F2["Fix it"] F2 --> G F -- "fails outside task scope,\nor unavailable" --> F3["Note it; don't fix unrelated code"] F3 --> G F -- "passes" --> G{"Step 6: ambiguous, infeasible,\nor genuinely ambiguous shape?"} G -- yes --> H["Stop; leave checkbox\nunchecked; report blocker to caller"] G -- no --> I["Step 7: check off this task's\ncheckbox + 'validation pending' note"] I --> J["Step 8: report outcome to caller:\nshape/target, files, tests, compile result, deviations"]

A conflict between reference/ and the surrounding code is deliberately not a stop condition — the skill follows the surrounding code and reports the divergence in Step 8.

Dependencies

Invokes

None — iru-swift-code-one-task is a leaf skill; it does not call any other skill in this catalog. It reads its own reference/ directory and edits the code and test files the task names. License headers, DocC audits, the full test suite, coverage, and quality checks all happen once per bucket in iru-swift-code-one-task-group.

Invoked by

  • Swift Code One Task Group — Step 2, once per task in a bucket (concurrently, in a single batch of Agent calls, when the group is marked Parallelizable: yes; one at a time otherwise), via the iru-isolated-skill-executor agent, passing that task’s full text including its exact checkbox line(s). That caller re-reads implementation_plan.md afterward to confirm the checkbox this skill already flipped landed, then replaces the "pending" note with the final validation outcome once the whole bucket’s validation passes.

Related agents

iru-swift-code-one-task itself does not spawn any Agent — it only reads its reference/ files and edits the code/test files the task names.

Source

SKILL.md on GitHub — the file this page was generated from. The bundled Swift code agreements live alongside it under reference/.