Sync Xcode Project Guidance

Purpose

Bring an existing Xcode app repository up to the expected guidance baseline without overloading the main Xcode execution skill. This skill owns repo-guidance alignment for existing Apple app repos, including deterministic AGENTS.md creation or bounded section append behavior, and runs maintain-project-repo with the xcode-app profile alongside that guidance. scripts/run_workflow.py is the runtime entrypoint, and scripts/sync_xcode_project_guidance.py applies the current sync behavior.

Companion Plugin Requirement

This skill can be discovered from a standalone apple-dev-skills install, but its mutating guidance-sync path refreshes repo-maintenance files through the companion productivity-skills plugin. Before giving filesystem-level fallback instructions, first check the skills exposed in the current Codex session and use the harness-discovered productivity-skills:maintain-project-repo workflow when it is available. If the companion skill is not exposed, tell the user to add the socket marketplace with codex plugin marketplace add gaelic-ghost/socket, then install the relevant plugins from Codex's plugin directory so future sessions expose both apple-dev-skills and productivity-skills.

When To Use

• Use this skill when an existing macOS, iOS, or iPadOS app repo needs AGENTS.md added, refreshed, or merged with the current Xcode workflow baseline.
• Use this skill when the repository already has an .xcodeproj or .xcworkspace and the user wants project guidance, onboarding rules, or workflow policy brought up to date.
• Use this skill when the user wants the repo guidance for the current narrower Xcode execution skills to be made explicit in the repo itself.
• Do not use this skill for new-project creation from nothing.
• Do not use this skill for ordinary build, test, run, diagnostics, docs lookup, or mutation work inside an existing Xcode project.
• Do not use this skill for plain Swift packages, libraries, or tools that are not native Apple apps.
• Recommend bootstrap-xcode-app-project when the repo does not exist yet.
• Recommend xcode-build-run-workflow when the task is active Xcode execution, diagnostics, docs lookup, previews, file-membership follow-through, or mutation work inside an existing Xcode project.
• Recommend xcode-testing-workflow when the task is primarily about Swift Testing, XCTest, XCUITest, .xctestplan, or test diagnosis inside an existing Xcode project.
• Recommend sync-swift-package-guidance when the repo is a plain Swift package instead of an Xcode app project.
• After updating this plugin's Xcode-policy surfaces, recommend rerunning sync-xcode-project-guidance in downstream repos so their AGENTS.md and maintain-project-repo output stay aligned.
• For maintainer notes about this repository itself, say plainly that the repo exports from top-level skills/ today and does not ship repo-local installer workflows.

Single-Path Workflow

1. Collect the required inputs:
   • repo_root
   • optional workspace_path
   • optional skip_validation
   • optional dry_run
2. Classify the request as existing Xcode app-repo guidance sync before continuing:
   • continue only when the repo already contains an .xcodeproj or .xcworkspace
   • stop if the request is really new-project bootstrap or SwiftPM-only guidance sync
3. Apply the Apple docs gate before shaping workflow guidance:
   • read the relevant Apple documentation first
   • prefer Dash or local Apple docs first, then official Apple web docs when needed
   • state the documented workflow boundary being relied on before proposing repo guidance changes
   • current documented anchors for this workflow include:
     • Apple's Xcode project-creation guidance: Creating an Xcode project for an app
     • SwiftUI app lifecycle guidance through the App protocol: App
     • scene composition guidance through Scene and WindowGroup: Scene and WindowGroup
   • if the docs and the current guidance template conflict, stop and report that conflict
   • if no relevant Apple docs can be found, say that explicitly before proceeding
4. Apply the shared Xcode-project policy before making repo-guidance changes:
   • apply the detailed local policy in references/snippets/apple-xcode-project-core.md
   • preserve its simplicity-first Swift, SwiftUI, Xcode-managed project, XcodeGen-backed project, test-plan, file-membership, tracked .pbxproj commit, and Debug/Release guidance
5. Run scripts/run_workflow.py to normalize inputs, detect whether the repo is really Xcode-managed, and shape the sync plan.
6. Apply the sync path:
   • if AGENTS.md is missing, copy assets/AGENTS.md
   • if AGENTS.md exists and already contains the managed section, keep the file unchanged
   • if AGENTS.md exists but lacks the managed section, append assets/append-section.md as a bounded section
7. Validate the synced repo guidance:
   • verify AGENTS.md exists
   • verify the synced file mentions xcode-build-run-workflow and xcode-testing-workflow
   • verify the synced file preserves the no-direct-.pbxproj rule and the tracked .pbxproj stage-and-commit rule
   • verify the synced file preserves the XcodeGen source-of-truth rule for repos that use generated projects
8. Refresh maintain-project-repo:
   • refresh scripts/repo-maintenance/
   • refresh .github/workflows/validate-repo-maintenance.yml
   • preserve repo-specific extra scripts that are not part of the managed file set
9. Verify the synced maintenance guidance still points at the expected maintainer files:
   • .swiftformat
   • scripts/repo-maintenance/hooks/pre-commit.sample
   • scripts/repo-maintenance/validate-all.sh
   • scripts/repo-maintenance/sync-shared.sh
   • scripts/repo-maintenance/release.sh
   • protected branches, when configured, require the GitHub Actions check context validate rather than Validate Repo Maintenance / validate
10. Hand off ongoing engineering work cleanly:

• recommend xcode-build-run-workflow or xcode-testing-workflow for active Xcode collaboration after the repo guidance is aligned
• recommend bootstrap-xcode-app-project only when the user actually needs a fresh repo instead of guidance sync

Inputs

• repo_root: optional absolute or relative path to the repository root; defaults to .
• workspace_path: optional path used only to improve Xcode-project discovery when repo-root detection is ambiguous
• skip_validation: optional flag to skip post-sync file validation
• dry_run: optional flag to emit the planned contract without writing files
• Defaults:
  • runtime entrypoint: executable scripts/run_workflow.py
  • repo_root=. when omitted
  • writeMode=sync-if-needed
  • validation runs unless --skip-validation is passed
  • successful mutating runs refresh maintain-project-repo output in place

Outputs

• status
  • success: guidance sync completed or was already satisfied
  • blocked: prerequisites, repo classification, or sync policy prevented completion
  • failed: the sync path started but did not complete successfully
• path_type
  • primary: the documented sync path completed
  • fallback: a non-mutating guided result was returned
• output
  • resolved repo root
  • detected workspace or project markers
  • AGENTS.md path
  • actions applied or planned
  • refreshed maintain-project-repo paths
  • validation result
  • one concise next step or handoff

Guards and Stop Conditions

• Stop with blocked if the repo root cannot be resolved.
• Stop with blocked if the repo does not contain an .xcodeproj or .xcworkspace.
• 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.

Fallbacks and Handoffs

• The only current fallback is a non-mutating dry-run or guided result that explains what the sync would do.
• After a successful sync, hand off ongoing build, run, diagnostics, preview, and mutation work to xcode-build-run-workflow.
• After a successful sync, hand off ongoing test execution and test diagnosis work to xcode-testing-workflow.
• After a successful sync, use scripts/repo-maintenance/validate-all.sh for local maintainer validation and scripts/repo-maintenance/release.sh --mode standard --version vX.Y.Z from a feature branch or worktree for protected-main releases.
• After a successful sync, configure protected branches to require validate for the managed repo-maintenance workflow; GitHub exposes that job check context directly rather than the workflow title plus job string.
• Recommend bootstrap-xcode-app-project when the repository still needs to be created from scratch.
• Recommend sync-swift-package-guidance when the repo is a plain Swift package rather than an Xcode app project.

Customization

• Use references/customization-flow.md.
• scripts/customization_config.py stores and reports customization state.
• scripts/run_workflow.py loads runtime-safe defaults from customization state before invoking the supported sync path.
• The current runtime-enforced customization surface is one writeMode knob that controls whether the workflow may create missing AGENTS.md, append the bounded Xcode section, or stay report-only.
• Run the Python wrapper and customization entrypoints through uv, because they rely on inline PyYAML script metadata rather than a repo-global Python environment.
• In consuming repos, the supported path is uv run scripts/run_workflow.py ... and uv run scripts/customization_config.py ...; do not assume plain python or python3 will have the needed YAML dependency installed.

References

Workflow References

• references/project-detection.md

Contract References

• references/automation-prompts.md
• references/customization-flow.md

Support References

• assets/AGENTS.md
• 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

Script Inventory

• scripts/run_workflow.py
• scripts/sync_xcode_project_guidance.py
• scripts/customization_config.py