Bewerbungszauberer/openspec/project.md

# Project Context

## Purpose

I want to develop a framework that helps to write job applications. It should work similar to how OpenSpec works. Based on the on information about the job, a user provides, the framework will generate a CV, emails or a cover letter.

## Workflow

1 CHOOSE TEMPLATE LEVEL

- Quick: Email application, existing CV
- Standard: Your planned workflow  
- Premium: + Research + CV customization

2 RESEARCH & CONTEXT

- Research job description + company
- Extract keywords/skills
- Analyze culture fit

3 PROPOSAL (= YOUR THOUGHTS)

- Why this position? (authentic!)
- What do you bring? (specific)
- How do you fit the company?
- Tone of Voice: formal/casual?

4 SPECIFICATION

- Define CV adjustments (which projects to emphasize?)
- Cover letter structure
- Format requirements (PDF/DOCX/Online)
- Key messages per paragraph

5 GENERATION

- Adapt CV
- Write cover letter
- Formulate subject line
- Write email body

6 QUALITY CHECK

- Fact check (company names, contact persons)
- Consistency (CV ↔ cover letter)
- Tone check (too stiff? too casual?)
- ATS optimization (if relevant)

7 FINALIZE

- Generate PDFs
- File names according to schema
- Send/Upload

8 TRACK & ARCHIVE

- Sent date, contact person
- Expected response deadline
- Follow-up reminder
- In case of rejection: Document learnings

## Tech Stack

- Claude Code as AI Agent.
- Markdown files to manage the specification 
- Python for scripting.

## Project Conventions

### Code Style
- **Python Version**: 3.10+ (for modern type hints and match statements)
- **Formatting**: Use `black` for code formatting (88 character line length)
- **Linting**: Use `ruff` for fast linting and import sorting
- **Type Hints**: Mandatory for all function signatures; use `mypy` for static type checking
- **Naming Conventions**:
  - Functions/variables: `snake_case`
  - Classes: `PascalCase`
  - Constants: `UPPER_SNAKE_CASE`
  - Private methods: `_leading_underscore`
- **Docstrings**: Google-style docstrings for all public functions and classes
- **Import Organization**: Standard library, third-party, local (separated by blank lines)

### Architecture Patterns
- **Modular Design**: Separate modules for research, generation, formatting, and tracking
- **Template System**: Use Jinja2 for CV and cover letter templates
- **Pipeline Pattern**: Each workflow step is a distinct, testable function
- **Data Classes**: Use Python dataclasses for structured data (JobInfo, ApplicantProfile, GeneratedOutput)
- **Configuration**: YAML/TOML files for user profiles, templates, and settings
- **File Organization**:
  ```
  src/
    ├── core/          # Core business logic
    ├── templates/     # Jinja2 templates for CVs, cover letters
    ├── research/      # Web scraping and analysis
    ├── generation/    # Content generation using Claude API
    ├── formatting/    # PDF/DOCX conversion
    └── tracking/      # Application tracking and archiving
  ```

### Testing Strategy
- **Framework**: pytest for all testing
- **Coverage Target**: Aim for 80%+ coverage on core business logic
- **Test Types**:
  - Unit tests for individual functions (research, generation logic)
  - Integration tests for full workflow pipelines
  - Snapshot/regression tests for generated content consistency
- **Fixtures**: Use pytest fixtures for sample job postings, user profiles
- **Mocking**: Mock external API calls (Claude API, web scraping) during tests
- **Test Data**: Store anonymized sample data in `tests/fixtures/`

### Git Workflow
- **Branching Strategy**: GitHub Flow (simplified)
  - `main` branch is always deployable
  - Feature branches: `feature/description` or `fix/description`
  - Merge via pull requests (even for solo work, for documentation)
- **Commit Conventions**:
  - Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`
  - Keep commits atomic and focused
  - Include OpenSpec references when implementing proposals
- **Versioning**: Semantic versioning (MAJOR.MINOR.PATCH)
- **Tags**: Tag releases with version numbers

## Domain Context

### Job Application Components
- **CV/Resume**: Structured document highlighting experience, skills, education
  - Formats: PDF (standard), DOCX (editable), ATS-friendly plain text
  - Sections: Summary, Experience, Education, Skills, Projects, Certifications
- **Cover Letter**: 1-page personalized motivation letter
  - Structure: Opening, Why this role, What you bring, Cultural fit, Closing
  - Tone variations: Formal (corporate), balanced (startups), casual (creative agencies)
- **Application Email**: Short intro email accompanying documents
  - Subject line optimization
  - Brief body (3-4 sentences max)
  - Professional signature

### ATS (Applicant Tracking System) Optimization
- **Keyword Matching**: Extract keywords from job description and incorporate naturally
- **Formatting Rules**:
  - Simple layouts (no tables, text boxes, headers/footers in CVs)
  - Standard section headings
  - Common fonts (Arial, Calibri, Times New Roman)
- **File Naming**: `FirstName_LastName_Position_Company.pdf`

### Cultural Considerations
- **German Market** (assumed based on "Bewerbungszauberer"):
  - Photo on CV may be expected/common
  - More formal tone than US applications
  - Detailed work history with exact dates
  - Certificates and credentials highly valued
- **Tone Analysis**: Detect company culture from job posting language and adapt

## Important Constraints

### Privacy & Data Protection
- **GDPR Compliance**: All personal data must be stored locally, never transmitted except to Claude API
- **No Cloud Storage**: Generated applications stored only on user's machine
- **API Key Security**: Claude API keys stored in environment variables or secure config, never in code
- **Data Retention**: User controls all archiving; no automatic telemetry or tracking

### Quality Standards
- **Factual Accuracy**: Never fabricate experience, skills, or achievements
- **Consistency**: All documents for one application must align (dates, job titles, responsibilities)
- **No Hallucinations**: Verify all company names, contact persons, and facts before generation
- **Human Review**: Generated content is a draft; user must review and approve

### Technical Limitations
- **API Rate Limits**: Respect Claude API rate limits; implement retry logic with exponential backoff
- **Cost Awareness**: Each application uses API tokens; provide cost estimates
- **Offline Capability**: Core template generation should work offline; only research requires internet

## External Dependencies

### AI Services
- **Anthropic Claude API**: Primary service for content generation, research analysis, and tone adaptation
  - Models: Claude 3.5 Sonnet (primary), Claude 3 Haiku (quick operations)
  - Usage: Cover letter writing, CV tailoring, keyword extraction, tone analysis

### Document Generation
- **ReportLab** or **WeasyPrint**: PDF generation from HTML/templates
- **python-docx**: DOCX file generation for editable documents
- **Jinja2**: Template engine for CV and cover letter structures

### Web Research (Optional)
- **BeautifulSoup4** + **requests**: Web scraping for company research
- **Playwright** or **Selenium**: For dynamic content if needed
- **Rate limiting**: Respect robots.txt and implement delays

### Data Management
- **PyYAML** or **tomli/tomllib**: Configuration file parsing
- **pydantic**: Data validation for user profiles and job information
- **SQLite**: Local database for tracking applications (lightweight, no server needed)

### Development Tools
- **black**: Code formatting
- **ruff**: Linting and import sorting
- **mypy**: Static type checking
- **pytest**: Testing framework
- **pytest-cov**: Coverage reporting