gurix/Bewerbungszauberer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add comprehensive user documentation (README.md)

Browse Source 
Implement the add-readme OpenSpec proposal with complete user-facing
documentation covering setup, workflow, and all implemented features.

Documentation includes:
- Framework introduction and feature overview
- Prerequisites (Claude Code required, Pandoc/LaTeX optional)
- Step-by-step setup instructions with profile shortcut
- Complete 12-step workflow (numbered 1-12)
- Detailed commands reference for all 7 slash commands
- Directory structure visualization with explanations
- Maintenance guidance for updates and archiving

Changes from initial draft:
- Removed Quick Start section for simplicity
- Renumbered workflow steps starting from 1 instead of 0
- Removed Example Workflow section to keep documentation concise
- Removed Best Practices section (redundant with workflow guidance)
- Removed Troubleshooting section (detailed help in CLAUDE.md)

All content focuses exclusively on implemented features. No mention of
unimplemented features like automated CV generation.

Closes OpenSpec change: add-readme

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Markus Graf
2025-11-10 15:08:11 +01:00
co-authored by Claude
parent d39be42e81
commit af47ac7663
2 changed files with 462 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+451
View File
@@ -0,0 +1,451 @@
# Bewerbungszauberer
**AI-powered job application framework for Claude Code**
Bewerbungszauberer (German: "Application Wizard") is a markdown-based framework that helps you create tailored job application documents using Claude Code. It manages your professional profile, analyzes job postings, and generates customized cover letters and application emails.
## Features
- **Application Workspace Management** - Organize each job application with its own folder structure
- **Profile Validation** - Ensure your professional profile is complete before generating documents
- **Intelligent Document Analysis** - Automatically analyze job postings and extract requirements
- **Strategic Planning** - Generate application strategies that match your experience to job requirements
- **Cover Letter Generation** - Create tailored, professional cover letters based on your profile and strategy
- **Swiss Format PDF Conversion** - Convert cover letters to professionally formatted PDFs (Swiss business letter standard)
- **Application Email Generation** - Generate concise, professional application emails with document references
- **Markdown-Based Workflow** - Everything is markdown files managed through slash commands in Claude Code
## Prerequisites
### Required
- **[Claude Code](https://claude.ai/download)** - The AI-powered CLI that runs this framework
### Optional (for PDF conversion)
- **Pandoc** - Document converter
- macOS: `brew install pandoc`
- Ubuntu/Debian: `sudo apt install pandoc`
- [Other platforms](https://pandoc.org/installing.html)
- **LaTeX** - PDF generation engine
- macOS: `brew install texlive` or [MacTeX](https://www.tug.org/mactex/)
- Ubuntu/Debian: `sudo apt install texlive-latex-base texlive-latex-extra texlive-lang-german`
- [Other platforms](https://www.latex-project.org/get/)
Note: PDF conversion is optional. You can generate markdown cover letters and convert them manually if preferred.
## Setup
### 1. Install Claude Code
Download and install Claude Code from [claude.ai/download](https://claude.ai/download).
### 2. Create Your Working Directory
Create a directory for your job applications:
```bash
mkdir my-applications
```
### 3. Copy Framework Files
Copy the contents of the `src/` directory to your working directory:
```bash
cp -r /path/to/Bewerbungszauberer/src/* my-applications/
cd my-applications/
```
### 4. Configure Your Profile
Open `profile.md` and fill in your personal and professional information. This file is the single source of truth for all generated documents.
**Profile Setup Shortcut:** If you have existing CVs, certificates, or portfolio documents, you can have Claude help you:
1. Create a subdirectory in your working directory:
```bash
mkdir documents/
```
2. Add your existing files (CV, certificates, portfolio PDFs, etc.) to this directory
3. In Claude Code, prompt:
```
Please read all documents in the documents/ folder and help me fill out profile.md with the information you find.
```
Claude will extract and structure the information from your documents automatically.
### 5. Start Using the Framework
You're ready to go! Navigate to your working directory in Claude Code and start creating applications.
## Complete Workflow
Here's the detailed end-to-end process for creating a job application:
### Step 1: Validate Your Profile
Before starting any application, ensure your profile is complete:
```bash
/validate-profile
```
This checks that all required sections in `profile.md` are filled out. Fix any issues before proceeding.
### Step 2: Create New Application
Create a workspace for your application:
```bash
/new-application "TechCorp - Senior Developer"
```
This creates a dated folder: `applications/pending/2025-11-10-TechCorp-Senior-Developer/`
### Step 3: Add Job Documents
Navigate to the application folder and add relevant documents to the `input/` folder:
```bash
cd applications/pending/2025-11-10-TechCorp-Senior-Developer/
# Copy job posting, recruiter emails, company research to input/
```
Supported formats: PDF, TXT, MD, DOCX, HTML, EML
### Step 4: Populate Application
Analyze the job documents and generate an application strategy:
```bash
/populate-application
```
This reads all documents in `input/`, analyzes requirements, and populates `application.md` with:
- Extracted job information
- Company research insights
- Match strategy (which experiences to emphasize)
- Key messages to convey
- Tone recommendations
### Step 5: Review and Refine Strategy
Open `application.md` and review the generated strategy:
- Verify job details are accurate
- Add your personal insights
- Adjust which experiences to emphasize
- Note your authentic reasons for interest
### Step 6: Validate Application
Ensure the application is ready for document generation:
```bash
/validate-application
```
This checks that required fields are complete. Fix any issues before proceeding.
### Step 7: Generate Cover Letter
Create a tailored cover letter based on your profile and strategy:
```bash
/write-cover-letter
```
This generates `cover-letter.md` with a professional cover letter (300-400 words) that:
- Uses your experiences from `profile.md`
- Follows the strategy in `application.md`
- Applies appropriate tone (Formal/Balanced/Casual)
- Incorporates job keywords naturally
### Step 8: Review Cover Letter
Open `cover-letter.md` and review:
- Verify factual accuracy (names, dates, achievements)
- Add personal touches
- Ensure authentic voice
- Proofread for typos
### Step 9: Convert to PDF (Optional)
Convert your cover letter to a professionally formatted PDF:
```bash
/convert-cover-letter
```
This requires Pandoc and LaTeX (see Prerequisites). The PDF follows Swiss business letter standards with proper address window positioning.
### Step 10: Prepare Attachments
Add final documents to the `attachments/` folder:
- Your CV/Resume (PDF format)
- Cover letter PDF (from step 9, or convert manually)
- Any required certificates or diplomas
### Step 11: Generate Application Email
Create a professional application email:
```bash
/write-application-email
```
This generates `application-email.md` with:
- Professional subject line
- Brief email body (3-4 sentences)
- Explicit references to attached documents
- Contact information
The system verifies that required documents exist in `attachments/` before generating.
### Step 12: Review and Send
Open `application-email.md` and verify:
- All attachments are correctly listed
- Subject line is appropriate
- Contact information is current
- Tone matches company culture
You're ready to send your application!
## Commands Reference
### `/validate-profile`
Validates that your `profile.md` is complete and ready for document generation.
**Usage:**
```bash
/validate-profile
```
**What it checks:**
- Required sections are filled out
- No placeholder text remains
- Profile has sufficient information for applications
### `/new-application "Company - Job Title"`
Creates a new application workspace with organized folder structure.
**Usage:**
```bash
/new-application "TechCorp - Senior Developer"
```
**Creates:**
- `applications/pending/YYYY-MM-DD-Company-JobTitle/`
- `application.md` template
- `input/` folder for job documents
- `attachments/` folder for final PDFs
### `/populate-application`
Analyzes documents in the `input/` folder and populates `application.md` with job information, research, and strategy.
**Usage:**
```bash
cd applications/pending/[your-application-folder]/
/populate-application
```
**Requires:**
- Job posting or related documents in `input/` folder
- Completed `profile.md`
**Generates:**
- Job requirements analysis
- Company research insights
- Match strategy
- Key messages and tone recommendations
### `/validate-application [optional-app-name]`
Validates that `application.md` is complete before document generation.
**Usage:**
```bash
# From inside application folder:
/validate-application
# From anywhere:
/validate-application 2025-11-10-TechCorp-Senior-Developer
```
**Checks:**
- Required fields are filled (Organization, Job Title, Job Description)
- No placeholder text remains
- Input folder has documents
### `/write-cover-letter [optional-app-name] [--skip-validation] [--force]`
Generates a tailored cover letter based on your profile and application strategy.
**Usage:**
```bash
# From inside application folder:
/write-cover-letter
# From anywhere:
/write-cover-letter 2025-11-10-TechCorp-Senior-Developer
# Skip validation (use with caution):
/write-cover-letter --skip-validation
# Overwrite existing cover letter:
/write-cover-letter --force
```
**Generates:**
- `cover-letter.md` with 300-400 word cover letter
- Standard structure: Opening → Why this role → What you bring → Cultural fit → Closing
- Applies tone from application.md (Formal/Balanced/Casual)
- Uses information only from profile.md (no fabrication)
**Flags:**
- `--skip-validation` - Skip application validation check
- `--force` - Overwrite existing cover letter
### `/convert-cover-letter`
Converts `cover-letter.md` to a professionally formatted PDF using Swiss business letter standards.
**Usage:**
```bash
# Must be run from application folder containing cover-letter.md:
cd applications/pending/[your-application-folder]/
/convert-cover-letter
```
**Requires:**
- Pandoc installed
- LaTeX (pdflatex) installed
- `cover-letter.md` with proper frontmatter
**Generates:**
- `cover-letter.pdf` in Swiss business letter format
- Address window positioning for standard Swiss envelopes
- Professional layout with proper margins
### `/write-application-email [optional-app-name] [--skip-validation] [--force]`
Generates a professional application email with document references.
**Usage:**
```bash
# From inside application folder:
/write-application-email
# From anywhere:
/write-application-email 2025-11-10-TechCorp-Senior-Developer
# Skip validation:
/write-application-email --skip-validation
# Overwrite existing email:
/write-application-email --force
```
**Requires:**
- CV/Resume in `attachments/` folder
- Cover letter in `attachments/` folder
**Generates:**
- `application-email.md` with brief email (3-4 sentences)
- Professional subject line
- Explicit references to attached documents
- Contact information and availability statement
**Flags:**
- `--skip-validation` - Skip application validation check
- `--force` - Overwrite existing email
## Directory Structure
After setup, your working directory will look like this:
```
my-applications/
├── profile.md # Your professional profile (single source of truth)
├── CLAUDE.md # AI assistant instructions (don't modify)
├── .claude/
│ ├── commands/ # Slash commands for the framework
│ │ ├── validate-profile.md
│ │ ├── new-application.md
│ │ ├── populate-application.md
│ │ ├── validate-application.md
│ │ ├── write-cover-letter.md
│ │ ├── convert-cover-letter.md
│ │ └── write-application-email.md
│ └── templates/ # Document templates
│ ├── application-template.md
│ └── swiss-letter.tex
└── applications/
└── pending/ # Active applications
└── 2025-11-10-TechCorp-Senior-Developer/
├── application.md # Strategy and planning
├── input/ # Job posting and research
│ ├── job-posting.pdf
│ └── company-research.md
├── cover-letter.md # Generated cover letter
├── cover-letter.pdf # PDF version
├── application-email.md # Generated email
└── attachments/ # Final documents to send
├── CV.pdf
├── Cover_Letter.pdf
└── Certificates.pdf
```
### Key Files and Folders
- **`profile.md`** - Your personal and professional information. This is the single source of truth for all generated documents. Keep it up to date.
- **`CLAUDE.md`** - Instructions for the AI assistant. Don't modify this file.
- **`.claude/`** - Framework commands and templates. These define how the slash commands work.
- **`applications/pending/`** - Active job applications. Each application gets its own dated folder.
- **`input/`** - Store job postings, recruiter emails, and company research here. The framework analyzes these to generate your strategy.
- **`attachments/`** - Final PDFs ready to send with your application (CV, cover letter, certificates).
## Maintenance
### Framework Updates
The framework files are in the `src/` directory of the repository. When updates are available:
1. Review the changelog or release notes
2. Selectively copy updated files to your working directory
3. **Be careful not to overwrite your `profile.md` or `applications/` folder**
Example safe update:
```bash
# Update slash commands only
cp -r /path/to/Bewerbungszauberer/src/.claude/commands/* .claude/commands/
# Update CLAUDE.md instructions
cp /path/to/Bewerbungszauberer/src/CLAUDE.md ./
```
Never use `cp -r src/* my-applications/` as this will overwrite your profile and applications.
### Archiving Completed Applications
Once an application process is complete (accepted, rejected, or withdrawn), you can move it from `pending/` to an archive folder:
```bash
mkdir -p applications/archive/2025/
mv applications/pending/2025-11-10-TechCorp-Senior-Developer/ applications/archive/2025/
```
This keeps your workspace organized and focused on active applications.
openspec/changes/add-readme/tasks.md
+11 -11
View File
@@ -291,17 +291,17 @@ Create comprehensive user-facing documentation in README.md that covers setup, c
- None (documentation only, no code dependencies) - None (documentation only, no code dependencies)
## Verification Checklist ## Verification Checklist
- [ ] README.md exists in repository root - [x] README.md exists in repository root
- [ ] Contains all required sections (About, Features, Prerequisites, Setup, Workflow, Commands) - [x] Contains all required sections (About, Features, Prerequisites, Setup, Workflow, Commands)
- [ ] Setup instructions are clear and complete - [x] Setup instructions are clear and complete
- [ ] All implemented slash commands are documented - [x] All implemented slash commands are documented
- [ ] No references to unimplemented features (e.g., automated CV generation) - [x] No references to unimplemented features (e.g., automated CV generation)
- [ ] Examples use realistic scenarios - [x] Examples use realistic scenarios
- [ ] Directory structure reflects actual layout - [x] Directory structure reflects actual layout
- [ ] Markdown formatting is correct - [x] Markdown formatting is correct
- [ ] Links (if any) are valid - [x] Links (if any) are valid
- [ ] Documentation is accessible to non-technical users - [x] Documentation is accessible to non-technical users
- [ ] Proofread for typos and clarity - [x] Proofread for typos and clarity
## Total Estimated Effort ## Total Estimated Effort
Approximately 3-4 hours for comprehensive documentation. Approximately 3-4 hours for comprehensive documentation.