docs: enforce strict XcodeGen roots

plugins/agent-portability-skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-portability-skills",
-  "version": "8.5.1",
+  "version": "8.5.2",
   "description": "Maintainer skills for Socket-owned agent skill portability, Codex plugin surfaces, and host adapter guidance.",
   "author": {
     "name": "Gale",

plugins/agent-portability-skills/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-portability-skills-maintenance"
-version = "8.5.1"
+version = "8.5.2"
 description = "Maintainer-only Python tooling baseline for Agent Portability Skills."
 requires-python = ">=3.11"
 dependencies = []

plugins/agentdeck/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentdeck",
-  "version": "8.5.1",
+  "version": "8.5.2",
   "description": "Local Codex runtime utilities for thread, hook, and app-server workflows.",
   "author": {
     "name": "Gale",

plugins/android-dev-skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "android-dev-skills",
-  "version": "8.5.1",
+  "version": "8.5.2",
   "description": "Android, Kotlin, Java, Gradle, Android Gradle Plugin, testing, lint, UI implementation, and release-readiness workflow skills.",
   "author": {
     "name": "Gale",

plugins/apple-dev-skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-dev-skills",
-  "version": "8.5.1",
+  "version": "8.5.2",
   "description": "Apple development workflows for Codex, including media and audio repair, XcodeGen migration, Xcode coding intelligence, SwiftUI animation and architecture, Core Animation, Apple typography, SF Symbols, AppKit architecture, Icon Composer app icons, Safari extensions, DeviceCheck/App Attest, Swift OpenAPI clients, and DocC authoring guidance.",
   "author": {
     "name": "Gale",

plugins/apple-dev-skills/.github/scripts/sync_shared_snippets.sh

@@ -53,6 +53,7 @@ sync_one \
   "$ROOT_DIR/skills/xcode-testing-workflow/references/snippets/apple-xcode-project-core.md" \
   "$ROOT_DIR/skills/xcode-app-project-workflow/references/snippets/apple-xcode-project-core.md" \
   "$ROOT_DIR/skills/bootstrap-xcode-app-project/references/snippets/apple-xcode-project-core.md" \
+  "$ROOT_DIR/skills/migrate-xcode-project-to-xcodegen/references/snippets/apple-xcode-project-core.md" \
   "$ROOT_DIR/skills/format-swift-sources/references/snippets/apple-xcode-project-core.md" \
   "$ROOT_DIR/skills/explore-apple-swift-docs/references/snippets/apple-xcode-project-core.md" \
   "$ROOT_DIR/skills/avfaudio-session-workflow/references/snippets/apple-xcode-project-core.md" \

plugins/apple-dev-skills/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "apple-dev-skills-maintainer"
-version = "8.5.1"
+version = "8.5.2"
 description = "Maintainer tooling for the apple-dev-skills repository"
 requires-python = ">=3.10"
 dependencies = []

plugins/apple-dev-skills/shared/agents-snippets/apple-xcode-project-core.md

@@ -64,6 +64,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Keep updates to view-driving state minimal and localized.
 - Prefer durable identity for types that drive SwiftUI state and view updates.
 - Treat `App` as the application entry and scene composition boundary, `Scene` as the container for scene-specific lifecycle and environment, and `View` as the component rendering layer.
+- Every native app target must have exactly one app lifecycle entry point: one `@main` app type, one `main.swift`, or the platform-equivalent single launch entry. Do not add alternate app entry points, second `@main` types, duplicate `main.swift` files, target-specific app entry files, or parallel app structs for variants. When launch behavior must differ by platform, configuration, or feature flag, keep the single entry point and use Swift conditional compilation or ordinary runtime conditionals inside that boundary.
 - Use app-level lifecycle concerns at the `App` boundary, scene lifecycle concerns at the `Scene` boundary, and view-local active or presentation behavior inside views.
 - Use `@Binding` to pass a focused writable piece of parent-owned state into a child view.
 - Use `@Bindable` when working with an observable model that should project bindings to its mutable properties in a view.
@@ -97,8 +98,10 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Only regenerate after that promotion is complete, then review the generated project diff to confirm XcodeGen preserved the intended behavior instead of deleting it. If the owning tracked file is ambiguous, stop and ask before regenerating.
 - For new XcodeGen-backed app scaffolds, start from the maintained `apple-dev-skills/templates/xcodegen/` templates when available instead of inventing a fresh project-spec shape from memory.
 - Keep `minimumXcodeGenVersion` on a recent validated release for new scaffolds. Prefer updating the template and validation together when the repo intentionally raises the baseline.
-- For Xcode 16 or newer project formats, prefer XcodeGen `syncedFolder` source roots for normal app and test source directories so file creation, deletion, and organization stay synchronized between Xcode and the filesystem without hand-listing every source file in YAML.
-- If `syncedFolder` behaves poorly for a repo, fall back to broad recursive source paths such as `Sources/App` and `Tests/AppTests` with explicit `includes` and `excludes`; do not fall back to one YAML entry per ordinary source file unless a specific file needs custom flags or build-phase behavior.
+- For Xcode 16 or newer project formats, prefer XcodeGen `syncedFolder` roots at the broad top-level directory boundary so file creation, deletion, and organization stay synchronized between Xcode and the filesystem without hand-listing every source file in YAML.
+- Do not fragment ordinary XcodeGen source roots by subdirectory. A standard app target gets one `Sources` source entry that includes all app source, resource, support, generated plist, entitlement, and nested feature folders. A standard test target gets one `Tests` source entry that includes all test subdirectories. If a project has a separate top-level logical root such as `Resources`, use one top-level `Resources` entry for that root, not one entry per child folder.
+- Never split `Sources/App`, `Sources/Resources`, `Sources/Support`, feature folders, or `Tests/<TargetName>Tests` into separate XcodeGen source entries unless a specific non-ordinary file or folder truly needs custom compiler flags, build-phase routing, destination filters, or target membership that cannot be represented from the broad root.
+- If `syncedFolder` behaves poorly for a repo, fall back to the same broad top-level recursive paths such as `Sources`, `Tests`, or `Resources` with explicit `includes` and `excludes`; do not fall back to subdirectory-level fragmentation or one YAML entry per ordinary source file.
 - Keep XcodeGen specs readable as project structure, not as a dumping ground for every build setting. Use `configs`, `configFiles`, `targets`, `schemes`, `packages`, `projectReferences`, `targetTemplates`, and `schemeTemplates` deliberately so future edits have an obvious owner.
 - Prefer explicit top-level schemes for app scaffolds once scheme behavior matters. Put build, run, test, profile, analyze, archive, environment variables, command-line arguments, and test-plan references in the scheme spec rather than relying on hidden generated defaults.
 - Prefer external `.xcconfig` files as the default home for nontrivial build settings. Keep build settings in XcodeGen inline settings only when they are small, local, and clearer there.

plugins/apple-dev-skills/skills/appkit-app-architecture-workflow/references/snippets/apple-xcode-project-core.md

@@ -64,6 +64,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Keep updates to view-driving state minimal and localized.
 - Prefer durable identity for types that drive SwiftUI state and view updates.
 - Treat `App` as the application entry and scene composition boundary, `Scene` as the container for scene-specific lifecycle and environment, and `View` as the component rendering layer.
+- Every native app target must have exactly one app lifecycle entry point: one `@main` app type, one `main.swift`, or the platform-equivalent single launch entry. Do not add alternate app entry points, second `@main` types, duplicate `main.swift` files, target-specific app entry files, or parallel app structs for variants. When launch behavior must differ by platform, configuration, or feature flag, keep the single entry point and use Swift conditional compilation or ordinary runtime conditionals inside that boundary.
 - Use app-level lifecycle concerns at the `App` boundary, scene lifecycle concerns at the `Scene` boundary, and view-local active or presentation behavior inside views.
 - Use `@Binding` to pass a focused writable piece of parent-owned state into a child view.
 - Use `@Bindable` when working with an observable model that should project bindings to its mutable properties in a view.
@@ -97,8 +98,10 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Only regenerate after that promotion is complete, then review the generated project diff to confirm XcodeGen preserved the intended behavior instead of deleting it. If the owning tracked file is ambiguous, stop and ask before regenerating.
 - For new XcodeGen-backed app scaffolds, start from the maintained `apple-dev-skills/templates/xcodegen/` templates when available instead of inventing a fresh project-spec shape from memory.
 - Keep `minimumXcodeGenVersion` on a recent validated release for new scaffolds. Prefer updating the template and validation together when the repo intentionally raises the baseline.
-- For Xcode 16 or newer project formats, prefer XcodeGen `syncedFolder` source roots for normal app and test source directories so file creation, deletion, and organization stay synchronized between Xcode and the filesystem without hand-listing every source file in YAML.
-- If `syncedFolder` behaves poorly for a repo, fall back to broad recursive source paths such as `Sources/App` and `Tests/AppTests` with explicit `includes` and `excludes`; do not fall back to one YAML entry per ordinary source file unless a specific file needs custom flags or build-phase behavior.
+- For Xcode 16 or newer project formats, prefer XcodeGen `syncedFolder` roots at the broad top-level directory boundary so file creation, deletion, and organization stay synchronized between Xcode and the filesystem without hand-listing every source file in YAML.
+- Do not fragment ordinary XcodeGen source roots by subdirectory. A standard app target gets one `Sources` source entry that includes all app source, resource, support, generated plist, entitlement, and nested feature folders. A standard test target gets one `Tests` source entry that includes all test subdirectories. If a project has a separate top-level logical root such as `Resources`, use one top-level `Resources` entry for that root, not one entry per child folder.
+- Never split `Sources/App`, `Sources/Resources`, `Sources/Support`, feature folders, or `Tests/<TargetName>Tests` into separate XcodeGen source entries unless a specific non-ordinary file or folder truly needs custom compiler flags, build-phase routing, destination filters, or target membership that cannot be represented from the broad root.
+- If `syncedFolder` behaves poorly for a repo, fall back to the same broad top-level recursive paths such as `Sources`, `Tests`, or `Resources` with explicit `includes` and `excludes`; do not fall back to subdirectory-level fragmentation or one YAML entry per ordinary source file.
 - Keep XcodeGen specs readable as project structure, not as a dumping ground for every build setting. Use `configs`, `configFiles`, `targets`, `schemes`, `packages`, `projectReferences`, `targetTemplates`, and `schemeTemplates` deliberately so future edits have an obvious owner.
 - Prefer explicit top-level schemes for app scaffolds once scheme behavior matters. Put build, run, test, profile, analyze, archive, environment variables, command-line arguments, and test-plan references in the scheme spec rather than relying on hidden generated defaults.
 - Prefer external `.xcconfig` files as the default home for nontrivial build settings. Keep build settings in XcodeGen inline settings only when they are small, local, and clearer there.

plugins/apple-dev-skills/skills/apple-typography-workflow/references/snippets/apple-xcode-project-core.md

@@ -64,6 +64,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Keep updates to view-driving state minimal and localized.
 - Prefer durable identity for types that drive SwiftUI state and view updates.
 - Treat `App` as the application entry and scene composition boundary, `Scene` as the container for scene-specific lifecycle and environment, and `View` as the component rendering layer.
+- Every native app target must have exactly one app lifecycle entry point: one `@main` app type, one `main.swift`, or the platform-equivalent single launch entry. Do not add alternate app entry points, second `@main` types, duplicate `main.swift` files, target-specific app entry files, or parallel app structs for variants. When launch behavior must differ by platform, configuration, or feature flag, keep the single entry point and use Swift conditional compilation or ordinary runtime conditionals inside that boundary.
 - Use app-level lifecycle concerns at the `App` boundary, scene lifecycle concerns at the `Scene` boundary, and view-local active or presentation behavior inside views.
 - Use `@Binding` to pass a focused writable piece of parent-owned state into a child view.
 - Use `@Bindable` when working with an observable model that should project bindings to its mutable properties in a view.
@@ -97,8 +98,10 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Only regenerate after that promotion is complete, then review the generated project diff to confirm XcodeGen preserved the intended behavior instead of deleting it. If the owning tracked file is ambiguous, stop and ask before regenerating.
 - For new XcodeGen-backed app scaffolds, start from the maintained `apple-dev-skills/templates/xcodegen/` templates when available instead of inventing a fresh project-spec shape from memory.
 - Keep `minimumXcodeGenVersion` on a recent validated release for new scaffolds. Prefer updating the template and validation together when the repo intentionally raises the baseline.
-- For Xcode 16 or newer project formats, prefer XcodeGen `syncedFolder` source roots for normal app and test source directories so file creation, deletion, and organization stay synchronized between Xcode and the filesystem without hand-listing every source file in YAML.
-- If `syncedFolder` behaves poorly for a repo, fall back to broad recursive source paths such as `Sources/App` and `Tests/AppTests` with explicit `includes` and `excludes`; do not fall back to one YAML entry per ordinary source file unless a specific file needs custom flags or build-phase behavior.
+- For Xcode 16 or newer project formats, prefer XcodeGen `syncedFolder` roots at the broad top-level directory boundary so file creation, deletion, and organization stay synchronized between Xcode and the filesystem without hand-listing every source file in YAML.
+- Do not fragment ordinary XcodeGen source roots by subdirectory. A standard app target gets one `Sources` source entry that includes all app source, resource, support, generated plist, entitlement, and nested feature folders. A standard test target gets one `Tests` source entry that includes all test subdirectories. If a project has a separate top-level logical root such as `Resources`, use one top-level `Resources` entry for that root, not one entry per child folder.
+- Never split `Sources/App`, `Sources/Resources`, `Sources/Support`, feature folders, or `Tests/<TargetName>Tests` into separate XcodeGen source entries unless a specific non-ordinary file or folder truly needs custom compiler flags, build-phase routing, destination filters, or target membership that cannot be represented from the broad root.
+- If `syncedFolder` behaves poorly for a repo, fall back to the same broad top-level recursive paths such as `Sources`, `Tests`, or `Resources` with explicit `includes` and `excludes`; do not fall back to subdirectory-level fragmentation or one YAML entry per ordinary source file.
 - Keep XcodeGen specs readable as project structure, not as a dumping ground for every build setting. Use `configs`, `configFiles`, `targets`, `schemes`, `packages`, `projectReferences`, `targetTemplates`, and `schemeTemplates` deliberately so future edits have an obvious owner.
 - Prefer explicit top-level schemes for app scaffolds once scheme behavior matters. Put build, run, test, profile, analyze, archive, environment variables, command-line arguments, and test-plan references in the scheme spec rather than relying on hidden generated defaults.
 - Prefer external `.xcconfig` files as the default home for nontrivial build settings. Keep build settings in XcodeGen inline settings only when they are small, local, and clearer there.