sync-xcode-workspace-guidance

name	sync-xcode-workspace-guidance
description	Sync guidance for an Apple .xcworkspace with Apps and Packages. Use to audit root guidance, app projects, local package wiring, XcodeGen settings, and service boundaries; not for one standalone .xcodeproj or package.

Sync Xcode Workspace Guidance

Purpose

Align the root guidance for a modular Apple workspace while preserving the separate owners of each app project and Swift package. scripts/run_workflow.py detects the shape, audits its composition, and adds the bounded workspace guidance section when needed.

Workflow

1. Use explore-apple-swift-docs before changing workflow policy. Prefer Xcode MCP, then Dash's usable XcodeGen : ProjectSpec archive.
2. Run scripts/run_workflow.py --repo-root <root> to inspect workspace, projects, packages, and optional services.
3. Confirm that the root contains one .xcworkspace, Apps/, and Packages/. Report missing or misplaced projects and packages; do not repair project membership by editing workspace or .pbxproj data directly.
4. Check each app's project.yml for a local packages declaration before claiming it consumes a Core package. Check the package's Package.swift for its real target and product graph.
5. For generated workspace projects, verify schemePathPrefix: "../" where workspace-relative scheme paths are used. Keep XcodeGen per-project: it does not become the workspace source of truth.
6. Route app-specific guidance to sync-xcode-project-guidance, package-specific guidance to sync-swift-package-guidance, and active execution to xcode-build-run-workflow or xcode-testing-workflow.
7. Keep optional services under Services/ as their own deployment and runtime boundary. Use the selected server skill for service-local policy.

Audit Contract

The runtime reports:

• workspace and app-project paths;
• package paths containing Package.swift;
• project.yml paths;
• optional service roots;
• missing workspace, app-project, package, or marker-directory findings;
• the root AGENTS.md action taken or planned.

It does not parse XcodeGen package declarations, classify topology, or change workspace membership, app target dependencies, package manifests, generated projects, or service code.

Guards And Handoffs

• Stop when the root has no .xcworkspace, Apps/, or Packages/ marker.
• Stop when the root is a single app project or package; use the narrower sync skill instead.
• Do not mistake a navigator group, folder reference, or directory for a Swift package target.
• Do not use cross-project references to replace local package products.
• Do not hand-edit .pbxproj or workspace data. Make Xcode/XcodeGen-aware changes through the owner skill.

References

• references/workspace-shape.md
• assets/append-section.md