Skip to content
Apple Development Foundation
Esc
↑↓navigate↵open⌘Jpreview
On this page

Quickstart

Install foundation skills, point an agent at this repo, and complete a first verified session.

Get from a clone of this repository to a working agent session in a few minutes. Skills target the consumer app you build next — not this repo’s archived package.

Prerequisites

Tool Why
Xcode (recent stable) Build/test iOS and macOS targets
Codex Supported and verified host for this repository’s installer, skill discovery, and $skill-name workflow
XcodeBuildMCP Preferred build/test/simulator MCP
Node.js 22.12+ Optional — this Blume docs site only
Maestro Optional until you need UI flows

See Tools for the full stack.

Other skill- and MCP-capable hosts have documentation-only/manual compatibility; this repository does not provide verified Cursor or Claude Code adapters. Read Agent host support before adapting these instructions.

1. Install skills

From the repository root:

./Scripts/install-skills.sh --dry-run   # preview
./Scripts/install-skills.sh
./Scripts/verify-skills.sh
Fact Detail
Default target ${CODEX_HOME:-$HOME/.codex}/skills
What install does Symlinks installable skills from .agents/skills/ into user scope
State file .apple-development-foundation-links under the target (installer-owned only)

Install failure modes

Message / situation What to do
Conflict; leaving untouched: … Something already occupies that skill name. Inspect the path; do not force-overwrite. Rename/remove only if you own it, then re-run install
Existing identical symlink is not installer-owned Destination is correct; leave it. Skills still resolve
Already installed (installer-owned) Success from a prior run
Missing manifest.json / required tools (python3, awk, readlink) Fix the clone and PATH; re-run

--uninstall removes only installer-owned symlinks that still match recorded destinations (including broken links after a moved repo). Full table: Troubleshooting · Scripts.

2. Configure XcodeBuildMCP

First, give an explicitly selected consumer repository its project-local operating contract. Preview before writing:

./Scripts/init-consumer-guidance.sh --target /path/to/consumer --dry-run
./Scripts/init-consumer-guidance.sh --target /path/to/consumer

The initializer copies the installed bootstrap skill’s .agents/skills/codex-bootstrap/assets/consumer-AGENTS.md.template to the consumer root as AGENTS.md. It refuses an existing AGENTS.md and never edits global ~/.codex/AGENTS.md; review and manually merge approved sections when consumer instructions already exist. Customize the template’s project/workspace, scheme, configuration, platforms, deployment versions, simulator/config, repository-native verification commands, and Apple verification policy knobs (XcodeBuildMCP CLI fallback and raw xcodebuild/xcrun/simctl: require-approval by default, or allowed / denied). Copy-paste the same contract from AGENTS.md template when you prefer not to run the script.

  1. Add XcodeBuildMCP to Codex’s MCP server list using current Codex and XcodeBuildMCP documentation.
  2. In the consumer (or monorepo) workspace root, create project-local config when you need more than the default simulator tools:
# <workspace-root>/.xcodebuildmcp/config.yaml
schemaVersion: 1
enabledWorkflows: ["simulator", "ui-automation", "debugging"]
# Optional sessionDefaults (auto-fill MCP + CLI):
#   projectPath or workspacePath, scheme, simulatorId (preferred) or simulatorName
Fact Detail
Default workflows simulator (+ session defaults tools). Add more only when needed
Need macOS / device / UI automation Add macos, device, ui-automation, … — configuration · workflows
After config change Reload or restart the MCP session
MCP vs CLI names MCP: build_run_sim, discover_projs. CLI: xcodebuildmcp simulator build-and-run — full map on XcodeBuildMCP

Interactive setup: xcodebuildmcp setup. List tools: xcodebuildmcp tools. Diagnostics: xcodebuildmcp doctor. Session discipline: XcodeBuildMCP and repo MCP.md.

MCP registration is host-specific. This repository verifies the Codex workflow but does not write host configuration. For any manual compatibility attempt, use the host’s authoritative documentation and do not invent paths or syntax. See Agent host support.

For build, run, and test fallback, follow the deterministic capability ladder: MCP tools; explicitly permitted XcodeBuildMCP CLI; authorized repository-native tooling; otherwise report blocked.

3. Open a session with a structured prompt

Minimal paste:

Goal: Use Apple Development Foundation skills for this Apple-platform task.
Constraints: Work only in the consumer workspace. Follow the authorized XcodeBuildMCP capability ladder. Do not expand AppleDevelopmentFoundation archive/Sources/.
Inputs: Skills at /path/to/AppleDevelopmentFoundation/.agents/skills
Done when: Task implemented, reviews applied if shared/sensitive UI, verification reported.
Verification: session_show_defaults, then MCP build/test; report scheme, simulator, residual risk.

More scenarios: Copy-paste 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 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.
  4. For simulator launch, prefer MCP build_run_sim. Use the matching CLI only when active policy explicitly permits that fallback.
  5. Implement only what the task needs; run review skills before shipping shared UI or sensitive code.
  6. Verify with XcodeBuildMCP (and Maestro when UI regression matters); pin simulatorId, wait for same-project test processes, and keep simulator tests serialized with parallel testing disabled by default.
  7. Report project/workspace, scheme, configuration, exact simulator/device, what ran, and residual risk.

Scenario paths: Task recipes.

5. How you know it worked

Check Pass looks like
Skills Codex can resolve $codex-bootstrap / foundation skills, or its repository path load works
Consumer contract Project-local AGENTS.md exists or approved rules were merged without replacing existing instructions
Verify script ./Scripts/verify-skills.sh exits 0 after install or skill edits
MCP session_show_defaults returns usable project/scheme/simulator (or clear missing fields you then fix)
App work Build/test via MCP succeeds for the consumer target

6. Preview these docs (optional)

npm install
npm run dev
# production check:
npm run build && npm run validate

Requires Node.js ≥ 22.12. App/skill work does not require the docs site.

Next

  1. Task recipes — pick the matching scenario
  2. Session workflow — full loop when the task spans multiple steps
  3. Skill routing — $apple-development-foundation shortlist
  4. Bootstrap a new app — new consumer SwiftUI project
  5. Agent host support — verified vs manual compatibility
  6. Troubleshooting — install / MCP / Maestro blockers

Agent feed (after deploy): site-root llms.txt. Skills source of truth: .agents/skills/manifest.json + each SKILL.md.

Was this page helpful?