From d6bb59314330747f31ae94b4ce24e9ec71b3b315 Mon Sep 17 00:00:00 2001 From: brbndon Date: Tue, 21 Jul 2026 12:16:52 -0700 Subject: [PATCH 1/5] fix(skills): fix macOS verification routing and strengthen foundation entry - Branch bootstrap/verification to macos tools (test_macos) vs iOS simulator - Strengthen apple-development-foundation as global bootstrap entry point - Add competing macOS skills routing plan and evaluation fixtures --- .agents/skills/README.md | 2 +- .../apple-development-foundation/SKILL.md | 25 ++++++--- .../master-skill.json | 9 ++-- .../references/competing-macos-skills-plan.md | 51 +++++++++++++++++++ .agents/skills/codex-bootstrap/SKILL.md | 36 +++++++++---- .../references/bootstrap-checklist.md | 17 ++++--- .agents/skills/manifest.json | 17 ++++--- .../swift-testing-verification/SKILL.md | 15 ++++-- AGENTS.md | 2 +- Evaluations/skill-routing.json | 39 ++++++++++++++ MCP.md | 12 ++--- README.md | 6 +-- docs/reference/prompts.mdx | 10 ++-- docs/skills/bootstrap.mdx | 19 ++++--- docs/skills/index.mdx | 2 +- docs/skills/skill-evaluation.mdx | 2 +- docs/tools/xcodebuildmcp.mdx | 4 +- 17 files changed, 201 insertions(+), 67 deletions(-) create mode 100644 .agents/skills/apple-development-foundation/references/competing-macos-skills-plan.md diff --git a/.agents/skills/README.md b/.agents/skills/README.md index 98bf64c..b6c8c09 100644 --- a/.agents/skills/README.md +++ b/.agents/skills/README.md @@ -6,7 +6,7 @@ These source-controlled skills are intentionally general Apple-development workf | 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 | diff --git a/.agents/skills/apple-development-foundation/SKILL.md b/.agents/skills/apple-development-foundation/SKILL.md index 31d50aa..fb2eea6 100644 --- a/.agents/skills/apple-development-foundation/SKILL.md +++ b/.agents/skills/apple-development-foundation/SKILL.md @@ -1,13 +1,13 @@ --- 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 @@ -15,11 +15,16 @@ requested. 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). diff --git a/.agents/skills/apple-development-foundation/master-skill.json b/.agents/skills/apple-development-foundation/master-skill.json index 05d78ab..ef70a3c 100644 --- a/.agents/skills/apple-development-foundation/master-skill.json +++ b/.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." } diff --git a/.agents/skills/apple-development-foundation/references/competing-macos-skills-plan.md b/.agents/skills/apple-development-foundation/references/competing-macos-skills-plan.md new file mode 100644 index 0000000..ffdf9fb --- /dev/null +++ b/.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. diff --git a/.agents/skills/codex-bootstrap/SKILL.md b/.agents/skills/codex-bootstrap/SKILL.md index f66d0ca..0f230c1 100644 --- a/.agents/skills/codex-bootstrap/SKILL.md +++ b/.agents/skills/codex-bootstrap/SKILL.md @@ -82,18 +82,29 @@ 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 when useful; run `test_macos` when a test target exists (required + verification when tests are present). 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 + - **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,7 +115,8 @@ 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. @@ -112,7 +124,9 @@ Never infer fallback permission from shell access or an installed command. Prese 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 diff --git a/.agents/skills/codex-bootstrap/references/bootstrap-checklist.md b/.agents/skills/codex-bootstrap/references/bootstrap-checklist.md index ff6a46a..3b41a4e 100644 --- a/.agents/skills/codex-bootstrap/references/bootstrap-checklist.md +++ b/.agents/skills/codex-bootstrap/references/bootstrap-checklist.md @@ -18,8 +18,8 @@ Use during and after `$codex-bootstrap` in the **consumer workspace**. - [ ] Existing consumer instructions preserved unless an explicit merge was authorized - [ ] New guidance previewed from `assets/consumer-AGENTS.md.template` when applicable - [ ] Project/workspace, scheme, configuration, platforms, deployment versions, - simulator/config, and repository-native check commands customized or left as - explicit placeholders + iOS simulatorId and/or macOS destination notes, and repository-native check + commands customized or left as explicit placeholders - [ ] Apple verification policy knobs set or reviewed (XcodeBuildMCP CLI fallback and raw `xcodebuild` / `xcrun` / `simctl`: each `require-approval` | `allowed` | `denied`; keep template default `require-approval` unless the @@ -45,11 +45,16 @@ Use during and after `$codex-bootstrap` in the **consumer workspace**. ## XcodeBuildMCP verification - [ ] `session_show_defaults` called -- [ ] Project/workspace, scheme, configuration, and exact simulator context confirmed -- [ ] No same-project simulator test process already active -- [ ] Build succeeded on target platform +- [ ] Project/workspace, scheme, configuration, and platform destination confirmed +- [ ] Platform branch followed (iOS simulator tools vs macOS `macos` workflow) +- [ ] iOS: exact `simulatorId`; no competing same-project simulator test process; + `build_run_sim` / `test_sim` as applicable +- [ ] macOS: `macos` workflow enabled; `build_run_macos` and/or `test_macos` as + applicable — not `test_sim` / ui-automation - [ ] Tests run serially with parallel testing disabled by default (if present) -- [ ] Optional: screenshot or view hierarchy confirms launch +- [ ] Optional iOS-only: screenshot or view hierarchy confirms launch +- [ ] macOS: no screenshot/hierarchy required (ui-automation is iOS-only); if no + tests yet, `test_macos` skip and residual risk reported - [ ] If MCP was unavailable, fallback followed consumer policy enums (`allowed`, or `require-approval` with fresh approval for that step; never when `denied`); otherwise the task was reported blocked with policy values in force diff --git a/.agents/skills/manifest.json b/.agents/skills/manifest.json index 5fe78ac..c9842b3 100644 --- a/.agents/skills/manifest.json +++ b/.agents/skills/manifest.json @@ -5,7 +5,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", @@ -15,14 +15,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." }, @@ -52,18 +53,18 @@ ], "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." }, "skills": [ { "name": "apple-development-foundation", "path": "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.", "role": "router", "scope": "repository-or-user", - "purpose": "Reference-first skill router with optional foundation audits", - "use_for": "reference-first child-skill routing and explicitly requested foundation audits", - "do_not_use_for": "replacing child instructions, implied audits or verification, or claiming automatic activation", + "purpose": "Global entry-point router for foundation bootstrap and child-skill selection, with optional foundation audits", + "use_for": "new iOS/macOS SwiftUI app bootstrap routing, reference-first child-skill selection, and explicitly requested foundation audits", + "do_not_use_for": "replacing child instructions, implied audits or verification, claiming automatic activation, or generic non-foundation macOS/iOS work", "installable": true, "router_included": false, "scripts": false, diff --git a/.agents/skills/swift-testing-verification/SKILL.md b/.agents/skills/swift-testing-verification/SKILL.md index 313a28c..6966e15 100644 --- a/.agents/skills/swift-testing-verification/SKILL.md +++ b/.agents/skills/swift-testing-verification/SKILL.md @@ -15,13 +15,20 @@ For Xcode projects, use the first authorized path: 1. XcodeBuildMCP MCP tools. Before the first build/run/test, call `session_show_defaults` and report project/workspace, scheme, configuration, - and exact simulator/device. Use one exact `simulatorId`; serialize same-project - simulator tests and default `test_sim` to - `extraArgs: ["-parallel-testing-enabled", "NO"]`. + and platform destination. Branch by platform: + - **iOS simulator:** one exact `simulatorId`; serialize same-project simulator + tests; prefer `test_sim` with + `extraArgs: ["-parallel-testing-enabled", "NO"]`. + - **macOS:** enable/use the `macos` workflow; prefer `test_macos` (and + `build_run_macos` when a launch smoke is needed). Do not use `test_sim` or + ui-automation screenshot/hierarchy tools for macOS — those are + iOS-simulator-only. If no test target exists, report the skip and residual + risk rather than claiming UI verification. 2. XcodeBuildMCP CLI only when active repository/user policy explicitly permits CLI fallback. 3. Repository-native raw Xcode tooling only when active policy authorizes it; - obtain explicit approval when required. + obtain explicit approval when required. For macOS, include an explicit + destination (for example `platform=macOS,arch=arm64`). 4. Report blocked when no authorized path exists. Never infer authorization from shell access or installed binaries. Preserve the diff --git a/AGENTS.md b/AGENTS.md index b890163..11d291d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,7 @@ Agent-facing playbook (install, routing, MCP, verification): Blume site under `d - Keep skills neutral and reusable: no business models, branding, secrets, user-specific paths, or hidden network behavior - Follow the Apple verification capability ladder in `MCP.md`: XcodeBuildMCP MCP tools first; XcodeBuildMCP CLI only when the active project/user policy explicitly permits it; repository-native raw Xcode tooling only when that policy authorizes it; otherwise report blocked. Never infer fallback permission from tool availability. - For Maestro app testing, use `$maestro-apple-app-testing` as the main workflow; combine XcodeBuildMCP for Apple builds/simulators with Maestro MCP and CLI flows for UI inspection and regression coverage. -- Use `$codex-bootstrap` or the `codex-bootstrap` skill when starting a new iOS/macOS SwiftUI project with these skills +- Use `$apple-development-foundation` for new-chat routing and new iOS/macOS app bootstrap (it shortlists `$codex-bootstrap`); use `$codex-bootstrap` directly when already selected - Update skills through `.agents/skills/`; see `docs/skills/skill-authoring-guide.mdx` before changing skill behavior ## Skill routing diff --git a/Evaluations/skill-routing.json b/Evaluations/skill-routing.json index 73aa796..3dba0ea 100644 --- a/Evaluations/skill-routing.json +++ b/Evaluations/skill-routing.json @@ -43,6 +43,26 @@ "report_residual_risk": true } } + }, + { + "id": "foundation-router-use-bootstrap-macos", + "prompt": "Use $apple-development-foundation to bootstrap a new macOS-only SwiftUI app in /Projects/DeskNotes with a single root shell and no tabs.", + "expected": { + "skill_ids": [ + "apple-development-foundation", + "codex-bootstrap", + "swift-testing-verification" + ], + "workspace_classification": "consumer-workspace", + "implementation_authorized": true, + "audit_expected": false, + "verification_category": "apple-code", + "stop_condition": "none", + "handoff": { + "report_exact_checks": true, + "report_residual_risk": true + } + } } ], "should_not_use": [ @@ -106,6 +126,25 @@ } } }, + { + "id": "bootstrap-use-new-macos-app", + "prompt": "Bootstrap a new macOS SwiftUI app in /Projects/DeskNotes; verify with XcodeBuildMCP macOS tools, not the iOS simulator.", + "expected": { + "skill_ids": [ + "codex-bootstrap", + "swift-testing-verification" + ], + "workspace_classification": "consumer-workspace", + "implementation_authorized": true, + "audit_expected": false, + "verification_category": "apple-code", + "stop_condition": "none", + "handoff": { + "report_exact_checks": true, + "report_residual_risk": true + } + } + }, { "id": "bootstrap-use-shared-app-skeleton", "prompt": "Set up a shared iOS and macOS SwiftUI app skeleton in the named consumer repository, including neutral local design tokens.", diff --git a/MCP.md b/MCP.md index 70c3228..793b6d9 100644 --- a/MCP.md +++ b/MCP.md @@ -68,20 +68,20 @@ See the host’s live tool list and any global `xcodebuildmcp` skill for version **Bootstrap a new SwiftUI app:** -> Bootstrap a new iOS (or macOS) SwiftUI app using `$codex-bootstrap` and the skills in `/path/to/AppleDevelopmentFoundation/.agents/skills`. If the app has multiple peer destinations, use `$swiftui-tab-navigation` for native primary navigation. Use the consumer's design system or create a minimal neutral one. Verify with XcodeBuildMCP. +> Use `$apple-development-foundation` as the entry point to bootstrap a new iOS (or macOS) SwiftUI app in the consumer workspace. It should route to `$codex-bootstrap` and chain `$swiftui-tab-navigation`, `$apple-design-system`, `$swiftui-component-author`, and review skills as needed. Verify with XcodeBuildMCP on the correct platform. **Verify after bootstrap or feature work:** -> Call `session_show_defaults`, then build and test on the iOS simulator with XcodeBuildMCP (`build_run_sim` / `test_sim` preferred). Report scheme, simulatorId, and any failures with the next actionable tool call. +> Call `session_show_defaults`, then verify with XcodeBuildMCP on the target platform: iOS → `build_run_sim` / `test_sim` (exact `simulatorId`); macOS → enable `macos` workflow, then `build_run_macos` / `test_macos`. Do not use simulator or ui-automation tools for macOS-only apps. Report scheme, destination, and any failures with the next actionable tool call. ## Bootstrap verification checklist After `$codex-bootstrap` completes initial structure: -1. `session_show_defaults` — confirm project/workspace, scheme, configuration, and exact simulator/device -2. Build on simulator via `build_run_sim` (or macOS via `build_run_macos` if applicable) -3. Run unit tests if present (`test_sim` / `test_macos`) -4. Optional: capture a screenshot or view hierarchy to confirm the shell launches +1. `session_show_defaults` — confirm project/workspace, scheme, configuration, and platform destination +2. **iOS:** `build_run_sim` for launch smoke; **macOS:** `build_run_macos` (requires `macos` workflow) +3. Run unit tests if present (`test_sim` / `test_macos`) with parallel testing disabled by default +4. Optional iOS-only: capture a screenshot or view hierarchy (`ui-automation`). macOS has no XcodeBuildMCP UI automation — rely on `test_macos` (or report skipped tests) 5. Apply review skills (`swift-concurrency-review`, `apple-security-privacy-review`, `apple-accessibility-review`) before shipping shared components Keep bootstraps focused on reusable skills and clean architecture in the **consumer workspace**. Do not rebuild the archived package in this repo unless asked — see [ARCHIVE.md](ARCHIVE.md). diff --git a/README.md b/README.md index 03b15f9..8c98090 100644 --- a/README.md +++ b/README.md @@ -53,13 +53,13 @@ See [MCP.md](MCP.md) for XcodeBuildMCP setup, tool names, copy-paste prompts, an Point Codex at this repo when bootstrapping apps: -> Use the skills from `/path/to/AppleDevelopmentFoundation/.agents/skills` (start with `codex-bootstrap`). +> Use the skills from `/path/to/AppleDevelopmentFoundation/.agents/skills` (start with `$apple-development-foundation` → `$codex-bootstrap` for new apps). ## Skill inventory | Skill | One-liner | | --- | --- | -| `apple-development-foundation` | Reference-first child-skill router with optional foundation audits | +| `apple-development-foundation` | Global entry point: bootstrap routing + child-skill shortlist (audits only when asked) | | `codex-bootstrap` | Bootstrap a new iOS/macOS SwiftUI project using these skills | | `apple-platform-planner` | Plan a platform feature before implementation | | `swiftui-tab-navigation` | Build native app-level tabs with system Liquid Glass behavior | @@ -78,7 +78,7 @@ Point Codex at this repo when bootstrapping apps: Full use/do-not-use table: [.agents/skills/README.md](.agents/skills/README.md). Manifest: [.agents/skills/manifest.json](.agents/skills/manifest.json). -For a single reusable baseline in a new chat, invoke `$apple-development-foundation`; it uses its [machine-readable catalog](.agents/skills/apple-development-foundation/master-skill.json) to shortlist child skills before reading their instructions. Audits and foundation verification are explicit requests. +For a single reusable baseline in a new chat—especially a new iOS or macOS app—invoke `$apple-development-foundation`; it uses its [machine-readable catalog](.agents/skills/apple-development-foundation/master-skill.json) to shortlist child skills (including `codex-bootstrap`) before reading their instructions. Prefer it over generic host-local macOS/iOS skills for foundation workflows. Audits and foundation verification are explicit requests. ## External skill routing diff --git a/docs/reference/prompts.mdx b/docs/reference/prompts.mdx index 8e302fb..a59adfc 100644 --- a/docs/reference/prompts.mdx +++ b/docs/reference/prompts.mdx @@ -30,7 +30,8 @@ Start with `$apple-development-foundation` when the task is broad or the chat is ```text Goal: Bootstrap a new iOS (or macOS) SwiftUI app in the consumer workspace. Constraints: -- Use $codex-bootstrap and sibling skills from /path/to/AppleDevelopmentFoundation/.agents/skills. +- Entry point: $apple-development-foundation → $codex-bootstrap (or $codex-bootstrap if already selected). +- Prefer foundation routing over generic host-local macOS/iOS skills. - If multiple peer destinations: $swiftui-tab-navigation for native primary navigation. - Design system: reuse consumer tokens or create a minimal neutral system in the consumer repo. - No invented business domain; no edits to AppleDevelopmentFoundation archived package. @@ -39,7 +40,9 @@ Inputs: - Navigation shape: - Consumer path: <…> Done when: App skeleton builds; skill chain applied or explicitly skipped with reason; handoff lists next skills. -Verification: session_show_defaults → build_run_sim (prefer) → test_sim if present → optional screenshot/snapshot_ui. +Verification: +- iOS: session_show_defaults → build_run_sim → test_sim if present → optional screenshot/snapshot_ui +- macOS: enable macos workflow → build_run_macos → test_macos if present (no ui-automation) ``` ## Ship a feature @@ -107,8 +110,7 @@ Done when: Defaults shown; build and tests executed; outcomes and next tool call Verification: 1. session_show_defaults (session_set_defaults if needed) 2. discover_projs only if defaults still wrong/missing -3. build_run_sim for launch (or build_run_macos / build_run_device) -4. test_sim / test_macos if present +3. iOS: build_run_sim → test_sim; macOS: enable macos workflow → build_run_macos → test_macos (no ui-automation) Never claim pass without running an authorized tool. Report project/workspace, scheme, configuration, exact destination, command/tool, and residual risk. ``` diff --git a/docs/skills/bootstrap.mdx b/docs/skills/bootstrap.mdx index 224f17f..2c59142 100644 --- a/docs/skills/bootstrap.mdx +++ b/docs/skills/bootstrap.mdx @@ -5,7 +5,10 @@ description: Scaffold a new iOS or macOS SwiftUI app in the consumer workspace w # Bootstrap -Invoke **`$codex-bootstrap`** when starting a new iOS/macOS SwiftUI project or major feature set in the **consumer** workspace. +Invoke **`$apple-development-foundation`** (routes to **`$codex-bootstrap`**) when +starting a new iOS/macOS SwiftUI project or major feature set in the **consumer** +workspace. You may also invoke `$codex-bootstrap` directly when the bootstrap +skill is already selected. | | | | --- | --- | @@ -51,14 +54,16 @@ Extraction of proven app code → `$reusable-code-extractor` into the **consumer ## Verification (XcodeBuildMCP) 1. `session_show_defaults`; report project/workspace, scheme, configuration, and - exact simulator/device (then `session_set_defaults` if needed) + platform destination (then `session_set_defaults` if needed) 2. `discover_projs` only if defaults are still wrong/missing -3. Simulator: prefer **`build_run_sim`**. macOS: **`build_run_macos`** -4. Before simulator tests, wait for any same-project `xcodebuild`, `xctest`, or - project test runner; use `test_sim` without a redundant build and default to +3. **iOS simulator:** prefer **`build_run_sim`**; wait for same-project test + runners; run `test_sim` without a redundant build and default to `extraArgs: ["-parallel-testing-enabled", "NO"]` -5. Tests on macOS if present: `test_macos` -6. Optional `screenshot` / `snapshot_ui` +4. **macOS:** enable the `macos` workflow; prefer **`build_run_macos`** for + launch smoke; run **`test_macos`** when tests exist (same parallel-testing + default). Do not use `test_sim` or ui-automation tools — they are + iOS-simulator-only +5. Optional iOS-only: `screenshot` / `snapshot_ui` If MCP is unavailable, use the XcodeBuildMCP CLI only when active policy explicitly permits it. Use repository-native raw Apple tooling only when active policy diff --git a/docs/skills/index.mdx b/docs/skills/index.mdx index 7b45493..6dceb49 100644 --- a/docs/skills/index.mdx +++ b/docs/skills/index.mdx @@ -19,7 +19,7 @@ Deep procedure lives in each skill’s `SKILL.md` — prefer reading that over f | Skill | Path | Use for | Do not use for | | --- | --- | --- | --- | -| `apple-development-foundation` | `.agents/skills/apple-development-foundation/SKILL.md` | reference-first child-skill routing and explicitly requested foundation audits | replacing child instructions, implied audits or verification, or claiming automatic activation | +| `apple-development-foundation` | `.agents/skills/apple-development-foundation/SKILL.md` | 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` | `.agents/skills/codex-bootstrap/SKILL.md` | 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` | `.agents/skills/apple-platform-planner/SKILL.md` | planning an Apple-platform feature | implementation-only requests | | `swiftui-tab-navigation` | `.agents/skills/swiftui-tab-navigation/SKILL.md` | native app-level SwiftUI tabs and system Liquid Glass tab chrome | page-style tabs, segmented controls, or business-specific screens | diff --git a/docs/skills/skill-evaluation.mdx b/docs/skills/skill-evaluation.mdx index ecf2302..9cf3709 100644 --- a/docs/skills/skill-evaluation.mdx +++ b/docs/skills/skill-evaluation.mdx @@ -15,7 +15,7 @@ The scope below describes where a skill performs its work. The manifest's `repos | Skill | Should trigger (two examples) | Should not trigger (two examples) | Overlap risk and explicit invocation | Scope | | --- | --- | --- | --- | --- | -| `apple-development-foundation` | “Route this iOS import task to foundation skills.”; “Compare this project’s skill inventory with the foundation catalog.” | “Implement the selected import flow.”; “Run an installer check for an ordinary app task.” | Routes before child workflows; use `$apple-development-foundation` for explicit routing or audits, then invoke selected children. | Consumer routing or foundation audit | +| `apple-development-foundation` | “Bootstrap a new macOS SwiftUI app with the foundation.”; “Route this iOS import task to foundation skills.”; “Compare this project’s skill inventory with the foundation catalog.” | “Implement the selected import flow without routing.”; “Run an installer check for an ordinary app task.” | Global entry point before child workflows and generic macOS skills; use `$apple-development-foundation` for new-app bootstrap routing or audits, then invoke selected children. | Consumer routing/bootstrap or foundation audit | | `apple-platform-planner` | “Plan a shared iOS/macOS document-import feature.”; “Design a macOS settings feature.” | “Implement the approved settings plan.”; “Plan a web dashboard.” | Overlaps module author for new targets; use `$apple-platform-planner` for architecture only. | Consumer workspace | | `swiftui-tab-navigation` | “Add native Plan and Settings tabs that use Liquid Glass on iOS 26.”; “Replace this custom SwiftUI tab bar with system navigation.” | “Build a page-style photo carousel.”; “Add one settings button.” | Overlaps component author and platform adaptation; use `$swiftui-tab-navigation` for the app-level peer-destination shell. | Consumer workspace | | `swiftui-component-author` | “Create a reusable SwiftUI error banner.”; “Refactor this reusable picker component.” | “Build our checkout screen.”; “Review this actor.” | Overlaps design system for tokens; use `$swiftui-component-author` for component implementation. | Consumer workspace | diff --git a/docs/tools/xcodebuildmcp.mdx b/docs/tools/xcodebuildmcp.mdx index 8546888..faf6670 100644 --- a/docs/tools/xcodebuildmcp.mdx +++ b/docs/tools/xcodebuildmcp.mdx @@ -92,9 +92,9 @@ By default the MCP server advertises **`simulator`** tools. **Session-management | iOS simulator build/run/test | `simulator` (default) | Core build path | | Show / set / clear defaults; named profiles | `session-management` (default) | See session tools below | | Simulator boot/erase/appearance/location | `simulator-management` | Lifecycle & env chrome | -| UI gestures, screenshots, hierarchy automation | `ui-automation` | Often paired with `snapshot_ui` | +| UI gestures, screenshots, hierarchy automation | `ui-automation` | **iOS simulator only** — not available for macOS apps | | Physical device | `device` | Needs signing in Xcode | -| macOS app build/run/test | `macos` | | +| macOS app build/run/test | `macos` | Prefer `build_run_macos` / `test_macos`; no UI automation tools | | SwiftPM packages | `swift-package` | | | Debug attach / breakpoints | `debugging` | Stateful (daemon in CLI mode) | | Scaffold new projects | `project-scaffolding` | | From 0cc24777a80e6fa0238d1149cb0b6b8a6bc5517a Mon Sep 17 00:00:00 2001 From: brbndon Date: Tue, 21 Jul 2026 12:26:16 -0700 Subject: [PATCH 2/5] docs(skills): route new-app entry points through foundation - Point MCP and primary docs at $apple-development-foundation first - Qualify direct $codex-bootstrap as only when already selected --- MCP.md | 2 +- docs/index.mdx | 2 +- docs/skills/index.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/MCP.md b/MCP.md index 793b6d9..72e9df3 100644 --- a/MCP.md +++ b/MCP.md @@ -64,7 +64,7 @@ See the host’s live tool list and any global `xcodebuildmcp` skill for version **Reference these skills in any Codex session:** -> Use the skills from `/path/to/AppleDevelopmentFoundation/.agents/skills` — start with `codex-bootstrap`, then apply `swiftui-tab-navigation`, `apple-design-system`, `swiftui-component-author`, and review skills as needed. +> Use the skills from `/path/to/AppleDevelopmentFoundation/.agents/skills` — start with `$apple-development-foundation` for routing (it shortlists `$codex-bootstrap` for new apps). Invoke `$codex-bootstrap` directly only when that skill is already selected. Then apply `$swiftui-tab-navigation`, `$apple-design-system`, `$swiftui-component-author`, and review skills as needed. **Bootstrap a new SwiftUI app:** diff --git a/docs/index.mdx b/docs/index.mdx index 260daa9..c0c8e1b 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -24,7 +24,7 @@ sidebar: | Goal | Start here | | --- | --- | | Install skills and open a first verified session | [Quickstart](/quickstart) | -| Bootstrap a new iOS/macOS SwiftUI app | [Bootstrap](/skills/bootstrap) · `$codex-bootstrap` | +| Bootstrap a new iOS/macOS SwiftUI app | [Bootstrap](/skills/bootstrap) · `$apple-development-foundation` → `$codex-bootstrap` | | Follow the full agent session loop | [Session workflow](/workflow) | | Choose the right skill for a task | [Skill routing](/workflow/skill-routing) · `$apple-development-foundation` | | Run a common scenario end-to-end | [Task recipes](/workflow/task-recipes) | diff --git a/docs/skills/index.mdx b/docs/skills/index.mdx index 6dceb49..e2ff7f5 100644 --- a/docs/skills/index.mdx +++ b/docs/skills/index.mdx @@ -41,7 +41,7 @@ Deep procedure lives in each skill’s `SKILL.md` — prefer reading that over f | Task | Guide | Skill(s) | | --- | --- | --- | -| New app | [Bootstrap](/skills/bootstrap) | `$codex-bootstrap` | +| New app | [Bootstrap](/skills/bootstrap) | `$apple-development-foundation` → `$codex-bootstrap` (direct `$codex-bootstrap` only if already selected) | | App-level tabs / Liquid Glass chrome | [Task recipes](/workflow/task-recipes#author-reusable-ui-tabs-tokens-components) · skill `SKILL.md` | `$swiftui-tab-navigation` | | Design tokens / shared components | [Task recipes](/workflow/task-recipes#author-reusable-ui-tabs-tokens-components) | `$apple-design-system` → `$swiftui-component-author` | | iOS vs macOS divergence | [Task recipes](/workflow/task-recipes#ship-a-feature-in-an-existing-app) | `$ios-macos-platform-adaptation` | From 7026f772adfff6cfb3ecaa81b6b991152bb8d47c Mon Sep 17 00:00:00 2001 From: brbndon Date: Tue, 21 Jul 2026 12:26:23 -0700 Subject: [PATCH 3/5] docs(skills): align workflow entry paths with foundation router MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Require foundation → bootstrap for new-app recipes and consumer bootstrap - Qualify direct child invocation in quickstart --- docs/quickstart.mdx | 2 +- docs/workflow/consumer-workspace.mdx | 3 ++- docs/workflow/task-recipes.mdx | 4 ++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index 659d41a..7457332 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -128,7 +128,7 @@ More scenarios: [Copy-paste prompts](/reference/prompts). ## 4. First task checklist 1. Confirm **active workspace** = consumer app/package (not this foundation repo unless skill maintenance was requested). -2. Route: `$apple-development-foundation` for a shortlist, or invoke the skill directly (`$codex-bootstrap`, `$swiftui-component-author`, …). +2. Route: `$apple-development-foundation` for new chats and new-app bootstrap (it shortlists `$codex-bootstrap`). Invoke a child skill directly only when it is already selected or the task is clearly scoped to that child (`$swiftui-component-author`, …). 3. Call **`session_show_defaults`** before the first build/run/test; report the project/workspace, scheme, configuration, and exact simulator/device, then fix missing values via **`session_set_defaults`** if needed. diff --git a/docs/workflow/consumer-workspace.mdx b/docs/workflow/consumer-workspace.mdx index 841ef3b..5e6e372 100644 --- a/docs/workflow/consumer-workspace.mdx +++ b/docs/workflow/consumer-workspace.mdx @@ -41,7 +41,8 @@ When the user wants a new app: 3. With authorization, preview or create a missing root contract from the `codex-bootstrap/assets/consumer-AGENTS.md.template` skill asset using `./Scripts/init-consumer-guidance.sh --target --dry-run`. -4. Invoke `$codex-bootstrap` against the **consumer** path. +4. Invoke `$apple-development-foundation` so it routes to `$codex-bootstrap` against + the **consumer** path (use `$codex-bootstrap` directly only when already selected). 5. Chain sibling skills as needed (tabs, design system, components, reviews). 6. Verify with XcodeBuildMCP in that consumer project. diff --git a/docs/workflow/task-recipes.mdx b/docs/workflow/task-recipes.mdx index 4985599..04fd0d3 100644 --- a/docs/workflow/task-recipes.mdx +++ b/docs/workflow/task-recipes.mdx @@ -20,9 +20,9 @@ Short paths for coding agents. Pick the scenario that matches the user request, | Step | Action | | --- | --- | -| Skills | Optional `$apple-development-foundation` → **`$codex-bootstrap`** → chain in skill (planner, tabs, design system, components, platform, reviews, testing) | +| Skills | **`$apple-development-foundation`** → **`$codex-bootstrap`** → chain in skill (planner, tabs, design system, components, platform, reviews, testing). Invoke `$codex-bootstrap` directly only when already selected. | | Tools | XcodeBuildMCP | -| Verify | `session_show_defaults` → **`build_run_sim`** (prefer) → `test_sim` if present → optional `screenshot` / `snapshot_ui` | +| Verify | Platform branch: iOS → `build_run_sim` / `test_sim` (+ optional screenshot); macOS → `build_run_macos` / `test_macos` (no ui-automation) | | Do not | Expand this repo’s `archive/Sources/`; invent business domain the user did not supply | Details: [Bootstrap](/skills/bootstrap). From bef377a9031af10f2469d57a9bd1d26103daa73e Mon Sep 17 00:00:00 2001 From: brbndon Date: Tue, 21 Jul 2026 21:06:46 -0700 Subject: [PATCH 4/5] fix(skills): platform-branch consumer AGENTS and bootstrap fixtures - Branch generated consumer XcodeBuildMCP guidance for iOS vs macOS - Prepend apple-development-foundation on new-app bootstrap fixtures - Assert macOS verification tools in consumer guidance tests --- .../assets/consumer-AGENTS.md.template | 70 ++++++++++++------- Evaluations/skill-routing.json | 3 + Scripts/test-consumer-guidance.sh | 8 +++ 3 files changed, 55 insertions(+), 26 deletions(-) diff --git a/.agents/skills/codex-bootstrap/assets/consumer-AGENTS.md.template b/.agents/skills/codex-bootstrap/assets/consumer-AGENTS.md.template index fe507ba..85540c4 100644 --- a/.agents/skills/codex-bootstrap/assets/consumer-AGENTS.md.template +++ b/.agents/skills/codex-bootstrap/assets/consumer-AGENTS.md.template @@ -12,8 +12,12 @@ this contract for files in their scope. - Build configuration: `` - Target platforms: `` - Minimum deployment versions: `` -- Simulator: `` or project-local defaults in - `.xcodebuildmcp/config.yaml` +- Destination: + - iOS / simulator targets: `` or project-local defaults in + `.xcodebuildmcp/config.yaml` + - macOS targets: `` (enable the XcodeBuildMCP + `macos` workflow); leave as `n/a` when the repo is iOS-only + - Shared iOS + macOS: fill both of the above - Formatter: `` - Linter: `` - 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,56 @@ 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 when useful. + - Use `test_macos` when a test target exists; default + `extraArgs: ["-parallel-testing-enabled", "NO"]`. + - 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. +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. diff --git a/Evaluations/skill-routing.json b/Evaluations/skill-routing.json index 3dba0ea..25c54ba 100644 --- a/Evaluations/skill-routing.json +++ b/Evaluations/skill-routing.json @@ -111,6 +111,7 @@ "prompt": "Bootstrap a new iOS SwiftUI app in /Projects/Journal with Timeline and Settings as peer destinations.", "expected": { "skill_ids": [ + "apple-development-foundation", "codex-bootstrap", "swiftui-tab-navigation", "swift-testing-verification" @@ -131,6 +132,7 @@ "prompt": "Bootstrap a new macOS SwiftUI app in /Projects/DeskNotes; verify with XcodeBuildMCP macOS tools, not the iOS simulator.", "expected": { "skill_ids": [ + "apple-development-foundation", "codex-bootstrap", "swift-testing-verification" ], @@ -150,6 +152,7 @@ "prompt": "Set up a shared iOS and macOS SwiftUI app skeleton in the named consumer repository, including neutral local design tokens.", "expected": { "skill_ids": [ + "apple-development-foundation", "codex-bootstrap", "apple-design-system", "ios-macos-platform-adaptation", diff --git a/Scripts/test-consumer-guidance.sh b/Scripts/test-consumer-guidance.sh index 0a1d5d1..485b25b 100755 --- a/Scripts/test-consumer-guidance.sh +++ b/Scripts/test-consumer-guidance.sh @@ -28,6 +28,14 @@ assert_apple_verification_policy() { || fail "raw tooling default is not require-approval in $file" grep -q 'Shell access or an installed' "$file" \ || fail "missing shell-is-not-permission guidance in $file" + grep -q '\*\*macOS targets:\*\*' "$file" \ + || fail "missing macOS verification branch in $file" + grep -q 'test_macos' "$file" \ + || fail "missing test_macos in $file" + grep -q 'build_run_macos' "$file" \ + || fail "missing build_run_macos in $file" + grep -q '\*\*iOS (simulator) targets:\*\*' "$file" \ + || fail "missing iOS simulator verification branch in $file" } assert_apple_verification_policy "$template" From 84d9cc8a49cfe6a37875058677ed71affe107eab Mon Sep 17 00:00:00 2001 From: brbndon Date: Thu, 23 Jul 2026 10:02:28 -0700 Subject: [PATCH 5/5] fix(skills): require macOS compile when tests are absent - Prefer build_run_macos / test_macos, but require at least build_macos when neither launch smoke nor tests run - Align MCP checklist, consumer AGENTS template, and docs; assert build_macos in consumer guidance tests --- .agents/skills/codex-bootstrap/SKILL.md | 8 +++++--- .../codex-bootstrap/assets/consumer-AGENTS.md.template | 6 ++++-- .../codex-bootstrap/references/bootstrap-checklist.md | 8 +++++--- .agents/skills/swift-testing-verification/SKILL.md | 5 +++-- MCP.md | 4 ++-- Scripts/test-consumer-guidance.sh | 2 ++ docs/reference/prompts.mdx | 4 ++-- docs/skills/bootstrap.mdx | 3 ++- docs/workflow/task-recipes.mdx | 2 +- 9 files changed, 26 insertions(+), 16 deletions(-) diff --git a/.agents/skills/codex-bootstrap/SKILL.md b/.agents/skills/codex-bootstrap/SKILL.md index 0f230c1..3819a21 100644 --- a/.agents/skills/codex-bootstrap/SKILL.md +++ b/.agents/skills/codex-bootstrap/SKILL.md @@ -98,12 +98,14 @@ Use XcodeBuildMCP (see repo `MCP.md`) — not raw `xcodebuild`/`simctl`. Enable `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 when useful; run `test_macos` when a test target exists (required - verification when tests are present). Default + 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 + 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. diff --git a/.agents/skills/codex-bootstrap/assets/consumer-AGENTS.md.template b/.agents/skills/codex-bootstrap/assets/consumer-AGENTS.md.template index 85540c4..b6e6e60 100644 --- a/.agents/skills/codex-bootstrap/assets/consumer-AGENTS.md.template +++ b/.agents/skills/codex-bootstrap/assets/consumer-AGENTS.md.template @@ -122,13 +122,15 @@ macOS-only app, and do not skip the `macos` workflow when macOS is in scope. enabled (iOS simulator only). 4. **macOS targets:** - Enable and use the XcodeBuildMCP `macos` workflow. - - Prefer `build_run_macos` for a launch smoke when useful. + - 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. + 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 diff --git a/.agents/skills/codex-bootstrap/references/bootstrap-checklist.md b/.agents/skills/codex-bootstrap/references/bootstrap-checklist.md index 3b41a4e..0c63603 100644 --- a/.agents/skills/codex-bootstrap/references/bootstrap-checklist.md +++ b/.agents/skills/codex-bootstrap/references/bootstrap-checklist.md @@ -49,12 +49,14 @@ Use during and after `$codex-bootstrap` in the **consumer workspace**. - [ ] Platform branch followed (iOS simulator tools vs macOS `macos` workflow) - [ ] iOS: exact `simulatorId`; no competing same-project simulator test process; `build_run_sim` / `test_sim` as applicable -- [ ] macOS: `macos` workflow enabled; `build_run_macos` and/or `test_macos` as - applicable — not `test_sim` / ui-automation +- [ ] macOS: `macos` workflow enabled; `build_run_macos` (preferred) or + `test_macos` when tests exist; if neither runs, at least `build_macos` — + not `test_sim` / ui-automation - [ ] Tests run serially with parallel testing disabled by default (if present) - [ ] Optional iOS-only: screenshot or view hierarchy confirms launch - [ ] macOS: no screenshot/hierarchy required (ui-automation is iOS-only); if no - tests yet, `test_macos` skip and residual risk reported + tests yet, `test_macos` skip and residual risk reported only after + `build_run_macos` or `build_macos` succeeds - [ ] If MCP was unavailable, fallback followed consumer policy enums (`allowed`, or `require-approval` with fresh approval for that step; never when `denied`); otherwise the task was reported blocked with policy values in force diff --git a/.agents/skills/swift-testing-verification/SKILL.md b/.agents/skills/swift-testing-verification/SKILL.md index 6966e15..d0e59d9 100644 --- a/.agents/skills/swift-testing-verification/SKILL.md +++ b/.agents/skills/swift-testing-verification/SKILL.md @@ -22,8 +22,9 @@ For Xcode projects, use the first authorized path: - **macOS:** enable/use the `macos` workflow; prefer `test_macos` (and `build_run_macos` when a launch smoke is needed). Do not use `test_sim` or ui-automation screenshot/hierarchy tools for macOS — those are - iOS-simulator-only. If no test target exists, report the skip and residual - risk rather than claiming UI verification. + iOS-simulator-only. If no test target exists, require at least `build_macos` + (or `build_run_macos`) and report the test skip and residual risk rather + than claiming UI verification. 2. XcodeBuildMCP CLI only when active repository/user policy explicitly permits CLI fallback. 3. Repository-native raw Xcode tooling only when active policy authorizes it; diff --git a/MCP.md b/MCP.md index 72e9df3..b541269 100644 --- a/MCP.md +++ b/MCP.md @@ -79,9 +79,9 @@ See the host’s live tool list and any global `xcodebuildmcp` skill for version After `$codex-bootstrap` completes initial structure: 1. `session_show_defaults` — confirm project/workspace, scheme, configuration, and platform destination -2. **iOS:** `build_run_sim` for launch smoke; **macOS:** `build_run_macos` (requires `macos` workflow) +2. **iOS:** `build_run_sim` for launch smoke; **macOS:** `build_run_macos` (requires `macos` workflow). If macOS launch smoke and tests are not run, at least `build_macos` 3. Run unit tests if present (`test_sim` / `test_macos`) with parallel testing disabled by default -4. Optional iOS-only: capture a screenshot or view hierarchy (`ui-automation`). macOS has no XcodeBuildMCP UI automation — rely on `test_macos` (or report skipped tests) +4. Optional iOS-only: capture a screenshot or view hierarchy (`ui-automation`). macOS has no XcodeBuildMCP UI automation — rely on `test_macos`; if tests are absent, still require `build_run_macos` or at least `build_macos` (do not declare complete on residual risk alone) 5. Apply review skills (`swift-concurrency-review`, `apple-security-privacy-review`, `apple-accessibility-review`) before shipping shared components Keep bootstraps focused on reusable skills and clean architecture in the **consumer workspace**. Do not rebuild the archived package in this repo unless asked — see [ARCHIVE.md](ARCHIVE.md). diff --git a/Scripts/test-consumer-guidance.sh b/Scripts/test-consumer-guidance.sh index 485b25b..961509f 100755 --- a/Scripts/test-consumer-guidance.sh +++ b/Scripts/test-consumer-guidance.sh @@ -34,6 +34,8 @@ assert_apple_verification_policy() { || fail "missing test_macos in $file" grep -q 'build_run_macos' "$file" \ || fail "missing build_run_macos in $file" + grep -q 'build_macos' "$file" \ + || fail "missing build_macos compile fallback in $file" grep -q '\*\*iOS (simulator) targets:\*\*' "$file" \ || fail "missing iOS simulator verification branch in $file" } diff --git a/docs/reference/prompts.mdx b/docs/reference/prompts.mdx index a59adfc..a4cda6b 100644 --- a/docs/reference/prompts.mdx +++ b/docs/reference/prompts.mdx @@ -42,7 +42,7 @@ Inputs: Done when: App skeleton builds; skill chain applied or explicitly skipped with reason; handoff lists next skills. Verification: - iOS: session_show_defaults → build_run_sim → test_sim if present → optional screenshot/snapshot_ui -- macOS: enable macos workflow → build_run_macos → test_macos if present (no ui-automation) +- macOS: enable macos workflow → build_run_macos (or at least build_macos if no launch/tests) → test_macos if present (no ui-automation) ``` ## Ship a feature @@ -110,7 +110,7 @@ Done when: Defaults shown; build and tests executed; outcomes and next tool call Verification: 1. session_show_defaults (session_set_defaults if needed) 2. discover_projs only if defaults still wrong/missing -3. iOS: build_run_sim → test_sim; macOS: enable macos workflow → build_run_macos → test_macos (no ui-automation) +3. iOS: build_run_sim → test_sim; macOS: enable macos workflow → build_run_macos (or at least build_macos if no launch/tests) → test_macos if present (no ui-automation) Never claim pass without running an authorized tool. Report project/workspace, scheme, configuration, exact destination, command/tool, and residual risk. ``` diff --git a/docs/skills/bootstrap.mdx b/docs/skills/bootstrap.mdx index 2c59142..2defd30 100644 --- a/docs/skills/bootstrap.mdx +++ b/docs/skills/bootstrap.mdx @@ -61,7 +61,8 @@ Extraction of proven app code → `$reusable-code-extractor` into the **consumer `extraArgs: ["-parallel-testing-enabled", "NO"]` 4. **macOS:** enable the `macos` workflow; prefer **`build_run_macos`** for launch smoke; run **`test_macos`** when tests exist (same parallel-testing - default). Do not use `test_sim` or ui-automation tools — they are + default). If neither launch smoke nor tests run, require at least + **`build_macos`**. Do not use `test_sim` or ui-automation tools — they are iOS-simulator-only 5. Optional iOS-only: `screenshot` / `snapshot_ui` diff --git a/docs/workflow/task-recipes.mdx b/docs/workflow/task-recipes.mdx index 04fd0d3..b4e2a35 100644 --- a/docs/workflow/task-recipes.mdx +++ b/docs/workflow/task-recipes.mdx @@ -22,7 +22,7 @@ Short paths for coding agents. Pick the scenario that matches the user request, | --- | --- | | Skills | **`$apple-development-foundation`** → **`$codex-bootstrap`** → chain in skill (planner, tabs, design system, components, platform, reviews, testing). Invoke `$codex-bootstrap` directly only when already selected. | | Tools | XcodeBuildMCP | -| Verify | Platform branch: iOS → `build_run_sim` / `test_sim` (+ optional screenshot); macOS → `build_run_macos` / `test_macos` (no ui-automation) | +| Verify | Platform branch: iOS → `build_run_sim` / `test_sim` (+ optional screenshot); macOS → `build_run_macos` / `test_macos`, or at least `build_macos` if neither runs (no ui-automation) | | Do not | Expand this repo’s `archive/Sources/`; invent business domain the user did not supply | Details: [Bootstrap](/skills/bootstrap).