app-planner

What this skill does

# 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