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