Initial Commit

openspec/project.md

@@ -0,0 +1,199 @@
+# 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