app-planner

# App Planner Skill Comprehensive guide for planning iOS/Swift applications and analyzing existing apps, covering product, technical, UI/UX, and distribution considerations. ## When This Skill Activates Use this skill when the user: **For New Apps:** - Wants to plan a new iOS/Swift app from scratch - Asks about app planning, architecture planning, or project setup - Needs help defining features, requirements, or technical stack - Wants to create a comprehensive app plan or design document - Asks "what should I consider when building a new app?" **For Existing Apps:** - Wants to analyze or audit their current iOS app - Asks to "run through my existing app" - Needs architecture evaluation or recommendations - Wants tech stack assessment - Planning major refactoring or improvements - Evaluating app health and identifying gaps ## Planning Process ### 1. Understand Project Context First, determine if this is a **new app** or **existing app**, then gather context: **App Status:** - New app (planning from scratch) - Existing app (analyze/improve) **For NEW Apps - gather:** - **Project Type**: Personal, client, startup, learning - **Current Stage**: Just an idea, have requirements, have designs, technical only - **Scope**: Full planning, feature planning, architecture only, tech stack only **For EXISTING Apps - gather:** - **Project Type**: Personal, client, startup, enterprise - **App Age**: How long in development/production - **Codebase Size**: Small (<10 screens), medium (10-30), large (30+) - **Current Issues**: Performance, maintainability, feature additions, technical debt - **Analysis Scope**: Full audit, architecture review, tech stack evaluation, specific area - **Existing Tech Stack**: SwiftUI/UIKit, architecture pattern, persistence layer - **Pain Points**: What's not working well, what needs improvement **Then proceed to appropriate workflow:** - **New App** → Continue to "Planning Phases for New Apps" (Section 3) - **Existing App** → Jump to "Analysis Process for Existing Apps" (Section 6) ### 2. Load Reference Materials Before detailed planning, familiarize yourself with these references in `.claude/skills/app-planner/`: - **planning-checklist.md** - Comprehensive planning checklist covering all phases - **architecture-guide.md** - Architecture patterns, decisions, and trade-offs - **tech-stack-options.md** - Technology choices for different requirements ### 3. Planning Phases for New Apps **Note**: For existing apps, skip to Section 6 "Analysis Process for Existing Apps" Guide the user through these planning phases based on their scope: #### Phase 1: Product Planning **Goals:** - Define what the app does and who it's for - Identify core features and prioritization - Understand user needs and workflows **Activities:** 1. **Define App Purpose** - What problem does it solve? - What's the core value proposition? - What makes it different? 2. **Identify Target Users** - Who will use this app? - What are their goals and pain points? - Create 1-2 user personas if helpful 3. **Feature Definition** - List all potential features - Categorize: MVP (must-have), v2 (nice-to-have), future - Prioritize based on value and complexity 4. **User Journeys** - Map key user workflows - Identify main user paths through the app - Note critical touchpoints #### Phase 2: Technical Planning **Goals:** - Choose appropriate architecture and patterns - Design data models - Select technology stack - Plan project structure **Activities:** 1. **Architecture Selection** - Review architecture-guide.md for options (MVVM, TCA, etc.) - Consider project size, team experience, requirements - Ask user about preferences and constraints - Recommend architecture with rationale 2. **Data Modeling** - Identify main entities and relationships - Define data flow (where data comes from, where it goes) - Choose persistence layer: - Core Data (complex data, relationships, offline-first) - SwiftData (iOS 17+, modern alternative) - UserDefaults (simple settings only) - Realm (alternative to Core Data) - Custom backend + caching 3. **Tech Stack Decisions** - Review tech-stack-options.md for guidance - **UI Framework**: SwiftUI, UIKit, or hybrid - **Minimum iOS version**: Based on features needed - **Networking**: URLSession, Alamofire, or custom - **Dependencies**: SPM, CocoaPods, or manual - **Third-party libraries**: Based on requirements - Ask about user preferences and constraints 4. **Project Structure** - Folder organization (features, layers, modules) - Modularization strategy (monolith vs multi-module) - Code organization patterns #### Phase 3: UI/UX Planning **Goals:** - Plan user interface and experience - Ensure HIG compliance - Design navigation and flows **Activities:** 1. **Design System** - Color palette (consider dark mode) - Typography (SF Pro, custom fonts) - Spacing system (8pt grid recommended) - Component library planning 2. **Navigation Pattern** - Tab bar (2-5 main sections) - Sidebar (iPad, complex hierarchies) - Navigation stack (linear flows) - Sheet/modal presentations - Recommend based on app structure 3. **Screen Planning** - List all main screens - Create simple wireframes or descriptions - Define screen hierarchy - Plan empty states, loading states, error states 4. **Accessibility First** - Dynamic Type support - VoiceOver compatibility - Color contrast requirements - Accessibility features priority 5. **Onboarding & UX Flows** - First-time user experience - Key user flows - Error handling UX - Feedback mechanisms #### Phase 4: Non-Functional Requirements **Goals:** - Define performance, security, testing requirements - Plan for scalability and maintainability **Activities:** 1. **Performance Targets** - Target device range (iPhone only, iPad support, Mac Catalyst) - Performance benchmarks - Memory constraints - Battery usage considerations 2. **Security & Privacy** - Authentication needs (if any) - Data encryption requirements - Privacy policy requirements - Secure storage for sensitive data - App Transport Security compliance 3. **Testing Strategy** - Unit testing approach and coverage goals - UI testing requirements - Beta testing plan - QA process 4. **Monitoring & Analytics** - Analytics needs (user behavior tracking) - Crash reporting (essential for production apps) - Performance monitoring - User feedback mechanism #### Phase 5: Distribution & Business **Goals:** - Plan for App Store distribution - Define monetization (if applicable) - Set timeline and milestones **Activities:** 1. **App Store Planning** - App name availability check - Bundle identifier decision - Screenshots/preview planning - App description and keywords 2. **Monetization** (if applicable) - Free, paid, freemium, subscription - In-app purchases planning - Ad integration strategy 3. **Localization** - Initial language(s) - Internationalization strategy - Future localization plans 4. **Timeline & Milestones** - MVP timeline estimate - Feature milestones - Release schedule - Version planning (1.0, 1.1, 2.0, etc.) ### 4. Create Planning Documentation Files **IMPORTANT**: After completing planning phases, create actual documentation files that the user can keep, update, and version control. #### Ask User About Documentation Location Before creating files, ask where to put documentation: - `docs/planning/` (recommended for most projects) - `planning/` (root-level planning folder) - `.claude/planning/` (keep with Claude Code files) - Custom location #### Documentation Files to Create For comprehensive planning, create these files: **1. docs/planning/overview.md** - Executive summary and key decisions **2. docs/planning/features.md** - Feature list, priorities, and roadmap **3. docs/planning/architecture.md** - Architecture pattern and rationale **4. docs/planning/tech-stack.md** - Technology choices and justification **5. docs/planning/ui-ux.md** - Design system, navigation, screens **6. docs/planning/data-model.md** - Data entities and relationships (if applicable) **7. docs/planning/personas.md** - User personas (if created) **8. docs/planning/roadmap.md** - Timeline and milestones **For focused planning** (architecture only, tech stack only), create only relevant files. #### Templates for Each Documentation File **File 1: overview.md** ```markdown # [App Name] - Overview **Last Updated**: [Date] ## Quick Summary - **Purpose**: [One sentence - what problem does this solve?] - **Target Users**: [Primary audience] - **Platform**: iOS [version]+ - **Project Type**: [Personal/Client/Startup/Enterprise] - **Status**: [Planning/In Development/Production] ## Vision [2-3 sentences describing the app's vision and core value proposition] ## Key Decisions ### Architecture - **Pattern**: [MVVM/TCA/MVC/etc.] - **Rationale**: [Why this choice] ### Tech Stack - **UI**: [SwiftUI/UIKit/Hybrid] - **Min iOS**: [Version] - **Persistence**: [Core Data/SwiftData/etc.] - **Backend**: [CloudKit/Firebase/Custom/None] ### Timeline - **MVP**: [Date/timeframe] - **v1.0**: [Target launch] ## Key Risks & Mitigation 1. [Risk 1] - [Mitigation strategy] 2. [Risk 2] - [Mitigation strategy] ## Success Metrics - [Metric 1] - [Metric 2] - [Metric 3] ## Related Documents - [features.md](./features.md) - Feature list and roadmap - [architecture.md](./architecture.md) - Architecture details - [tech-stack.md](./tech-stack.md) - Technology choices - [ui-ux.md](./ui-ux.md) - Design and UX ``` **File 2: features.md** ```markdown # [App Name] - Features **Last Updated**: [Date] ## MVP Features (v1.0) ### Feature 1: [Name] - **Priority**: High/Medium/Low - **Complexity**: Low/Medium/High - **Description**: [What it does] - **User Value**: [Why users need this] - **Dependencies**: [Other features needed first] - **Status**: [ ] Not Started / [ ] In Progress / [x] Complete ### Feature 2: [Name] [Same structure] ## Post-MVP Features (v1.1+) ### Feature 3: [Name] - **Target Version**: v1.1 / v2.0 - **Priority**: High/Medium/Low - **Description**: [What it does] - **Why Later**: [Rationale for not including in MVP] ## Future Considerations - [Feature idea 1] - [Feature idea 2] ## Feature Dependencies ``` Feature A ├── Feature B (depends on A) └── Feature C (depends on A) ``` ## Feature Estimates | Feature | Complexity | Effort | Priority | |---------|-----------|--------|----------| | Feature 1 | Medium | 2 weeks | High | | Feature 2 | Low | 3 days | High | | Feature 3 | High | 4 weeks | Medium | ``` **File 3: architecture.md** ```markdown # [App Name] - Architecture **Last Updated**: [Date] ## Architecture Pattern **Chosen Pattern**: [MVVM/TCA/MVC/VIPER] ### Rationale [Why this pattern was chosen for this specific app] ### Alternatives Considered - **[Pattern 1]**: [Why not chosen] - **[Pattern 2]**: [Why not chosen] ## Project Structure ``` AppName/ ├── App/ │ ├── AppName.swift │ └── Configuration/ ├── Features/ │ ├── FeatureA/ │ │ ├── Views/ │ │ ├── ViewModels/ │ │ └── Models/ │ └── FeatureB/ ├── Shared/ │ ├── Components/ │ ├── Extensions/ │ └── Utilities/ ├── Services/ │ ├── DataService/ │ └── NetworkService/ └── Resources/ ├── Assets.xcassets └── Localizable.strings ``` ## Layer Responsibilities ### Presentation Layer (Views) - SwiftUI views or UIKit view controllers - UI presentation only - Binds to ViewModels - No business logic ### Business Logic Layer (ViewModels) - Presentation logic - State management - Coordinates between View and Data layers - Testable without UI ### Data Layer (Models & Services) - Domain models - Data access (repositories) - API communication - Persistence management ## Data Flow ``` User Action ↓ View ↓ ViewModel (handles action) ↓ Service/Repository ↓ Model (data) ↓ ViewModel (transforms for presentation) ↓ View (updates UI) ``` ## Key Architectural Decisions ### 1. [Decision Name] - **Decision**: [What was decided] - **Context**: [Why it mattered] - **Rationale**: [Why this choice] - **Consequences**: [Trade-offs] ### 2. [Decision Name] [Same structure] ## Testing Strategy ### Unit Tests - ViewModels (business logic) - Services and repositories - Utilities and extensions - **Coverage Goal**: 70%+ ### UI Tests - Critical user flows - Key navigation paths ## Future Considerations - [Potential architecture evolution] - [Migration strategy if needed] ``` **File 4: tech-stack.md** ```markdown # [App Name] - Tech Stack