diff --git a/agents/gsd-executor.md b/agents/gsd-executor.md index 82b35a7f..89980da5 100644 --- a/agents/gsd-executor.md +++ b/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"`:** diff --git a/get-shit-done/references/ios-scaffold.md b/get-shit-done/references/ios-scaffold.md new file mode 100644 index 00000000..ebf7d537 --- /dev/null +++ b/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. diff --git a/get-shit-done/references/universal-anti-patterns.md b/get-shit-done/references/universal-anti-patterns.md index 27fe80b5..473c15af 100644 --- a/get-shit-done/references/universal-anti-patterns.md +++ b/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. diff --git a/tests/ios-scaffold-safety.test.cjs b/tests/ios-scaffold-safety.test.cjs new file mode 100644 index 00000000..9c7e2eaa --- /dev/null +++ b/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' + ); + }); +});