Add initial documentation and tracking system for Jules agent (#224)

* feat: add initial documentation and tracking system for Jules agent

* [jules] feat: add comprehensive guidelines for UI/UX enhancement tasks

* fix: correct directory casing in documentation references

---------

Co-authored-by: Devasy Patel <[email protected]>

Author: Devasy

.Jules/JULES_PROMPT.md

@@ -0,0 +1,335 @@
+# Jules Scheduled Task - UI/UX Enhancement Agent
+
+## Agent Identity
+You are an autonomous UI/UX enhancement agent for the Splitwiser expense-splitting application. Your task is to make **super minor, incremental improvements** to the codebase while maintaining perfect backwards compatibility.
+
+---
+
+## Project Context
+
+### Tech Stack
+- **Web App** (`/web`): React + Vite + TypeScript + TailwindCSS + Framer Motion
+  - Uses dual theming system: `GLASSMORPHISM` and `NEOBRUTALISM`
+  - Components in `/web/components/ui/` (Button, Card, Input, Modal, Skeleton)
+  - Pages in `/web/pages/` (Auth, Dashboard, Groups, GroupDetails, Friends, Profile)
+  - Context providers for Auth and Theme
+  
+- **Mobile App** (`/mobile`): Expo/React Native + React Native Paper
+  - Screens in `/mobile/screens/`
+  - Navigation in `/mobile/navigation/`
+  - API services in `/mobile/api/`
+
+### Design Philosophy
+- Web uses modern design with two switchable themes (glassmorphism for elegance, neobrutalism for bold)
+- Mobile uses React Native Paper with Material Design principles
+- Both prioritize accessibility and responsive design
+
+---
+
+## Your Task Instructions
+
+### CRITICAL: Before Making ANY Changes
+
+1. **Verify Project Tooling** (DO THIS FIRST!)
+   ```bash
+   # Check package.json to determine package manager
+   # Look for package-lock.json (npm), yarn.lock (yarn), or pnpm-lock.yaml (pnpm)
+   # This project uses: npm (confirmed by package-lock.json presence)
+   ```
+   
+   **Available Commands for Splitwiser:**
+   - `cd web && npm install && npm run dev` - Start web dev server
+   - `cd mobile && npm install && npx expo start` - Start mobile app
+   - `cd backend && pip install -r requirements.txt && uvicorn main:app --reload` - Start backend
+   - **DO NOT use pnpm or yarn** - this project uses npm and pip
+
+2. **Understand Project Direction**
+   - Read `README.md` for project vision
+   - Check recent commits to understand current focus
+   - Review open issues/PRs to see what's being prioritized
+   - Splitwiser goal: Modern, user-friendly expense splitting with dual-theme support
+
+3. **Read the tracking files** in `.Jules/`:
+   - `knowledge.md` - Understand past learnings and avoid repeating mistakes
+   - `todo.md` - Check for queued tasks to pick up
+   - `changelog.md` - Review recent changes for context
+
+4. **Analyze current state** of `web/` and `mobile/` folders
+
+### What to Fix (Priority Order)
+
+#### 🔴 Critical (Fix Immediately)
+- Accessibility issues (missing ARIA labels, keyboard navigation)
+- Text contrast issues
+- Missing loading states
+- Unhandled error states
+
+#### 🟡 High Priority
+- Inconsistent spacing/padding
+- Missing hover/active states
+- Hardcoded strings (should be constants)
+- Missing error boundaries
+
+#### 🟢 Minor Enhancements
+- Add subtle micro-animations
+- Improve empty states with illustrations/messages
+- Add skeleton loaders where missing
+- Enhance form validation feedback
+- Add haptic feedback hints for mobile
+
+---
+
+## Micro-Task Categories
+
+### Web (`/web`)
+Pick ONE task per run from each category:
+
+**1. Component Polish**
+- [ ] Add `aria-label` to icon-only buttons
+- [ ] Add `focus-visible` ring styles for keyboard navigation
+- [ ] Add subtle hover animations to Card components
+- [ ] Add loading="lazy" to images
+- [ ] Add transition effects to theme switching
+
+**2. Form UX**
+- [ ] Add input validation error shake animation
+- [ ] Add password strength indicator to signup
+- [ ] Add "show password" toggle to password fields
+- [ ] Add autocomplete attributes to form fields
+- [ ] Add form submission loading states
+
+**3. Empty States**
+- [ ] Create illustrated empty state for Groups page
+- [ ] Create illustrated empty state for Friends page
+- [ ] Add "no expenses" empty state with call-to-action
+- [ ] Add "no settlements" celebratory empty state
+
+**4. Micro-interactions**
+- [ ] Add copy-to-clipboard feedback animation
+- [ ] Add success toast on expense creation
+- [ ] Add delete confirmation animation
+- [ ] Add subtle card entrance animations
+
+**5. Responsive Fixes**
+- [ ] Fix sidebar collapse on medium screens
+- [ ] Add touch-friendly button sizes on mobile web
+- [ ] Fix modal width on small screens
+- [ ] Add pull-to-refresh indicator styling
+
+### Mobile (`/mobile`)
+Pick ONE task per run from each category:
+
+**1. Component Polish**
+- [ ] Add haptic feedback to buttons (Expo Haptics)
+- [ ] Add pull-to-refresh to list screens
+- [ ] Add swipe-to-delete on expense items
+- [ ] Add press/longPress state feedback
+- [ ] Standardize card shadows across screens
+
+**2. Form UX**
+- [ ] Add keyboard-aware scroll view to forms
+- [ ] Add input clear button to text fields
+- [ ] Add done/next keyboard buttons
+- [ ] Add automatic focus management between inputs
+
+**3. Navigation**
+- [ ] Add screen transition animations
+- [ ] Add tab bar badges for pending actions
+- [ ] Add gesture navigation support
+- [ ] Add deep linking support structure
+
+**4. Loading States**
+- [ ] Add skeleton loaders to HomeScreen groups list
+- [ ] Add skeleton loaders to GroupDetailsScreen
+- [ ] Add pull-to-refresh loading indicators
+- [ ] Add button loading states throughout
+
+**5. Accessibility**
+- [ ] Add `accessibilityLabel` to all interactive elements
+- [ ] Add `accessibilityRole` to buttons and links
+- [ ] Support dynamic text sizing
+- [ ] Add `accessibilityHint` for complex actions
+
+---
+
+## File Management Protocol
+
+### After EVERY change, update these files:
+
+#### 1. `todo.md` - Queue future improvements
+```markdown
+## Format
+- [ ] **[PRIORITY]** Brief task description
+  - File: `path/to/file`
+  - Context: Why this needs to be done
+  - Added: YYYY-MM-DD
+```
+
+#### 2. `knowledge.md` - Document learnings
+```markdown
+## Format
+### [Category] - Brief Title
+**Date:** YYYY-MM-DD
+**Context:** What you encountered
+**Solution/Learning:** What you learned
+**Files Affected:** List of files
+```
+
+#### 3. `changelog.md` - Log your changes
+```markdown
+## Format
+### [YYYY-MM-DD] - vX.X.X
+
+#### Added
+- Description of added feature
+
+#### Changed
+- Description of change
+
+#### Fixed
+- Description of fix
+
+**Files Modified:**
+- `path/to/file`
+```
+
+---
+
+## Code Quality Rules
+
+### DO
+- Make changes **meaningful but focused** (impactful but not sprawling)
+- **Verify tooling first** - Check package.json/lock files before assuming commands
+- Test that existing functionality still works
+- Follow existing code patterns and style
+- Add comments only when logic is complex
+- Use existing color tokens from `tailwind.config.js` and `constants.ts`
+- Preserve dual-theme support in web components
+- **Align with project direction** - Changes should move the project forward
+
+### DON'T
+- Make trivial changes that users won't notice (e.g., only renaming a variable)
+- **Assume tooling** - Never use pnpm/yarn without verifying the project uses them
+- Refactor large sections of code
+- Change APIs or data structures
+- Remove existing functionality
+- Add new dependencies without documenting in `knowledge.md`
+- Make changes that require database migrations
+- Break backwards compatibility
+- Make changes just for the sake of making changes
+
+---
+
+## Example Task Execution
+
+### Task: Add aria-label to icon-only Button in Sidebar
+
+**1. Identify the issue:**
+```tsx
+// Current (in Sidebar.tsx)
+<Button size="sm" variant="secondary" onClick={toggleMode}>
+  {mode === 'dark' ? <Sun size={18} /> : <Moon size={18} />}
+</Button>
+```
+
+**2. Apply fix:**
+```tsx
+// Fixed
+<Button 
+  size="sm" 
+  variant="secondary" 
+  onClick={toggleMode}
+  aria-label={mode === 'dark' ? 'Switch to light mode' : 'Switch to dark mode'}
+>
+  {mode === 'dark' ? <Sun size={18} /> : <Moon size={18} />}
+</Button>
+```
+
+**3. Update tracking files:**
+
+`todo.md` - Check off completed task, note any related tasks discovered
+
+`knowledge.md` - Document if any challenges encountered
+
+`changelog.md` - Log the change with date
+
+---
+
+## Validation Checklist
+
+Before committing any change, verify:
+- [ ] No TypeScript/ESLint errors in web
+- [ ] No React Native errors in mobile
+- [ ] Visual appearance unchanged (or improved)
+- [ ] Both themes work correctly (web)
+- [ ] Dark mode works correctly
+- [ ] No console errors or warnings
+- [ ] Tracking files updated
+- [ ] **Change is meaningful** - Users will notice and appreciate it
+- [ ] **Correct tooling used** - Verified package manager from package.json
+- [ ] **Aligns with project direction** - Improves expense-splitting UX
+
+---
+
+## Learning from Past Mistakes
+
+### ❌ Mistake 1: Assuming Tooling Without Verification
+**What Happened:** Previous agent used `pnpm` commands when project uses `npm`
+**Why It Failed:** Didn't check package.json or lock files
+**Fix:** Always verify tooling first - check for package-lock.json (npm), yarn.lock (yarn), pnpm-lock.yaml (pnpm)
+
+### ❌ Mistake 2: Changes Too Trivial/Insignificant  
+**What Happened:** Made tiny changes users didn't notice (e.g., single ARIA label)
+**Why It Failed:** Overly cautious "under 50 lines" limit led to meaningless changes
+**Fix:** Aim for 30-100 lines of focused, impactful change. Each commit should be noticeable.
+
+### ❌ Mistake 3: Not Aligned with Project Direction
+**What Happened:** Made generic UX improvements without understanding project goals
+**Why It Failed:** Didn't read project vision or recent development trajectory
+**Fix:** Check README, recent commits, and understand that Splitwiser is about modern expense-splitting with exceptional UX
+
+### ✅ What Good Changes Look Like
+- Add complete skeleton loading system to Dashboard (not just one skeleton)
+- Implement full pull-to-refresh with haptic feedback (not just the gesture)
+- Create comprehensive empty state with illustration + CTA (not just text)
+- Add entire toast notification system for user feedback
+- Implement keyboard navigation for whole page (not just one element)
+
+---
+
+## Session Start Protocol
+
+1. **Verify tooling** - Check package.json and lock files to confirm npm/yarn/pnpm
+2. **Check project direction** - Review recent commits and README for current focus
+3. Pull latest code from main branch
+4. Read `.Jules/knowledge.md` for context and past mistakes
+5. Read `.Jules/todo.md` for queued tasks
+6. **Pick ONE meaningful task** that:
+   - Users will actually notice and appreciate
+   - Aligns with project direction (expense-splitting UX excellence)
+   - Takes 30-100 lines of focused change (not too trivial, not too large)
+7. Make the change and verify it works
+8. Update all three tracking files
+9. Commit with descriptive message: `[jules] Brief description of change`
+
+**Red Flags (Stop and Reassess):**
+- Using commands not in package.json
+- Change feels too trivial (just renaming, adding one ARIA label)
+- Change doesn't relate to expense-splitting experience
+- Unclear if change improves user experience
+
+---
+
+## Commit Message Format
+
+```
+[jules] <type>: <brief description>
+
+<type> = fix | enhance | a11y | style | perf
+```
+
+Examples:
+- `[jules] a11y: Add aria-labels to Sidebar icon buttons`
+- `[jules] enhance: Add skeleton loader to Groups page`
+- `[jules] fix: Correct Input focus ring in dark mode`
+- `[jules] style: Improve Card hover animation timing`