Task recipes
Scenario → skills → tools → verification for common Apple-platform agent tasks.
Short paths for coding agents. Pick the scenario that matches the user request, follow the skill chain, then verify. Deep procedure lives in each skill’s SKILL.md — do not invent behavior from this page alone.
How to use
- Confirm the active workspace (consumer app vs this foundation repo).
- Invoke skills with
$name(or host equivalent). - Follow the XcodeBuildMCP capability ladder; missing tools do not authorize fallback.
- Stop when the recipe’s verification gate passes or a documented stop condition is hit.
Recipes
New iOS/macOS SwiftUI app (bootstrap)
| Step | Action |
|---|---|
| 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, 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.
Ship a feature in an existing app
| Step | Action |
|---|---|
| Skills | $apple-platform-planner only if multi-feature/multi-platform; then authoring skills as needed ($swiftui-component-author, $apple-design-system, $ios-macos-platform-adaptation) |
| Tools | XcodeBuildMCP for build/test |
| Verify | $swift-testing-verification + MCP build/test; reviews if shared UI / async / sensitive paths |
| Do not | Plan-for-planning on one-off screens; skip a11y on shared components |
Author reusable UI (tabs, tokens, components)
| Step | Action |
|---|---|
| Skills | $swiftui-tab-navigation when the app needs app-level peer destinations; $apple-design-system for tokens/appearance; $swiftui-component-author for reusable components on that system; $ios-macos-platform-adaptation only when platforms diverge |
| Tools | XcodeBuildMCP for build/preview targets |
| Verify | MCP build; $apple-accessibility-review on shared UI; $swift-testing-verification when logic or public component APIs change |
| Do not | Use tab skill for page-style TabView content or segmented controls; put branding-specific tokens into foundation skills; land components in this repo’s archive/Sources/ |
Read each skill’s SKILL.md for checklists. Bootstrap chain context: Bootstrap.
Fix a bug
| Step | Action |
|---|---|
| Skills | Targeted skill if the bug domain matches (concurrency, security, UI component); else implement directly with defaults from AGENTS.md |
| Tools | XcodeBuildMCP; $maestro-apple-app-testing if the bug is UI/flow |
| Verify | Smallest failing unit/UI check first; re-run after fix; report residual risk |
| Do not | Broad refactors; claim fixed without a re-run |
Review quality before ship
| Step | Action |
|---|---|
| Skills | $swift-concurrency-review (async/actors) → $apple-security-privacy-review (files/logging/permissions) → $apple-accessibility-review (shared SwiftUI) |
| Tools | Compiler/diagnostics via build when needed |
| Verify | Findings + fixes authorized by user; then verification matrix |
| Do not | Run a11y review on non-UI services; run concurrency review for pure styling |
Details: Reviews and quality.
Unit / focused verification
| Step | Action |
|---|---|
| Skills | $swift-testing-verification after meaningful code exists |
| Tools | XcodeBuildMCP test/build on the right simulator or macOS target |
| Verify | Smallest suite that proves the change; never claim pass without execution |
| Do not | Use for planning-only work |
UI regression / flaky flow
| Step | Action |
|---|---|
| Skills | $maestro-apple-app-testing |
| Tools | XcodeBuildMCP (build/install/sim) + Maestro MCP (inspect) + maestro test (regression) |
| Verify | One exact simulator ID; run only the edited or directly affected flow (full/tagged suite only if user or release/CI asks) |
| Do not | OS=latest; speculative flows when Maestro CLI is missing |
Add a shared SPM module or extract reusable code
| Step | Action |
|---|---|
| Skills | $swift-package-module-author (new module in active workspace) or $reusable-code-extractor (proven app code → consumer shared module) |
| Tools | XcodeBuildMCP / package build as appropriate |
| Verify | Module builds and is importable from the consumer app |
| Do not | Land extracted code in this foundation repo’s archived package |
Author or update a foundation skill
| Step | Action |
|---|---|
| Skills | $codex-skill-maintainer |
| Tools | ./Scripts/verify-skills.sh; ./Scripts/test-install-skills.sh if installer behavior changed |
| Verify | Canonical manifest update + generated catalog check; dry-run install |
| Do not | Put business branding/secrets in skills |
Details: Authoring skills.
Explicit foundation audit (only when requested)
| Step | Action |
|---|---|
| Skills | $apple-development-foundation in audit mode with master-skill.json classifications |
| Tools | Foundation verify scripts only if this repo or its installer is in scope |
| Verify | Report inventory comparison + exact verification outcomes requested |
| Do not | Treat ordinary routing as an audit, install, or full-repo scan |
Details: Skill routing.
App Store marketing screenshots
| Step | Action |
|---|---|
| Skills | $app-store-screenshots (external; not in manifest.json) |
| Tools | Upstream skill tooling |
| Verify | Per upstream skill |
| Do not | Vendor the skill into .agents/skills/ unless maintainers decide to |
Details: External skills.
Session skeleton (every recipe)
1. Orient: consumer vs foundation; read AGENTS.md if in this repo
2. Route: $apple-development-foundation OR direct $skill
3. Implement only in the active workspace required by the task
4. session_show_defaults before first build/run/test
5. Review skills when shared UI / async / sensitive data changed
6. Verify + report scheme, simulator/device, residual risk