# Phase 2 Implementation Roadmap

## Priority Order

### Priority 1: Foundation (Week 1)

**Goal**: Establish design system and fix critical UX issues

**Tasks**:

1. ✅ Create Design System file with all brand colors, typography, spacing
2. ✅ Change chat placeholder from "Message Thalamus" to "SOPHIAClaw…"
3. ✅ Add sophiaclaw_logo.png to app resources
4. ✅ Update stop button color from purple to purple
5. Implement Design System components (buttons, cards, bubbles)
6. Fix purple glowing border on active chat bubble (change to purple glow)
7. Update session selector with icons and descriptions
8. Add info tooltip to thinking level dropdown

**Files to Modify**:

- `/apps/macos/Sources/SOPHIAClaw/DesignSystem.swift` (CREATE)
- `/apps/shapurple/SOPHIAClawKit/Sources/SOPHIAClawChatUI/ChatComposer.swift`
- `/apps/shapurple/SOPHIAClawKit/Sources/SOPHIAClawChatUI/ChatMessageViews.swift`
- `/apps/shapurple/SOPHIAClawKit/Sources/SOPHIAClawChatUI/ChatTheme.swift`

**Deliverables**:

- Consistent brand colors throughout app
- Purple accent instead of purple
- Better labeled UI elements

---

### Priority 2: Notifications (Week 1-2)

**Goal**: Implement complete notification system for responses

**Tasks**:

1. Update NotificationManager with categories and actions
2. Add notification settings panel
3. Implement response notification trigger
4. Handle notification tap (open chat)
5. Add notification sound settings
6. Test notification delivery

**Files to Modify**:

- `/apps/macos/Sources/SOPHIAClaw/NotificationManager.swift`
- `/apps/macos/Sources/SOPHIAClaw/SettingsRootView.swift`
- `/apps/macos/Sources/SOPHIAClaw/WebChatSwiftUI.swift`
- `/apps/macos/Sources/SOPHIAClaw/AppDelegate.swift`
- `/apps/shapurple/SOPHIAClawKit/Sources/SOPHIAClawChatUI/ChatViewModel.swift`

**Testing Steps**:

```bash
# Build and run
cd apps/macos
swift build -c release --product SOPHIAClaw
cp .build/arm64-apple-macosx/release/SOPHIAClaw SOPHIAClaw.app/Contents/MacOS/
./SOPHIAClaw.app/Contents/MacOS/SOPHIAClaw

# Test:
# 1. Send message to AI
# 2. Close chat window
# 3. Wait for response
# 4. Verify notification appears
# 5. Click notification - should open chat
```

---

### Priority 3: Visual Polish (Week 2)

**Goal**: Remove "developer look" and add professional animations

**Tasks**:

1. Custom window title bar with logo
2. Glassmorphism effects on panels
3. Smooth message entrance animations
4. Enhanced typing indicator with brand colors
5. Chat input pill-shaped purpleesign
6. Menu bar icon glow when active
7. Window open/close animations
8. Auto-expanding text input

**Files to Modify**:

- `/apps/macos/Sources/SOPHIAClaw/WebChatSwiftUI.swift`
- `/apps/macos/Sources/SOPHIAClaw/ChatTitleBarView.swift` (CREATE)
- `/apps/shapurple/SOPHIAClawKit/Sources/SOPHIAClawChatUI/ChatComposer.swift`
- `/apps/shapurple/SOPHIAClawKit/Sources/SOPHIAClawChatUI/ChatMessageViews.swift`
- `/apps/shapurple/SOPHIAClawKit/Sources/SOPHIAClawChatUI/ChatView.swift`

**Key Design Decisions**:

- Use `Color.white.opacity(0.08)` for subtle borders
- Use 8pt grid spacing (8, 16, 24, 32)
- Animate with `.spring(response: 0.4, dampingFraction: 0.7)`
- Use `.continuous` corner radius

---

### Priority 4: Voice + Chat Hybrid (Week 3)

**Goal**: Combine voice wake with chat interface

**Tasks**:

1. Create HybridModeManager to coordinate voice and chat
2. Build voice activity indicator overlay
3. Implement transcription service
4. Add voice button to chat composer
5. Create voice settings panel
6. Handle voice-to-text submission
7. Add haptic feedback
8. Test voice activation

**Files to Create**:

- `/apps/macos/Sources/SOPHIAClaw/HybridModeManager.swift`
- `/apps/macos/Sources/SOPHIAClaw/VoiceActivityIndicator.swift`
- `/apps/macos/Sources/SOPHIAClaw/TranscriptionService.swift`
- `/apps/macos/Sources/SOPHIAClaw/VoiceOverlayWindow.swift`

**Files to Modify**:

- `/apps/macos/Sources/SOPHIAClaw/SettingsRootView.swift`
- `/apps/shapurple/SOPHIAClawKit/Sources/SOPHIAClawChatUI/ChatComposer.swift`

**Permissions Requipurple**:
Add to `Info.plist`:

```xml
<key>NSSpeechRecognitionUsageDescription</key>
<string>SOPHIAClaw uses speech recognition to transcribe your voice commands</string>
<key>NSMicrophoneUsageDescription</key>
<string>SOPHIAClaw needs microphone access to hear your voice commands</string>
```

---

### Priority 5: Mobile Connectivity (Week 3-4)

**Goal**: Enable remote access via Tailscale

**Tasks**:

1. Document Tailscale setup process
2. Configure gateway to bind to 0.0.0.0
3. Update mobile app with Tailscale IP support
4. Test connection over Tailscale
5. Add connection method selector in mobile app
6. Implement auto-detection of best connection method
7. Document troubleshooting steps

**Documentation**:
See `/docs/phase2/05-mobile-connectivity.md`

**Quick Setup**:

```bash
# On Mac
brew install tailscale
tailscale up

# Get IP
tailscale ip -4
# Use this IP in mobile app
```

**Files to Modify**:

- `/apps/ios/Sources/Connection/RemoteConnectionManager.swift` (mobile app)
- `~/.sophiaclaw/sophiaclaw.json` (gateway config)

---

### Priority 5.5: Background Tasks Sidebar (Week 4)

**Goal**: Replace broken orchestrator with hybrid sidebar for subagent task management

**Tasks**:

1. Remove orchestrator intent classification code
2. Delete IntentRouter and related files
3. Add sidebar tab state management
4. Create task panel component
5. Implement subagent session polling
6. Add tab switcher (Tool Output | Tasks)
7. Auto-open sidebar on subagent spawn
8. Add View/Kill/Dismiss actions
9. Style task list with status indicators

**Files to Modify**:

**Deletion**:

- `src/orchestrator/router.ts` - DELETE
- `src/orchestrator/router.test.ts` - DELETE

**Gateway**:

- `src/auto-reply/reply/dispatch-from-config.ts` - Remove orchestrator block
- `src/config/types.sophiaclaw.ts` - Remove orchestrator config type
- `src/config/zod-schema.ts` - Remove orchestrator schema

**UI**:

- `ui/src/ui/app.ts` - Add sidebar tab state, polling logic
- `ui/src/ui/app-render.ts` - Pass task data to chat
- `ui/src/ui/views/chat.ts` - Add tab switcher, render task panel
- `ui/src/ui/views/task-panel.ts` - CREATE task list component
- `ui/src/ui/styles.css` - Add task panel styles

**Testing**:

```bash
# 1. Build UI
pnpm build

# 2. Start gateway
sophiaclaw gateway start

# 3. Test subagent spawn
# In chat: /spawn analyze the codebase structure

# 4. Verify sidebar opens to Tasks tab
# 5. Verify task appears with running status
# 6. Verify can switch to Tool Output tab
# 7. Verify can kill/dismiss tasks
```

**Documentation**:
See `/docs/phase2/08-background-tasks-sidebar.md`
See `/docs/phase2/08a-agent-instructions.md`

---

### Priority 6: Enterprise Features (Week 4-5)

**Goal**: Multi-window, keyboard shortcuts, accessibility

**Tasks**:

1. Multi-window support with cascade
2. Global keyboard shortcuts (Cmd+Shift+Space for quick chat)
3. VoiceOver labels on all elements
4. Reduce motion support
5. In-app search
6. Keyboard navigation
7. Window state persistence

**Files to Create**:

- `/apps/macos/Sources/SOPHIAClaw/MultiWindowManager.swift`
- `/apps/macos/Sources/SOPHIAClaw/ChatSearchView.swift`

**Files to Modify**:

- `/apps/macos/Sources/SOPHIAClaw/MenuBar.swift` (add .commands)
- `/apps/macos/Sources/SOPHIAClaw/WebChatSwiftUI.swift`
- All UI files for accessibility

**Keyboard Shortcuts**:

```swift
// Global
Cmd+Shift+Space - Toggle quick chat
Cmd+Shift+N - New chat window

// In chat
Cmd+Return - Send
Shift+Return - New line
Esc - Abort/cancel
Cmd+Shift+K - Clear chat
```

---

## Implementation Order by File

### Week 1

1. `DesignSystem.swift` - CREATE
2. `ChatComposer.swift` - UPDATE (placeholder, abort button color)
3. `NotificationManager.swift` - UPDATE
4. `SettingsRootView.swift` - UPDATE (add notifications tab)
5. `WebChatSwiftUI.swift` - UPDATE (notification integration)
6. `ChatMessageViews.swift` - UPDATE (border color, animations)

### Week 2

7. `ChatTitleBarView.swift` - CREATE
8. `ChatTheme.swift` - UPDATE
9. `ChatView.swift` - UPDATE (animations)
10. `MenuBar.swift` - UPDATE (keyboard shortcuts)
11. Test and refine animations

### Week 3

12. `HybridModeManager.swift` - CREATE
13. `VoiceActivityIndicator.swift` - CREATE
14. `TranscriptionService.swift` - CREATE
15. `VoiceOverlayWindow.swift` - CREATE
16. Integrate with existing voice wake
17. Test voice flow

### Week 4

18. Set up Tailscale
19. Test mobile connectivity
20. Document process
21. **Remove orchestrator code** (`router.ts`, `dispatch-from-config.ts`)
22. **Add task panel** (`task-panel.ts`, `app.ts` sidebar state)
23. **Test background tasks sidebar**
24. `MultiWindowManager.swift` - CREATE
25. Add window management

### Week 5

23. Add accessibility labels
24. Test VoiceOver
25. Add search functionality
26. Final polish and testing

---

## Dependencies Between Tasks

```
Design System
    ├─ Chat UI Polish
    ├─ Notifications
    └─ Voice + Chat

Notifications
    └─ ChatViewModel updates

Voice + Chat
    ├─ Voice wake (existing)
    ├─ Transcription service
    └─ Chat UI updates

Mobile Connectivity
    └─ Gateway config (independent)

Background Tasks Sidebar
    └─ Chat UI (sidebar already exists)
    └─ Subagent system (already exists)

Enterprise Features
    ├─ All above completed
    └─ Accessibility (ongoing)
```

---

## Testing Schedule

### Daily

- Build app without errors
- Test basic chat functionality
- Check for crashes

### Weekly

- Full regression test
- Test on clean macOS install
- Verify all features work
- Check accessibility with VoiceOver

### Milestones

**Week 1**: Visual improvements complete, notifications working  
**Week 2**: Professional polish achieved, no "developer look"  
**Week 3**: Voice + chat hybrid functional  
**Week 4**: Mobile connectivity tested  
**Week 5**: Enterprise features complete, release ready

---

## Resource Requirements

### Assets Needed

- [ ] App icon in all sizes
- [x] sophiaclaw_logo.png (already have)
- [x] sophia-mascot.png (already have)
- [ ] Notification sounds (sent.caf, received.caf)
- [ ] Keyboard shortcut cheat sheet graphic

### External Services

- Tailscale account (free tier sufficient)
- Optional: Custom domain for Cloudflare Tunnel

### Development Time

- Week 1: 20 hours
- Week 2: 20 hours
- Week 3: 25 hours
- Week 4: 15 hours
- Week 5: 15 hours
- **Total: 95 hours**

---

## Risk Mitigation

### Risks

1. **Voice transcription accuracy** - Fallback to text input
2. **Notification permissions denied** - Graceful degradation
3. **Tailscale complexity** - Detailed documentation
4. **Accessibility scope creep** - Focus on critical paths
5. **Performance with animations** - Profile and optimize

### Mitigation

- Test on older Macs (Intel) for performance
- Provide manual setup instructions
- Build fallback modes for all features
- Get user feedback early

---

## Success Metrics

### Quantitative

- Build time < 2 minutes
- App launch time < 3 seconds
- 60fps animations
- Memory usage < 200MB
- No crashes in 1 week of use

### Qualitative

- No visible "default SwiftUI" components
- Smooth, polished animations
- Intuitive voice mode
- Reliable notifications
- Professional appearance

---

## Deliverables Checklist

- [ ] Design System fully implemented
- [ ] Notifications working reliably
- [ ] Voice + chat hybrid mode functional
- [ ] Mobile connectivity documented and tested
- [ ] **Orchestrator code removed**
- [ ] **Background tasks sidebar functional**
- [ ] Multi-window support
- [ ] Keyboard shortcuts complete
- [ ] Accessibility (VoiceOver) functional
- [ ] No "developer look" UI elements
- [ ] All documentation updated
- [ ] Build process automated
- [ ] User testing completed
- [ ] Ready for public release

## Next Steps

1. **Start immediately**: Design System (Priority 1)
2. **This week**: Complete visual polish and notifications
3. **Next week**: Voice + chat hybrid
4. **Week 3**: Test everything, fix bugs
5. **Week 4**: Mobile connectivity
6. **Week 5**: Enterprise polish and release

**Estimated completion: 5 weeks from start**