Workflow: Build a New macOS App

<required_reading> Read these reference files NOW before writing any code:

references/project-scaffolding.md
references/cli-workflow.md
references/app-architecture.md
references/swiftui-patterns.md </required_reading>

## Step 1: Clarify Requirements

Ask the user:

What does the app do? (core functionality)
What type of app? (document-based, shoebox/library, menu bar utility, single-window)
Any specific features needed? (persistence, networking, system integration)

Step 2: Choose App Archetype

Based on requirements, select:

Type	When to Use	Reference
Document-based	User creates/saves files	references/document-apps.md
Shoebox/Library	Internal database, no explicit save	references/shoebox-apps.md
Menu bar utility	Background functionality, quick actions	references/menu-bar-apps.md
Single-window	Focused task, simple UI	(use base patterns)

Read the relevant app type reference if not single-window.

Step 3: Scaffold Project

Use XcodeGen (recommended):

# Create project structure
mkdir -p AppName/Sources
cd AppName

# Create project.yml (see references/project-scaffolding.md for template)
# Create Swift files
# Generate xcodeproj
xcodegen generate

Step 4: Implement with TDD

Follow test-driven development:

Write failing test
Run → RED
Implement minimal code
Run → GREEN
Refactor
Repeat

See references/testing-tdd.md for patterns.

Step 5: Build and Verify

# Build
xcodebuild -project AppName.xcodeproj -scheme AppName build 2>&1 | xcsift

# Run
open ./build/Build/Products/Debug/AppName.app

Step 6: Polish

Read references/macos-polish.md for:

Keyboard shortcuts
Menu bar integration
Accessibility
State restoration

<anti_patterns> Avoid:

Massive view models - views ARE the view model in SwiftUI
Fighting SwiftUI - use declarative patterns
Ignoring platform conventions - standard shortcuts, menus, windows
Blocking main thread - async/await for all I/O
Hard-coded paths - use FileManager APIs
Retain cycles - use [weak self] in escaping closures </anti_patterns>

<success_criteria> A well-built macOS app:

Follows macOS conventions (menu bar, shortcuts, window behavior)
Uses SwiftUI for UI with AppKit integration where needed
Manages state with @Observable and environment
Persists data appropriately
Handles errors gracefully
Supports accessibility
Builds and runs from CLI without opening Xcode
Feels native and responsive </success_criteria>

2.6 KiB Raw Blame History