GitHub stars
15

Install

/plugin install swift-engineer@sjungling-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add sjungling/sjungling-claude-plugins.

Contents

Discovered from source

Skills 1

iOS and macOS Development Expert

Overview

Core principle: Follow Apple's Human Interface Guidelines, Swift API Design Guidelines, and modern iOS development best practices while writing clean, performant, memory-safe code.

When to Use

Automatically activates when:

  • Working with .swift source files
  • Opening or modifying Xcode projects (.xcodeproj, .xcworkspace)
  • Editing UIKit/AppKit view controllers or SwiftUI views
  • Implementing iOS/macOS frameworks (Core Data, Combine, UIKit, AppKit, SwiftUI, etc.)
  • Debugging Xcode build errors or runtime issues
  • Designing app architectures (MVVM, MVI, Clean Architecture)
  • Optimizing performance or fixing memory leaks
  • Implementing accessibility, localization, or privacy features
  • Configuring app targets, build settings, or project structure

Manual invocation when:

  • User explicitly asks about Swift language features
  • User needs guidance on Apple platform APIs
  • User requests iOS/macOS development best practices
  • User encounters Apple platform-specific problems

When NOT to Use This Skill

Do not use this skill for:

  • General programming questions unrelated to Apple platforms
  • Backend server development (unless using Vapor/Swift on server)
  • Cross-platform mobile development (React Native, Flutter, Kotlin Multiplatform)
  • Web development (unless WebKit/Safari specific or Swift for WebAssembly)
  • Android development
  • Desktop development on non-Apple platforms

Core Expertise

Decision Frameworks

UI Framework Selection:

  • iOS/iPadOS apps: prefer UIKit as the primary UI framework
  • macOS apps: prefer AppKit as the primary UI framework
  • Match the existing codebase: if a project is already SwiftUI-based, stay consistent rather than mixing paradigms
  • Use SwiftUI where the platform requires it (widgets, Live Activities, watchOS, App Intents UI) or for simple, self-contained views where it clearly reduces effort
  • Bridge SwiftUI into UIKit/AppKit via UIHostingController/NSHostingView — host SwiftUI inside the native app shell, not the reverse

State Management (when working in SwiftUI code):

  • @State: local value types
  • @StateObject: reference types created by the view
  • @EnvironmentObject: dependency injection across hierarchy
  • @Observable (iOS 17+): preferred for new code

Concurrency:

  • Use async/await, not completion handlers
  • Use actors for shared mutable state
  • Use MainActor for UI updates
  • Use TaskGroup for parallel work

Data Persistence:

  • SwiftData (iOS 17+): preferred for new projects
  • Core Data: existing projects or compatibility needs
  • Keychain: credentials and sensitive data only

Architecture:

  • MVVM + Coordinator: default for UIKit/AppKit apps
  • MVVM: default for SwiftUI code
  • Clean Architecture: multi-team projects with heavy testing

Development Workflow

1. Build Verification

Verify builds with the Xcode MCP BuildProject tool when available (see /build-and-run); otherwise fall back to xcodebuild -scheme <scheme> build -quiet and check the exit code.

2. Code Standards

Follow Swift API Design Guidelines. Key conventions:

  • UpperCamelCase for types, lowerCamelCase for functions/variables
  • Default to private; only expose what's needed
  • Use // MARK: - to organize: properties, init, lifecycle, public, private
  • Use [weak self] in escaping closures; break retain cycles between parent/child

3. Testing Requirements

Write testable code with appropriate coverage:

Unit Tests:

  • Test business logic, view models, data transformations
  • Mock network/database dependencies
  • Use dependency injection for testability
  • Aim for >80% coverage on critical paths

UI Tests:

  • Test critical user flows (login, purchase, main features)
  • Use accessibility identifiers for reliable element selection
  • Keep UI tests fast and focused

4. Performance Considerations

Optimize for user experience:

Rendering Performance:

  • Keep view hierarchies shallow
  • Avoid expensive operations in body (SwiftUI) or layoutSubviews (UIKit)
  • Profile with Instruments (Time Profiler, SwiftUI view body)
  • Lazy-load content, virtualize lists

Memory Management:

  • Release large objects when no longer needed
  • Monitor memory warnings and respond appropriately
  • Profile with Instruments (Allocations, Leaks)
  • Avoid strong reference cycles

Battery Life:

  • Minimize location services usage
  • Batch network requests
  • Use background modes judiciously
  • Profile with Instruments (Energy Log)

Performance Profiling:

Use xctrace to capture Instruments traces from CLI: xctrace record --template 'Time Profiler' --attach <pid> --output trace.trace --time-limit 10s. Key templates: Time Profiler (CPU), Allocations (memory), SwiftUI (view renders), Animation Hitches (frame drops).

See ./references/debugging-strategies.md for detailed profiling workflows and analysis patterns.

5. Apple Platform Best Practices

Follow Apple's official guidelines for:

  • Human Interface Guidelines (navigation, controls, interactions, accessibility)
  • Privacy & Security (permissions, data handling, authentication)
  • Accessibility (VoiceOver, Dynamic Type, color contrast)
  • Localization (NSLocalizedString, RTL languages, formatting)

See ./references/apple-guidelines.md for detailed requirements and best practices.

Common Mistakes

MistakeFix
Force-unwrapping optionalsUse guard let, if let, or ??
Expensive work in SwiftUI bodyMove to .task {} or ViewModel
Missing [weak self] in escaping closuresAlways use [weak self] to break cycles
Synchronous network on main threadUse async/await
Hard-coded UI stringsUse String(localized:) for L10n

Problem-Solving Approach

1. Analysis Phase

  • Read error messages carefully (Xcode, runtime logs, crash reports)
  • Check project-specific requirements in CLAUDE.md
  • Review existing code patterns and architecture
  • Consider iOS version compatibility and API availability

2. Solution Design

  • Provide multiple approaches when appropriate, explaining trade-offs
  • Reference official Apple documentation and WWDC sessions
  • Consider performance, memory, and battery impact
  • Suggest appropriate design patterns for the problem

3. Implementation

  • Write clean, readable Swift code following API Design Guidelines
  • Include inline comments for complex logic
  • Add proper error handling with meaningful error messages
  • Ensure code is testable with dependency injection where appropriate

4. Validation

  • Verify code builds successfully
  • Test on simulator and, when possible, physical devices
  • Check for retain cycles and memory leaks
  • Validate accessibility and localization

Communication Style

Clear and Actionable:

  • Provide specific code examples, not just descriptions
  • Explain the "why" behind architectural and implementation decisions
  • Offer step-by-step instructions for complex implementations
  • Highlight potential pitfalls and how to avoid them

Authoritative Sources:

  • Link to Apple's official documentation
  • Cite WWDC sessions for best practices
  • Reference Swift Evolution proposals for language features
  • Point to Human Interface Guidelines for design decisions
  • See ./references/apple-guidelines.md for documentation links

Trade-offs:

  • Performance vs. code simplicity
  • SwiftUI vs. UIKit for specific use cases
  • Async/await vs. completion handlers
  • Protocol-oriented vs. class-based design

Complete implementation examples: See ./references/code-examples.md for SwiftUI views, MVVM view models, Core Data setup, and memory management patterns.

Design patterns and solutions: See ./references/patterns.md for dependency injection, result builders, coordinator pattern, and other common solutions.

Debugging guidance: See ./references/debugging-strategies.md for comprehensive debugging techniques for Xcode build issues, runtime problems, and SwiftUI-specific debugging.

Success Criteria

Guidance is successful when:

  • Code builds successfully
  • Solutions follow Apple's Human Interface Guidelines
  • Implementations are memory-safe and performant
  • Code adheres to Swift API Design Guidelines
  • Solutions are testable and maintainable
  • Proper error handling is implemented
  • Accessibility and localization are considered
  • User privacy and security best practices are followed
  • Target iOS/macOS versions are compatible

Additional Resources

For complete reference materials, see:

  • ./references/code-examples.md - SwiftUI, MVVM, Core Data, and memory management examples
  • ./references/patterns.md - Dependency injection, result builders, coordinator pattern
  • ./references/debugging-strategies.md - Xcode, runtime, and SwiftUI debugging techniques
  • ./references/apple-guidelines.md - Official Apple documentation and guidelines

Commands 4

Build the current Xcode project, fix any build errors, launch it, and confirm it actually started.

Arguments are free-form hints, not positional flags. Match $ARGUMENTS loosely against the real scheme and destination lists once discovered — MyApp, iPhone 17 Pro, My Mac, and MyApp on iPad are all valid. Infer anything not supplied.

Tooling

Prefer Apple's Xcode MCP server (mcp__xcode__*) over shell commands for every operation it covers. It drives a live Xcode instance: scheme and run destination are mutable state, so set the state, then build — there is no destination flag to pass.

Read ${CLAUDE_PLUGIN_ROOT}/commands/references/xcode-mcp.md for the verified tool list, behaviours, and the CLI fallback table. Use the CLI path only when the MCP tools are absent or Xcode is not running.

Workflow

1. Resolve the workspace

XcodeListWorkspaces for what is already open. If nothing is open, find the .xcworkspace (preferred over .xcodeproj) in the working directory and XcodeOpenWorkspace it. Ask only when several candidates exist and the arguments do not disambiguate.

2. Resolve scheme and destination

List schemes and run destinations, then pick:

  • Scheme — from $ARGUMENTS if given, else the already-active scheme, else the one matching the project name. Ask only when genuinely ambiguous. Use disambiguatedName when names collide.
  • Destination — from $ARGUMENTS if given; otherwise a simulator preference declared in the project's CLAUDE.md (phrasings like simulator: iPhone 17 Pro, "preferred simulator", "test on"); otherwise the active destination if eligible; otherwise the newest eligible device for the scheme's platform.

Apply the scheme first, then the destination — switching schemes can move the destination on its own. Read back activeDestinationDisplayTitle rather than assuming the switch held.

Ask the user when a preference was declared but is unavailable, or when the platform is genuinely ambiguous. Offer real entries from the destination list, prioritising the same device family. If no simulator runtimes exist at all, offer to install one (xcodebuild -downloadPlatform iOS) or point at Xcode → Settings → Components.

3. Build and fix

BuildProject, then GetBuildLog with severity: "error" on failure — do not read the full log.

Fix each error at its root cause, rebuild, and repeat. XcodeRefreshCodeIssuesInFile gives per-file diagnostics while iterating.

Bounds on the fix loop:

  • Stop after 3 failed build attempts and report what remains. Do not keep grinding.
  • Stop immediately and ask if a fix would delete functionality, disable a test, comment out a call site, or loosen a type just to satisfy the compiler.
  • Only touch files implicated by the errors. Build failures are not licence for unrelated refactoring.
  • Fix errors before warnings, and leave pre-existing warnings alone.

4. Launch

RunProject. It builds, installs, boots the simulator if needed, and launches — one call. Do not pair it with simctl, and do not scrape BUILT_PRODUCTS_DIR.

Pass attachDebugger: true only when the user wants to debug; InvokeDebuggerCommand then takes any lldb command.

5. Confirm it is actually running

A clean build is not a working app. After launch, check GetConsoleOutput for startup failures — filter on errors and faults rather than pulling everything:

GetConsoleOutput(pattern: "error|fatal|crash|exception|Terminating", oslogSeverity: ["error", "fault"], tailLimit: 100)

If it crashed on launch, treat the trace as the next bug: fix it and return to step 3, under the same 3-attempt bound.

6. Report

State the scheme, destination, build result, and launch state. Report what the evidence shows — if the build succeeded but the app crashed on launch, or errors remain after 3 attempts, say so plainly with the relevant output. Never describe an unverified launch as working.

Mention StopProject if the app is left running.

Notes

  • Do not run BuildProject and RunProject in sequence for a plain run — RunProject already builds. Build separately only when the goal is to check compilation without launching.
  • GetTargetBuildSettings reads build settings; never parse project.pbxproj.
  • Clearing DerivedData (rm -rf ~/Library/Developer/Xcode/DerivedData/*) is a last resort for stale artifacts, not a routine step — it forces a full rebuild of every project on the machine.

Launch the generate-docs agent to build symbol graph documentation with context isolation.

Pass the following context to the agent:

  • Plugin root: ${CLAUDE_PLUGIN_ROOT}
  • Scheme argument: $ARGUMENTS (if provided)
  • Working directory: the current project root

When the agent completes, report its summary to the user including documented modules, counts, and what files were updated.

Xcode MCP reference

Apple's Xcode MCP server (mcp__xcode__*, Xcode 26+) drives a live Xcode instance, not xcodebuild.

That distinction drives everything else here: there is no -destination flag to pass. Scheme and run destination are mutable state on the open workspace. Set the state, then act on it. Every tool takes an optional workspaceIdentifier (identifier such as workspace1, or an absolute path); omit it when a single workspace is open, pass it whenever more than one is.

Detecting availability

The server is available when mcp__xcode__* tools appear in the tool list. If their schemas are not loaded, fetch them with ToolSearch using select:mcp__xcode__BuildProject,.... Absence of the tools — or any call failing because Xcode is not running — means fall back to the CLI table below.

Tools this workflow uses

PurposeToolNotes
Find open workspacesXcodeListWorkspacesReturns identifier + path for each. No arguments.
Open oneXcodeOpenWorkspacepath to .xcworkspace/.xcodeproj; returns its identifier.
List schemesXcodeListSchemesActive scheme first. Full list written to fullSchemeListPath.
Set schemeXcodeSwitchSchemeReturns activeDestinationDisplayTitle — Xcode may auto-switch the destination.
List destinationsXcodeListRunDestinationsGrouped as in the Xcode picker. Incompatible ones omitted unless includeIncompatible: true.
Set destinationXcodeSwitchRunDestinationTakes displayTitle. Refuses ineligible destinations and reports why.
BuildBuildProjectBlocks until the build finishes. buildForTesting also builds test targets.
Read failuresGetBuildLogFilter with severity (error/warning/remark), pattern (regex), glob (path).
Build + install + launchRunProjectEquivalent to Cmd+R. Boots the simulator itself. attachDebugger for lldb.
Read app outputGetConsoleOutputstdout/stderr + OSLog. Filter by pattern, oslogSeverity, tailLimit.
Stop the appStopProjectCmd+. — no-op if nothing is running.
Per-file diagnosticsXcodeRefreshCodeIssuesInFilefilePath is project-relative (MyApp/Sources/Foo.swift).
Build settingsGetTargetBuildSettingsUse this rather than parsing project.pbxproj.

Round-tripping destination titles

activeDestinationDisplayTitle is returned by XcodeListRunDestinations, XcodeSwitchScheme, and XcodeSwitchRunDestination alike, and feeds straight back into XcodeSwitchRunDestination. Chain those outputs instead of re-listing.

Key behaviours worth relying on

  • RunProject subsumes the whole launch sequence. It builds, installs, boots the simulator if needed, and launches. Do not pair it with simctl boot/install/launch, and do not scrape BUILT_PRODUCTS_DIR.
  • BuildProject blocks. No background task or polling needed; GetBuildLog also reports whether a build is still in progress.
  • GetBuildLog filters server-side. Ask for severity: "error" rather than reading a full log.
  • XcodeSwitchScheme can move the destination. A scheme change may silently swap e.g. My Mac for My Mac (Mac Catalyst). Read the returned activeDestinationDisplayTitle rather than assuming.

Runtime interaction (optional, expensive)

For tapping through UI or capturing screenshots. Sessions hold real resources and affect the user's UI — always close them.

  • DeviceInteractionStartWorkspaceSession — bound to the workspace, so it offers only devices the active scheme can run on and enables install+run. Requires sessionIdentifier (Title Case, human-friendly).
  • DeviceInteractionStartSession — no workspace; cannot build or install. Requires deviceIdentifier.
  • DeviceInteractionInstallAndRun — builds, installs, launches on the session's device.
  • DeviceInteractionSynthesize — one interaction command (t 100 200 to tap, swipe, type, press), then returns a screenshot and a UI hierarchy dump. Derive coordinates from the hierarchy, never from the screenshot alone.
  • DeviceInteractionEndSession — always call this when finished.

Parameter-name gotcha: the session key is interactionSessionKey on InstallAndRun and EndSession, but interactSessionKey on Synthesize.

Other tools available on the server

Tests (GetTestList, RunAllTests, RunSomeTests, XcodeListTestPlans, XcodeSwitchTestPlan), project structure (XcodeListTargets, XcodeNewProject, XcodeNewTarget, XcodeListTemplates), file operations within project organization (XcodeRead, XcodeWrite, XcodeGrep, XcodeGlob, XcodeLS, XcodeMV, XcodeRM, XcodeMakeDir, XcodeUpdate), configuration (AddEntitlement, AddInfoPlist, UpdateTargetBuildSetting, GetFileCompilerFlags, UpdateFileCompilerFlags), debugging (InvokeDebuggerCommand for any lldb command), SwiftUI previews (RenderPreview), scratch evaluation (RunCodeSnippet), docs (DocumentationSearch), localization (LocalizationPlanner, StringCatalogRead/Edit/Context), and production diagnostics (GetTopCrashIssues, GetCrashIssueLogs, GetTopFieldPerformanceIssues, GetFieldPerformanceIssueLogs).

Prefer any of these over the equivalent shell command when the server is available.

CLI fallback

Used only when the MCP server is unavailable. <proj> is -workspace X.xcworkspace or -project X.xcodeproj.

MCP toolCLI equivalent
XcodeListWorkspacesls -d *.xcworkspace *.xcodeproj
XcodeListSchemesxcodebuild <proj> -list -json
XcodeListRunDestinationsxcodebuild <proj> -scheme S -showdestinations
BuildProjectxcodebuild <proj> -scheme S -destination D build
GetBuildLogParse xcodebuild output for error: lines
RunProject (macOS)open "$BUILT_PRODUCTS_DIR/<app>.app"
RunProject (simulator)xcrun simctl boot D, simctl install booted <app>, simctl launch --terminate-running-process booted <bundle-id>
GetConsoleOutputxcrun simctl spawn booted log stream --level debug
GetTargetBuildSettingsxcodebuild <proj> -scheme S -showBuildSettings -json

CLI notes:

  • Builds take 30s–5m+. Run xcodebuild with run_in_background: true and poll.
  • Prefer -json output and jq over grep | awk on human-readable output.
  • List simulators with xcrun simctl list devices available -j; filter on isAvailable.
  • No simulator runtimes installed: xcodebuild -downloadPlatform iOS, or direct the user to Xcode → Settings → Components.

Troubleshooting

SymptomAction
MCP calls fail / no workspaceConfirm Xcode is running with the project open; XcodeOpenWorkspace otherwise.
Ambiguous scheme nameUse the disambiguatedName from XcodeListSchemes (e.g. MyScheme (MyProject)).
Destination refused as ineligibleRe-list with includeIncompatible: true and read the stated reason.
Simulator boot hangsxcrun simctl shutdown all, then retry.
Stale build artifactsrm -rf ~/Library/Developer/Xcode/DerivedData/*. Last resort — it forces a full rebuild of everything.

Launch the swift-lint agent to format and lint Swift code with context isolation.

Pass the following context to the agent:

  • Plugin root: ${CLAUDE_PLUGIN_ROOT}
  • Target path: $ARGUMENTS (or . if none provided)
  • Working directory: the current project root

When the agent completes, report its summary to the user. If it fixed lint issues, mention how many files were modified.

Agents 2

Build symbol graph documentation for the current Xcode project and make it discoverable to future LLM sessions. The dispatching command will provide context including the plugin root path and optional scheme argument.

For the visual workflow diagram, see <plugin-root>/commands/references/generate-docs-workflow.mmd.

Step 1: Run generate-docs.sh

Execute the helper script which handles scheme discovery, docbuild, symbol graph extraction, and transformation to structured CSVs:

bash <plugin-root>/commands/references/generate-docs.sh [scheme]
  • The <plugin-root> path and optional scheme argument will be provided by the dispatching command

The script outputs one JSON line per step with the structure: {"step": "...", "status": "...", "output": "..."}.

Step 2: Handle Results

Parse the JSON output from the script:

  1. preflight step: If status is "error", report the error and stop
  2. scheme step: If status is "error", report available schemes and stop
  3. docbuild step: If status is "error", report the build error and suggest running /build-and-run first to fix compilation issues
  4. extract step: If status is "warning", report the warning and stop (no symbol graphs to transform)
  5. transform step: If status is "error", report the transform error and stop
  6. summary step: Extract modules, types, methods, relationships counts from the output object

Step 3: Update .gitignore

Check if .gitignore exists in the project root:

  • If .gitignore doesn't exist, create it
  • Check if .build/ is already covered (which would include all subdirectories)
  • If not, check for .build/api-docs/, .build/docs/, and .build/symbol-graphs-raw/ individually
  • Append any missing entries

Do NOT add a blanket .build/ entry — the project may manage that differently.

Step 4: Update CLAUDE.md

Check if CLAUDE.md exists in the project root. If not, create it.

Search for the marker <!-- generate-docs --> in CLAUDE.md:

  • If found, replace everything from <!-- generate-docs --> to <!-- /generate-docs --> (inclusive) with the block below
  • If not found, append the block below to the end of CLAUDE.md

Replace <module list> with the comma-separated module names from the summary output.

<!-- generate-docs -->
## API Documentation

This project contains pre-analyzed API documentation generated by `/generate-docs`.
The context files in `.build/api-docs/` contain structured information about the public API surface.

Available modules: <module list>

| Context | Description | Details |
|---------|-------------|---------|
| API Surface | Index of all modules and data table schemas | [`.build/api-docs/api-surface.md`](.build/api-docs/api-surface.md) |
| Types | All public types (classes, structs, enums, protocols) | [`.build/api-docs/types.csv`](.build/api-docs/types.csv) |
| Methods | All public methods, properties, and subscripts with declarations | [`.build/api-docs/methods.csv`](.build/api-docs/methods.csv) |
| Relationships | Type conformances, inheritance, and membership | [`.build/api-docs/relationships.csv`](.build/api-docs/relationships.csv) |

**Reading the context files:**
- Start with `api-surface.md` to understand what's available and the CSV column schemas
- Read the `.csv` files directly when you need specific API details
- Use Grep to search across CSVs for specific type or method names
<!-- /generate-docs -->

Step 5: Report Summary

Provide a concise summary including:

  • List of documented modules
  • Counts of types, methods, and relationships
  • Output path (.build/api-docs/)
  • What was updated (.gitignore, CLAUDE.md)

Format and lint Swift code for the target project. The dispatching command will provide context including the plugin root path and target path.

Step 1: Run swift-lint.sh

Execute the helper script which handles periphery (auto-detected), formatting, and linting in a single invocation:

bash <plugin-root>/commands/references/swift-lint.sh [path] --periphery
  • Pass the target path (or . for the full project)
  • Always pass --periphery — the script automatically skips if periphery is not installed or the project lacks configuration
  • The <plugin-root> path will be provided by the dispatching command

The script outputs one JSON line per step with the structure: {"step": "...", "status": "...", "output": "..."}.

Step 2: Handle Results

Parse the JSON output from the script:

  1. periphery step (if run): Note any unused code findings
  2. format step: Note that formatting was applied in-place
  3. lint step:
    • If status is "clean" — done
    • If status is "issues" — read the flagged files, fix each lint issue using Edit, then re-verify by running:
      bash <plugin-root>/commands/references/swift-lint.sh [path] --lint-only
      
    • Repeat until lint is clean

Step 3: Report Summary

Provide a concise summary including:

  • Number of files formatted
  • Number of lint issues found and fixed
  • Any unused code findings from periphery
  • Whether lint is now clean

Sponsors

Details

Marketplace
sjungling/sjungling-claude-plugins
Source
plugins/swift-engineer
Category
Community

More from sjungling/sjungling-claude-plugins

All 15