awl-ios-ref


Type	Skill
Plugin	awl-ios · v0.0.6
Invoke	`/awl-ios:awl-ios-ref`
Source	plugins/awl-ios/skills/awl-ios-ref/SKILL.md

When Claude uses it

Command reference for closed-loop iOS development on AWL Tuist projects — generate the project, build with xcodebuild plus xcbeautify or xcsift, boot and drive the simulator with simctl, capture screenshots, read console output, automate UI with AXe, test on devices with devicectl, and pull Loco translations. Use whenever you build, run, install, launch, screenshot, or test an iOS app from Claude Code, need a simulator UDID, or work with Localizable.strings and the LS accessors. NOT for writing tests (use awl-testing testing-swift), not for scaffolding or aligning a project with the template (use ios-project-setup), not for KMP shared Kotlin code (use awl-android kotlin-expert).

Definition

Closing the loop means you build, run, look at, and interact with the app without switching to Xcode. Every command here matches the AWL iOS project template (ios-infra/templates/project-template-ios), which is a Tuist project with the schemes staging, prod, and Feature.

Project facts to resolve first

Read these from the project before running anything. The values below are the template defaults, and rename_project.sh replaces ProjectTemplate with the app name.

Value	Where it comes from	Template default
Workspace	`tuist generate` output, gitignored	`ProjectTemplate.xcworkspace`
Scheme	`Project.swift` `schemes()`	`staging` (also `prod`, `Feature`)
Configuration	`Project.swift` `Configuration` extension	`stagingDebug`, `stagingRelease`, `prodDebug`, `prodRelease`
Bundle ID	`Configurations/<config>.xcconfig`	`com.appswithlove.projecttemplate.staging` (staging), `com.appswithlove.projecttemplate` (prod)
App target	`Project.swift` `Target.main`	`ProjectTemplate`
Test targets	`Project.swift`	`ProjectTemplateTests`, `FeatureTests` (Swift Testing)
Xcode	`.xcode-version`	`26.5`
Tuist	`.mise.toml`	`4.98.0`
Min iOS	`Project.swift` `minIosVersion`	`26.4`

Export them once per session so the snippets in references/ work unchanged:

export WORKSPACE=ProjectTemplate.xcworkspace SCHEME=staging CONFIG=stagingDebug \
  APP=ProjectTemplate BUNDLE_ID=com.appswithlove.projecttemplate.staging
export UDID=$(xcrun simctl list devices -j | jq -r '.devices | to_entries[] | .value[] | select(.state == "Booted") | .udid' | head -1)

If the project has a ## Close the Loop section in its CLAUDE.md, prefer those values.

Decision table

Situation	Do this	Read
No `.xcworkspace` in the repo	`tuist install && tuist generate --no-open` (the workspace is gitignored)	`references/build-run.md`
Xcode MCP is configured and the project is open in Xcode	Build, test, and read issues through MCP; keep CLI for simulator, console, screenshots, automation	`references/build-run.md`
Xcode MCP is not configured	`xcodebuild ... 2>&1 \| xcbeautify` (in the template Brewfile) or `\| xcsift` (install separately, JSON output)	`references/build-run.md`
Need to run the app and see its output	`simctl install` + `simctl launch --console-pty --terminate-running-process`	`references/build-run.md`
Verify a visual change	Screenshot with `simctl io`, then read the PNG	`references/build-run.md`
Tap, type, scroll in the simulator	AXe: `describe-ui` first, then `tap --id`	`references/ui-automation.md`
Framework only works on hardware	`devicectl` install and launch	`references/devices.md`
Run the whole test suite the way CI does	`bundle exec fastlane test --env staging`	`references/build-run.md`
Add or check a translation	Loco is the source of truth; `LS.<camelKey>` in Swift	`references/localization.md`
Lint the way CI does	`bundle exec fastlane lint --env staging`	`references/build-run.md`

Minimal loop

# 1. generate (once, or after Project.swift changes)
tuist install && tuist generate --no-open

# 2. build
xcodebuild -workspace "$WORKSPACE" -scheme "$SCHEME" -configuration "$CONFIG" \
  -destination "platform=iOS Simulator,id=$UDID" \
  -derivedDataPath DerivedData build 2>&1 | xcbeautify

# 3. install + launch with console
xcrun simctl install "$UDID" "DerivedData/Build/Products/$CONFIG-iphonesimulator/$APP.app"
xcrun simctl launch --console-pty --terminate-running-process "$UDID" "$BUNDLE_ID"

# 4. look
xcrun simctl io "$UDID" screenshot DerivedData/tmp/screen.png

Pitfalls

Product path includes the configuration name. The template has no Debug configuration, so the app lands in DerivedData/Build/Products/stagingDebug-iphonesimulator/, not Debug-iphonesimulator/.
Regenerate after editing Project.swift, Tuist/Package.swift, or adding files outside a buildable folder. The template uses buildableFolders, so new Swift files inside ProjectTemplate/Sources or Feature/Sources need no regeneration.
Always pass -derivedDataPath DerivedData. The default location mixes CLI and Xcode caches and produces stale builds; rm -rf DerivedData fixes the rest.
Always add --terminate-running-process with --console-pty. Without it, relaunching a running app reconnects silently and you see no output.
Always pipe 2>&1. xcodebuild writes progress to stderr, and both xcbeautify and xcsift only read stdin.
AXe gestures are named after the finger, not the content. scroll-up reveals content below.
Never call the Loco API without the user’s approval. Every string you add lands in the shared project for all developers.
bundle exec fastlane <lane> needs --env staging or --env prod. Lanes read fastlane/.env.<env>, and locally before_all resolves secrets through the 1Password CLI, so run op signin first.

ios-project-setup for Tuist, Swift 6 settings, fastlane, secrets, and CI shape
awl-testing:testing-swift for writing Swift Testing and XCTest code
swiftui-expert-skill and swift-optimization for the code itself
Axiom marketplace (axiom-axe-ref, axiom-xcode-debugging) when installed, for the full AXe CLI and Xcode environment diagnostics