Initial commit

skills/expertise/macos-apps/workflows/build-new-app.md

@@ -0,0 +1,98 @@
+# Workflow: Build a New macOS App
+
+<required_reading>
+**Read these reference files NOW before writing any code:**
+1. references/project-scaffolding.md
+2. references/cli-workflow.md
+3. references/app-architecture.md
+4. references/swiftui-patterns.md
+</required_reading>
+
+<process>
+## 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):
+
+```bash
+# 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:
+1. Write failing test
+2. Run → RED
+3. Implement minimal code
+4. Run → GREEN
+5. Refactor
+6. Repeat
+
+See references/testing-tdd.md for patterns.
+
+## Step 5: Build and Verify
+
+```bash
+# 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
+</process>
+
+<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>