gaelic-ghost · gaelic-ghost · Jun 6, 2026 · Jun 6, 2026 · Jun 6, 2026 · Jun 6, 2026
diff --git 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
@@ -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
@@ -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
@@ -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
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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/...ppkit-app-architecture-workflow/references/snippets/apple-xcode-project-core.md b/...ppkit-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/...apple-ui-accessibility-workflow/references/snippets/apple-xcode-project-core.md b/...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
@@ -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/.../skills/bootstrap-swift-package/references/snippets/apple-swift-package-core.md b/.../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
@@ -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