Project Context

• Recent commits: !git log --oneline -5 2>/dev/null || echo "no git history"
• Project files: !ls *.xcodeproj 2>/dev/null || ls Package.swift 2>/dev/null || echo "no project file found"

App Development Workflow

End-to-end lifecycle for building Apple apps with this toolkit. Each phase tells you what to do, which skills to load, and where to go next.

Lifecycle Overview

Phase 0: Scaffold → Phase 1: Architecture → Phase 2: Design → Phase 3: Implement → Phase 4: Build → Phase 5: Review → Phase 6: Test

Phase 0 — Scaffold

When: Starting a new app or major feature from scratch.

Load: apple-app-architect:macos-development (read app-planner/ module)

Steps:

1. Define the app's purpose, target users, and core features
2. Use /brainstorm to explore approaches and constraints
3. Use /write-plan to create a detailed implementation plan
4. Identify app archetype (document-based, library+editor, utility, menu-bar, pro tool)
5. Scaffold the project: Use /scaffold-project command (preferred)
   • Loads apple-app-architect:swift-project-scaffold skill automatically
   • Detects XcodeGen (primary) or falls back to XcodeBuildMCP scaffold tools
   • Creates project.yml, app entry point, ContentView, .gitignore
   • Configures Swift 6.2, strict concurrency, correct deployment target
   • Fallback: use scaffold_macos_project / scaffold_ios_project MCP tools directly, or apple-app-builder:xcodebuildmcp-cli skill

Next phase → Load apple-app-architect:macos-development architecture-patterns module for Phase 1.

Phase 1 — Architecture

When: Designing system structure, navigation, state management, data model.

Load: apple-app-architect:macos-development (read architecture-patterns/ module) Agent: macos-architect — consult for architecture decisions

Steps:

1. Choose navigation pattern (NavigationSplitView, TabView, etc.)
2. Design state management (@Observable, SwiftData, actor isolation)
3. Plan module boundaries (Swift Package Manager local packages)
4. Define data model and persistence strategy (apple-app-architect:swift-actor-persistence for lightweight JSON, SwiftData for relational/CloudKit)
5. Map command structure (menus, keyboard shortcuts)

Next phase → Load apple-design-system:macos-app-design for UI design in Phase 2.

Phase 2 — Design

When: Designing the UI layer — HIG compliance, Liquid Glass, layout decisions.

Load: apple-design-system:macos-app-design, apple-design-system:apple-liquid-glass-design

Steps:

1. Review Mac Citizen Checklist from apple-design-system:macos-app-design
2. Identify which surfaces get Liquid Glass treatment
3. Plan information architecture (sidebar structure, toolbar groups)
4. Define accessibility plan (VoiceOver, keyboard nav, Reduce Motion)
5. Produce deliverables: app archetype, IA, command map, state model, a11y plan

Next phase → Load apple-design-system:swiftui-components + apple-design-system:swiftui-ui-patterns for Phase 3. For autonomous UI loop, load apple-app-builder:autonomous-ui-workflow.

Phase 3 — Implement

When: Writing SwiftUI views and business logic.

Load: apple-design-system:swiftui-components, apple-design-system:swiftui-ui-patterns, apple-app-architect:swift-actor-persistence (if feature needs local storage) Agent: ui-developer — autonomous implementation with build verification API References: Load as needed from the research table:

Need	Skill
Glass effects, floating controls	apple-design-system:apple-liquid-glass-design
Icons, SF Symbols	apple-design-system:swiftui-iconography-api
Background materials, shapes	apple-design-system:swiftui-material-api
Text fields, pickers, forms	apple-design-system:swiftui-input-api
Font choices, text styling	apple-design-system:swiftui-typography-api
Colors, gradients, tint	apple-design-system:swiftui-colors-api
Blur, shadow, opacity	apple-design-system:swiftui-effects-api
Sheets, popovers, alerts	apple-design-system:swiftui-presentation-api
Local storage, caching	apple-app-architect:swift-actor-persistence

Steps:

1. Read existing similar views for pattern consistency
2. Apply templates from apple-design-system:swiftui-components/templates/
3. Follow apple-design-system:swiftui-ui-patterns core guidelines for state, APIs, composition
4. Use #Preview blocks for every view
5. Run /implement-component for scaffolding

Next phase → Build and verify in Phase 4.

Phase 4 — Build

When: Compiling, verifying builds, iterating on errors.

Load: apple-app-builder:xcodebuildmcp or apple-app-builder:xcodebuildmcp-cli Also: apple-app-builder:autonomous-ui-workflow covers phases 5-8 (Build → Preview → Validate → Iterate)

Xcode MCP (Primary Interface): When XcodeBuildMCP MCP server is available, it is the primary interface for ALL file operations, builds, and tests. Load the apple-app-builder:xcodebuildmcp skill for:

• File ops: XcodeRead/XcodeUpdate/XcodeWrite (not Read/Edit/Write)
• Build: BuildFix Loop (max 5 iterations with Issue Navigator diagnostics)
• Test: TestFix Loop (with crash detection and CLI fallback)
• Preview: RenderPreview for visual verification

Steps:

1. Build via XcodeBuildMCP tools or CLI (/build)
2. Fix build errors (/fix-build) — read full error, fix, rebuild
3. Preview with RenderPreview to verify visual correctness
4. Validate against project rules (see apple-app-builder:autonomous-ui-workflow Phase 7)
5. Iterate until build is green and preview matches intent

Next phase → When build is green, proceed to Phase 5. Load apple-app-quality:swiftui-view-refactor.

Phase 5 — Review (iterative)

When: Build is green, code needs quality review and refactoring.

Exit criterion: No CRITICAL or MAJOR findings remain. Grade A- or better (0 FAIL sections in code-analyzer output, 0 CRITICAL findings from swift-reviewer).

Load: apple-app-quality:code-analyzer, apple-design-system:swiftui-ui-patterns (review checklist), apple-app-quality:swiftui-view-refactor, apple-app-builder:swift-concurrency (review checklist) Optional deep-dive: apple-app-quality:audit-context-building for security audit or architectural review Agents: swift-reviewer, code-reviewer (dispatched via /review command)

Steps:

1. Run review swarm: /review dispatches swift-reviewer + code-reviewer in parallel
2. Triage findings: Classify each as CRITICAL (fix now), MAJOR (fix now), MINOR (fix later), SUGGESTION (backlog)
3. Fix CRITICAL and MAJOR findings — apply fixes one category at a time (security → concurrency → API → accessibility)
4. Rebuild: /build to verify fixes compile
5. Re-run review swarm — repeat steps 1-4 until exit criterion met
6. Apply optional polish: /refactor-view for view structure, /swift-style for conventions
7. Grade check: 0 FAIL + 0 CRITICAL = A- (proceed). Otherwise loop back to step 2.

Grading scale:

Grade	Criteria	Action
A- or better	0 FAIL, 0 CRITICAL	Proceed to Phase 6
B	0 FAIL, 1-2 CRITICAL	Fix CRITICALs, re-review
C or below	1+ FAIL	Fix all FAILs and CRITICALs, re-review

Next phase → When review grade is A- or better, proceed to Phase 6. Load apple-app-quality:ios-testing.

Phase 6 — Test

When: Code is reviewed, ready for test coverage.

Load: apple-app-quality:ios-testing

Steps:

1. Write unit tests with XCTest or Swift Testing framework
2. Test @Observable models with in-memory ModelContainer
3. Follow Arrange/Act/Assert pattern
4. Target 80%+ coverage for critical paths
5. Run tests via /test or XcodeBuildMCP test_macos/test_sim

Choosing Your Entry Point

Situation	Start At
Brand new app	Phase 0 (Scaffold)
New feature in existing app	Phase 1 or 2
Building a specific view	Phase 3 (load apple-app-builder:autonomous-ui-workflow)
Build is broken	Phase 4
Code review	Phase 5
Adding tests	Phase 6

Related Skills

• apple-app-builder:autonomous-ui-workflow — The inner UI development loop (Spec → Build → Validate). Lives within Phases 2-4.
• apple-app-architect:macos-development — Comprehensive macOS reference modules. Spans Phases 0-1.
• apple-design-system:macos-app-design — macOS HIG and design system. Phase 2.
• apple-design-system:apple-liquid-glass-design — Liquid Glass API reference. Phases 2-3.
• apple-app-architect:swift-actor-persistence — Actor-based JSON persistence with in-memory cache. Phase 3.