axiom-app-composition

# App Composition

## When to Use This Skill

Use this skill when:
- Structuring your @main entry point and root view
- Managing authentication state (login → onboarding → main)
- Switching between app-level states without flicker
- Handling scene lifecycle events (scenePhase)
- Restoring app state after termination
- Deciding when to split into feature modules
- Coordinating between multiple windows (iPad, axiom-visionOS)

## Example Prompts

| What You Might Ask | Why This Skill Helps |
|--------------------|----------------------|
| "How do I switch between login and main screens?" | AppStateController pattern with validated transitions |
| "My app flickers when switching from splash to main" | Flicker prevention with animation coordination |
| "Where should auth state live?" | App-level state machine, not scattered booleans |
| "How do I handle app going to background?" | scenePhase lifecycle patterns |
| "When should I split my app into modules?" | Decision tree based on codebase size and team |
| "How do I restore state after app is killed?" | SceneStorage and state validation patterns |

## Quick Decision Tree

```
What app-level architecture question are you solving?
│
├─ How do I manage app states (loading, auth, main)?
│  └─ Part 1: App-Level State Machines
│     - Enum-based state with validated transitions
│     - AppStateController pattern
│     - Prevents "boolean soup" anti-pattern
│
├─ How do I structure @main and root view switching?
│  └─ Part 2: Root View Switching Patterns
│     - Delegate to AppStateController (no logic in @main)
│     - Flicker prevention with animation
│     - Coordinator integration
│
├─ How do I handle scene lifecycle?
│  └─ Part 3: Scene Lifecycle Integration
│     - scenePhase for session validation
│     - SceneStorage for restoration
│     - Multi-window coordination
│
├─ When should I modularize?
│  └─ Part 4: Feature Module Basics
│     - Decision tree by size/team
│     - Module boundaries and DI
│     - Navigation co