Bootstrap Xcode App Project

Bootstrap Xcode App Project

SwiftData And SwiftUI Rule

When a task combines SwiftData with SwiftUI, keep SwiftData directly coupled to SwiftUI through Apple's data-driven path: modelContainer, environment modelContext, @Query, SwiftData model objects, and bindings. Do not add repositories, stores, service layers, DTO mirrors, view-model caches, wrapper objects, or other abstraction layers between SwiftData and SwiftUI. If this skill is not the right owner for SwiftData-backed SwiftUI work, hand off to apple-dev-skills:swiftui-app-architecture-workflow instead of inventing an intermediate data layer.

Purpose

Create a new native Apple app repository from nothing to a usable baseline on disk. The first implementation prioritizes a deterministic XcodeGen path for SwiftUI app projects and a guarded planning path for the standard Xcode-created-project flow. scripts/run_workflow.py is the runtime entrypoint, and scripts/bootstrap_xcode_app_project.py is the current implementation core for XcodeGen-backed scaffold creation plus maintain-project-repo installation with the xcode-app profile.

Companion Plugin Requirement

This skill can be discovered from a standalone apple-dev-skills install, but its mutating bootstrap path installs repo-maintenance files through the companion productivity-skills plugin. If the companion maintain-project-repo runner is missing, tell the user to install productivity-skills alongside apple-dev-skills, or add the socket marketplace with codex plugin marketplace add gaelic-ghost/socket and then install or enable both apple-dev-skills and productivity-skills from the Socket catalog.

When To Use

• Use this skill when the user wants to start, begin, create, or bootstrap a new macOS, iOS, or iPadOS app project on macOS.
• Use this skill when the user explicitly asks for a new Xcode app, a native Apple app, or a new SwiftUI app repository.
• Use this skill when the user wants a reproducible app-project generator flow and prefers XcodeGen.
• Use this skill when a brand-new app repo should also get baseline repo guidance such as AGENTS.md.
• Do not use this skill for ordinary collaboration inside an existing Xcode project.
• Do not use this skill for plain Swift packages, libraries, or tools that are not native Apple apps.
• Recommend bootstrap-swift-package when the user wants a regular SwiftPM package instead of a native Apple app.
• Recommend xcode-build-run-workflow when the project already exists and the task is execution, diagnostics, docs lookup, mutation, build, run, or preview work inside that existing project.
• Recommend xcode-testing-workflow when the project already exists and the task is primarily about Swift Testing, XCTest, XCUITest, .xctestplan, or test diagnosis.

Single-Path Workflow

1. Collect the required inputs:

• name
• destination
• platform
• ui_stack
• project_generator
• optional bundle_identifier
• optional org_identifier
• optional skip_validation
• optional dry_run

1. Classify the request as a native Apple app bootstrap request before continuing:

• continue only for project_kind=app
• stop if the request is actually a Swift package, library, or tool bootstrap

1. Apply the Apple docs gate before recommending project structure or implementation guidance:

• read the relevant Apple documentation first
• use Xcode MCP DocumentationSearch or Xcode-local documentation first for Apple-owned SDK, framework, lifecycle, and Xcode project-creation behavior
• use Dash MCP or Dash HTTP next when installed local docsets are a better fit
• use open source Swift project repositories, generated DocC, or release notes when the relevant Swift package or tool is open source and available there
• use official Apple web docs only when the page content is actually readable through a capable source; generic no-JS web search/open results, snippets, metadata shells, or bare URLs are not enough
• state the documented behavior being relied on before design or implementation guidance
• current documented anchors for this workflow include:
• Apple's Xcode project-creation guidance: Creating an Xcode project for an app
• SwiftUI app lifecycle guidance through the App protocol: App
• scene composition guidance through Scene and WindowGroup: Scene and WindowGroup
• if the docs and the current code or planned scaffold conflict, stop and report that conflict
• if no relevant Apple docs can be found, say that explicitly before proceeding

1. Apply the shared Swift policy before giving implementation guidance:

• apply the detailed local policy in references/snippets/apple-xcode-project-core.md
• preserve its simplicity-first, shape-preserving, and anti-ceremony Swift guidance

1. Run scripts/run_workflow.py to normalize inputs, load customization state, and select the supported bootstrap path.
2. Resolve the generator path:

• prefer xcodegen by default for new app projects unless the user explicitly prefers the standard Xcode project-creation flow
• use xcode only when the user explicitly prefers the standard Xcode project-creation flow
• treat ask as a legacy explicit-blocking value only when the user or customization state supplies it intentionally

1. Create the project:

• for xcodegen, let scripts/bootstrap_xcode_app_project.py generate the repo scaffold, project.yml, checked-in .xcconfig files, source files, tests, and AGENTS.md, then run xcodegen generate
• install .codex/environments/xcode-project.toml from templates/codex-local-environments/xcode-project.toml and replace the scheme placeholder with the generated app target name
• keep the generated project.yml aligned with the current XcodeGen project spec concepts: project options, targets, sources, schemes, packages, config files, test plans, and minimumXcodeGenVersion
• keep nontrivial build settings in external .xcconfig files by default and wire them through the XcodeGen spec instead of duplicating settings inline
• for xcode, use a guarded guidance path for now instead of pretending the repo supports full GUI automation already

1. Validate the scaffold:

• verify the expected app files exist
• verify .swiftformat exists
• verify AGENTS.md exists when enabled
• verify .codex/environments/xcode-project.toml exists and uses the generated app target name for Codex GUI actions
• verify generated guidance says tracked .pbxproj changes must be reviewed, staged, and committed before push, merge, release, or cleanup
• verify scripts/repo-maintenance/hooks/pre-commit.sample exists
• verify scripts/repo-maintenance/validate-all.sh and scripts/repo-maintenance/release.sh exist
• verify branch protection, when enabled, requires the GitHub Actions check context validate rather than Validate Repo Maintenance / validate
• when a GitHub remote is created or already exists, route repository

settings audit or mutation through productivity-skills:maintain-github-repository instead of embedding a separate Xcode-specific baseline

• if validation is enabled, verify project generation and basic project introspection succeeded

1. Hand off existing-project work cleanly:

• recommend sync-xcode-project-guidance when the repo guidance should be refreshed or merged after creation
• recommend xcode-build-run-workflow for normal Xcode build or run collaboration after bootstrap and guidance sync
• recommend xcode-testing-workflow for test-focused collaboration after bootstrap and guidance sync

Inputs

• name: required; app project name and repo directory name.
• destination: parent directory for the new app repo.
• project_kind: defaults to app; any non-app value blocks the workflow.
• platform: macos, ios, or ipados.
• ui_stack: swiftui, uikit, or appkit.
• project_generator: ask, xcode, or xcodegen.
• bundle_identifier: optional explicit bundle identifier.
• org_identifier: optional organization identifier used to derive a bundle identifier when bundle_identifier is omitted.
• skip_validation: optional flag to skip post-generation verification.
• dry_run: optional flag to resolve inputs and emit the planned execution contract without creating files.
• Defaults:
• runtime entrypoint: executable scripts/run_workflow.py
• project_kind defaults to app
• destination defaults to .
• platform defaults to ask unless explicitly set
• ui_stack defaults to swiftui
• project_generator defaults to xcodegen
• copy_agents_md defaults to true
• Codex GUI local environments are installed from templates/codex-local-environments/xcode-project.toml into .codex/environments/xcode-project.toml
• validation runs unless --skip-validation is passed
• maintain-project-repo installs scripts/repo-maintenance/ on successful mutating runs

Outputs

• status
• success: bootstrap completed on the supported path
• blocked: prerequisites, unsupported selections, or safety rules prevented completion
• failed: the implementation path started but did not complete successfully
• path_type
• primary: the documented supported path completed
• fallback: a guided fallback or non-mutating plan was returned instead
• output
• resolved project path
• normalized inputs
• resolved bundle identifier
• generator path
• installed .codex/environments/xcode-project.toml
• installed maintain-project-repo paths
• validation result
• one concise next step or handoff

Guards and Stop Conditions

• Stop with blocked if name is missing.
• Stop with blocked if project_kind is not app.
• Stop with blocked if the platform cannot be resolved safely.
• Stop with blocked if project_generator=ask and the request intentionally asks not to choose the default generator.
• Stop with blocked if ui_stack is not supported by the current implementation path.
• Stop with blocked if the target directory already exists and contains non-ignorable files.
• Stop with blocked if project_generator=xcodegen and xcodegen is not available on PATH.
• Stop with blocked if the user chose the standard Xcode flow and the repo cannot safely automate that path yet.

Fallbacks and Handoffs

• Preferred implementation path in the first iteration is XcodeGen plus generated scaffold files.
• Use the standard Xcode-created-project path only as a guided fallback for now.
• After a successful XcodeGen bootstrap, treat project.yml as the editable source for generated project structure and regenerate with xcodegen generate after project-spec changes.
• After a successful bootstrap, hand off to sync-xcode-project-guidance for repo-guidance alignment when needed, then to xcode-build-run-workflow for build, run, diagnostics, mutation, preview, and docs work.
• After a successful bootstrap, hand off to xcode-testing-workflow for Swift Testing, XCTest, XCUITest, .xctestplan, and test diagnosis work.
• After a successful bootstrap, use scripts/repo-maintenance/validate-all.sh for local maintainer validation and scripts/repo-maintenance/release.sh --mode standard --version vX.Y.Z from a feature branch or worktree for protected-main releases.
• After a successful bootstrap, configure protected branches to require validate for the managed repo-maintenance workflow; GitHub exposes that job check context directly rather than the workflow title plus job string.
• When the app repository is published to GitHub, use

productivity-skills:maintain-github-repository to audit repository features, merge modes, security automation, sign-off policy, and branch protection.

• Recommend bootstrap-swift-package directly when the task is really package bootstrap.
• Recommend sync-xcode-project-guidance when the repo already exists and only needs repo-guidance or documentation alignment.

Customization

• Use references/customization-flow.md.
• scripts/customization_config.py stores and reports customization state.
• scripts/run_workflow.py loads runtime-safe defaults from customization state before invoking the supported implementation path.
• Current runtime-enforced knobs include the default platform, bundle-ID prefix, and AGENTS.md copy behavior. Project kind, UI stack, generator choice, and validation policy now live as fixed workflow behavior or explicit invocation inputs.
• Run the Python wrapper and customization entrypoints through uv, because they rely on inline PyYAML script metadata rather than a repo-global Python environment.
• In consuming repos, the supported path is uv run scripts/run_workflow.py ... and uv run scripts/customization_config.py ...; do not assume plain python or python3 will have the needed YAML dependency installed.

References

Workflow References

• references/project-generators.md
• references/platform-matrix.md

Contract References

• references/automation-prompts.md
• references/customization-flow.md

Support References

• assets/AGENTS.md
• Recommend references/snippets/apple-xcode-project-core.md when the new app repo should start with reusable Xcode-project baseline policy content next to the generated AGENTS.md.
• references/snippets/apple-xcode-project-core.md

Script Inventory

• scripts/run_workflow.py
• scripts/bootstrap_xcode_app_project.py
• scripts/customization_config.py

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gaelic-ghost
• Source: gaelic-ghost/socket
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.