diff --git a/README.md b/README.md
index 170a3910..26a8af80 100644
--- a/README.md
+++ b/README.md
@@ -82,7 +82,7 @@ Current Socket catalog shape:
 - `cardhop-app`: mixed skill plus bundled MCP server for Cardhop.app contact workflows
 - `codex-utilities`: local Codex runtime utilities, starting with a capture-only SessionStart hook for thread-title automation research
 - `dotnet-skills`: .NET, F#, and C# project-shape, bootstrap, implementation, test, package, diagnostics, ASP.NET Core, interop, CI, upgrade, and tooling guidance
-- `productivity-skills`: general-purpose maintainer and documentation workflows plus source-bundled docs-audit and code-tracing custom-agent definitions
+- `productivity-skills`: general-purpose maintainer, documentation, Codex GUI worktree workflow, and automation-design workflows plus source-bundled docs-audit and code-tracing custom-agent definitions
 - `python-skills`: Python runtime and tooling workflows for Python-based projects; see the [Python skills expansion plan](./docs/maintainers/python-skills-plugin-plan.md) for maintainer details
 - `server-side-swift`: server-side Swift support plus the source-bundled `server-swift-steward` custom-agent definition for services with frameworks like Vapor and Hummingbird
 - `rust-skills`: Rust, Cargo, rustup, crate, workspace, CLI, library, package, CI, test, lint, and format workflow guidance
diff --git a/ROADMAP.md b/ROADMAP.md
index 163268c1..7412bf6f 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -286,6 +286,7 @@ In Progress
 - [x] GitHub #60: Apple Dev Skills workflow helper is missing PyYAML runtime dependency ([#60](https://github.com/gaelic-ghost/socket/issues/60))
 - [x] Hardened `web-dev-skills:expo-inline-native-modules-workflow` with native-shape decision and validation reference tables.
 - [x] Added Server-Side Swift ecosystem package preference guidance for Vapor, Vapor Community, and Hummingbird-aligned packages.
+- [x] Added `productivity-skills:codex-gui-worktree-workflow` for general Codex GUI worktree-first planning, plus Apple and server-side Swift local environment templates in their owning stack plugins.
 
 ## Backlog Candidates
 
@@ -311,6 +312,7 @@ In Progress
 - [x] Add `agent-plugin-skills:skills-repo-guidance-sync` as a read-only custom-agent role for plugin-root policy audits, marketplace wording checks, Codex docs freshness, `.agents/skills` discovery mirrors, and generated guidance drift.
 - [ ] Add privacy-fenced app plugin auditor roles only after their read/write boundaries are explicit: `things-app:things-route-auditor` for read-only Things route and digest planning, and `cardhop-app:cardhop-contact-auditor` for schema, health, route, and dry-run preview checks.
 - [ ] Add language validation triager roles after one shared contract is agreed: `python-skills:python-validation-triager`, `rust-skills:rust-validation-triager`, and `dotnet-skills:dotnet-validation-triager`, each report-first and scoped to logs, manifests, CI, test, tooling, package, and upgrade evidence.
+- [ ] Add Codex GUI local environment templates and auto-copy/install behavior to `dotnet-skills` for F#, C#, and mixed `.NET` repos, keeping setup/actions portable and preserving customized `.codex/environments/*.toml` files the same way the SwiftPM and Xcode workflows do.
 - [ ] Revisit maybe-later subagent roles only after the owning plugin surface justifies them: `productivity-skills:roadmap-triage-worker`, `productivity-skills:automation-plan-designer`, `swiftasb-skills:swiftasb-steward`, and `web-dev-skills:expo-native-boundary-scout`.
 - [ ] Keep placeholder or write-heavy surfaces out of bundled roles for now: do not add `android-dev-skills:android-steward`, `spotify`, or a `maintain-project-repo` worker role until those surfaces have enough read-heavy workflow evidence and safe boundaries.
 - [x] Grow Swift Steward from read-heavy guidance-sync and repo-maintenance scans into reviewable patch artifacts that can be saved, edited, or applied by the main thread, then decide whether any apply-mode behavior belongs in the main thread, a guarded report workflow, or a future repo-local sidecar.
@@ -361,6 +363,7 @@ In Progress
 - Updated `socket` and plugin guidance so ordinary user installs and updates default to Git-backed Codex marketplace sources and official marketplace add/upgrade commands.
 - Loosened coordinated Codex subagent guidance so skills preserve OpenAI's explicit-trigger model while allowing narrower workflow guidance, such as Codex Security repository-wide scans, to ask for and use subagents when the task depends on parallel file-pass review.
 - Added coordinated Codex subagent guidance across `agent-plugin-skills` and `productivity-skills`, grounding skill wording in OpenAI's current explicit-trigger `subagents` model while keeping the root docs clear about why the pass belongs in `socket`.
+- Added `productivity-skills:codex-gui-worktree-workflow` as the general Codex GUI worktree-first planning surface, while keeping SwiftPM, Xcode, Vapor, Hummingbird, and server-side Swift local environment templates inside their stack-specific plugins.
 - Prepared the `v6.1.0` minor release by adding the `maintain-project-api` productivity skill and keeping the monorepo-owned child docs, tests, and shared version surfaces aligned.
 - Added explicit `standard` and `subtrees` release-mode guidance, including the pull-only `SpeakSwiftlyServer` rule for `socket` subtree sync.
 - Published `apple-dev-skills` `v6.0.11` after adding direct regression coverage for SwiftPM-generated `.swiftpm/xcode/package.xcworkspace` classification and synced the released child state back into `socket`.
diff --git a/plugins/agent-plugin-skills/.codex-plugin/plugin.json b/plugins/agent-plugin-skills/.codex-plugin/plugin.json
index ffe08582..8b845ba8 100644
--- a/plugins/agent-plugin-skills/.codex-plugin/plugin.json
+++ b/plugins/agent-plugin-skills/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "agent-plugin-skills",
-  "version": "6.16.2",
+  "version": "6.17.0",
   "description": "Installable maintainer skills for skills-export repositories.",
   "author": {
     "name": "Gale",
diff --git a/plugins/agent-plugin-skills/pyproject.toml b/plugins/agent-plugin-skills/pyproject.toml
index 2624d3a8..c6723be2 100644
--- a/plugins/agent-plugin-skills/pyproject.toml
+++ b/plugins/agent-plugin-skills/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "agent-plugin-skills-maintenance"
-version = "6.16.2"
+version = "6.17.0"
 description = "Maintainer-only Python tooling baseline for agent-plugin-skills."
 requires-python = ">=3.11"
 dependencies = []
diff --git a/plugins/agent-plugin-skills/uv.lock b/plugins/agent-plugin-skills/uv.lock
index 3ff767a0..284a19af 100644
--- a/plugins/agent-plugin-skills/uv.lock
+++ b/plugins/agent-plugin-skills/uv.lock
@@ -4,7 +4,7 @@ requires-python = ">=3.11"
 
 [[package]]
 name = "agent-plugin-skills-maintenance"
-version = "6.16.2"
+version = "6.17.0"
 source = { virtual = "." }
 
 [package.dev-dependencies]
diff --git a/plugins/android-dev-skills/.codex-plugin/plugin.json b/plugins/android-dev-skills/.codex-plugin/plugin.json
index 885bf91c..54dddd5a 100644
--- a/plugins/android-dev-skills/.codex-plugin/plugin.json
+++ b/plugins/android-dev-skills/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "android-dev-skills",
-  "version": "6.16.2",
+  "version": "6.17.0",
   "description": "Placeholder plugin repository for future Android, Kotlin, and Java Codex skills.",
   "author": {
     "name": "Gale",
diff --git a/plugins/apple-dev-skills/.codex-plugin/plugin.json b/plugins/apple-dev-skills/.codex-plugin/plugin.json
index a419354c..c53a07df 100644
--- a/plugins/apple-dev-skills/.codex-plugin/plugin.json
+++ b/plugins/apple-dev-skills/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "apple-dev-skills",
-  "version": "6.16.2",
+  "version": "6.17.0",
   "description": "Apple development workflows for Codex, including SwiftUI and AppKit architecture, Icon Composer app icons, Safari extensions, Swift OpenAPI clients, and DocC authoring guidance.",
   "author": {
     "name": "Gale",
diff --git a/plugins/apple-dev-skills/.github/scripts/sync_shared_snippets.sh b/plugins/apple-dev-skills/.github/scripts/sync_shared_snippets.sh
index 3e79772e..907a0599 100755
--- a/plugins/apple-dev-skills/.github/scripts/sync_shared_snippets.sh
+++ b/plugins/apple-dev-skills/.github/scripts/sync_shared_snippets.sh
@@ -35,12 +35,14 @@ sync_one \
   "$ROOT_DIR/skills/explore-apple-swift-docs/references/snippets/apple-xcode-project-core.md" \
   "$ROOT_DIR/skills/safari-extension-control-workflow/references/snippets/apple-xcode-project-core.md" \
   "$ROOT_DIR/skills/swiftui-app-architecture-workflow/references/snippets/apple-xcode-project-core.md" \
+  "$ROOT_DIR/skills/appkit-app-architecture-workflow/references/snippets/apple-xcode-project-core.md" \
   "$ROOT_DIR/skills/sync-xcode-project-guidance/references/snippets/apple-xcode-project-core.md"
 
 sync_one \
   "$ROOT_DIR/shared/agents-snippets/apple-swift-package-core.md" \
   "$ROOT_DIR/skills/swift-package-build-run-workflow/references/snippets/apple-swift-package-core.md" \
   "$ROOT_DIR/skills/swift-package-testing-workflow/references/snippets/apple-swift-package-core.md" \
+  "$ROOT_DIR/skills/swift-package-workflow/references/snippets/apple-swift-package-core.md" \
   "$ROOT_DIR/skills/bootstrap-swift-package/references/snippets/apple-swift-package-core.md" \
   "$ROOT_DIR/skills/sync-swift-package-guidance/references/snippets/apple-swift-package-core.md"
 
diff --git a/plugins/apple-dev-skills/pyproject.toml b/plugins/apple-dev-skills/pyproject.toml
index c871f543..22766834 100644
--- a/plugins/apple-dev-skills/pyproject.toml
+++ b/plugins/apple-dev-skills/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "apple-dev-skills-maintainer"
-version = "6.16.2"
+version = "6.17.0"
 description = "Maintainer tooling for the apple-dev-skills repository"
 requires-python = ">=3.9"
 dependencies = []
diff --git a/plugins/apple-dev-skills/shared/agents-snippets/apple-swift-package-core.md b/plugins/apple-dev-skills/shared/agents-snippets/apple-swift-package-core.md
index e6db1925..0b457687 100644
--- a/plugins/apple-dev-skills/shared/agents-snippets/apple-swift-package-core.md
+++ b/plugins/apple-dev-skills/shared/agents-snippets/apple-swift-package-core.md
@@ -72,6 +72,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Bundle precompiled Metal artifacts such as `.metallib` files as explicit package resources, and prefer `.copy(...)` when exact distribution matters more than resource processing.
 - When the requested work requires compiling Metal shaders, validating Apple-platform bundle integration, or inspecting Apple-managed components such as the Metal toolchain, hand off to the Xcode-aware workflow instead of assuming plain `swift build` is sufficient.
 - Run `swift build` and `swift test` as the default validation checks after package-level changes.
+- For Codex GUI worktree-first SwiftPM 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/swift-package.toml`, keep paths repo-relative, and do not commit machine-local dependency paths or user-specific build output paths.
 - Use `xcodebuild` for package validation when configuration-specific Apple-platform behavior matters, when test plans must be exercised, or when package builds depend on Xcode-managed SDK or Metal-toolchain behavior.
 - When package test plans are part of the contract, keep `.xctestplan` files versioned alongside the package-facing Xcode integration and exercise them explicitly with `xcodebuild -showTestPlans` and `xcodebuild -testPlan ...`.
 - Prefer normal SwiftPM parallel test execution for ordinary Swift Testing and XCTest runs. Do not serialize regular package tests just because they use Swift, XCTest, async tests, fixtures, or test plans.
diff --git a/plugins/apple-dev-skills/shared/agents-snippets/apple-xcode-project-core.md b/plugins/apple-dev-skills/shared/agents-snippets/apple-xcode-project-core.md
index 68f1bc21..92e839cd 100644
--- a/plugins/apple-dev-skills/shared/agents-snippets/apple-xcode-project-core.md
+++ b/plugins/apple-dev-skills/shared/agents-snippets/apple-xcode-project-core.md
@@ -78,6 +78,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Prefer edits through Xcode-aware project structure and keep project file changes intentional and reviewed closely.
 - 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.
 - When scripts or terminal workflows add files on disk, verify that Xcode project membership, target membership, build-phase membership, and resource-bundle inclusion all match the intended result; files appearing in the directory tree alone are not enough.
 - Direct filesystem edits outside `.pbxproj` are generally safe when Xcode is closed or when the current project is not open in Xcode, but still verify that the Xcode project picks up the intended files and memberships afterward.
 - Prefer Debug builds for everyday edit-build-test loops, but validate Release builds explicitly when optimization, packaging, launch behavior, watchdog timing, or deployment realism matters.
diff --git a/plugins/apple-dev-skills/skills/appkit-app-architecture-workflow/references/snippets/apple-xcode-project-core.md b/plugins/apple-dev-skills/skills/appkit-app-architecture-workflow/references/snippets/apple-xcode-project-core.md
index 68f1bc21..92e839cd 100644
--- a/plugins/apple-dev-skills/skills/appkit-app-architecture-workflow/references/snippets/apple-xcode-project-core.md
+++ b/plugins/apple-dev-skills/skills/appkit-app-architecture-workflow/references/snippets/apple-xcode-project-core.md
@@ -78,6 +78,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Prefer edits through Xcode-aware project structure and keep project file changes intentional and reviewed closely.
 - 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.
 - When scripts or terminal workflows add files on disk, verify that Xcode project membership, target membership, build-phase membership, and resource-bundle inclusion all match the intended result; files appearing in the directory tree alone are not enough.
 - Direct filesystem edits outside `.pbxproj` are generally safe when Xcode is closed or when the current project is not open in Xcode, but still verify that the Xcode project picks up the intended files and memberships afterward.
 - Prefer Debug builds for everyday edit-build-test loops, but validate Release builds explicitly when optimization, packaging, launch behavior, watchdog timing, or deployment realism matters.
diff --git a/plugins/apple-dev-skills/skills/apple-ui-accessibility-workflow/references/snippets/apple-xcode-project-core.md b/plugins/apple-dev-skills/skills/apple-ui-accessibility-workflow/references/snippets/apple-xcode-project-core.md
index 68f1bc21..92e839cd 100644
--- a/plugins/apple-dev-skills/skills/apple-ui-accessibility-workflow/references/snippets/apple-xcode-project-core.md
+++ b/plugins/apple-dev-skills/skills/apple-ui-accessibility-workflow/references/snippets/apple-xcode-project-core.md
@@ -78,6 +78,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Prefer edits through Xcode-aware project structure and keep project file changes intentional and reviewed closely.
 - 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.
 - When scripts or terminal workflows add files on disk, verify that Xcode project membership, target membership, build-phase membership, and resource-bundle inclusion all match the intended result; files appearing in the directory tree alone are not enough.
 - Direct filesystem edits outside `.pbxproj` are generally safe when Xcode is closed or when the current project is not open in Xcode, but still verify that the Xcode project picks up the intended files and memberships afterward.
 - Prefer Debug builds for everyday edit-build-test loops, but validate Release builds explicitly when optimization, packaging, launch behavior, watchdog timing, or deployment realism matters.
diff --git a/plugins/apple-dev-skills/skills/bootstrap-swift-package/SKILL.md b/plugins/apple-dev-skills/skills/bootstrap-swift-package/SKILL.md
index e5c0a2bb..7a4e4333 100644
--- a/plugins/apple-dev-skills/skills/bootstrap-swift-package/SKILL.md
+++ b/plugins/apple-dev-skills/skills/bootstrap-swift-package/SKILL.md
@@ -62,6 +62,7 @@ This skill can be discovered from a standalone `apple-dev-skills` install, but i
    - `// swift-tools-version:` remains `6.2` or newer when the generated manifest keeps trait-enabled dependencies
    - `.git`
    - `AGENTS.md`
+   - `.codex/environments/swift-package.toml`
    - `scripts/repo-maintenance/hooks/pre-commit.sample`
    - `scripts/repo-maintenance/validate-all.sh`
    - `scripts/repo-maintenance/release.sh`
@@ -105,6 +106,7 @@ This skill can be discovered from a standalone `apple-dev-skills` install, but i
   - generated manifests should preserve an explicit Swift 6 language-mode declaration with `swiftLanguageModes: [.v6]` when the active manifest surface supports it
   - generated manifests include `swift-configuration` by default with the `Configuration` product on the primary target and traits `.defaults`, `Reloading`, `YAML`, and `CommandLineArguments`
   - generated manifests may lower `// swift-tools-version:` from the scaffold default when the package should support the previous supported Swift minor, but they should never go below the current `6.2` floor while trait-enabled dependencies remain in the manifest
+  - Codex GUI local environments are installed from `templates/codex-local-environments/swift-package.toml` into `.codex/environments/swift-package.toml`
   - `maintain-project-repo` installs `scripts/repo-maintenance/` on successful mutating runs
 
 ## Outputs
@@ -121,6 +123,7 @@ This skill can be discovered from a standalone `apple-dev-skills` install, but i
   - normalized inputs
   - resolved `testing_strategy`
   - detected `swift_toolchain` on real runs
+  - installed `.codex/environments/swift-package.toml`
   - installed `maintain-project-repo` paths
   - validation result
   - one concise next step
diff --git a/plugins/apple-dev-skills/skills/bootstrap-swift-package/references/snippets/apple-swift-package-core.md b/plugins/apple-dev-skills/skills/bootstrap-swift-package/references/snippets/apple-swift-package-core.md
index e6db1925..0b457687 100644
--- a/plugins/apple-dev-skills/skills/bootstrap-swift-package/references/snippets/apple-swift-package-core.md
+++ b/plugins/apple-dev-skills/skills/bootstrap-swift-package/references/snippets/apple-swift-package-core.md
@@ -72,6 +72,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Bundle precompiled Metal artifacts such as `.metallib` files as explicit package resources, and prefer `.copy(...)` when exact distribution matters more than resource processing.
 - When the requested work requires compiling Metal shaders, validating Apple-platform bundle integration, or inspecting Apple-managed components such as the Metal toolchain, hand off to the Xcode-aware workflow instead of assuming plain `swift build` is sufficient.
 - Run `swift build` and `swift test` as the default validation checks after package-level changes.
+- For Codex GUI worktree-first SwiftPM 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/swift-package.toml`, keep paths repo-relative, and do not commit machine-local dependency paths or user-specific build output paths.
 - Use `xcodebuild` for package validation when configuration-specific Apple-platform behavior matters, when test plans must be exercised, or when package builds depend on Xcode-managed SDK or Metal-toolchain behavior.
 - When package test plans are part of the contract, keep `.xctestplan` files versioned alongside the package-facing Xcode integration and exercise them explicitly with `xcodebuild -showTestPlans` and `xcodebuild -testPlan ...`.
 - Prefer normal SwiftPM parallel test execution for ordinary Swift Testing and XCTest runs. Do not serialize regular package tests just because they use Swift, XCTest, async tests, fixtures, or test plans.
diff --git a/plugins/apple-dev-skills/skills/bootstrap-swift-package/scripts/bootstrap_swift_package.sh b/plugins/apple-dev-skills/skills/bootstrap-swift-package/scripts/bootstrap_swift_package.sh
index 01a733a3..ece4b7bd 100755
--- a/plugins/apple-dev-skills/skills/bootstrap-swift-package/scripts/bootstrap_swift_package.sh
+++ b/plugins/apple-dev-skills/skills/bootstrap-swift-package/scripts/bootstrap_swift_package.sh
@@ -74,6 +74,7 @@ swift_major_version=""
 swift_minor_version=""
 script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 agents_template="$script_dir/../assets/AGENTS.md"
+local_environment_template="$script_dir/../../../templates/codex-local-environments/swift-package.toml"
 maintain_project_repo_runner="$script_dir/../../../../productivity-skills/skills/maintain-project-repo/scripts/run_workflow.py"
 maintain_project_repo_missing_message="Validation failed: bootstrap-swift-package needs productivity-skills/maintain-project-repo to install repo-maintenance files, but the runner was missing at $maintain_project_repo_runner. Install productivity-skills alongside apple-dev-skills, or add the socket marketplace with 'codex plugin marketplace add gaelic-ghost/socket' and enable both apple-dev-skills and productivity-skills from the Socket catalog, then rerun this workflow."
 
@@ -440,6 +441,10 @@ if [[ "$copy_agents" == "true" ]] && [[ ! -f "$agents_template" ]]; then
   blocked "Template missing: $agents_template"
 fi
 
+if [[ ! -f "$local_environment_template" ]]; then
+  blocked "Template missing: $local_environment_template"
+fi
+
 target_dir="$destination/$name"
 
 if [[ -e "$destination" && ! -d "$destination" ]]; then
@@ -501,6 +506,9 @@ mkdir -p "$target_dir"
     cp "$agents_template" AGENTS.md
   fi
 
+  mkdir -p .codex/environments
+  cp "$local_environment_template" .codex/environments/swift-package.toml
+
   if [[ -x "$maintain_project_repo_runner" ]]; then
     "$maintain_project_repo_runner" --repo-root "$target_dir" --operation install --profile swift-package >/dev/null
   else
@@ -537,6 +545,10 @@ mkdir -p "$target_dir"
     failed "Validation failed: AGENTS.md missing."
   fi
 
+  if [[ ! -f .codex/environments/swift-package.toml ]]; then
+    failed "Validation failed: .codex/environments/swift-package.toml missing."
+  fi
+
   if [[ ! -d Tests ]]; then
     failed "Validation failed: Tests target directory missing."
   fi
@@ -568,6 +580,7 @@ if [[ "$copy_agents" == "true" ]]; then
 else
   echo "AGENTS: skipped"
 fi
+echo "Codex environment: installed .codex/environments/swift-package.toml"
 if [[ "$run_validation" == "true" ]]; then
   echo "Validation: swift build + swift test passed"
 else
diff --git a/plugins/apple-dev-skills/skills/bootstrap-swift-package/scripts/run_workflow.py b/plugins/apple-dev-skills/skills/bootstrap-swift-package/scripts/run_workflow.py
index 343b2167..53e229f6 100755
--- a/plugins/apple-dev-skills/skills/bootstrap-swift-package/scripts/run_workflow.py
+++ b/plugins/apple-dev-skills/skills/bootstrap-swift-package/scripts/run_workflow.py
@@ -30,6 +30,7 @@ def parse_output(stdout: str) -> dict:
         "validation_result": None,
         "git_initialized": None,
         "agents_copied": None,
+        "local_environment_installed": None,
         "testing_mode": None,
         "testing_strategy": None,
         "swift_toolchain": None,
@@ -43,6 +44,8 @@ def parse_output(stdout: str) -> dict:
             result["git_initialized"] = line.endswith("initialized")
         elif line.startswith("AGENTS: "):
             result["agents_copied"] = line.endswith("copied")
+        elif line.startswith("Codex environment: "):
+            result["local_environment_installed"] = "installed" in line
         elif line.startswith("Swift toolchain: "):
             result["swift_toolchain"] = line.split(": ", 1)[1].strip()
         elif line.startswith("Testing mode: "):
@@ -243,6 +246,7 @@ def main() -> int:
         "validation_result": parsed["validation_result"],
         "git_initialized": parsed["git_initialized"],
         "agents_copied": parsed["agents_copied"],
+        "local_environment_installed": parsed["local_environment_installed"],
         "testing_mode": parsed["testing_mode"],
         "testing_strategy": parsed["testing_strategy"],
         "swift_toolchain": parsed["swift_toolchain"],
diff --git a/plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/SKILL.md b/plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/SKILL.md
index 866a3908..b7730b27 100644
--- a/plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/SKILL.md
+++ b/plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/SKILL.md
@@ -60,6 +60,7 @@ This skill can be discovered from a standalone `apple-dev-skills` install, but i
    - treat `ask` as a legacy explicit-blocking value only when the user or customization state supplies it intentionally
 7. Create the project:
    - for `xcodegen`, let `scripts/bootstrap_xcode_app_project.py` generate the repo scaffold, `project.yml`, checked-in `.xcconfig` files, source files, tests, and `AGENTS.md`, then run `xcodegen generate`
+   - install `.codex/environments/xcode-project.toml` from `templates/codex-local-environments/xcode-project.toml` and replace the scheme placeholder with the generated app target name
    - keep the generated `project.yml` aligned with the current XcodeGen project spec concepts: project `options`, targets, sources, schemes, packages, config files, test plans, and `minimumXcodeGenVersion`
    - keep nontrivial build settings in external `.xcconfig` files by default and wire them through the XcodeGen spec instead of duplicating settings inline
    - for `xcode`, use a guarded guidance path for now instead of pretending the repo supports full GUI automation already
@@ -67,6 +68,7 @@ This skill can be discovered from a standalone `apple-dev-skills` install, but i
    - verify the expected app files exist
    - verify `.swiftformat` exists
    - verify `AGENTS.md` exists when enabled
+   - verify `.codex/environments/xcode-project.toml` exists and uses the generated app target name for Codex GUI actions
    - verify generated guidance says tracked `.pbxproj` changes must be reviewed, staged, and committed before push, merge, release, or cleanup
    - verify `scripts/repo-maintenance/hooks/pre-commit.sample` exists
    - verify `scripts/repo-maintenance/validate-all.sh` and `scripts/repo-maintenance/release.sh` exist
@@ -97,6 +99,7 @@ This skill can be discovered from a standalone `apple-dev-skills` install, but i
   - `ui_stack` defaults to `swiftui`
   - `project_generator` defaults to `xcodegen`
   - `copy_agents_md` defaults to `true`
+  - Codex GUI local environments are installed from `templates/codex-local-environments/xcode-project.toml` into `.codex/environments/xcode-project.toml`
   - validation runs unless `--skip-validation` is passed
   - `maintain-project-repo` installs `scripts/repo-maintenance/` on successful mutating runs
 
@@ -114,6 +117,7 @@ This skill can be discovered from a standalone `apple-dev-skills` install, but i
   - normalized inputs
   - resolved bundle identifier
   - generator path
+  - installed `.codex/environments/xcode-project.toml`
   - installed `maintain-project-repo` paths
   - validation result
   - one concise next step or handoff
diff --git a/plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/references/snippets/apple-xcode-project-core.md b/plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/references/snippets/apple-xcode-project-core.md
index 68f1bc21..92e839cd 100644
--- a/plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/references/snippets/apple-xcode-project-core.md
+++ b/plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/references/snippets/apple-xcode-project-core.md
@@ -78,6 +78,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Prefer edits through Xcode-aware project structure and keep project file changes intentional and reviewed closely.
 - 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.
 - When scripts or terminal workflows add files on disk, verify that Xcode project membership, target membership, build-phase membership, and resource-bundle inclusion all match the intended result; files appearing in the directory tree alone are not enough.
 - Direct filesystem edits outside `.pbxproj` are generally safe when Xcode is closed or when the current project is not open in Xcode, but still verify that the Xcode project picks up the intended files and memberships afterward.
 - Prefer Debug builds for everyday edit-build-test loops, but validate Release builds explicitly when optimization, packaging, launch behavior, watchdog timing, or deployment realism matters.
diff --git a/plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/scripts/bootstrap_xcode_app_project.py b/plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/scripts/bootstrap_xcode_app_project.py
index b1001a08..cfa937bd 100755
--- a/plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/scripts/bootstrap_xcode_app_project.py
+++ b/plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/scripts/bootstrap_xcode_app_project.py
@@ -45,6 +45,21 @@ def write_text(path: Path, content: str) -> None:
     path.write_text(content, encoding="utf-8")
 
 
+def install_local_environment(target_dir: Path, scheme_name: str) -> str:
+    template_path = (
+        Path(__file__).resolve().parents[3]
+        / "templates"
+        / "codex-local-environments"
+        / "xcode-project.toml"
+    )
+    target_path = target_dir / ".codex" / "environments" / "xcode-project.toml"
+    if not template_path.is_file():
+        raise RuntimeError(f"Codex local environment template is missing: {template_path}")
+    template_text = template_path.read_text(encoding="utf-8").replace("SCHEME_NAME", scheme_name)
+    write_text(target_path, template_text)
+    return str(target_path)
+
+
 def render_app_file(name: str) -> str:
     return f"""import SwiftUI
 
@@ -218,6 +233,20 @@ def main() -> int:
     write_text(target_dir / "Sources/App/App.swift", render_app_file(args.name))
     write_text(target_dir / "Sources/App/ContentView.swift", render_content_view())
     write_text(target_dir / f"Tests/{args.name}Tests/{args.name}Tests.swift", render_test_file(args.name))
+    try:
+        local_environment_path = install_local_environment(target_dir, args.name)
+    except RuntimeError as exc:
+        payload = {
+            "status": "failed",
+            "path_type": "primary",
+            "resolved_path": str(target_dir),
+            "normalized_inputs": normalized_inputs,
+            "validation_result": "failed (codex local environment install)",
+            "stderr": str(exc),
+            "next_step": "Resolve the Codex local environment template path and rerun bootstrap-xcode-app-project.",
+        }
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return 1
 
     agents_copied = False
     if args.copy_agents:
@@ -330,6 +359,7 @@ def main() -> int:
         "validation_result": validation_result,
         "generator": "xcodegen",
         "project_file": str(target_dir / f"{args.name}.xcodeproj"),
+        "local_environment_path": local_environment_path,
         "agents_copied": agents_copied,
         "stdout": proc_install_toolkit.stdout + proc_generate.stdout + validation_stdout,
         "stderr": proc_install_toolkit.stderr + proc_generate.stderr + validation_stderr,
diff --git a/plugins/apple-dev-skills/skills/explore-apple-swift-docs/references/snippets/apple-xcode-project-core.md b/plugins/apple-dev-skills/skills/explore-apple-swift-docs/references/snippets/apple-xcode-project-core.md
index 68f1bc21..92e839cd 100644
--- a/plugins/apple-dev-skills/skills/explore-apple-swift-docs/references/snippets/apple-xcode-project-core.md
+++ b/plugins/apple-dev-skills/skills/explore-apple-swift-docs/references/snippets/apple-xcode-project-core.md
@@ -78,6 +78,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Prefer edits through Xcode-aware project structure and keep project file changes intentional and reviewed closely.
 - 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.
 - When scripts or terminal workflows add files on disk, verify that Xcode project membership, target membership, build-phase membership, and resource-bundle inclusion all match the intended result; files appearing in the directory tree alone are not enough.
 - Direct filesystem edits outside `.pbxproj` are generally safe when Xcode is closed or when the current project is not open in Xcode, but still verify that the Xcode project picks up the intended files and memberships afterward.
 - Prefer Debug builds for everyday edit-build-test loops, but validate Release builds explicitly when optimization, packaging, launch behavior, watchdog timing, or deployment realism matters.
diff --git a/plugins/apple-dev-skills/skills/format-swift-sources/references/snippets/apple-xcode-project-core.md b/plugins/apple-dev-skills/skills/format-swift-sources/references/snippets/apple-xcode-project-core.md
index 68f1bc21..92e839cd 100644
--- a/plugins/apple-dev-skills/skills/format-swift-sources/references/snippets/apple-xcode-project-core.md
+++ b/plugins/apple-dev-skills/skills/format-swift-sources/references/snippets/apple-xcode-project-core.md
@@ -78,6 +78,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Prefer edits through Xcode-aware project structure and keep project file changes intentional and reviewed closely.
 - 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.
 - When scripts or terminal workflows add files on disk, verify that Xcode project membership, target membership, build-phase membership, and resource-bundle inclusion all match the intended result; files appearing in the directory tree alone are not enough.
 - Direct filesystem edits outside `.pbxproj` are generally safe when Xcode is closed or when the current project is not open in Xcode, but still verify that the Xcode project picks up the intended files and memberships afterward.
 - Prefer Debug builds for everyday edit-build-test loops, but validate Release builds explicitly when optimization, packaging, launch behavior, watchdog timing, or deployment realism matters.
diff --git a/plugins/apple-dev-skills/skills/safari-extension-control-workflow/references/snippets/apple-xcode-project-core.md b/plugins/apple-dev-skills/skills/safari-extension-control-workflow/references/snippets/apple-xcode-project-core.md
index 68f1bc21..92e839cd 100644
--- a/plugins/apple-dev-skills/skills/safari-extension-control-workflow/references/snippets/apple-xcode-project-core.md
+++ b/plugins/apple-dev-skills/skills/safari-extension-control-workflow/references/snippets/apple-xcode-project-core.md
@@ -78,6 +78,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Prefer edits through Xcode-aware project structure and keep project file changes intentional and reviewed closely.
 - 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.
 - When scripts or terminal workflows add files on disk, verify that Xcode project membership, target membership, build-phase membership, and resource-bundle inclusion all match the intended result; files appearing in the directory tree alone are not enough.
 - Direct filesystem edits outside `.pbxproj` are generally safe when Xcode is closed or when the current project is not open in Xcode, but still verify that the Xcode project picks up the intended files and memberships afterward.
 - Prefer Debug builds for everyday edit-build-test loops, but validate Release builds explicitly when optimization, packaging, launch behavior, watchdog timing, or deployment realism matters.
diff --git a/plugins/apple-dev-skills/skills/swift-package-build-run-workflow/references/snippets/apple-swift-package-core.md b/plugins/apple-dev-skills/skills/swift-package-build-run-workflow/references/snippets/apple-swift-package-core.md
index e6db1925..0b457687 100644
--- a/plugins/apple-dev-skills/skills/swift-package-build-run-workflow/references/snippets/apple-swift-package-core.md
+++ b/plugins/apple-dev-skills/skills/swift-package-build-run-workflow/references/snippets/apple-swift-package-core.md
@@ -72,6 +72,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Bundle precompiled Metal artifacts such as `.metallib` files as explicit package resources, and prefer `.copy(...)` when exact distribution matters more than resource processing.
 - When the requested work requires compiling Metal shaders, validating Apple-platform bundle integration, or inspecting Apple-managed components such as the Metal toolchain, hand off to the Xcode-aware workflow instead of assuming plain `swift build` is sufficient.
 - Run `swift build` and `swift test` as the default validation checks after package-level changes.
+- For Codex GUI worktree-first SwiftPM 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/swift-package.toml`, keep paths repo-relative, and do not commit machine-local dependency paths or user-specific build output paths.
 - Use `xcodebuild` for package validation when configuration-specific Apple-platform behavior matters, when test plans must be exercised, or when package builds depend on Xcode-managed SDK or Metal-toolchain behavior.
 - When package test plans are part of the contract, keep `.xctestplan` files versioned alongside the package-facing Xcode integration and exercise them explicitly with `xcodebuild -showTestPlans` and `xcodebuild -testPlan ...`.
 - Prefer normal SwiftPM parallel test execution for ordinary Swift Testing and XCTest runs. Do not serialize regular package tests just because they use Swift, XCTest, async tests, fixtures, or test plans.
diff --git a/plugins/apple-dev-skills/skills/swift-package-testing-workflow/references/snippets/apple-swift-package-core.md b/plugins/apple-dev-skills/skills/swift-package-testing-workflow/references/snippets/apple-swift-package-core.md
index e6db1925..0b457687 100644
--- a/plugins/apple-dev-skills/skills/swift-package-testing-workflow/references/snippets/apple-swift-package-core.md
+++ b/plugins/apple-dev-skills/skills/swift-package-testing-workflow/references/snippets/apple-swift-package-core.md
@@ -72,6 +72,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Bundle precompiled Metal artifacts such as `.metallib` files as explicit package resources, and prefer `.copy(...)` when exact distribution matters more than resource processing.
 - When the requested work requires compiling Metal shaders, validating Apple-platform bundle integration, or inspecting Apple-managed components such as the Metal toolchain, hand off to the Xcode-aware workflow instead of assuming plain `swift build` is sufficient.
 - Run `swift build` and `swift test` as the default validation checks after package-level changes.
+- For Codex GUI worktree-first SwiftPM 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/swift-package.toml`, keep paths repo-relative, and do not commit machine-local dependency paths or user-specific build output paths.
 - Use `xcodebuild` for package validation when configuration-specific Apple-platform behavior matters, when test plans must be exercised, or when package builds depend on Xcode-managed SDK or Metal-toolchain behavior.
 - When package test plans are part of the contract, keep `.xctestplan` files versioned alongside the package-facing Xcode integration and exercise them explicitly with `xcodebuild -showTestPlans` and `xcodebuild -testPlan ...`.
 - Prefer normal SwiftPM parallel test execution for ordinary Swift Testing and XCTest runs. Do not serialize regular package tests just because they use Swift, XCTest, async tests, fixtures, or test plans.
diff --git a/plugins/apple-dev-skills/skills/swift-package-workflow/references/snippets/apple-swift-package-core.md b/plugins/apple-dev-skills/skills/swift-package-workflow/references/snippets/apple-swift-package-core.md
index e6db1925..0b457687 100644
--- a/plugins/apple-dev-skills/skills/swift-package-workflow/references/snippets/apple-swift-package-core.md
+++ b/plugins/apple-dev-skills/skills/swift-package-workflow/references/snippets/apple-swift-package-core.md
@@ -72,6 +72,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Bundle precompiled Metal artifacts such as `.metallib` files as explicit package resources, and prefer `.copy(...)` when exact distribution matters more than resource processing.
 - When the requested work requires compiling Metal shaders, validating Apple-platform bundle integration, or inspecting Apple-managed components such as the Metal toolchain, hand off to the Xcode-aware workflow instead of assuming plain `swift build` is sufficient.
 - Run `swift build` and `swift test` as the default validation checks after package-level changes.
+- For Codex GUI worktree-first SwiftPM 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/swift-package.toml`, keep paths repo-relative, and do not commit machine-local dependency paths or user-specific build output paths.
 - Use `xcodebuild` for package validation when configuration-specific Apple-platform behavior matters, when test plans must be exercised, or when package builds depend on Xcode-managed SDK or Metal-toolchain behavior.
 - When package test plans are part of the contract, keep `.xctestplan` files versioned alongside the package-facing Xcode integration and exercise them explicitly with `xcodebuild -showTestPlans` and `xcodebuild -testPlan ...`.
 - Prefer normal SwiftPM parallel test execution for ordinary Swift Testing and XCTest runs. Do not serialize regular package tests just because they use Swift, XCTest, async tests, fixtures, or test plans.
diff --git a/plugins/apple-dev-skills/skills/swiftui-app-architecture-workflow/references/snippets/apple-xcode-project-core.md b/plugins/apple-dev-skills/skills/swiftui-app-architecture-workflow/references/snippets/apple-xcode-project-core.md
index 68f1bc21..92e839cd 100644
--- a/plugins/apple-dev-skills/skills/swiftui-app-architecture-workflow/references/snippets/apple-xcode-project-core.md
+++ b/plugins/apple-dev-skills/skills/swiftui-app-architecture-workflow/references/snippets/apple-xcode-project-core.md
@@ -78,6 +78,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Prefer edits through Xcode-aware project structure and keep project file changes intentional and reviewed closely.
 - 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.
 - When scripts or terminal workflows add files on disk, verify that Xcode project membership, target membership, build-phase membership, and resource-bundle inclusion all match the intended result; files appearing in the directory tree alone are not enough.
 - Direct filesystem edits outside `.pbxproj` are generally safe when Xcode is closed or when the current project is not open in Xcode, but still verify that the Xcode project picks up the intended files and memberships afterward.
 - Prefer Debug builds for everyday edit-build-test loops, but validate Release builds explicitly when optimization, packaging, launch behavior, watchdog timing, or deployment realism matters.
diff --git a/plugins/apple-dev-skills/skills/sync-swift-package-guidance/SKILL.md b/plugins/apple-dev-skills/skills/sync-swift-package-guidance/SKILL.md
index b0c2aa22..35437620 100644
--- a/plugins/apple-dev-skills/skills/sync-swift-package-guidance/SKILL.md
+++ b/plugins/apple-dev-skills/skills/sync-swift-package-guidance/SKILL.md
@@ -91,6 +91,7 @@ This skill can be discovered from a standalone `apple-dev-skills` install, but i
   - `repo_root=.` when omitted
   - `writeMode=sync-if-needed`
   - validation runs unless `--skip-validation` is passed
+  - successful mutating runs install `.codex/environments/swift-package.toml` from `templates/codex-local-environments/swift-package.toml` when missing, leave matching files unchanged, and preserve customized existing files
   - successful mutating runs refresh `maintain-project-repo` output in place
 
 ## Outputs
@@ -107,6 +108,7 @@ This skill can be discovered from a standalone `apple-dev-skills` install, but i
   - detected package and Xcode markers
   - `AGENTS.md` path
   - actions applied or planned
+  - installed or preserved `.codex/environments/swift-package.toml`
   - refreshed `maintain-project-repo` paths
   - validation result
   - one concise next step or handoff
@@ -118,6 +120,7 @@ This skill can be discovered from a standalone `apple-dev-skills` install, but i
 - Stop with `blocked` if the repo root looks ambiguous because it contains both `Package.swift` and Xcode app markers.
 - Stop with `blocked` if the chosen `writeMode` does not allow the mutation the repo still needs, such as creating a missing `AGENTS.md` or appending the bounded Swift package guidance section.
 - Stop with `blocked` if the target `AGENTS.md` path exists but is not a regular file.
+- Fail with a clear message if the Codex local environment template is missing or the target `.codex/environments/swift-package.toml` path exists but is not a regular file.
 
 ## Fallbacks and Handoffs
 
@@ -169,6 +172,7 @@ Keep apply-mode edits in the main thread. The steward may return proposed patch-
 - `assets/append-section.md`
 - Recommend `references/snippets/apple-swift-package-core.md` when an existing Swift package repo needs the reusable baseline policy content in a human-reviewable form.
 - `references/snippets/apple-swift-package-core.md`
+- `templates/codex-local-environments/swift-package.toml`
 
 ### Script Inventory
 
diff --git a/plugins/apple-dev-skills/skills/sync-swift-package-guidance/references/snippets/apple-swift-package-core.md b/plugins/apple-dev-skills/skills/sync-swift-package-guidance/references/snippets/apple-swift-package-core.md
index e6db1925..0b457687 100644
--- a/plugins/apple-dev-skills/skills/sync-swift-package-guidance/references/snippets/apple-swift-package-core.md
+++ b/plugins/apple-dev-skills/skills/sync-swift-package-guidance/references/snippets/apple-swift-package-core.md
@@ -72,6 +72,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Bundle precompiled Metal artifacts such as `.metallib` files as explicit package resources, and prefer `.copy(...)` when exact distribution matters more than resource processing.
 - When the requested work requires compiling Metal shaders, validating Apple-platform bundle integration, or inspecting Apple-managed components such as the Metal toolchain, hand off to the Xcode-aware workflow instead of assuming plain `swift build` is sufficient.
 - Run `swift build` and `swift test` as the default validation checks after package-level changes.
+- For Codex GUI worktree-first SwiftPM 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/swift-package.toml`, keep paths repo-relative, and do not commit machine-local dependency paths or user-specific build output paths.
 - Use `xcodebuild` for package validation when configuration-specific Apple-platform behavior matters, when test plans must be exercised, or when package builds depend on Xcode-managed SDK or Metal-toolchain behavior.
 - When package test plans are part of the contract, keep `.xctestplan` files versioned alongside the package-facing Xcode integration and exercise them explicitly with `xcodebuild -showTestPlans` and `xcodebuild -testPlan ...`.
 - Prefer normal SwiftPM parallel test execution for ordinary Swift Testing and XCTest runs. Do not serialize regular package tests just because they use Swift, XCTest, async tests, fixtures, or test plans.
diff --git a/plugins/apple-dev-skills/skills/sync-swift-package-guidance/scripts/run_workflow.py b/plugins/apple-dev-skills/skills/sync-swift-package-guidance/scripts/run_workflow.py
index 6371c0dd..8723aea7 100755
--- a/plugins/apple-dev-skills/skills/sync-swift-package-guidance/scripts/run_workflow.py
+++ b/plugins/apple-dev-skills/skills/sync-swift-package-guidance/scripts/run_workflow.py
@@ -191,6 +191,12 @@ def main() -> int:
         elif normalized_inputs["report_only"]:
             actions.append("report that AGENTS.md is missing the bounded Swift package guidance section")
 
+    local_environment_path = repo_root / ".codex" / "environments" / "swift-package.toml"
+    if local_environment_path.exists():
+        actions.append("inspect existing .codex/environments/swift-package.toml without overwriting local edits")
+    else:
+        actions.append("install .codex/environments/swift-package.toml from template")
+
     if args.dry_run:
         payload = {
             "status": "success",
diff --git a/plugins/apple-dev-skills/skills/sync-swift-package-guidance/scripts/sync_swift_package_guidance.py b/plugins/apple-dev-skills/skills/sync-swift-package-guidance/scripts/sync_swift_package_guidance.py
index 8dd006bc..b27bab09 100755
--- a/plugins/apple-dev-skills/skills/sync-swift-package-guidance/scripts/sync_swift_package_guidance.py
+++ b/plugins/apple-dev-skills/skills/sync-swift-package-guidance/scripts/sync_swift_package_guidance.py
@@ -85,6 +85,30 @@ def read_asset(name: str) -> str:
     return (Path(__file__).resolve().parents[1] / "assets" / name).read_text(encoding="utf-8").rstrip() + "\n"
 
 
+def install_local_environment(repo_root: Path) -> str:
+    template_path = (
+        Path(__file__).resolve().parents[3]
+        / "templates"
+        / "codex-local-environments"
+        / "swift-package.toml"
+    )
+    target_path = repo_root / ".codex" / "environments" / "swift-package.toml"
+
+    if not template_path.is_file():
+        raise RuntimeError(f"Codex local environment template is missing: {template_path}")
+    if target_path.exists() and not target_path.is_file():
+        raise RuntimeError(f"Codex local environment target exists but is not a regular file: {target_path}")
+
+    template_text = template_path.read_text(encoding="utf-8")
+    if not target_path.exists():
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+        target_path.write_text(template_text, encoding="utf-8")
+        return "installed .codex/environments/swift-package.toml from template"
+    if target_path.read_text(encoding="utf-8") == template_text:
+        return "left matching .codex/environments/swift-package.toml unchanged"
+    return "preserved existing .codex/environments/swift-package.toml because it differs from the template"
+
+
 def maintain_project_repo_runner() -> Path:
     script_path = Path(__file__).resolve()
     candidate_paths: list[Path] = []
@@ -242,6 +266,23 @@ def main() -> int:
             return 1
         validation_result = "validated"
 
+    try:
+        actions.append(install_local_environment(repo_root))
+    except RuntimeError as exc:
+        payload = {
+            "status": "failed",
+            "path_type": "primary",
+            "repo_root": str(repo_root),
+            "agents_path": str(agents_path),
+            "detected_state": detected_state,
+            "validation_result": validation_result,
+            "actions": actions,
+            "stderr": str(exc),
+            "next_step": "Resolve the Codex local environment template or target path issue, then rerun sync-swift-package-guidance.",
+        }
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return 1
+
     try:
         runner = maintain_project_repo_runner()
     except RuntimeError as exc:
diff --git a/plugins/apple-dev-skills/skills/sync-xcode-project-guidance/SKILL.md b/plugins/apple-dev-skills/skills/sync-xcode-project-guidance/SKILL.md
index cccea06c..f45eb35c 100644
--- a/plugins/apple-dev-skills/skills/sync-xcode-project-guidance/SKILL.md
+++ b/plugins/apple-dev-skills/skills/sync-xcode-project-guidance/SKILL.md
@@ -87,6 +87,7 @@ This skill can be discovered from a standalone `apple-dev-skills` install, but i
   - `repo_root=.` when omitted
   - `writeMode=sync-if-needed`
   - validation runs unless `--skip-validation` is passed
+  - successful mutating runs install `.codex/environments/xcode-project.toml` from `templates/codex-local-environments/xcode-project.toml` when missing, replace `SCHEME_NAME` with the workspace or project stem, leave matching files unchanged, and preserve customized existing files
   - successful mutating runs refresh `maintain-project-repo` output in place
 
 ## Outputs
@@ -103,6 +104,7 @@ This skill can be discovered from a standalone `apple-dev-skills` install, but i
   - detected workspace or project markers
   - `AGENTS.md` path
   - actions applied or planned
+  - installed or preserved `.codex/environments/xcode-project.toml`
   - refreshed `maintain-project-repo` paths
   - validation result
   - one concise next step or handoff
@@ -114,6 +116,7 @@ This skill can be discovered from a standalone `apple-dev-skills` install, but i
 - Stop with `blocked` if the repo appears to be a SwiftPM-only package without Xcode-managed app markers.
 - Stop with `blocked` if the chosen `writeMode` does not allow the mutation the repo still needs, such as creating a missing `AGENTS.md` or appending the bounded Xcode guidance section.
 - Stop with `blocked` if the target `AGENTS.md` path exists but is not a regular file.
+- Fail with a clear message if the Codex local environment template is missing or the target `.codex/environments/xcode-project.toml` path exists but is not a regular file.
 
 ## Fallbacks and Handoffs
 
@@ -164,6 +167,7 @@ Keep apply-mode edits in the main thread. The steward may return proposed patch-
 - `assets/append-section.md`
 - Recommend `references/snippets/apple-xcode-project-core.md` when an existing Xcode repo needs the reusable baseline policy content in a human-reviewable form.
 - `references/snippets/apple-xcode-project-core.md`
+- `templates/codex-local-environments/xcode-project.toml`
 
 ### Script Inventory
 
diff --git a/plugins/apple-dev-skills/skills/sync-xcode-project-guidance/references/snippets/apple-xcode-project-core.md b/plugins/apple-dev-skills/skills/sync-xcode-project-guidance/references/snippets/apple-xcode-project-core.md
index 68f1bc21..92e839cd 100644
--- a/plugins/apple-dev-skills/skills/sync-xcode-project-guidance/references/snippets/apple-xcode-project-core.md
+++ b/plugins/apple-dev-skills/skills/sync-xcode-project-guidance/references/snippets/apple-xcode-project-core.md
@@ -78,6 +78,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Prefer edits through Xcode-aware project structure and keep project file changes intentional and reviewed closely.
 - 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.
 - When scripts or terminal workflows add files on disk, verify that Xcode project membership, target membership, build-phase membership, and resource-bundle inclusion all match the intended result; files appearing in the directory tree alone are not enough.
 - Direct filesystem edits outside `.pbxproj` are generally safe when Xcode is closed or when the current project is not open in Xcode, but still verify that the Xcode project picks up the intended files and memberships afterward.
 - Prefer Debug builds for everyday edit-build-test loops, but validate Release builds explicitly when optimization, packaging, launch behavior, watchdog timing, or deployment realism matters.
diff --git a/plugins/apple-dev-skills/skills/sync-xcode-project-guidance/scripts/run_workflow.py b/plugins/apple-dev-skills/skills/sync-xcode-project-guidance/scripts/run_workflow.py
index d287aee6..e293fd63 100755
--- a/plugins/apple-dev-skills/skills/sync-xcode-project-guidance/scripts/run_workflow.py
+++ b/plugins/apple-dev-skills/skills/sync-xcode-project-guidance/scripts/run_workflow.py
@@ -172,6 +172,12 @@ def main() -> int:
         elif normalized_inputs["report_only"]:
             actions.append("report that AGENTS.md is missing the bounded Xcode guidance section")
 
+    local_environment_path = repo_root / ".codex" / "environments" / "xcode-project.toml"
+    if local_environment_path.exists():
+        actions.append("inspect existing .codex/environments/xcode-project.toml without overwriting local edits")
+    else:
+        actions.append("install .codex/environments/xcode-project.toml from template")
+
     if args.dry_run:
         payload = {
             "status": "success",
diff --git a/plugins/apple-dev-skills/skills/sync-xcode-project-guidance/scripts/sync_xcode_project_guidance.py b/plugins/apple-dev-skills/skills/sync-xcode-project-guidance/scripts/sync_xcode_project_guidance.py
index e5ac821b..9c9a4aad 100755
--- a/plugins/apple-dev-skills/skills/sync-xcode-project-guidance/scripts/sync_xcode_project_guidance.py
+++ b/plugins/apple-dev-skills/skills/sync-xcode-project-guidance/scripts/sync_xcode_project_guidance.py
@@ -58,6 +58,41 @@ def read_asset(name: str) -> str:
     return (Path(__file__).resolve().parents[1] / "assets" / name).read_text(encoding="utf-8").rstrip() + "\n"
 
 
+def local_environment_scheme_name(detected_state: dict, workspace_path: str | None) -> str:
+    if workspace_path:
+        return Path(workspace_path).stem
+    for key in ("workspace", "project"):
+        value = detected_state.get(key)
+        if value:
+            return Path(value).stem
+    return "SCHEME_NAME"
+
+
+def install_local_environment(repo_root: Path, detected_state: dict, workspace_path: str | None) -> str:
+    template_path = (
+        Path(__file__).resolve().parents[3]
+        / "templates"
+        / "codex-local-environments"
+        / "xcode-project.toml"
+    )
+    target_path = repo_root / ".codex" / "environments" / "xcode-project.toml"
+
+    if not template_path.is_file():
+        raise RuntimeError(f"Codex local environment template is missing: {template_path}")
+    if target_path.exists() and not target_path.is_file():
+        raise RuntimeError(f"Codex local environment target exists but is not a regular file: {target_path}")
+
+    scheme_name = local_environment_scheme_name(detected_state, workspace_path)
+    template_text = template_path.read_text(encoding="utf-8").replace("SCHEME_NAME", scheme_name)
+    if not target_path.exists():
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+        target_path.write_text(template_text, encoding="utf-8")
+        return f"installed .codex/environments/xcode-project.toml from template with scheme {scheme_name}"
+    if target_path.read_text(encoding="utf-8") == template_text:
+        return "left matching .codex/environments/xcode-project.toml unchanged"
+    return "preserved existing .codex/environments/xcode-project.toml because it differs from the template"
+
+
 def maintain_project_repo_runner() -> Path:
     script_path = Path(__file__).resolve()
     candidate_paths: list[Path] = []
@@ -200,6 +235,23 @@ def main() -> int:
             return 1
         validation_result = "validated"
 
+    try:
+        actions.append(install_local_environment(repo_root, detected_state, args.workspace_path))
+    except RuntimeError as exc:
+        payload = {
+            "status": "failed",
+            "path_type": "primary",
+            "repo_root": str(repo_root),
+            "agents_path": str(agents_path),
+            "detected_state": detected_state,
+            "validation_result": validation_result,
+            "actions": actions,
+            "stderr": str(exc),
+            "next_step": "Resolve the Codex local environment template or target path issue, then rerun sync-xcode-project-guidance.",
+        }
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return 1
+
     try:
         runner = maintain_project_repo_runner()
     except RuntimeError as exc:
diff --git a/plugins/apple-dev-skills/skills/xcode-app-project-workflow/references/snippets/apple-xcode-project-core.md b/plugins/apple-dev-skills/skills/xcode-app-project-workflow/references/snippets/apple-xcode-project-core.md
index 68f1bc21..92e839cd 100644
--- a/plugins/apple-dev-skills/skills/xcode-app-project-workflow/references/snippets/apple-xcode-project-core.md
+++ b/plugins/apple-dev-skills/skills/xcode-app-project-workflow/references/snippets/apple-xcode-project-core.md
@@ -78,6 +78,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Prefer edits through Xcode-aware project structure and keep project file changes intentional and reviewed closely.
 - 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.
 - When scripts or terminal workflows add files on disk, verify that Xcode project membership, target membership, build-phase membership, and resource-bundle inclusion all match the intended result; files appearing in the directory tree alone are not enough.
 - Direct filesystem edits outside `.pbxproj` are generally safe when Xcode is closed or when the current project is not open in Xcode, but still verify that the Xcode project picks up the intended files and memberships afterward.
 - Prefer Debug builds for everyday edit-build-test loops, but validate Release builds explicitly when optimization, packaging, launch behavior, watchdog timing, or deployment realism matters.
diff --git a/plugins/apple-dev-skills/skills/xcode-build-run-workflow/references/snippets/apple-xcode-project-core.md b/plugins/apple-dev-skills/skills/xcode-build-run-workflow/references/snippets/apple-xcode-project-core.md
index 68f1bc21..92e839cd 100644
--- a/plugins/apple-dev-skills/skills/xcode-build-run-workflow/references/snippets/apple-xcode-project-core.md
+++ b/plugins/apple-dev-skills/skills/xcode-build-run-workflow/references/snippets/apple-xcode-project-core.md
@@ -78,6 +78,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Prefer edits through Xcode-aware project structure and keep project file changes intentional and reviewed closely.
 - 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.
 - When scripts or terminal workflows add files on disk, verify that Xcode project membership, target membership, build-phase membership, and resource-bundle inclusion all match the intended result; files appearing in the directory tree alone are not enough.
 - Direct filesystem edits outside `.pbxproj` are generally safe when Xcode is closed or when the current project is not open in Xcode, but still verify that the Xcode project picks up the intended files and memberships afterward.
 - Prefer Debug builds for everyday edit-build-test loops, but validate Release builds explicitly when optimization, packaging, launch behavior, watchdog timing, or deployment realism matters.
diff --git a/plugins/apple-dev-skills/skills/xcode-testing-workflow/references/snippets/apple-xcode-project-core.md b/plugins/apple-dev-skills/skills/xcode-testing-workflow/references/snippets/apple-xcode-project-core.md
index 68f1bc21..92e839cd 100644
--- a/plugins/apple-dev-skills/skills/xcode-testing-workflow/references/snippets/apple-xcode-project-core.md
+++ b/plugins/apple-dev-skills/skills/xcode-testing-workflow/references/snippets/apple-xcode-project-core.md
@@ -78,6 +78,7 @@ Use this snippet in repository `AGENTS.md` files when you want baseline standard
 - Prefer edits through Xcode-aware project structure and keep project file changes intentional and reviewed closely.
 - 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.
 - When scripts or terminal workflows add files on disk, verify that Xcode project membership, target membership, build-phase membership, and resource-bundle inclusion all match the intended result; files appearing in the directory tree alone are not enough.
 - Direct filesystem edits outside `.pbxproj` are generally safe when Xcode is closed or when the current project is not open in Xcode, but still verify that the Xcode project picks up the intended files and memberships afterward.
 - Prefer Debug builds for everyday edit-build-test loops, but validate Release builds explicitly when optimization, packaging, launch behavior, watchdog timing, or deployment realism matters.
diff --git a/plugins/apple-dev-skills/templates/codex-local-environments/swift-package.toml b/plugins/apple-dev-skills/templates/codex-local-environments/swift-package.toml
new file mode 100644
index 00000000..0d264329
--- /dev/null
+++ b/plugins/apple-dev-skills/templates/codex-local-environments/swift-package.toml
@@ -0,0 +1,21 @@
+# Copy to .codex/environments/swift-package.toml and adjust action names if needed.
+version = 1
+name = "swift-package"
+
+[setup]
+script = "swift package resolve"
+
+[[actions]]
+name = "resolve"
+icon = "tool"
+command = "swift package resolve"
+
+[[actions]]
+name = "build"
+icon = "tool"
+command = "swift build"
+
+[[actions]]
+name = "test"
+icon = "tool"
+command = "swift test"
diff --git a/plugins/apple-dev-skills/templates/codex-local-environments/xcode-project.toml b/plugins/apple-dev-skills/templates/codex-local-environments/xcode-project.toml
new file mode 100644
index 00000000..9f9fb609
--- /dev/null
+++ b/plugins/apple-dev-skills/templates/codex-local-environments/xcode-project.toml
@@ -0,0 +1,22 @@
+# Copy to .codex/environments/xcode-project.toml and replace SCHEME_NAME.
+# Keep DerivedData inside the worktree so Codex GUI worktree validation is isolated.
+version = 1
+name = "xcode-project"
+
+[setup]
+script = "xcodebuild -scheme SCHEME_NAME -derivedDataPath ./DerivedData -resolvePackageDependencies"
+
+[[actions]]
+name = "resolve packages"
+icon = "tool"
+command = "xcodebuild -scheme SCHEME_NAME -derivedDataPath ./DerivedData -resolvePackageDependencies"
+
+[[actions]]
+name = "build"
+icon = "tool"
+command = "xcodebuild -scheme SCHEME_NAME -derivedDataPath ./DerivedData build"
+
+[[actions]]
+name = "test"
+icon = "tool"
+command = "xcodebuild -scheme SCHEME_NAME -derivedDataPath ./DerivedData test"
diff --git a/plugins/apple-dev-skills/tests/test_bootstrap_workflow.py b/plugins/apple-dev-skills/tests/test_bootstrap_workflow.py
index bd659eda..61d7b20c 100644
--- a/plugins/apple-dev-skills/tests/test_bootstrap_workflow.py
+++ b/plugins/apple-dev-skills/tests/test_bootstrap_workflow.py
@@ -78,6 +78,7 @@ def test_wrapper_injects_runtime_defaults(self) -> None:
             self.assertEqual(payload["normalized_inputs"]["testing_mode"], "xctest")
             self.assertFalse(payload["normalized_inputs"]["initialize_git"])
             self.assertFalse(payload["normalized_inputs"]["copy_agents_md"])
+            self.assertIsNone(payload.get("local_environment_installed"))
             self.assertEqual(payload["testing_strategy"], "init-flags")
             self.assertIn("--testing-mode", payload["command"])
             self.assertIn("xctest", payload["command"])
diff --git a/plugins/apple-dev-skills/tests/test_swift_package_guidance_sync_workflow.py b/plugins/apple-dev-skills/tests/test_swift_package_guidance_sync_workflow.py
index 115b08e6..1f7edbac 100644
--- a/plugins/apple-dev-skills/tests/test_swift_package_guidance_sync_workflow.py
+++ b/plugins/apple-dev-skills/tests/test_swift_package_guidance_sync_workflow.py
@@ -146,6 +146,12 @@ def test_sync_creates_agents_template(self) -> None:
                 'REPO_MAINTENANCE_PROFILE="swift-package"',
                 Path(tmpdir, "scripts/repo-maintenance/config/profile.env").read_text(encoding="utf-8"),
             )
+            local_environment_path = Path(tmpdir, ".codex/environments/swift-package.toml")
+            self.assertTrue(local_environment_path.is_file())
+            local_environment_text = local_environment_path.read_text(encoding="utf-8")
+            self.assertIn('name = "swift-package"', local_environment_text)
+            self.assertIn('command = "swift test"', local_environment_text)
+            self.assertIn("installed .codex/environments/swift-package.toml from template", payload["actions"])
             self.assertTrue(Path(tmpdir, ".github/workflows/validate-repo-maintenance.yml").is_file())
             workflow_text = Path(tmpdir, ".github/workflows/validate-repo-maintenance.yml").read_text(encoding="utf-8")
             self.assertIn("Branch protection should require the Actions check context `validate`.", workflow_text)
@@ -233,6 +239,27 @@ def test_sync_appends_section_to_existing_agents(self) -> None:
                 Path(tmpdir, "scripts/repo-maintenance/config/profile.env").read_text(encoding="utf-8"),
             )
 
+    def test_sync_preserves_existing_local_environment(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            repo_root = Path(tmpdir)
+            (repo_root / "Package.swift").write_text("// swift-tools-version: 6.0\n", encoding="utf-8")
+            local_environment_path = repo_root / ".codex/environments/swift-package.toml"
+            local_environment_path.parent.mkdir(parents=True)
+            local_environment_path.write_text('version = 1\nname = "custom-swift-package"\n', encoding="utf-8")
+
+            code, payload = self.run_script("--repo-root", tmpdir)
+
+            self.assertEqual(code, 0)
+            self.assertEqual(payload["status"], "success")
+            self.assertEqual(
+                local_environment_path.read_text(encoding="utf-8"),
+                'version = 1\nname = "custom-swift-package"\n',
+            )
+            self.assertIn(
+                "preserved existing .codex/environments/swift-package.toml because it differs from the template",
+                payload["actions"],
+            )
+
     def test_write_mode_can_disable_append_behavior(self) -> None:
         with tempfile.TemporaryDirectory() as tmpdir:
             Path(tmpdir, "Package.swift").write_text("// swift-tools-version: 6.0\n", encoding="utf-8")
@@ -277,6 +304,7 @@ def test_sync_discovers_socket_cache_sibling_productivity_runner(self) -> None:
                 / "maintain-project-repo"
             )
             shutil.copytree(ROOT / "skills/sync-swift-package-guidance", apple_skill)
+            shutil.copytree(ROOT / "templates", cache_root / "apple-dev-skills" / "6.5.1" / "templates")
             shutil.copytree(ROOT.parent / "productivity-skills/skills/maintain-project-repo", productivity_skill)
 
             repo_root = Path(tmpdir) / "Repo"
diff --git a/plugins/apple-dev-skills/tests/test_xcode_app_bootstrap_workflow.py b/plugins/apple-dev-skills/tests/test_xcode_app_bootstrap_workflow.py
index 1183db46..72d7a312 100644
--- a/plugins/apple-dev-skills/tests/test_xcode_app_bootstrap_workflow.py
+++ b/plugins/apple-dev-skills/tests/test_xcode_app_bootstrap_workflow.py
@@ -199,6 +199,11 @@ def test_xcodegen_path_can_succeed_with_fake_tools(self) -> None:
                 (target / "Configurations" / "App-Shared.xcconfig").read_text(encoding="utf-8"),
             )
             self.assertTrue((target / "AGENTS.md").exists())
+            local_environment_path = target / ".codex" / "environments" / "xcode-project.toml"
+            self.assertTrue(local_environment_path.exists())
+            local_environment_text = local_environment_path.read_text(encoding="utf-8")
+            self.assertIn("xcodebuild -scheme DemoApp -derivedDataPath ./DerivedData build", local_environment_text)
+            self.assertEqual(payload["local_environment_path"], str(local_environment_path))
             agents_text = (target / "AGENTS.md").read_text(encoding="utf-8")
             self.assertIn("xcode-build-run-workflow", agents_text)
             self.assertIn("xcode-testing-workflow", agents_text)
diff --git a/plugins/apple-dev-skills/tests/test_xcode_guidance_sync_workflow.py b/plugins/apple-dev-skills/tests/test_xcode_guidance_sync_workflow.py
index eade56da..9693e78e 100644
--- a/plugins/apple-dev-skills/tests/test_xcode_guidance_sync_workflow.py
+++ b/plugins/apple-dev-skills/tests/test_xcode_guidance_sync_workflow.py
@@ -92,6 +92,15 @@ def test_sync_creates_agents_template(self) -> None:
                 'REPO_MAINTENANCE_PROFILE="xcode-app"',
                 Path(tmpdir, "scripts/repo-maintenance/config/profile.env").read_text(encoding="utf-8"),
             )
+            local_environment_path = Path(tmpdir, ".codex/environments/xcode-project.toml")
+            self.assertTrue(local_environment_path.is_file())
+            local_environment_text = local_environment_path.read_text(encoding="utf-8")
+            self.assertIn('name = "xcode-project"', local_environment_text)
+            self.assertIn("xcodebuild -scheme Demo -derivedDataPath ./DerivedData test", local_environment_text)
+            self.assertIn(
+                "installed .codex/environments/xcode-project.toml from template with scheme Demo",
+                payload["actions"],
+            )
             self.assertTrue(Path(tmpdir, ".github/workflows/validate-repo-maintenance.yml").is_file())
             workflow_text = Path(tmpdir, ".github/workflows/validate-repo-maintenance.yml").read_text(encoding="utf-8")
             self.assertIn("Branch protection should require the Actions check context `validate`.", workflow_text)
@@ -127,6 +136,24 @@ def test_sync_appends_section_to_existing_agents(self) -> None:
                 Path(tmpdir, "scripts/repo-maintenance/config/profile.env").read_text(encoding="utf-8"),
             )
 
+    def test_sync_preserves_existing_local_environment(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            repo_root = Path(tmpdir)
+            (repo_root / "Demo.xcodeproj").mkdir()
+            local_environment_path = repo_root / ".codex/environments/xcode-project.toml"
+            local_environment_path.parent.mkdir(parents=True)
+            local_environment_path.write_text('version = 1\nname = "custom-xcode"\n', encoding="utf-8")
+
+            code, payload = self.run_script("--repo-root", tmpdir)
+
+            self.assertEqual(code, 0)
+            self.assertEqual(payload["status"], "success")
+            self.assertEqual(local_environment_path.read_text(encoding="utf-8"), 'version = 1\nname = "custom-xcode"\n')
+            self.assertIn(
+                "preserved existing .codex/environments/xcode-project.toml because it differs from the template",
+                payload["actions"],
+            )
+
     def test_write_mode_can_disable_append_behavior(self) -> None:
         with tempfile.TemporaryDirectory() as tmpdir:
             Path(tmpdir, "Demo.xcodeproj").mkdir()
@@ -171,6 +198,7 @@ def test_sync_discovers_socket_cache_sibling_productivity_runner(self) -> None:
                 / "maintain-project-repo"
             )
             shutil.copytree(ROOT / "skills/sync-xcode-project-guidance", apple_skill)
+            shutil.copytree(ROOT / "templates", cache_root / "apple-dev-skills" / "6.5.1" / "templates")
             shutil.copytree(ROOT.parent / "productivity-skills/skills/maintain-project-repo", productivity_skill)
 
             repo_root = Path(tmpdir) / "Repo"
diff --git a/plugins/apple-dev-skills/uv.lock b/plugins/apple-dev-skills/uv.lock
index 8f5f4020..f46427e6 100644
--- a/plugins/apple-dev-skills/uv.lock
+++ b/plugins/apple-dev-skills/uv.lock
@@ -8,7 +8,7 @@ resolution-markers = [
 
 [[package]]
 name = "apple-dev-skills-maintainer"
-version = "6.16.2"
+version = "6.17.0"
 source = { virtual = "." }
 
 [package.dev-dependencies]
diff --git a/plugins/cardhop-app/.codex-plugin/plugin.json b/plugins/cardhop-app/.codex-plugin/plugin.json
index cf98617f..cd4c1286 100644
--- a/plugins/cardhop-app/.codex-plugin/plugin.json
+++ b/plugins/cardhop-app/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "cardhop-app",
-  "version": "6.16.2",
+  "version": "6.17.0",
   "description": "Cardhop.app workflow guidance plus a bundled local MCP server for contact capture and updates on macOS.",
   "author": {
     "name": "Gale",
diff --git a/plugins/cardhop-app/mcp/pyproject.toml b/plugins/cardhop-app/mcp/pyproject.toml
index 73a20302..309e2e05 100644
--- a/plugins/cardhop-app/mcp/pyproject.toml
+++ b/plugins/cardhop-app/mcp/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "cardhop-app-mcp"
-version = "6.16.2"
+version = "6.17.0"
 requires-python = ">=3.13"
 dependencies = [
     "fastmcp>=3.0.2",
diff --git a/plugins/cardhop-app/mcp/uv.lock b/plugins/cardhop-app/mcp/uv.lock
index 4fc23d35..d104c0e4 100644
--- a/plugins/cardhop-app/mcp/uv.lock
+++ b/plugins/cardhop-app/mcp/uv.lock
@@ -93,7 +93,7 @@ wheels = [
 
 [[package]]
 name = "cardhop-app-mcp"
-version = "6.16.2"
+version = "6.17.0"
 source = { virtual = "." }
 dependencies = [
     { name = "fastmcp" },
diff --git a/plugins/codex-utilities/.codex-plugin/plugin.json b/plugins/codex-utilities/.codex-plugin/plugin.json
index 88a986f4..bce5b006 100644
--- a/plugins/codex-utilities/.codex-plugin/plugin.json
+++ b/plugins/codex-utilities/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "codex-utilities",
-  "version": "6.16.2",
+  "version": "6.17.0",
   "description": "Local Codex runtime utilities for thread, hook, and app-server workflows.",
   "author": {
     "name": "Gale",
diff --git a/plugins/dotnet-skills/.codex-plugin/plugin.json b/plugins/dotnet-skills/.codex-plugin/plugin.json
index 44e1bacf..6d437d5d 100644
--- a/plugins/dotnet-skills/.codex-plugin/plugin.json
+++ b/plugins/dotnet-skills/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "dotnet-skills",
-  "version": "6.16.2",
+  "version": "6.17.0",
   "description": "Codex skills for choosing, bootstrapping, building, testing, packaging, diagnosing, and maintaining .NET projects with F# and C# as equal first-party languages.",
   "author": {
     "name": "Gale",
diff --git a/plugins/productivity-skills/.codex-plugin/plugin.json b/plugins/productivity-skills/.codex-plugin/plugin.json
index 35b5e9e1..433c4489 100644
--- a/plugins/productivity-skills/.codex-plugin/plugin.json
+++ b/plugins/productivity-skills/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "productivity-skills",
-  "version": "6.16.2",
+  "version": "6.17.0",
   "description": "Broadly useful productivity workflows for Codex.",
   "author": {
     "name": "Gale",
@@ -22,7 +22,7 @@
   "interface": {
     "displayName": "Productivity Skills",
     "shortDescription": "Broadly useful workflow and maintainer skills for Codex.",
-    "longDescription": "Bundle general-purpose productivity and repository-maintenance skills for documentation, accessibility standards, roadmap work, code explanation, agent automation design, agent eval design, and reusable maintainer-toolkit workflows.",
+    "longDescription": "Bundle general-purpose productivity and repository-maintenance skills for documentation, accessibility standards, roadmap work, code explanation, Codex GUI worktree workflow planning, agent automation design, agent eval design, and reusable maintainer-toolkit workflows.",
     "developerName": "Gale",
     "category": "Productivity",
     "capabilities": [
@@ -33,6 +33,7 @@
     "defaultPrompt": [
       "Install or refresh the repo-maintenance toolkit for this project and explain the local entrypoints.",
       "Explain this code slice in plain language and compare the relevant alternatives.",
+      "Plan a Codex GUI worktree-first workflow for this repo, including local environments, actions, sandbox notes, and stack handoffs.",
       "Design an agent or automation workflow and choose the smallest suitable surface before implementation.",
       "Design evals for an agent, skill, prompt, or automation and decide whether it is fit for safe full automation.",
       "Help me update the README, AGENTS guidance, accessibility standards, roadmap, or maintainer docs without flattening the existing structure."
diff --git a/plugins/productivity-skills/docs/maintainers/codex-gui-worktree-guidance.md b/plugins/productivity-skills/docs/maintainers/codex-gui-worktree-guidance.md
new file mode 100644
index 00000000..8d2db382
--- /dev/null
+++ b/plugins/productivity-skills/docs/maintainers/codex-gui-worktree-guidance.md
@@ -0,0 +1,31 @@
+# Codex GUI Worktree Guidance
+
+Use this maintainer note when updating `productivity-skills:codex-gui-worktree-workflow`.
+
+This workflow owns general Codex app worktree-first planning: which worktree surface to use, how to talk about Codex local environments, and where stack-specific setup or action commands should be delegated.
+
+## Ownership Boundary
+
+- `productivity-skills` owns general Codex GUI workflow choice and repo guidance shape.
+- `apple-dev-skills` owns SwiftPM and Xcode local environment templates.
+- `server-side-swift` owns Vapor, Hummingbird, and server-side Swift local environment templates.
+- Other stack plugins own their stack-specific build, test, run, and setup actions.
+- Worktrunk bridge implementation belongs to its own integration work, not this workflow skill.
+
+## Required Claims
+
+Refresh official Codex docs before changing product-behavior wording. Keep these claims aligned with current docs:
+
+- Codex GUI Worktree mode uses Git worktrees plus app-managed thread association, handoff, snapshots, cleanup, review pane state, local environment setup, and actions.
+- Permanent Codex worktrees are the app-visible long-lived branch option.
+- Plain Git and Worktrunk-managed worktrees are terminal-first unless opened as their own Codex app project or path-specific thread.
+- Local environment files should be portable and repo-owned.
+- Auto-review reviews approval requests but does not expand the sandbox boundary.
+
+## Official References
+
+- [OpenAI Codex app worktrees](https://developers.openai.com/codex/app/worktrees)
+- [OpenAI Codex local environments](https://developers.openai.com/codex/app/local-environments)
+- [OpenAI Codex app features](https://developers.openai.com/codex/app/features)
+- [OpenAI Codex sandboxing](https://developers.openai.com/codex/concepts/sandboxing)
+- [OpenAI Codex auto-review](https://developers.openai.com/codex/concepts/sandboxing/auto-review)
diff --git a/plugins/productivity-skills/pyproject.toml b/plugins/productivity-skills/pyproject.toml
index 6b669d39..8756882f 100644
--- a/plugins/productivity-skills/pyproject.toml
+++ b/plugins/productivity-skills/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "productivity-skills-maintenance"
-version = "6.16.2"
+version = "6.17.0"
 description = "Maintainer-only Python tooling baseline for productivity-skills."
 requires-python = ">=3.11"
 dependencies = []
diff --git a/plugins/productivity-skills/skills/codex-gui-worktree-workflow/SKILL.md b/plugins/productivity-skills/skills/codex-gui-worktree-workflow/SKILL.md
new file mode 100644
index 00000000..022b2bab
--- /dev/null
+++ b/plugins/productivity-skills/skills/codex-gui-worktree-workflow/SKILL.md
@@ -0,0 +1,77 @@
+---
+name: codex-gui-worktree-workflow
+description: Plan and align Codex GUI worktree-first workflows, local environments, actions, permanent worktrees, and handoffs to Git or Worktrunk worktrees. Use when a repo should make Codex app Worktree mode easier to use without mixing stack-specific commands into general guidance.
+---
+
+# Codex GUI Worktree Workflow
+
+## Purpose
+
+Make Codex GUI worktree-first development easier to use by choosing the right worktree mode, local environment shape, action set, and stack-specific handoff.
+
+This is a general productivity workflow. It owns the Codex app workflow decision and repo-facing guidance shape. It does not own SwiftPM, Xcode, Vapor, Hummingbird, JavaScript, Python, Rust, or other stack-specific build commands; use the relevant stack plugin for those templates and validation details.
+
+## When To Use
+
+- Use this skill when a repository should prefer Codex GUI Worktree mode for Codex-started tasks.
+- Use this skill when the user wants Codex local environments, setup scripts, and app action buttons planned or aligned.
+- Use this skill when choosing between Codex GUI managed worktrees, permanent Codex worktrees, plain Git worktrees, and Worktrunk-managed worktrees.
+- Use this skill when repo guidance should explain how Codex GUI worktrees differ from terminal-created worktrees.
+- Do not use this skill to implement stack-specific build, test, run, or simulator commands. Hand those to the owning stack plugin.
+- Do not use this skill to build a Worktrunk bridge. Treat that as a separate integration project.
+
+## Workflow
+
+1. Refresh current Codex docs before making product-behavior claims:
+   - Codex app worktrees
+   - Codex local environments
+   - Codex app features
+   - Codex sandboxing and auto-review
+2. Inspect the target repo shape:
+   - Git repository state and worktree list
+   - existing `.codex/environments/*.toml`
+   - repo `AGENTS.md`
+   - existing validation or maintainer scripts
+   - stack markers such as `Package.swift`, `.xcodeproj`, `pyproject.toml`, `package.json`, `Cargo.toml`, or service framework files
+3. Choose the worktree strategy:
+   - Codex GUI Worktree mode for Codex-started isolated tasks
+   - permanent Codex worktree for long-lived branches that should stay visible as app projects
+   - plain Git or Worktrunk-managed worktree for terminal-first branch management
+   - path-specific new Codex thread or app project when a terminal-created worktree should become a GUI workspace
+4. Shape general repo guidance:
+   - explain that Codex GUI worktrees are Git worktrees plus app-owned thread association, handoff, snapshots, cleanup, review pane state, local environment setup, and action buttons
+   - explain that terminal-created Git or Worktrunk worktrees are not automatically Codex-managed app worktrees
+   - state that auto-review reviews approval requests without expanding writable roots or sandbox permissions
+   - keep `.codex/environments/*.toml` portable and repo-owned
+5. Delegate stack-specific commands:
+   - Apple SwiftPM or Xcode commands: use `apple-dev-skills`
+   - server-side Swift commands: use `server-side-swift`
+   - Python commands: use `python-skills`
+   - Rust commands: use `rust-skills`
+   - .NET commands: use `dotnet-skills`
+   - JavaScript or TypeScript commands: use the repo's owning web or Node workflow
+6. If the user asks for implementation, create or update only the general guidance and general local environment structure here; apply stack-specific templates from the owning plugin.
+
+## Output Contract
+
+Return a concise plan or implementation summary with:
+
+- `Worktree Mode`: local, Codex GUI worktree, permanent Codex worktree, Git worktree, or Worktrunk-managed worktree
+- `Local Environment`: setup script and action button plan
+- `Stack Handoff`: owning plugin or repo script for stack-specific commands
+- `Sandbox Notes`: approval and writable-root implications
+- `Files`: `.codex/environments`, `AGENTS.md`, or docs touched or proposed
+- `Validation`: commands run or intentionally skipped
+
+## Guardrails
+
+- Do not claim Codex can control where Codex-managed worktrees are created if current docs say it cannot.
+- Do not treat shell `cwd` changes as moving an existing Codex GUI project.
+- Do not commit machine-local absolute paths, private checkout paths, user-specific DerivedData locations, secrets, local package paths, or local dependency paths.
+- Do not make global `danger-full-access` or broad writable-root changes as a convenience fix for noisy approvals.
+- Do not imply auto-review expands the sandbox boundary.
+- Do not put stack-specific command templates in this productivity skill when an owning stack plugin exists.
+
+## References
+
+- `references/codex-gui-worktree-guidance.md`
diff --git a/plugins/productivity-skills/skills/codex-gui-worktree-workflow/agents/openai.yaml b/plugins/productivity-skills/skills/codex-gui-worktree-workflow/agents/openai.yaml
new file mode 100644
index 00000000..c2062786
--- /dev/null
+++ b/plugins/productivity-skills/skills/codex-gui-worktree-workflow/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "Codex GUI Worktree Workflow"
+  short_description: "Plan Codex app worktree-first workflows, local environments, actions, and stack handoffs."
+  default_prompt: "Use $codex-gui-worktree-workflow to plan or align a repo for Codex GUI worktree-first development, choose between Codex managed worktrees, permanent Codex worktrees, plain Git worktrees, and Worktrunk-managed worktrees, keep local environment files portable, explain sandbox and auto-review boundaries, and hand stack-specific build, test, run, or Xcode commands to the owning stack plugin."
diff --git a/plugins/productivity-skills/skills/codex-gui-worktree-workflow/references/codex-gui-worktree-guidance.md b/plugins/productivity-skills/skills/codex-gui-worktree-workflow/references/codex-gui-worktree-guidance.md
new file mode 100644
index 00000000..21166761
--- /dev/null
+++ b/plugins/productivity-skills/skills/codex-gui-worktree-workflow/references/codex-gui-worktree-guidance.md
@@ -0,0 +1,52 @@
+# Codex GUI Worktree Guidance
+
+Use this reference when a repo wants Codex GUI worktree-first development as the default collaboration shape.
+
+## Worktree Surfaces
+
+- Codex GUI Worktree mode is best for Codex-started isolated work because the app owns thread association, handoff, snapshots, cleanup, review pane state, setup scripts, and action buttons.
+- Permanent Codex worktrees are best for long-lived branches that should stay visible as app projects.
+- Plain Git worktrees and Worktrunk-managed worktrees are best for terminal-first branch management. Open those paths as their own Codex app project or path-specific new thread when the GUI should work there.
+- Worktrunk bridge work belongs to a separate integration project, not to ordinary repo guidance.
+
+## Local Environment Shape
+
+Local environment files should live under `.codex/environments/` in the target repo when they are meant to be shared. Keep them portable:
+
+- no machine-local absolute paths
+- no private checkout paths
+- no local dependency paths
+- no user-specific DerivedData locations
+- no secrets
+
+Use setup scripts for worktree initialization and actions for common commands the user should run from the Codex app top bar.
+
+## Stack Handoffs
+
+General workflow guidance belongs here. Stack commands belong elsewhere:
+
+- Apple SwiftPM and Xcode templates: `apple-dev-skills`
+- server-side Swift service templates: `server-side-swift`
+- Python commands: `python-skills`
+- Rust commands: `rust-skills`
+- .NET commands: `dotnet-skills`
+- JavaScript or TypeScript commands: the repo's owning web or Node workflow
+
+## Sandbox And Auto-Review
+
+Auto-review changes who reviews approval requests. It does not expand writable roots, allow protected paths, or make arbitrary Git metadata writable.
+
+If worktree workflows create too many mundane reviews, fix the boundary or command shape first:
+
+- keep build output inside the worktree when the stack supports it
+- use repo-owned scripts for repeatable commands
+- use narrow command prefix rules only for commands the user actually trusts
+- avoid broad full-access defaults
+
+## Official References
+
+- [OpenAI Codex app worktrees](https://developers.openai.com/codex/app/worktrees)
+- [OpenAI Codex local environments](https://developers.openai.com/codex/app/local-environments)
+- [OpenAI Codex app features](https://developers.openai.com/codex/app/features)
+- [OpenAI Codex sandboxing](https://developers.openai.com/codex/concepts/sandboxing)
+- [OpenAI Codex auto-review](https://developers.openai.com/codex/concepts/sandboxing/auto-review)
diff --git a/plugins/productivity-skills/uv.lock b/plugins/productivity-skills/uv.lock
index c29351f7..3e0ce6d0 100644
--- a/plugins/productivity-skills/uv.lock
+++ b/plugins/productivity-skills/uv.lock
@@ -40,7 +40,7 @@ wheels = [
 
 [[package]]
 name = "productivity-skills-maintenance"
-version = "6.16.2"
+version = "6.17.0"
 source = { virtual = "." }
 
 [package.dev-dependencies]
diff --git a/plugins/python-skills/.codex-plugin/plugin.json b/plugins/python-skills/.codex-plugin/plugin.json
index 6385571b..a494eabb 100644
--- a/plugins/python-skills/.codex-plugin/plugin.json
+++ b/plugins/python-skills/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "python-skills",
-  "version": "6.16.2",
+  "version": "6.17.0",
   "description": "Bundled Python-focused Codex skills for uv bootstrapping, project implementation, diagnostics, packaging, tooling, CI, upgrades, FastAPI, FastMCP, and pytest workflows.",
   "author": {
     "name": "Gale",
diff --git a/plugins/python-skills/pyproject.toml b/plugins/python-skills/pyproject.toml
index 74d393be..99c5cdbf 100644
--- a/plugins/python-skills/pyproject.toml
+++ b/plugins/python-skills/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "python-skills-maintainer"
-version = "6.16.2"
+version = "6.17.0"
 description = "Maintainer tooling for the python-skills repository"
 requires-python = ">=3.11"
 dependencies = []
diff --git a/plugins/python-skills/uv.lock b/plugins/python-skills/uv.lock
index 93c50625..a3f5420e 100644
--- a/plugins/python-skills/uv.lock
+++ b/plugins/python-skills/uv.lock
@@ -206,7 +206,7 @@ wheels = [
 
 [[package]]
 name = "python-skills-maintainer"
-version = "6.16.2"
+version = "6.17.0"
 source = { virtual = "." }
 
 [package.dev-dependencies]
diff --git a/plugins/rust-skills/.codex-plugin/plugin.json b/plugins/rust-skills/.codex-plugin/plugin.json
index 6156174a..47076f0d 100644
--- a/plugins/rust-skills/.codex-plugin/plugin.json
+++ b/plugins/rust-skills/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "rust-skills",
-  "version": "6.16.2",
+  "version": "6.17.0",
   "description": "Rust, Cargo, rustup, crate, workspace, CLI, library, package, CI, testing, linting, and formatting workflow skills.",
   "skills": "./skills/",
   "author": {
diff --git a/plugins/server-side-swift/.codex-plugin/plugin.json b/plugins/server-side-swift/.codex-plugin/plugin.json
index af225095..38546b39 100644
--- a/plugins/server-side-swift/.codex-plugin/plugin.json
+++ b/plugins/server-side-swift/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "server-side-swift",
-  "version": "6.16.2",
+  "version": "6.17.0",
   "description": "Codex skills for building, running, containerizing, and maintaining server-side Swift services, including Vapor, Hummingbird, persistence, Swift OpenAPI, RPC-fit decisions, Docker, Apple Containerization, and SwiftPM-first workflows.",
   "author": {
     "name": "Gale",
diff --git a/plugins/server-side-swift/AGENTS.md b/plugins/server-side-swift/AGENTS.md
index 50b0a62c..a856c765 100644
--- a/plugins/server-side-swift/AGENTS.md
+++ b/plugins/server-side-swift/AGENTS.md
@@ -13,6 +13,7 @@ This file is the Server-Side Swift child-plugin override for work done from `soc
 
 - Match the `socket` shared semantic version exactly; use the Socket root release workflow for version inventory and bumps.
 - Prefer Swift Package Manager as the source of truth for server-side Swift package structure, dependencies, builds, tests, and run commands.
+- For Codex GUI worktree-first server-side Swift repos, keep local environment files portable and repo-owned. Start from `templates/codex-local-environments/`, keep paths repo-relative, and adjust executable names instead of committing machine-local paths.
 - Use official framework documentation first for server-side Swift libraries and tools. For Vapor work, use the official Vapor docs before proposing CLI usage, app structure, migrations, deployment, or runtime changes. For Hummingbird work, use the official Hummingbird docs before proposing app setup, routes, middleware, request contexts, testing, service lifecycle, deployment, or runtime changes.
 - For Docker work, use current official Docker documentation and Swift Docker image sources before proposing Dockerfile, Compose, BuildKit, image, registry, or runtime changes.
 - For Apple Containerization work, use the official `apple/containerization` and `apple/container` documentation for the relevant branch or release before proposing `container` CLI commands, Containerization Swift API use, host requirements, kernel setup, Rosetta behavior, image, registry, or runtime changes.
diff --git a/plugins/server-side-swift/skills/hummingbird-server-workflow/SKILL.md b/plugins/server-side-swift/skills/hummingbird-server-workflow/SKILL.md
index 892dc065..8108c2c4 100644
--- a/plugins/server-side-swift/skills/hummingbird-server-workflow/SKILL.md
+++ b/plugins/server-side-swift/skills/hummingbird-server-workflow/SKILL.md
@@ -111,6 +111,10 @@ swift run
 
 When adding Hummingbird to an existing package, edit `Package.swift` through normal SwiftPM dependency rules and follow current Hummingbird docs for package products. Do not copy a template over an existing service unless the user explicitly asks for replacement.
 
+## Codex GUI Local Environment
+
+When a Hummingbird repo should be easy to use from Codex GUI Worktree mode, start from `templates/codex-local-environments/hummingbird.toml`. Keep the copied file under `.codex/environments/`, keep paths repo-relative, and replace `EXECUTABLE_NAME` with the repo's actual executable target.
+
 ## App Structure
 
 For typical Hummingbird 2 projects:
diff --git a/plugins/server-side-swift/skills/vapor-server-workflow/SKILL.md b/plugins/server-side-swift/skills/vapor-server-workflow/SKILL.md
index fbd584b0..1dbbc82f 100644
--- a/plugins/server-side-swift/skills/vapor-server-workflow/SKILL.md
+++ b/plugins/server-side-swift/skills/vapor-server-workflow/SKILL.md
@@ -110,6 +110,10 @@ swift run
 
 Use `vapor new MyService -n` only when the user wants the non-interactive bare template and the documented options fit the task. Otherwise, preserve the interactive template questions because they choose real project features such as Fluent, database support, or Leaf.
 
+## Codex GUI Local Environment
+
+When a Vapor repo should be easy to use from Codex GUI Worktree mode, start from `templates/codex-local-environments/vapor.toml`. Keep the copied file under `.codex/environments/`, keep paths repo-relative, and adjust the executable name only when the app target is not `App`.
+
 ## App Structure
 
 For typical Vapor 4 projects:
diff --git a/plugins/server-side-swift/templates/codex-local-environments/hummingbird.toml b/plugins/server-side-swift/templates/codex-local-environments/hummingbird.toml
new file mode 100644
index 00000000..8b353205
--- /dev/null
+++ b/plugins/server-side-swift/templates/codex-local-environments/hummingbird.toml
@@ -0,0 +1,21 @@
+# Copy to .codex/environments/hummingbird.toml and replace EXECUTABLE_NAME.
+version = 1
+name = "hummingbird"
+
+[setup]
+script = "swift package resolve"
+
+[[actions]]
+name = "build"
+icon = "tool"
+command = "swift build"
+
+[[actions]]
+name = "test"
+icon = "tool"
+command = "swift test"
+
+[[actions]]
+name = "run"
+icon = "play"
+command = "swift run EXECUTABLE_NAME"
diff --git a/plugins/server-side-swift/templates/codex-local-environments/swift-server-package.toml b/plugins/server-side-swift/templates/codex-local-environments/swift-server-package.toml
new file mode 100644
index 00000000..73fd43ce
--- /dev/null
+++ b/plugins/server-side-swift/templates/codex-local-environments/swift-server-package.toml
@@ -0,0 +1,26 @@
+# Copy to .codex/environments/swift-server-package.toml and replace EXECUTABLE_NAME.
+version = 1
+name = "swift-server-package"
+
+[setup]
+script = "swift package resolve"
+
+[[actions]]
+name = "resolve"
+icon = "tool"
+command = "swift package resolve"
+
+[[actions]]
+name = "build"
+icon = "tool"
+command = "swift build"
+
+[[actions]]
+name = "test"
+icon = "tool"
+command = "swift test"
+
+[[actions]]
+name = "run"
+icon = "play"
+command = "swift run EXECUTABLE_NAME"
diff --git a/plugins/server-side-swift/templates/codex-local-environments/vapor.toml b/plugins/server-side-swift/templates/codex-local-environments/vapor.toml
new file mode 100644
index 00000000..48092cf1
--- /dev/null
+++ b/plugins/server-side-swift/templates/codex-local-environments/vapor.toml
@@ -0,0 +1,26 @@
+# Copy to .codex/environments/vapor.toml and adjust the executable name if needed.
+version = 1
+name = "vapor"
+
+[setup]
+script = "swift package resolve"
+
+[[actions]]
+name = "build"
+icon = "tool"
+command = "swift build"
+
+[[actions]]
+name = "test"
+icon = "tool"
+command = "swift test"
+
+[[actions]]
+name = "serve"
+icon = "play"
+command = "swift run App serve"
+
+[[actions]]
+name = "migrate"
+icon = "database"
+command = "swift run App migrate"
diff --git a/plugins/spotify/.codex-plugin/plugin.json b/plugins/spotify/.codex-plugin/plugin.json
index 96f06e39..abe97bbb 100644
--- a/plugins/spotify/.codex-plugin/plugin.json
+++ b/plugins/spotify/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "spotify",
-  "version": "6.16.2",
+  "version": "6.17.0",
   "description": "Placeholder plugin repository for future Spotify-focused Codex workflows.",
   "author": {
     "name": "Gale",
diff --git a/plugins/swiftasb-skills/.codex-plugin/plugin.json b/plugins/swiftasb-skills/.codex-plugin/plugin.json
index 6778f744..c0b2ed22 100644
--- a/plugins/swiftasb-skills/.codex-plugin/plugin.json
+++ b/plugins/swiftasb-skills/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "swiftasb-skills",
-  "version": "6.16.2",
+  "version": "6.17.0",
   "description": "Codex skills for explaining SwiftASB and building SwiftUI, AppKit, and Swift package integrations on top of it.",
   "author": {
     "name": "Gale",
diff --git a/plugins/things-app/.codex-plugin/plugin.json b/plugins/things-app/.codex-plugin/plugin.json
index 217dedd7..53513fd2 100644
--- a/plugins/things-app/.codex-plugin/plugin.json
+++ b/plugins/things-app/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "things-app",
-  "version": "6.16.2",
+  "version": "6.17.0",
   "description": "Things.app skills and a bundled local MCP server for reminders, planning digests, and structured task workflows.",
   "author": {
     "name": "Gale",
diff --git a/plugins/things-app/mcp/pyproject.toml b/plugins/things-app/mcp/pyproject.toml
index 4ce5487e..22c7fcb8 100644
--- a/plugins/things-app/mcp/pyproject.toml
+++ b/plugins/things-app/mcp/pyproject.toml
@@ -7,7 +7,7 @@ packages = ["app"]
 
 [project]
 name = "things-mcp"
-version = "6.16.2"
+version = "6.17.0"
 requires-python = ">=3.13"
 dependencies = [
     "fastmcp>=3.0.2",
diff --git a/plugins/things-app/mcp/uv.lock b/plugins/things-app/mcp/uv.lock
index 58993f96..5dcaa385 100644
--- a/plugins/things-app/mcp/uv.lock
+++ b/plugins/things-app/mcp/uv.lock
@@ -1118,7 +1118,7 @@ wheels = [
 
 [[package]]
 name = "things-mcp"
-version = "6.16.2"
+version = "6.17.0"
 source = { editable = "." }
 dependencies = [
     { name = "fastmcp" },
diff --git a/plugins/things-app/pyproject.toml b/plugins/things-app/pyproject.toml
index 80c83034..2deb9a2f 100644
--- a/plugins/things-app/pyproject.toml
+++ b/plugins/things-app/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "things-app-maintenance"
-version = "6.16.2"
+version = "6.17.0"
 description = "Maintainer-only Python tooling baseline for things-app skills and plugin packaging."
 requires-python = ">=3.11"
 dependencies = []
diff --git a/plugins/things-app/uv.lock b/plugins/things-app/uv.lock
index 5ffc79ff..b0299b0d 100644
--- a/plugins/things-app/uv.lock
+++ b/plugins/things-app/uv.lock
@@ -120,7 +120,7 @@ wheels = [
 
 [[package]]
 name = "things-app-maintenance"
-version = "6.16.2"
+version = "6.17.0"
 source = { virtual = "." }
 
 [package.dev-dependencies]
diff --git a/plugins/web-dev-skills/.codex-plugin/plugin.json b/plugins/web-dev-skills/.codex-plugin/plugin.json
index 7f07ccdc..56dff980 100644
--- a/plugins/web-dev-skills/.codex-plugin/plugin.json
+++ b/plugins/web-dev-skills/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "web-dev-skills",
-  "version": "6.16.2",
+  "version": "6.17.0",
   "description": "Codex skills for focused web and Expo native-boundary workflows.",
   "author": {
     "name": "Gale",
diff --git a/pyproject.toml b/pyproject.toml
index 35aae75b..fb143a34 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "socket-maintenance"
-version = "6.16.2"
+version = "6.17.0"
 description = "Root uv tooling baseline for the socket superproject."
 requires-python = ">=3.11"
 dependencies = []
diff --git a/uv.lock b/uv.lock
index 2f95180d..68e1ae2b 100644
--- a/uv.lock
+++ b/uv.lock
@@ -286,7 +286,7 @@ wheels = [
 
 [[package]]
 name = "socket-maintenance"
-version = "6.16.2"
+version = "6.17.0"
 source = { virtual = "." }
 
 [package.dev-dependencies]