From af47ac7663f53b9da1d5c84631d2c7a04b652efc Mon Sep 17 00:00:00 2001 From: Markus Graf Date: Mon, 10 Nov 2025 15:08:11 +0100 Subject: [PATCH] docs: add comprehensive user documentation (README.md) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.md | 451 +++++++++++++++++++++++++++ openspec/changes/add-readme/tasks.md | 22 +- 2 files changed, 462 insertions(+), 11 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..9f4a10e --- /dev/null +++ b/README.md @@ -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. + diff --git a/openspec/changes/add-readme/tasks.md b/openspec/changes/add-readme/tasks.md index d8b5463..8e0014d 100644 --- a/openspec/changes/add-readme/tasks.md +++ b/openspec/changes/add-readme/tasks.md @@ -291,17 +291,17 @@ Create comprehensive user-facing documentation in README.md that covers setup, c - None (documentation only, no code dependencies) ## Verification Checklist -- [ ] README.md exists in repository root -- [ ] Contains all required sections (About, Features, Prerequisites, Setup, Workflow, Commands) -- [ ] Setup instructions are clear and complete -- [ ] All implemented slash commands are documented -- [ ] No references to unimplemented features (e.g., automated CV generation) -- [ ] Examples use realistic scenarios -- [ ] Directory structure reflects actual layout -- [ ] Markdown formatting is correct -- [ ] Links (if any) are valid -- [ ] Documentation is accessible to non-technical users -- [ ] Proofread for typos and clarity +- [x] README.md exists in repository root +- [x] Contains all required sections (About, Features, Prerequisites, Setup, Workflow, Commands) +- [x] Setup instructions are clear and complete +- [x] All implemented slash commands are documented +- [x] No references to unimplemented features (e.g., automated CV generation) +- [x] Examples use realistic scenarios +- [x] Directory structure reflects actual layout +- [x] Markdown formatting is correct +- [x] Links (if any) are valid +- [x] Documentation is accessible to non-technical users +- [x] Proofread for typos and clarity ## Total Estimated Effort Approximately 3-4 hours for comprehensive documentation.