App Development Workflow

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
   • Uses XcodeGen as the automation path for generating project.yml, the app entry point, ContentView, and .gitignore
   • Configures Swift 6.2, strict concurrency, and the correct deployment target
   • If XcodeGen is unavailable, stop and either ask the user to install it or create the starter project in Xcode manually

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:

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:xcode-mcp Also: apple-app-builder:autonomous-ui-workflow covers phases 5-8 (Build → Preview → Validate → Iterate)

Xcode MCP (Primary Interface): When the official Xcode MCP bridge is available, it is the primary interface for Xcode-aware file operations, builds, previews, and targeted test runs. Load the apple-app-builder:xcode-mcp skill for:

• File ops: XcodeRead/XcodeUpdate/XcodeWrite
• Build: BuildFix Loop with Issue Navigator diagnostics and build logs
• Test: GetTestList, RunSomeTests, and RunAllTests when broader coverage is justified
• Preview: RenderPreview for visual verification

Steps:

1. Build via the official Xcode MCP bridge or the native Xcode 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:

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 the official Xcode MCP test tools (GetTestList, RunSomeTests, RunAllTests)

Choosing Your Entry Point

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.