Document Apple companion install paths

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

@@ -1,6 +1,6 @@
 {
   "name": "agent-plugin-skills",
-  "version": "6.1.0",
+  "version": "6.1.1",
   "description": "Installable maintainer skills for skills-export repositories.",
   "author": {
     "name": "Gale",

plugins/agent-plugin-skills/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-plugin-skills-maintenance"
-version = "6.1.0"
+version = "6.1.1"
 description = "Maintainer-only Python tooling baseline for agent-plugin-skills."
 requires-python = ">=3.11"
 dependencies = []

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

@@ -1,6 +1,6 @@
 {
   "name": "apple-dev-skills",
-  "version": "6.1.0",
+  "version": "6.1.1",
   "description": "Apple development workflows for Codex and Claude Code, including SwiftUI architecture and DocC authoring guidance.",
   "author": {
     "name": "Gale",
@@ -26,7 +26,7 @@
   "interface": {
     "displayName": "Apple Dev Skills",
     "shortDescription": "Apple, Swift, Xcode, SwiftUI, and DocC workflows for Codex.",
-    "longDescription": "Bundle Apple-platform development skills for Swift, SwiftUI architecture, Xcode, SwiftPM, DocC authoring and review, testing, formatting, and repository guidance work across iOS, macOS, and related Apple tooling.",
+    "longDescription": "Bundle Apple-platform development skills for Swift, SwiftUI architecture, Xcode, SwiftPM, DocC authoring and review, testing, formatting, and repository guidance work across iOS, macOS, and related Apple tooling. Most workflows work standalone; bootstrap and guidance-sync workflows that install or refresh repo-maintenance files require the companion Productivity Skills plugin, or the socket marketplace that installs both.",
     "developerName": "Gale",
     "category": "Developer Tools",
     "capabilities": [
@@ -38,7 +38,7 @@
       "Explore the relevant Apple docs first, then explain the right SwiftUI or Xcode path for this repository.",
       "Help me build, test, or debug this Swift or Xcode project using the repo's Apple workflows.",
       "Write or review DocC symbol comments, articles, extension files, and landing-page structure for this Swift repository.",
-      "Sync the Apple project guidance in this repo without hand-editing Xcode project files."
+      "Sync the Apple project guidance in this repo without hand-editing Xcode project files, using Productivity Skills when repo-maintenance files must be installed or refreshed."
     ],
     "brandColor": "#0A84FF"
   }

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

@@ -43,6 +43,8 @@ echo "Validating local discovery mirrors..."
 echo "Validating root README contract..."
 require_contains "README.md" 'Treat `productivity-skills` as the default baseline layer for general repo-doc and maintenance work'
 require_contains "README.md" 'This repository is the canonical source of truth for Gale'"'"'s Apple, Swift, and Xcode workflow skills.'
+require_contains "README.md" 'Most Apple Dev Skills workflows are useful as a standalone plugin.'
+require_contains "README.md" 'The [`socket`](https://github.com/gaelic-ghost/socket) repository is Gale'"'"'s plugin superproject and marketplace catalog.'
 require_contains "README.md" 'Treat root [`skills/`](./skills/) as the canonical authored surface.'
 require_contains "README.md" 'Keep shared reusable assets in [`shared/`](./shared/)'
 require_contains "README.md" 'Run the repository test suite for skill and metadata changes:'
@@ -61,6 +63,7 @@ require_contains "CONTRIBUTING.md" 'uv run pytest'
 echo "Validating AGENTS contract..."
 require_contains "AGENTS.md" 'This repository is the canonical home for Gale'"'"'s Apple, Swift, and Xcode workflow skills.'
 require_contains "AGENTS.md" 'Treat `productivity-skills` as the default baseline maintainer layer'
+require_contains "AGENTS.md" 'Preserve standalone-install guidance for public users who install only `apple-dev-skills`'
 require_contains "AGENTS.md" 'Root `skills/` is the canonical authored and exported surface.'
 require_contains "AGENTS.md" 'Keep shared reusable assets in [`shared/`](./shared/) and maintainer tests in [`tests/`](./tests/).'
 require_contains "AGENTS.md" 'require reading the relevant Apple documentation before proposing implementation changes.'
@@ -95,6 +98,7 @@ require_contains "$audit_doc" "## Audit Procedure"
 require_contains "$audit_doc" "## Local Discovery Smoke Test Flow"
 require_contains "$audit_doc" "## Reporting Shape"
 require_contains "$audit_doc" '`productivity-skills` owns the reusable `maintain-project-repo` toolkit contract'
+require_contains "$audit_doc" 'standalone `apple-dev-skills` installs from installs that also include the `productivity-skills` companion plugin'
 require_contains "$audit_doc" 'this repository owns only the Apple-specific profile selection and Xcode MCP registration contract'
 require_contains "$audit_doc" 'Historical milestone planning decisions that no longer need standalone docs should live in `ROADMAP.md`'
 require_not_contains "$audit_doc" 'plugins/apple-dev-skills/'
@@ -116,6 +120,7 @@ require_contains "$execution_split_doc" "## AGENTS Expansion Strategy"
 require_contains "$execution_split_doc" "## Repo-Maintenance Direction"
 require_contains "$execution_split_doc" "## Implementation Plan"
 require_contains "$execution_split_doc" '`productivity-skills/maintain-project-repo` as the canonical shipped repo-maintenance surface'
+require_contains "$execution_split_doc" 'Users who install only `apple-dev-skills` still get the Apple-only workflows'
 require_contains "ROADMAP.md" "Completed Milestones 22 and 23"
 require_contains "ROADMAP.md" 'See `docs/maintainers/customization-consolidation-review.md`.'
 require_contains "ROADMAP.md" "Completed Milestones 30 through 36"
@@ -250,6 +255,8 @@ do
   [[ ! -e "$skill_dir/assets/repo-maintenance" ]] || fail "Did not expect vendored repo-maintenance assets in $skill_dir"
   [[ ! -e "$skill_dir/assets/github/repo-maintenance-workflows" ]] || fail "Did not expect vendored repo-maintenance workflow assets in $skill_dir"
   require_contains "$skill_dir/SKILL.md" 'maintain-project-repo'
+  require_contains "$skill_dir/SKILL.md" 'Companion Plugin Requirement'
+  require_contains "$skill_dir/SKILL.md" 'https://github.com/gaelic-ghost/socket'
 done
 require_contains "./skills/bootstrap-swift-package/scripts/bootstrap_swift_package.sh" 'productivity-skills/skills/maintain-project-repo/scripts/run_workflow.py'
 require_contains "./skills/bootstrap-xcode-app-project/scripts/bootstrap_xcode_app_project.py" 'productivity-skills" / "skills" / "maintain-project-repo" / "scripts" / "run_workflow.py'

plugins/apple-dev-skills/AGENTS.md

@@ -8,6 +8,7 @@ Use this file for durable repo-local guidance that Codex should follow before ch
 
 - This repository is the canonical home for Gale's Apple, Swift, and Xcode workflow skills.
 - Treat `productivity-skills` as the default baseline maintainer layer for general repo docs and maintenance work; this repo is the narrower specialist layer when Apple-specific behavior should change the workflow.
+- Preserve standalone-install guidance for public users who install only `apple-dev-skills`, and make the `productivity-skills` companion requirement explicit only for workflows that install or refresh `maintain-project-repo`.
 - Root `skills/` is the canonical authored and exported surface.
 - Keep shared reusable assets in [`shared/`](./shared/) and maintainer tests in [`tests/`](./tests/).
 

plugins/apple-dev-skills/README.md

@@ -47,6 +47,14 @@ Use this repository's skills when the work is about:
 
 When installed as a Codex plugin, this repository also registers Xcode's built-in MCP bridge through `xcrun mcpbridge`. Users still need to allow external agents in Xcode's Intelligence settings and keep the relevant project open in Xcode before external Codex sessions can use Xcode-provided tools.
 
+### Companion Plugin Requirements
+
+Most Apple Dev Skills workflows are useful as a standalone plugin. The bootstrap and repo-guidance sync workflows that install or refresh `scripts/repo-maintenance/` also need the companion [`productivity-skills`](https://github.com/gaelic-ghost/productivity-skills) plugin installed alongside this plugin, because `productivity-skills` owns the reusable `maintain-project-repo` implementation while Apple Dev Skills chooses the Apple-specific `swift-package` or `xcode-app` profile.
+
+If an agent has only `apple-dev-skills` installed, it can still use the documentation lookup, SwiftUI architecture, Xcode build/run/test, DocC, formatting, source-structure, and accessibility workflows. It should install `productivity-skills` before running `bootstrap-swift-package`, `bootstrap-xcode-app-project`, `sync-swift-package-guidance`, or `sync-xcode-project-guidance` in mutating mode.
+
+The [`socket`](https://github.com/gaelic-ghost/socket) repository is Gale's plugin superproject and marketplace catalog. Installing from the socket marketplace is useful when you want Apple Dev Skills and its companion plugins available together without wiring each plugin one by one; standalone installs remain supported for Apple-only workflows that do not call `maintain-project-repo`.
+
 Use [`CONTRIBUTING.md`](./CONTRIBUTING.md) for maintainer workflow details, and use [`ROADMAP.md`](./ROADMAP.md) for planned and completed milestone-level work.
 
 ## Development

plugins/apple-dev-skills/ROADMAP.md

@@ -29,6 +29,7 @@
 - Keep root `skills/` as the canonical authored and exported surface.
 - Keep Apple documentation requirements explicit and enforceable in the skill guidance.
 - Keep plugin packaging thin and secondary to the workflow-authoring surface.
+- Keep standalone install behavior honest: Apple-only workflows should remain usable from `apple-dev-skills` alone, while repo-maintenance bootstrap and sync workflows should name their `productivity-skills` companion requirement and the optional `socket` marketplace path.
 - Expand the repo deliberately instead of adding loosely related helper features ad hoc.
 
 ## Milestone Progress

plugins/apple-dev-skills/docs/maintainers/execution-split-and-inference-plan.md

@@ -98,7 +98,7 @@ Planned profile shape:
 - `xcode-app`
 - optional later `swift-mixed-root`
 
-The socket plugin ships `productivity-skills` and `apple-dev-skills` together, so Apple workflows can call the sibling `maintain-project-repo` skill instead of vendoring another toolkit source.
+The `socket` marketplace lists `productivity-skills` and `apple-dev-skills` together, so users who install that catalog get the sibling `maintain-project-repo` skill without wiring each plugin one by one. Users who install only `apple-dev-skills` still get the Apple-only workflows, but mutating bootstrap and guidance-sync workflows must explain that repo-maintenance install or refresh requires the `productivity-skills` companion plugin.
 
 Current Apple-side integration status:
 

plugins/apple-dev-skills/docs/maintainers/reality-audit.md

@@ -67,6 +67,7 @@ Use this flow when validating the current top-level export surface and local dis
 ## Durable Review Criteria
 
 - Root docs should say plainly that `productivity-skills` remains the default baseline layer for general repo-doc and maintenance work, while this repo is the Apple-specific specialization layer.
+- Root docs should distinguish standalone `apple-dev-skills` installs from installs that also include the `productivity-skills` companion plugin or the `socket` marketplace catalog.
 - Root docs must describe the same active skill surface.
 - Root docs must describe the current top-level export shape without treating deleted nested packaging experiments as active.
 - Codex plugin docs must describe Xcode MCP registration as Xcode-owned `xcrun mcpbridge` wiring, not as a bundled third-party server package.

plugins/apple-dev-skills/docs/maintainers/workflow-atlas.md

@@ -87,6 +87,7 @@ flowchart TD
 - End-user `AGENTS.md` guidance is recommended from each skill's local snippet copy, not from a router.
 - The active skill surface now uses the intended install-facing names directly.
 - The reusable repo-maintenance implementation now lives in `productivity-skills/maintain-project-repo`; Apple bootstrap and sync skills call that sibling skill with the `swift-package` or `xcode-app` profile.
+- Standalone `apple-dev-skills` installs remain useful for Apple-only workflows, but mutating bootstrap and guidance-sync workflows must tell users when they need the `productivity-skills` companion plugin or the `socket` marketplace catalog.
 - The canonical shipped repo-maintenance contract stays profile-aware and gives downstream repos `scripts/repo-maintenance/config/profile.env` while Apple workflows choose either the `swift-package` or `xcode-app` profile explicitly.
 - The managed workflow's protected-branch check context is `validate`; GitHub exposes the job check run by that context, not by the display-style workflow title plus job string `Validate Repo Maintenance / validate`.
 - The Swift package side of the execution split is now in place, with build-run and testing split into separate primary skills while `swift-package-workflow` remains only as a legacy compatibility-routing surface.
@@ -114,6 +115,7 @@ flowchart TD
 
 - Treat `productivity-skills` as the baseline maintainer layer for general repo-doc and maintenance work.
 - Use `apple-dev-skills` when Swift, Xcode, Apple docs requirements, or Apple-platform repo shape should materially change the workflow.
+- Keep public install guidance explicit about the two valid shapes: standalone `apple-dev-skills` for Apple-only workflows, or `apple-dev-skills` plus `productivity-skills` for repo-maintenance bootstrap and sync workflows. The `socket` marketplace is the convenient catalog when users want those companion plugins together.
 - The repository currently exports only from top-level `skills/`.
 - If this repository later grows top-level `mcps/` or `apps/`, those directories are valid export surfaces too.
 - The repository must not reintroduce a nested packaged plugin tree or any other second export surface under `plugins/`.

plugins/apple-dev-skills/pyproject.toml

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

plugins/apple-dev-skills/skills/bootstrap-swift-package/SKILL.md

@@ -9,6 +9,10 @@ description: Bootstrap new Swift Package Manager repositories with consistent de
 
 Create a new Swift package repository with one top-level entry point, a simplicity-first Swift baseline, and a local-first maintainer surface. `scripts/run_workflow.py` is the runtime wrapper, and `scripts/bootstrap_swift_package.sh` is the deterministic implementation core for scaffold creation, testing-mode selection, validation, and `maintain-project-repo` installation with the `swift-package` profile.
 
+## Companion Plugin Requirement
+
+This skill can be discovered from a standalone `apple-dev-skills` install, but its mutating bootstrap path installs repo-maintenance files through the companion [`productivity-skills`](https://github.com/gaelic-ghost/productivity-skills) plugin. If the companion `maintain-project-repo` runner is missing, tell the user to install `productivity-skills` alongside `apple-dev-skills` or install the [`socket`](https://github.com/gaelic-ghost/socket) marketplace, which is useful when they want Gale's Apple and general maintainer plugins available together.
+
 ## When To Use
 
 - Use this skill for new Swift package scaffolding.

plugins/apple-dev-skills/skills/bootstrap-swift-package/scripts/bootstrap_swift_package.sh

@@ -75,6 +75,7 @@ swift_minor_version=""
 script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 agents_template="$script_dir/../assets/AGENTS.md"
 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 the productivity-skills plugin alongside apple-dev-skills, or install the socket marketplace from https://github.com/gaelic-ghost/socket so both companion plugins are available, then rerun this workflow."
 
 is_ignorable_directory_entry() {
   local entry_name="$1"
@@ -479,7 +480,7 @@ mkdir -p "$target_dir"
   if [[ -x "$maintain_project_repo_runner" ]]; then
     "$maintain_project_repo_runner" --repo-root "$target_dir" --operation install --profile swift-package >/dev/null
   else
-    failed "Validation failed: maintain-project-repo runner missing at $maintain_project_repo_runner. Ensure productivity-skills ships alongside apple-dev-skills before rerunning."
+    failed "$maintain_project_repo_missing_message"
   fi
 
   ensure_test_target "$testing_mode" "$name"

plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/SKILL.md

@@ -9,6 +9,10 @@ description: Bootstrap a new native Apple app project for macOS, iOS, or iPadOS
 
 Create a new native Apple app repository from nothing to a usable baseline on disk. The first implementation prioritizes a deterministic `XcodeGen` path for SwiftUI app projects and a guarded planning path for the standard Xcode-created-project flow. `scripts/run_workflow.py` is the runtime entrypoint, and `scripts/bootstrap_xcode_app_project.py` is the current implementation core for XcodeGen-backed scaffold creation plus `maintain-project-repo` installation with the `xcode-app` profile.
 
+## Companion Plugin Requirement
+
+This skill can be discovered from a standalone `apple-dev-skills` install, but its mutating bootstrap path installs repo-maintenance files through the companion [`productivity-skills`](https://github.com/gaelic-ghost/productivity-skills) plugin. If the companion `maintain-project-repo` runner is missing, tell the user to install `productivity-skills` alongside `apple-dev-skills` or install the [`socket`](https://github.com/gaelic-ghost/socket) marketplace, which is useful when they want Gale's Apple and general maintainer plugins available together.
+
 ## When To Use
 
 - Use this skill when the user wants to start, begin, create, or bootstrap a new macOS, iOS, or iPadOS app project on macOS.

plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/scripts/bootstrap_xcode_app_project.py

@@ -122,7 +122,11 @@ def maintain_project_repo_runner() -> Path:
     runner = plugins_root / "productivity-skills" / "skills" / "maintain-project-repo" / "scripts" / "run_workflow.py"
     if not runner.is_file():
         raise RuntimeError(
-            f"Expected maintain-project-repo runner at {runner}, but it was missing."
+            "bootstrap-xcode-app-project needs productivity-skills/maintain-project-repo "
+            f"to install repo-maintenance files, but the runner was missing at {runner}. "
+            "Install the productivity-skills plugin alongside apple-dev-skills, or install "
+            "the socket marketplace from https://github.com/gaelic-ghost/socket so both "
+            "companion plugins are available, then rerun this workflow."
         )
     return runner
 
@@ -207,7 +211,7 @@ def main() -> int:
             "normalized_inputs": normalized_inputs,
             "validation_result": "failed (maintain-project-repo install)",
             "stderr": str(exc),
-            "next_step": "Ensure productivity-skills ships alongside apple-dev-skills, then rerun the workflow.",
+            "next_step": "Install the productivity-skills companion plugin or the socket marketplace, then rerun bootstrap-xcode-app-project.",
         }
         print(json.dumps(payload, indent=2, sort_keys=True))
         return 1