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:

   # 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

• 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

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