# Genesis WebVoice Setup Plan

**Project:** Voice interface for AIVA conversations and PRD creation  
**Owner:** Kinan  
**Created:** 2025-01-15  
**Status:** Planning → Implementation

---

## Overview

Build a web-based voice interface that enables:
1. Real-time voice conversations with AIVA
2. Voice-to-PRD document creation workflow
3. Integration with Claude Code for monitored execution
4. Future path to autonomous AIVA orchestration

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     Web Voice Interface                      │
│                  (Browser - Any Device)                      │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ├─ Mode 1: Conversation
                       │  └─> Real-time AIVA dialogue
                       │
                       └─ Mode 2: PRD Recording
                          └─> Voice → Structured PRD → Template
                             
┌──────────────────────────────────────────────────────────────┐
│                    AIVA (Elestio Core)                       │
│  - Receives audio/transcript                                 │
│  - Conversation mode: Responds immediately                   │
│  - PRD mode: Structures into Ralph Wiggum template          │
│  - Saves to E:\genesis-system\docs\prds\                    │
└──────────────────────────────────────────────────────────────┘
                             │
                             ↓
┌──────────────────────────────────────────────────────────────┐
│              Genesis File System (Windows)                    │
│  E:\genesis-system\docs\prds\[generated-prd].md             │
└──────────────────────────────────────────────────────────────┘
                             │
                             ↓ (Manual for now)
┌──────────────────────────────────────────────────────────────┐
│           Kinan Opens Claude Code Terminal                   │
│  - Loads completed PRD                                       │
│  - Monitors execution                                        │
│  - Assesses quality                                          │
└──────────────────────────────────────────────────────────────┘
```

---

## Phase 1: WebVoice Interface (This Weekend)

### Components

#### 1. HTML/JavaScript Frontend
**Location:** Can be hosted on Elestio or run locally

**Features:**
- Simple, clean UI
- Two mode buttons: "Talk to AIVA" and "Record PRD"
- Visual feedback (mic active, transcribing, processing)
- Transcript display
- PRD preview before save
- Download/copy completed PRD

**Tech Stack:**
- Pure HTML/CSS/JavaScript (no frameworks needed)
- Web Speech API for browser-based transcription (free)
- WebSocket connection to AIVA
- Or: Groq Whisper API for better privacy/quality

#### 2. Transcription Options

**Option A: Browser Web Speech API** (Fastest to implement)
- Built into Chrome/Edge/Safari
- Free
- Real-time
- Privacy: Local processing
- Quality: 7/10
- Limitation: Requires internet connection

**Option B: Groq Whisper API** (Better quality)
- Privacy-respecting (not OpenAI)
- Free tier: 14,400 minutes/day
- Quality: 9/10
- Latency: ~200ms
- Requires API key

**Recommendation:** Start with Option A, add Option B as upgrade

#### 3. AIVA Connection

**WebSocket Bridge:**
```
Browser → WebSocket → n8n (Elestio) → AIVA → Response → Browser
```

**Or Direct:**
```
Browser → HTTPS Endpoint → AIVA FastAPI → Response → Browser
```

### Conversation Mode Workflow

```
1. User clicks "Talk to AIVA"
2. Mic activates (visual indicator)
3. User speaks: "AIVA, what's Genesis status?"
4. Browser transcribes (real-time)
5. Transcript sent to AIVA via WebSocket
6. AIVA processes, responds: "Genesis status is..."
7. Browser speaks response (TTS)
8. Conversation continues (persistent context)
```

**Context Management:**
- Each session has unique ID
- AIVA maintains conversation history
- User can view transcript
- Can save conversation for later reference

### PRD Recording Mode Workflow

```
1. User clicks "Record PRD"
2. Mic activates (red indicator = recording)
3. User speaks continuously:
   "This is a PRD for voice routing integration.
   
   Problem: Need to connect GHL phone number to AIVA 
   and enable routing to Claude Code sessions.
   
   Requirements:
   - GHL webhook integration
   - AIVA intent detection
   - Claude Code session management
   - Response formatting for voice
   
   Success criteria:
   - Can call Australian number
   - AIVA answers and processes request
   - Complex requests route to Claude Code
   - Responses return via voice within 5 seconds"
   
4. User clicks "Stop Recording"
5. Full transcript sent to AIVA
6. AIVA processes:
   - Structures content
   - Identifies sections
   - Formats into Ralph Wiggum template
   - Fills in metadata
7. Preview shown to user
8. User confirms or requests edits
9. PRD saved to E:\genesis-system\docs\prds\voice-routing-001.md
10. File path shown, ready for Claude Code
```

---

## Phase 2: AIVA PRD Processing (This Weekend)

### Ralph Wiggum Template Integration

**AIVA receives voice transcript and:**

1. **Analyzes content** for PRD structure
2. **Extracts sections:**
   - Problem statement
   - Requirements
   - Success criteria
   - Technical approach
   - Implementation details
   - Dependencies

3. **Populates Ralph Wiggum template:**
   ```markdown
   # PRD: [Extracted Title]
   
   **Status:** Draft
   **Created:** [Timestamp]
   **Owner:** Kinan
   **Priority:** [Detected or asks user]
   
   ## Problem
   [Extracted from voice]
   
   ## Requirements
   [Structured list from voice]
   
   ## Success Criteria
   [Extracted metrics/goals]
   
   ## Technical Approach
   [If mentioned in voice]
   
   ## Implementation Notes
   [Any additional context]
   ```

4. **Generates filename:** `voice-routing-001.md` (auto-incrementing)

5. **Saves to:** `E:\genesis-system\docs\prds\`

6. **Returns to user:**
   - Preview in browser
   - File path for Claude Code
   - Option to download/copy

### AIVA Prompt Enhancement

**Add to AIVA system prompt:**

```
When user says "This is a PRD" or clicks PRD mode:
1. Listen for complete recording without interruption
2. Identify PRD structure from natural speech
3. Extract key sections (problem, requirements, success criteria)
4. Format into Ralph Wiggum template
5. Generate appropriate filename
6. Save to E:\genesis-system\docs\prds\
7. Confirm with user and provide file path
8. Ask if user wants any revisions before finalizing
```

---

## Phase 3: Manual Claude Code Execution (Current State)

**After PRD is created:**

### Kinan's Workflow:

1. **Receive PRD notification** from AIVA:
   - "PRD created: E:\genesis-system\docs\prds\voice-routing-001.md"
   - Preview shown in browser
   - Can download or access directly

2. **Open Claude Code terminal:**
   ```bash
   cd E:\genesis-system
   claude-code
   ```

3. **Load PRD:**
   ```
   "Read and implement docs/prds/voice-routing-001.md"
   ```

4. **Monitor execution:**
   - Watch Claude Code's thought process
   - Review proposed changes
   - Approve/reject steps
   - Assess code quality
   - Provide feedback

5. **Interact as needed:**
   - Ask questions
   - Request modifications
   - Guide implementation
   - Quality control

### Quality Assessment Checklist:

- [ ] Code follows Genesis patterns
- [ ] Tests included
- [ ] Documentation updated
- [ ] HANDOFF.md reflects changes
- [ ] No obvious bugs or issues
- [ ] Meets PRD requirements
- [ ] Maintains existing functionality

---

## Phase 4: Future Autonomous Operation (When Trust Built)

**Evolution path for AIVA autonomy:**

### Level 1: Assisted (Current)
- AIVA creates PRD
- Kinan opens Claude Code
- Kinan monitors fully

### Level 2: Semi-Autonomous (Next Month)
- AIVA creates PRD
- AIVA opens Claude Code session
- AIVA provides initial prompt
- Kinan monitors execution
- Kinan approves final changes

### Level 3: Supervised Autonomous (3 Months)
- AIVA receives voice PRD
- AIVA creates structured PRD
- AIVA opens Claude Code session
- AIVA monitors execution
- AIVA reports completion
- Kinan reviews finished work
- Kinan spot-checks quality

### Level 4: Full Autonomous (6+ Months)
- AIVA receives voice PRD
- AIVA orchestrates full implementation
- AIVA manages multiple Claude Code sessions
- AIVA conducts quality checks
- AIVA deploys to staging
- AIVA notifies Kinan of completion
- Kinan reviews only on request

### Technical Requirements for Autonomy:

**AIVA needs ability to:**
- Spawn Claude Code sessions programmatically
- Monitor session output
- Parse Claude Code responses
- Detect errors/issues
- Request clarification when needed
- Run tests/validation
- Create git commits
- Update HANDOFF.md
- Generate completion reports

**Safety mechanisms:**
- Dry-run mode (shows what would happen)
- Approval gates for destructive operations
- Automatic rollback on errors
- Detailed logging of all actions
- Human override at any point
- Quality score thresholds

---

## Implementation Timeline

### This Weekend (Jan 15-16)

**Saturday:**
- [ ] Build WebVoice HTML interface (2 hours)
- [ ] Set up WebSocket/endpoint to AIVA (1 hour)
- [ ] Test conversation mode (30 min)
- [ ] Test PRD recording mode (30 min)

**Sunday:**
- [ ] Integrate Ralph Wiggum template processor (1 hour)
- [ ] Test end-to-end PRD creation (1 hour)
- [ ] Polish UI/UX (1 hour)
- [ ] Documentation (30 min)

**Deliverable:** Working WebVoice interface for conversations and PRD creation

### Next Week (Jan 17-21)

- [ ] Refine PRD structuring logic
- [ ] Add voice quality options (TTS selection)
- [ ] Create mobile-friendly version
- [ ] Test with actual Genesis PRDs
- [ ] Gather quality metrics

### Following Week (Jan 22-28)

- [ ] Add AIVA → Claude Code connection
- [ ] Test AIVA opening Claude Code sessions
- [ ] Build monitoring dashboard
- [ ] Begin supervised execution tests

---

## Technical Specifications

### WebVoice Interface

**File Structure:**
```
webvoice/
├── index.html          # Main interface
├── css/
│   └── style.css      # Styling
├── js/
│   ├── voice.js       # Voice recording/TTS
│   ├── websocket.js   # AIVA connection
│   └── prd.js         # PRD processing
└── config.js          # API endpoints
```

**API Endpoints:**

```javascript
// Conversation
POST /api/aiva/message
Body: { text: "...", session_id: "...", mode: "conversation" }
Response: { response: "...", audio_url: "..." }

// PRD Creation
POST /api/aiva/prd
Body: { transcript: "...", user_id: "kinan" }
Response: { 
  preview: "...", 
  file_path: "E:\\genesis-system\\docs\\prds\\...",
  status: "success"
}
```

### AIVA Enhancements

**New capabilities needed:**

1. **PRD Processor Module**
   ```python
   class PRDProcessor:
       def analyze_transcript(self, text: str) -> Dict
       def extract_sections(self, text: str) -> Dict
       def format_to_template(self, sections: Dict) -> str
       def generate_filename(self, title: str) -> str
       def save_prd(self, content: str, filename: str) -> str
   ```

2. **Voice Context Manager**
   ```python
   class VoiceContextManager:
       def create_session(self, user_id: str) -> str
       def append_message(self, session_id: str, message: str)
       def get_context(self, session_id: str) -> List
       def end_session(self, session_id: str)
   ```

3. **TTS Integration**
   ```python
   class TTSHandler:
       def generate_speech(self, text: str, voice: str) -> bytes
       # Options: Piper (local), ElevenLabs (paid), Browser (client-side)
   ```

### File System Integration

**Ensure AIVA can write to:**
- `E:\genesis-system\docs\prds\` (PRD files)
- `E:\genesis-system\logs\voice-sessions\` (Conversation logs)
- `E:\genesis-system\VOICE-IN.md` (For Claude Code bridge - future)
- `E:\genesis-system\VOICE-OUT.md` (For Claude Code bridge - future)

**Permissions needed:**
- Read/write access to Genesis system directory
- Can be via network share from Elestio
- Or via file sync (Syncthing, rsync)

---

## Testing Plan

### Conversation Mode Tests

1. **Basic conversation:**
   - "AIVA, what's Genesis status?"
   - Verify response quality
   - Check latency (<2 seconds)

2. **Context retention:**
   - Multi-turn conversation
   - References to previous statements
   - Verify context maintained

3. **Complex requests:**
   - "Check Redis connection and report status"
   - Verify AIVA can execute and report

### PRD Mode Tests

1. **Simple PRD:**
   - Record short, clear PRD
   - Verify template population
   - Check file saved correctly

2. **Complex PRD:**
   - Record detailed PRD with multiple sections
   - Verify proper section extraction
   - Check formatting quality

3. **Ambiguous input:**
   - Record unclear/rambling PRD
   - Verify AIVA asks clarifying questions
   - Check quality of final document

4. **Integration test:**
   - Create PRD via voice
   - Load into Claude Code
   - Verify Claude Code can parse and execute

---

## Success Metrics

### Phase 1 (WebVoice Launch):
- [ ] Can have 5+ turn conversation with AIVA
- [ ] Response latency <2 seconds
- [ ] Voice quality acceptable (7/10 or better)
- [ ] Transcript accuracy >90%

### Phase 2 (PRD Creation):
- [ ] Can create PRD via voice in <5 minutes
- [ ] PRD properly formatted (matches template)
- [ ] File successfully saved to Genesis
- [ ] Claude Code can load and execute PRD

### Phase 3 (Quality):
- [ ] 3 successful PRD → implementation cycles
- [ ] Code quality meets Genesis standards
- [ ] No major bugs in implemented features
- [ ] Kinan comfortable with workflow

### Phase 4 (Future Autonomy):
- [ ] AIVA can open Claude Code sessions
- [ ] AIVA can monitor execution
- [ ] AIVA can detect issues
- [ ] 80%+ of implementations require no intervention

---

## Cost Analysis

### Free Option (Recommended Start):
- Browser Web Speech API: $0
- Piper TTS (local): $0
- Existing Elestio infrastructure: $0 (already paying)
- **Total: $0/month**

### Enhanced Quality Option:
- Groq Whisper API: $0 (free tier sufficient)
- ElevenLabs TTS: ~$5/month (30K chars)
- Existing infrastructure: $0
- **Total: ~$5/month**

### Premium Option:
- Groq Whisper API: $0
- ElevenLabs TTS Pro: ~$20/month (100K chars)
- Existing infrastructure: $0
- **Total: ~$20/month**

**Comparison to VAPI:** $0-20/mo vs ~$50-100/mo for equivalent usage

---

## Risks & Mitigations

### Risk 1: Transcription Quality
**Issue:** Voice not accurately transcribed
**Mitigation:** 
- Start with browser API, upgrade to Groq if needed
- Add manual transcript editing before PRD creation
- Show transcript preview for confirmation

### Risk 2: PRD Structure Quality
**Issue:** AIVA doesn't extract sections well
**Mitigation:**
- Iterative prompt tuning
- User can edit before finalizing
- Templates guide AIVA's extraction
- Fallback to manual structuring

### Risk 3: File System Access
**Issue:** AIVA can't write to Windows filesystem from Elestio
**Mitigation:**
- Network share E:\genesis-system
- Or use file sync (Syncthing)
- Or AIVA writes to local Elestio, you sync
- Test file permissions early

### Risk 4: Voice Fatigue
**Issue:** Dictating long PRDs is tiring
**Mitigation:**
- Support pause/resume
- Can dictate in chunks
- Hybrid: voice for main points, text for details
- Template pre-fills common sections

### Risk 5: Trust Gap
**Issue:** Not ready to let AIVA operate autonomously
**Mitigation:**
- Gradual autonomy increase
- Always provide manual override
- Detailed logging of all actions
- Start with read-only access
- Build trust through observed quality

---

## Next Actions

### Immediate (Today):
1. **Review this plan** - confirm approach
2. **Choose transcription option** (Browser or Groq?)
3. **Confirm file access method** (Network share or sync?)
4. **Set priority** (Conversation mode or PRD mode first?)

### This Weekend:
1. **Build WebVoice interface**
2. **Connect to AIVA**
3. **Test conversation mode**
4. **Test PRD creation**

### Decision Points:

**Q1:** Start with Browser Speech API or Groq Whisper?
**Recommendation:** Browser (faster to test), add Groq later

**Q2:** Where to host WebVoice?
**Recommendation:** Elestio (already running), or local file (simpler)

**Q3:** TTS voice quality priority?
**Recommendation:** Start with browser TTS (free), upgrade to ElevenLabs if needed

**Q4:** Build conversation mode or PRD mode first?
**Recommendation:** PRD mode (higher immediate value)

---

## Conclusion

This plan provides a clear path from voice PRD creation with manual Claude Code execution to eventual autonomous AIVA orchestration. Each phase builds on the previous, allowing you to increase AIVA's autonomy as trust grows through demonstrated quality.

**Key Philosophy:**
- Start simple (free, browser-based)
- Validate quality early
- Upgrade components as needed
- Maintain manual control until trust earned
- Document everything for future autonomy

**Estimated Total Time:**
- Phase 1 (WebVoice): 4-6 hours
- Phase 2 (PRD Processing): 2-3 hours
- Phase 3 (Integration Testing): 2-3 hours
- **Total: ~10 hours for working system**

Ready to start building this weekend.

---

**Questions? Feedback? Ready to begin?**

Let me know which phase you want to tackle first, and any modifications to the plan.
