Bewerbungszauberer/src/CLAUDE.md

Job Application Framework - Instructions for Claude Code

This directory contains the Job Application Framework (Bewerbungszauberer), designed to help create tailored CVs, cover letters, and application emails using Claude Code.

Core Principle: Profile as Source of Truth

IMPORTANT: When the user requests help with ANY job application task (CV, cover letter, email, or application advice), you MUST:

1. Validate the profile first - Run /validate-profile to ensure profile.md is complete (see Profile Validation section below)
2. Always read profile.md first - This file contains the applicant's verified personal and professional information
3. Use ONLY information from profile.md - Never fabricate, assume, or hallucinate details about the applicant
4. Maintain consistency - All generated documents must align with the information in profile.md

Profile Validation

CRITICAL: Before generating any job application documents (CV, cover letter, or email), you MUST validate that profile.md is complete.

When to Validate

Run /validate-profile automatically before:

• Generating a CV/resume
• Writing a cover letter
• Drafting an application email
• Creating any job application materials

Validation Process

1. Automatic validation: When the user requests application generation, first run /validate-profile
2. Check results:
   • ✅ If validation passes → proceed with generation
   • ❌ If validation fails → inform the user of incomplete sections and STOP
3. User action: User must complete the profile sections flagged by validation
4. Re-validate: After user updates profile.md, run /validate-profile again before proceeding

Handling Validation Failures

If /validate-profile reports incomplete sections:

1. Do NOT generate documents - Incomplete profiles will result in placeholder text in professional documents
2. Show validation results - Display which sections need completion
3. Guide the user: "Your profile has incomplete sections. Please update profile.md with your real information in the following areas: [list sections]. Run /validate-profile again when ready."
4. Wait for updates: Do not proceed until validation passes

Explicit Skip Option

If the user explicitly requests to skip validation with phrases like:

• "Generate CV without validation"
• "I know my profile is incomplete, proceed anyway"
• "Skip validation and generate"

You MAY proceed with a clear warning:

⚠️  WARNING: Proceeding without validation. Your profile may contain placeholder text.
Generated documents might include [Your Name], [Company], or other template text.
Please review carefully and manually replace any placeholders before sending to employers.

Default behavior: ALWAYS validate unless explicitly told to skip.

Application Management

The framework provides a structured system for managing individual job applications. Each application gets its own workspace with organized folders for documents and strategy.

Creating a New Application

Use /new-application to initialize a new job application:

/new-application "Company Name - Job Title"

This will:

1. Create a dated folder: applications/pending/YYYY-MM-DD-CompanyName-JobTitle/
2. Generate an application.md template with sections for research, strategy, and planning
3. Create an input/ folder for storing job-related documents

Example:

/new-application "TechCorp - Senior Developer"

Creates: applications/pending/2025-11-02-TechCorp-Senior-Developer/

Adding Input Documents

After creating an application, add all relevant documents to the input/ folder:

Recommended documents:

• Job posting/advertisement (PDF, TXT, MD, DOCX)
• Recruiter emails or communications
• Company research notes (from website, LinkedIn, Glassdoor)
• Follow-up emails or additional context
• Application requirements or instructions

Supported formats: PDF, TXT, MD, DOCX, HTML, EML

The more context you provide, the better the analysis will be.

Populating the Application

Once you've added documents to the input/ folder, navigate to the application directory and run:

cd applications/pending/[your-application-folder]/
/populate-application

This will:

1. Read and analyze all documents in the input/ folder
2. Extract job requirements, company information, and keywords
3. Read your profile.md to understand your background
4. Match your experience and skills to the job requirements
5. Populate application.md with:
   • Extracted job information
   • Company research and culture insights
   • Match strategy (which experiences/skills to emphasize)
   • Key messages to convey
   • Tone recommendations
   • Suggested projects and achievements to highlight

The population preserves any manual notes you've added - it merges AI analysis with your insights.

Working with application.md

After population, review and refine the application.md file:

• Review extracted information: Ensure job details and requirements are accurate
• Add your insights: Enhance the strategy with your own thoughts
• Adjust match strategy: Fine-tune which experiences and projects to emphasize
• Add personal notes: Document your authentic reasons for interest in the role
• Plan your approach: Use the document checklist to track what needs to be created

The application.md serves as your strategic planning document for the entire application process.

Re-populating Applications

You can run /populate-application multiple times:

• Add more documents to input/ folder
• Re-run to merge new analysis with existing content
• Manual notes are always preserved

When to Read the Profile

Read profile.md automatically when the user asks for help with:

• Creating or tailoring a CV/resume
• Writing a cover letter
• Drafting an application email
• Customizing application documents for a specific job
• Reviewing or improving existing application materials
• Extracting relevant experience or skills for a position
• Advice on how to position themselves for a role

Job Application Workflow

When helping with job applications, follow this comprehensive workflow:

0. Profile Validation (REQUIRED FIRST STEP)

• Run /validate-profile to check profile.md is complete
• If validation fails, stop and ask user to complete profile
• If validation passes or user explicitly skips, proceed to step 1

1. Initialize Application (NEW)

• Use /new-application "Company - Job Title" to create organized workspace
• This creates: applications/pending/YYYY-MM-DD-Company-JobTitle/
• Workspace includes application.md template and input/ folder

2. Gather Documents & Context (NEW)

• User adds documents to input/ folder:
  • Job posting/description
  • Recruiter communications
  • Company research
  • Any other relevant context
• More context = better analysis and strategy

3. Analyze & Populate (NEW)

• Navigate to application folder: cd applications/pending/[folder-name]/
• Run /populate-application to:
  • Read and analyze all input documents
  • Extract job requirements, keywords, company culture
  • Cross-reference with profile.md
  • Generate match strategy
  • Populate application.md with research and recommendations

4. Review & Refine Strategy

• User reviews application.md for accuracy
• User adds personal insights and authentic motivations
• Adjust which experiences and projects to emphasize
• Fine-tune key messages and tone

5. Validate Application (NEW - Quality Gate)

• Run /validate-application to ensure application.md is complete
• Check that required sections are filled (Organization, Job Title, Job Description)
• Verify no placeholder text remains (like [To be filled])
• Get warnings if input/ folder is empty or application seems unpopulated
• Must pass before document generation

6. Generate Cover Letter

• Run /write-cover-letter to generate a tailored cover letter
• System automatically validates application first (stops if incomplete)
• Checks if cover-letter.md already exists (prevents overwriting)
• Generates 300-400 word cover letter using:
  • Profile.md for applicant background and achievements
  • Application.md for job strategy, key messages, and tone
• Standard structure: Opening → Why this role → What you bring → Cultural fit → Closing
• Applies appropriate tone (Formal/Balanced/Casual) from application.md
• Saves to cover-letter.md in application folder
• Flags available: --skip-validation, --force (overwrite existing)

7. Review and Refine Cover Letter

• Read generated cover-letter.md carefully
• Verify factual accuracy (names, dates, achievements)
• Add personal touches or additional insights
• Ensure authentic voice and genuine enthusiasm
• Proofread for typos and flow

8. Generate CV (FUTURE)

• Generate tailored CV based on application.md strategy (coming soon)
• Emphasize relevant experience from profile.md
• Incorporate keywords naturally

9. Generate Application Email (FUTURE)

• Create professional application email (coming soon)

10. Quality Assurance

• Verify all company names, dates, and facts are correct
• Ensure consistency between all documents (CV ↔ cover letter ↔ email)
• Check that tone matches the target company culture
• Confirm ATS optimization if applicable (simple formatting, keywords, standard sections)

Document Standards

CV/Resume

• Use information from relevant sections of profile.md
• Tailor the professional summary to the specific role
• Emphasize experiences and skills that match job requirements
• Keep formatting simple and ATS-friendly
• Use quantifiable achievements when available

Cover Letter (Generated by /write-cover-letter)

• Structure: Opening → Why this role → What you bring → Cultural fit → Closing
• Length: 300-400 words (approximately 1 page)
• Tone: Applied from application.md tone assessment (Formal/Balanced/Casual)
• Language: Inferred from job posting context (German/English)
• Content:
  • Use ONLY authentic information from profile.md (no fabrication)
  • Incorporate 2-3 key experiences from match strategy
  • Reference company research and culture insights from application.md
  • Natural incorporation of keywords from job description
  • Company-specific personalization (values, news, projects)
• Quality checks:
  • Automatic validation before generation
  • Protection against overwriting existing work
  • Word count target enforcement (300-400 words)
  • Factual accuracy verification

Application Email

• Keep it short (3-4 sentences maximum)
• Subject line: Clear and professional
• Body: Brief introduction, reference to attached documents, expression of interest
• Professional signature using contact info from profile.md

Cultural Considerations

This framework is designed with the German job market in mind:

• More formal tone is often expected
• Detailed work history with exact dates is valued
• Certificates and credentials are highly regarded
• A professional photo on CV may be common (user's choice)

Adjust recommendations based on the target market if the user specifies a different region.

Constraints

Data Privacy:

• All information stays local - only API calls to Claude use the data
• Never suggest uploading sensitive personal data to third-party services
• Respect GDPR and data protection principles

Accuracy & Honesty:

• NEVER fabricate experience, skills, or achievements
• If profile.md lacks information needed for a job application, ask the user to update profile.md first
• Be transparent about what can and cannot be emphasized from the applicant's background

Quality Standards:

• All generated content is a DRAFT - user must review and approve
• Fact-check company names, contact persons, and details from job postings
• Maintain consistency across all documents for a single application

Available Commands

• /validate-profile - Validate that profile.md is complete and ready for application generation
• /new-application "Company - Job Title" - Create a new application workspace with organized folder structure
• /populate-application - Analyze input documents and populate application.md with job info, research, and strategy
• /validate-application [optional-app-name] - Validate that application.md is complete before document generation
• /write-cover-letter [optional-app-name] [--skip-validation] [--force] - Generate a tailored cover letter based on application strategy

Example Usage

Example 1: Complete Application Workflow

User: "Help me apply for this software engineering position at TechCorp"

Claude Code should:

1. Run /validate-profile to check profile completeness
2. If validation passes, suggest: "Let's create an application workspace. Run: /new-application 'TechCorp - Software Engineer'"
3. After application is created, guide user: "Add the job posting and any other documents to applications/pending/[folder]/input/"
4. When user has added documents: "Navigate to the application folder and run /populate-application"
5. After population completes: "Review application.md to see the analysis and strategy"
6. Validation step: "Run /validate-application to ensure the application is complete"
7. If validation passes: "Generate cover letter with /write-cover-letter"
8. After generation: "Review cover-letter.md and personalize as needed"
9. Future: Generate tailored CV and application email

Example 2: Quick Document Request (Legacy Flow)

User: "Write a cover letter for this role [paste job description]"

Claude Code should:

1. Run /validate-profile to check profile completeness
2. If validation fails: inform user of incomplete sections and stop
3. If validation passes: Read profile.md to load applicant information
4. Analyze the job description for requirements and culture
5. Identify matching experiences and skills from the profile
6. Generate tailored cover letter using only information from profile.md
7. Suggest: "For better organization, consider using /new-application next time to manage the full application process"

Example 3: Validating an Application

User: "Check if my TechCorp application is ready"

Claude Code should:

1. If user is in application folder: Run /validate-application (auto-detects current location)
2. If user is elsewhere: Run /validate-application 2025-11-02-TechCorp-Software-Engineer
3. If validation passes (✅): "Your application is complete! Organization: TechCorp, Position: Software Engineer. Ready for document generation."
4. If validation fails (❌): Show specific issues like "Organization Name: Contains placeholder '[To be filled]'" and suggest "Please update application.md or run /populate-application if you have documents in input/"
5. Provide clear next steps based on validation result

Example 4: Generating a Cover Letter

User: "Generate cover letter for my TechCorp application"

Claude Code should:

1. If user is in application folder: Run /write-cover-letter (auto-detects location)
2. If user is elsewhere: Run /write-cover-letter 2025-11-02-TechCorp-Software-Engineer
3. System automatically validates application first:
   • If validation fails: Stop and show errors, suggest fixing or using --skip-validation
   • If validation passes: Proceed to generation
4. Check for existing cover-letter.md:
   • If exists: Stop and suggest using --force flag to overwrite
   • If doesn't exist: Proceed to generation
5. Generate cover letter:
   • Read profile.md for applicant background
   • Read application.md for job strategy and tone
   • Generate 300-400 word tailored cover letter
   • Save to cover-letter.md
6. Show success: "✅ Cover letter saved: cover-letter.md. Generated 376 words. Next: Review and personalize."

User: "Regenerate the cover letter with different approach"

Claude Code should:

1. Run /write-cover-letter --force to overwrite existing file
2. System warns: "⚠️ Overwriting existing cover letter"
3. Proceeds with generation
4. Suggests: "Review the new version and keep whichever you prefer"

Updating the Profile

If you notice missing or outdated information during application preparation:

• Inform the user which sections of profile.md need updates
• Ask them to update profile.md first before generating documents
• This ensures the profile remains the single source of truth

---

Remember: The quality of output depends on the quality of profile.md. Encourage users to keep it complete, accurate, and up to date.