AI-Assisted Development Task Organization

Last updated on May 25, 2025

Expo/React/Clerk example using the Atomic design pattern

Core File Structure

project-docs/
├── design-principles.md          # Immutable design philosophy
├── tasks/
│   ├── current.md               # What we're building right now
│   ├── backlog.md              # Next up (prioritized list)
│   ├── completed/              # Finished work (for context/reference)
│   │   ├── auth-system.md      # Completed: User authentication
│   │   ├── button-atoms.md     # Completed: Button component system
│   │   └── navigation-setup.md # Completed: App navigation
│   └── templates/
│       └── task-template.md    # Standard task format
└── tech-stack.md               # Current architecture decisions

Task Format (Simplified for AI Context)

Current Tasks (current.md)

# Current Development Tasks

## 🔥 Active Task: User Authentication System
**Context**: Building login/signup flow with Clerk
**Files to Focus**: 
- `src/atoms/Button/`
- `src/screens/AuthScreen/`
- `src/services/auth.ts`

**What to Build**:
- Login screen with email/password inputs
- Signup screen with validation
- Auth service integration with Clerk
- Error handling for auth failures

**Definition of Done**:
- User can sign up with email/password
- User can log in with existing credentials  
- Auth state persists across app restart
- Error states show appropriate messages
- Works on both iOS and Android

**Tech Requirements**:
- Use Clerk SDK for Expo
- Follow atomic design (atoms → molecules → organisms → screens)
- TypeScript interfaces for all auth-related types
- Platform-specific handling if needed

**Deployment Pipeline**:
- [ ] Build locally ✓
- [ ] Test on simulator
- [ ] Deploy to dev environment  
- [ ] Test on physical device
- [ ] Deploy to production when approved

---

## 🎯 Next Task: Design System - Typography Atoms
**Context**: Create reusable text components
**Files to Focus**:
- `src/atoms/Typography/`
- `src/theme/typography.ts`

**What to Build**:
- Heading components (H1, H2, H3)
- Body text component
- Caption/small text component
- Platform-specific font handling

**Definition of Done**:
- All text sizes follow 18sp base system
- Components work across web/iOS/Android
- Proper TypeScript props
- Documented in Storybook (if using)

**Tech Requirements**:
- 18sp base font size for mobile readability
- Platform-appropriate font families
- Consistent line heights (1.5 for body)
- Accessibility support (font scaling)

Backlog (backlog.md)

# Development Backlog (Priority Order)

## 1. Navigation Setup
**Why**: Users need to move between screens
**Scope**: Expo Router implementation, tab navigation, stack navigation
**Dependencies**: Auth system completion

## 2. Task Management Core
**Why**: Main app functionality  
**Scope**: Create, read, update, delete tasks
**Dependencies**: Navigation, basic UI components

## 3. Dark Mode Toggle
**Why**: User preference, modern app expectation
**Scope**: Theme switching, persistent storage
**Dependencies**: Design system completion

## 4. Offline Support
**Why**: App should work without internet
**Scope**: Local storage, sync when online
**Dependencies**: Core task management

## 5. Push Notifications
**Why**: User engagement and reminders
**Scope**: Expo Notifications setup, scheduling
**Dependencies**: User permissions, task system

Completed Archive (completed/auth-system.md)

# Completed: User Authentication System

**Completed**: Jan 15, 2025
**Development Time**: 3 days
**AI Assistance**: Used for component generation, error handling patterns

## What Was Built
- Complete Clerk integration for Expo
- Login/Signup screens following atomic design
- Auth state management with React Context
- Error boundary for auth failures
- Cross-platform testing completed

## Key Files Created/Modified
- `src/screens/AuthScreen/LoginScreen.tsx`
- `src/screens/AuthScreen/SignupScreen.tsx`
- `src/services/auth.ts`
- `src/hooks/useAuth.ts`
- `src/atoms/Input/Input.tsx`
- `src/atoms/Button/Button.tsx`

## Technical Decisions Made
- Chose Clerk over Firebase Auth (better Expo integration)
- Used React Context instead of Redux (simpler for auth state)
- Implemented platform-specific keyboard handling
- Added biometric authentication support

## Lessons Learned
- Clerk's Expo SDK made integration smoother than expected
- Platform-specific input handling was necessary for good UX
- Error states needed more attention than initially planned

## Deployment History
- ✅ Dev Environment: Jan 13, 2025
- ✅ TestFlight/Internal Testing: Jan 14, 2025  
- ✅ Production: Jan 15, 2025

## Issues Encountered & Solutions
- **Issue**: Keyboard covering input fields on iOS
- **Solution**: Added KeyboardAvoidingView with platform-specific behavior
- **Issue**: Android back button not handled in auth flow
- **Solution**: Custom back handler in auth stack

## Code Quality Metrics
- TypeScript coverage: 100%
- Unit tests: 15 tests passing
- Integration tests: 5 tests passing
- No console errors in production build

AI Development Workflow

1. Context Selection

# Give AI Assistant This Context:
- Current task from current.md
- Relevant completed tasks for reference
- Design principles (always)
- Tech stack decisions
- Specific files/components involved

2. Development Process

**Step 1: Analysis**
AI reviews task requirements and existing codebase

**Step 2: Implementation**  
AI generates code following atomic design + platform requirements

**Step 3: Verification**
Developer reviews generated code against Definition of Done

**Step 4: Testing**
Run locally → simulator → dev environment → device testing

**Step 5: Deployment**
Dev → staging → production (with rollback plan)

**Step 6: Archive**
Move completed task to completed/ with learnings

3. Context Management Strategy

**For Current Work**: 
- Load current.md + design-principles.md + relevant completed tasks

**For New Features**:
- Load backlog.md + design-principles.md + tech-stack.md

**For Bug Fixes**:
- Load relevant completed task + current codebase context

**For Refactoring**:
- Load multiple completed tasks + design principles

Tech Stack Integration (tech-stack.md)

# Current Tech Stack Decisions

## Core Framework
- **Expo SDK 50+**: Cross-platform development
- **React Native**: Mobile-first approach  
- **TypeScript**: Strict mode, full coverage

## Backend & Services
- **Clerk**: Authentication (chosen over Firebase for Expo integration)
- **Convex**: Real-time backend (chosen over Supabase for TypeScript DX)

## State Management
- **React Context**: For global state (auth, theme)
- **Local State**: useState/useReducer for component state
- **No Redux**: Keeping it simple for now

## Navigation
- **Expo Router**: File-based routing
- **Native Stack**: Primary navigation pattern

## Styling
- **StyleSheet.create()**: Performance-first approach
- **Theme tokens**: Centralized design system
- **18sp base font**: Mobile-optimized typography

## Development Environment
- **Development**: Expo Go for quick testing
- **Staging**: EAS Build for internal testing
- **Production**: App Store/Play Store via EAS Submit

## Deployment Pipeline
- **Local**: `expo start` for development
- **Dev Build**: `eas build --profile development`  
- **Staging**: `eas build --profile preview`
- **Production**: `eas build --profile production`

Benefits of This System

Laser-Focused AI Context: Only current work + principles, no noise
Actionable Tasks: Clear "what to build" instead of abstract requirements
Component Architecture: Fits perfectly with atomic design approach
Deployment Integration: Built-in dev → prod pipeline thinking
Learning System: Completed tasks inform future development
Scalable: Works solo or with team, simple or complex projects

The key insight: Each task becomes a focused AI prompt with clear deliverables and verification steps. No project management overhead, just pure development context! 🚀