Workflow: Add a Feature to an Existing App

<required_reading> Read these reference files NOW:

references/app-architecture.md
references/swiftui-patterns.md

Plus relevant refs based on feature type (see Step 2). </required_reading>

## Step 1: Understand the Feature

Ask the user:

What should the feature do?
Where in the app does it belong?
Any specific requirements or constraints?

Step 2: Read Relevant References

Based on feature type, read additional references:

Feature Type	Additional References
Data persistence	references/data-persistence.md
Networking/API	references/networking.md
File handling	references/document-apps.md
Background tasks	references/concurrency-patterns.md
System integration	references/system-apis.md
Menu bar	references/menu-bar-apps.md
Extensions	references/app-extensions.md
UI polish	references/design-system.md, references/macos-polish.md

Step 3: Understand Existing Code

Read the relevant parts of the existing codebase:

App entry point (usually AppName.swift or AppNameApp.swift)
State management (AppState, models)
Existing views related to the feature area

Identify:

How state flows through the app
Existing patterns to follow
Where the new feature fits

Step 4: Plan the Implementation

Before writing code:

Identify new files/types needed
Identify existing files to modify
Plan the data flow
Consider edge cases

Step 5: Implement with TDD

Follow test-driven development:

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

Step 6: Integrate

Wire up new views to navigation
Connect to existing state management
Add menu items/shortcuts if applicable
Handle errors gracefully

Step 7: Build and Test

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

# Run tests
xcodebuild test -project AppName.xcodeproj -scheme AppName

# Launch for manual testing
open ./build/Build/Products/Debug/AppName.app

Step 8: Polish

Add keyboard shortcuts (references/macos-polish.md)
Ensure accessibility
Match existing UI patterns

<integration_patterns> Adding to state:

// In AppState
@Observable
class AppState {
    // Add new property
    var newFeatureData: [NewType] = []

    // Add new methods
    func performNewFeature() { ... }
}

Adding a new view:

struct NewFeatureView: View {
    @Environment(AppState.self) private var appState

    var body: some View {
        // Use existing patterns from app
    }
}

Adding to navigation:

// In existing NavigationSplitView or similar
NavigationLink("New Feature", destination: NewFeatureView())

Adding menu command:

struct AppCommands: Commands {
    var body: some Commands {
        CommandGroup(after: .newItem) {
            Button("New Feature Action") {
                // action
            }
            .keyboardShortcut("N", modifiers: [.command, .shift])
        }
    }
}

</integration_patterns>

<success_criteria> Feature is complete when:

Functionality works as specified
Tests pass
Follows existing code patterns
UI matches app style
Keyboard shortcuts work
No regressions in existing features </success_criteria>

3.3 KiB Raw Blame History