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). Business-specific screens are implemented inline per AGENTS.md craft and Templates/NewFeature/Feature.md; shared parts only go through the component/design-system skills |
| 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 |
Multi-service LAN / API mesh integration (read-only phase)
| Step | Action |
|---|---|
| Skills | Security/privacy review mindset ($apple-security-privacy-review when touching Keychain/logging); concurrency review if sessions/actors grow; testing verification after clients land |
| Patterns | Multi-service iOS app patterns — phase slice, Keychain refs, transport policy, FeatureState, joins, handoff shape |
| Tools | XcodeBuildMCP test_sim (parallel off); fixtures only—no live secrets |
| Verify | Decode/auth tests; secrets skim; optional inspection screenshots for UI |
| Do not | Disable TLS validation; title-only cross-service matching; write APIs before read path is solid; invent endpoints when a fact-checked agent guide exists |
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 |
| Liquid Glass | Treat the request as system chrome adoption first: native tabs, navigation bars, toolbars, and sheets; keep content opaque; use custom glass only for a navigation-plane control the system cannot express |
| 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.
Liquid orb loading mark (full-surface + inline)
Proven pattern (consumer iOS app). Continuous 3×3 ring + liquid-glass orb (no brand glyph). Harmonics, not keyframe holds. Soft glow must not clip to a hard square.
| Step | Action |
|---|---|
| Template | Templates/LiquidOrbLoader/ — README.md (wiring + anti-box checklist) + drop-in DotMatrixLoader.swift |
| Full-screen | FeatureLoadingView for FeatureState.loading with screen-specific detail; put loader outside ScrollView (tabs, service screens, release sheets) |
| Inline | InlineLoadingRow / DotMatrixLoader.compact / .micro for forms, detail panels, poster tiles |
| Replace | Indeterminate ProgressView() busy chrome only — keep determinate ProgressView(value:) |
| Glow | Oversized canvas (layoutScale ≈ 2.6; micro ≈ 2.0); bake squash into path; no scaleEffect + tight frame; radial mask + transparent gradient stops |
| Micro cost | Economy path (30 Hz, fewer path steps, single blur) when many tiles can load together |
| A11y | Reduce Motion freezes via TimelineView; mark label "Loading"; surface combines title+detail |
| Tools | XcodeBuildMCP build + optional loading inspection screenshot |
| Verify | No rectangular glow box; light/dark; ring/orb clearance; Reduce Motion freeze; loader not collapsed in scroll |
| Do not | Keyboard chrome; private hostnames in detail; expand foundation archive/Sources/ for this drop-in |
Proven in: tab-root lists + forms/details/posters + release sheets. Full notes: Templates/LiquidOrbLoader/README.md.
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