Claude Code Execution Guide for VoiceAssist V2

This guide provides comprehensive instructions for Claude Code (or other AI assistants) working on the VoiceAssist V2 project. It covers session startup, branching strategy, parallel session safety, quality checks, and phase completion criteria.

For ready-to-use prompts, see CLAUDE_PROMPTS.md

Starting a Claude Code Session
Branch and Commit Strategy
Parallel Session Safety Rules
Quality Checks Before Committing
Phase Completion Criteria
Working with Documentation

Starting a Claude Code Session

Every Claude Code session working on VoiceAssist V2 should begin with these steps to ensure proper context and avoid rework.

1.1 Sync and Setup

cd ~/VoiceAssist
git pull origin main
git status  # Check for any uncommitted changes

If working on an existing branch:

git checkout <branch-name>
git pull origin main  # Merge latest changes
git status

Install/update dependencies if needed:

Backend:

cd services/api-gateway
pip install -r requirements.txt

Frontend:

cd apps/web-app  # or apps/admin-panel
pnpm install

1.2 Read Core Documentation

Before starting ANY work, read these documents IN ORDER:

Required Reading (Always):

docs/overview/IMPLEMENTATION_STATUS.md - Source of truth for component status
docs/START_HERE.md - Project orientation and documentation map
docs/UNIFIED_ARCHITECTURE.md - System architecture and design

Machine-Readable Endpoints (for AI agents):

https://assistdocs.asimo.io/agent/index.json - Documentation metadata
https://assistdocs.asimo.io/agent/docs.json - Full document list with filtering
https://assistdocs.asimo.io/search-index.json - Full-text search index

Phase-Specific Reading: If implementing a phase, read:

docs/phases/PHASE_XX_<NAME>.md - Detailed phase instructions
Any referenced specification documents (WEB_APP_SPECS.md, etc.)

Service-Specific Reading: If working on a specific service:

services/api-gateway/README.md - Canonical backend service guide
apps/web-app/README.md - Web app implementation
apps/admin-panel/README.md - Admin panel implementation

Security/Compliance Work:

docs/SECURITY_COMPLIANCE.md - HIPAA requirements
docs/SEMANTIC_SEARCH_DESIGN.md - PHI detection and routing

1.3 Identify Your Work Scope

Determine and document:

What am I working on?

Which phase (0-15 project phases, or 0-8 web app phases)?
Which service or component?
Which files will I modify?

Dependencies:

Do other services need to be running?
Are there prerequisites from previous phases?
Do I need test data or fixtures?

Success Criteria:

What does "done" look like?
What tests must pass?
What documentation needs updating?

Example Session Checklist:

Session: Phase 5 - Medical Knowledge Base & RAG System

- [x] Read DEVELOPMENT_PHASES_V2.md
- [x] Read PHASE_05_MEDICAL_AI.md
- [x] Read SEMANTIC_SEARCH_DESIGN.md
- [x] Verified Phase 4 is complete (documents indexed)
- [x] Confirmed Qdrant is running
- [ ] Implement RAG service
- [ ] Add PubMed integration
- [ ] Write tests
- [ ] Update documentation

Branch and Commit Strategy

Branch Naming Conventions

Follow these patterns for branch names:

Phase Implementation:

phase-N-short-name

Examples:

phase-1-infrastructure
phase-4-voice-pipeline
phase-11-web-app-ui

Feature Work:

feature/area-description

Examples:

feature/web-chat-layout
feature/admin-kb-upload
feature/voice-vad-integration

Bug Fixes:

fix/issue-description

Examples:

fix/kb-search-timeout
fix/nextcloud-auth-loop
fix/voice-echo-cancellation

Documentation Updates:

docs/description

Examples:

docs/api-contracts
docs/service-catalog
docs/deployment-guide

Infrastructure/Deployment:

infra/description

Examples:

infra/docker-compose-optimization
infra/k8s-manifests
infra/prometheus-dashboards

When to Branch vs Commit to Main

Create a Branch:

Phase implementations (significant work, 4-8 hours)
New features or significant refactoring
Experimental work or architecture changes
Work that requires multiple commits
When multiple parallel sessions are active

Commit Directly to Main:

Documentation-only updates (no code changes)
Trivial fixes (typos, formatting)
Emergency hotfixes (with thorough testing)
When you're the only active session

Branch Workflow:

# Create and switch to new branch
git checkout -b phase-5-medical-ai

# Make changes, commit frequently
git add .
git commit -m "feat(medical-kb): implement RAG service"

# Push to remote
git push -u origin phase-5-medical-ai

# When complete, merge to main
git checkout main
git merge phase-5-medical-ai
git push origin main

# Delete branch (optional)
git branch -d phase-5-medical-ai

Commit Message Format

Use conventional commits format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

feat - New feature
fix - Bug fix
docs - Documentation only
test - Adding or updating tests
refactor - Code refactoring (no functional changes)
perf - Performance improvements
chore - Build process, dependencies, tooling
style - Code style (formatting, semicolons, etc.)

Scopes:

Service names: voice-proxy, medical-kb, auth-service, admin-api
Component names: web-app, admin-panel, docs-site
Phase numbers: phase-1, phase-5, phase-11
Areas: api, database, docker, k8s

Examples:

# Phase implementation
git commit -m "feat(phase-4): implement voice pipeline with VAD and echo cancellation"

# Service feature
git commit -m "feat(medical-kb): add PubMed API integration"

# Bug fix
git commit -m "fix(voice-proxy): resolve WebSocket connection timeout"

# Documentation
git commit -m "docs(phase-2): update database schema documentation"

# Refactoring
git commit -m "refactor(medical-kb): extract RAG logic into separate module"

# Multiple changes (use body)
git commit -m "feat(auth-service): add MFA support

- Implement TOTP generation and validation
- Add MFA setup endpoints
- Update user model with mfa_secret field
- Add tests for MFA flow"

Long Commit Messages (with heredoc):

git commit -m "$(cat <<'EOF'
feat(phase-11): implement web app UI with clinical workflows

Implemented components:
- Quick Consult mode with voice input
- Case Workspace with patient context panel
- Citation display with AMA format
- Safety warnings and disclaimers

Tests:
- Unit tests for all components
- E2E test for quick consult flow

Documentation:
- Updated WEB_APP_SPECS.md
- Added component documentation
EOF
)"

Parallel Session Safety Rules

When multiple Claude Code sessions (or developers) are working simultaneously, follow these rules to avoid conflicts and data loss.

3.1 Service/Phase Ownership

Golden Rule: Only ONE session should modify a given service or phase at a time.

Before starting work:

Check active branches: git branch -a
Look for branch names indicating work in your area
If conflict, coordinate or work on different area

Communication:

Use branch names to signal your work area
If uncertain, create a placeholder branch: git checkout -b phase-5-in-progress

Example:

# Check what's being worked on
git branch -a
# Output:
#   main
#   phase-4-voice-pipeline  <- Someone working on Phase 4
#   feature/admin-kb-upload <- Someone working on admin panel
# * phase-5-medical-ai     <- You are here (safe to work on Phase 5)

3.2 Avoiding Conflicts

High-Risk Shared Files:

docker-compose.yml - Coordinate changes carefully
.env files - Don't commit, document changes
alembic/versions/*.py - Database migrations (coordinate)
Root-level config files (pyproject.toml, package.json)

Safe Practices:

Work in separate services when possible
Each service has its own directory (low conflict)
Frontend and backend can be worked on in parallel
Tests and docs can be updated independently

If you MUST modify shared files:

Pull latest changes first: git pull origin main
Make minimal, focused changes
Commit and push quickly
Notify other sessions

Conflict Resolution:

# If you encounter merge conflicts
git pull origin main
# Fix conflicts in editor
git add <resolved-files>
git commit -m "merge: resolve conflicts from main"

3.3 Testing Boundaries

Isolated Testing:

Test your service in isolation when possible
Use mocks/stubs for dependencies being worked on
Don't rely on services under active development

Docker Compose Testing:

# Test only your service
docker compose up your-service postgres redis qdrant

# Don't start services being modified by others
docker compose up --scale other-service=0

Integration Testing:

Run full integration tests AFTER merging
Not during parallel development
Coordinate timing with other sessions

Quality Checks Before Committing

Run ALL applicable checks before committing code. These checks prevent regressions and maintain code quality.

Backend (Python/FastAPI)

Run from services/api-gateway/ directory:

# Activate virtual environment
source .venv/bin/activate

# 1. Run all tests
pytest tests/ -v

# 2. Run tests with coverage
pytest tests/ --cov=app --cov-report=term-missing

# 3. Format code with black
black app/ tests/

# 4. Check formatting (don't auto-fix)
black app/ tests/ --check

# 5. Lint with flake8
flake8 app/ tests/

# 6. Type checking with mypy
mypy app/

# 7. Security check (optional)
bandit -r app/

Fix Common Issues:

Import errors: isort app/ tests/
Long lines: Refactor or add # noqa comment
Type errors: Add type hints or # type: ignore

All checks must pass:

# Run all checks in sequence
pytest tests/ && black app/ tests/ --check && flake8 app/ && mypy app/

Frontend (Vite/React)

Run from apps/web-app/ or apps/admin-panel/ directory:

# 1. Run all tests
pnpm test

# 2. Run tests in watch mode (during development)
pnpm test:watch

# 3. Type checking
pnpm type-check

# 4. Linting
pnpm lint

# 5. Lint and auto-fix
pnpm lint --fix

# 6. Build check (ensures no build errors)
pnpm build

Fix Common Issues:

ESLint errors: pnpm lint --fix
Type errors: Fix TypeScript types
Build errors: Check imports and dependencies

All checks must pass:

# Run all checks in sequence
pnpm test && pnpm type-check && pnpm lint && pnpm build

Docker Compose Validation

Always validate Docker Compose files:

# 1. Validate syntax
docker compose config

# 2. Validate and view merged config
docker compose config > /tmp/compose-merged.yml
cat /tmp/compose-merged.yml

# 3. Start services and verify
docker compose up -d

# 4. Check all services are healthy
docker compose ps

# 5. Check logs for errors
docker compose logs --tail=50

Expected Output:

NAME                  STATUS    PORTS
postgres              Up        5432/tcp
redis                 Up        6379/tcp
qdrant                Up        6333/tcp
voice-proxy           Up        8001/tcp
medical-kb            Up        8002/tcp

Documentation Quality Checks

Before committing documentation:

Check all links work:

# Use markdown-link-check (install if needed)
npm install -g markdown-link-check
markdown-link-check docs/**/*.md

Verify code examples are valid:

Python: Copy code to temp file, run python -m py_compile
TypeScript: Copy code to temp file, run tsc --noEmit
Bash: Copy to temp file, run bash -n (syntax check)

Check formatting consistency:

Headers use ATX style (# not underlines)
Code blocks specify language
Lists use consistent markers (- not *)
Proper spacing (blank line before/after headers, lists, code blocks)

Spell check (manual or tool):

# Use aspell or similar
aspell check docs/YOUR_FILE.md

Phase Completion Criteria

DO NOT mark a phase as complete until ALL criteria are met. Incomplete phases cause cascading issues in later phases.

Exit Checklist for Every Phase

Verification Commands

Run this command block before marking phase complete:

# 1. All tests pass
cd services/api-gateway && pytest tests/
cd ../../apps/web-app && pnpm test
cd ../admin-panel && pnpm test

# 2. Code quality
cd ../../services/api-gateway && black . --check && flake8 . && mypy app/
cd ../../apps/web-app && pnpm lint && pnpm type-check
cd ../admin-panel && pnpm lint && pnpm type-check

# 3. Docker Compose
cd ..
docker compose config
docker compose up -d
docker compose ps  # All should be "Up"
docker compose logs --tail=100 | grep -i error  # Should be empty or expected

# 4. Health checks
curl http://localhost:8000/health  # API Gateway
curl http://localhost:8001/health  # Voice Proxy
curl http://localhost:8002/health  # Medical KB
# ... (all services)

# 5. Documentation
markdown-link-check docs/**/*.md

If ANY check fails, do NOT mark phase complete.

Phase-Specific Criteria

Phase 0 (Initialization):

All spec documents read and understood
Architecture diagram reviewed
Questions documented

Phase 1 (Infrastructure):

PostgreSQL accessible and accepting connections
Redis accessible and responding to PING
Qdrant accessible and collection created
All databases persist data after restart

Phase 5 (Medical KB & RAG):

Can embed and search documents
RAG pipeline returns relevant results
PubMed API integration works
Citations are properly formatted

Phase 11 (Web App UI):

All workflows (Quick Consult, Case Workspace) functional
Voice input working
Citations display correctly
No console errors in browser

Phase 14 (Production Deployment):

All services running on production server
SSL certificates valid
Monitoring and alerts configured
Backups scheduled and tested
Load testing completed

Working with Documentation

Documentation-First Approach

Before implementing:

Read existing docs to understand design
Note any gaps or ambiguities
Plan implementation based on specs

During implementation:

Update docs as you discover clarifications
Add inline code comments for complex logic
Document any deviations from original spec

After implementation:

Update all affected documentation
Add examples and usage instructions
Document configuration and environment variables

Documentation Standards

File Naming:

Use UPPERCASE for major docs: ARCHITECTURE_V2.md
Use lowercase for code docs: server/README.md
Use underscores for multi-word: WEB_APP_SPECS.md

Structure:

Always include Table of Contents for docs >200 lines
Use consistent heading levels (don't skip levels)
Include "Last Updated" date at bottom

Code Examples:

Always specify language for syntax highlighting
Include imports/context needed to run example
Test that examples actually work

Links:

Use relative links within repo: [link](../docs/FILE.md)
Use absolute URLs for external links
Don't link to specific line numbers (they change)

Troubleshooting Common Issues

"Tests are failing"

Check if tests were failing before your changes: git stash && pytest
If yes, fix tests first, then implement
If no, debug your changes

"Docker Compose won't start"

Check syntax: docker compose config
Check logs: docker compose logs <service>
Check ports: lsof -i :<port> (ensure not in use)
Reset: docker compose down -v && docker compose up -d

"Service not accessible"

Verify service is running: docker compose ps
Check health endpoint: curl http://localhost:<port>/health
Check logs: docker compose logs <service> --tail=100
Verify networking: Services should be on same Docker network

"Merge conflicts"

Pull latest: git pull origin main
Resolve conflicts in editor
Run tests to ensure resolution is correct
Commit: git commit -m "merge: resolve conflicts"

"Phase seems complete but something's not working"

Go through exit checklist systematically
Don't skip manual verification
Check logs for warnings (not just errors)
Test with fresh data/state

Best Practices Summary

Always read docs first - Don't skip docs/START_HERE.md
Run tests frequently - Not just at the end
Commit often - Small, focused commits are better
Document as you go - Don't leave it for later
Test manually - Automated tests don't catch everything
Use meaningful commit messages - Future you will thank you
Coordinate on shared files - Especially docker-compose.yml
Don't mark phases complete prematurely - Verify ALL criteria
Keep branches short-lived - Merge within 1-2 days
When in doubt, ask - Better to clarify than assume

CLAUDE_PROMPTS.md - Ready-to-use prompts for common tasks
Implementation Status - Source of truth for component status
START_HERE.md - Project orientation
UNIFIED_ARCHITECTURE.md - System architecture
Agent Onboarding - AI assistant quick start
Agent API Reference - Machine-readable endpoints

Note: Always reconcile any conflicting statements in other docs against docs/overview/IMPLEMENTATION_STATUS.md and the actual code.

Last Updated: 2025-11-27 Version: V2.1

Claude Execution Guide

Claude Code Execution Guide for VoiceAssist V2

Table of Contents

Starting a Claude Code Session

1.1 Sync and Setup

1.2 Read Core Documentation

1.3 Identify Your Work Scope

Branch and Commit Strategy

Branch Naming Conventions

When to Branch vs Commit to Main

Commit Message Format

Parallel Session Safety Rules

3.1 Service/Phase Ownership

3.2 Avoiding Conflicts

3.3 Testing Boundaries

Quality Checks Before Committing

Backend (Python/FastAPI)

Frontend (Vite/React)

Docker Compose Validation

Documentation Quality Checks

Phase Completion Criteria

Exit Checklist for Every Phase

Verification Commands

Phase-Specific Criteria

Working with Documentation

Documentation-First Approach

Documentation Standards

Troubleshooting Common Issues

"Tests are failing"

"Docker Compose won't start"

"Service not accessible"

"Merge conflicts"

"Phase seems complete but something's not working"

Best Practices Summary

Related Documentation