Reading Order for New Sessions

IMPORTANT: Before beginning work, read these documents IN ORDER.

🤖 Claude Code Configuration (READ FIRST!)

📁 .claude/ Directory - Essential Claude Code setup and agent resources:

1. .claude/CLAUDE.md - Autonomous Development Mode, Context Engineering, Project Configuration
2. .claude/README.md - Directory structure and quick start guide

🎭 Available Agents & Commands (2025-10-14):

3. .claude/agents/ - 6 custom agents (codebase-analyzer, codebase-locator, pattern-finder, thoughts-analyzer, web-search-researcher, etc.)
4. .claude/commands/ - 24 workflow commands (create_plan, implement_plan, research_codebase, debug, ci_commit, etc.)
5. .claude/agents-reference/ - 84 community agents (backend, frontend, security, DevOps, ML) - Git submodule
6. .claude/commands-reference/ - 42 development tools (security-scan, api-scaffold, db-migrate) - Git submodule

📚 Reference Materials (2025-10-14):

7. archive/coditect-v4/ - V4 Reference (19 FDB data models, 88 ADRs, agent patterns) - Git submodule
   • archive/coditect-v4/docs/reference/database-models/ - Complete V4 data model documentation
8. archive/agents-research-plan-code/ - Agent Research (Multi-llm patterns, human-in-loop) - Git submodule
9. docs/analysis-human-layer/ - 10 analysis documents (architecture, tech stack, llm integration strategies)
10. docs/reference/database-models/ - 19 V4 FDB Models (User, Session, Tenant, Agent, etc.) - Copied from V4 for T2 reference
    • docs/reference/V4-DATABASE-MODELS-analysis.md - Analysis for T2 (priorities, patterns, migration guide)

Why read .claude/ first?

• 🚀 Autonomous Mode: Enables multi-hour coding sessions with state tracking
• 🎯 Context Engineering: Anthropic best practices for efficient token usage
• 🤖 Specialized Agents: Production-ready agents for Rust, TypeScript, FoundationDB, GCP
• 🛠️ Development Tools: Security scanning, API generation, monitoring setup

📐 V5 Design & Architecture

1. 🎨 DEFINITIVE V5 ARCHITECTURE: docs/DEFINITIVE-V5-architecture.md - Complete system design (95% theia + 5% wrapper)
2. 🍎 APPLE-QUALITY DESIGN SYSTEM: docs/apple-quality-design-system.md - Steve Jobs/Jony Ive design principles
3. ✅ FRONTEND BUILD VERIFICATION: docs/v5-frontend-build-verification.md - 100% build completion status
4. 📱 MOBILE-FIRST DESIGN: docs/mobile-first-design-system.md - Touch-friendly patterns (56px targets)

🏗️ Implementation & Deployment

5. 🎯 EXECUTION PLAN: docs/10-execution-plans/corrected-execution-order.md - Step-by-step with dependencies
6. 📋 DEPLOYMENT TRACKER: docs/10-execution-plans/deployment-step-by-step-tracker.md - Live progress
7. 🚀 DEPLOYMENT GUIDE: docs/06-backend/gcp-cloud-build-guide.md - GCP/GKE reference

🔍 Backend & Infrastructure

8. ⚙️ BACKEND SUMMARY: docs/06-backend/backend-summary.md - Rust API deployed to GCP
9. 🗄️ INFRASTRUCTURE MAP: docs/03-infrastructure/infrastructure-map.md - FoundationDB, GKE cluster
10. 🔐 SECURITY PLAN: docs/04-security/security-hardening-plan.md - Security architecture

📚 theia Integration

11. 🔧 THEIA RESEARCH: docs/theia-ai-research-findings.md - theia 1.65 AI capabilities
12. 🎭 THEIA WRAPPER ARCHITECTURE: docs/V5-THEIA-WRAPPER-architecture.md - React-theia bridge pattern

🧪 Deployment & Testing Infrastructure (2025-10-14)

13. ✅ TESTING INFRASTRUCTURE: testing-infrastructure-complete.md - Complete automated testing suite
14. 📋 TESTING SUMMARY: docs/testing-summary.md - Quick reference guide
15. 📖 TESTING GUIDE: docs/testing-guide.md - Complete documentation (558 lines)
16. 🔧 TEST SCRIPTS:
    • scripts/test-deployment.sh - Pre-deployment validation (403 lines)
    • scripts/test-endpoints.sh - Live endpoint testing (122 lines)
    • Makefile - Convenient test commands (73 lines)
17. 🚀 DEPLOYMENT FILES:
    • cloudbuild-combined.yaml - GCP Cloud Build with automated validation
    • dockerfile.local-test - Production Docker image
    • dockerfile.combined - Multi-stage build
    • nginx-combined.conf - NGINX configuration
    • k8s-combined-deployment.yaml - Kubernetes deployment
18. ⚙️ ENVIRONMENT CONFIG:
    • .env.production - CRITICAL: Must have VITE_API_URL=/api/v5
    • package.json - Must have prototype:build script
19. 📊 DEPLOYMENT ISSUES TRACKER: docs/10-execution-plans/api-integration-fixes-complete.md - All 9 issues documented

Why this is critical:

• 🚨 Automated testing catches ALL 9 deployment issues in < 2 minutes, BEFORE wasting 10-20 minutes on Cloud Build
• ⚡ Saves 79% time (80-160 min → 17 min per deployment)
• 💰 Saves $40-80 per incident (no failed builds)
• ✅ Zero failed deployments from config issues

This ensures continuity and prevents duplicate work.

🎯 V5 Implementation Status (2025-10-12)

Current Status: ✅ Ready to Build - Docker Installed, All Prerequisites Verified

Latest Achievements (2025-10-12):

• ✅ Docker Installation: Docker v28.5.1 installed and verified working
• ✅ Architecture Documented: Complete V5+theia architecture explanation with troubleshooting
• ✅ Combined Deployment Architecture: Single-container deployment (V5 + theia + NGINX)
• ✅ Deployment Files Created: 9 files (Dockerfiles, NGINX config, Cloud Build, K8s manifests)
• ✅ Documentation Complete: Architecture diagrams, deployment guides, troubleshooting
• ✅ V5 Frontend Build: Production dist/ folder ready (1.2 MB)

📋 Current Session Documents:

• Docker Build Session - Complete architecture deep dive, build strategy, testing procedures, troubleshooting guide (~27 min build timeline)
• Quick Reference Card - Fast command reference for Docker build and testing
• Checkpoint Status - Current deployment status and next steps

Previous Achievements (2025-10-08):

• ✅ Coditect AI Branding: Custom "Coditect AI Agents" welcome message in theia AI Chat
• ✅ Custom Robot Logo: SVG-based Coditect branding
• ✅ V5 Frontend Wrapper: React 18 + Vite 5 running on port 5173 with 28 complete pages
• ✅ Startup Scripts: Convenience scripts for starting/stopping both services
• ✅ Two-Service Architecture: theia backend (3000) + V5 frontend (5173) working

Critical Path:

1. ✅ Phase 0: Pre-requisites (JWT secret, service accounts) - COMPLETE
2. ✅ Phase 1: Frontend Wrapper (Header/Footer/layout) - COMPLETE (2025-10-08)
3. 🔄 Phase 2: theia Container Build - IN PROGRESS (Docker Testing)
4. 🔲 Phase 3: Auth Backend (JWT + FDB sessions) - Ready to start
5. 🔲 Phase 4: WebSocket Sidecar - Pending
6. 🔲 Phase 5: Pod Auto-Provisioning - Pending
7. 🔲 Phase 6: Full Integration & Deploy - Pending
8. 🔲 Phase 7: Blue-Green Rollout - Pending

Next Steps:

1. Install Docker client in development environment
2. Test dockerfile.local-test locally (~27 minute build)
3. Deploy to Cloud Build after local success
4. Deploy to GKE cluster

Remaining Timeline: ~10-12 days (solo) | 6-8 days (2-person) | 4-6 days (4-person)

Infrastructure Ready (serene-voltage-464305-n2):

• ✅ GKE cluster: codi-poc-e2-cluster (us-central1-a)
• ✅ FoundationDB: 10.128.0.8:4500 (3-node StatefulSet)
• ✅ Domain/SSL: coditect.ai (34.8.51.57, Google-managed cert)
• ✅ Container Registry: gcr.io/serene-voltage-464305-n2
• ✅ CI/CD: Cloud Build pipelines ready

V4 Reference Materials (for patterns only):

• docs/08-v4-reference/ - SDD, TDD, 88 ADRs (~2.2MB)
• docs/v4-agents/ - Agent system (512KB)
• src/v4-*/ - Source code reference (~5.3MB)
• .codi/ - Monitoring infrastructure (543 files)

⚠️ CRITICAL: V4 materials are REFERENCE ONLY. Do NOT copy v4 patterns directly - t2 uses Eclipse theia architecture which already provides most features. Always check if theia has the feature before referencing v4 implementations.

---

Back to: CLAUDE.md | DOCUMENTATION-index.md