plugin: standardize Xcode app repo layout

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

@@ -1,6 +1,6 @@
 {
   "name": "agent-portability-skills",
-  "version": "8.5.2",
+  "version": "8.5.3",
   "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.2"
+version = "8.5.3"
 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.2",
+  "version": "8.5.3",
   "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.2",
+  "version": "8.5.3",
   "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.2",
+  "version": "8.5.3",
   "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/validate_repo_docs.sh

@@ -298,9 +298,9 @@ xcode_agents_assets=(
 for agents_asset in "${xcode_agents_assets[@]}"; do
   require_contains "$agents_asset" 'Use `xcode-build-run-workflow`'
   require_contains "$agents_asset" 'Use `xcode-testing-workflow`'
-  require_contains "$agents_asset" 'scripts/repo-maintenance/config/profile.env'
+  require_contains "$agents_asset" 'Scripts/repo-maintenance/config/profile.env'
   require_contains "$agents_asset" '.swiftformat'
-  require_contains "$agents_asset" 'scripts/repo-maintenance/hooks/pre-commit.sample'
+  require_contains "$agents_asset" 'Scripts/repo-maintenance/hooks/pre-commit.sample'
   require_contains "$agents_asset" 'swiftformat --lint'
   require_contains "$agents_asset" '.xctestplan'
   require_contains "$agents_asset" 'project membership, target membership, build phases, and resource inclusion'

plugins/apple-dev-skills/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "apple-dev-skills-maintainer"
-version = "8.5.2"
+version = "8.5.3"
 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

@@ -78,6 +78,9 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 
 - Treat the `.xcworkspace` or `.xcodeproj` as the source of truth for Apple platform app integration, schemes, build settings, destinations, and target membership.
 - Prefer edits through Xcode-aware project structure and keep project file changes intentional and reviewed closely.
+- Use the standard top-level Xcode app repository layout when creating or normalizing native app repos: `Sources/`, `Tests/`, `Shared/`, `Extensions/`, `Configurations/`, `Scripts/`, and `Packages/`.
+- `Sources/` owns the main app target implementation and app-owned resources/support files. `Tests/` owns all test targets. `Shared/` owns reusable source intended to be compiled into the app and extension targets. `Extensions/` owns extension target roots, one folder per extension. `Configurations/` owns `.xcconfig` layers. `Scripts/` owns project-local automation and build helper scripts. `Packages/` owns local Swift packages only when a real package boundary is justified.
+- Keep those top-level roots stable. Do not invent parallel names such as `AppSources`, `TestSources`, `Config`, `BuildScripts`, or `LocalPackages` for ordinary Xcode app repos unless the existing repo already has a deliberate, documented convention.
 - Use `xcodebuild` for Apple platform integration validation, including scheme, destination or SDK, and configuration-specific build or test runs.
 - Keep `xcodebuild` invocations reproducible in automation by passing explicit schemes, destinations or SDKs, and configurations when relevant.
 - For Codex GUI worktree-first Xcode repos, use a portable `.codex/environments/*.toml` local environment file when the repo wants shared app setup or action buttons. Start from `apple-dev-skills/templates/codex-local-environments/xcode-project.toml`, keep paths repo-relative, and prefer `-derivedDataPath ./DerivedData` or another ignored repo-local build directory instead of user-global DerivedData.
@@ -99,7 +102,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - 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` 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.
+- 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, plus one `Shared` source entry when shared app/extension code exists. A standard test target gets one `Tests` source entry that includes all test subdirectories. Extension targets use one `Extensions/<ExtensionName>` source entry per extension target. If a project has another separate top-level logical root, use one top-level 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.

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

@@ -78,6 +78,9 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 
 - Treat the `.xcworkspace` or `.xcodeproj` as the source of truth for Apple platform app integration, schemes, build settings, destinations, and target membership.
 - Prefer edits through Xcode-aware project structure and keep project file changes intentional and reviewed closely.
+- Use the standard top-level Xcode app repository layout when creating or normalizing native app repos: `Sources/`, `Tests/`, `Shared/`, `Extensions/`, `Configurations/`, `Scripts/`, and `Packages/`.
+- `Sources/` owns the main app target implementation and app-owned resources/support files. `Tests/` owns all test targets. `Shared/` owns reusable source intended to be compiled into the app and extension targets. `Extensions/` owns extension target roots, one folder per extension. `Configurations/` owns `.xcconfig` layers. `Scripts/` owns project-local automation and build helper scripts. `Packages/` owns local Swift packages only when a real package boundary is justified.
+- Keep those top-level roots stable. Do not invent parallel names such as `AppSources`, `TestSources`, `Config`, `BuildScripts`, or `LocalPackages` for ordinary Xcode app repos unless the existing repo already has a deliberate, documented convention.
 - Use `xcodebuild` for Apple platform integration validation, including scheme, destination or SDK, and configuration-specific build or test runs.
 - Keep `xcodebuild` invocations reproducible in automation by passing explicit schemes, destinations or SDKs, and configurations when relevant.
 - For Codex GUI worktree-first Xcode repos, use a portable `.codex/environments/*.toml` local environment file when the repo wants shared app setup or action buttons. Start from `apple-dev-skills/templates/codex-local-environments/xcode-project.toml`, keep paths repo-relative, and prefer `-derivedDataPath ./DerivedData` or another ignored repo-local build directory instead of user-global DerivedData.
@@ -99,7 +102,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - 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` 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.
+- 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, plus one `Shared` source entry when shared app/extension code exists. A standard test target gets one `Tests` source entry that includes all test subdirectories. Extension targets use one `Extensions/<ExtensionName>` source entry per extension target. If a project has another separate top-level logical root, use one top-level 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.

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

@@ -78,6 +78,9 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 
 - Treat the `.xcworkspace` or `.xcodeproj` as the source of truth for Apple platform app integration, schemes, build settings, destinations, and target membership.
 - Prefer edits through Xcode-aware project structure and keep project file changes intentional and reviewed closely.
+- Use the standard top-level Xcode app repository layout when creating or normalizing native app repos: `Sources/`, `Tests/`, `Shared/`, `Extensions/`, `Configurations/`, `Scripts/`, and `Packages/`.
+- `Sources/` owns the main app target implementation and app-owned resources/support files. `Tests/` owns all test targets. `Shared/` owns reusable source intended to be compiled into the app and extension targets. `Extensions/` owns extension target roots, one folder per extension. `Configurations/` owns `.xcconfig` layers. `Scripts/` owns project-local automation and build helper scripts. `Packages/` owns local Swift packages only when a real package boundary is justified.
+- Keep those top-level roots stable. Do not invent parallel names such as `AppSources`, `TestSources`, `Config`, `BuildScripts`, or `LocalPackages` for ordinary Xcode app repos unless the existing repo already has a deliberate, documented convention.
 - Use `xcodebuild` for Apple platform integration validation, including scheme, destination or SDK, and configuration-specific build or test runs.
 - Keep `xcodebuild` invocations reproducible in automation by passing explicit schemes, destinations or SDKs, and configurations when relevant.
 - For Codex GUI worktree-first Xcode repos, use a portable `.codex/environments/*.toml` local environment file when the repo wants shared app setup or action buttons. Start from `apple-dev-skills/templates/codex-local-environments/xcode-project.toml`, keep paths repo-relative, and prefer `-derivedDataPath ./DerivedData` or another ignored repo-local build directory instead of user-global DerivedData.
@@ -99,7 +102,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - 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` 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.
+- 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, plus one `Shared` source entry when shared app/extension code exists. A standard test target gets one `Tests` source entry that includes all test subdirectories. Extension targets use one `Extensions/<ExtensionName>` source entry per extension target. If a project has another separate top-level logical root, use one top-level 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.