diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..f9e9a95 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +# Do not consider Markdown files documentation anymore for +# the Documentation! +src/**/*.md -linguist-documentation \ No newline at end of file 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/proposal.md b/openspec/changes/add-readme/proposal.md new file mode 100644 index 0000000..60e686e --- /dev/null +++ b/openspec/changes/add-readme/proposal.md @@ -0,0 +1,98 @@ +# Proposal: Add User Documentation (README.md) + +**Change ID**: `add-readme` +**Date**: 2025-11-10 +**Status**: Draft + +## Overview + +Add a comprehensive README.md to the repository root that documents the actual working functionality of the Job Application Framework (Bewerbungszauberer). The documentation will focus on practical setup and usage instructions based on implemented features. + +## Motivation + +Currently, the framework lacks user-facing documentation that explains how to: +- Install and set up the framework +- Configure the profile.md file +- Use the slash commands workflow +- Generate application documents + +Users need clear, step-by-step instructions that document only what is actually implemented and working, not aspirational features. This documentation will lower the barrier to entry and help new users get started quickly. + +## Scope + +### In Scope +- Installation and setup instructions (Claude Code installation, copying src directory) +- Profile configuration guidance (including shortcut using Claude to help fill it out) +- Complete workflow documentation based on archived specs: + - Creating new applications (`/new-application`) + - Populating applications (`/populate-application`) + - Validating applications (`/validate-application`) + - Generating cover letters (`/write-cover-letter`) + - Converting to PDF (`/convert-cover-letter`) + - Generating application emails (`/write-application-email`) +- Brief framework description and purpose +- Prerequisites (system requirements) + +### Out of Scope +- Unimplemented features (CV generation workflow automation) +- Development/contribution guidelines +- Internal architecture documentation +- API documentation for extending the framework + +## User Impact + +**Positive**: +- New users can quickly understand what the framework does and how to use it +- Clear setup instructions reduce friction in getting started +- Workflow documentation helps users leverage all implemented features +- Self-service documentation reduces need for direct support + +**Neutral**: +- Existing users who already understand the workflow won't need this documentation + +## Implementation Approach + +1. Create README.md in repository root +2. Structure documentation in user-friendly format: + - Brief introduction and purpose + - Prerequisites section + - Setup instructions + - Quick start guide + - Detailed workflow documentation + - Troubleshooting section (if needed) +3. Use clear, concise language with examples +4. Include command snippets that users can copy-paste +5. Reference only implemented features validated against archived specs + +## Alternatives Considered + +1. **Wiki or separate documentation site**: Rejected - adds complexity and requires maintenance of separate system +2. **Documentation in CLAUDE.md only**: Rejected - CLAUDE.md is for AI assistant instructions, not human users +3. **Video tutorial**: Rejected - text documentation is easier to maintain and update + +## Success Criteria + +- [ ] README.md exists in repository root +- [ ] Documentation covers all implemented slash commands +- [ ] Setup instructions are clear and actionable +- [ ] No references to unimplemented features +- [ ] Uses examples from actual usage patterns +- [ ] New users can follow README to complete a full application workflow + +## Dependencies + +None - documentation change only. + +## Risks + +**Low Risk**: This is purely additive documentation. No code changes required. + +**Mitigation**: Review against actual implementation to ensure accuracy. + +## Related Changes + +None - standalone documentation addition. + +## Specs Modified + +- **NEW**: `user-documentation` - Documents the requirements for user-facing README diff --git a/openspec/changes/add-readme/specs/user-documentation/spec.md b/openspec/changes/add-readme/specs/user-documentation/spec.md new file mode 100644 index 0000000..b266533 --- /dev/null +++ b/openspec/changes/add-readme/specs/user-documentation/spec.md @@ -0,0 +1,277 @@ +# user-documentation Specification + +## Purpose +Provide user-facing documentation that enables new users to set up and use the Job Application Framework effectively. + +## ADDED Requirements + +### Requirement: Repository README + +The system SHALL provide a README.md file in the repository root that documents setup, configuration, and usage. + +#### Scenario: README exists in root + +- **WHEN** user clones or downloads the repository +- **THEN** README.md is present in the root directory +- **AND** is immediately visible on GitHub/GitLab repository page + +#### Scenario: README is readable + +- **WHEN** user opens README.md +- **THEN** content is formatted in clear markdown +- **AND** uses headings, lists, and code blocks for readability + +### Requirement: Framework Introduction + +The system documentation SHALL provide a brief description of the framework's purpose and capabilities. + +#### Scenario: Purpose statement + +- **WHEN** user reads the README introduction +- **THEN** they understand the framework helps with job application document generation +- **AND** understand it uses Claude Code as the AI agent +- **AND** understand it works with markdown files and slash commands + +#### Scenario: Feature overview + +- **WHEN** user reads the features section +- **THEN** they see a list of implemented capabilities: + - Application management (workspaces) + - Profile validation + - Cover letter generation + - PDF conversion (Swiss format) + - Application email generation + +### Requirement: Prerequisites Documentation + +The system documentation SHALL list all prerequisites required before users can use the framework. + +#### Scenario: Claude Code requirement + +- **WHEN** user checks prerequisites +- **THEN** documentation states Claude Code must be installed +- **AND** provides link or reference to Claude Code installation + +#### Scenario: System requirements for PDF conversion + +- **WHEN** user checks prerequisites for PDF features +- **THEN** documentation mentions Pandoc and LaTeX requirements +- **AND** notes these are optional (only needed for `/convert-cover-letter`) + +### Requirement: Setup Instructions + +The system documentation SHALL provide step-by-step setup instructions. + +#### Scenario: Initial setup steps + +- **WHEN** user follows setup instructions +- **THEN** instructions include: + 1. Install Claude Code (prerequisite) + 2. Create working directory (e.g., "my-applications") + 3. Copy contents of src/ directory to working directory + 4. Navigate to working directory in terminal + +#### Scenario: Profile configuration step + +- **WHEN** user reaches profile setup in instructions +- **THEN** documentation instructs them to fill out profile.md +- **AND** explains profile.md contains personal and professional information +- **AND** provides shortcut: create subdirectory with existing CV/docs and ask Claude to help populate profile + +#### Scenario: Profile shortcut explanation + +- **WHEN** user wants help filling out profile +- **THEN** documentation suggests: + - Create subdirectory (e.g., "documents/") + - Add existing CVs, certificates, portfolio materials + - Prompt Claude: "Please read all documents in documents/ and help me fill out profile.md" +- **AND** explains Claude will extract and structure information automatically + +### Requirement: Workflow Documentation + +The system documentation SHALL document the complete application workflow with all implemented slash commands. + +#### Scenario: Command reference + +- **WHEN** user reviews available commands +- **THEN** documentation lists each implemented slash command: + - `/validate-profile` - Check profile completeness + - `/new-application "Company - Job Title"` - Create application workspace + - `/populate-application` - Analyze job documents and generate strategy + - `/validate-application` - Verify application readiness + - `/write-cover-letter` - Generate tailored cover letter + - `/convert-cover-letter` - Convert to Swiss format PDF + - `/write-application-email` - Generate professional application email + +#### Scenario: Complete workflow example + +- **WHEN** user reads workflow section +- **THEN** documentation provides end-to-end example: + 1. Validate profile + 2. Create new application + 3. Add job posting to input/ folder + 4. Populate application with analysis + 5. Review and refine application.md + 6. Validate application + 7. Generate cover letter + 8. Convert cover letter to PDF + 9. Add PDF and CV to attachments/ + 10. Generate application email + 11. Review and send + +#### Scenario: Command usage examples + +- **WHEN** user reads about a specific command +- **THEN** documentation includes: + - Command syntax with parameters + - Example usage with realistic values + - Expected output or result + - Common flags (--force, --skip-validation) + +### Requirement: Quick Start Guide + +The system documentation SHALL provide a condensed quick start guide for experienced users. + +#### Scenario: Minimal setup path + +- **WHEN** user follows quick start +- **THEN** guide shows fastest path to first application: + 1. Copy src/ to working directory + 2. Fill out profile.md + 3. Run `/new-application "Company - Role"` + 4. Add job posting to input/ + 5. Run `/populate-application` + 6. Run `/write-cover-letter` + +#### Scenario: Quick start assumptions + +- **WHEN** quick start is presented +- **THEN** it assumes user has Claude Code installed +- **AND** assumes basic familiarity with terminal/CLI + +### Requirement: Directory Structure Documentation + +The system documentation SHALL explain the directory structure users will work with. + +#### Scenario: Working directory structure + +- **WHEN** user reviews directory structure +- **THEN** documentation shows example structure: +``` +my-applications/ +├── profile.md (your information) +├── CLAUDE.md (AI instructions) +├── .claude/ +│ ├── commands/ (slash commands) +│ └── templates/ +└── applications/ + └── pending/ + └── 2025-11-10-Company-Role/ + ├── application.md (strategy) + ├── input/ (job posting, etc.) + ├── cover-letter.md + ├── application-email.md + └── attachments/ (PDFs, CV) +``` + +#### Scenario: Folder purpose explanation + +- **WHEN** user reads about directory structure +- **THEN** documentation explains purpose of each key folder: + - `profile.md` - User's professional profile (single source of truth) + - `applications/pending/` - Active job applications + - `input/` - Job postings and research materials + - `attachments/` - Final PDFs ready to send + +### Requirement: Troubleshooting Section + +The system documentation SHALL provide troubleshooting guidance for common issues. + +#### Scenario: Profile validation failures + +- **WHEN** user encounters profile validation errors +- **THEN** documentation explains common issues: + - Incomplete required sections + - Placeholder text remaining +- **AND** suggests running `/validate-profile` to identify issues + +#### Scenario: PDF conversion issues + +- **WHEN** user has PDF conversion problems +- **THEN** documentation references: + - Pandoc installation requirements + - LaTeX installation requirements + - Links to /convert-cover-letter command documentation in CLAUDE.md + +### Requirement: No Unimplemented Features + +The system documentation SHALL NOT reference features that are not implemented. + +#### Scenario: Only implemented commands + +- **WHEN** documentation lists available commands +- **THEN** it includes only commands that exist in src/.claude/commands/ +- **AND** does not mention planned but unimplemented features + +#### Scenario: No CV generation workflow + +- **WHEN** documentation describes workflow +- **THEN** it does NOT include automated CV generation steps +- **AND** assumes user provides their own CV file to attachments/ + +#### Scenario: Honest feature status + +- **WHEN** documentation mentions future features +- **THEN** they are clearly marked as "Coming soon" or "Planned" +- **AND** not included in main workflow instructions + +### Requirement: Practical Examples + +The system documentation SHALL use realistic examples that reflect actual usage. + +#### Scenario: Example company and job title + +- **WHEN** documentation shows command examples +- **THEN** uses realistic company names and job titles +- **AND** shows actual command syntax (e.g., `/new-application "TechCorp - Senior Developer"`) + +#### Scenario: Example workflow narrative + +- **WHEN** documentation walks through complete workflow +- **THEN** uses consistent example throughout: + - Applying to specific company + - Using actual job title + - Showing realistic file contents where helpful + +### Requirement: Accessibility + +The system documentation SHALL be accessible to users with varying technical backgrounds. + +#### Scenario: Clear language + +- **WHEN** user reads documentation +- **THEN** language is clear and jargon-free +- **AND** technical terms are explained when first introduced + +#### Scenario: Progressive detail + +- **WHEN** documentation presents information +- **THEN** starts with high-level overview +- **AND** provides detailed steps afterward +- **AND** allows users to skip to sections relevant to them + +### Requirement: Maintenance Notes + +The system documentation SHALL include guidance on keeping the profile updated. + +#### Scenario: Profile maintenance reminder + +- **WHEN** user completes initial setup +- **THEN** documentation reminds them to keep profile.md current +- **AND** suggests updating after new projects, certifications, or role changes + +#### Scenario: Framework updates + +- **WHEN** documentation discusses framework usage +- **THEN** mentions that src/ directory contains the framework source +- **AND** notes updates should be applied by copying updated src/ files (with care not to overwrite user data) diff --git a/openspec/changes/add-readme/tasks.md b/openspec/changes/add-readme/tasks.md new file mode 100644 index 0000000..8e0014d --- /dev/null +++ b/openspec/changes/add-readme/tasks.md @@ -0,0 +1,314 @@ +# Tasks: Add User Documentation (README.md) + +## Overview +Create comprehensive user-facing documentation in README.md that covers setup, configuration, and usage of all implemented features. + +## Prerequisites +- Review all implemented slash commands in src/.claude/commands/ +- Review archived OpenSpec changes to understand implemented features +- Review CLAUDE.md for current framework instructions + +## Task Breakdown + +### 1. Create README.md Structure +**Description**: Create README.md file in repository root with complete documentation structure. + +**Steps**: +1. Create README.md in repository root +2. Add title and brief tagline +3. Create section headers: + - About + - Features + - Prerequisites + - Setup + - Quick Start + - Workflow + - Directory Structure + - Commands Reference + - Troubleshooting (optional) + +**Validation**: File exists at /Users/markus.graf/workspace/Bewerbungszauberer/README.md + +**Estimated effort**: 15 minutes + +--- + +### 2. Write About and Features Sections +**Description**: Document what the framework is and what it can do (implemented features only). + +**Steps**: +1. Write brief description of framework purpose (job application document generation) +2. Mention Claude Code as the AI agent platform +3. List implemented features: + - Application workspace management + - Profile validation + - Document analysis and strategy generation + - Cover letter generation + - Swiss format PDF conversion + - Application email generation +4. Emphasize markdown-based workflow with slash commands + +**Validation**: Sections accurately describe framework without mentioning unimplemented features + +**Estimated effort**: 20 minutes + +--- + +### 3. Document Prerequisites +**Description**: List all requirements users need before using the framework. + +**Steps**: +1. Document required prerequisites: + - Claude Code installation (with link/reference) +2. Document optional prerequisites: + - Pandoc (for PDF conversion) + - LaTeX/pdflatex (for PDF conversion) +3. Note system requirements (macOS, Linux, Windows with appropriate tools) +4. Clarify what's required vs optional + +**Validation**: All prerequisites are accurate and necessary + +**Estimated effort**: 10 minutes + +--- + +### 4. Write Setup Instructions +**Description**: Provide step-by-step setup guide for new users. + +**Steps**: +1. Write setup steps: + - Step 1: Install Claude Code + - Step 2: Create working directory (e.g., "my-applications") + - Step 3: Copy src/ directory contents to working directory + - Step 4: Navigate to working directory in terminal + - Step 5: Fill out profile.md +2. Document profile setup shortcut: + - Create subdirectory (e.g., "documents/") + - Add existing CV, certificates, portfolio + - Prompt Claude to help populate profile from documents +3. Provide example commands for each step + +**Validation**: New user can follow instructions without prior knowledge + +**Estimated effort**: 25 minutes + +--- + +### 5. Create Quick Start Guide +**Description**: Provide condensed guide for experienced users or second-time usage. + +**Steps**: +1. Write minimal quick start sequence: + ```bash + # 1. Setup + cp -r src/* my-applications/ + cd my-applications/ + # Edit profile.md + + # 2. Create application + /new-application "Company - Job Title" + + # 3. Add job posting to input/ + + # 4. Generate documents + /populate-application + /write-cover-letter + /convert-cover-letter + /write-application-email + ``` +2. Note assumptions (Claude Code installed, terminal familiarity) + +**Validation**: Experienced user can complete workflow quickly + +**Estimated effort**: 15 minutes + +--- + +### 6. Document Complete Workflow +**Description**: Provide detailed end-to-end workflow with explanations. + +**Steps**: +1. Document step-by-step workflow: + - Step 0: Validate profile (`/validate-profile`) + - Step 1: Create application (`/new-application "Company - Role"`) + - Step 2: Add job posting/documents to input/ + - Step 3: Populate application (`/populate-application`) + - Step 4: Review and refine application.md + - Step 5: Validate application (`/validate-application`) + - Step 6: Generate cover letter (`/write-cover-letter`) + - Step 7: Review cover-letter.md + - Step 8: Convert to PDF (`/convert-cover-letter`) + - Step 9: Add CV and cover letter PDF to attachments/ + - Step 10: Generate email (`/write-application-email`) + - Step 11: Review and send +2. Add brief explanation for each step +3. Note which steps are optional or can be repeated + +**Validation**: Workflow matches implemented features and actual usage patterns + +**Estimated effort**: 30 minutes + +--- + +### 7. Create Commands Reference +**Description**: Document all implemented slash commands with usage examples. + +**Steps**: +1. Document each command with: + - Command name + - Description + - Syntax/parameters + - Example usage + - Common flags +2. Commands to document: + - `/validate-profile` + - `/new-application "Company - Job Title"` + - `/populate-application` + - `/validate-application [optional-app-name]` + - `/write-cover-letter [optional-app-name] [--skip-validation] [--force]` + - `/convert-cover-letter` + - `/write-application-email [optional-app-name] [--skip-validation] [--force]` +3. Use realistic examples (e.g., "TechCorp - Senior Developer") + +**Validation**: All commands in src/.claude/commands/ are documented + +**Estimated effort**: 30 minutes + +--- + +### 8. Document Directory Structure +**Description**: Explain the directory layout users will work with. + +**Steps**: +1. Create visual directory tree example: + ``` + my-applications/ + ├── profile.md + ├── CLAUDE.md + ├── .claude/ + │ ├── commands/ + │ └── templates/ + └── applications/ + └── pending/ + └── 2025-11-10-Company-Role/ + ├── application.md + ├── input/ + ├── cover-letter.md + ├── application-email.md + └── attachments/ + ``` +2. Explain purpose of each key file/folder: + - profile.md: Personal and professional information + - CLAUDE.md: AI assistant instructions + - .claude/: Framework commands and templates + - applications/pending/: Active applications + - input/: Job postings and research materials + - attachments/: Final PDFs to send + +**Validation**: Structure reflects actual directory layout after setup + +**Estimated effort**: 20 minutes + +--- + +### 9. Add Troubleshooting Section (Optional) +**Description**: Document common issues and solutions. + +**Steps**: +1. Add troubleshooting section (if helpful) +2. Document common issues: + - Profile validation failures → run `/validate-profile` + - PDF conversion issues → check Pandoc/LaTeX installation + - Missing documents → verify attachments/ folder contents +3. Keep concise - detailed troubleshooting is in CLAUDE.md for AI + +**Validation**: Troubleshooting addresses most common user issues + +**Estimated effort**: 15 minutes + +--- + +### 10. Add Maintenance and Best Practices +**Description**: Provide guidance on keeping the framework useful over time. + +**Steps**: +1. Document profile maintenance: + - Update profile.md after new projects, certifications, roles + - Keeps generated documents accurate and current +2. Note best practices: + - Review generated documents before sending + - Personalize AI-generated content + - Keep input/ folder organized with relevant documents +3. Framework updates: + - Note that src/ contains framework source + - Updates can be applied by selectively copying updated files + +**Validation**: Users understand ongoing maintenance requirements + +**Estimated effort**: 10 minutes + +--- + +### 11. Add Examples and Use Cases +**Description**: Provide concrete examples that illustrate usage. + +**Steps**: +1. Create example scenario: + - User applying to "TechCorp - Senior Developer" position + - Show command sequence with actual parameters + - Show example file contents where helpful +2. Maintain consistent example throughout README +3. Use realistic but generic company names + +**Validation**: Examples are clear and illustrate actual usage patterns + +**Estimated effort**: 20 minutes + +--- + +### 12. Proofread and Validate +**Description**: Review documentation for accuracy, clarity, and completeness. + +**Steps**: +1. Read through entire README as if you're a new user +2. Verify all commands exist in src/.claude/commands/ +3. Check that no unimplemented features are documented +4. Verify all code snippets are accurate +5. Check markdown formatting renders correctly +6. Ensure consistent tone and voice +7. Fix typos and grammatical errors + +**Validation**: +- No references to unimplemented features +- All commands are accurate +- Documentation is clear and actionable + +**Estimated effort**: 20 minutes + +--- + +## Dependencies +- None (documentation only, no code dependencies) + +## Verification Checklist +- [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. + +## Notes +- Focus on user needs, not developer needs +- Keep language clear and jargon-free +- Use examples liberally +- Prioritize clarity over comprehensiveness +- The goal is to enable new users to successfully use the framework