fix(workflow): use XcodeGen for iOS app scaffold — prevent SPM executable instead of .xcodeproj (#2041)

Adds ios-scaffold.md reference that explicitly prohibits Package.swift +
.executableTarget for iOS apps (produces macOS CLI, not iOS app bundle),
requires project.yml + xcodegen generate to create a proper .xcodeproj,
and documents SwiftUI API availability tiers (iOS 16 vs 17). Adds iOS
anti-patterns 28-29 to universal-anti-patterns.md and wires the reference
into gsd-executor.md so executors see the guidance during iOS plan execution.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

agents/gsd-executor.md

@@ -98,6 +98,9 @@ grep -n "type=\"checkpoint" [plan-path]
 At execution decision points, apply structured reasoning:
 @~/.claude/get-shit-done/references/thinking-models-execution.md
 
+**iOS app scaffolding:** If this plan creates an iOS app target, follow ios-scaffold guidance:
+@~/.claude/get-shit-done/references/ios-scaffold.md
+
 For each task:
 
 1. **If `type="auto"`:**

get-shit-done/references/ios-scaffold.md

@@ -0,0 +1,123 @@
+# iOS App Scaffold Reference
+
+Rules and patterns for scaffolding iOS applications. Apply when any plan involves creating a new iOS app target.
+
+---
+
+## Critical Rule: Never Use Package.swift as the Primary Build System for iOS Apps
+
+**NEVER use `Package.swift` with `.executableTarget` (or `.target`) to scaffold an iOS app.** Swift Package Manager executable targets compile as macOS command-line tools — they do not produce `.app` bundles, cannot be signed for iOS devices, and cannot be submitted to the App Store.
+
+**Prohibited pattern:**
+```swift
+// Package.swift — DO NOT USE for iOS apps
+.executableTarget(name: "MyApp", dependencies: [])
+// or
+.target(name: "MyApp", dependencies: [])
+```
+
+Using this pattern produces a macOS CLI binary, not an iOS app. The app will not build for any iOS simulator or device.
+
+---
+
+## Required Pattern: XcodeGen
+
+All iOS app scaffolding MUST use XcodeGen to generate the `.xcodeproj`.
+
+### Step 1 — Install XcodeGen (if not present)
+
+```bash
+brew install xcodegen
+```
+
+### Step 2 — Create `project.yml`
+
+`project.yml` is the XcodeGen spec that describes the project structure. Minimum viable spec:
+
+```yaml
+name: MyApp
+options:
+  bundleIdPrefix: com.example
+  deploymentTarget:
+    iOS: "17.0"
+settings:
+  SWIFT_VERSION: "5.10"
+  IPHONEOS_DEPLOYMENT_TARGET: "17.0"
+targets:
+  MyApp:
+    type: application
+    platform: iOS
+    sources: [Sources/MyApp]
+    settings:
+      PRODUCT_BUNDLE_IDENTIFIER: com.example.MyApp
+      INFOPLIST_FILE: Sources/MyApp/Info.plist
+    scheme:
+      testTargets:
+        - MyAppTests
+  MyAppTests:
+    type: bundle.unit-test
+    platform: iOS
+    sources: [Tests/MyAppTests]
+    dependencies:
+      - target: MyApp
+```
+
+### Step 3 — Generate the .xcodeproj
+
+```bash
+xcodegen generate
+```
+
+This creates `MyApp.xcodeproj` in the project root. Commit `project.yml` but add `*.xcodeproj` to `.gitignore` (regenerate on checkout).
+
+### Step 4 — Standard project layout
+
+```
+MyApp/
+├── project.yml              # XcodeGen spec — commit this
+├── .gitignore               # includes *.xcodeproj
+├── Sources/
+│   └── MyApp/
+│       ├── MyAppApp.swift   # @main entry point
+│       ├── ContentView.swift
+│       └── Info.plist
+└── Tests/
+    └── MyAppTests/
+        └── MyAppTests.swift
+```
+
+---
+
+## iOS Deployment Target Compatibility
+
+Always verify SwiftUI API availability against the project's `IPHONEOS_DEPLOYMENT_TARGET` before using any SwiftUI component.
+
+| API | Minimum iOS |
+|-----|-------------|
+| `NavigationView` | iOS 13 |
+| `NavigationStack` | iOS 16 |
+| `NavigationSplitView` | iOS 16 |
+| `List(selection:)` with multi-select | iOS 17 |
+| `ScrollView` scroll position APIs | iOS 17 |
+| `Observable` macro (`@Observable`) | iOS 17 |
+| `SwiftData` | iOS 17 |
+| `@Bindable` | iOS 17 |
+| `TipKit` | iOS 17 |
+
+**Rule:** If a plan requires a SwiftUI API that exceeds the project's deployment target, either:
+1. Raise the deployment target in `project.yml` (and document the decision), or
+2. Wrap the call in `if #available(iOS NN, *) { ... }` with a fallback implementation.
+
+Do NOT silently use an API that requires a higher iOS version than the declared deployment target — the app will crash at runtime on older devices.
+
+---
+
+## Verification
+
+After running `xcodegen generate`, verify the project builds:
+
+```bash
+xcodebuild -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16' build
+```
+
+A successful build (exit code 0) confirms the scaffold is valid for iOS.

get-shit-done/references/universal-anti-patterns.md

@@ -56,3 +56,8 @@ Reference: `references/questioning.md` for the full anti-pattern list.
 25. **Always use `gsd-tools.cjs`** (not `gsd-tools.js` or any other variant) -- GSD uses CommonJS for Node.js CLI compatibility.
 26. **Plan files MUST follow `{padded_phase}-{NN}-PLAN.md` pattern** (e.g., `01-01-PLAN.md`). Never use `PLAN-01.md`, `plan-01.md`, or any other variation -- gsd-tools detection depends on this exact pattern.
 27. **Do not start executing the next plan before writing the SUMMARY.md for the current plan** -- downstream plans may reference it via `@` includes.
+
+## iOS / Apple Platform Rules
+
+28. **NEVER use `Package.swift` + `.executableTarget` (or `.target`) as the primary build system for iOS apps.** SPM executable targets produce macOS CLI binaries, not iOS `.app` bundles. They cannot be installed on iOS devices or submitted to the App Store. Use XcodeGen (`project.yml` + `xcodegen generate`) to create a proper `.xcodeproj`. See `references/ios-scaffold.md` for the full pattern.
+29. **Verify SwiftUI API availability before use.** Many SwiftUI APIs require a specific minimum iOS version (e.g., `NavigationSplitView` is iOS 16+, `List(selection:)` with multi-select and `@Observable` require iOS 17). If a plan uses an API that exceeds the declared `IPHONEOS_DEPLOYMENT_TARGET`, raise the deployment target or add `#available` guards.

tests/ios-scaffold-safety.test.cjs

@@ -0,0 +1,126 @@
+'use strict';
+
+/**
+ * iOS Scaffold Safety Tests (#2023)
+ *
+ * Validates that GSD guidance:
+ * 1. Does NOT instruct using Package.swift + .executableTarget as the primary
+ *    build system for iOS apps (which produces a macOS CLI, not an iOS app).
+ * 2. DOES contain XcodeGen guidance (project.yml + xcodegen generate) for iOS
+ *    app scaffolding.
+ * 3. Documents SwiftUI API availability (iOS 16 vs 17 compatibility).
+ */
+
+const { describe, test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+const IOS_SCAFFOLD_REF = path.join(
+  __dirname, '..', 'get-shit-done', 'references', 'ios-scaffold.md'
+);
+const EXECUTOR_AGENT = path.join(
+  __dirname, '..', 'agents', 'gsd-executor.md'
+);
+const UNIVERSAL_ANTI_PATTERNS = path.join(
+  __dirname, '..', 'get-shit-done', 'references', 'universal-anti-patterns.md'
+);
+
+describe('ios-scaffold.md reference exists and contains XcodeGen guidance', () => {
+  test('reference file exists at get-shit-done/references/ios-scaffold.md', () => {
+    assert.ok(
+      fs.existsSync(IOS_SCAFFOLD_REF),
+      `Expected iOS scaffold reference at ${IOS_SCAFFOLD_REF}`
+    );
+  });
+
+  test('reference prohibits Package.swift as primary build system for iOS apps', () => {
+    const content = fs.readFileSync(IOS_SCAFFOLD_REF, 'utf-8');
+    const prohibitsPackageSwift =
+      content.includes('Package.swift') &&
+      (
+        content.includes('NEVER') ||
+        content.includes('never') ||
+        content.includes('prohibited') ||
+        content.includes('do not') ||
+        content.includes('Do not') ||
+        content.includes('must not')
+      );
+    assert.ok(
+      prohibitsPackageSwift,
+      'ios-scaffold.md must explicitly prohibit Package.swift as the primary build system for iOS apps'
+    );
+  });
+
+  test('reference prohibits .executableTarget for iOS apps', () => {
+    const content = fs.readFileSync(IOS_SCAFFOLD_REF, 'utf-8');
+    const prohibitsExecutableTarget =
+      content.includes('executableTarget') &&
+      (
+        content.includes('NEVER') ||
+        content.includes('never') ||
+        content.includes('prohibited') ||
+        content.includes('do not') ||
+        content.includes('Do not') ||
+        content.includes('must not')
+      );
+    assert.ok(
+      prohibitsExecutableTarget,
+      'ios-scaffold.md must explicitly prohibit .executableTarget for iOS app targets'
+    );
+  });
+
+  test('reference requires project.yml (XcodeGen spec) for iOS app scaffolding', () => {
+    const content = fs.readFileSync(IOS_SCAFFOLD_REF, 'utf-8');
+    assert.ok(
+      content.includes('project.yml'),
+      'ios-scaffold.md must require project.yml as the XcodeGen spec file'
+    );
+  });
+
+  test('reference requires xcodegen generate command', () => {
+    const content = fs.readFileSync(IOS_SCAFFOLD_REF, 'utf-8');
+    assert.ok(
+      content.includes('xcodegen generate') || content.includes('xcodegen'),
+      'ios-scaffold.md must require the xcodegen generate command to create .xcodeproj'
+    );
+  });
+
+  test('reference documents iOS deployment target compatibility', () => {
+    const content = fs.readFileSync(IOS_SCAFFOLD_REF, 'utf-8');
+    const hasApiCompatibility =
+      content.includes('iOS 16') ||
+      content.includes('iOS 17') ||
+      content.includes('deployment target') ||
+      content.includes('NavigationSplitView') ||
+      content.includes('availability') ||
+      content.includes('SwiftUI API');
+    assert.ok(
+      hasApiCompatibility,
+      'ios-scaffold.md must document SwiftUI API availability and iOS deployment target compatibility'
+    );
+  });
+});
+
+describe('gsd-executor.md references ios-scaffold guidance', () => {
+  test('executor agent references ios-scaffold.md', () => {
+    const content = fs.readFileSync(EXECUTOR_AGENT, 'utf-8');
+    assert.ok(
+      content.includes('ios-scaffold.md') || content.includes('ios-scaffold'),
+      'gsd-executor.md must reference ios-scaffold.md for iOS app scaffold guidance'
+    );
+  });
+});
+
+describe('universal-anti-patterns.md documents iOS SPM anti-pattern', () => {
+  test('universal-anti-patterns.md documents Package.swift misuse for iOS apps', () => {
+    const content = fs.readFileSync(UNIVERSAL_ANTI_PATTERNS, 'utf-8');
+    const hasAntiPattern =
+      (content.includes('Package.swift') || content.includes('SPM')) &&
+      (content.includes('iOS') || content.includes('ios'));
+    assert.ok(
+      hasAntiPattern,
+      'universal-anti-patterns.md must document the Package.swift/SPM misuse anti-pattern for iOS apps'
+    );
+  });
+});