visionos-app-bootstrap

name

visionos-app-bootstrap

description

Bootstrap new Apple Vision Pro apps from vetted visionOS starter templates instead of creating projects from scratch. Use when Codex needs to scaffold, clone, adapt, rename, validate, or deploy a fresh visionOS window app or immersive mixed-reality app with working Info.plist settings, Swift 6 / strict concurrency project defaults, icon-layer tooling, signing sync, and active-device deployment helpers.

visionOS App Bootstrap

Overview

Use the installed blueprint payload under ~/.codex/vendor/visionos-codex-kit/blueprints instead of generating a new project shell by hand. This skill is for fast, correct startup. It complements visionos-3d-development, which remains the reference skill for implementation details after the scaffold exists.

Installed Asset Resolution

Resolve installed blueprint paths with the bundled scripts:

• Root: bash scripts/locate_blueprint_assets.sh root
• Window template: bash scripts/locate_blueprint_assets.sh window
• Mixed template: bash scripts/locate_blueprint_assets.sh mixed
• Install manifest: bash scripts/locate_blueprint_assets.sh manifest

Copy a template into a destination with:

• bash scripts/create_from_blueprint.sh window /abs/path/NewApp
• bash scripts/create_from_blueprint.sh mixed /abs/path/NewApp

Template Selection

• window: use for a normal visionOS window app with a sane default size, empty starter content, layered icon workflow, signing sync, and active-device deployment helper.
• mixed: use for an immersive-only mixed-reality app with no WindowGroup, room-geometry visualization, a reachable red test ball, layered icon workflow, signing sync, and active-device deployment helper.

Bootstrap Workflow

1. Choose the template. Do not start from scratch if one of these blueprints fits the request.
2. Copy the template into the requested destination with scripts/create_from_blueprint.sh.
3. Rename the shell cleanly:
   • app name and module name
   • source folder and entry-point file names
   • .xcodeproj name
   • target and shared scheme names
   • bundle identifier
   • user-facing app strings
   • README examples if still present
4. Prefer changing project.yml and source files, then regenerate with ./tools/regenerate_project.sh. Do not hand-edit the .pbxproj unless regeneration cannot express the change.
5. Preserve the icon workflow. If icon layers change, update IconSources/ and run ./tools/build_app_icon.sh.
6. Validate with:
   • xcodebuild -project <Project>.xcodeproj -scheme <Scheme> -destination 'platform=visionOS Simulator,name=Apple Vision Pro' build
   • ./tools/deploy_to_active_device.sh when device deployment matters

Guardrails

• Keep the vendored tools/ scripts unless the user explicitly wants a different bootstrap standard.
• Preserve Swift 6, strict concurrency, and xcodegen-based project regeneration.
• For the mixed template, do not add a WindowGroup unless the user asks for a mixed shell with a window.
• For the window template, keep the default window placement and size behavior unless the user asks to change it.
• Use the device deploy script rather than trying to encode run-destination UI state into Xcode user files.
• If the task shifts from scaffolding into feature work, also use visionos-3d-development for API and architecture guidance.

Search Patterns

• Locate installed templates: bash scripts/locate_blueprint_assets.sh root
• Copy a window starter: bash scripts/create_from_blueprint.sh window /tmp/MyWindowApp
• Copy a mixed starter: bash scripts/create_from_blueprint.sh mixed /tmp/MyMixedApp