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

# [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

# [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

# [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

# [App Name] - Tech Stack

**Last Updated**: [Date]

## UI Framework

**Choice**: [SwiftUI/UIKit/Hybrid]

### Rationale
[Why this choice for this app]

### Version Support
- **Minimum iOS**: [e.g., iOS 17 for broad reach]
- **Target iOS**: [e.g., iOS 26]
- **Rationale**: [Why these versions]

## Persistence

**Choice**: [Core Data/SwiftData/Realm/UserDefaults/File System]

### Rationale
[Why this persistence layer]

### Data Sync
- **Strategy**: [CloudKit/Firebase/Custom/None]
- **Offline Support**: [Yes/No - approach]

## Networking

**Choice**: [URLSession/Alamofire/Moya/Custom]

### Rationale
[Why this networking approach]

### API Details
- **Type**: REST/GraphQL/None
- **Base URL**: [If applicable]
- **Authentication**: [Method if needed]

## Dependency Management

**Choice**: [Swift Package Manager/CocoaPods/Carthage]

### Rationale
[Why this dependency manager]

## Third-Party Dependencies

| Dependency | Purpose | Version | Justification |
|-----------|---------|---------|---------------|
| [Name] | [What it does] | [Version] | [Why needed] |
| [Name] | [What it does] | [Version] | [Why needed] |

### Dependency Guidelines
- Minimize external dependencies
- Prefer native solutions when possible
- All dependencies must be actively maintained

## Development Tools

- **Linting**: SwiftLint
- **Formatting**: SwiftFormat (optional)
- **Analytics**: [Tool if needed]
- **Crash Reporting**: [Tool if needed]

## Backend Services

**Choice**: [CloudKit/Firebase/Supabase/Custom/None]

### Services Used
- [ ] Authentication
- [ ] Database/Storage
- [ ] Analytics
- [ ] Push Notifications
- [ ] Cloud Functions

### Rationale
[Why this backend choice]

## CI/CD

**Choice**: [Xcode Cloud/GitHub Actions/Bitrise/Other]

### Pipeline
- Automated builds
- Automated testing
- TestFlight deployment

## Alternative Considered

### [Alternative 1]
- **What**: [Alternative tech choice]
- **Pros**: [Benefits]
- **Cons**: [Drawbacks]
- **Why Not Chosen**: [Reason]

## Tech Stack Summary

UI: [SwiftUI] iOS: [15+] Architecture: [MVVM] Persistence: [Core Data] Backend: [CloudKit] Networking: [URLSession] Dependencies: [SPM] CI/CD: [Xcode Cloud]

## Migration Considerations

[If tech stack might change later, note migration paths]

File 5: ui-ux.md

# [App Name] - UI/UX Design

**Last Updated**: [Date]

## Design System

### Color Palette

**Light Mode:**
- Primary: `#XXXXXX` (Purpose)
- Secondary: `#XXXXXX` (Purpose)
- Background: System background
- Text: System label

**Dark Mode:**
- Primary: `#XXXXXX`
- Secondary: `#XXXXXX`
- Background: System background
- Text: System label

### Typography

**Font**: [SF Pro/Custom font]

**Text Styles:**
- Large Title: 34pt, Bold
- Title: 28pt, Regular
- Headline: 17pt, Semibold
- Body: 17pt, Regular
- Caption: 12pt, Regular

**Dynamic Type**: ✅ Supported

### Spacing

**Base Unit**: 8pt

**Scale**:
- XXS: 4pt
- XS: 8pt
- S: 12pt
- M: 16pt
- L: 24pt
- XL: 32pt
- XXL: 48pt

## Navigation

**Primary Pattern**: [Tab Bar/Sidebar/Navigation Stack]

### Rationale
[Why this navigation pattern]

### Tab Bar Structure (if applicable)
1. **Tab 1**: [Name] - [Icon] - [Purpose]
2. **Tab 2**: [Name] - [Icon] - [Purpose]
3. **Tab 3**: [Name] - [Icon] - [Purpose]

## Screens

### Screen 1: [Name]
- **Purpose**: [What users do here]
- **Navigation**: [How users get here]
- **Key Elements**: [Main UI components]
- **States**: Loading, Empty, Error, Success

### Screen 2: [Name]
[Same structure]

## User Flows

### Flow 1: [Primary User Flow]

Launch ↓ Home Screen ↓ Action Button ↓ Detail View ↓ Completion

### Flow 2: [Another Flow]
[Same structure]

## Accessibility

### VoiceOver
- [ ] All interactive elements labeled
- [ ] Meaningful labels (not just "Button")
- [ ] Logical navigation order
- [ ] Tested with VoiceOver

### Dynamic Type
- [ ] All text uses text styles
- [ ] Layout adapts to larger text
- [ ] Tested at largest size

### Color Contrast
- [ ] WCAG AA compliance (4.5:1 for text)
- [ ] Not relying on color alone for information

### Other
- [ ] Reduce Motion support
- [ ] Haptic feedback
- [ ] Clear tap targets (44pt minimum)

## Platform Considerations

### iPhone
- Supported sizes: [All/iPhone 13 and newer]
- Orientation: [Portrait only/Both]

### iPad
- Support: [Yes/No/Future]
- Layout: [Adaptive/Optimized]

### Mac Catalyst
- Support: [Yes/No/Future]

## Design Assets

- **App Icon**: [Status - designed/placeholder]
- **Launch Screen**: [Approach]
- **SF Symbols**: [Symbols used]
- **Custom Icons**: [If any]

## Onboarding

### First Launch
- [ ] Welcome screen
- [ ] Feature highlights
- [ ] Permission requests (with rationale)
- [ ] Optional tutorial

## Empty States

- [Screen] when empty: [Message/visual]
- [Feature] when no data: [Message/visual]

## Error States

- Network error: [Message and UI]
- Data error: [Message and UI]
- Permission denied: [Message and UI]

## Loading States

- Initial load: [Loading indicator type]
- Pull to refresh: [System/Custom]
- Pagination: [Approach]

File 6: data-model.md (if applicable)

# [App Name] - Data Model

**Last Updated**: [Date]

## Entities

### Entity 1: [Name]

**Purpose**: [What this entity represents]

**Attributes**:
- `id`: UUID (unique identifier)
- `attribute1`: String (description)
- `attribute2`: Date (description)
- `attribute3`: Double (description)

**Relationships**:
- `relationshipName`: Relationship to [OtherEntity] (one-to-many/many-to-one)

**Validation**:
- [Validation rule 1]
- [Validation rule 2]

### Entity 2: [Name]
[Same structure]

## Relationships

Entity1 ├── one-to-many → Entity2 └── many-to-one → Entity3

Entity2 └── many-to-many → Entity4

## Data Flow

### Create
1. User creates [entity] via UI
2. ViewModel validates input
3. Repository creates entity in persistence layer
4. UI updates with new entity

### Read
1. ViewModel requests data from repository
2. Repository fetches from persistence layer
3. Data transformed for presentation
4. UI displays data

### Update
1. User modifies [entity]
2. ViewModel validates changes
3. Repository updates persistence layer
4. UI reflects changes

### Delete
1. User confirms deletion
2. ViewModel requests deletion
3. Repository removes from persistence
4. UI updates

## Persistence Strategy

**Technology**: [Core Data/SwiftData]

**Context Management**:
- Main context: UI operations
- Background context: Heavy operations

**Fetch Strategies**:
- Batching: [Yes/No - batch size]
- Faulting: [Approach]
- Prefetching: [Relationships to prefetch]

## Cloud Sync

**Strategy**: [CloudKit/Firebase/None]

**Conflict Resolution**:
[How conflicts are handled]

**Sync Triggers**:
- App launch
- Significant data change
- Manual sync option

## Migration Strategy

**Version 1**: Initial schema

**Future Migrations**:
[Plan for schema changes]

## Sample Data

```swift
// Example entity
let example = Entity1(
    id: UUID(),
    attribute1: "Example",
    attribute2: Date(),
    attribute3: 123.45
)

**File 7: personas.md** (if created)
```markdown
# [App Name] - User Personas

**Last Updated**: [Date]

## Persona 1: [Name]

**Photo/Avatar**: [Optional]

### Demographics
- **Age**: [Age range]
- **Occupation**: [Job/role]
- **Location**: [Where they live]
- **Tech Savviness**: Low/Medium/High

### Background
[2-3 sentences about this person's background and context]

### Goals
- [Goal 1]
- [Goal 2]
- [Goal 3]

### Pain Points
- [Pain point 1]
- [Pain point 2]
- [Pain point 3]

### How [App Name] Helps
[How your app solves their problems]

### User Journey
1. [Discovery - how they find the app]
2. [Onboarding - first experience]
3. [Regular Usage - typical use case]
4. [Value Realization - when they see benefit]

### Quote
> "[A quote that represents this persona's perspective]"

## Persona 2: [Name]
[Same structure]

## Persona Comparison

| Aspect | Persona 1 | Persona 2 |
|--------|-----------|-----------|
| Primary Goal | [Goal] | [Goal] |
| Key Pain Point | [Pain] | [Pain] |
| Usage Frequency | Daily | Weekly |
| Key Feature | [Feature] | [Feature] |

File 8: roadmap.md

# [App Name] - Roadmap

**Last Updated**: [Date]

## Timeline Overview

Planning Development Testing Launch |==============|===============|===========|=====> [Date range] [Date range] [Date range] [Date]

## Milestones

### Milestone 1: Project Setup
**Target**: [Date/Week 1]
- [ ] Create Xcode project
- [ ] Set up git repository
- [ ] Configure CI/CD
- [ ] Create initial project structure
- [ ] Set up dependencies

### Milestone 2: Core Architecture
**Target**: [Date/Week 2]
- [ ] Implement MVVM structure
- [ ] Set up Core Data/persistence
- [ ] Create base ViewModels
- [ ] Set up networking layer

### Milestone 3: MVP Features
**Target**: [Date/Weeks 3-6]
- [ ] Feature 1 implementation
- [ ] Feature 2 implementation
- [ ] Feature 3 implementation
- [ ] Basic UI/UX
- [ ] Integration testing

### Milestone 4: Polish & Testing
**Target**: [Date/Week 7-8]
- [ ] UI polish
- [ ] Accessibility implementation
- [ ] Performance optimization
- [ ] Bug fixes
- [ ] User testing

### Milestone 5: Launch Prep
**Target**: [Date/Week 9]
- [ ] App Store assets
- [ ] Privacy policy
- [ ] App Store submission
- [ ] Marketing materials
- [ ] Support documentation

### Milestone 6: v1.0 Launch
**Target**: [Date]
- [ ] Submit to App Store
- [ ] App Review
- [ ] Public release
- [ ] Monitor analytics & crashes
- [ ] Gather user feedback

## Version Planning

### v1.0 - MVP (Launch)
- Core features only
- Stable and polished
- **Target**: [Date]

### v1.1 - Quick Improvements
- User feedback incorporated
- Quick wins
- Performance improvements
- **Target**: [Date - 1 month after launch]

### v2.0 - Major Update
- [Major feature 1]
- [Major feature 2]
- Significant improvements
- **Target**: [Date - 3-6 months after launch]

## Feature Release Schedule

| Version | Features | Target Date |
|---------|----------|-------------|
| v1.0 | [Feature 1, 2, 3] | [Date] |
| v1.1 | [Feature 4, improvements] | [Date] |
| v1.2 | [Feature 5, 6] | [Date] |
| v2.0 | [Major features] | [Date] |

## Dependencies & Blockers

### Current Blockers
- [Blocker 1 - impact and mitigation]
- [Blocker 2 - impact and mitigation]

### External Dependencies
- [Dependency 1 - impact on timeline]
- [Dependency 2 - impact on timeline]

## Risks

| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| [Risk 1] | High/Med/Low | High/Med/Low | [Strategy] |
| [Risk 2] | High/Med/Low | High/Med/Low | [Strategy] |

## Resource Allocation

- **Development**: [X hours/weeks]
- **Design**: [X hours/weeks]
- **Testing**: [X hours/weeks]
- **Marketing**: [X hours/weeks]

## Success Metrics

### Launch Metrics (v1.0)
- Downloads: [Target]
- Active users: [Target]
- Crash-free rate: >99%
- App Store rating: >4.0

### 3-Month Metrics
- Downloads: [Target]
- Daily active users: [Target]
- Retention: [Target]%
- [Custom metric]: [Target]

## Notes

[Any additional timeline notes, assumptions, or considerations]

5. Provide Recommendations

After planning, provide tailored recommendations:

Recommendations Format

## 📋 Planning Recommendations