ios-project-scaffold
Scaffold a new iOS project with a pinned Xcode toolchain, Tuist manifest, repo-owned worktree execution helper, simprofile-driven simulator policy, Makefile targets for build/test/run/trace/release, F
SKILL.mdagent-marketplace/src/ios/skills/ios-project-scaffold/SKILL.md
GitHubiOS Project Scaffold
Use this skill to create a new iOS project with a consistent local workflow or to check an existing project against that workflow. Choose init when creating the scaffold and audit when checking for drift.
The generated repo has one clear ownership contract:
makeis the public interface for local builds, tests, screenshots, cleanup, and trace collection.- The repo-owned worktree helper manages simulators, ownership locks, and mutable state under
build/. Project.swiftdefines targets, schemes, and suite metadata tags.TestPlans/<App>.simprofile.tomldefines runtime classes and preferred devices only.AGENTS.mdand the worktree runbook direct future agents to use the helper when it owns the requested state, instead of issuing freehandxcodebuild,simctl,tuist, orfastlanecommands.- Generated hooks stay fast: they may format staged files and run lightweight lint, but they do not run simulator tests,
xcodebuild, or deep analysis.
Init: scaffold a project
Run the scaffold script with the target directory, app name, bundle ID, and team ID:
bash ~/.agents/plugins/plugins/ios/skills/ios-project-scaffold/scripts/scaffold.sh \ --target /path/to/new/app \ --name MyApp \ --bundle-id com.example.MyApp \ --team-id ABCD123456Add
--with-analysiswhen the project should include Periphery configuration and amake analyzetarget. The script also accepts--forceto overwrite existing generated files.In the generated project, follow the script's printed next steps: read
README.bootstrap.md, rungit init, thenmake bootstrap-local,make generate,make build,make run-iphone, andmake test-matrix. The script creates the scaffold; it does not install Xcode.
The scaffold includes:
- Tool pins:
.xcode-version,.tuist-version,mise.toml, and.envrc - Tuist source of truth:
Project.swiftandTuist/Package.swift - Agent and test guidance:
AGENTS.md,docs/operations/runbooks/worktree-execution.md, andTestPlans/README.md - Runtime policy:
TestPlans/<App>.simprofile.toml - Helper-driven automation:
Makefile,scripts/<app>_worktree.py, andscripts/trace_execution.py - Local hygiene:
.swiftlint.yml,.swiftformat,.typos.toml, and.githooks/pre-commit - Release configuration:
fastlane/Fastfile,fastlane/Appfile, andfastlane/.env.example - CI workflows:
.github/workflows/ci.yml,.github/workflows/beta.yml, and.github/workflows/security.yml - A minimal SwiftUI app under
<App>/
With --with-analysis, the scaffold also adds .periphery.yml, pins Periphery, and wires make analyze.
Audit: check an existing project
Run the deterministic convention checks:
bash ~/.agents/plugins/plugins/ios/skills/ios-project-scaffold/scripts/audit.sh --target /path/to/appAdd
--jsonfor machine-readable results:bash ~/.agents/plugins/plugins/ios/skills/ios-project-scaffold/scripts/audit.sh --target /path/to/app --jsonRead the flagged files and assess the judgment calls below. Report concrete drift and applicable fix commands; the script's output alone does not assess these qualitative points.
The audit exits with 0 when all checks pass and 1 when at least one check fails.
Audit judgment calls
Repo contract
- Does
AGENTS.mdclearly identifymakeas the public command surface? - Does the runbook explain ownership, simulator reuse, cleanup, and the
build/artifact layout? - Does the repo keep mutable generated state under
build/, rather than/tmpor global DerivedData paths?
Project.swift and Tuist
- Does
Project.swiftdefine shared schemes and suite topology directly, without depending on generated scheme edits? - Do targets carry metadata tags for role, suite kind, runtime class, device support, and data mode?
- Is
Project.swiftthe only place that encodes target and suite topology? - Does
Tuist/Package.swiftinclude the external package dependencies expected by the manifest?
Worktree helper
- Does the helper infer topology from
tuist dump projectand target metadata instead of handwritten lane maps? - Does it own one reusable iPhone simulator and one reusable iPad simulator per worktree?
- Does it keep locks in
build/state/and simulator metadata inbuild/simulators/? - Does it expose
doctor-state,clean-build,clean-simulators,reset-simulators,release-owner, andclean?
Makefile
- Do
build,run,test-*,record-snapshots-*, and screenshot targets use the helper? - Does
generateuse the helper so ownership and state remain consistent? - Does the Makefile consume helper-exported environment such as derived-data paths, simulator names, and result-bundle paths?
- Do build and test commands still flow through
xcbeautify? - Are grouped targets split by device family so an agent can intentionally run one lane?
Simprofile
- Does
TestPlans/<App>.simprofile.tomldefine runtime classes and preferred device identifiers only? - Does it leave task names, suite topology, and scheme names to their source of truth?
Local hygiene
- Is
.githooks/pre-commitlimited to staged-file operations? - Does it avoid
xcodebuild, simulator work, and deep analysis? - Do
setup-toolsandbootstrap-localremain local-only rather than mixing in CI concerns?
CI and release
- Does
ci.ymlrun throughmakeinstead of hand-rolledxcodebuildcommands? - Do macOS jobs have
timeout-minutes? - Does
ci.ymlcancel stale runs whilebeta.ymlpreserves in-flight releases? - Does the beta/TestFlight workflow use an approval-gated environment?
References
Load the relevant reference when you need implementation details for that area:
Requirements
The scaffold assumes Xcode 26.3 is installed and selected, with xcodes, mise, jq, and perl available. Run make bootstrap-local once after git init. Xcode installation is outside this skill's scope.
Related skill
Use ios-audit for a broader engineering and UX audit. This skill checks scaffold and repo-hygiene conventions.
The scaffold does not create an App Store Connect app record, design product architecture or feature modules, define backend contracts, choose app design or HIG-specific UX, or replace project-specific release, secrets, and API workflows beyond the scaffold baseline.