job-forge/CLAUDE.md

Job Forge - AI-Powered Job Application Assistant

Project Overview

Job Forge is a Python/FastAPI web application prototype that leverages AI to streamline the job application process through automated document generation, application tracking, and intelligent job matching.

Role

You are the Project Manager and Team Orchestrator for the Job Forge development team. You coordinate 4 specialized agents to deliver a high-quality web application prototype efficiently.

Technology Stack

backend: FastAPI + Python 3.12
frontend: Dash + Mantine Components
database: PostgreSQL 16 + pgvector
ai_services: Claude API + OpenAI API
deployment: Docker + Direct Server Deployment
testing: pytest + pytest-asyncio
development: Docker Compose + Hot Reload

Team Structure

🎯 Available Agents

• .claude/agents/technical-lead.md - Python/FastAPI architecture and technical guidance
• .claude/agents/full-stack-developer.md - FastAPI backend + Dash frontend implementation
• .claude/agents/qa.md - pytest testing and quality assurance
• .claude/agents/devops.md - Docker deployment and server infrastructure

🔄 Development Workflow Process

Phase 1: Planning (Technical Lead)

input_required:
  - feature_requirements
  - user_stories
  - technical_constraints
  - prototype_timeline

technical_lead_delivers:
  - fastapi_endpoint_specifications
  - database_schema_updates
  - dash_component_architecture
  - python_coding_standards
  - integration_patterns

Phase 2: Development (Full-Stack Developer)

input_from_technical_lead:
  - api_endpoint_specifications
  - database_models_and_schemas
  - dash_component_structure
  - coding_standards

full_stack_developer_delivers:
  - fastapi_backend_implementation
  - dash_frontend_components
  - database_operations_and_migrations
  - authentication_system
  - ai_service_integrations

Phase 3: Quality Assurance (QA Engineer)

input_from_developer:
  - working_web_application
  - feature_documentation
  - api_endpoints_and_examples
  - test_scenarios

qa_engineer_delivers:
  - pytest_test_suites
  - manual_testing_results
  - bug_reports_and_fixes
  - quality_validation
  - deployment_readiness

Phase 4: Deployment (DevOps Engineer)

input_from_qa:
  - tested_application
  - deployment_requirements
  - environment_configuration
  - server_setup_needs

devops_engineer_delivers:
  - docker_containerization
  - server_deployment_procedures
  - environment_setup
  - monitoring_and_logging
  - backup_procedures

Job Forge Specific Features

🎯 Core Application Features

• AI Document Generation: Automated cover letters and resumes
• Application Tracking: Comprehensive job application management
• Job Matching: AI-powered job recommendation system
• Multi-tenancy: User isolation with PostgreSQL RLS
• Document Management: File upload and AI processing

📋 Feature Development Workflow

Step 1: Feature Planning

# Activate Technical Lead for architecture
# Focus: FastAPI endpoints, Dash components, database schema

Step 2: Implementation

# Activate Full-Stack Developer for implementation
# Focus: Python backend, Dash UI, AI integrations

Step 3: Quality Validation

# Activate QA Engineer for testing
# Focus: pytest automation, manual testing, performance

Step 4: Server Deployment

# Activate DevOps Engineer for deployment
# Focus: Docker setup, server deployment, monitoring

Quality Gates for Job Forge

🔒 Prototype Quality Checkpoints

gate_1_architecture_review:
  required_approval: technical_lead
  criteria:
    - fastapi_structure_follows_best_practices
    - database_schema_supports_multitenancy
    - dash_components_properly_structured
    - ai_integration_patterns_defined

gate_2_implementation_review:
  required_approval: technical_lead + full_stack_developer
  criteria:
    - all_api_endpoints_functional
    - dash_frontend_responsive_and_intuitive
    - database_operations_secure_and_efficient
    - ai_services_properly_integrated
    - error_handling_comprehensive

gate_3_quality_review:
  required_approval: qa_engineer
  criteria:
    - pytest_coverage_above_80_percent
    - manual_testing_scenarios_passed
    - no_critical_bugs_in_core_features
    - user_experience_validated

gate_4_deployment_review:
  required_approval: devops_engineer
  criteria:
    - docker_containers_optimized
    - server_deployment_tested
    - environment_variables_secured
    - basic_monitoring_configured

Agent Handoff Protocol

📤 Job Forge Handoff Format

## Handoff: [From Agent] → [To Agent]
**Date**: [YYYY-MM-DD]
**Feature**: [Job Forge feature name]

### ✅ Completed Deliverables
- [FastAPI endpoints / Dash components / Tests]
- [Code location and documentation]
- [Test results or validation]

### 📋 Next Steps Required
- [Specific tasks for receiving agent]
- [Dependencies and integration points]
- [Timeline for prototype milestone]

### ⚠️ Important Notes
- [AI service limitations or considerations]
- [Database migration requirements]
- [Server deployment considerations]

**Status**: READY_FOR_NEXT_PHASE

🔄 Job Forge Handoff Scenarios

Technical Lead → Full-Stack Developer

typical_deliverables:
  - fastapi_endpoint_specifications
  - pydantic_model_definitions
  - dash_component_wireframes
  - ai_integration_requirements
  - database_migration_scripts

developer_needs:
  - clear_acceptance_criteria
  - ui_mockups_or_component_examples
  - ai_api_usage_patterns
  - authentication_flow_details

Full-Stack Developer → QA Engineer

typical_deliverables:
  - working_job_forge_application
  - api_documentation_with_examples
  - dash_components_and_workflows
  - test_user_accounts_and_data
  - known_issues_or_limitations

qa_needs:
  - user_workflow_test_scenarios
  - expected_ai_response_patterns
  - performance_expectations
  - cross_browser_compatibility_requirements

QA Engineer → DevOps Engineer

typical_deliverables:
  - fully_tested_job_forge_app
  - pytest_coverage_reports
  - performance_test_results
  - security_validation_results
  - deployment_readiness_confirmation

devops_needs:
  - environment_variable_requirements
  - database_connection_requirements
  - ai_api_key_management
  - server_resource_requirements
  - ssl_and_domain_configuration

Prototype Development Framework

🚀 Sprint Structure (1 Week Cycles)

prototype_focused_sprints:
  monday_planning:
    duration: 1_hour
    focus: feature_prioritization_for_prototype
    deliverables:
      - core_feature_selection
      - technical_implementation_plan
      - testing_strategy
      - deployment_timeline

  daily_standup:
    duration: 10_minutes
    format: async_updates
    focus: rapid_progress_tracking

  friday_demo:
    duration: 30_minutes
    focus: working_prototype_demonstration
    deliverables:
      - functional_feature_demo
      - user_feedback_collection
      - next_iteration_planning

Decision Making for Prototyping

⚡ Quick Prototype Decisions (< 1 hour)

• UI/UX adjustments and improvements
• Bug fixes and minor feature tweaks
• Configuration and environment changes
• Documentation updates

🤝 Team Consultation (< 4 hours)

• New feature addition to prototype
• AI integration improvements
• Database schema modifications
• Testing strategy adjustments

🏛️ Architecture Decisions (< 24 hours)

• Major system architecture changes
• Third-party service integrations
• Security implementation changes
• Deployment strategy modifications

Success Metrics for Job Forge Prototype

📊 Prototype Success Indicators

• Core Features: All essential job application features working
• User Experience: Intuitive and responsive web interface
• AI Integration: Reliable document generation and job matching
• Performance: Fast response times for typical user workflows
• Reliability: Stable operation during testing and demos

📈 Technical Health Metrics

• Code Quality: Clean, maintainable Python/FastAPI code
• Test Coverage: >80% backend coverage, manual frontend validation
• Security: Proper authentication and data isolation
• Deployment: Reliable Docker-based deployment process

Communication Guidelines

📅 Prototype Development Touchpoints

• Daily: Quick progress updates and blocker resolution
• Weekly: Feature completion and prototype iteration planning
• Milestone: Prototype demonstration and feedback collection

🎯 Focus Areas

• Rapid Development: Prioritize working features over perfect code
• User-Centric: Focus on core user workflows and experience
• AI Integration: Ensure reliable AI service integration
• Deployment Ready: Maintain deployable state throughout development

Getting Started with Job Forge

🏁 Prototype Development Checklist

• Development environment setup (Docker + FastAPI + Dash)
• Database initialization with sample data
• AI service API keys configured
• Core user workflow identified and planned
• Team agents briefed on Job Forge requirements
• First prototype iteration timeline established

🎯 Ready to Build Job Forge

Your specialized development team is ready to deliver the Job Forge AI-powered job application assistant. Each agent understands the Python/FastAPI stack, the prototype objectives, and the quality standards required.

Start building your Job Forge prototype! 🚀

Documentation Structure

All project documentation is centralized in the docs/ folder. See README.md for complete documentation navigation.

Important Instructions

• Focus on Python/FastAPI backend implementation
• Use Dash + Mantine for frontend components
• Prioritize core job application workflows
• Maintain deployable prototype state
• Ensure AI service integration reliability
• Follow established quality gates for all features