Bewerbungszauberer/openspec/changes/add-readme/tasks.md

# 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