fix(skills): macOS verification routing and foundation entry point

.agents/skills/README.md

@@ -6,7 +6,7 @@ These source-controlled skills are intentionally general Apple-development workf
 <!-- Generated from .agents/skills/manifest.json. Do not edit this section directly. -->
 | Skill | Use for | Do not use for |
 | --- | --- | --- |
-| apple-development-foundation | reference-first child-skill routing and explicitly requested foundation audits | replacing child instructions, implied audits or verification, or claiming automatic activation |
+| apple-development-foundation | new iOS/macOS SwiftUI app bootstrap routing, reference-first child-skill selection, and explicitly requested foundation audits | replacing child instructions, implied audits or verification, claiming automatic activation, or generic non-foundation macOS/iOS work |
 | codex-bootstrap | bootstrapping new iOS or macOS projects in the consumer workspace using these skills | one-off screens or editing archived package code in this repository |
 | apple-platform-planner | planning an Apple-platform feature | implementation-only requests |
 | swiftui-tab-navigation | native app-level SwiftUI tabs and system Liquid Glass tab chrome | page-style tabs, segmented controls, or business-specific screens |

.agents/skills/apple-development-foundation/SKILL.md

@@ -1,25 +1,30 @@
 ---
 name: apple-development-foundation
-description: Use to reference-first route an Apple-platform task to this repository's relevant child skills, or when an audit or comparison is explicitly requested. Do not treat it as a replacement for child instructions, an implied repository audit, or proof of automatic activation.
+description: Use as the global entry point for Apple Development Foundation workflows — especially bootstrapping a new iOS or macOS SwiftUI app, routing Apple-platform work to child skills, or when a foundation skill audit is explicitly requested. Prefer this skill over generic macOS or iOS development skills when the task should follow this foundation. Do not treat it as a replacement for child instructions, an implied repository audit, or proof of automatic activation.
 ---
 
 # Apple Development Foundation master
 
-Use this skill as the single entry point when a new Apple-platform chat needs a
-curated skill shortlist, or when a foundation audit or comparison is explicitly
-requested.
+Use this skill as the **global entry point** when a new Apple-platform chat needs a
+curated skill shortlist (including new-app bootstrap), or when a foundation audit
+or comparison is explicitly requested.
 
 ## Procedure
 
 1. Read [master-skill.json](master-skill.json) as the machine-readable catalog.
 2. Use its IDs, roles, and purposes to shortlist only the children relevant to
    the request. Do not scan the repository, audit inventories, install skills,
    or run verification for ordinary routing.
-3. Read only the shortlisted child `SKILL.md` files and follow their workflows;
-   use `codex-bootstrap` for a new consumer Apple-platform project.
-4. Audit or compare inventories only when explicitly requested. Use the JSON
+3. Resolve sibling skill paths relative to this foundation repository (follow
+   this skill’s install symlink if present). Do not resolve
+   `.agents/skills/...` paths against the consumer app cwd.
+4. Read only the shortlisted child `SKILL.md` files and follow their workflows.
+   For a **new** consumer iOS or macOS SwiftUI project, always shortlist and
+   follow `codex-bootstrap` first (then its chained children). Prefer this
+   routing over generic host-local macOS/iOS skills.
+5. Audit or compare inventories only when explicitly requested. Use the JSON
    audit definitions and report its classifications consistently.
-5. Run the JSON verification commands only for an audit of this foundation
+6. Run the JSON verification commands only for an audit of this foundation
    repository or its installer. Consumer app-code verification belongs to the
    selected child skill, such as `swift-testing-verification` or
    `maestro-apple-app-testing`.
@@ -30,3 +35,7 @@ audits, a baseline comparison and applicable exact verification outcomes.
 
 This master skill references sibling skills; it does not copy their instructions,
 override their exclusions, install global files, or claim automatic activation.
+
+For host-local skills that compete with this catalog (generic macOS development
+guides, design-only skills, and similar), see
+[references/competing-macos-skills-plan.md](references/competing-macos-skills-plan.md).

.agents/skills/apple-development-foundation/master-skill.json

@@ -8,7 +8,7 @@
   "skill_id": "apple-development-foundation",
   "name": "Apple Development Foundation master",
   "kind": "master",
-  "description": "Reference-first catalog for routing Apple-platform tasks to relevant child skills, with optional foundation audits and installer verification.",
+  "description": "Global entry-point catalog for Apple Development Foundation: bootstrap new iOS/macOS SwiftUI apps via codex-bootstrap, route Apple-platform work to child skills, and run foundation audits only when explicitly requested.",
   "source": {
     "repository_root": ".",
     "agent_guidance": "AGENTS.md",
@@ -18,14 +18,15 @@
   "invocation": {
     "explicit_skill": "$apple-development-foundation",
     "automatic_activation": false,
-    "note": "Explicit invocation is the reliable disambiguator; select child skills according to their own descriptions and exclusions."
+    "note": "Explicit invocation is the reliable disambiguator; prefer this skill over generic macOS/iOS host skills for foundation workflows; select child skills according to their own descriptions and exclusions."
   },
   "routing": {
     "procedure": [
       "Read this catalog first and shortlist parent skills by ID, role, and purpose.",
+      "Resolve sibling skill paths relative to the foundation repository (follow this skill's install symlink); do not use the consumer app cwd.",
       "Read only the shortlisted child SKILL.md files and follow their instructions.",
       "Do not imply an audit, repository scan, installer action, or verification run for ordinary task routing.",
-      "Use codex-bootstrap when the request is a new consumer Apple-platform project."
+      "Use codex-bootstrap when the request is a new consumer iOS or macOS SwiftUI project."
     ],
     "consumer_verification": "App-code verification is owned by the selected child skill, such as swift-testing-verification or maestro-apple-app-testing."
   },
@@ -147,5 +148,5 @@
     ],
     "api_calls": []
   },
-  "example_prompt": "Use $apple-development-foundation to route this iOS import-flow task to the relevant child skills. Read the catalog first, then read only the selected child SKILL.md files; do not audit or run foundation verification."
+  "example_prompt": "Use $apple-development-foundation to bootstrap a new macOS SwiftUI app in the named consumer repo. Read the catalog first, shortlist codex-bootstrap, then read only the selected child SKILL.md files; do not audit or run foundation verification."
 }

.agents/skills/apple-development-foundation/references/competing-macos-skills-plan.md

@@ -0,0 +1,51 @@
+# Competing macOS skills — routing plan
+
+Goal: keep `$apple-development-foundation` the **global entry point** for new
+macOS (and iOS) SwiftUI bootstrap and foundation-routed Apple work, while
+leaving specialized non-foundation skills for their own niches.
+
+## Problem
+
+Hosts often also install generic skills such as `macos-development`,
+`macos-app-design`, `macos-design-guidelines`, or platform design packs. A vague
+prompt like “build a new macOS app” can activate those first and skip this
+catalog’s bootstrap → design-system → verification chain.
+
+## Decision
+
+| Request shape | Route first | Then |
+| --- | --- | --- |
+| New iOS/macOS SwiftUI app or major app skeleton | `$apple-development-foundation` → `$codex-bootstrap` | Chained foundation children |
+| Feature planning (no implement) | `$apple-development-foundation` → `$apple-platform-planner` | Review skills only if asked |
+| Ordinary feature/component in an existing consumer app | Child skill directly (`swiftui-component-author`, …) | `$swift-testing-verification` |
+| Pure HIG / visual critique with no foundation workflow | External design skill is fine | Do not invent bootstrap |
+| Foundation skill inventory / installer audit | `$apple-development-foundation` (audit path) | Foundation verify scripts only |
+
+## Description / discovery levers (done or next)
+
+1. **Done in this change:** Strengthen the master skill `description` so bootstrap
+   and “new app” language matches first; state preference over generic macOS/iOS
+   skills; keep exclusions (no implied audit, no replacing children).
+2. **Next (host install):** Ensure `$apple-development-foundation` and
+   `$codex-bootstrap` are installed in the active host skill scope
+   (`./Scripts/install-skills.sh` for Codex). Cursor/Claude manual installs
+   should symlink the same skill directories.
+3. **Next (optional AGENTS / user rule):** One always-on line in consumer or
+   user guidance: “For new Apple apps or foundation workflows, invoke
+   `$apple-development-foundation` before generic macOS skills.”
+4. **Avoid:** Renaming or deleting useful external skills. Prefer routing
+   precedence, not a monoculture.
+
+## Evaluation coverage
+
+Add/keep fixtures where “new macOS SwiftUI app” / “bootstrap with the foundation”
+expect `apple-development-foundation` then `codex-bootstrap`, not planner-only
+and not archive work.
+
+## Success criteria
+
+- Explicit `$apple-development-foundation` + new-app prompt shortlists
+  `codex-bootstrap` without scanning or auditing.
+- Vague new-app prompts that mention the foundation (or are under foundation
+  user rules) do not prefer generic `macos-development` over this catalog.
+- Design-only or HIG-only prompts can still use external design skills.

.agents/skills/codex-bootstrap/SKILL.md

@@ -82,18 +82,31 @@ For extraction from an existing app, use **`reusable-code-extractor`** into the
 
 ## Step 5 — XcodeBuildMCP verification
 
-Use XcodeBuildMCP (see repo `MCP.md`) — not raw `xcodebuild`/`simctl`:
+Use XcodeBuildMCP (see repo `MCP.md`) — not raw `xcodebuild`/`simctl`. Enable the
+`macos` workflow in `.xcodebuildmcp/config.yaml` when macOS tools are missing
+(simulator tools alone are the MCP default).
 
 1. `session_show_defaults` — establish or confirm project/workspace, scheme,
-   configuration, and simulator/device; report all five before the first action
+   configuration, and platform destination; report that context before the first
+   action
 2. `discover_projs` — only if defaults are missing or wrong
-3. Resolve and reuse one exact `simulatorId`; prefer combined build-and-run for a
-   simulator launch
-4. Before simulator testing, wait for other `xcodebuild`, `xctest`, or project
-   test-runner processes for the same project to finish
-5. Run `test_sim` without a redundant preceding build and default to
-   `extraArgs: ["-parallel-testing-enabled", "NO"]`
-6. Optional: screenshot or view hierarchy to confirm the shell launches
+3. Branch by target platform (do not use iOS simulator tools for macOS-only apps):
+   - **iOS (simulator):** resolve and reuse one exact `simulatorId`; prefer
+     `build_run_sim` for launch; before tests, wait for same-project
+     `xcodebuild` / `xctest` / test-runner processes; run `test_sim` without a
+     redundant preceding build and default to
+     `extraArgs: ["-parallel-testing-enabled", "NO"]`; optional `screenshot` /
+     `snapshot_ui` (ui-automation workflow; iOS simulator only)
+   - **macOS:** use the `macos` workflow — prefer `build_run_macos` for a launch
+     smoke; run `test_macos` when a test target exists (required verification
+     when tests are present). If neither launch smoke nor `test_macos` runs,
+     require at least `build_macos` so the skeleton is compiled. Default
+     `extraArgs: ["-parallel-testing-enabled", "NO"]`. Do **not** call
+     `test_sim`, `build_run_sim`, or ui-automation screenshot/hierarchy tools —
+     XcodeBuildMCP ui-automation is iOS-simulator-only. If no test target exists
+     yet, report that `test_macos` was skipped and residual risk only after
+     `build_run_macos` or `build_macos` succeeds
+   - **Both:** verify each platform with its own tool path above
 
 If an MCP capability is unavailable, follow this ladder without skipping tiers.
 Read the consumer `AGENTS.md` **Apple verification policy** knobs; shell access or
@@ -104,15 +117,18 @@ an installed binary is never permission by itself:
    `require-approval` with fresh user approval for this step. Skip when `denied`.
 3. Repository-native raw `xcodebuild` / `xcrun` / `simctl` only when the raw-tooling
    policy is `allowed`, or `require-approval` with fresh user approval. Skip when
-   `denied`.
+   `denied`. For macOS fallbacks, state destination architecture explicitly
+   (for example `platform=macOS,arch=arm64`).
 4. Report blocked when no authorized path exists, including the policy values in
    force, checks not run, next action, and residual risk.
 
 Never infer fallback permission from shell access or an installed command. Preserve
 the same project/workspace, scheme, configuration, exact destination, serialized
 test scope, and reporting in any authorized fallback.
 
-Report scheme, simulator/device, and any failure with the next actionable tool call. Full checklist: [references/bootstrap-checklist.md](references/bootstrap-checklist.md).
+Report scheme, destination (simulatorId or macOS), and any failure with the next
+actionable tool call. Full checklist:
+[references/bootstrap-checklist.md](references/bootstrap-checklist.md).
 
 ## Step 6 — Handoff
 

.agents/skills/codex-bootstrap/assets/consumer-AGENTS.md.template

@@ -12,8 +12,12 @@ this contract for files in their scope.
 - Build configuration: `<CONFIGURATION>`
 - Target platforms: `<IOS_MACOS_WATCHOS_TVOS_VISIONOS_OR_SWIFT_PACKAGE>`
 - Minimum deployment versions: `<PLATFORM_VERSION_PAIRS>`
-- Simulator: `<EXACT_SIMULATOR_ID>` or project-local defaults in
-  `.xcodebuildmcp/config.yaml`
+- Destination:
+  - iOS / simulator targets: `<EXACT_SIMULATOR_ID>` or project-local defaults in
+    `.xcodebuildmcp/config.yaml`
+  - macOS targets: `<MACOS_ARCH_OR_PROJECT_DEFAULT>` (enable the XcodeBuildMCP
+    `macos` workflow); leave as `n/a` when the repo is iOS-only
+  - Shared iOS + macOS: fill both of the above
 - Formatter: `<REPOSITORY_NATIVE_FORMATTER_COMMAND_OR_NOT_CONFIGURED>`
 - Linter: `<REPOSITORY_NATIVE_LINTER_COMMAND_OR_NOT_CONFIGURED>`
 - Additional type or build checks:
@@ -40,8 +44,8 @@ Interpret as:
 
 Do not guess missing values. Inspect checked-in project configuration and scripts,
 then ask before choosing among materially different targets or workflows. Keep
-machine-specific simulator IDs in project-local configuration only when the team
-intentionally shares them.
+machine-specific simulator IDs and Mac destinations in project-local configuration
+only when the team intentionally shares them.
 
 ## Engineering lifecycle
 
@@ -86,42 +90,58 @@ Use an inspect → implement → verify → handoff lifecycle, scaled to the tas
 - Summarize what changed and why.
 - Report every verification command or MCP action and its outcome.
 - Report the active project/workspace, scheme, configuration, platform, and exact
-  simulator or device used.
+  destination (simulatorId and/or macOS) used.
 - Identify skipped or failed checks, remaining risks, and preserved unrelated
   working-tree changes.
 
 ## XcodeBuildMCP workflow
 
-Use XcodeBuildMCP first for Apple-platform builds, tests, simulator runs, and
-simulator management. Do not silently fall back to raw `xcodebuild`, `xcrun`, or
-`simctl`.
+Use XcodeBuildMCP first for Apple-platform builds, tests, and runs. Do not
+silently fall back to raw `xcodebuild`, `xcrun`, or `simctl`. Branch by the
+**Target platforms** value above — do not use iOS simulator tools for a
+macOS-only app, and do not skip the `macos` workflow when macOS is in scope.
 
 1. Before the first build, run, or test action in a session, call
    `session_show_defaults`. Report the active project/workspace, scheme,
-   configuration, and simulator/device.
+   configuration, and platform destination.
 2. If defaults are missing or incorrect, use `session_set_defaults`; use project
-   discovery only when the correct path is not already known. Prefer one exact
-   `simulatorId` over name-only or `OS=latest` destinations.
-3. Reuse an already-booted simulator. For a manual simulator launch, use
-   `build_run_sim`; do not separately build, boot, install, and launch for the
-   same operation.
-4. Use `test_sim` as the complete simulator test workflow. Do not build
-   immediately before it unless a separate compile-only build was requested.
-5. Before simulator tests, check for another active `xcodebuild`, `xctest`, or
-   project test-runner process. Wait rather than starting a concurrent run for
-   the same project.
-6. Run simulator tests serially with
-   `extraArgs: ["-parallel-testing-enabled", "NO"]` unless the project explicitly
-   requires and has verified parallel workers.
-7. If an MCP capability is unavailable, apply **Apple verification policy**
+   discovery only when the correct path is not already known.
+3. **iOS (simulator) targets:**
+   - Prefer one exact `simulatorId` over name-only or `OS=latest` destinations.
+   - Reuse an already-booted simulator. For a manual launch, use `build_run_sim`;
+     do not separately build, boot, install, and launch for the same operation.
+   - Use `test_sim` as the complete simulator test workflow. Do not build
+     immediately before it unless a separate compile-only build was requested.
+   - Before simulator tests, check for another active `xcodebuild`, `xctest`, or
+     project test-runner process. Wait rather than starting a concurrent run for
+     the same project.
+   - Run simulator tests serially with
+     `extraArgs: ["-parallel-testing-enabled", "NO"]` unless the project
+     explicitly requires and has verified parallel workers.
+   - Optional: `screenshot` / `snapshot_ui` when the `ui-automation` workflow is
+     enabled (iOS simulator only).
+4. **macOS targets:**
+   - Enable and use the XcodeBuildMCP `macos` workflow.
+   - Prefer `build_run_macos` for a launch smoke.
+   - Use `test_macos` when a test target exists; default
+     `extraArgs: ["-parallel-testing-enabled", "NO"]`.
+   - If neither launch smoke nor `test_macos` runs, require at least
+     `build_macos` so the target is compiled.
+   - Do **not** call `build_run_sim`, `test_sim`, or ui-automation
+     screenshot/hierarchy tools for macOS — those are iOS-simulator-only.
+   - If no test target exists yet, report that `test_macos` was skipped and the
+     residual risk only after `build_run_macos` or `build_macos` succeeds.
+5. **Shared iOS + macOS:** verify each platform with its branch above.
+6. If an MCP capability is unavailable, apply **Apple verification policy**
    above for XcodeBuildMCP CLI. Use CLI only when that policy is `allowed`, or
    when it is `require-approval` and the user has just approved this step. If the
    policy is `denied`, skip CLI and evaluate the next ladder step.
-8. Use repository-native raw `xcodebuild`, `xcrun`, or `simctl` only when the
+7. Use repository-native raw `xcodebuild`, `xcrun`, or `simctl` only when the
    raw-tooling policy is `allowed`, or `require-approval` with fresh user
    approval. Preserve the same project/workspace, scheme, configuration, exact
-   destination, serialized execution, and test scope.
-9. If no authorized path exists, report blocked with the exact unavailable
+   destination, serialized execution, and test scope. For macOS fallbacks, state
+   destination architecture explicitly (for example `platform=macOS,arch=arm64`).
+8. If no authorized path exists, report blocked with the exact unavailable
    capability, policy value in force, checks not run, next action, and residual
    risk.