Files

2025-08-02 20:51:59 -04:00

12 KiB

Raw Blame History

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! 🚀

Project Structure and Organization

📁 Clean Project Structure Requirements

MANDATORY: Only necessary files should be stored in the project root folder. All supporting files must be organized into appropriate subdirectories:

job-forge/
├── src/                    # Source code only
├── tests/                  # Test files only
├── docs/                   # All documentation
├── docker/                 # All Docker-related files
├── database/               # Database scripts and migrations
├── .env.example           # Environment template
├── requirements-*.txt     # Python dependencies
├── pytest.ini            # Test configuration
└── README.md              # Main project readme

🔧 Docker Files Organization

All Docker-related files are stored in the docker/ folder:

docker/docker-compose.yml - Main orchestration file
docker/Dockerfile.backend - Backend container definition
docker/Dockerfile.frontend - Frontend container definition

Usage: Run cd docker && docker compose up -d to start the environment.

📚 Documentation Structure Requirements

All project documentation is centralized in the docs/ folder:

docs/lessons-learned/ - MANDATORY: All project issues and solutions
docs/api_specification.md - API documentation
docs/database_design.md - Database schema and design
docs/development/ - Development guides and standards

📝 Lessons Learned Process

MANDATORY: For every issue encountered during development:

Create a new markdown file in docs/lessons-learned/
Use format: ###-issue-name.md (where ### is sequential number)
Include: Issue name, description, error messages, root cause, solution, prevention strategy
Reference the lesson learned in relevant documentation

🏗️ Development Environment Setup

# 1. Clone and navigate to project
git clone <repository>
cd job-forge

# 2. Set up environment variables
cp .env.example .env
# Edit .env with your API keys

# 3. Start development environment
cd docker
docker compose up -d

# 4. Access applications
# Frontend: http://localhost:8501
# Backend: http://localhost:8000
# Database: localhost:5432

Important Instructions

Clean Structure: Only necessary files in project root
Docker Organization: All Docker files in docker/ folder
Lessons Learned: Document all issues in docs/lessons-learned/
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

Project Memories

Save files in an organized manner in the project folder to keep it clear and maintainable

12 KiB Raw Blame History