| name | init-xcode-app |
| description | Scaffold a standalone SwiftUI app via XcodeGen — pick macOS, iOS, or iOS+watchOS; ships house conventions, a Swift Testing target, swiftformat/swiftlint, optional CloudKit/CI/Release/Push modules, and optional JTBD product context. Use to "init an xcode project", "scaffold a swiftui app", "new mac/ios app". |
init-xcode-app
Scaffolds a native SwiftUI app with XcodeGen (project.yml → generated, committed .xcodeproj),
pre-loaded with the conventions and loop-closer toolchain (xcsift, the Xcode MCP, swiftformat/lint).
The lighter native sibling of init-tauri-app.
When to use
- "init an xcode project", "scaffold a swiftui app", "new macOS/iOS app".
Prerequisites (verify before scaffolding)
xcodegen on PATH (xcodegen --version; brew install xcodegen if missing).- Xcode + CLT (
xcodebuild -version).
Procedure
1. Gather inputs (AskUserQuestion)
- App name (PascalCase, e.g.
Tidepool) → <Name>; lowercase → <name>.
- Bundle-id prefix (default
com.glebkalinin) → <bundlePrefix>.
- DEVELOPMENT_TEAM (optional — blank allowed) →
<TEAM>.
- Target shape:
ios | macos | ios-watchos.
- Modules (multi-select): CloudKit · CI · Release · Push.
- JTBD artifact (optional): path to a
jtbd.json (else auto-discover ./jtbd.json, ~/jtbd/<name>/jtbd.json). See 1.5.
- Target directory (default
~/ai_projects/<name>). Abort if non-empty.
1.5 Ingest JTBD (optional, additive)
Identical contract to init-tauri-app: resolve (explicit → ./jtbd.json → ~/jtbd/<name>/jtbd.json),
confirm via hook, validate (render-jtbd.sh exits 3 → skip), pre-fill name. Artifacts written in Step 3.
2. Render core
Copy assets/core/common/* into the project (renames: gitignore→.gitignore, swiftformat→.swiftformat,
CLAUDE.md→.claude/CLAUDE.md). Copy assets/core/shapes/<shape>/* into the project root. For macos,
also copy assets/core/shapes/ios/Sources + Tests (macos reuses the same SwiftUI sources). Substitute
<Name>/<name>/<bundlePrefix>/<TEAM> in every copied file. Blank <TEAM> → leave the placeholder line
DEVELOPMENT_TEAM: "".
If a JTBD artifact was confirmed: render assets/jtbd/PRODUCT.md.template→docs/PRODUCT.md,
guardrails-check.md.template→docs/internal/guardrails-check.md, insert
agents-product-section.md.template into AGENTS.md after the first heading, copy the artifact to
project-root jtbd.json. See assets/jtbd/jtbd-map.md.
3. Compose selected modules
For each selected module open assets/modules/<m>/INSERT.md and follow it: it lists source files to copy
and a project-fragment.yml to merge into project.yml (merge into the existing targets.<Name> and
entitlements: maps — never overwrite). CloudKit + Push both extend the same entitlements: map.
4. Generate + verify (the gate)
xcodegen generate
Then the unsigned build gate by shape:
- ios / ios-watchos:
xcodebuild build -scheme <Name> -destination 'generic/platform=iOS Simulator'
- macos:
xcodebuild build -scheme <Name> -destination 'platform=macOS' CODE_SIGNING_ALLOWED=NO
Then xcodebuild test against the same destination for the test target. Both must pass.
5. Handoff
Offer git init && git add -A && git commit. Print summary: shape, modules, signing note
(device/release signing is a human step), next command (open <Name>.xcodeproj).
