fixed path

Archived completed OpenSpec change after successful deployment.
The template path fix has been applied to specs and is now in production.

Change archived as: 2026-01-12-fix-coverletter-template-path

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

.agent/workflows/openspec-apply.md

@@ -0,0 +1,20 @@
+---
+description: Implement an approved OpenSpec change and keep tasks in sync.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+Track these steps as TODOs and complete them one by one.
+1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
+2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
+3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
+4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality.
+5. Reference `openspec list` or `openspec show <item>` when additional context is required.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
+<!-- OPENSPEC:END -->

.agent/workflows/openspec-archive.md

@@ -0,0 +1,24 @@
+---
+description: Archive a deployed OpenSpec change and update specs.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+1. Determine the change ID to archive:
+   - If this prompt already includes a specific change ID (for example inside a `<ChangeId>` block populated by slash-command arguments), use that value after trimming whitespace.
+   - If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
+   - Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
+   - If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
+2. Validate the change ID by running `openspec list` (or `openspec show <id>`) and stop if the change is missing, already archived, or otherwise not ready to archive.
+3. Run `openspec archive <id> --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work).
+4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`.
+5. Validate with `openspec validate --strict` and inspect with `openspec show <id>` if anything looks off.
+
+**Reference**
+- Use `openspec list` to confirm change IDs before archiving.
+- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off.
+<!-- OPENSPEC:END -->

.agent/workflows/openspec-proposal.md

@@ -0,0 +1,25 @@
+---
+description: Scaffold a new OpenSpec change and validate strictly.
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
+- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.
+
+**Steps**
+1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.
+2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`.
+3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
+4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
+5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant.
+6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
+7. Validate with `openspec validate <id> --strict` and resolve every issue before sharing the proposal.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails.
+- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones.
+- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
+<!-- OPENSPEC:END -->

.claude/commands/openspec/proposal.md

@@ -10,6 +10,7 @@ tags: [openspec, change]
 - Keep changes tightly scoped to the requested outcome.
 - Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
 - Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
+- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.
 
 **Steps**
 1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.

.gitattributes

@@ -0,0 +1,3 @@
+# Do not consider Markdown files documentation anymore for
+# the Documentation!
+src/**/*.md -linguist-documentation

.gitignore

@@ -0,0 +1 @@
+applications

AGENTS.md

@@ -16,3 +16,91 @@ Use `@/openspec/AGENTS.md` to learn:
 Keep this managed block so 'openspec update' can refresh the instructions.
 
 <!-- OPENSPEC:END -->
+
+---
+
+# Updating the Test Framework
+
+## ⚠️ CRITICAL: Preserve User Data During Updates
+
+When updating the test framework at `~/workspace/test-bewerbungen/`, you MUST preserve user data files. **NEVER** use `cp -r src/* ~/workspace/test-bewerbungen/` as this overwrites everything including user work.
+
+## Protected Files & Folders
+
+**NEVER overwrite these in the test directory:**
+- `profile.md` - Contains user's personal and professional information
+- `applications/` folder - Contains all job application work in progress
+- Any PDF files - User's CVs, certificates, or job-related documents
+- Any user-created files or modifications
+
+## Safe Update Process
+
+### Method 1: Selective File Update (Recommended)
+
+Update only framework code files, preserving user data:
+
+```bash
+# Update main instruction file
+cp src/CLAUDE.md ~/workspace/test-bewerbungen/
+
+# Update slash commands and templates
+cp -r src/.claude ~/workspace/test-bewerbungen/
+
+# ONLY create applications directory if it doesn't exist
+# (don't overwrite existing one with user's applications)
+if [ ! -d ~/workspace/test-bewerbungen/applications ]; then
+  mkdir -p ~/workspace/test-bewerbungen/applications/pending
+fi
+```
+
+### Method 2: Manual Selective Copy
+
+For more control, copy specific files individually:
+
+```bash
+# Framework instructions
+cp src/CLAUDE.md ~/workspace/test-bewerbungen/
+
+# Slash commands
+cp src/.claude/commands/new-application.md ~/workspace/test-bewerbungen/.claude/commands/
+cp src/.claude/commands/populate-application.md ~/workspace/test-bewerbungen/.claude/commands/
+cp src/.claude/commands/validate-profile.md ~/workspace/test-bewerbungen/.claude/commands/
+
+# Templates
+cp src/.claude/templates/application-template.md ~/workspace/test-bewerbungen/.claude/templates/
+```
+
+### ❌ NEVER Use These Commands on Test Directory
+
+```bash
+# DANGEROUS - Overwrites everything including user data
+cp -r src/* ~/workspace/test-bewerbungen/
+
+# DANGEROUS - Overwrites user's profile
+cp src/profile.md ~/workspace/test-bewerbungen/
+
+# DANGEROUS - Deletes user's applications
+rm -rf ~/workspace/test-bewerbungen/applications/
+```
+
+## When to Update Test Framework
+
+Update the test directory when:
+- Adding new slash commands to `src/.claude/commands/`
+- Modifying the application template in `src/.claude/templates/`
+- Updating framework instructions in `src/CLAUDE.md`
+- Fixing bugs in command logic
+
+**Do NOT update** `profile.md` or touch the `applications/` folder - these belong to the user.
+
+## Workflow Summary
+
+1. **Make changes** to framework files in `src/`
+2. **Test locally** in development environment first
+3. **Selectively copy** only framework files to test directory
+4. **Verify** user data (`profile.md`, `applications/`) remains intact
+5. **Test** the updated commands in the test environment
+
+---
+
+**Remember**: The test directory simulates a real user's environment. Treat user data with care!

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.
+

openspec/AGENTS.md

@@ -160,6 +160,8 @@ New request?
 
 2. **Write proposal.md:**
 ```markdown
+# Change: [Brief description of change]
+
 ## Why
 [1-2 sentences on problem/opportunity]
 

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

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)

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

openspec/changes/archive-applications/design.md

@@ -0,0 +1,549 @@
+# Design Document: Application Archiving
+
+## Overview
+
+This document captures the technical design decisions and architectural considerations for implementing the application archiving feature.
+
+## Design Principles
+
+### 1. Follow Existing Patterns
+
+**Principle:** The archive command should follow established patterns from existing commands.
+
+**Rationale:**
+- Consistency in user experience
+- Easier maintenance and understanding
+- Leverages proven patterns from `write-cover-letter.md` and `write-application-email.md`
+
+**Application:**
+- Command file structure: Markdown with procedural instructions for Claude Code
+- Argument parsing: Position-based with optional parameters and flags
+- Error handling: Clear, actionable error messages with examples
+- Validation: Check inputs before performing operations
+
+### 2. Safety First
+
+**Principle:** Protect user work by detecting and warning about generated documents.
+
+**Rationale:**
+- Users may invest significant time in cover letters and emails
+- Accidental archiving of work-in-progress could be frustrating
+- Better to err on the side of caution
+
+**Application:**
+- Detect: `cover-letter.md`, `application-email.md`, files in `attachments/`
+- Warn: Show detailed message listing all detected work
+- Require: Explicit `--force` flag to bypass warnings
+- Preserve: All files during move (nothing is deleted)
+
+### 3. Minimal Metadata Updates
+
+**Principle:** Update only what's necessary, preserve everything else.
+
+**Rationale:**
+- Reduce risk of data corruption
+- Simple updates are easier to verify and rollback
+- Users may have customized other fields
+
+**Application:**
+- Only modify: Status field in Metadata section
+- Format: `- **Status**: [State] (Archived: YYYY-MM-DD HH:MM)`
+- Preserve: All other content in `application.md`
+- Rollback: If move fails, don't update status
+
+### 4. On-Demand Creation
+
+**Principle:** Create archive folders only when needed.
+
+**Rationale:**
+- Avoid cluttering file system with empty folders
+- Simpler initial setup (no migration needed)
+- Users who don't use archiving don't see archive folders
+
+**Application:**
+- Check: Does `applications/rejected/` exist?
+- Create: Only if first time archiving with "rejected"
+- Same: For `applications/not-interested/`
+- Track: In git with `.gitkeep` if desired
+
+## Technical Architecture
+
+### Command Flow
+
+```
+User Input: /archive-application [reason] [app-name] [--force]
+                      ↓
+        ┌─────────────────────────┐
+        │ 1. Parse Arguments      │
+        │  - Extract reason       │
+        │  - Extract app name     │
+        │  - Check for --force    │
+        └──────────┬──────────────┘
+                   ↓
+        ┌─────────────────────────┐
+        │ 2. Validate Inputs      │
+        │  - Reason is valid?     │
+        │  - App exists?          │
+        └──────────┬──────────────┘
+                   ↓
+        ┌─────────────────────────┐
+        │ 3. Detect Location      │
+        │  - Current dir?         │
+        │  - Or resolve path      │
+        └──────────┬──────────────┘
+                   ↓
+        ┌─────────────────────────┐
+        │ 4. Safety Checks        │
+        │  - Cover letter?        │
+        │  - Email?               │
+        │  - Attachments?         │
+        └──────────┬──────────────┘
+                   ↓
+          ┌────────┴────────┐
+          │ Documents found? │
+          └────────┬────────┘
+                   │
+         Yes ┌─────┴─────┐ No
+             ↓           ↓
+    ┌──────────────┐   ┌──────────────┐
+    │ --force set? │   │ 5. Update    │
+    └──────┬───────┘   │    Status    │
+           │           └──────┬───────┘
+    Yes ┌──┴──┐ No            ↓
+        ↓     ↓        ┌──────────────┐
+        │   STOP       │ 6. Create    │
+        │   (warn)     │    Archive   │
+        ↓              │    Folder    │
+  ┌──────────────┐    └──────┬───────┘
+  │ 5. Update    │           ↓
+  │    Status    │    ┌──────────────┐
+  └──────┬───────┘    │ 7. Move      │
+         ↓            │    Folder    │
+  ┌──────────────┐    └──────┬───────┘
+  │ 6. Create    │           ↓
+  │    Archive   │    ┌──────────────┐
+  │    Folder    │    │ 8. Verify    │
+  └──────┬───────┘    │    Success   │
+         ↓            └──────┬───────┘
+  ┌──────────────┐           ↓
+  │ 7. Move      │    ┌──────────────┐
+  │    Folder    │    │ 9. Confirm   │
+  └──────┬───────┘    │    Message   │
+         ↓            └──────────────┘
+  ┌──────────────┐
+  │ 8. Verify    │
+  │    Success   │
+  └──────┬───────┘
+         ↓
+  ┌──────────────┐
+  │ 9. Confirm   │
+  │    Message   │
+  └──────────────┘
+```
+
+### Data Flow
+
+```
+Input: applications/pending/2025-11-02-TechCorp-Developer/
+                      ↓
+        ┌─────────────────────────┐
+        │ Read application.md     │
+        │ Current Status: Draft   │
+        └──────────┬──────────────┘
+                   ↓
+        ┌─────────────────────────┐
+        │ Update in Memory        │
+        │ New Status: Rejected    │
+        │ Timestamp: 2025-12-18   │
+        └──────────┬──────────────┘
+                   ↓
+        ┌─────────────────────────┐
+        │ Write Back to File      │
+        │ application.md updated  │
+        └──────────┬──────────────┘
+                   ↓
+        ┌─────────────────────────┐
+        │ Move Entire Folder      │
+        │ Including updated file  │
+        └──────────┬──────────────┘
+                   ↓
+Output: applications/rejected/2025-11-02-TechCorp-Developer/
+```
+
+### File System Operations
+
+```bash
+# 1. Status Update (before move)
+cd applications/pending/[folder]/
+cat application.md | sed 's/- \*\*Status\*\*:.*/- **Status**: Rejected (Archived: 2025-12-18 15:30)/' > application.md.tmp
+mv application.md.tmp application.md
+
+# 2. Create Archive Directory (if needed)
+mkdir -p applications/rejected/
+
+# 3. Move Application
+mv applications/pending/[folder]/ applications/rejected/[folder]/
+
+# 4. Verify
+test -d applications/rejected/[folder]/ && echo "Success"
+test ! -d applications/pending/[folder]/ && echo "Source removed"
+```
+
+## Key Design Decisions
+
+### Decision 1: Status Update Timing
+
+**Options:**
+- A) Update status BEFORE moving folder
+- B) Update status AFTER moving folder
+- C) Update status IN PLACE after moving
+
+**Chosen:** Option A - Update status BEFORE moving
+
+**Rationale:**
+- Easier to rollback if move fails (just revert file)
+- Status update is atomic operation (less likely to fail)
+- If update fails, we stop early (don't move)
+- Move operation is riskier, so do simpler operation first
+
+**Trade-offs:**
+- If move fails, status is updated but folder isn't moved
+- User sees "Rejected" status in pending folder
+- Mitigation: Show clear error, user can fix status or retry move
+
+### Decision 2: Safety Check Scope
+
+**Options:**
+- A) Only check for generated documents (cover-letter.md, application-email.md)
+- B) Check for any modifications to application.md
+- C) Check for generated documents + attachments folder
+- D) No safety checks, always allow archiving
+
+**Chosen:** Option C - Generated documents + attachments
+
+**Rationale:**
+- Generated documents represent significant work
+- Attachments likely contain CV and certificates
+- Checking application.md changes is too broad (may be auto-populated)
+- Some safety is better than none, but not overly restrictive
+
+**Trade-offs:**
+- Users can still accidentally archive applications with manual edits to application.md
+- Acceptable: application.md is easier to recreate than generated documents
+
+### Decision 3: Archive Folder Naming
+
+**Options:**
+- A) `rejected/` and `not-interested/`
+- B) `archived-rejected/` and `archived-not-interested/`
+- C) `archive/rejected/` and `archive/not-interested/`
+- D) `rejected/` and `withdrawn/`
+
+**Chosen:** Option A - `rejected/` and `not-interested/`
+
+**Rationale:**
+- Short, clear folder names
+- "rejected" clearly indicates company rejected
+- "not-interested" clearly indicates user withdrew
+- No redundant "archived" prefix (location implies archived)
+- Consistent with user's original request
+
+**Trade-offs:**
+- "not-interested" is verbose compared to "withdrawn"
+- Acceptable: clarity over brevity
+
+### Decision 4: Auto-Detection Scope
+
+**Options:**
+- A) Only detect if in exact application folder
+- B) Detect from application folder or subfolders
+- C) Detect from anywhere in pending folder tree
+- D) No auto-detection, always require application name
+
+**Chosen:** Option B - Application folder or subfolders
+
+**Rationale:**
+- Users may be in `input/` or `attachments/` when deciding to archive
+- Detecting parent folder is user-friendly
+- Not too broad (don't detect from root or pending folder itself)
+- Matches pattern from other commands
+
+**Trade-offs:**
+- Slightly more complex path resolution logic
+- Acceptable: improves user experience
+
+### Decision 5: Error Handling Strategy
+
+**Options:**
+- A) Fail fast, stop on first error
+- B) Try to proceed, show warnings
+- C) Rollback on any error
+- D) Partial success allowed (e.g., move but don't update status)
+
+**Chosen:** Option A - Fail fast with Option C rollback on critical errors
+
+**Rationale:**
+- Validate all inputs BEFORE making changes
+- Stop early if anything is wrong
+- Rollback status update if move fails (critical path)
+- Allow partial success only for non-critical operations (e.g., Timeline update)
+
+**Trade-offs:**
+- Less forgiving for edge cases
+- Acceptable: better to stop and fix than proceed with errors
+
+## Component Responsibilities
+
+### Command File (`archive-application.md`)
+
+**Responsibilities:**
+- Parse and validate command arguments
+- Detect application location
+- Perform safety checks
+- Update Status field
+- Create archive directory
+- Move application folder
+- Verify success
+- Show confirmation message
+
+**NOT Responsible For:**
+- Modifying other files besides application.md
+- Validating application completeness (separate concern)
+- Tracking archived applications (future enhancement)
+- Providing archive search (future enhancement)
+
+### Framework Documentation (`CLAUDE.md`)
+
+**Responsibilities:**
+- Explain when and how to use archiving
+- Document command syntax
+- Describe safety features
+- Show integration with workflow
+
+**NOT Responsible For:**
+- Implementation details (that's in command file)
+- Specification (that's in OpenSpec)
+
+### Specifications (`application-archiving/spec.md`)
+
+**Responsibilities:**
+- Define requirements with scenarios
+- Document expected behaviors
+- Specify error handling
+- Define integration points
+
+**NOT Responsible For:**
+- Implementation approach (that's in command file)
+- User-facing documentation (that's in CLAUDE.md)
+
+## Integration Points
+
+### With Existing Commands
+
+```
+/new-application
+    ↓ creates
+application.md (with Status: Draft)
+    ↓ populated by
+/populate-application
+    ↓ validated by
+/validate-application
+    ↓ generates
+/write-cover-letter → cover-letter.md
+    ↓ generates
+/write-application-email → application-email.md
+    ↓ user sends
+(Application submitted)
+    ↓ archives
+/archive-application → moves to rejected/ or not-interested/
+```
+
+### With File System
+
+```
+File System Operations:
+- Read: application.md (for current status)
+- Write: application.md (to update status)
+- Check: cover-letter.md, application-email.md, attachments/*
+- Create: applications/rejected/, applications/not-interested/
+- Move: applications/pending/[folder]/ → applications/[reason]/[folder]/
+- Verify: Destination exists, source removed
+```
+
+### With User Workflow
+
+```
+User Decision Points:
+1. Should I archive? → User decides based on application outcome
+2. Which reason? → rejected (company) or not-interested (user)
+3. Force or not? → If documents exist, user decides to proceed or cancel
+4. Where is it? → User can check archive folders if needed
+```
+
+## Performance Considerations
+
+### Operation Speed
+
+**Status update:**
+- Fast: Read/write single text file
+- ~10-50ms typical
+
+**Safety checks:**
+- Fast: Check file existence (no content reading)
+- ~5-20ms per file
+
+**Folder move:**
+- Fast: On same filesystem, just updates directory entries
+- ~10-100ms typical
+- Slow: On different filesystems, copies all files
+- ~1-10s depending on file count and size
+
+**Total typical time:** < 1 second
+
+### Resource Usage
+
+**Memory:**
+- Minimal: Read/write application.md (~5-20KB)
+- No large file operations or in-memory copies
+
+**Disk I/O:**
+- Light: Status update (one file write)
+- Moderate: Folder move (directory metadata updates)
+- Heavy: Only if moving across filesystems (full copy)
+
+**Optimization:**
+- Not needed for typical use case
+- Could add progress indicator for large attachments folders
+
+## Security Considerations
+
+### File System Access
+
+**Concerns:**
+- User must have write permissions on pending/ and archive folders
+- Must be able to modify application.md
+- Must be able to move folders
+
+**Mitigations:**
+- Check permissions before attempting operations
+- Clear error messages if permissions denied
+- No privilege escalation or dangerous operations
+
+### Data Preservation
+
+**Concerns:**
+- Accidental data loss if move fails partway
+- Status update without successful move
+
+**Mitigations:**
+- Verify move succeeded before confirming
+- Rollback status if move fails
+- Never delete source until verified at destination
+- Safety warnings for generated documents
+
+### Path Traversal
+
+**Concerns:**
+- User could provide application name like "../../../etc"
+- Could try to move folders outside applications/
+
+**Mitigations:**
+- Validate application name is valid folder in pending/
+- Resolve full paths and check they're within applications/
+- No user-provided target paths (only reason parameter)
+
+## Testing Strategy
+
+### Unit-Level Testing
+
+**Test each component:**
+- Argument parsing (valid/invalid inputs)
+- Location detection (current dir vs. explicit name)
+- Safety checks (detect documents correctly)
+- Status update (find and replace correctly)
+- Folder move (succeed and rollback)
+
+### Integration Testing
+
+**Test command flow:**
+- End-to-end archiving (from pending to rejected)
+- End-to-end with safety checks
+- Error scenarios (not found, invalid reason, etc.)
+
+### Edge Case Testing
+
+**Test unusual scenarios:**
+- Missing Status field (add it)
+- Empty attachments folder (don't warn)
+- Re-archiving (error appropriately)
+- Concurrent access (handle gracefully)
+
+### Manual Testing
+
+**User acceptance:**
+- Run through complete workflow
+- Verify intuitive behavior
+- Check error messages are clear
+- Confirm success messages are helpful
+
+## Future Considerations
+
+### Extensibility
+
+**Easy to add later:**
+- Additional archive reasons (accepted, on-hold, etc.)
+- Archive search and listing commands
+- Bulk archiving operations
+- Archive statistics and reporting
+
+**Design supports:**
+- Parameterized reason (easy to add new values)
+- Consistent folder structure (easy to extend)
+- Status field format (can add more states)
+
+### Scalability
+
+**Current design:**
+- Handles dozens to hundreds of applications fine
+- Linear search in pending folder (acceptable scale)
+- File system operations are efficient
+
+**If needed later:**
+- Index of archived applications
+- Database for faster searches
+- Bulk operations for managing many archives
+
+### Maintenance
+
+**Design for maintainability:**
+- Follows existing command patterns
+- Clear separation of concerns
+- Well-documented in code and specs
+- Testable components
+
+**Future updates:**
+- Easy to modify error messages
+- Easy to add new safety checks
+- Easy to extend with new features
+- Easy to update status field format
+
+## Summary
+
+The archiving feature is designed to:
+- ✅ Follow established patterns for consistency
+- ✅ Protect user work with safety checks
+- ✅ Minimize changes to existing files
+- ✅ Create resources on-demand
+- ✅ Integrate naturally with existing workflow
+- ✅ Handle errors gracefully with clear messages
+- ✅ Support future enhancements
+
+**Complexity:** Low to moderate
+**Risk:** Low (additive feature, no breaking changes)
+**Maintenance:** Low (follows patterns, well-documented)
+**User Impact:** High (solves real organizational need)
+
+---
+
+**Design Status:** Complete and ready for implementation
+**Next Steps:** Review proposal, implement according to tasks.md

openspec/changes/archive-applications/proposal.md

@@ -0,0 +1,709 @@
+# Proposal: Archive Applications
+
+## Change ID
+`archive-applications`
+
+## Summary
+Add the ability to archive unsuccessful job applications by moving them from `applications/pending/` to organized archive folders (`applications/rejected/` or `applications/not-interested/`). The system will update application metadata and warn users before archiving applications with generated documents.
+
+## Problem Statement
+
+Users currently have no structured way to organize completed or unsuccessful applications. All applications remain in the `applications/pending/` folder indefinitely, making it difficult to:
+
+1. Distinguish between active and inactive applications
+2. Organize applications by outcome (rejected by company vs. user withdrew)
+3. Keep the pending folder clean and focused on current opportunities
+4. Track the lifecycle of applications from creation to completion
+
+## Proposed Solution
+
+Introduce a `/archive-application` command that:
+
+1. Moves applications from `applications/pending/` to outcome-specific folders:
+   - `applications/rejected/` - Company rejected the application
+   - `applications/not-interested/` - User decided not to pursue
+
+2. Updates application metadata:
+   - Modifies the Status field in `application.md` with timestamp
+   - Preserves all application work (documents, input files, attachments)
+
+3. Protects user work:
+   - Detects generated documents (cover letters, emails, attachments)
+   - Warns before archiving and requires explicit `--force` flag
+   - Prevents accidental loss of significant work
+
+4. Provides flexible usage:
+   - Auto-detects application when run from within application folder
+   - Accepts application name parameter when run from any location
+   - Supports help flag for usage information
+
+## User Requirements
+
+Based on user clarification during proposal phase:
+
+- ✅ **Metadata update**: Move files AND update Status field with timestamp
+- ✅ **Command design**: Single command with parameter: `/archive-application [reason]`
+- ✅ **Safety checks**: Warn if documents exist, require `--force` to proceed
+- ✅ **Scope**: Only rejection paths (`rejected` and `not-interested`) for now
+
+## Success Criteria
+
+After implementation, users should be able to:
+
+1. Archive applications from within the application folder
+2. Archive applications by name from any location
+3. Receive warnings before archiving applications with work invested
+4. See updated Status field with timestamp after archiving
+5. Find archived applications in organized folders by reason
+6. Use `--force` to skip safety checks when confident
+
+## Command Interface
+
+### Syntax
+
+```bash
+/archive-application [reason] [application-name] [--force]
+```
+
+### Parameters
+
+- **reason** (required): Either `rejected` or `not-interested`
+  - `rejected` - Company rejected the application
+  - `not-interested` - User decided to withdraw or not pursue further
+
+- **application-name** (optional): Application folder name
+  - If omitted: Auto-detect from current working directory
+  - If provided: Resolve to full path in pending folder
+
+- **--force** (flag): Skip safety warnings about generated documents
+
+### Examples
+
+```bash
+# From within application folder
+cd applications/pending/2025-11-02-TechCorp-Developer/
+/archive-application rejected
+
+# From anywhere with application name
+/archive-application rejected 2025-11-02-TechCorp-Developer
+
+# Skip safety checks
+/archive-application not-interested --force
+
+# Get help
+/archive-application --help
+```
+
+## Folder Structure
+
+### Before
+```
+src/applications/
+└── pending/
+    ├── 2025-11-02-TechCorp-Developer/
+    ├── 2025-11-05-StartupCo-Engineer/
+    └── 2025-11-10-BigCorp-Lead/
+```
+
+### After
+```
+src/applications/
+├── pending/
+│   └── 2025-11-10-BigCorp-Lead/          # Still active
+├── rejected/
+│   └── 2025-11-02-TechCorp-Developer/     # Company rejected
+└── not-interested/
+    └── 2025-11-05-StartupCo-Engineer/     # User withdrew
+```
+
+Applications maintain their original folder name (`YYYY-MM-DD-Company-JobTitle/`) when moved.
+
+## Archiving Process
+
+### Step-by-Step Flow
+
+1. **Parse & Validate**
+   - Extract reason parameter (rejected/not-interested)
+   - Extract optional application name and flags
+   - Validate reason is one of the allowed values
+
+2. **Location Detection**
+   - If no application name: Check if running from within an application folder
+   - If application name: Resolve to full path in pending folder
+   - Verify `application.md` exists
+
+3. **Safety Check** (unless `--force`)
+   - Check for `cover-letter.md` in application folder
+   - Check for `application-email.md` in application folder
+   - Check for files in `attachments/` folder (excluding `.keep`)
+   - If ANY found: Show warning and require `--force` to proceed
+
+4. **Update Metadata**
+   - Read `application.md`
+   - Find Status field in Metadata section: `- **Status**: Draft`
+   - Replace with: `- **Status**: Rejected (Archived: 2025-12-18 15:30)` OR `- **Status**: Not Interested (Archived: 2025-12-18 15:30)`
+   - Write back to file
+
+5. **Create Archive Directory**
+   - Create `applications/rejected/` or `applications/not-interested/` if doesn't exist
+
+6. **Move Application**
+   - Execute: `mv applications/pending/[folder]/ applications/[reason]/[folder]/`
+   - Verify move succeeded (destination exists, source removed)
+
+7. **Confirm Success**
+   - Show success message with archive details
+   - Include original and new locations
+   - Display updated status
+
+### Safety Warning Example
+
+```
+⚠️  Warning: Generated documents detected
+
+This application contains work that may be lost:
+- cover-letter.md (exists)
+- application-email.md (exists)
+- attachments/ folder (3 files)
+
+Archiving will move everything to the archive folder, but these documents
+suggest you may have put significant work into this application.
+
+Options:
+1. Continue archiving anyway: /archive-application rejected --force
+2. Cancel and review the documents first
+3. Export/backup documents before archiving
+
+Are you sure you want to archive this application?
+```
+
+**System behavior**: STOP and require `--force` flag to proceed.
+
+## Technical Implementation
+
+### Status Field Update
+
+**Current format (in template):**
+```markdown
+- **Status**: Draft
+```
+
+**After archiving (rejected):**
+```markdown
+- **Status**: Rejected (Archived: 2025-12-18 15:30)
+```
+
+**After archiving (not-interested):**
+```markdown
+- **Status**: Not Interested (Archived: 2025-12-18 15:30)
+```
+
+**Implementation approach:**
+1. Read entire `application.md` file
+2. Find line matching pattern: `^(\s*-\s*\*\*Status\*\*:\s*)(.*)$`
+3. Replace entire line with new status and timestamp
+4. Write back to file
+
+**Timestamp format:** `YYYY-MM-DD HH:MM` (ISO-style date, 24-hour time)
+
+### Safety Check Logic
+
+**Detection criteria:**
+```bash
+# Check for generated documents
+test -f cover-letter.md          # Cover letter exists
+test -f application-email.md     # Email exists
+ls attachments/ | grep -v '\.keep' | wc -l > 0   # Has attachments besides .keep
+```
+
+**Warning trigger:**
+- ANY of: cover-letter.md exists, application-email.md exists, attachments count > 0
+
+**Bypass:**
+- Provide `--force` flag to skip all safety checks
+
+### Auto-Detection Pattern
+
+**When no application name provided:**
+1. Get current working directory
+2. Check if path matches: `*/applications/pending/[folder-name]/`
+3. Verify `application.md` exists in current directory
+4. Extract folder name for use in move operation
+
+**When application name provided:**
+1. Resolve to full path: `applications/pending/[provided-name]/`
+2. Verify folder exists
+3. Verify `application.md` exists
+
+## Error Handling
+
+### Error Scenarios
+
+1. **Invalid reason**
+   ```
+   ❌ Invalid reason: [provided-reason]
+
+   Reason must be one of:
+   - rejected: Company rejected the application
+   - not-interested: User withdrew or not pursuing
+
+   Usage: /archive-application [reason] [application-name]
+   ```
+
+2. **Application not found**
+   ```
+   ❌ Application not found: [application-name]
+
+   Available applications in pending:
+   [List folders in applications/pending/]
+
+   Usage: /archive-application [reason] [application-name]
+   ```
+
+3. **Not in application folder**
+   ```
+   ❌ Not in an application folder
+
+   Please either:
+   1. Navigate to an application folder:
+      cd applications/pending/[application-folder]/
+      /archive-application [reason]
+
+   2. Or provide the application folder name:
+      /archive-application [reason] [application-folder-name]
+
+   Available applications:
+   [List folders in applications/pending/]
+   ```
+
+4. **Already archived**
+   ```
+   ❌ Application not found in pending folder
+
+   The application "[folder-name]" doesn't exist in applications/pending/.
+
+   Did you already archive it? Check:
+   - applications/rejected/
+   - applications/not-interested/
+
+   To move between archives, use mv command directly.
+   ```
+
+5. **File operation failure**
+   ```
+   ❌ Failed to archive application
+
+   Error: [specific error message]
+
+   Possible causes:
+   - Insufficient permissions
+   - File system full
+   - Application folder is open in another program
+
+   Please check the issue and try again.
+   The application has NOT been modified.
+   ```
+
+6. **Status update failure**
+   ```
+   ⚠️  Application moved but status update failed
+
+   The application was moved to:
+   applications/[reason]/[folder-name]/
+
+   However, the Status field in application.md could not be updated.
+   Please manually update: - **Status**: [Rejected/Not Interested] (Archived: [date])
+
+   Error: [specific error details]
+   ```
+
+## Edge Cases
+
+### Handled Edge Cases
+
+1. **Partially generated application**
+   - User created cover letter but not email
+   - **Handling:** Warn - any generated document is significant work
+
+2. **Empty attachments folder**
+   - `attachments/` exists but only contains `.keep` file
+   - **Handling:** Don't count as "having attachments" - no warning
+
+3. **Re-archiving**
+   - User tries to archive application already in rejected folder
+   - **Handling:** Error message suggesting application already archived
+
+4. **Missing Status field**
+   - Old `application.md` doesn't have Status field in Metadata section
+   - **Handling:** Add Status field to Metadata section, then proceed
+
+5. **Permission errors**
+   - Can't write to `application.md` or can't move folder
+   - **Handling:** Rollback any changes, show clear error, leave in pending
+
+6. **Concurrent operations**
+   - User has application open in editor while archiving
+   - **Handling:** File system will handle, may fail - show appropriate error
+
+## Integration Points
+
+### With Existing Workflow
+
+The archiving feature integrates at the end of the application lifecycle:
+
+```
+Current workflow:
+1. Create: /new-application "Company - Job Title"
+2. Populate: /populate-application
+3. Validate: /validate-application
+4. Generate: /write-cover-letter
+5. Generate: /write-application-email
+6. Send: (User sends application via email client)
+
+NEW:
+7. Archive: /archive-application [reason]  ← NEW STEP
+```
+
+### With Application States
+
+**Application lifecycle states:**
+
+- **Draft** - Created, not yet populated (in `pending/`)
+- **In Progress** - Being worked on, documents generated (in `pending/`)
+- **Submitted** - Sent to company, awaiting response (in `pending/`)
+- **Rejected** - Company rejected (in `rejected/`)
+- **Not Interested** - User withdrew (in `not-interested/`)
+
+**Status field tracking:**
+- `application.md` Metadata section maintains current state
+- Archive operation updates state with timestamp
+- State history is preserved in Timeline section
+
+### With Documentation
+
+**Updates needed to `src/CLAUDE.md`:**
+
+1. Add new section: "Archiving Applications" (~40 lines)
+   - Explain archiving workflow
+   - Show command syntax and examples
+   - Describe safety checks
+   - Document archive folder structure
+
+2. Update "Available Commands" list
+   - Add `/archive-application` with parameters and flags
+
+3. Update workflow examples
+   - Include archiving as final step in lifecycle
+
+## Dependencies
+
+### File Dependencies
+
+**Required existing files:**
+- `applications/pending/` - Source folder for active applications
+- `application.md` - Must exist in each application folder
+- `src/CLAUDE.md` - Framework instructions to update
+
+**Created files:**
+- `applications/rejected/` - Created on-demand when first needed
+- `applications/not-interested/` - Created on-demand when first needed
+
+### Command Dependencies
+
+**No hard dependencies on other commands**, but archiving is typically the last step after:
+- `/new-application` - Creates the application
+- `/populate-application` - Populates strategy
+- `/write-cover-letter` - Generates cover letter
+- `/write-application-email` - Generates email
+
+**Users can archive at any stage** (even immediately after creation if they change their mind).
+
+## Testing Considerations
+
+### Test Scenarios
+
+1. **Basic archiving from within application folder**
+   - No generated documents
+   - Should succeed without warnings
+
+2. **Archiving with application name parameter**
+   - From any location
+   - Should resolve path and succeed
+
+3. **Safety check with cover letter**
+   - Generated cover-letter.md exists
+   - Should warn and require --force
+
+4. **Safety check with attachments**
+   - Files exist in attachments/ folder
+   - Should warn and require --force
+
+5. **Force flag bypasses warnings**
+   - Use --force with generated documents
+   - Should proceed without warnings
+
+6. **Invalid reason parameter**
+   - Provide unsupported reason (e.g., "accepted")
+   - Should error with valid options
+
+7. **Application not found**
+   - Provide non-existent application name
+   - Should error with available applications list
+
+8. **Wrong directory without parameter**
+   - Run from root without application name
+   - Should error with usage guidance
+
+9. **Create rejected folder for first time**
+   - First time archiving with "rejected" reason
+   - Should create applications/rejected/ folder
+
+10. **Multiple applications to same folder**
+    - Archive multiple applications as rejected
+    - Should handle without conflicts
+
+11. **Status field update verification**
+    - Check application.md after archiving
+    - Should have updated Status with timestamp
+
+12. **Missing Status field**
+    - Archive old application without Status field
+    - Should add field before archiving
+
+## Backwards Compatibility
+
+### Compatibility Analysis
+
+**No breaking changes:**
+- Existing applications in `pending/` folder are unaffected
+- Archive folders are created on-demand
+- Status field already exists in current template (line 12)
+- No changes to existing command behavior
+- No changes to folder structure for pending applications
+
+**Forwards compatible:**
+- Old applications can be archived (Status field added if missing)
+- New applications will work with archiving from day one
+- Archive folders follow same naming convention as pending
+
+**Migration:** None required - feature works with existing applications as-is
+
+## Alternatives Considered
+
+### Alternative 1: Separate Commands for Each Reason
+
+**Approach:** Create `/reject-application` and `/withdraw-application` commands
+
+**Pros:**
+- More intuitive command names
+- Clearer user intent
+- Better discoverability (separate help for each)
+
+**Cons:**
+- Code duplication (same logic in two commands)
+- More commands to maintain
+- Harder to add new archive reasons later
+
+**Decision:** Rejected in favor of single parameterized command based on user preference
+
+### Alternative 2: Just Move Files (No Metadata Update)
+
+**Approach:** Simple file move without updating `application.md`
+
+**Pros:**
+- Simpler implementation
+- Faster execution
+- Less chance of file corruption
+
+**Cons:**
+- Lose tracking of when and why archived
+- Status field becomes outdated
+- No audit trail of archival
+
+**Decision:** Rejected - metadata update provides valuable tracking
+
+### Alternative 3: Always Allow Archiving (No Safety Checks)
+
+**Approach:** Skip all warnings, just move files
+
+**Pros:**
+- Faster for experienced users
+- No interruptions
+- Simpler implementation
+
+**Cons:**
+- Risk of accidentally archiving significant work
+- No protection against mistakes
+- Harder to recover from accidents
+
+**Decision:** Rejected - safety checks prevent data loss and frustration
+
+### Alternative 4: Add `accepted` Folder Immediately
+
+**Approach:** Include `applications/accepted/` from the start
+
+**Pros:**
+- Complete lifecycle coverage
+- Users can track successful applications
+- More comprehensive solution
+
+**Cons:**
+- Scope creep beyond user request
+- Different use case (accepted apps are managed differently)
+- Can add later if needed
+
+**Decision:** Rejected - focus on user's current need (rejection paths)
+
+## Future Enhancements
+
+Not included in this proposal but could be added in future changes:
+
+1. **Accepted archive** - `applications/accepted/` folder for successful applications
+2. **Unarchive command** - `/unarchive-application` to move back to pending
+3. **List archived** - `/list-archived` command to browse archives by reason
+4. **Archive statistics** - Show counts of applications by outcome
+5. **Archive search** - Find applications in archives by company or date
+6. **Bulk operations** - Archive multiple applications at once
+7. **Archive notes** - Add custom notes when archiving (why rejected, lessons learned)
+8. **Expiration/cleanup** - Auto-delete archived applications older than X months
+9. **Export archive** - Export archived applications to external format (CSV, JSON)
+10. **Timeline tracking** - Add "Archived" entry to Timeline section in `application.md`
+
+## Risks and Mitigations
+
+### Risk 1: Accidental Data Loss
+
+**Risk:** Users accidentally archive applications with significant work
+
+**Likelihood:** Medium (users may not realize they have generated documents)
+
+**Impact:** High (loss of cover letters, emails, strategy work)
+
+**Mitigation:**
+- Implement safety checks that detect generated documents
+- Require explicit `--force` flag to bypass warnings
+- Show detailed warning listing all documents that would be archived
+- Preserve all files during move (nothing is deleted)
+
+### Risk 2: File System Errors
+
+**Risk:** Move operation fails due to permissions, disk space, or concurrent access
+
+**Likelihood:** Low (most systems handle file operations reliably)
+
+**Impact:** Medium (application left in inconsistent state)
+
+**Mitigation:**
+- Check permissions before attempting move
+- Verify destination doesn't already exist
+- Rollback metadata changes if move fails
+- Show clear error messages with troubleshooting steps
+- Never delete source until move is verified
+
+### Risk 3: Status Update Failures
+
+**Risk:** Status field update fails but files are moved
+
+**Likelihood:** Low (text file updates usually succeed)
+
+**Impact:** Low (application is archived, just metadata is stale)
+
+**Mitigation:**
+- Update status BEFORE moving files (easier to recover)
+- If update fails, stop and don't move
+- If move succeeds but status fails, warn user but don't rollback
+- Provide manual update instructions in error message
+
+### Risk 4: User Confusion About Archive Locations
+
+**Risk:** Users can't find archived applications after moving them
+
+**Likelihood:** Medium (users may forget where they archived)
+
+**Impact:** Low (applications are still accessible, just in different folder)
+
+**Mitigation:**
+- Show clear success message with new location
+- Use intuitive folder names (rejected, not-interested)
+- Document archive structure in CLAUDE.md
+- Consider future enhancement: `/list-archived` command
+
+### Risk 5: Archive Folder Clutter
+
+**Risk:** Archive folders become cluttered with many old applications
+
+**Likelihood:** High (over time, many applications will be archived)
+
+**Impact:** Low (just organizational issue, doesn't affect functionality)
+
+**Mitigation:**
+- Maintain date prefix in folder names for chronological sorting
+- Document folder structure in CLAUDE.md
+- Consider future enhancement: expiration/cleanup policy
+- Consider future enhancement: archive search functionality
+
+## Implementation Approach
+
+### Phase 1: Core Command (Priority 1)
+
+1. Create command file: `src/.claude/commands/archive-application.md`
+   - ~500-700 lines procedural instructions
+   - Follow pattern from `write-cover-letter.md`
+   - Include all validation, safety checks, error handling
+
+2. Update framework docs: `src/CLAUDE.md`
+   - Add "Archiving Applications" section
+   - Update "Available Commands" list
+   - Include workflow integration examples
+
+### Phase 2: Specifications (Priority 1)
+
+3. Create OpenSpec spec: `openspec/specs/application-archiving/spec.md`
+   - Formal requirements with scenarios
+   - Document all behaviors and edge cases
+
+4. Update existing spec: `openspec/specs/application-management/spec.md`
+   - Add lifecycle management requirement
+   - Document application states
+
+### Phase 3: Testing & Validation (Priority 2)
+
+5. Manual testing of all scenarios
+6. Verification of error handling
+7. Documentation review for clarity
+
+### Phase 4: Optional Enhancements (Priority 3)
+
+8. Consider adding Timeline section updates
+9. Consider archive listing functionality
+10. Consider unarchive command
+
+## Approval Checklist
+
+Before implementation begins, verify:
+
+- [ ] User has confirmed archiving approach (move + metadata update)
+- [ ] Command syntax is clear and intuitive
+- [ ] Safety check behavior is acceptable
+- [ ] Archive folder structure makes sense
+- [ ] Error handling covers common scenarios
+- [ ] Integration with existing workflow is smooth
+- [ ] OpenSpec proposal follows project conventions
+- [ ] No breaking changes to existing functionality
+
+## Success Metrics
+
+After implementation, measure success by:
+
+1. **Functionality**: Users can successfully archive applications
+2. **Safety**: No reports of accidental data loss
+3. **Usability**: Users understand command syntax without extensive documentation
+4. **Integration**: Command fits naturally into existing workflow
+5. **Maintenance**: Command follows established patterns, easy to maintain
+
+---
+
+**Status:** Proposal draft ready for review
+**Change ID:** archive-applications
+**Estimated Effort:** Medium (1-2 hours implementation)
+**Risk Level:** Low (non-breaking, additive feature)

openspec/changes/archive-applications/specs/application-archiving/spec.md

@@ -0,0 +1,377 @@
+# application-archiving Specification
+
+## Purpose
+Provide a structured way to archive job applications that are no longer active, maintaining organization and preserving all application work. This capability enables users to move applications from `applications/pending/` to outcome-specific folders (`rejected`, `not-interested`) with metadata updates and safety protections.
+
+## ADDED Requirements
+
+### Requirement: Application Archiving Command
+
+The system SHALL provide a `/archive-application` command that moves applications from pending to archive folders with metadata updates.
+
+#### Scenario: Archive rejected application from current directory
+
+- **WHEN** user navigates to `applications/pending/[folder]/` and runs `/archive-application rejected`
+- **THEN** system detects current application automatically
+- **AND** moves application folder from `applications/pending/` to `applications/rejected/`
+- **AND** updates Status field to "Rejected (Archived: [timestamp])"
+- **AND** preserves all files and folders (application.md, input/, attachments/)
+- **AND** shows success message with archive location
+
+#### Scenario: Archive not-interested application by name
+
+- **WHEN** user runs `/archive-application not-interested 2025-11-02-TechCorp-Developer` from any location
+- **THEN** system resolves application path in pending folder
+- **AND** moves application to `applications/not-interested/`
+- **AND** updates Status field to "Not Interested (Archived: [timestamp])"
+- **AND** shows success message with original and new locations
+
+#### Scenario: Display help information
+
+- **WHEN** user runs `/archive-application --help`
+- **THEN** system displays command syntax and usage information
+- **AND** explains parameters (reason, application-name, flags)
+- **AND** provides examples for common scenarios
+- **AND** describes what happens during archiving
+
+#### Scenario: Validate reason parameter
+
+- **WHEN** user provides invalid reason (not "rejected" or "not-interested")
+- **THEN** system shows error message listing valid reasons
+- **AND** displays usage information
+- **AND** does NOT modify any files
+
+#### Scenario: Resolve application location
+
+- **WHEN** user provides application name without full path
+- **THEN** system searches `applications/pending/` for matching folder
+- **AND** resolves to full path if found
+- **AND** shows error if application not found
+- **AND** lists available applications in pending folder
+
+---
+
+### Requirement: Safety Warnings for Generated Documents
+
+The system SHALL warn users before archiving applications with generated documents to prevent accidental loss of work.
+
+#### Scenario: Detect and warn about cover letter
+
+- **WHEN** application folder contains `cover-letter.md`
+- **THEN** system displays warning message
+- **AND** lists cover-letter.md as generated document
+- **AND** stops archiving process
+- **AND** requires `--force` flag to proceed
+
+#### Scenario: Detect and warn about application email
+
+- **WHEN** application folder contains `application-email.md`
+- **THEN** system displays warning message
+- **AND** lists application-email.md as generated document
+- **AND** stops archiving process
+- **AND** requires `--force` flag to proceed
+
+#### Scenario: Detect and warn about attachments
+
+- **WHEN** `attachments/` folder contains files (excluding `.keep`)
+- **THEN** system displays warning message
+- **AND** shows count of files in attachments folder
+- **AND** stops archiving process
+- **AND** requires `--force` flag to proceed
+
+#### Scenario: Warning message provides clear options
+
+- **WHEN** safety warning is displayed
+- **THEN** message lists all detected documents
+- **AND** explains that archiving will move everything
+- **AND** provides three options: continue with --force, cancel to review, or backup first
+- **AND** shows exact command to use with --force flag
+
+#### Scenario: Force flag bypasses all warnings
+
+- **WHEN** user provides `--force` flag
+- **THEN** system skips all safety checks
+- **AND** proceeds with archiving without warnings
+- **AND** shows brief notice that --force was used
+- **AND** completes archiving successfully
+
+#### Scenario: No warning for empty attachments folder
+
+- **WHEN** `attachments/` folder exists but only contains `.keep` file
+- **THEN** system does NOT treat this as "having attachments"
+- **AND** does NOT display warning about attachments
+- **AND** proceeds with archiving (if no other documents found)
+
+---
+
+### Requirement: Status and Timestamp Tracking
+
+The system SHALL update application metadata when archiving to maintain audit trail and lifecycle tracking.
+
+#### Scenario: Update Status field for rejected application
+
+- **WHEN** application is archived with reason "rejected"
+- **THEN** system reads `application.md` file
+- **AND** locates Status field in Metadata section
+- **AND** replaces Status line with: `- **Status**: Rejected (Archived: YYYY-MM-DD HH:MM)`
+- **AND** writes updated content back to file
+- **AND** preserves all other content in application.md
+
+#### Scenario: Update Status field for not-interested application
+
+- **WHEN** application is archived with reason "not-interested"
+- **THEN** system reads `application.md` file
+- **AND** locates Status field in Metadata section
+- **AND** replaces Status line with: `- **Status**: Not Interested (Archived: YYYY-MM-DD HH:MM)`
+- **AND** writes updated content back to file
+- **AND** preserves all other content in application.md
+
+#### Scenario: Handle missing Status field
+
+- **WHEN** application.md does not have Status field in Metadata section
+- **THEN** system adds Status field to Metadata section
+- **AND** sets Status to appropriate archived value with timestamp
+- **AND** preserves existing Metadata section formatting
+- **AND** proceeds with archiving
+
+#### Scenario: Timestamp format
+
+- **WHEN** Status field is updated with timestamp
+- **THEN** timestamp follows format: YYYY-MM-DD HH:MM
+- **AND** uses current date and time at moment of archiving
+- **AND** uses 24-hour time format
+- **AND** is human-readable and sortable
+
+#### Scenario: Status update failure handling
+
+- **WHEN** Status field update fails (file locked, permissions error)
+- **THEN** system stops archiving process
+- **AND** shows error message with details
+- **AND** does NOT move application folder
+- **AND** leaves application in pending folder unchanged
+
+---
+
+### Requirement: Archive Folder Structure
+
+The system SHALL maintain organized archive folders by reason while preserving application structure.
+
+#### Scenario: Create rejected archive folder on first use
+
+- **WHEN** user archives first application with reason "rejected"
+- **AND** `applications/rejected/` folder does not exist
+- **THEN** system creates `applications/rejected/` directory
+- **AND** shows progress message: "Created archive directory: applications/rejected/"
+- **AND** proceeds with archiving to new folder
+
+#### Scenario: Create not-interested archive folder on first use
+
+- **WHEN** user archives first application with reason "not-interested"
+- **AND** `applications/not-interested/` folder does not exist
+- **THEN** system creates `applications/not-interested/` directory
+- **AND** shows progress message: "Created archive directory: applications/not-interested/"
+- **AND** proceeds with archiving to new folder
+
+#### Scenario: Preserve folder naming convention
+
+- **WHEN** application is moved to archive
+- **THEN** folder name remains unchanged (YYYY-MM-DD-Company-JobTitle format)
+- **AND** application is placed in `applications/[reason]/[original-folder-name]/`
+- **AND** date prefix is preserved for chronological sorting
+
+#### Scenario: Preserve application structure
+
+- **WHEN** application folder is moved to archive
+- **THEN** all subfolders are preserved (input/, attachments/)
+- **AND** all files are preserved (application.md, cover-letter.md, application-email.md)
+- **AND** folder structure remains identical to pending folder structure
+- **AND** no files are modified except application.md Status field
+
+#### Scenario: Verify successful move
+
+- **WHEN** move operation completes
+- **THEN** system verifies destination folder exists: `applications/[reason]/[folder]/`
+- **AND** verifies source folder no longer exists: `applications/pending/[folder]/`
+- **AND** verifies application.md exists at destination
+- **AND** only shows success message after verification passes
+
+---
+
+### Requirement: Comprehensive Error Handling
+
+The system SHALL provide clear, actionable error messages for all failure scenarios.
+
+#### Scenario: Invalid reason parameter error
+
+- **WHEN** user provides unsupported reason (not "rejected" or "not-interested")
+- **THEN** system displays error message: "Invalid reason: [provided-reason]"
+- **AND** lists valid options: rejected, not-interested
+- **AND** explains what each reason means
+- **AND** shows usage syntax
+
+#### Scenario: Application not found error
+
+- **WHEN** user provides application name that doesn't exist in pending
+- **THEN** system displays error message: "Application not found: [application-name]"
+- **AND** lists all available applications in `applications/pending/`
+- **AND** shows usage syntax with application name parameter
+
+#### Scenario: Not in application folder error
+
+- **WHEN** user runs command without application name parameter
+- **AND** current directory is not within an application folder
+- **THEN** system displays error message: "Not in an application folder"
+- **AND** explains two options: navigate to application folder, or provide application name
+- **AND** lists available applications in pending folder
+- **AND** shows example commands for both approaches
+
+#### Scenario: Already archived error
+
+- **WHEN** user tries to archive application that doesn't exist in pending
+- **THEN** system displays error message: "Application not found in pending folder"
+- **AND** suggests checking archive folders (rejected/, not-interested/)
+- **AND** explains how to move between archives if needed
+- **AND** does NOT show pending applications list (not relevant)
+
+#### Scenario: File operation failure error
+
+- **WHEN** move operation fails (permissions, disk space, concurrent access)
+- **THEN** system displays error message: "Failed to archive application"
+- **AND** includes specific error details from file system
+- **AND** lists possible causes (permissions, disk space, file in use)
+- **AND** confirms: "The application has NOT been modified"
+- **AND** suggests checking the issue and trying again
+
+#### Scenario: Permission denied error
+
+- **WHEN** user lacks permissions to write to application.md or move folder
+- **THEN** system displays error about insufficient permissions
+- **AND** explains which operation failed (status update or folder move)
+- **AND** suggests checking file/folder permissions
+- **AND** ensures no partial changes (rollback any modifications)
+
+---
+
+### Requirement: Auto-Detection of Application Location
+
+The system SHALL automatically detect the target application when run from within an application folder.
+
+#### Scenario: Detect application from current directory
+
+- **WHEN** user is in directory matching pattern `*/applications/pending/[folder-name]/`
+- **AND** current directory contains `application.md` file
+- **THEN** system automatically detects application to archive
+- **AND** extracts folder name for use in move operation
+- **AND** does NOT require application name parameter
+
+#### Scenario: Verify application.md exists
+
+- **WHEN** system detects application from current directory
+- **THEN** system verifies `application.md` file exists
+- **AND** shows error if application.md missing
+- **AND** explains that directory doesn't appear to be valid application folder
+
+#### Scenario: Handle subdirectories within application
+
+- **WHEN** user is in subdirectory like `*/applications/pending/[folder]/input/`
+- **THEN** system detects parent application folder
+- **AND** resolves to correct application path
+- **AND** proceeds with archiving parent application
+
+#### Scenario: Explicit name overrides auto-detection
+
+- **WHEN** user provides application name parameter
+- **THEN** system uses provided name instead of auto-detecting
+- **AND** ignores current directory location
+- **AND** resolves to specified application in pending folder
+
+---
+
+### Requirement: Success Messaging and Confirmation
+
+The system SHALL provide clear confirmation when archiving succeeds with relevant details.
+
+#### Scenario: Display success message with details
+
+- **WHEN** archiving completes successfully
+- **THEN** system displays success message: "Application archived successfully"
+- **AND** shows application name (Company - Job Title)
+- **AND** shows original location: `applications/pending/[folder]/`
+- **AND** shows archived location: `applications/[reason]/[folder]/`
+- **AND** shows reason: "Rejected by company" or "No longer interested"
+- **AND** shows updated Status: "Rejected (Archived: [timestamp])"
+
+#### Scenario: Confirm preservation of all files
+
+- **WHEN** success message is displayed
+- **THEN** message confirms: "All documents intact"
+- **AND** explains application can still be accessed at new location
+- **AND** provides full path to archived application
+
+#### Scenario: Success with --force flag
+
+- **WHEN** archiving completes with --force flag
+- **THEN** success message includes note: "Safety checks skipped (--force)"
+- **AND** lists which documents were detected but bypassed
+- **AND** confirms all documents were moved to archive
+
+---
+
+## Cross-References
+
+### Related Capabilities
+
+- **application-management**: Archiving is the final step in application lifecycle
+- **application-validation**: Validation ensures applications are complete before potential archiving
+- **cover-letter-generation**: Generated cover letters trigger safety warnings when archiving
+- **application-email**: Generated emails trigger safety warnings when archiving
+
+### Integration Points
+
+- Status field in `application.md` (managed by application-management)
+- Application folder structure (defined by application-management)
+- Generated document detection (cover-letter.md, application-email.md)
+- Attachments folder (created by application-management)
+
+---
+
+## Technical Notes
+
+### Status Field Update Implementation
+
+**Pattern matching:**
+```regex
+^(\s*-\s*\*\*Status\*\*:\s*)(.*)$
+```
+
+**Replacement format:**
+```markdown
+- **Status**: [Rejected|Not Interested] (Archived: YYYY-MM-DD HH:MM)
+```
+
+### Safety Check Detection
+
+**Files to check:**
+1. `cover-letter.md` in application folder
+2. `application-email.md` in application folder
+3. Any files in `attachments/` excluding `.keep`
+
+**Warning triggered if ANY found**
+
+### Archive Folder Paths
+
+- Rejected: `src/applications/rejected/`
+- Not interested: `src/applications/not-interested/`
+
+**Folders created on-demand when first needed**
+
+---
+
+## Validation
+
+This specification can be validated by:
+
+1. Running `openspec validate archive-applications --strict`
+2. Verifying all requirements have at least one scenario
+3. Checking all scenarios follow WHEN/THEN/AND format
+4. Confirming no placeholder text remains in requirements

openspec/changes/archive-applications/specs/application-management/spec.md

@@ -0,0 +1,197 @@
+# application-management Specification Delta
+
+## Purpose
+Document updates to application-management capability to include lifecycle management and archival support.
+
+## ADDED Requirements
+
+### Requirement: Application Lifecycle Management
+
+The system SHALL support the complete lifecycle of applications from creation through archival with clear state tracking.
+
+#### Scenario: Application progresses through lifecycle states
+
+- **WHEN** application is created with `/new-application`
+- **THEN** Status is set to "Draft" in Metadata section
+- **AND** application is stored in `applications/pending/` folder
+- **WHEN** application is archived with `/archive-application rejected`
+- **THEN** Status is updated to "Rejected (Archived: [timestamp])"
+- **AND** application is moved to `applications/rejected/` folder
+- **WHEN** application is archived with `/archive-application not-interested`
+- **THEN** Status is updated to "Not Interested (Archived: [timestamp])"
+- **AND** application is moved to `applications/not-interested/` folder
+
+#### Scenario: Folder organization reflects application state
+
+- **WHEN** viewing applications directory structure
+- **THEN** active applications are in `applications/pending/`
+- **AND** rejected applications are in `applications/rejected/`
+- **AND** withdrawn applications are in `applications/not-interested/`
+- **AND** all folders use same naming convention (YYYY-MM-DD-Company-JobTitle)
+
+#### Scenario: Status field tracks current state
+
+- **WHEN** application exists in any folder
+- **THEN** application.md contains Status field in Metadata section
+- **AND** Status field accurately reflects current lifecycle state
+- **AND** Archived states include timestamp of archival
+- **AND** Status field format is: `- **Status**: [State] (Archived: [timestamp])`
+
+#### Scenario: Application structure preserved across lifecycle
+
+- **WHEN** application moves between lifecycle states
+- **THEN** all files are preserved (application.md, generated documents)
+- **AND** all folders are preserved (input/, attachments/)
+- **AND** folder name remains unchanged
+- **AND** only Status field in Metadata section is modified
+
+---
+
+### Requirement: Archive Folder Support
+
+The system SHALL provide dedicated folders for archived applications organized by outcome.
+
+#### Scenario: Rejected applications folder
+
+- **WHEN** application is rejected by company
+- **THEN** application is moved to `applications/rejected/` folder
+- **AND** folder is created if it doesn't already exist
+- **AND** folder contains applications rejected by companies
+
+#### Scenario: Not-interested applications folder
+
+- **WHEN** user decides not to pursue application
+- **THEN** application is moved to `applications/not-interested/` folder
+- **AND** folder is created if it doesn't already exist
+- **AND** folder contains applications user withdrew from
+
+#### Scenario: Archive folders maintain chronological organization
+
+- **WHEN** multiple applications are archived
+- **THEN** date prefix (YYYY-MM-DD) allows chronological sorting
+- **AND** folders can be easily browsed by date
+- **AND** organization matches pending folder structure
+
+---
+
+### Requirement: Status Field Management
+
+The system SHALL maintain accurate Status field in application.md throughout lifecycle.
+
+#### Scenario: Status field exists in template
+
+- **WHEN** new application is created from template
+- **THEN** Metadata section includes Status field
+- **AND** Status field is formatted: `- **Status**: Draft`
+- **AND** Status field is on line 12 of application.md
+
+#### Scenario: Status field is preserved during population
+
+- **WHEN** `/populate-application` analyzes documents
+- **THEN** Status field in Metadata section is not modified
+- **AND** user can manually update Status as needed
+- **AND** Status field persists through multiple population runs
+
+#### Scenario: Status field is updated on archival
+
+- **WHEN** application is archived
+- **THEN** Status field is updated with new state and timestamp
+- **AND** old Status value is replaced (not appended)
+- **AND** timestamp format is consistent (YYYY-MM-DD HH:MM)
+
+---
+
+## MODIFIED Requirements
+
+### Requirement: Application Folder Structure
+
+The application folder structure SHALL include archive folders in addition to the pending folder for organizing applications by lifecycle state.
+
+#### Scenario: Complete folder hierarchy
+
+- **WHEN** application framework is in use
+- **THEN** folder structure is:
+  ```
+  applications/
+  ├── pending/              # Active applications
+  ├── rejected/             # Rejected by company
+  └── not-interested/       # User withdrew
+  ```
+- **AND** each folder contains application subfolders with format: `YYYY-MM-DD-Company-JobTitle/`
+- **AND** archive folders are created on-demand when first needed
+
+---
+
+## Cross-References
+
+### Related Capabilities
+
+- **application-archiving** (NEW): Provides `/archive-application` command for moving applications to archive folders
+- **applicant-profile**: Profile information is preserved in archived applications for future reference
+- **cover-letter-generation**: Generated cover letters trigger safety checks during archiving
+- **application-email**: Generated emails trigger safety checks during archiving
+- **application-validation**: Validation ensures applications are complete, but archived applications may be incomplete
+
+### Integration Points
+
+- Archive folders created by `application-archiving` capability
+- Status field updated by `application-archiving` capability
+- Application folder structure maintained by both capabilities
+- Generated document detection shared between capabilities
+
+---
+
+## Technical Notes
+
+### Lifecycle State Diagram
+
+```
+[Created] ──/new-application──> [Draft (pending/)]
+                                      │
+                                      ├──(user works on application)
+                                      ├──/populate-application
+                                      ├──/validate-application
+                                      ├──/write-cover-letter
+                                      ├──/write-application-email
+                                      ├──(user submits application)
+                                      │
+                                      ├──/archive-application rejected
+                                      │   └─> [Rejected (rejected/)]
+                                      │
+                                      └──/archive-application not-interested
+                                          └─> [Not Interested (not-interested/)]
+```
+
+### Status Field Values
+
+- **Draft**: Initial state, application being prepared
+- **Rejected (Archived: [timestamp])**: Company rejected application
+- **Not Interested (Archived: [timestamp])**: User decided not to pursue
+
+**Note**: Additional states may be used by user (e.g., "Submitted", "Interview Scheduled") but are not enforced by system.
+
+---
+
+## Backwards Compatibility
+
+**No breaking changes:**
+- Existing applications in `pending/` folder remain valid
+- Archive folders are optional and created on-demand
+- Status field already exists in template (line 12)
+- No changes to existing command behavior
+
+**Forward compatible:**
+- Old applications can be archived without modification
+- New applications work with archiving from creation
+- Archive structure supports future enhancements (e.g., accepted folder)
+
+---
+
+## Validation
+
+This specification delta can be validated by:
+
+1. Running `openspec validate archive-applications --strict`
+2. Verifying integration with application-archiving capability
+3. Checking that existing application-management requirements still apply
+4. Confirming no conflicts with other capabilities

openspec/changes/archive-applications/tasks.md

@@ -0,0 +1,397 @@
+# Implementation Tasks: Archive Applications
+
+## Overview
+
+This document outlines the ordered list of tasks to implement the application archiving feature. Tasks are designed to deliver user-visible progress incrementally with validation at each step.
+
+## Task Sequence
+
+### Task 1: Create Archive Application Command File
+
+**Description:** Create the main command implementation file with complete procedural instructions for Claude Code.
+
+**Actions:**
+1. Create file: `src/.claude/commands/archive-application.md`
+2. Follow pattern from `write-cover-letter.md` and `write-application-email.md`
+3. Include complete implementation logic in markdown format:
+   - Command purpose and overview
+   - Argument parsing (reason, application-name, flags)
+   - Location detection (auto-detect vs. explicit name)
+   - Safety checks for generated documents
+   - Status field update logic
+   - Directory creation
+   - File move operation
+   - Error handling for all scenarios
+   - Success messaging
+
+**Validation:**
+- [ ] File exists and follows command pattern
+- [ ] All scenarios from proposal are covered
+- [ ] Error handling is comprehensive
+- [ ] Help documentation is clear
+
+**Deliverable:** `src/.claude/commands/archive-application.md` (~500-700 lines)
+
+**Dependencies:** None
+
+---
+
+### Task 2: Update Framework Documentation
+
+**Description:** Update `CLAUDE.md` to include archiving in the framework workflow.
+
+**Actions:**
+1. Add new section "Archiving Applications" after "Application Management" section
+2. Include:
+   - When to archive applications
+   - Command syntax and examples
+   - Safety check explanation
+   - Archive folder structure
+   - Integration with workflow
+3. Update "Available Commands" list with `/archive-application`
+4. Add archiving to workflow examples
+
+**Validation:**
+- [ ] New section is clear and comprehensive
+- [ ] Commands list includes archive command
+- [ ] Examples are helpful and accurate
+- [ ] Integration with existing workflow is explained
+
+**Deliverable:** Updated `src/CLAUDE.md` (~40 lines added)
+
+**Dependencies:** Task 1 (understand command functionality)
+
+---
+
+### Task 3: Create Application Archiving Specification
+
+**Description:** Create formal OpenSpec specification for the archiving feature.
+
+**Actions:**
+1. Create directory: `openspec/specs/application-archiving/`
+2. Create file: `openspec/specs/application-archiving/spec.md`
+3. Include requirements with scenarios for:
+   - Application Archiving Command
+   - Safety Warnings for Generated Documents
+   - Status and Timestamp Tracking
+   - Archive Folder Structure
+4. Follow OpenSpec format: `## Requirements` → `### Requirement:` → `#### Scenario:`
+
+**Validation:**
+- [ ] All proposal behaviors are captured as requirements
+- [ ] Each requirement has clear scenarios
+- [ ] Scenarios follow WHEN/THEN/AND format
+- [ ] Spec validates with `openspec validate archive-applications`
+
+**Deliverable:** `openspec/specs/application-archiving/spec.md` (~150-200 lines)
+
+**Dependencies:** Task 1 (understand implementation details)
+
+---
+
+### Task 4: Update Application Management Specification
+
+**Description:** Update existing spec to document application lifecycle including archival.
+
+**Actions:**
+1. Open: `openspec/specs/application-management/spec.md`
+2. Add new requirement: "Application Lifecycle Management"
+3. Include scenarios for:
+   - Application states (Draft, Rejected, Not Interested)
+   - Folder organization by state (pending/, rejected/, not-interested/)
+   - Status field tracking through lifecycle
+
+**Validation:**
+- [ ] Lifecycle states are clearly defined
+- [ ] Folder organization is documented
+- [ ] Integration with existing requirements is clear
+- [ ] Spec validates with `openspec validate`
+
+**Deliverable:** Updated `openspec/specs/application-management/spec.md` (~30 lines added)
+
+**Dependencies:** Task 3 (understand new archiving spec)
+
+---
+
+### Task 5: Verify Template Status Field
+
+**Description:** Verify that the application template has the Status field required for archiving.
+
+**Actions:**
+1. Open: `src/.claude/templates/application-template.md`
+2. Verify line 12 contains: `- **Status**: Draft`
+3. Verify Status field is in Metadata section
+4. Document finding (no changes needed if field exists)
+
+**Validation:**
+- [ ] Status field exists at line 12
+- [ ] Field is in correct format: `- **Status**: Draft`
+- [ ] Field is within Metadata section
+- [ ] No changes needed (field already present)
+
+**Deliverable:** Verification confirmation (no file changes)
+
+**Dependencies:** None (verification task)
+
+---
+
+### Task 6: Create Archive Folders (Test Setup)
+
+**Description:** Create initial archive folder structure for testing purposes.
+
+**Actions:**
+1. Create directory: `src/applications/rejected/`
+2. Create directory: `src/applications/not-interested/`
+3. Add `.gitkeep` files to preserve empty directories in version control
+
+**Validation:**
+- [ ] `src/applications/rejected/` exists
+- [ ] `src/applications/not-interested/` exists
+- [ ] Both directories are tracked in git
+- [ ] Directories are ready for archiving operations
+
+**Deliverable:** Archive folder structure
+
+**Dependencies:** None
+
+**Note:** These folders will be created on-demand by the command, but creating them upfront ensures they're tracked in version control.
+
+---
+
+### Task 7: Manual Testing - Basic Archiving
+
+**Description:** Test basic archiving functionality with simple application.
+
+**Test Cases:**
+1. Create test application: `/new-application "TestCo - Test Role"`
+2. Navigate to application folder
+3. Run: `/archive-application rejected`
+4. Verify:
+   - Application moved to `applications/rejected/`
+   - Status field updated with timestamp
+   - All files preserved (application.md, input/, attachments/)
+
+**Validation:**
+- [ ] Application successfully moved
+- [ ] Status field shows: `Rejected (Archived: [timestamp])`
+- [ ] All folders and files intact
+- [ ] Success message shows correct details
+
+**Deliverable:** Test results documentation
+
+**Dependencies:** Tasks 1-2 (command implementation and docs)
+
+---
+
+### Task 8: Manual Testing - Safety Checks
+
+**Description:** Test safety warning functionality with generated documents.
+
+**Test Cases:**
+1. Create test application with cover letter and email
+2. Run: `/archive-application rejected` (without --force)
+3. Verify warning message appears
+4. Verify archiving is blocked
+5. Run: `/archive-application rejected --force`
+6. Verify archiving proceeds
+
+**Validation:**
+- [ ] Warning appears when documents detected
+- [ ] Warning lists all generated documents
+- [ ] Archiving stops without --force
+- [ ] --force flag bypasses warning
+- [ ] Documents are preserved in archive
+
+**Deliverable:** Test results documentation
+
+**Dependencies:** Task 7 (basic functionality working)
+
+---
+
+### Task 9: Manual Testing - Error Handling
+
+**Description:** Test error scenarios and messages.
+
+**Test Cases:**
+1. Invalid reason: `/archive-application accepted`
+2. Application not found: `/archive-application rejected NonExistent`
+3. Not in application folder: Run from root without parameter
+4. Already archived: Try to archive same application twice
+
+**Validation:**
+- [ ] Invalid reason shows correct error with valid options
+- [ ] Not found shows available applications
+- [ ] Wrong location shows usage guidance
+- [ ] Already archived shows helpful message
+- [ ] All error messages are clear and actionable
+
+**Deliverable:** Test results documentation
+
+**Dependencies:** Task 7 (basic functionality working)
+
+---
+
+### Task 10: Manual Testing - Auto-Detection
+
+**Description:** Test automatic application detection from current directory.
+
+**Test Cases:**
+1. Create test application
+2. Navigate INTO application folder: `cd applications/pending/[folder]/`
+3. Run: `/archive-application not-interested` (no app name)
+4. Verify correct application is detected and archived
+
+**Validation:**
+- [ ] Auto-detection identifies correct application
+- [ ] Archiving proceeds without application name parameter
+- [ ] Success message shows detected application name
+- [ ] Application moved to correct archive folder
+
+**Deliverable:** Test results documentation
+
+**Dependencies:** Task 7 (basic functionality working)
+
+---
+
+### Task 11: OpenSpec Validation
+
+**Description:** Validate all OpenSpec specifications are correctly formatted.
+
+**Actions:**
+1. Run: `openspec validate archive-applications --strict`
+2. Resolve any validation errors
+3. Run: `openspec validate` (validate entire project)
+4. Ensure all specs pass validation
+
+**Validation:**
+- [ ] `openspec validate archive-applications --strict` passes
+- [ ] No formatting errors in proposal.md
+- [ ] No formatting errors in spec files
+- [ ] All requirements have at least one scenario
+
+**Deliverable:** Clean validation results
+
+**Dependencies:** Tasks 3-4 (all specs created)
+
+---
+
+### Task 12: Documentation Review
+
+**Description:** Review all documentation for clarity, completeness, and accuracy.
+
+**Actions:**
+1. Review `proposal.md` for completeness
+2. Review `tasks.md` for task ordering and clarity
+3. Review `archive-application.md` command for user-friendliness
+4. Review `CLAUDE.md` updates for integration with existing docs
+5. Review spec files for requirement coverage
+
+**Validation:**
+- [ ] All documents are clear and well-organized
+- [ ] No ambiguous or confusing sections
+- [ ] Examples are helpful and accurate
+- [ ] Error messages are user-friendly
+- [ ] Integration with existing workflow is seamless
+
+**Deliverable:** Documentation review notes
+
+**Dependencies:** Tasks 1-4 (all documentation created)
+
+---
+
+### Task 13: Final Integration Check
+
+**Description:** Verify archiving integrates smoothly with existing application workflow.
+
+**Test Workflow:**
+1. Create complete application: `/new-application "FinalTest - Role"`
+2. Populate: `/populate-application` (with documents in input/)
+3. Validate: `/validate-application`
+4. Generate cover letter: `/write-cover-letter`
+5. Generate email: `/write-application-email`
+6. Archive: `/archive-application rejected`
+
+**Validation:**
+- [ ] All commands work in sequence
+- [ ] Safety warning appears (cover letter and email detected)
+- [ ] --force flag allows archiving
+- [ ] All generated documents preserved in archive
+- [ ] Workflow feels natural and intuitive
+
+**Deliverable:** End-to-end workflow validation
+
+**Dependencies:** All previous tasks (complete implementation)
+
+---
+
+## Task Summary
+
+| Task | Description | Priority | Est. Time | Dependencies |
+|------|-------------|----------|-----------|--------------|
+| 1 | Create archive command file | P1 | 60 min | None |
+| 2 | Update framework docs | P1 | 20 min | Task 1 |
+| 3 | Create archiving spec | P1 | 30 min | Task 1 |
+| 4 | Update management spec | P1 | 15 min | Task 3 |
+| 5 | Verify template status field | P2 | 5 min | None |
+| 6 | Create archive folders | P2 | 5 min | None |
+| 7 | Test basic archiving | P1 | 15 min | Tasks 1-2 |
+| 8 | Test safety checks | P1 | 15 min | Task 7 |
+| 9 | Test error handling | P1 | 15 min | Task 7 |
+| 10 | Test auto-detection | P2 | 10 min | Task 7 |
+| 11 | OpenSpec validation | P1 | 10 min | Tasks 3-4 |
+| 12 | Documentation review | P2 | 20 min | Tasks 1-4 |
+| 13 | Final integration check | P1 | 20 min | All tasks |
+
+**Total Estimated Time:** ~4 hours
+
+## Parallelization Opportunities
+
+Tasks that can be done in parallel:
+- Tasks 1, 5, 6 (independent)
+- Tasks 3, 4 (both specs, can work simultaneously)
+- Tasks 8, 9, 10 (all testing, can run concurrently)
+
+Critical path: Task 1 → Task 2 → Task 7 → Tasks 8-10 → Task 13
+
+## Validation Checklist
+
+After all tasks complete, verify:
+
+- [ ] `/archive-application` command works from within application folder
+- [ ] `/archive-application` command works with application name parameter
+- [ ] Safety warnings appear when documents exist
+- [ ] `--force` flag bypasses warnings
+- [ ] Status field is updated with correct timestamp
+- [ ] Applications move to correct archive folder
+- [ ] All files and folders are preserved
+- [ ] Error messages are clear and helpful
+- [ ] OpenSpec validation passes
+- [ ] Documentation is complete and accurate
+- [ ] Integration with existing workflow is seamless
+
+## Rollback Plan
+
+If issues arise during implementation:
+
+1. **Command not working**: Comment out command file, revert CLAUDE.md changes
+2. **Spec validation fails**: Fix spec formatting issues, re-validate
+3. **File corruption**: Archive operations preserve originals, can restore from archive
+4. **Integration issues**: Archive feature is additive, can be disabled without affecting other commands
+
+## Success Criteria
+
+Implementation is complete when:
+
+1. All tasks have passing validation
+2. OpenSpec validation passes with `--strict` flag
+3. All test scenarios pass
+4. Documentation is clear and complete
+5. Feature integrates smoothly with existing workflow
+6. No breaking changes to existing functionality
+
+---
+
+**Status:** Task list ready for implementation
+**Total Tasks:** 13
+**Estimated Time:** ~4 hours
+**Priority Distribution:** 9 P1, 4 P2

openspec/changes/archive/2025-11-03-add-cover-letter-pdf-conversion/proposal.md

@@ -0,0 +1,24 @@
+# Add Cover Letter PDF Conversion
+
+## Why
+
+The current system generates cover letters in markdown format, but many job applications require PDF submissions. This creates a gap in the workflow where users must manually convert their generated cover letters to PDF format using external tools. Adding native PDF conversion will complete the job application workflow by providing professionally formatted Swiss-style business letters ready for submission.
+
+## What Changes
+
+- Add new slash command `/convert-cover-letter` for converting markdown cover letters to PDF
+- Implement environment validation to check for required tools (Pandoc, LaTeX)
+- Create Swiss letter template (scrlttr2) with proper formatting for Swiss business correspondence
+- Support automatic extraction of metadata from markdown frontmatter (sender, recipient, date, subject, etc.)
+- Generate PDF output in the same directory as the markdown source
+- Provide helpful error messages and setup guidance when tools are missing
+
+## Impact
+
+- **Affected specs**: New capability `cover-letter-pdf-conversion`
+- **Affected code**:
+  - New slash command: `src/.claude/commands/convert-cover-letter.md`
+  - New LaTeX template: `src/.claude/templates/swiss-letter.tex`
+  - Test environment: Will need to update test directory with new command
+- **Dependencies**: Requires Pandoc and LaTeX (texlive-latex-base, texlive-lang-german) to be installed on the user's system
+- **User workflow**: Completes step 7 "Generate PDFs" in the project workflow (see project.md:51)

openspec/changes/archive/2025-11-03-add-cover-letter-pdf-conversion/specs/cover-letter-pdf-conversion/spec.md

@@ -0,0 +1,144 @@
+# Cover Letter PDF Conversion Specification
+
+## ADDED Requirements
+
+### Requirement: Cover Letter Detection
+
+The system SHALL detect the presence of a valid cover letter markdown file in the current directory before attempting conversion.
+
+#### Scenario: Valid cover letter found
+- **WHEN** a file named `cover-letter.md` exists in the current directory
+- **AND** the file contains valid markdown with frontmatter
+- **THEN** the system proceeds with conversion
+
+#### Scenario: No cover letter found
+- **WHEN** no `cover-letter.md` file exists in the current directory
+- **THEN** the system displays an error message indicating no cover letter was found
+- **AND** suggests running `/write-cover-letter` first
+
+#### Scenario: Invalid cover letter format
+- **WHEN** `cover-letter.md` exists but lacks required frontmatter fields
+- **THEN** the system displays an error listing the missing required fields
+- **AND** provides an example of correct frontmatter structure
+
+### Requirement: Environment Validation
+
+The system SHALL validate that all required tools are installed before attempting conversion.
+
+#### Scenario: All tools available
+- **WHEN** the user runs `/convert-cover-letter`
+- **AND** Pandoc is installed and accessible
+- **AND** LaTeX (pdflatex) is installed and accessible
+- **THEN** the system proceeds with conversion
+
+#### Scenario: Pandoc missing
+- **WHEN** the user runs `/convert-cover-letter`
+- **AND** Pandoc is not installed
+- **THEN** the system displays installation instructions for Pandoc
+- **AND** provides platform-specific commands (apt, brew, etc.)
+- **AND** stops the conversion process
+
+#### Scenario: LaTeX missing
+- **WHEN** the user runs `/convert-cover-letter`
+- **AND** Pandoc is installed but LaTeX is not installed
+- **THEN** the system displays installation instructions for LaTeX packages
+- **AND** lists required packages (texlive-latex-base, texlive-lang-german, texlive-latex-extra)
+- **AND** stops the conversion process
+
+### Requirement: Swiss Letter Formatting
+
+The system SHALL generate PDFs using Swiss business letter standards (scrlttr2 with SN configuration).
+
+#### Scenario: Address window positioning
+- **WHEN** converting a cover letter to PDF
+- **THEN** the recipient address is positioned according to Swiss Norm (SN)
+- **AND** fits within standard Swiss envelope window dimensions
+
+#### Scenario: Swiss German formatting
+- **WHEN** the cover letter content contains German text
+- **THEN** Swiss German hyphenation rules are applied
+- **AND** date formatting follows Swiss convention (DD.MM.YYYY)
+- **AND** number formatting uses Swiss conventions
+
+#### Scenario: Professional layout
+- **WHEN** converting to PDF
+- **THEN** the output includes proper margins for Swiss business letters
+- **AND** sender information is positioned in the header
+- **AND** contact information (phone, email) is formatted with hyperlinks
+
+### Requirement: Metadata Extraction
+
+The system SHALL extract metadata from markdown frontmatter and map it to LaTeX variables.
+
+#### Scenario: Complete frontmatter
+- **WHEN** the markdown contains all required frontmatter fields
+- **THEN** sender information (name, street, city, phone, email) is extracted
+- **AND** recipient address lines are extracted
+- **AND** letter details (date, subject, opening, closing, signature) are extracted
+- **AND** optional enclosures list is extracted if present
+
+#### Scenario: Minimal frontmatter
+- **WHEN** the markdown contains only required frontmatter fields
+- **THEN** the system uses default values for optional fields
+- **AND** generates a valid PDF without enclosures section
+
+#### Scenario: Invalid frontmatter structure
+- **WHEN** the frontmatter cannot be parsed as YAML
+- **THEN** the system displays a clear error message
+- **AND** points to the specific syntax error if possible
+
+### Requirement: PDF Generation
+
+The system SHALL convert the markdown body to PDF using Pandoc with the Swiss letter template.
+
+#### Scenario: Successful conversion
+- **WHEN** all prerequisites are met
+- **AND** the markdown is valid
+- **THEN** the system generates a PDF file in the same directory
+- **AND** names the file `cover-letter.pdf`
+- **AND** displays a success message with the file path
+
+#### Scenario: Conversion with enclosures
+- **WHEN** the frontmatter includes an `enclosures` list
+- **THEN** the generated PDF includes an enclosures section after the closing
+- **AND** lists each enclosure item on a separate line
+
+#### Scenario: LaTeX compilation error
+- **WHEN** Pandoc generates LaTeX but pdflatex fails to compile
+- **THEN** the system displays the LaTeX error output
+- **AND** suggests checking for special characters or formatting issues
+- **AND** preserves the intermediate .tex file for debugging
+
+### Requirement: Template Management
+
+The system SHALL provide and maintain the Swiss letter LaTeX template.
+
+#### Scenario: Template availability
+- **WHEN** the `/convert-cover-letter` command is run
+- **THEN** the system uses the template at `src/.claude/templates/swiss-letter.tex`
+- **AND** passes it to Pandoc via the `--template` option
+
+#### Scenario: Template customization
+- **WHEN** users need to modify letter styling
+- **THEN** they can edit the swiss-letter.tex template
+- **AND** changes apply to all subsequent conversions
+- **AND** the template includes comments explaining customizable sections
+
+### Requirement: Error Handling
+
+The system SHALL provide clear, actionable error messages for common failure scenarios.
+
+#### Scenario: File permission error
+- **WHEN** the PDF cannot be written due to permissions
+- **THEN** the system displays a permission error message
+- **AND** suggests checking directory write permissions
+
+#### Scenario: Disk space error
+- **WHEN** PDF generation fails due to insufficient disk space
+- **THEN** the system displays a disk space error
+- **AND** suggests freeing up space or choosing a different output location
+
+#### Scenario: Process timeout
+- **WHEN** LaTeX compilation takes longer than 30 seconds
+- **THEN** the system displays a timeout warning
+- **AND** suggests checking for complex formatting or large embedded content

openspec/changes/archive/2025-11-03-add-cover-letter-pdf-conversion/tasks.md

@@ -0,0 +1,58 @@
+# Implementation Tasks
+
+## 1. Template Creation
+- [x] 1.1 Create Swiss letter LaTeX template at `src/.claude/templates/swiss-letter.tex`
+- [x] 1.2 Configure scrlttr2 with Swiss Norm (SN) settings
+- [x] 1.3 Add proper encoding (UTF-8, T1 font encoding) for German characters
+- [x] 1.4 Implement hyperlinks for email addresses
+- [x] 1.5 Add Pandoc variable placeholders for all frontmatter fields
+- [x] 1.6 Add inline comments explaining customizable sections
+- [x] 1.7 Test template with sample data to ensure proper formatting
+
+## 2. Slash Command Implementation
+- [x] 2.1 Create command file at `src/.claude/commands/convert-cover-letter.md`
+- [x] 2.2 Implement cover letter file detection logic
+- [x] 2.3 Implement environment validation checks (Pandoc, LaTeX)
+- [x] 2.4 Add platform-specific installation instructions
+- [x] 2.5 Implement frontmatter parsing and validation
+- [x] 2.6 Build Pandoc command with correct arguments
+- [x] 2.7 Execute conversion and capture output
+- [x] 2.8 Implement error handling for common failure scenarios
+- [x] 2.9 Add success message with file path output
+
+## 3. Error Handling & Messaging
+- [x] 3.1 Create clear error message for missing cover letter
+- [x] 3.2 Create error message for missing required frontmatter fields
+- [x] 3.3 Create installation guide for Pandoc (apt, brew, winget)
+- [x] 3.4 Create installation guide for LaTeX packages
+- [x] 3.5 Add error handling for YAML parsing failures
+- [x] 3.6 Add error handling for LaTeX compilation failures
+- [x] 3.7 Add error handling for file permission issues
+- [x] 3.8 Add timeout handling for long-running conversions
+
+## 4. Testing
+- [x] 4.1 Test with complete frontmatter and body content
+- [x] 4.2 Test with minimal required frontmatter only
+- [x] 4.3 Test with optional enclosures list
+- [x] 4.4 Test with missing cover-letter.md file
+- [x] 4.5 Test with invalid YAML frontmatter
+- [x] 4.6 Test with missing required frontmatter fields
+- [x] 4.7 Test with special characters (ä, ö, ü, ß) in German text
+- [x] 4.8 Test environment validation when Pandoc is missing
+- [x] 4.9 Test environment validation when LaTeX is missing
+- [x] 4.10 Test error handling for file permission issues
+- [x] 4.11 Verify Swiss address window positioning with printed output
+- [x] 4.12 Verify date formatting follows Swiss convention
+
+## 5. Documentation
+- [x] 5.1 Document required frontmatter structure
+- [x] 5.2 Document system requirements (Pandoc, LaTeX)
+- [x] 5.3 Add example cover-letter.md with complete frontmatter
+- [x] 5.4 Document troubleshooting steps for common errors
+- [x] 5.5 Add template customization guide
+
+## 6. Integration
+- [x] 6.1 Update test directory with new command
+- [x] 6.2 Update test directory with new template
+- [x] 6.3 Ensure compatibility with existing cover letter generation
+- [x] 6.4 Verify workflow integration (step 7 in project.md)

openspec/changes/archive/2026-01-12-fix-coverletter-template-path/proposal.md

@@ -0,0 +1,33 @@
+# Change: Fix Cover Letter Template Path Resolution
+
+## Why
+
+The `/convert-cover-letter` command uses a placeholder syntax `[path-to-swiss-letter.tex]` instead of an explicit path, causing Claude Code to inconsistently locate the Swiss letter template. This results in cover letters sometimes using Pandoc's default template instead of the required Swiss business letter standards (scrlttr2 with Swiss Norm).
+
+The user reported: "Often claude does not take the template swiss-letter.tex" - this is because the placeholder syntax is ambiguous and Claude Code cannot reliably resolve it.
+
+## What Changes
+
+- Fix template path in `/convert-cover-letter` command from placeholder to explicit path
+- Update specification to require explicit path resolution
+- Add documentation clarifying path must be relative to framework root
+
+This is a **single-line bug fix** with specification clarification - no architectural changes, no new features.
+
+## Impact
+
+**Affected specs**:
+- `cover-letter-pdf-conversion` (MODIFIED - Template Management requirement)
+
+**Affected code**:
+- `src/.claude/commands/convert-cover-letter.md:250` (PRIMARY FIX - change placeholder to explicit path)
+- Add clarification about path resolution after line 255
+
+**Benefits**:
+- Consistent template usage in all scenarios
+- Reliable Swiss Norm formatting (address window positioning)
+- No more fallback to incorrect Pandoc defaults
+
+**Risks**:
+- **LOW** - Single-line change, easy to test and verify
+- No breaking changes - existing functionality preserved

openspec/changes/archive/2026-01-12-fix-coverletter-template-path/specs/cover-letter-pdf-conversion/spec.md

@@ -0,0 +1,25 @@
+# cover-letter-pdf-conversion Delta
+
+## MODIFIED Requirements
+
+### Requirement: Template Management
+
+The system SHALL provide and maintain the Swiss letter LaTeX template with explicit path resolution to ensure consistent template usage across all execution contexts.
+
+#### Scenario: Template availability
+- **WHEN** the `/convert-cover-letter` command is run
+- **THEN** the system uses the template at `src/.claude/templates/swiss-letter.tex`
+- **AND** the path is specified explicitly relative to the typical execution location
+- **AND** passes it to Pandoc via the `--template` option with the full relative path
+
+#### Scenario: Template path resolution
+- **WHEN** converting a cover letter from an application folder location (`applications/pending/[job-folder]/`)
+- **THEN** the template path `../../../src/.claude/templates/swiss-letter.tex` is used
+- **AND** the path goes up three levels to the project root and then to the template directory
+- **AND** the explicit path ensures consistent template discovery regardless of execution context
+
+#### Scenario: Template customization
+- **WHEN** users need to modify letter styling
+- **THEN** they can edit the swiss-letter.tex template at `src/.claude/templates/swiss-letter.tex`
+- **AND** changes apply to all subsequent conversions
+- **AND** the template includes comments explaining customizable sections

openspec/changes/archive/2026-01-12-fix-coverletter-template-path/tasks.md

@@ -0,0 +1,27 @@
+# Implementation Tasks
+
+## 1. Fix Command Implementation
+- [ ] 1.1 Update `src/.claude/commands/convert-cover-letter.md` line 250 from `--template=[path-to-swiss-letter.tex]` to `--template=src/.claude/templates/swiss-letter.tex`
+- [ ] 1.2 Add clarification after line 255 explaining path resolution (relative to framework root)
+- [ ] 1.3 Verify command documentation consistency with workflow version
+
+## 2. Update Specification
+- [ ] 2.1 Modify "Requirement: Template Management" in `openspec/specs/cover-letter-pdf-conversion/spec.md`
+- [ ] 2.2 Add new scenario "Template path resolution" specifying explicit path requirement
+- [ ] 2.3 Update existing "Template availability" scenario to mention path resolution
+
+## 3. Validation
+- [ ] 3.1 Run `openspec validate fix-coverletter-template-path --strict`
+- [ ] 3.2 Resolve any validation errors
+
+## 4. Testing
+- [ ] 4.1 Create test application with `/new-application`
+- [ ] 4.2 Create minimal valid cover-letter.md with required frontmatter
+- [ ] 4.3 Run `/convert-cover-letter` from application folder
+- [ ] 4.4 Verify PDF generated with Swiss Norm formatting
+- [ ] 4.5 Test from different working directories (framework root, application folder)
+- [ ] 4.6 Verify address window positioning is correct
+
+## 5. Documentation
+- [ ] 5.1 Update commit message with reference to this change
+- [ ] 5.2 Verify all documentation is consistent

openspec/specs/applicant-profile/spec.md

@@ -0,0 +1,132 @@
+# applicant-profile Specification
+
+## Purpose
+TBD - created by archiving change add-profile-template. Update Purpose after archive.
+## Requirements
+### Requirement: Profile Storage
+
+The system SHALL provide a markdown file (`src/profile.md`) in the distributable framework directory for storing applicant information.
+
+#### Scenario: Profile file exists with template structure
+
+- **WHEN** the framework is set up in `src/` directory
+- **THEN** `src/profile.md` contains template sections for Personal Information, Professional Summary, Work Experience, Education, Skills, Projects, Certifications, and Languages
+
+#### Scenario: Profile sections are clearly documented
+
+- **WHEN** user opens `src/profile.md`
+- **THEN** each section includes helpful comments explaining what information to include and formatting guidance
+
+### Requirement: Profile Schema
+
+The profile markdown SHALL include the following sections with structured information:
+
+1. Personal Information (name, email, phone, location, LinkedIn, GitHub)
+2. Professional Summary (2-3 sentence overview)
+3. Work Experience (company, position, dates, responsibilities, achievements)
+4. Education (institution, degree, field, dates, honors)
+5. Skills (categorized: technical, languages, tools, soft skills)
+6. Projects (name, description, technologies, link)
+7. Certifications (name, issuer, date)
+8. Languages (language, proficiency level)
+
+#### Scenario: Work experience includes all necessary fields
+
+- **WHEN** user adds a work experience entry
+- **THEN** template provides fields for company, position, employment period, key responsibilities, and quantifiable achievements
+
+#### Scenario: Skills are organized by category
+
+- **WHEN** user lists their skills
+- **THEN** template groups skills into categories (Technical Skills, Programming Languages, Tools & Technologies, Soft Skills)
+
+### Requirement: Claude Code Integration
+
+The `src/CLAUDE.md` file SHALL instruct Claude Code to automatically read `profile.md` when the user requests help with job applications.
+
+#### Scenario: Claude Code loads profile for application tasks
+
+- **WHEN** user asks Claude Code to help with a job application (CV, cover letter, or email) in a directory containing the framework
+- **THEN** Claude Code reads `profile.md` to access applicant information without asking the user to provide it again
+
+#### Scenario: Profile is used as source of truth
+
+- **WHEN** generating application documents
+- **THEN** Claude Code uses only information from `profile.md`, ensuring consistency across all applications and preventing hallucinations
+
+### Requirement: Framework Distribution
+
+The framework SHALL be contained in a `src/` directory separate from the development project files.
+
+#### Scenario: Users can copy framework to use elsewhere
+
+- **WHEN** user wants to use the job application framework
+- **THEN** they can copy the entire `src/` directory to any location and start using it immediately
+
+#### Scenario: Development and usage are separated
+
+- **WHEN** working on the framework itself
+- **THEN** changes are made in this repository, and `src/` contains only the distributable framework files
+
+### Requirement: Profile Validation Command
+
+The system SHALL provide a `/validate-profile` slash command that verifies the profile is complete and ready for use.
+
+#### Scenario: Validation command is available
+
+- **WHEN** user is in a directory containing the framework
+- **THEN** they can run `/validate-profile` to check if `profile.md` is complete
+
+#### Scenario: Validation detects incomplete profile
+
+- **WHEN** `/validate-profile` is run and `profile.md` contains placeholder text patterns (e.g., `[Your name]`, `[Company]`)
+- **THEN** the command reports which sections contain placeholders and need completion
+
+#### Scenario: Validation confirms complete profile
+
+- **WHEN** `/validate-profile` is run and `profile.md` has no placeholder patterns in required fields
+- **THEN** the command reports that the profile is ready for application generation
+
+### Requirement: Placeholder Detection
+
+The validation SHALL detect common placeholder patterns indicating incomplete profile data.
+
+#### Scenario: Square bracket placeholders detected
+
+- **WHEN** profile contains text in the format `[placeholder text]`
+- **THEN** validation identifies these as incomplete fields
+
+#### Scenario: Required sections checked
+
+- **WHEN** validation runs
+- **THEN** it checks that Personal Information, Professional Summary, and at least one Work Experience entry are filled out (not placeholders)
+
+#### Scenario: Optional sections allowed to be empty
+
+- **WHEN** validation runs
+- **THEN** empty optional sections (Certifications, Projects) do not cause validation failure
+
+### Requirement: Automatic Validation Before Applications
+
+The `src/CLAUDE.md` instructions SHALL require Claude Code to validate the profile before generating any application documents.
+
+#### Scenario: Profile validated before CV generation
+
+- **WHEN** user requests CV generation
+- **THEN** Claude Code first validates `profile.md` is complete before proceeding
+
+#### Scenario: Profile validated before cover letter generation
+
+- **WHEN** user requests cover letter or application email generation
+- **THEN** Claude Code first validates `profile.md` is complete before proceeding
+
+#### Scenario: Validation failure blocks application generation
+
+- **WHEN** profile validation fails (incomplete data detected)
+- **THEN** Claude Code informs the user to complete the profile and does not generate application documents
+
+#### Scenario: User can skip validation explicitly
+
+- **WHEN** user explicitly requests to skip validation (e.g., "generate CV without validation" or "I know my profile is incomplete, proceed anyway")
+- **THEN** Claude Code can proceed with a warning about potential placeholder text in output
+

openspec/specs/application-email/spec.md

@@ -0,0 +1,178 @@
+# application-email Specification
+
+## Purpose
+TBD - created by archiving change add-application-email. Update Purpose after archive.
+## Requirements
+### Requirement: Email Command Invocation
+
+The system SHALL provide a `/write-application-email` command that generates professional application emails with subject lines based on application context and profile information.
+
+#### Scenario: Command executed in application folder
+
+- **WHEN** user runs `/write-application-email` while in an application folder
+- **THEN** the system detects the current application automatically
+- **AND** generates email based on that application's data
+
+#### Scenario: Command executed with application name parameter
+
+- **WHEN** user runs `/write-application-email [application-name]` from any location
+- **THEN** the system locates the specified application folder
+- **AND** generates email based on that application's data
+
+#### Scenario: Command executed with --help flag
+
+- **WHEN** user runs `/write-application-email --help`
+- **THEN** the system displays usage information with examples
+- **AND** does not generate any email
+
+### Requirement: Document Verification
+
+The system SHALL verify that all required documents exist in the `attachments/` folder before generating the application email.
+
+#### Scenario: All required documents present
+
+- **WHEN** CV and cover letter files exist in `attachments/` folder
+- **THEN** the system proceeds with email generation
+- **AND** includes references to these documents in the email body
+
+#### Scenario: Required documents missing
+
+- **WHEN** CV or cover letter files are missing from `attachments/` folder
+- **THEN** the system displays a clear error message listing missing documents
+- **AND** does not generate the email
+- **AND** provides guidance on where to place documents
+
+#### Scenario: Optional certificates present
+
+- **WHEN** certificate or diploma files exist in `attachments/` folder
+- **THEN** the system includes references to these documents in the email
+- **AND** mentions them in the document list
+
+### Requirement: Email Content Generation
+
+The system SHALL generate email content with appropriate subject line, greeting, body, and closing based on application strategy and profile information.
+
+#### Scenario: Subject line generation
+
+- **WHEN** generating email for an application
+- **THEN** the subject line includes job title and applicant name
+- **AND** follows professional email conventions
+- **AND** matches the target language (German/English)
+
+#### Scenario: Email body with document references
+
+- **WHEN** generating email body
+- **THEN** the email includes a brief introduction
+- **AND** explicitly references attached documents (CV, cover letter)
+- **AND** mentions certificates/diplomas if present in attachments folder
+- **AND** expresses interest in the position
+- **AND** includes professional closing with contact information
+
+#### Scenario: Tone adaptation
+
+- **WHEN** application.md specifies tone (Formal/Balanced/Casual)
+- **THEN** the email adopts the appropriate language level
+- **AND** matches formality to company culture
+
+### Requirement: Language Detection
+
+The system SHALL detect and apply the appropriate language (German or English) for the email based on application context.
+
+#### Scenario: German language application
+
+- **WHEN** job posting or application context indicates German
+- **THEN** the email is generated in German
+- **AND** uses appropriate German business email conventions
+- **AND** uses formal German addressing (Sie, Herr/Frau)
+
+#### Scenario: English language application
+
+- **WHEN** job posting or application context indicates English
+- **THEN** the email is generated in English
+- **AND** uses professional English business email conventions
+
+### Requirement: File Management
+
+The system SHALL save generated email content to a markdown file in the application folder and handle file conflicts appropriately.
+
+#### Scenario: New email generation
+
+- **WHEN** `application-email.md` does not exist in application folder
+- **THEN** the system creates the file with generated content
+- **AND** displays success message with file location
+
+#### Scenario: Email already exists without force flag
+
+- **WHEN** `application-email.md` already exists
+- **AND** user did not provide `--force` flag
+- **THEN** the system displays error message
+- **AND** does not overwrite existing file
+- **AND** suggests using `--force` flag to overwrite
+
+#### Scenario: Email overwrite with force flag
+
+- **WHEN** `application-email.md` already exists
+- **AND** user provides `--force` or `--overwrite` flag
+- **THEN** the system overwrites the existing file
+- **AND** displays warning about overwriting
+- **AND** creates new email with generated content
+
+### Requirement: Error Handling
+
+The system SHALL provide clear, actionable error messages when email generation cannot proceed.
+
+#### Scenario: Application folder not found
+
+- **WHEN** specified application folder does not exist
+- **THEN** the system displays error with list of available applications
+- **AND** provides example command syntax
+
+#### Scenario: Application data incomplete
+
+- **WHEN** application.md is missing required fields
+- **THEN** the system displays error indicating incomplete sections
+- **AND** suggests running `/populate-application` or manual completion
+
+#### Scenario: Profile data missing
+
+- **WHEN** profile.md cannot be read or is incomplete
+- **THEN** the system displays error message
+- **AND** suggests running `/validate-profile`
+- **AND** does not proceed with generation
+
+### Requirement: Integration with Workflow
+
+The system SHALL integrate seamlessly with existing application workflow commands and validation.
+
+#### Scenario: Reads application strategy
+
+- **WHEN** generating email
+- **THEN** the system reads application.md for job details, company info, and tone
+- **AND** reads profile.md for applicant contact information
+- **AND** incorporates key messages from application strategy
+
+#### Scenario: References cover letter context
+
+- **WHEN** cover-letter.md exists in application folder
+- **THEN** the system ensures email tone and messaging align with cover letter
+- **AND** maintains consistency across all application documents
+
+### Requirement: Output Format
+
+The system SHALL generate email in markdown format with metadata and clear structure.
+
+#### Scenario: Email file structure
+
+- **WHEN** email is generated
+- **THEN** the file includes metadata comment block (generation date, sources, language, tone)
+- **AND** contains subject line as heading
+- **AND** contains email body with proper paragraphs
+- **AND** includes signature block with applicant information
+
+#### Scenario: Email brevity
+
+- **WHEN** generating email body
+- **THEN** the content is concise (3-4 sentences maximum)
+- **AND** mentions attached documents explicitly
+- **AND** avoids redundancy with cover letter content
+

openspec/specs/application-management/spec.md

@@ -0,0 +1,209 @@
+# application-management Specification
+
+## Purpose
+TBD - created by archiving change add-application-email. Update Purpose after archive.
+## Requirements
+### Requirement: Attachments Folder Creation
+
+The system SHALL create an `attachments/` subfolder with a `.keep` file when initializing new applications to support document organization for email generation.
+
+#### Scenario: Application folder creation includes attachments directory
+
+- **WHEN** user runs `/new-application "Company - Job Title"`
+- **THEN** the system creates folder structure: `applications/pending/[folder-name]/attachments/`
+- **AND** creates an empty `.keep` file inside `attachments/` folder
+- **AND** the attachments folder is ready for user to add documents
+
+#### Scenario: Version control compatibility
+
+- **WHEN** attachments folder is created with `.keep` file
+- **THEN** the empty folder can be tracked in version control systems
+- **AND** the folder structure is preserved even when empty
+
+#### Scenario: Success message includes attachments folder
+
+- **WHEN** new application is created successfully
+- **THEN** the success message mentions the attachments folder
+- **AND** provides guidance on what documents to place there
+- **AND** indicates this folder is for CV, cover letter, certificates
+
+### Requirement: Application Folder Structure
+
+The system SHALL create a complete folder structure for each new application including metadata, input documents, and attachments.
+
+#### Scenario: Complete folder structure created
+
+- **WHEN** `/new-application` command is executed
+- **THEN** the following structure is created:
+  ```
+  applications/pending/[YYYY-MM-DD-Company-JobTitle]/
+  ├── application.md
+  ├── input/
+  └── attachments/
+      └── .keep
+  ```
+- **AND** application.md contains the template with metadata
+- **AND** input/ folder is empty and ready for job posting documents
+- **AND** attachments/ folder contains .keep file for version control
+
+### Requirement: User Guidance for Attachments
+
+The system SHALL provide clear guidance on the purpose and usage of the attachments folder.
+
+#### Scenario: Attachments folder purpose explained
+
+- **WHEN** new application is created
+- **THEN** the success message explains attachments folder is for "final documents ready to send"
+- **AND** distinguishes it from input/ folder (which is for "source materials and research")
+- **AND** lists expected document types (CV, cover letter, certificates, diplomas)
+
+#### Scenario: Workflow guidance includes attachments
+
+- **WHEN** user views success message after creating application
+- **THEN** the workflow guidance mentions adding documents to attachments/ after generation
+- **AND** indicates attachments/ folder is checked by `/write-application-email` command
+
+### Requirement: Application Initialization Command
+
+The system SHALL provide a `/new-application` slash command that creates a new application workspace with proper folder structure.
+
+#### Scenario: Create new application with minimal info
+
+- **WHEN** user runs `/new-application "TechCorp - Senior Developer"`
+- **THEN** system creates folder `src/applications/pending/2025-11-02-TechCorp-Senior-Developer/` with `application.md` template and empty `input/` folder
+
+#### Scenario: Create application with date prefix
+
+- **WHEN** application folder is created
+- **THEN** folder name is prefixed with current date in `YYYY-MM-DD` format for chronological sorting
+
+#### Scenario: Handle special characters in folder names
+
+- **WHEN** organization name or job title contains special characters (/, \, :, etc.)
+- **THEN** system sanitizes the folder name by replacing invalid characters with hyphens or removing them
+
+#### Scenario: Application template is created
+
+- **WHEN** new application is initialized
+- **THEN** `application.md` file is created with template sections (Organization, Job Title, Research, Match Strategy, Key Messages, Tone, etc.)
+
+#### Scenario: Input folder is created automatically
+
+- **WHEN** new application is initialized
+- **THEN** `input/` subfolder is created for storing job-related documents
+
+### Requirement: Application Structure
+
+Each application workspace SHALL contain a standardized folder structure and files.
+
+#### Scenario: Folder hierarchy is consistent
+
+- **WHEN** application is created
+- **THEN** structure is: `src/applications/pending/[date-org-title]/application.md` and `src/applications/pending/[date-org-title]/input/`
+
+#### Scenario: Application template has required sections
+
+- **WHEN** `application.md` is created
+- **THEN** it includes sections for: Organization Name, Job Title, Job Description Summary, Research Notes, Match Strategy, Key Messages, Tone of Voice, and Document Checklist
+
+#### Scenario: Template provides guidance
+
+- **WHEN** user opens newly created `application.md`
+- **THEN** each section includes helpful comments explaining what information to include
+
+### Requirement: Document Population Command
+
+The system SHALL provide a `/populate-application` slash command that analyzes input documents and populates `application.md`.
+
+#### Scenario: Populate from current directory
+
+- **WHEN** user runs `/populate-application` from within an application folder
+- **THEN** system reads all files in `input/` subfolder and extracts relevant information
+
+#### Scenario: Analyze job advertisement
+
+- **WHEN** `input/` contains a job advertisement (PDF, DOCX, TXT, MD)
+- **THEN** system extracts: company name, job title, requirements, responsibilities, keywords, and company culture indicators
+
+#### Scenario: Analyze email communications
+
+- **WHEN** `input/` contains email files or text
+- **THEN** system extracts: recruiter name, company context, timeline, special instructions, and tone expectations
+
+#### Scenario: Update application.md with findings
+
+- **WHEN** input analysis is complete
+- **THEN** system updates relevant sections of `application.md` with extracted information while preserving any existing manual entries
+
+#### Scenario: Ask user for missing information
+
+- **WHEN** critical information cannot be extracted from input files (e.g., no clear job title)
+- **THEN** system prompts user to provide missing details before completing population
+
+#### Scenario: Handle empty input folder
+
+- **WHEN** `/populate-application` is run and `input/` folder is empty or doesn't exist
+- **THEN** system informs user to add job-related documents first and explains what types of files are helpful
+
+### Requirement: Profile Integration
+
+The application management system SHALL integrate with the existing profile system.
+
+#### Scenario: Reference profile during population
+
+- **WHEN** `/populate-application` runs
+- **THEN** system reads `src/profile.md` to understand applicant's background for match strategy analysis
+
+#### Scenario: Profile validation is preserved
+
+- **WHEN** working with applications
+- **THEN** the existing `/validate-profile` requirement remains enforced before document generation (to be implemented in future proposal)
+
+#### Scenario: Match applicant to job requirements
+
+- **WHEN** populating application
+- **THEN** system identifies which experiences, skills, and projects from profile.md best match the job requirements
+
+### Requirement: Claude Code Workflow Instructions
+
+The `src/CLAUDE.md` file SHALL include instructions for the application management workflow.
+
+#### Scenario: Instructions explain application lifecycle
+
+- **WHEN** Claude Code is helping with applications
+- **THEN** it understands the workflow: initialize → add input files → populate → [future: generate documents]
+
+#### Scenario: Commands are documented
+
+- **WHEN** user asks how to create an application
+- **THEN** Claude Code can explain `/new-application` and `/populate-application` commands
+
+#### Scenario: Input file guidance is provided
+
+- **WHEN** user asks what files to add to input folder
+- **THEN** Claude Code suggests: job postings (PDF/DOCX/text), recruiter emails, company research notes, or any relevant context
+
+### Requirement: File Format Support
+
+The population command SHALL support multiple input file formats.
+
+#### Scenario: Read PDF files
+
+- **WHEN** `input/` contains PDF files
+- **THEN** system extracts text content for analysis (Note: Claude Code has built-in PDF reading capability)
+
+#### Scenario: Read text-based formats
+
+- **WHEN** `input/` contains TXT, MD, or copied text files
+- **THEN** system reads and analyzes content directly
+
+#### Scenario: Read email formats
+
+- **WHEN** `input/` contains .eml or plain text email content
+- **THEN** system parses sender, subject, body and extracts relevant application context
+
+#### Scenario: Handle unsupported formats gracefully
+
+- **WHEN** `input/` contains unsupported file types (e.g., images, videos)
+- **THEN** system skips these files with a warning and processes supported formats
+

openspec/specs/application-validation/spec.md

@@ -0,0 +1,225 @@
+# application-validation Specification
+
+## Purpose
+TBD - created by archiving change add-application-validation. Update Purpose after archive.
+## Requirements
+### Requirement: Application Validation Command
+
+The system SHALL provide a `/validate-application` slash command that validates application.md completeness before document generation.
+
+#### Scenario: Validate from current directory
+
+- **WHEN** user runs `/validate-application` from inside an application folder (e.g., `applications/pending/2025-11-02-TechCorp-Developer/`)
+- **THEN** system validates the `application.md` file in the current directory
+
+#### Scenario: Validate with explicit path
+
+- **WHEN** user runs `/validate-application 2025-11-02-TechCorp-Developer`
+- **THEN** system validates `applications/pending/2025-11-02-TechCorp-Developer/application.md`
+
+#### Scenario: Handle invalid location without parameter
+
+- **WHEN** user runs `/validate-application` from a directory that is not an application folder
+- **THEN** system displays error message and lists available applications in `applications/pending/`
+
+#### Scenario: Handle non-existent application with parameter
+
+- **WHEN** user runs `/validate-application non-existent-app`
+- **THEN** system displays error that application doesn't exist and lists available applications
+
+#### Scenario: Handle missing application.md
+
+- **WHEN** validation target directory exists but has no `application.md` file
+- **THEN** system displays error: "No application.md found. This doesn't appear to be a valid application folder."
+
+### Requirement: Required Section Validation
+
+The validation SHALL check that required sections contain real content, not placeholders.
+
+#### Scenario: Organization Information is required
+
+- **WHEN** Organization Information section contains placeholders like `[To be filled]` or `[Organization name]`
+- **THEN** validation fails with specific error: "Organization Name: Contains placeholder '[To be filled]'"
+
+#### Scenario: Job Title is required
+
+- **WHEN** Job Information section has placeholder job title like `[Job Title]`
+- **THEN** validation fails with specific error: "Job Title: Contains placeholder '[Job Title]'"
+
+#### Scenario: Job Description Summary must have content
+
+- **WHEN** Job Description Summary section is empty or only contains placeholder text
+- **THEN** validation fails with error: "Job Description Summary: No content found"
+
+#### Scenario: At least some job requirements documented
+
+- **WHEN** Responsibilities, Required Skills, or other job description subsections all contain only placeholders
+- **THEN** validation fails with error listing which subsections need content
+
+#### Scenario: Partial completion is acceptable
+
+- **WHEN** Organization Name and Job Title are filled, and at least one job description subsection has real content
+- **THEN** validation passes even if other optional fields have placeholders
+
+### Requirement: Optional Section Handling
+
+The validation SHALL NOT fail for incomplete optional sections.
+
+#### Scenario: Match Strategy is optional
+
+- **WHEN** Match Strategy section contains placeholders or is empty
+- **THEN** validation does not fail (this section is optional)
+
+#### Scenario: Key Messages is optional
+
+- **WHEN** Key Messages section contains placeholders
+- **THEN** validation does not fail
+
+#### Scenario: Tone of Voice is optional
+
+- **WHEN** Tone of Voice section is empty or has placeholders
+- **THEN** validation does not fail
+
+#### Scenario: Research Notes is optional
+
+- **WHEN** Research Notes section is empty
+- **THEN** validation does not fail (user may not have research yet)
+
+### Requirement: Placeholder Detection
+
+The validation SHALL detect various placeholder patterns.
+
+#### Scenario: Detect square bracket placeholders
+
+- **WHEN** content contains `[To be filled]`, `[Organization name]`, `[Any text]`
+- **THEN** system identifies these as placeholders
+
+#### Scenario: Detect generic template text
+
+- **WHEN** content contains unchanged template phrases like "Add organization information here"
+- **THEN** system identifies these as incomplete
+
+#### Scenario: Allow legitimate brackets
+
+- **WHEN** content contains legitimate bracket uses like `[PhD]` in a name or `[Acquired by X]` in context
+- **THEN** system does not flag these as placeholders (context-aware detection)
+
+#### Scenario: Detect empty sections
+
+- **WHEN** a required section exists but has no content after the heading
+- **THEN** system identifies this as incomplete
+
+### Requirement: Population Awareness
+
+The validation SHALL check if the application has been properly populated from input documents.
+
+#### Scenario: Warn if input folder is empty
+
+- **WHEN** `input/` folder doesn't exist or contains no files
+- **THEN** validation includes warning: "Input folder is empty. Consider adding documents and running /populate-application"
+
+#### Scenario: Suggest population if sections are empty
+
+- **WHEN** most sections still contain `[To be filled]` placeholders
+- **THEN** validation suggests: "Application appears unpopulated. Run /populate-application after adding documents to input/"
+
+#### Scenario: Don't warn if manually populated
+
+- **WHEN** required sections are filled with real content (even if `input/` is empty)
+- **THEN** validation does not suggest running `/populate-application`
+
+### Requirement: Pass/Fail Reporting
+
+The validation SHALL use binary pass/fail status with structured output.
+
+#### Scenario: Successful validation output
+
+- **WHEN** all required sections are complete
+- **THEN** system displays:
+  - ✅ emoji and "Application Validation: PASSED" title
+  - Summary of application (organization, position, key stats)
+  - Encouraging message
+  - Clear next step: "You can now proceed with generating..."
+
+#### Scenario: Failed validation output
+
+- **WHEN** any required section has placeholders or is empty
+- **THEN** system displays:
+  - ❌ emoji and "Application Validation: FAILED" title
+  - Explanation of the issue
+  - Structured list of problems organized by section
+  - Specific placeholder text quoted for each issue
+  - Actionable guidance: "Please update application.md... then run /validate-application again"
+
+#### Scenario: Include population warnings in failure output
+
+- **WHEN** validation fails AND input folder is empty
+- **THEN** failure output includes additional "Population Status" section with suggestions
+
+### Requirement: Error Message Clarity
+
+The validation SHALL provide clear, actionable error messages.
+
+#### Scenario: Quote specific placeholder text
+
+- **WHEN** a field contains placeholder `[Company Name Here]`
+- **THEN** error message shows: "Organization Name: Contains placeholder '[Company Name Here]'"
+
+#### Scenario: Group errors by section
+
+- **WHEN** multiple fields in Job Description Summary are incomplete
+- **THEN** errors are grouped under "## Job Description Summary" heading with individual items listed
+
+#### Scenario: Provide next steps
+
+- **WHEN** validation fails
+- **THEN** output includes clear guidance: "Please update application.md to fill in these sections, then run /validate-application again"
+
+#### Scenario: List available applications on location error
+
+- **WHEN** user runs command from wrong location without parameter
+- **THEN** error message includes: "Available applications:" followed by list from `ls applications/pending/`
+
+### Requirement: Edge Case Handling
+
+The validation SHALL handle edge cases gracefully.
+
+#### Scenario: Handle corrupted or unreadable application.md
+
+- **WHEN** application.md exists but cannot be read or parsed
+- **THEN** system displays error: "Could not read application.md. File may be corrupted."
+
+#### Scenario: Handle very long placeholder text
+
+- **WHEN** placeholder text is longer than 100 characters
+- **THEN** error message truncates it: "Contains placeholder '[First 100 chars...]'"
+
+#### Scenario: Handle missing required sections
+
+- **WHEN** application.md is missing entire required sections (e.g., no Job Information section)
+- **THEN** validation fails with error: "Missing required section: Job Information"
+
+#### Scenario: Case-insensitive section matching
+
+- **WHEN** section headings use different cases (e.g., "organization information" vs "Organization Information")
+- **THEN** system correctly identifies the section
+
+### Requirement: Workflow Integration
+
+The validation command SHALL integrate with the existing application workflow.
+
+#### Scenario: Documentation includes validation step
+
+- **WHEN** user checks `src/CLAUDE.md` workflow documentation
+- **THEN** validation step is shown between "Populate application" and "Generate documents"
+
+#### Scenario: Validation mentioned in populate-application
+
+- **WHEN** `/populate-application` completes successfully
+- **THEN** output suggests: "Next: Run /validate-application to check completeness"
+
+#### Scenario: Consistent with profile validation
+
+- **WHEN** comparing `/validate-application` output to `/validate-profile` output
+- **THEN** format, tone, and structure are consistent (both use ✅/❌, structured errors, encouraging tone)
+

openspec/specs/cover-letter-generation/spec.md

@@ -0,0 +1,345 @@
+# cover-letter-generation Specification
+
+## Purpose
+TBD - created by archiving change add-cover-letter-generation. Update Purpose after archive.
+## Requirements
+### Requirement: Cover Letter Generation Command
+
+The system SHALL provide a `/write-cover-letter` slash command that generates tailored cover letters based on application strategy and profile information.
+
+#### Scenario: Generate from current directory
+
+- **WHEN** user runs `/write-cover-letter` from inside an application folder
+- **THEN** system generates cover letter for the application in current directory
+
+#### Scenario: Generate with explicit application name
+
+- **WHEN** user runs `/write-cover-letter 2025-11-02-TechCorp-Developer`
+- **THEN** system generates cover letter for that specific application
+
+#### Scenario: Handle unclear location
+
+- **WHEN** user runs `/write-cover-letter` from a directory that is not an application folder and no parameter is provided
+- **THEN** system lists all applications in `applications/pending/` and asks user to specify which one
+
+#### Scenario: Handle non-existent application
+
+- **WHEN** user provides application name that doesn't exist
+- **THEN** system shows error and lists available applications
+
+### Requirement: Automatic Validation Check
+
+The system SHALL automatically validate the application before generating a cover letter.
+
+#### Scenario: Validation passes automatically
+
+- **WHEN** user runs `/write-cover-letter` and application validation passes
+- **THEN** system proceeds with cover letter generation
+
+#### Scenario: Validation fails automatically
+
+- **WHEN** user runs `/write-cover-letter` and application validation fails
+- **THEN** system shows validation errors and stops generation (does not create cover-letter.md)
+
+#### Scenario: Skip validation with flag
+
+- **WHEN** user runs `/write-cover-letter --skip-validation` and application has incomplete sections
+- **THEN** system shows warning but proceeds with generation anyway
+
+#### Scenario: Show validation progress
+
+- **WHEN** validation is running
+- **THEN** system shows progress: "🔍 Validating application..." followed by result
+
+### Requirement: Existing File Protection
+
+The system SHALL check if cover-letter.md already exists and prevent overwriting without explicit permission.
+
+#### Scenario: Cover letter already exists
+
+- **WHEN** user runs `/write-cover-letter` and `cover-letter.md` already exists in application folder
+- **THEN** system stops and shows error: "Cover letter already exists. Use --force to overwrite."
+
+#### Scenario: Force overwrite with flag
+
+- **WHEN** user runs `/write-cover-letter --force` and cover-letter.md exists
+- **THEN** system shows warning and overwrites the file
+
+#### Scenario: No existing file
+
+- **WHEN** user runs `/write-cover-letter` and no cover-letter.md exists
+- **THEN** system proceeds with generation without prompting
+
+### Requirement: Multi-Source Data Reading
+
+The system SHALL read both profile.md and application.md to gather information for the cover letter.
+
+#### Scenario: Read profile for applicant background
+
+- **WHEN** generating cover letter
+- **THEN** system reads `profile.md` to extract:
+  - Personal information (name, contact)
+  - Professional summary
+  - Relevant work experiences (as identified in match strategy)
+  - Key skills and achievements
+  - Projects to highlight
+
+#### Scenario: Read application for job strategy
+
+- **WHEN** generating cover letter
+- **THEN** system reads `application.md` to extract:
+  - Organization name and job title
+  - Match strategy (which experiences to emphasize)
+  - Key messages to convey
+  - Tone assessment (Formal/Balanced/Casual)
+  - Company research and culture insights
+  - Job requirements and keywords
+
+#### Scenario: Handle missing profile.md
+
+- **WHEN** profile.md doesn't exist or is unreadable
+- **THEN** system shows error: "profile.md not found. Please create your profile first." and stops
+
+#### Scenario: Cross-reference match strategy
+
+- **WHEN** application.md has match strategy section with specific experiences to emphasize
+- **THEN** system prioritizes those experiences from profile.md in the cover letter content
+
+### Requirement: Standard Structure Generation
+
+The system SHALL generate cover letters with a standard 1-page structure.
+
+#### Scenario: Opening paragraph with hook
+
+- **WHEN** generating cover letter
+- **THEN** opening paragraph includes:
+  - Specific job title and company name
+  - Brief statement of interest
+  - One compelling reason for applying (from key messages or research)
+
+#### Scenario: Why this role paragraph
+
+- **WHEN** generating cover letter
+- **THEN** "why this role" section includes:
+  - Connection to company mission/values
+  - Reference to company research insights
+  - Genuine interest in the position
+
+#### Scenario: What you bring paragraphs
+
+- **WHEN** generating cover letter
+- **THEN** "what you bring" sections include:
+  - 2-3 most relevant experiences from match strategy
+  - Specific achievements from profile.md
+  - Connection to job requirements
+  - Natural incorporation of keywords
+
+#### Scenario: Cultural fit paragraph
+
+- **WHEN** generating cover letter
+- **THEN** cultural fit section includes:
+  - Alignment of personal values with company culture
+  - Reference to soft skills that match company culture indicators
+  - Enthusiasm for work environment
+
+#### Scenario: Closing paragraph
+
+- **WHEN** generating cover letter
+- **THEN** closing includes:
+  - Strong statement of interest
+  - Availability for interview
+  - Professional thank you
+  - Call to action
+
+### Requirement: Length and Formatting
+
+The system SHALL generate cover letters with appropriate length and formatting.
+
+#### Scenario: Target word count
+
+- **WHEN** generating cover letter
+- **THEN** system aims for 300-400 words total (approximately 1 page)
+
+#### Scenario: Paragraph structure
+
+- **WHEN** generating cover letter
+- **THEN** system creates 4-5 distinct paragraphs (Opening, Why role, What you bring 1-2 paragraphs, Cultural fit, Closing)
+
+#### Scenario: Professional formatting
+
+- **WHEN** cover letter is generated
+- **THEN** format includes:
+  - Applicant contact information header (from profile.md)
+  - Date
+  - Company/recruiter address (from application.md)
+  - Professional salutation
+  - Body paragraphs
+  - Professional sign-off
+
+### Requirement: Tone and Language
+
+The system SHALL apply appropriate tone and language based on application.md guidance.
+
+#### Scenario: Apply tone from application.md
+
+- **WHEN** application.md has tone assessment of "Formal"
+- **THEN** cover letter uses formal language, professional vocabulary, traditional business letter tone
+
+#### Scenario: Apply balanced tone
+
+- **WHEN** application.md has tone assessment of "Balanced"
+- **THEN** cover letter uses professional but approachable language, moderate formality
+
+#### Scenario: Apply casual tone
+
+- **WHEN** application.md has tone assessment of "Casual"
+- **THEN** cover letter uses conversational yet professional language, more personal voice
+
+#### Scenario: Infer language from context
+
+- **WHEN** job posting, company information, or application.md content suggests German language
+- **THEN** cover letter is generated in German
+
+#### Scenario: Default to English
+
+- **WHEN** language cannot be clearly determined from context
+- **THEN** cover letter is generated in English
+
+### Requirement: Content Quality and Authenticity
+
+The system SHALL ensure generated content is authentic, factual, and high-quality.
+
+#### Scenario: Use only real information
+
+- **WHEN** generating cover letter content
+- **THEN** system uses ONLY experiences, skills, and achievements documented in profile.md (no hallucination)
+
+#### Scenario: Natural keyword incorporation
+
+- **WHEN** job description has specific keywords or required skills
+- **THEN** system incorporates them naturally in context (not as a list)
+
+#### Scenario: Company-specific personalization
+
+- **WHEN** application.md has research notes about company
+- **THEN** cover letter references specific company initiatives, values, or news
+
+#### Scenario: Authentic voice
+
+- **WHEN** generating prose
+- **THEN** system creates natural, human-sounding text (not obviously AI-generated)
+
+### Requirement: Success and Progress Reporting
+
+The system SHALL provide clear feedback during the generation process.
+
+#### Scenario: Show generation steps
+
+- **WHEN** cover letter is being generated
+- **THEN** system shows progress:
+  - "🔍 Validating application..."
+  - "📝 Generating cover letter..."
+  - "✓ Read profile.md"
+  - "✓ Read application.md"
+  - "✓ Analyzed match strategy"
+  - "✓ Generated [N] words"
+
+#### Scenario: Success message
+
+- **WHEN** cover letter generation completes successfully
+- **THEN** system shows:
+  - ✅ emoji and "Cover letter saved: cover-letter.md"
+  - Summary (word count, tone, language, key experiences used)
+  - Next steps (review, personalize, generate CV)
+
+#### Scenario: Include file location
+
+- **WHEN** showing success message
+- **THEN** system includes full or relative path to cover-letter.md file
+
+### Requirement: Error Handling
+
+The system SHALL handle errors gracefully with helpful messages.
+
+#### Scenario: Missing application.md
+
+- **WHEN** application folder has no application.md file
+- **THEN** system shows error: "No application.md found. Please create application first with /new-application"
+
+#### Scenario: Validation failure stops generation
+
+- **WHEN** /validate-application fails with incomplete sections
+- **THEN** system shows specific validation errors and suggests: "Fix issues or use --skip-validation to proceed anyway"
+
+#### Scenario: Existing cover letter blocks generation
+
+- **WHEN** cover-letter.md already exists
+- **THEN** system shows: "Cover letter already exists. Use --force to overwrite. Warning: This will replace your existing cover letter."
+
+#### Scenario: File write errors
+
+- **WHEN** cover-letter.md cannot be written (permissions, disk full, etc.)
+- **THEN** system shows clear error: "Could not save cover-letter.md: [reason]"
+
+### Requirement: Flags and Options
+
+The system SHALL support command flags for advanced usage.
+
+#### Scenario: Skip validation flag
+
+- **WHEN** user provides `--skip-validation` flag
+- **THEN** system skips /validate-application check and generates anyway
+
+#### Scenario: Force overwrite flag
+
+- **WHEN** user provides `--force` or `--overwrite` flag
+- **THEN** system overwrites existing cover-letter.md without prompting
+
+#### Scenario: Combined flags
+
+- **WHEN** user provides multiple flags: `/write-cover-letter --skip-validation --force`
+- **THEN** system applies both: skips validation AND overwrites existing file
+
+#### Scenario: Help flag
+
+- **WHEN** user runs `/write-cover-letter --help`
+- **THEN** system shows usage information, available flags, and examples
+
+### Requirement: Post-Generation Guidance
+
+The system SHALL provide clear next steps after generation.
+
+#### Scenario: Review guidance
+
+- **WHEN** cover letter is generated
+- **THEN** system suggests: "Review cover-letter.md for accuracy and authenticity"
+
+#### Scenario: Personalization guidance
+
+- **WHEN** cover letter is generated
+- **THEN** system suggests: "Add any additional personal insights or connections to the role"
+
+#### Scenario: Next command suggestion
+
+- **WHEN** cover letter is generated
+- **THEN** system suggests next step: "Generate CV: /write-cv (coming soon)"
+
+### Requirement: Integration with Workflow
+
+The system SHALL integrate seamlessly with existing application workflow.
+
+#### Scenario: Workflow step documentation
+
+- **WHEN** user checks workflow in CLAUDE.md
+- **THEN** cover letter generation appears as Step 6 after validation
+
+#### Scenario: Command availability
+
+- **WHEN** user lists available commands
+- **THEN** `/write-cover-letter` is documented with description and usage examples
+
+#### Scenario: Consistent patterns
+
+- **WHEN** using `/write-cover-letter`
+- **THEN** location detection, error handling, and output format match patterns from other commands (/validate-application, /populate-application)
+

openspec/specs/cover-letter-pdf-conversion/spec.md

@@ -0,0 +1,153 @@
+# cover-letter-pdf-conversion Specification
+
+## Purpose
+TBD - created by archiving change add-cover-letter-pdf-conversion. Update Purpose after archive.
+## Requirements
+### Requirement: Cover Letter Detection
+
+The system SHALL detect the presence of a valid cover letter markdown file in the current directory before attempting conversion.
+
+#### Scenario: Valid cover letter found
+- **WHEN** a file named `cover-letter.md` exists in the current directory
+- **AND** the file contains valid markdown with frontmatter
+- **THEN** the system proceeds with conversion
+
+#### Scenario: No cover letter found
+- **WHEN** no `cover-letter.md` file exists in the current directory
+- **THEN** the system displays an error message indicating no cover letter was found
+- **AND** suggests running `/write-cover-letter` first
+
+#### Scenario: Invalid cover letter format
+- **WHEN** `cover-letter.md` exists but lacks required frontmatter fields
+- **THEN** the system displays an error listing the missing required fields
+- **AND** provides an example of correct frontmatter structure
+
+### Requirement: Environment Validation
+
+The system SHALL validate that all required tools are installed before attempting conversion.
+
+#### Scenario: All tools available
+- **WHEN** the user runs `/convert-cover-letter`
+- **AND** Pandoc is installed and accessible
+- **AND** LaTeX (pdflatex) is installed and accessible
+- **THEN** the system proceeds with conversion
+
+#### Scenario: Pandoc missing
+- **WHEN** the user runs `/convert-cover-letter`
+- **AND** Pandoc is not installed
+- **THEN** the system displays installation instructions for Pandoc
+- **AND** provides platform-specific commands (apt, brew, etc.)
+- **AND** stops the conversion process
+
+#### Scenario: LaTeX missing
+- **WHEN** the user runs `/convert-cover-letter`
+- **AND** Pandoc is installed but LaTeX is not installed
+- **THEN** the system displays installation instructions for LaTeX packages
+- **AND** lists required packages (texlive-latex-base, texlive-lang-german, texlive-latex-extra)
+- **AND** stops the conversion process
+
+### Requirement: Swiss Letter Formatting
+
+The system SHALL generate PDFs using Swiss business letter standards (scrlttr2 with SN configuration).
+
+#### Scenario: Address window positioning
+- **WHEN** converting a cover letter to PDF
+- **THEN** the recipient address is positioned according to Swiss Norm (SN)
+- **AND** fits within standard Swiss envelope window dimensions
+
+#### Scenario: Swiss German formatting
+- **WHEN** the cover letter content contains German text
+- **THEN** Swiss German hyphenation rules are applied
+- **AND** date formatting follows Swiss convention (DD.MM.YYYY)
+- **AND** number formatting uses Swiss conventions
+
+#### Scenario: Professional layout
+- **WHEN** converting to PDF
+- **THEN** the output includes proper margins for Swiss business letters
+- **AND** sender information is positioned in the header
+- **AND** contact information (phone, email) is formatted with hyperlinks
+
+### Requirement: Metadata Extraction
+
+The system SHALL extract metadata from markdown frontmatter and map it to LaTeX variables.
+
+#### Scenario: Complete frontmatter
+- **WHEN** the markdown contains all required frontmatter fields
+- **THEN** sender information (name, street, city, phone, email) is extracted
+- **AND** recipient address lines are extracted
+- **AND** letter details (date, subject, opening, closing, signature) are extracted
+- **AND** optional enclosures list is extracted if present
+
+#### Scenario: Minimal frontmatter
+- **WHEN** the markdown contains only required frontmatter fields
+- **THEN** the system uses default values for optional fields
+- **AND** generates a valid PDF without enclosures section
+
+#### Scenario: Invalid frontmatter structure
+- **WHEN** the frontmatter cannot be parsed as YAML
+- **THEN** the system displays a clear error message
+- **AND** points to the specific syntax error if possible
+
+### Requirement: PDF Generation
+
+The system SHALL convert the markdown body to PDF using Pandoc with the Swiss letter template.
+
+#### Scenario: Successful conversion
+- **WHEN** all prerequisites are met
+- **AND** the markdown is valid
+- **THEN** the system generates a PDF file in the same directory
+- **AND** names the file `cover-letter.pdf`
+- **AND** displays a success message with the file path
+
+#### Scenario: Conversion with enclosures
+- **WHEN** the frontmatter includes an `enclosures` list
+- **THEN** the generated PDF includes an enclosures section after the closing
+- **AND** lists each enclosure item on a separate line
+
+#### Scenario: LaTeX compilation error
+- **WHEN** Pandoc generates LaTeX but pdflatex fails to compile
+- **THEN** the system displays the LaTeX error output
+- **AND** suggests checking for special characters or formatting issues
+- **AND** preserves the intermediate .tex file for debugging
+
+### Requirement: Template Management
+
+The system SHALL provide and maintain the Swiss letter LaTeX template with explicit path resolution to ensure consistent template usage across all execution contexts.
+
+#### Scenario: Template availability
+- **WHEN** the `/convert-cover-letter` command is run
+- **THEN** the system uses the template at `src/.claude/templates/swiss-letter.tex`
+- **AND** the path is specified explicitly relative to the typical execution location
+- **AND** passes it to Pandoc via the `--template` option with the full relative path
+
+#### Scenario: Template path resolution
+- **WHEN** converting a cover letter from an application folder location (`applications/pending/[job-folder]/`)
+- **THEN** the template path `../../../src/.claude/templates/swiss-letter.tex` is used
+- **AND** the path goes up three levels to the project root and then to the template directory
+- **AND** the explicit path ensures consistent template discovery regardless of execution context
+
+#### Scenario: Template customization
+- **WHEN** users need to modify letter styling
+- **THEN** they can edit the swiss-letter.tex template at `src/.claude/templates/swiss-letter.tex`
+- **AND** changes apply to all subsequent conversions
+- **AND** the template includes comments explaining customizable sections
+
+### Requirement: Error Handling
+
+The system SHALL provide clear, actionable error messages for common failure scenarios.
+
+#### Scenario: File permission error
+- **WHEN** the PDF cannot be written due to permissions
+- **THEN** the system displays a permission error message
+- **AND** suggests checking directory write permissions
+
+#### Scenario: Disk space error
+- **WHEN** PDF generation fails due to insufficient disk space
+- **THEN** the system displays a disk space error
+- **AND** suggests freeing up space or choosing a different output location
+
+#### Scenario: Process timeout
+- **WHEN** LaTeX compilation takes longer than 30 seconds
+- **THEN** the system displays a timeout warning
+- **AND** suggests checking for complex formatting or large embedded content
+

src/.agent/workflows/convert-cover-letter.md

@@ -0,0 +1,506 @@
+---
+description: Convert a markdown cover letter to a professionally formatted PDF using Swiss business letter standards.
+---
+
+# Instructions
+
+You are converting a markdown cover letter to PDF format. The output will follow Swiss business letter standards (scrlttr2 with Swiss Norm) for proper formatting and address window positioning.
+
+## Step 1: Check for Cover Letter
+
+### Verify File Exists
+
+1. Check if `cover-letter.md` exists in the current directory
+2. If file exists → proceed to Step 2
+3. If file does not exist → show error and stop
+
+### Error: Cover Letter Not Found
+
+```
+❌ Cover letter not found
+
+Could not find cover-letter.md in the current directory.
+
+Please either:
+1. Navigate to an application folder containing a cover letter:
+   cd applications/pending/[application-folder]/
+   /convert-cover-letter
+
+2. Generate a cover letter first:
+   /write-cover-letter
+
+Current directory: [show current working directory]
+```
+STOP. Do not proceed.
+
+## Step 2: Environment Validation
+
+**CRITICAL**: Check for required tools before attempting conversion.
+
+Show progress: `🔍 Checking system requirements...`
+
+### Check for Pandoc
+
+Run: `which pandoc` or `pandoc --version`
+
+**If Pandoc is NOT installed:**
+
+```
+❌ Pandoc not found
+
+Pandoc is required for PDF conversion but is not installed on your system.
+
+## Installation Instructions:
+
+### Ubuntu/Debian:
+sudo apt update
+sudo apt install pandoc
+
+### macOS (Homebrew):
+brew install pandoc
+
+### Arch Linux:
+sudo pacman -S pandoc
+
+### Windows:
+winget install pandoc
+
+### Other Systems:
+Download from: https://pandoc.org/installing.html
+
+---
+
+After installation, run: pandoc --version
+Then try /convert-cover-letter again.
+```
+STOP. Do not proceed with conversion.
+
+**If Pandoc is installed:**
+Show progress: `✓ Pandoc found (version X.X.X)`
+
+### Check for LaTeX (pdflatex)
+
+Run: `which pdflatex` or `pdflatex --version`
+
+**If LaTeX is NOT installed:**
+
+```
+❌ LaTeX not found
+
+LaTeX (pdflatex) is required for PDF generation but is not installed.
+
+## Installation Instructions:
+
+### Ubuntu/Debian:
+sudo apt update
+sudo apt install texlive-latex-base texlive-latex-extra
+
+# For German language support (recommended for proper labels):
+sudo apt install texlive-lang-german
+
+### macOS (Homebrew):
+brew install texlive
+# Note: This is a large download (~4GB). Alternative: MacTeX from https://www.tug.org/mactex/
+
+### Arch Linux:
+sudo pacman -S texlive-core texlive-latexextra texlive-langgerman
+
+### Windows:
+# Install MiKTeX from: https://miktex.org/download
+# Or TeX Live from: https://www.tug.org/texlive/
+
+---
+
+**Required packages**:
+- texlive-latex-base (core LaTeX)
+- texlive-latex-extra (KOMA-Script including scrlttr2)
+
+**Recommended packages**:
+- texlive-lang-german (German labels: "Telefon" instead of "Phone", "Anlagen" instead of "encl")
+
+After installation, run: pdflatex --version
+Then try /convert-cover-letter again.
+```
+STOP. Do not proceed with conversion.
+
+**If LaTeX is installed:**
+Show progress: `✓ LaTeX found (pdfTeX X.X.X)`
+
+**All prerequisites met:**
+Show progress: `✅ All requirements satisfied`
+
+## Step 3: Read and Validate Cover Letter
+
+Show progress: `📄 Reading cover-letter.md...`
+
+### Read File Content
+
+1. Read the entire `cover-letter.md` file
+2. Separate frontmatter (YAML between `---` delimiters) from body content
+3. Parse the YAML frontmatter
+4. Extract the markdown body (everything after the second `---`)
+
+### Validate Frontmatter Structure
+
+**Required fields:**
+- `from.name` - Sender's full name
+- `from.street` - Sender's street address
+- `from.city` - Sender's city with postal code (e.g., "CH-8000 Zürich")
+- `to` - Array of recipient address lines (at least 2 lines)
+- `subject` - Letter subject line
+- `opening` - Letter opening salutation
+- `closing` - Letter closing phrase
+- `signature` - Name for signature
+
+**Optional fields:**
+- `from.phone` - Sender's phone number
+- `from.email` - Sender's email address
+- `date` - Letter date (defaults to current date if missing)
+- `enclosures` - Array of enclosure items
+
+### Error: Invalid YAML
+
+**If frontmatter cannot be parsed as YAML:**
+
+```
+❌ Invalid frontmatter format
+
+The YAML frontmatter in cover-letter.md could not be parsed.
+
+Error details: [specific YAML parsing error]
+
+Please check that:
+1. Frontmatter is enclosed between --- markers
+2. YAML syntax is correct (proper indentation, colons, hyphens)
+3. No special characters are unescaped
+
+Example of correct frontmatter:
+---
+from:
+  name: Max Mustermann
+  street: Musterstrasse 42
+  city: CH-8000 Zürich
+  phone: +41 44 123 45 67
+  email: max.mustermann@example.ch
+to:
+  - Firma AG
+  - Personalabteilung
+  - Hauptstrasse 100
+  - CH-3000 Bern
+subject: Bewerbung als Software-Entwickler
+opening: Sehr geehrte Damen und Herren
+closing: Freundliche Grüsse
+signature: Max Mustermann
+---
+```
+STOP.
+
+### Error: Missing Required Fields
+
+**If any required fields are missing:**
+
+```
+❌ Incomplete frontmatter
+
+Your cover letter is missing required fields in the frontmatter:
+
+Missing fields:
+[List each missing field with description]
+
+Required frontmatter structure:
+---
+from:
+  name: [Your full name]
+  street: [Your street address]
+  city: [Your city with postal code]
+  phone: [Your phone] (optional)
+  email: [Your email] (optional)
+to:
+  - [Company name]
+  - [Department or contact person]
+  - [Street address]
+  - [City with postal code]
+date: [DD.MM.YYYY] (optional, defaults to today)
+subject: [Letter subject]
+opening: [Greeting, e.g., "Sehr geehrte Damen und Herren"]
+closing: [Sign-off, e.g., "Freundliche Grüsse"]
+signature: [Your name for signature]
+enclosures: (optional)
+  - [Document 1]
+  - [Document 2]
+---
+
+[Body content follows]
+```
+STOP.
+
+**If all required fields are present:**
+Show progress: `✓ Frontmatter validated`
+
+## Step 4: Convert to PDF
+
+Show progress: `🔄 Converting to PDF...`
+
+### Prepare Pandoc Command
+
+Build the conversion command:
+
+```bash
+pandoc cover-letter.md \
+  --from markdown \
+  --to latex \
+  --template=.claude/templates/swiss-letter.tex \
+  --pdf-engine=pdflatex \
+  --output=cover-letter.pdf
+```
+
+**Template path**: Use the template at `.claude/templates/swiss-letter.tex` relative to the framework root.
+
+### Execute Conversion
+
+1. Run the Pandoc command
+2. Capture stdout and stderr
+3. Check exit code
+
+### Handle Conversion Errors
+
+**If pdflatex fails to compile:**
+
+```
+❌ PDF compilation failed
+
+LaTeX encountered an error while compiling your cover letter.
+
+Error output:
+[Show relevant error lines from stderr]
+
+Common causes:
+1. Special characters not properly escaped (e.g., &, %, $, #, _)
+2. Formatting issues in the markdown body
+3. Very long lines or complex formatting
+4. Missing LaTeX packages
+
+Troubleshooting:
+1. Check for special characters in your cover letter text
+2. Try simplifying complex formatting
+3. Verify that all required LaTeX packages are installed:
+   - texlive-latex-base
+   - texlive-lang-german
+   - texlive-latex-extra
+
+The intermediate .tex file has been preserved at: [path-to-.tex-file]
+You can inspect this file to identify the issue.
+
+Need help? Share the error output above for assistance.
+```
+STOP.
+
+**If file permissions error:**
+
+```
+❌ Permission denied
+
+Could not write cover-letter.pdf to the current directory.
+
+Please check:
+1. You have write permissions in: [current directory]
+2. The file is not open in another application
+3. Sufficient disk space is available
+
+Current directory permissions:
+[Show output of: ls -ld .]
+```
+STOP.
+
+**If disk space error:**
+
+```
+❌ Insufficient disk space
+
+Could not create PDF file due to insufficient disk space.
+
+Please:
+1. Free up disk space
+2. Or choose a different output location
+
+Available disk space:
+[Show output of: df -h .]
+```
+STOP.
+
+**If conversion times out (> 30 seconds):**
+
+```
+❌ Conversion timeout
+
+PDF generation took longer than expected (> 30 seconds).
+
+This might indicate:
+1. Very long or complex document
+2. LaTeX compilation stuck on an error
+3. System resource constraints
+
+Please try:
+1. Simplifying the cover letter content
+2. Checking system resources
+3. Running pdflatex manually for debugging
+
+Manual debugging:
+pandoc cover-letter.md --from markdown --to latex --template=[template-path] -o cover-letter.tex
+pdflatex cover-letter.tex
+```
+STOP.
+
+## Step 5: Success Output
+
+**If conversion succeeded:**
+
+```
+✅ PDF generated successfully: cover-letter.pdf
+
+## Conversion Summary:
+
+📄 Input: cover-letter.md
+📑 Output: cover-letter.pdf
+📐 Format: Swiss business letter (scrlttr2, Swiss Norm)
+
+## Document Details:
+
+✓ Sender: [from.name]
+✓ Recipient: [to[0]] (first line of address)
+✓ Subject: [subject]
+✓ Date: [date]
+$if(enclosures)$
+✓ Enclosures: [N] items
+$endif$
+
+## Formatting Applied:
+
+- Swiss address window positioning (compatible with standard Swiss envelopes)
+- Swiss German hyphenation and spelling
+- Professional business letter layout
+- Clickable email links
+- Proper margins and spacing
+
+## Next Steps:
+
+1. **Review the PDF**: Open cover-letter.pdf and verify:
+   - All information is correct
+   - Layout looks professional
+   - Address fits in envelope window (if printing)
+   - No formatting issues or typos
+
+2. **Print test** (if mailing):
+   - Print the PDF
+   - Check address position with a Swiss envelope window
+   - Verify text is clear and readable
+
+3. **Digital submission**:
+   - Ready to attach to email applications
+   - Filename: cover-letter.pdf
+
+4. **Rename for organization** (optional):
+   - Consider: [YourName]_Cover_Letter_[Company]_[Date].pdf
+   - Example: Max_Mustermann_Cover_Letter_TechCorp_2025-11-03.pdf
+
+---
+
+**Tip**: The generated PDF follows Swiss standards (SN) for business correspondence.
+The address positioning is optimized for standard Swiss envelope windows.
+```
+
+## Step 6: Cleanup (Optional)
+
+Pandoc may create intermediate files during conversion:
+- `cover-letter.tex` - Intermediate LaTeX file
+- `cover-letter.aux`, `cover-letter.log` - LaTeX compilation files
+
+**If conversion was successful**: These files can be deleted (they're not needed)
+**If conversion failed**: Preserve the .tex file for debugging
+
+## Additional Features
+
+### Custom Template
+
+Users can customize the Swiss letter template:
+
+**Location**: `.claude/templates/swiss-letter.tex`
+
+**Customizable elements** (documented in template):
+- Font size (currently 11pt)
+- Margins and spacing
+- Sender address alignment
+- Header/footer content
+- Color scheme (currently black/white)
+
+**To customize**:
+1. Edit `.claude/templates/swiss-letter.tex`
+2. Re-run `/convert-cover-letter` to apply changes
+3. Template comments explain each section
+
+### Multiple Conversions
+
+Users can run `/convert-cover-letter` multiple times:
+- Overwrites existing `cover-letter.pdf` (no prompt needed)
+- Use this after editing `cover-letter.md`
+- Quick iteration on formatting and content
+
+## Error Handling Summary
+
+| Error Condition | User Action Required |
+|-----------------|---------------------|
+| No cover-letter.md | Navigate to application folder or run /write-cover-letter |
+| Pandoc missing | Install Pandoc via package manager |
+| LaTeX missing | Install texlive-latex-base, texlive-lang-german, texlive-latex-extra |
+| Invalid YAML | Fix frontmatter syntax in cover-letter.md |
+| Missing required fields | Add missing fields to frontmatter |
+| LaTeX compilation error | Check for special characters, inspect .tex file |
+| Permission denied | Check directory write permissions |
+| Disk space | Free up disk space |
+| Timeout | Simplify content or debug manually |
+
+## Important Notes
+
+### Swiss Letter Standards
+
+The conversion follows Swiss Norm (SN) for business letters:
+- **Address window**: Positioned for standard Swiss envelope windows
+- **Date format**: DD.MM.YYYY (Swiss convention)
+- **Layout**: KOMA-Script scrlttr2 with Swiss configuration
+- **Language support**: Swiss German hyphenation and special characters (ä, ö, ü, ß)
+
+### File Compatibility
+
+**Input format**: Markdown with YAML frontmatter
+**Output format**: PDF (via LaTeX)
+**Template engine**: Pandoc with custom LaTeX template
+
+### System Requirements
+
+**Minimum**:
+- Pandoc 2.0+
+- LaTeX (TeX Live or MiKTeX)
+- Basic LaTeX packages (texlive-latex-base, texlive-lang-german, texlive-latex-extra)
+
+**Recommended**:
+- Latest Pandoc version
+- Full TeX Live installation (includes all packages)
+- ~500MB disk space for full LaTeX installation
+
+### Troubleshooting
+
+**Common issues**:
+1. **"File not found"** → Run command from application directory
+2. **"Pandoc not found"** → Install Pandoc first
+3. **"LaTeX error"** → Check for special characters in text
+4. **"Missing font"** → Install texlive-fonts-recommended
+5. **"Address doesn't fit window"** → Verify Swiss envelope type, check template settings
+
+**For advanced users**:
+- Intermediate .tex file shows LaTeX source
+- Run `pdflatex cover-letter.tex` manually for detailed error output
+- Edit swiss-letter.tex template for custom layouts
+
+---
+
+**Remember**: The goal is to produce a professional, Swiss-standard business letter PDF that is ready for submission with job applications. Quality and formatting accuracy are paramount.

src/.agent/workflows/new-application.md

@@ -0,0 +1,179 @@
+---
+description: Initialize a new job application with organized folder structure.
+---
+
+# Instructions
+
+You are creating a new job application workspace for the user.
+
+## Input Processing
+
+### 1. Parse User Input
+
+The user will provide information about the application in the command. Extract:
+- **Organization Name**: The company/organization they're applying to
+- **Job Title**: The position they're applying for
+
+Example inputs:
+- `/new-application "TechCorp - Senior Developer"`
+- `/new-application "Startup Inc - Product Manager"`
+- `/new-application "Google - Software Engineer"`
+
+If the user provides insufficient information, prompt them:
+```
+Please provide the organization name and job title.
+Format: /new-application "Organization Name - Job Title"
+Example: /new-application "TechCorp - Senior Developer"
+```
+
+### 2. Generate Folder Name
+
+Create a folder name in the format: `YYYY-MM-DD-OrganizationName-JobTitle`
+
+**Date Format**:
+- Use today's date from the system
+- Format: YYYY-MM-DD (e.g., 2025-11-02)
+
+**Name Sanitization**:
+- Remove or replace invalid filesystem characters: `/ \ : * ? " < > |`
+- Replace spaces with hyphens
+- Remove multiple consecutive hyphens
+- Trim leading/trailing hyphens
+- Limit total length to 100 characters for filesystem compatibility
+- If too long, truncate job title portion first, then organization name if needed
+
+**Examples**:
+- Input: "Tech Corp Inc. - Senior Software Engineer"
+- Output: `2025-11-02-Tech-Corp-Inc-Senior-Software-Engineer`
+
+- Input: "Company/Organization - Manager: Sales & Marketing"
+- Output: `2025-11-02-Company-Organization-Manager-Sales-Marketing`
+
+### 3. Handle Duplicate Folders
+
+If a folder with the generated name already exists:
+- Append a counter: `-2`, `-3`, etc.
+- Example: `2025-11-02-TechCorp-Developer-2`
+- Inform the user: "A folder for this application already exists. Created with suffix -2."
+
+## Folder Creation
+
+### 4. Create Directory Structure
+
+Create the following structure in `applications/pending/`:
+
+```
+applications/pending/[generated-folder-name]/
+├── application.md
+├── input/
+└── attachments/
+    └── .keep
+```
+
+Use these steps:
+1. Create the application folder: `applications/pending/[generated-folder-name]/`
+2. Create the `input/` subfolder inside it
+3. Create the `attachments/` subfolder inside it
+4. Create an empty `.keep` file inside `attachments/` folder for version control
+5. Create `application.md` from the template
+
+### 5. Create application.md
+
+Copy the template from `.claude/templates/application-template.md` to the new folder as `application.md`.
+
+**Update Metadata Section**:
+- Replace `[Auto-filled on creation]` in the Created field with current timestamp
+- Format: `YYYY-MM-DD HH:MM` (e.g., "2025-11-02 14:30")
+
+**Optional - Pre-fill Known Information**:
+If the user provided clear organization name and job title:
+- Fill in "Organization Name" field
+- Fill in "Job Title" field
+- Leave all other fields as placeholders for `/populate-application` to fill
+
+## User Confirmation
+
+### 6. Success Message
+
+After successfully creating the application, provide this output:
+
+```
+✅ New application created successfully!
+
+**Location**: applications/pending/[folder-name]/
+**Organization**: [Organization Name]
+**Position**: [Job Title]
+
+## Next Steps:
+
+1. **Add documents to the input folder**:
+   ```
+   applications/pending/[folder-name]/input/
+   ```
+
+   Add any of these documents:
+   - Job posting/advertisement (PDF, TXT, MD, DOCX)
+   - Recruiter emails or communications
+   - Company research notes
+   - Any other relevant context
+
+2. **Prepare attachments folder** (for later use):
+   ```
+   applications/pending/[folder-name]/attachments/
+   ```
+
+   This folder is for final documents ready to send:
+   - CV/Resume (PDF)
+   - Cover letter (PDF)
+   - Certificates and diplomas (PDF)
+
+   Note: Documents will be generated first, then you add them here before creating the application email.
+
+3. **Populate the application**:
+   Once you've added your documents, run:
+   ```
+   /populate-application
+   ```
+   This will analyze all input files and populate application.md with:
+   - Job requirements and keywords
+   - Company research and culture insights
+   - Match strategy (your relevant skills/experience)
+   - Suggested tone and key messages
+
+4. **Review and refine**:
+   After population, review `application.md` and add your own insights.
+
+5. **Generate documents**:
+   Use the populated application to generate tailored cover letter and email:
+   ```
+   /write-cover-letter
+   /write-application-email
+   ```
+
+---
+
+**Tip**: You can manually edit `application.md` at any time to add notes, ideas, or strategy thoughts.
+```
+
+## Error Handling
+
+### 7. Handle Edge Cases
+
+**If applications/pending/ doesn't exist**:
+- Create it automatically with parent directories
+- Inform user: "Created applications directory structure."
+
+**If template file is missing** (`.claude/templates/application-template.md`):
+- Create a basic application.md with minimal structure
+- Warn user: "Template file not found. Created basic application.md structure."
+
+**If filesystem errors occur**:
+- Provide clear error message
+- Suggest checking permissions or path length
+
+## Important Notes
+
+- Always use forward slashes (/) for paths, even on Windows (handled by tools)
+- Preserve the YYYY-MM-DD prefix for chronological sorting
+- Keep folder names readable - avoid cryptic abbreviations
+- The input/ folder should be empty initially - it's for the user to fill

src/.agent/workflows/populate-application.md

@@ -0,0 +1,393 @@
+---
+description: Analyze input documents and populate the application.md file with job information, research, and strategy.
+---
+
+# Instructions
+
+You are populating a job application by analyzing documents and cross-referencing with the applicant's profile.
+
+## Pre-flight Checks
+
+### 1. Verify Location
+
+**Check Current Directory**:
+- Verify you're inside an application folder (should be in `applications/pending/[application-name]/`)
+- Check if `application.md` exists in current directory
+- Check if `input/` subfolder exists
+
+**If NOT in correct location**:
+```
+❌ Not in an application folder
+
+Please navigate to an application folder first:
+cd applications/pending/[your-application-folder]/
+
+Then run /populate-application again.
+
+To see available applications:
+ls applications/pending/
+```
+
+**If application.md doesn't exist**:
+```
+❌ No application.md found
+
+This doesn't appear to be a valid application folder.
+Did you create this application with /new-application?
+```
+
+### 2. Check Input Folder
+
+**If input/ folder doesn't exist**:
+- Create it automatically
+- Inform user: "Created input/ folder. Please add documents before populating."
+
+**If input/ folder is empty**:
+```
+⚠️  Input folder is empty
+
+Please add documents to analyze:
+- Job posting/advertisement (PDF, TXT, MD, DOCX)
+- Recruiter emails or communications
+- Company research notes
+- Any other relevant context
+
+Add files to: ./input/
+
+Then run /populate-application again.
+```
+
+## Document Discovery & Analysis
+
+### 3. List Input Files
+
+Scan the `input/` folder and categorize files:
+
+**Supported Formats**:
+- PDF files (`.pdf`) - Read using Read tool (has built-in PDF support)
+- Text files (`.txt`, `.md`, `.markdown`)
+- Document files (`.docx`) - Try to read as best as possible
+- Email files (`.eml`, `.msg`) - Extract as text
+- HTML files (`.html`, `.htm`)
+
+**Unsupported Formats** (warn but skip):
+- Images (`.jpg`, `.png`, `.gif`) - "Cannot extract text from images"
+- Videos, audio, archives, executables
+
+**Output file list**:
+```
+📄 Found [N] documents in input/ folder:
+
+Supported:
+✓ job-posting.pdf
+✓ recruiter-email.txt
+✓ company-research.md
+
+Skipped (unsupported format):
+⊘ company-logo.png
+```
+
+### 4. Read All Supported Files
+
+For each supported file:
+1. Use the Read tool to extract content
+2. Note the filename for reference
+3. If a file fails to read, skip it with a warning
+
+### 5. Analyze Job Information
+
+**Extract from job postings/descriptions**:
+
+**Organization Information**:
+- Company name
+- Industry/sector
+- Location (city, country, remote options)
+- Company size (if mentioned)
+- Website or apply URL
+
+**Job Details**:
+- Job title
+- Job level (Junior, Mid, Senior, Lead, Manager, etc.)
+- Department or team
+- Employment type (Full-time, Part-time, Contract, Freelance)
+- Salary range (if mentioned)
+- Remote/hybrid/on-site requirements
+
+**Job Description**:
+- Key responsibilities (extract 5-10 main duties)
+- Required skills and qualifications
+- Preferred/nice-to-have skills
+- Required experience (years, specific domains)
+- Education requirements
+- Certifications or licenses
+
+**Keywords**:
+- Extract important keywords for ATS optimization
+- Programming languages, frameworks, tools mentioned
+- Industry-specific terms
+- Soft skills mentioned
+
+**Company Culture Indicators**:
+- Language tone (formal, casual, enthusiastic)
+- Values mentioned (innovation, collaboration, diversity, etc.)
+- Benefits and perks mentioned
+- Work environment description
+
+### 6. Analyze Additional Documents
+
+**From recruiter emails**:
+- Recruiter/contact person name and email
+- Timeline and deadlines
+- Special instructions or requirements
+- Salary expectations or discussions
+- Interview process details
+
+**From research notes**:
+- Company news, funding, acquisitions
+- Product launches or initiatives
+- Company culture insights
+- Employee reviews or Glassdoor data
+- Competitive landscape
+
+## Profile Cross-Reference
+
+### 7. Read Applicant Profile
+
+Read `profile.md` (in the framework root directory) to understand the applicant's background.
+
+**If profile.md doesn't exist or is incomplete**:
+```
+⚠️  Profile not found or incomplete
+
+Your profile.md should be filled out for best results.
+Run /validate-profile to check your profile status.
+
+Continuing with job analysis only (without personalized matching).
+```
+
+### 8. Match Analysis
+
+**IF profile is available**, analyze matches:
+
+**Experience Matching**:
+- Which work experiences from profile align with job requirements?
+- Which responsibilities overlap?
+- Which achievements are most relevant?
+
+**Skills Matching**:
+- Which technical skills match required skills?
+- Which soft skills align with the role?
+- Which tools/technologies match?
+
+**Projects Matching**:
+- Which projects demonstrate relevant capabilities?
+- Which projects solve similar problems?
+
+**Gap Analysis**:
+- What required skills are missing from profile?
+- Can any gaps be filled with transferable skills?
+- What learning or growth opportunities does this role present?
+
+**Recommendations**:
+- Which experiences to emphasize in CV?
+- Which projects to highlight?
+- Which achievements to feature prominently?
+- Stories or examples from profile that demonstrate required skills?
+
+## Population Strategy
+
+### 9. Check Existing Content
+
+Before populating, read current `application.md`:
+- Check which sections already have content
+- Identify manually added notes or insights
+- Determine which sections need population
+
+### 10. Populate application.md
+
+**Update each section intelligently**:
+
+**Metadata**:
+- Update status if appropriate
+- Add deadline if found in documents
+
+**Organization Information**:
+- Fill in company name, industry, location, website, contact person
+- Only overwrite `[To be filled]` placeholders, preserve manually entered data
+
+**Job Information**:
+- Fill in job title, level, department, employment type, remote status
+- Only overwrite placeholders
+
+**Job Description Summary**:
+- Add key responsibilities (bulleted list)
+- Add required skills (bulleted list)
+- Add preferred skills (bulleted list)
+- Add extracted keywords
+
+**Research Notes**:
+- Add company culture observations
+- Add recent news/developments
+- If user has manual notes, ADD to them (don't replace)
+
+**Match Strategy** (only if profile is available):
+- List relevant experiences to emphasize
+- Map required skills to applicant's skills
+- List projects to highlight
+- Identify gaps and suggest how to address them
+
+**Key Messages**:
+- Suggest 3-5 main points to convey in application
+- Base these on match analysis
+
+**Tone of Voice**:
+- Assess appropriate tone (Formal/Balanced/Casual)
+- Provide reasoning based on job posting language
+- Suggest example phrases
+
+**Document Checklist**:
+- Check appropriate boxes based on application requirements
+
+### 11. Preserve Manual Content
+
+**IMPORTANT**:
+- Do NOT overwrite manually entered content
+- If a section has user-written notes, ADD analysis below them with a separator
+- Add a timestamp comment: `<!-- Auto-populated on YYYY-MM-DD HH:MM -->`
+- Mark auto-populated sections clearly
+
+**Example**:
+```markdown
+## Research Notes
+
+<!-- User's manual notes -->
+I really like their commitment to open source.
+
+---
+
+<!-- Auto-populated on 2025-11-02 14:30 -->
+### Company Culture & Values
+Based on job posting analysis:
+- Emphasizes collaboration and innovation
+- Values work-life balance (mentions flexible hours)
+- Strong focus on diversity and inclusion
+```
+
+### 12. Interactive Prompts
+
+**Ask for missing critical information**:
+
+If critical fields cannot be determined:
+```
+Some information couldn't be extracted from the documents.
+Please provide the following:
+
+1. Job Title: [Current extracted value or "Unknown"]
+2. Organization Name: [Current extracted value or "Unknown"]
+
+Would you like to provide this now? (Or leave as-is to fill manually later)
+```
+
+**Confirm before major changes**:
+
+If application.md already has significant content:
+```
+⚠️  This application already has populated content.
+
+Would you like to:
+1. **Merge** - Add new analysis alongside existing content (recommended)
+2. **Replace** - Overwrite with new analysis (will preserve metadata)
+3. **Cancel** - Don't make changes
+
+Choice: [Ask user to respond]
+```
+
+## Completion
+
+### 13. Summary Report
+
+After successful population:
+
+```
+✅ Application populated successfully!
+
+## Analyzed Documents:
+- job-posting.pdf
+- recruiter-email.txt
+- company-research.md
+
+## Extracted Information:
+✓ Organization: [Company Name]
+✓ Position: [Job Title]
+✓ Key Requirements: [N] identified
+✓ Keywords: [N] extracted
+✓ Company Culture: [Tone assessment]
+
+## Profile Matching:
+✓ Relevant Experience: [N] positions identified
+✓ Skills Match: [N/M] required skills matched
+✓ Projects to Highlight: [N] projects suggested
+✓ Potential Gaps: [N] areas for development
+
+## Updated Sections:
+✓ Organization Information
+✓ Job Information
+✓ Job Description Summary
+✓ Research Notes
+✓ Match Strategy
+✓ Key Messages
+✓ Tone of Voice
+
+## Next Steps:
+
+1. **Review application.md**:
+   Open and review the populated information for accuracy.
+
+2. **Add your insights**:
+   Enhance sections with your own thoughts and strategy.
+
+3. **Refine match strategy**:
+   Adjust which experiences and projects to emphasize.
+
+4. **Validate application**:
+   Run /validate-application to ensure completeness before document generation.
+
+5. **Generate documents** (coming soon):
+   Once validation passes, generate tailored CV and cover letter.
+
+---
+
+**Tip**: You can re-run /populate-application after adding more documents to input/.
+The analysis will be merged with existing content.
+```
+
+## Error Handling
+
+**If files cannot be read**:
+- Skip the file
+- Warn: "Could not read [filename]. Continuing with other files."
+
+**If no useful information extracted**:
+```
+⚠️  Limited information extracted
+
+The documents in input/ didn't contain clear job information.
+Please check:
+- Do you have the job posting/description?
+- Are the files readable (not corrupted)?
+- Is the text extractable (not image-only PDFs)?
+
+You can manually fill in application.md or add more documents.
+```
+
+**If profile analysis fails**:
+- Continue with job analysis only
+- Warn: "Could not analyze profile matching. Consider running /validate-profile."
+
+## Important Notes
+
+- Be thorough but not overwhelming - prioritize the most relevant information
+- Preserve user's manual work - they may have important insights
+- Be honest about gaps and limitations
+- Provide actionable next steps
+- Always leave the user in control - they can manually edit anything

src/.agent/workflows/validate-application.md

@@ -0,0 +1,387 @@
+---
+description: Validate that `application.md` is completely filled out and ready for document generation.
+---
+
+# Instructions
+
+You are validating a job application to ensure it's ready for generating tailored CV, cover letter, and email.
+
+## Step 1: Location Detection
+
+### Determine Which Application to Validate
+
+**If NO parameter provided:**
+1. Check current working directory
+2. Verify if you're inside an application folder by checking:
+   - Path pattern: ends with `applications/pending/[folder-name]/`
+   - File existence: `application.md` exists in current directory
+3. If yes → validate this application
+4. If no → show error with available applications (see Error Handling section)
+
+**If parameter PROVIDED:**
+1. Parameter can be:
+   - Folder name: `2025-11-02-TechCorp-Developer`
+   - Relative path: `applications/pending/2025-11-02-TechCorp-Developer`
+   - Absolute path: `/full/path/to/application/folder`
+2. Resolve to application folder: `applications/pending/[folder-name]/`
+3. Check if `application.md` exists in that location
+4. If yes → validate that application
+5. If no → show error with available applications
+
+### Error Handling: Wrong Location / Not Found
+
+**If running from wrong location without parameter:**
+```
+❌ Not in an application folder
+
+Please either:
+1. Navigate to an application folder:
+   cd applications/pending/[application-folder]/
+   /validate-application
+
+2. Or provide the application folder name:
+   /validate-application [application-folder-name]
+
+Available applications:
+[List output of: ls applications/pending/]
+
+Example:
+/validate-application 2025-11-02-TechCorp-Developer
+```
+
+**If application doesn't exist with parameter:**
+```
+❌ Application not found: [provided-name]
+
+Available applications:
+[List output of: ls applications/pending/]
+
+Usage:
+/validate-application [folder-name]
+```
+
+**If application.md missing in found folder:**
+```
+❌ No application.md found in [path]
+
+This doesn't appear to be a valid application folder.
+Did you create this application with /new-application?
+```
+
+## Step 2: Read application.md
+
+Read the entire `application.md` file in the detected/specified application folder.
+
+**If file is corrupted or unreadable:**
+```
+❌ Could not read application.md
+
+The file exists but cannot be read. It may be corrupted or have permission issues.
+Please check the file: [full-path-to-application.md]
+```
+
+## Step 3: Parse Sections
+
+Extract content for each section by markdown headings. Recognize sections case-insensitively:
+
+**Required Sections** (validation checks these):
+- "Organization Information" / "organization information"
+- "Job Information" / "job information"
+- "Job Description Summary" / "job description summary"
+
+**Optional Sections** (don't cause validation failure):
+- Match Strategy
+- Key Messages
+- Tone of Voice
+- Research Notes
+- Document Checklist
+- Application Strategy Notes
+- Timeline
+- Metadata
+
+## Step 4: Detect Placeholders
+
+Check for these placeholder patterns that indicate incomplete data:
+
+### Placeholder Patterns
+
+**Square brackets:**
+- `[To be filled]`
+- `[Organization name]`
+- `[Job Title]`
+- `[Company Name]`
+- `[...]`
+- `[Any text in brackets]`
+
+**Generic template text:**
+- "Add information here"
+- "To be filled"
+- Text that matches the template unchanged
+
+### Context-Aware Detection
+
+**DO flag as placeholders:**
+- `[To be filled]`
+- `[Company Name]`
+- `[Job Title]` as the only content
+- `[Organization name here]`
+
+**DON'T flag as placeholders:**
+- `[PhD]` after a name in context
+- `[Acquired by Google]` in a company description
+- `[Remote]` as a job location descriptor
+- Other brackets used meaningfully in normal text
+
+If placeholder text is longer than 100 characters, truncate it in the error message: `"[First 100 chars...]"`
+
+## Step 5: Validate Required Sections
+
+### Organization Information
+
+**Must have:**
+- Organization Name field with real content (not placeholder)
+
+**Check:**
+- Look for "Organization Name:", "Company:", or similar field labels
+- Extract the value after the label
+- Check if value contains placeholders
+- Check if value is empty or only whitespace
+
+**If incomplete:**
+- Flag: `Organization Name: Contains placeholder "[exact-text]"`
+- Or: `Organization Name: Missing or empty`
+
+### Job Information
+
+**Must have:**
+- Job Title field with real content (not placeholder)
+
+**Check:**
+- Look for "Job Title:", "Position:", or similar field labels
+- Extract the value after the label
+- Check if value contains placeholders
+- Check if value is empty or only whitespace
+
+**If incomplete:**
+- Flag: `Job Title: Contains placeholder "[exact-text]"`
+- Or: `Job Title: Missing or empty`
+
+### Job Description Summary
+
+**Must have:**
+- At least SOME content in one or more subsections:
+  - Responsibilities / Key Responsibilities
+  - Required Skills / Qualifications
+  - Preferred Skills
+  - Requirements
+  - Keywords
+
+**Check:**
+- Verify section exists
+- Check if section has any real content (not just placeholders)
+- Check if at least one subsection has meaningful text
+
+**If incomplete:**
+- Flag: `Job Description Summary: No content found`
+- Or: `Responsibilities: Contains placeholder "[exact-text]"`
+- Or: `Required Skills: Missing or empty`
+
+### Missing Sections
+
+If an entire required section is missing from the document:
+- Flag: `Missing required section: [Section Name]`
+
+## Step 6: Check Population Status
+
+### Input Folder Check
+
+**Check if `input/` folder exists and has files:**
+
+1. Check for `input/` subfolder in the application directory
+2. List files in `input/` folder
+3. Count supported files (exclude .gitkeep, .DS_Store, etc.)
+
+**Categorize status:**
+- **Empty**: `input/` doesn't exist or has no files (0 files)
+- **Populated**: `input/` has 1+ files
+- **Not applicable**: Required sections are filled (manual population is fine)
+
+### Population Warning Logic
+
+**Warn about population IF:**
+- Input folder is empty (0 files) AND
+- Multiple required sections still have placeholders
+
+**Suggest /populate-application IF:**
+- Input folder has files (1+ files) AND
+- Multiple required sections still have placeholders
+
+**DON'T warn IF:**
+- Required sections are filled with real content (manual population is fine, even if input/ is empty)
+
+## Step 7: Generate Validation Report
+
+### Success Format (Validation PASSES)
+
+**If all required sections are complete:**
+
+```
+✅ Application Validation: PASSED
+
+Your application is complete and ready for document generation!
+
+Summary:
+- Organization: [Extracted Company Name]
+- Position: [Extracted Job Title]
+- Job requirements: [N] identified
+- Input documents: [N] files in input/ folder
+[If Match Strategy section has content:]
+- Match strategy: Complete
+[If Key Messages section has content:]
+- Key messages: Defined
+
+You can now proceed with generating tailored CV, cover letter, and application email.
+```
+
+**Extract actual values** from application.md for the summary (organization name, position, count requirements/skills mentioned).
+
+### Failure Format (Validation FAILS)
+
+**If any required section is incomplete:**
+
+```
+❌ Application Validation: FAILED
+
+Your application has incomplete sections that need attention before document generation.
+
+Issues found:
+
+[Group errors by section - only show sections with errors]
+
+## Organization Information
+- [ ] Organization Name: Contains placeholder "[To be filled]"
+
+## Job Information
+- [ ] Job Title: Missing or empty
+
+## Job Description Summary
+- [ ] Responsibilities: Contains placeholder "[List key responsibilities]"
+- [ ] Required Skills: No content found
+
+[If population warning applies:]
+
+## Population Status
+⚠️  Input folder appears empty. Consider:
+1. Adding job posting and related documents to input/
+2. Running /populate-application to extract information
+
+[Or if input has files but sections empty:]
+
+## Population Status
+⚠️  Input folder has [N] documents but application seems unpopulated.
+Consider running:
+   /populate-application
+
+This will analyze your input documents and populate the sections above.
+
+[End with guidance:]
+
+Please update application.md to fill in these sections, then run /validate-application again.
+
+[Alternative if only placeholders:]
+Or manually edit application.md to add the missing information, then run /validate-application again.
+```
+
+### Error Details Format
+
+**For each issue, use checkbox format:**
+```
+- [ ] Field Name: Issue description
+```
+
+**Quote exact placeholder text:**
+```
+- [ ] Organization Name: Contains placeholder "[To be filled]"
+```
+
+**Group by section:**
+```
+## Organization Information
+- [ ] Organization Name: Issue
+- [ ] Location: Issue
+
+## Job Description Summary
+- [ ] Responsibilities: Issue
+```
+
+## Step 8: Provide Clear Next Steps
+
+### After Success
+
+```
+You can now proceed with generating tailored CV, cover letter, and application email.
+```
+
+### After Failure
+
+```
+Please update application.md to fill in these sections, then run /validate-application again.
+```
+
+Or if they should run population:
+```
+Add documents to input/ folder and run /populate-application to analyze and populate application.md.
+Then run /validate-application again to confirm completeness.
+```
+
+## Important Notes
+
+### Tone
+- Be encouraging - validation is a positive quality check
+- Be specific about what's missing
+- Provide actionable guidance
+- Don't be judgmental about incomplete applications
+
+### Flexibility
+- Optional sections can remain incomplete
+- Manual population is perfectly fine (don't require /populate-application if sections are filled)
+- Input folder can be empty if user manually populated
+- Focus on required information only
+
+### Accuracy
+- Quote exact placeholder text when reporting issues
+- Extract real values from application.md for success summary
+- Count actual items (requirements, skills, documents)
+- Be precise about what's missing vs what's present
+
+### Integration
+- This is a quality gate before document generation
+- Match the pattern of `/validate-profile` for consistency
+- User can explicitly skip validation if they want (with warning)
+- Default behavior: validate before generating any documents
+
+## Edge Cases
+
+### Legitimate Brackets
+- `[PhD]` or `[MBA]` in credentials → not a placeholder
+- `[Remote]` as location descriptor → not a placeholder
+- `[Acquired]` in company history → not a placeholder
+- Check surrounding context to distinguish
+
+### Partial Completion
+- If Organization Name is filled but Job Title has placeholder → only flag Job Title
+- If some job description subsections are filled → validation can pass
+- Don't require ALL subsections, just SOME content
+
+### Very Long Placeholders
+- Truncate to 100 characters: `"[First 100 characters...]"`
+- Still quote them to show what was found
+
+### Multiple Issues in Same Field
+- List each issue separately
+- Be clear about what specifically is wrong
+
+### Application Already Has Some Content
+- Focus error messages only on what's still missing
+- Acknowledge what's already complete in summary (if desired)
+- Be constructive about gaps

src/.agent/workflows/validate-profile.md

@@ -0,0 +1,110 @@
+---
+description: Validate that `profile.md` is completely filled out and ready for generating job applications.
+---
+
+# Instructions
+
+You are validating the applicant's profile to ensure it's ready for job application generation.
+
+## Validation Rules
+
+### 1. Read the Profile
+- Read `profile.md` in its entirety
+
+### 2. Detect Placeholder Patterns
+
+Check for these placeholder patterns that indicate incomplete data:
+- Text in square brackets: `[Your name]`, `[Company]`, `[anything]`
+- Generic template text: "Your professional summary here"
+- Example text that hasn't been replaced
+
+### 3. Required Sections
+
+These sections MUST be complete (no placeholders):
+
+**Personal Information:**
+- Full Name
+- Email
+- Phone
+- Location
+
+**Professional Summary:**
+- Must contain a real 2-3 sentence summary (not placeholder text)
+
+**Work Experience:**
+- At least ONE complete work experience entry with:
+  - Real job title and company name (not `[Job Title]` or `[Company Name]`)
+  - Real dates (not `[Month Year]`)
+  - At least one real responsibility or achievement
+
+### 4. Optional Sections
+
+These sections CAN be empty or contain placeholders without causing validation failure:
+- Projects
+- Certifications
+- Additional work experiences beyond the first one
+- Languages (if only one language)
+- Portfolio/Website in Personal Information
+- GitHub in Personal Information
+
+### 5. Output Format
+
+Provide a clear validation report:
+
+**If validation PASSES:**
+```
+✅ Profile Validation: PASSED
+
+Your profile is complete and ready for job application generation!
+
+Summary:
+- Personal information: Complete
+- Professional summary: Complete
+- Work experience: X entries found
+- Education: X entries found
+- Skills: Categorized and complete
+
+You can now proceed with generating CVs, cover letters, and application emails.
+```
+
+**If validation FAILS:**
+```
+❌ Profile Validation: FAILED
+
+Your profile has incomplete sections that need attention before generating applications.
+
+Issues found:
+
+## Personal Information
+- [ ] Full Name: Contains placeholder "[Your full name]"
+- [ ] Email: Contains placeholder "[your.email@example.com]"
+
+## Professional Summary
+- [ ] Summary text is still the default placeholder
+
+## Work Experience
+- [ ] No complete work experience entries found
+- [ ] First entry contains placeholders: [Job Title], [Company Name]
+
+Please update profile.md to fill in these sections with your real information, then run /validate-profile again.
+```
+
+### 6. Be Specific
+
+When reporting issues:
+- Quote the exact placeholder text found
+- Indicate which section it's in
+- Provide actionable guidance on what needs to be filled in
+
+### 7. Handle Edge Cases
+
+- **Legitimate brackets**: If someone has `[PhD]` after their name or `[Company] (Acquired)`, don't flag these as placeholders if they're in context
+- **Partial completion**: If most fields are filled but one or two have placeholders, list only the incomplete ones
+- **Multiple issues in one section**: List each placeholder separately
+
+## Important Notes
+
+- Be encouraging in your tone - validating a profile is a positive step
+- If validation fails, provide clear next steps
+- Don't generate any application documents if validation fails (unless user explicitly requests to skip validation)
+- This validation is a safety check to prevent placeholder text from appearing in professional documents

src/.agent/workflows/write-application-email.md

@@ -0,0 +1,650 @@
+---
+description: Generate a professional application email with subject line and document references.
+---
+
+# Instructions
+
+You are generating a professional application email for a job application. This email must be brief, professional, and include proper references to attached documents.
+
+## Step 1: Parse Command Arguments
+
+Check for optional flags and parameters:
+
+**Flags:**
+- `--skip-validation`: Skip automatic validation check
+- `--force` or `--overwrite`: Overwrite existing application-email.md if it exists
+- `--help`: Show usage information and exit
+
+**Parameter:**
+- Application folder name (optional): e.g., `2025-11-02-TechCorp-Developer`
+
+If `--help` flag is present, show usage and exit:
+```
+Usage: /write-application-email [application-name] [flags]
+
+Generates a professional application email with document references.
+
+Options:
+  [application-name]     Optional. Name of application folder.
+                         If omitted, uses current directory.
+
+  --skip-validation      Skip automatic validation check (not recommended)
+  --force, --overwrite   Overwrite existing application-email.md
+  --help                 Show this help message
+
+Examples:
+  /write-application-email
+  /write-application-email 2025-11-02-TechCorp-Developer
+  /write-application-email --force
+  /write-application-email --skip-validation --force
+
+The command will:
+1. Validate the application (unless --skip-validation)
+2. Check if email already exists (unless --force)
+3. Verify required documents exist in attachments/ folder
+4. Read profile.md and application.md
+5. Generate a brief professional email with subject line
+6. Save to application-email.md in the application folder
+```
+
+## Step 2: Location Detection
+
+### Determine Target Application
+
+**If NO parameter provided:**
+1. Check current working directory
+2. Verify if inside an application folder:
+   - Path pattern: ends with `applications/pending/[folder-name]/`
+   - File existence: `application.md` exists in current directory
+3. If yes → use this application
+4. If no → show error with available applications
+
+**If parameter PROVIDED:**
+1. Resolve to application folder: `applications/pending/[folder-name]/`
+2. Check if `application.md` exists in that location
+3. If yes → use that application
+4. If no → show error with available applications
+
+### Error: Location Unclear
+
+```
+❌ Not in an application folder
+
+Please either:
+1. Navigate to an application folder:
+   cd applications/pending/[application-folder]/
+   /write-application-email
+
+2. Or provide the application folder name:
+   /write-application-email [application-folder-name]
+
+Available applications:
+[List output of: ls applications/pending/]
+
+Example:
+/write-application-email 2025-11-02-TechCorp-Developer
+```
+
+### Error: Application Not Found
+
+```
+❌ Application not found: [provided-name]
+
+Available applications:
+[List output of: ls applications/pending/]
+```
+
+## Step 3: Automatic Validation Check
+
+**Unless `--skip-validation` flag is present**, run validation before generating.
+
+### Run Validation
+
+1. Show progress: `🔍 Validating application...`
+2. Execute `/validate-application` for the target application
+3. Capture result (pass/fail)
+
+### Handle Validation Result
+
+**If validation PASSES:**
+```
+✅ Application validation passed
+```
+Proceed to Step 4.
+
+**If validation FAILS:**
+```
+❌ Application validation failed
+
+Your application has incomplete sections. Please fix these issues first:
+
+[Show validation error details]
+
+Options:
+1. Fix the issues in application.md and try again
+2. Run /validate-application for full details
+3. Use --skip-validation to proceed anyway (not recommended)
+
+Example:
+/write-application-email --skip-validation
+```
+STOP. Do not generate email.
+
+### Skip Validation Warning
+
+**If `--skip-validation` flag is present:**
+```
+⚠️  Skipping validation check (not recommended)
+
+Proceeding with email generation. The application may have incomplete sections.
+```
+Proceed to Step 4.
+
+## Step 4: Check for Existing Email
+
+Check if `application-email.md` exists in the application folder.
+
+### If File Exists (and --force NOT present)
+
+```
+❌ Application email already exists
+
+File: [path-to-application-email.md]
+
+To regenerate, use:
+/write-application-email --force
+
+⚠️  Warning: This will overwrite your existing email.
+If you've made manual edits, they will be lost.
+```
+STOP. Do not overwrite.
+
+### If File Exists (and --force IS present)
+
+```
+⚠️  Overwriting existing application email
+
+File: [path-to-application-email.md]
+Your previous email will be replaced.
+```
+Proceed to Step 5.
+
+### If File Does Not Exist
+
+Proceed to Step 5 (no message needed).
+
+## Step 5: Verify Documents in Attachments Folder
+
+**CRITICAL**: The email will reference attached documents. Verify they exist in the `attachments/` folder.
+
+Show progress: `📎 Verifying attachments...`
+
+### Check Attachments Folder
+
+1. Verify `attachments/` folder exists in application directory
+2. List all files in `attachments/` folder (excluding `.keep`)
+3. Categorize files by type:
+   - **CV/Resume**: Files containing "cv", "resume", "lebenslauf" in filename (case-insensitive)
+   - **Cover Letter**: Files containing "cover", "letter", "anschreiben", "motivationsschreiben" in filename (case-insensitive)
+   - **Certificates**: Files containing "certificate", "diploma", "zeugnis", "zertifikat" in filename (case-insensitive)
+   - **Other**: Any other PDF or document files
+
+### Required Documents Check
+
+**Minimum requirements:**
+- At least one CV/Resume file
+- At least one Cover Letter file
+
+**If attachments/ folder doesn't exist:**
+```
+❌ Attachments folder not found
+
+The attachments/ folder is missing. This might be an old application.
+
+To fix:
+1. Create the folder: mkdir attachments
+2. Add your documents (CV, cover letter, certificates)
+3. Try again
+
+Expected location: [application-path]/attachments/
+```
+STOP.
+
+**If folder is empty (only .keep file or no files):**
+```
+❌ No documents found in attachments folder
+
+The attachments/ folder is empty. You need to add documents before generating the email.
+
+Required documents:
+- ✗ CV/Resume (PDF) - Not found
+- ✗ Cover letter (PDF) - Not found
+
+Optional documents:
+- Certificates/Diplomas (PDF)
+
+Location: [application-path]/attachments/
+
+Please add your documents and try again.
+```
+STOP.
+
+**If CV is missing:**
+```
+❌ CV/Resume not found in attachments folder
+
+Required documents:
+- ✗ CV/Resume (PDF) - Not found
+- ✓ Cover letter - Found: [filename]
+
+Please add your CV to:
+[application-path]/attachments/
+
+Tip: Filename should contain "cv", "resume", or "lebenslauf"
+Example: John_Doe_CV.pdf
+```
+STOP.
+
+**If Cover Letter is missing:**
+```
+❌ Cover letter not found in attachments folder
+
+Required documents:
+- ✓ CV/Resume - Found: [filename]
+- ✗ Cover letter (PDF) - Not found
+
+Please add your cover letter to:
+[application-path]/attachments/
+
+Tip: Filename should contain "cover-letter" or "anschreiben"
+Example: John_Doe_Cover_Letter.pdf
+```
+STOP.
+
+**If all required documents found:**
+```
+✓ Found attachments:
+  - CV: [filename]
+  - Cover Letter: [filename]
+  [- Certificates: [filename(s)] (if any)]
+```
+Proceed to Step 6.
+
+## Step 6: Read Data Sources
+
+Show progress: `📝 Generating application email...`
+
+### Read profile.md
+
+1. Check if `profile.md` exists in framework root
+2. Read entire file
+3. Parse and extract:
+   - **Personal Information**: Full name, email, phone
+   - For email signature and sender information
+
+**If profile.md is missing or unreadable:**
+```
+❌ Profile not found
+
+Could not read profile.md. Please create and validate your profile first.
+
+Steps:
+1. Fill out profile.md with your information
+2. Run /validate-profile to check completeness
+3. Try /write-application-email again
+```
+STOP.
+
+Show progress: `✓ Read profile.md (applicant info)`
+
+### Read application.md
+
+1. Check if `application.md` exists in application folder
+2. Read entire file
+3. Parse and extract:
+   - **Organization Information**: Company name, contact person name, contact email
+   - **Job Information**: Job title, job level
+   - **Tone of Voice**: Tone assessment (Formal/Balanced/Casual)
+   - **Key Messages**: Main points (for reference, though email is brief)
+
+**If application.md is missing or unreadable:**
+```
+❌ Application not found
+
+Could not read application.md in [path].
+
+This doesn't appear to be a valid application folder.
+Did you create this application with /new-application?
+```
+STOP.
+
+Show progress: `✓ Read application.md (job details)`
+
+## Step 7: Determine Language and Tone
+
+### Detect Language
+
+Check these indicators in order:
+1. **Job posting language** (if job description in input/ was in German)
+2. **Company location** (if Germany/Austria/Switzerland → likely German)
+3. **Application.md language** (if written in German → use German)
+4. **Default**: English if unclear
+
+### Extract Tone
+
+From application.md "Tone of Voice" section:
+- Look for: "Formal", "Balanced", or "Casual"
+- Default to "Balanced" if not specified
+
+Show progress: `✓ Applied tone: [Formal/Balanced/Casual]`
+Show progress: `✓ Language: [German/English]`
+
+## Step 8: Generate Email Content
+
+Generate a professional application email. Target: **Brief and concise (3-4 sentences in body)**.
+
+### Structure Overview
+
+1. Subject Line
+2. Greeting/Salutation
+3. Email Body (3-4 sentences)
+4. Sign-off and Signature
+
+---
+
+### Subject Line
+
+**Purpose**: Clear, professional, immediately conveys the purpose.
+
+**Format for German:**
+```
+Bewerbung als [Job Title] - [Applicant Full Name]
+```
+
+**Format for English:**
+```
+Application for [Job Title] - [Applicant Full Name]
+```
+
+**Examples:**
+- German: `Bewerbung als Senior Software Engineer - Max Mustermann`
+- English: `Application for Senior Software Engineer - John Doe`
+
+---
+
+### Greeting/Salutation
+
+**If contact person name is available in application.md:**
+- German: `Sehr geehrte/r [Herr/Frau] [Last Name],` or `Liebe/r [First Name],` (Casual tone only)
+- English: `Dear [Mr./Ms./Dr.] [Last Name],` or `Dear [First Name],` (Casual tone only)
+
+**If no contact person:**
+- German: `Sehr geehrte Damen und Herren,`
+- English: `Dear Hiring Manager,`
+
+---
+
+### Email Body (3-4 sentences maximum)
+
+**Purpose**: Brief introduction, state purpose, reference documents, express interest.
+
+**Content elements:**
+1. **Opening**: State you're applying for the specific position
+2. **Documents**: Explicitly mention attached documents (CV, cover letter, and certificates if present)
+3. **Brief interest**: One sentence showing genuine interest or fit
+4. **Availability**: Mention availability for interview/discussion
+
+**Tone guidance:**
+- **Formal**: Professional and respectful, traditional business language
+- **Balanced**: Professional but warm, straightforward
+- **Casual**: Friendly and approachable, but still professional
+
+**IMPORTANT**: Keep it concise. The cover letter contains the details; the email is just a brief cover message.
+
+**Example (Balanced, English):**
+> I am writing to apply for the Senior Software Engineer position at TechCorp. Please find attached my CV, cover letter, and relevant certificates for your review. I have eight years of experience in backend development and am particularly interested in your work on cloud infrastructure. I am available for an interview at your convenience.
+
+**Example (Formal, German):**
+> hiermit bewerbe ich mich um die Position als Senior Software Engineer bei TechCorp. Im Anhang finden Sie meinen Lebenslauf, mein Anschreiben sowie relevante Zeugnisse. Mit acht Jahren Erfahrung in der Backend-Entwicklung interessiere ich mich besonders für Ihre Arbeit im Bereich Cloud-Infrastruktur. Für ein Vorstellungsgespräch stehe ich Ihnen gerne zur Verfügung.
+
+**Example (Casual, English):**
+> I'm applying for the Senior Software Engineer position at TechCorp. I've attached my CV, cover letter, and certificates for you to review. I've been working in backend development for about eight years and find your cloud infrastructure work really interesting. I'm happy to chat whenever works for you.
+
+**Document Reference Variations:**
+
+*If CV and Cover Letter only:*
+- German: `Im Anhang finden Sie meinen Lebenslauf und mein Anschreiben.`
+- English: `Please find attached my CV and cover letter.`
+
+*If CV, Cover Letter, and Certificates:*
+- German: `Im Anhang finden Sie meinen Lebenslauf, mein Anschreiben sowie relevante Zeugnisse.`
+- English: `Please find attached my CV, cover letter, and relevant certificates.`
+
+---
+
+### Sign-off and Signature
+
+**German:**
+- Formal: `Mit freundlichen Grüßen,`
+- Balanced: `Mit freundlichen Grüßen,`
+- Casual: `Viele Grüße,`
+
+**English:**
+- Formal: `Sincerely,` or `Best regards,`
+- Balanced: `Best regards,`
+- Casual: `Best regards,` or `Kind regards,`
+
+Follow with applicant's full name and contact information from profile.md:
+```
+[Applicant Full Name]
+[Email]
+[Phone]
+```
+
+---
+
+## Step 9: Format and Write File
+
+### Format as Markdown
+
+```markdown
+<!--
+Application Email
+Generated: [YYYY-MM-DD HH:MM]
+Sources: profile.md, application.md, attachments/
+Language: [German/English]
+Tone: [Formal/Balanced/Casual]
+-->
+
+# Subject
+
+[Subject Line]
+
+---
+
+[Greeting]
+
+[Email Body - 3-4 sentences]
+
+[Sign-off]
+[Applicant Full Name]
+[Email]
+[Phone]
+
+---
+
+## Attachments
+
+[List of files in attachments/ folder to be sent:]
+- [CV filename]
+- [Cover letter filename]
+- [Certificate filename(s)] (if any)
+```
+
+### Write to File
+
+1. Write content to `application-email.md` in the application folder
+2. Handle write errors gracefully:
+   - Permission denied: "Could not save application-email.md. Check write permissions."
+   - Disk full: "Could not save application-email.md. Check available disk space."
+   - Other errors: "Could not save application-email.md: [error details]"
+
+## Step 10: Success Output
+
+Display success message:
+
+```
+✅ Application email saved: application-email.md
+
+## Generation Summary:
+
+📊 Email Details:
+- Language: [German/English]
+- Tone: [Formal/Balanced/Casual]
+- Subject: [Generated subject line]
+- Attachments referenced: [N] files
+
+📍 Location:
+[full or relative path to application-email.md]
+
+📎 Attachments Ready:
+- ✓ [CV filename]
+- ✓ [Cover letter filename]
+[- ✓ [Certificate filename(s)]] (if any)
+
+## Next Steps:
+
+1. **Review application-email.md**:
+   Open and read the email. Verify:
+   - Subject line is appropriate
+   - All attachments are correctly listed
+   - Tone matches the company culture
+   - Contact information is correct
+
+2. **Prepare email in your client**:
+   - Copy subject line from the file
+   - Copy email body
+   - Attach the documents from attachments/ folder:
+     [List each file with checkboxes]
+     □ [CV filename]
+     □ [Cover letter filename]
+     [□ [Certificate filename(s)]] (if any)
+
+3. **Final checks before sending**:
+   - Verify recipient email address
+   - Double-check all attachments are included
+   - Proofread one last time
+   - Ensure file names are professional
+
+---
+
+**Tip**: This email is intentionally brief. The cover letter contains the detailed information about your qualifications and interest in the role.
+```
+
+## Error Handling Reference
+
+### Missing profile.md
+
+```
+❌ Profile not found
+
+Could not read profile.md. Please create and validate your profile first.
+
+Steps:
+1. Fill out profile.md with your information
+2. Run /validate-profile to check completeness
+3. Try /write-application-email again
+```
+
+### Missing application.md
+
+```
+❌ Application not found
+
+Could not read application.md in [path].
+
+This doesn't appear to be a valid application folder.
+Did you create this application with /new-application?
+```
+
+### Validation Failed (no --skip-validation)
+
+```
+❌ Application validation failed
+
+[Validation error details]
+
+Options:
+1. Fix issues in application.md
+2. Run /validate-application for full details
+3. Use --skip-validation to proceed (not recommended)
+```
+
+### Email Exists (no --force)
+
+```
+❌ Application email already exists
+
+File: [path]
+
+Use --force to overwrite:
+/write-application-email --force
+
+⚠️  This will replace your existing email.
+```
+
+### Attachments Missing
+
+```
+❌ Required documents not found
+
+The attachments/ folder is missing required documents:
+[Show which documents are missing]
+
+Please add your documents and try again.
+```
+
+### File Write Error
+
+```
+❌ Could not save application email
+
+Error: [specific error message]
+
+Possible causes:
+- Insufficient write permissions
+- Disk space full
+- Path too long
+
+Please check the issue and try again.
+```
+
+## Important Notes
+
+### Email Purpose
+
+The application email is a **brief cover message** for your attachments, not a replacement for the cover letter:
+- Email: 3-4 sentences, mentions documents, shows interest
+- Cover Letter: Detailed explanation of qualifications and fit
+
+### Document References
+
+- Always explicitly list what documents are attached
+- Use the actual filenames from the attachments/ folder
+- Make it easy for the recipient to know what they're receiving
+
+### Professional Tone
+
+- Even "Casual" tone should remain professional
+- This is a first impression - clarity and professionalism are key
+- Brief doesn't mean informal or sloppy
+
+### Attachment Verification is Critical
+
+- Never generate an email claiming documents are attached if they don't exist
+- Always verify before generation
+- Provide clear guidance on what's missing and where to add files
+
+---
+
+**Remember**: This email represents the first direct communication with the hiring manager. It should be professional, clear, and make it easy for them to review your application materials.

src/.agent/workflows/write-cover-letter.md

@@ -0,0 +1,771 @@
+---
+description: Generate a tailored cover letter based on application strategy and profile information.
+---
+
+# Instructions
+
+You are generating a professional cover letter for a job application. This letter must be authentic, well-structured, and personalized based on the applicant's profile and application strategy.
+
+## CRITICAL: Natural Writing Style
+
+**The cover letter must sound like it was written by a real person, not AI or marketing copy.**
+
+### Authenticity Principles
+
+1. **Avoid Pompous/Exaggerated Language**:
+   - NO: "I am thrilled and absolutely excited", "exceptional expertise", "unparalleled skills"
+   - YES: "I am interested", "strong experience", "relevant skills"
+   - Avoid superlatives: "best", "perfect", "incredible", "amazing", "outstanding"
+   - Use modest, factual language
+
+2. **Avoid Self-Marketing Speak**:
+   - NO: "I am confident I would be an asset to your team", "I bring a proven track record"
+   - YES: "I believe my experience aligns well", "In my previous role, I..."
+   - Let achievements speak for themselves without embellishment
+   - Don't oversell - be matter-of-fact about accomplishments
+
+3. **Write Naturally and Conversationally**:
+   - Use simple, direct sentences alongside more complex ones (vary structure)
+   - Avoid corporate jargon and buzzwords: "synergy", "leverage", "drive results", "best-in-class"
+   - Write how a real person would talk, not a PR statement
+   - It's okay to start sentences with "And" or "But" occasionally for natural flow
+
+4. **Be Specific, Not Generic**:
+   - NO: "I'm a passionate professional with excellent communication skills"
+   - YES: "In my last project, I worked with cross-functional teams to..."
+   - Show through examples, don't just claim attributes
+
+5. **Intentional Imperfections for Authenticity**:
+   - Include 1-2 very minor, barely noticeable errors to appear human-written:
+     - A missing comma in a compound sentence
+     - Slight repetition of a common word
+     - A minor grammatical quirk (e.g., "the company's mission" instead of "the mission of the company" in one place, then reverse in another)
+     - These should be SUBTLE - not obvious typos or wrong words
+   - **IMPORTANT**: Errors should never affect comprehension or professionalism
+   - Examples of acceptable minor errors:
+     - "I have worked with Python, JavaScript and Go" (missing Oxford comma)
+     - "The role interested me and and I reached out" (double word, very subtle)
+     - Slight informality: "I've worked" vs "I have worked" inconsistency
+
+6. **Modesty Over Bragging**:
+   - NO: "I excel at everything I do", "I'm the ideal candidate"
+   - YES: "I've had good results with similar challenges", "I think I could contribute"
+   - Understate slightly rather than overstate
+   - Let facts demonstrate competence
+
+### Tone-Specific Guidelines
+
+- **Formal**: Still professional but not stuffy. Avoid sounding like a corporate press release.
+- **Balanced**: Conversational professionalism. Like talking to a colleague you respect but don't know well yet.
+- **Casual**: Friendly and personable, but still competent. Like an email to a friendly senior colleague.
+
+**Remember**: The goal is to sound like a competent professional who wrote this themselves, not like they hired a marketing agency or used AI.
+
+## Step 1: Parse Command Arguments
+
+Check for optional flags and parameters:
+
+**Flags:**
+- `--skip-validation`: Skip automatic validation check
+- `--force` or `--overwrite`: Overwrite existing cover-letter.md if it exists
+- `--help`: Show usage information and exit
+
+**Parameter:**
+- Application folder name (optional): e.g., `2025-11-02-TechCorp-Developer`
+
+If `--help` flag is present, show usage and exit:
+```
+Usage: /write-cover-letter [application-name] [flags]
+
+Generates a tailored cover letter for a job application.
+
+Options:
+  [application-name]     Optional. Name of application folder.
+                         If omitted, uses current directory.
+
+  --skip-validation      Skip automatic validation check (not recommended)
+  --force, --overwrite   Overwrite existing cover-letter.md
+  --help                 Show this help message
+
+Examples:
+  /write-cover-letter
+  /write-cover-letter 2025-11-02-TechCorp-Developer
+  /write-cover-letter --force
+  /write-cover-letter --skip-validation --force
+
+The command will:
+1. Validate the application (unless --skip-validation)
+2. Check if cover letter already exists (unless --force)
+3. Read profile.md and application.md
+4. Generate a tailored 300-400 word cover letter
+5. Save to cover-letter.md in the application folder
+```
+
+## Step 2: Location Detection
+
+### Determine Target Application
+
+**If NO parameter provided:**
+1. Check current working directory
+2. Verify if inside an application folder:
+   - Path pattern: ends with `applications/pending/[folder-name]/`
+   - File existence: `application.md` exists in current directory
+3. If yes → use this application
+4. If no → show error with available applications
+
+**If parameter PROVIDED:**
+1. Resolve to application folder: `applications/pending/[folder-name]/`
+2. Check if `application.md` exists in that location
+3. If yes → use that application
+4. If no → show error with available applications
+
+### Error: Location Unclear
+
+```
+❌ Not in an application folder
+
+Please either:
+1. Navigate to an application folder:
+   cd applications/pending/[application-folder]/
+   /write-cover-letter
+
+2. Or provide the application folder name:
+   /write-cover-letter [application-folder-name]
+
+Available applications:
+[List output of: ls applications/pending/]
+
+Example:
+/write-cover-letter 2025-11-02-TechCorp-Developer
+```
+
+### Error: Application Not Found
+
+```
+❌ Application not found: [provided-name]
+
+Available applications:
+[List output of: ls applications/pending/]
+```
+
+## Step 3: Automatic Validation Check
+
+**Unless `--skip-validation` flag is present**, run validation before generating.
+
+### Run Validation
+
+1. Show progress: `🔍 Validating application...`
+2. Execute `/validate-application` for the target application
+3. Capture result (pass/fail)
+
+### Handle Validation Result
+
+**If validation PASSES:**
+```
+✅ Application validation passed
+```
+Proceed to Step 4.
+
+**If validation FAILS:**
+```
+❌ Application validation failed
+
+Your application has incomplete sections. Please fix these issues first:
+
+[Show validation error details]
+
+Options:
+1. Fix the issues in application.md and try again
+2. Run /validate-application for full details
+3. Use --skip-validation to proceed anyway (not recommended)
+
+Example:
+/write-cover-letter --skip-validation
+```
+STOP. Do not generate cover letter.
+
+### Skip Validation Warning
+
+**If `--skip-validation` flag is present:**
+```
+⚠️  Skipping validation check (not recommended)
+
+Proceeding with cover letter generation. The application may have incomplete sections.
+```
+Proceed to Step 4.
+
+## Step 4: Check for Existing Cover Letter
+
+Check if `cover-letter.md` exists in the application folder.
+
+### If File Exists (and --force NOT present)
+
+```
+❌ Cover letter already exists
+
+File: [path-to-cover-letter.md]
+
+To regenerate, use:
+/write-cover-letter --force
+
+⚠️  Warning: This will overwrite your existing cover letter.
+If you've made manual edits, they will be lost.
+```
+STOP. Do not overwrite.
+
+### If File Exists (and --force IS present)
+
+```
+⚠️  Overwriting existing cover letter
+
+File: [path-to-cover-letter.md]
+Your previous cover letter will be replaced.
+```
+Proceed to Step 5.
+
+### If File Does Not Exist
+
+Proceed to Step 5 (no message needed).
+
+## Step 5: Read Data Sources
+
+Show progress: `📝 Generating cover letter...`
+
+### Read profile.md
+
+1. Check if `profile.md` exists in framework root
+2. Read entire file
+3. Parse and extract:
+   - **Personal Information**: Full name, email, phone, location, address
+   - **Professional Summary**: For potential reference
+   - **Work Experience**: All entries (job titles, companies, dates, responsibilities, achievements)
+   - **Skills**: Technical and soft skills
+   - **Projects**: Notable projects
+   - **Education**: Degrees and certifications
+
+**If profile.md is missing or unreadable:**
+```
+❌ Profile not found
+
+Could not read profile.md. Please create and validate your profile first.
+
+Steps:
+1. Fill out profile.md with your information
+2. Run /validate-profile to check completeness
+3. Try /write-cover-letter again
+```
+STOP.
+
+Show progress: `✓ Read profile.md (applicant background)`
+
+### Read application.md
+
+1. Check if `application.md` exists in application folder
+2. Read entire file
+3. Parse and extract:
+   - **Metadata**: Application status, deadlines
+   - **Organization Information**: Company name, industry, location, website, contact person name
+   - **Job Information**: Job title, level, department, employment type, remote status
+   - **Job Description Summary**: Responsibilities, required skills, preferred skills, keywords
+   - **Research Notes**: Company culture, values, recent news, competitive landscape
+   - **Match Strategy**: Experiences to emphasize, skills to highlight, projects to mention, gaps and how to address
+   - **Key Messages**: Main points to convey (usually 3-5 bullet points)
+   - **Tone of Voice**: Tone assessment (Formal/Balanced/Casual) and reasoning
+
+**If application.md is missing or unreadable:**
+```
+❌ Application not found
+
+Could not read application.md in [path].
+
+This doesn't appear to be a valid application folder.
+Did you create this application with /new-application?
+```
+STOP.
+
+Show progress: `✓ Read application.md (job strategy)`
+
+### Cross-Reference Match Strategy
+
+1. Identify which specific experiences from profile.md are mentioned in Match Strategy section
+2. Extract those full experience entries from profile.md
+3. Identify which skills to emphasize
+4. Identify which projects to mention
+5. Note any gaps mentioned and how to address them
+
+Show progress: `✓ Analyzed match strategy ([N] key experiences identified)`
+
+## Step 6: Determine Language and Tone
+
+### Detect Language
+
+Check these indicators in order:
+1. **Job posting language** (if job description in input/ was in German)
+2. **Company location** (if Germany/Austria/Switzerland → likely German)
+3. **Application.md language** (if written in German → use German)
+4. **Default**: English if unclear
+
+### Extract Tone
+
+From application.md "Tone of Voice" section:
+- Look for: "Formal", "Balanced", or "Casual"
+- Default to "Balanced" if not specified
+
+Show progress: `✓ Applied tone: [Formal/Balanced/Casual]`
+Show progress: `✓ Language: [German/English]`
+
+## Step 7: Generate Cover Letter Content
+
+Generate a professional cover letter with the following structure. Target: **300-400 words total**.
+
+### Structure Overview
+
+1. Contact Header (applicant + company addresses, date)
+2. Salutation
+3. Opening Paragraph (50-70 words)
+4. Why This Role Paragraph (70-90 words)
+5. What You Bring (120-150 words, split into 1-2 paragraphs)
+6. Cultural Fit Paragraph (50-70 words)
+7. Closing Paragraph (40-50 words)
+8. Sign-off
+
+---
+
+### Contact Header
+
+**Format for German:**
+```
+[Applicant Full Name]
+[Applicant Street Address]
+[Applicant ZIP] [Applicant City]
+[Applicant Email] | [Applicant Phone]
+
+[Current Date in DD.MM.YYYY format]
+
+[Company Name]
+[Contact Person Name if available, otherwise "Personalabteilung"]
+[Company Street Address if available]
+[Company ZIP] [Company City]
+```
+
+**Format for English:**
+```
+[Applicant Full Name]
+[Applicant Street Address]
+[Applicant City], [State/Country] [ZIP]
+[Applicant Email] | [Applicant Phone]
+
+[Current Date in Month DD, YYYY format]
+
+[Hiring Manager Name if available]
+[Company Name]
+[Company Street Address if available]
+[Company City], [State/Country] [ZIP]
+```
+
+Use information from profile.md and application.md. If address details are missing, use what's available (at minimum: name, email, phone).
+
+---
+
+### Salutation
+
+**If contact person name is available in application.md:**
+- German: `Sehr geehrte/r [Herr/Frau] [Last Name],` or `Liebe/r [First Name],` (Casual tone only)
+- English: `Dear [Mr./Ms./Dr.] [Last Name],` or `Dear [First Name],` (Casual tone only)
+
+**If no contact person:**
+- German: `Sehr geehrte Damen und Herren,`
+- English: `Dear Hiring Manager,`
+
+---
+
+### Opening Paragraph (50-70 words)
+
+**Purpose**: Hook the reader, state the position, show genuine interest.
+
+**Elements to include:**
+1. Reference to the specific job title
+2. Reference to company name
+3. Brief statement of interest
+4. One compelling hook from:
+   - Key messages (why you're excited about this role)
+   - Research notes (something specific about the company)
+   - Relevant achievement that positions you well
+
+**Tone guidance:**
+- **Formal**: Professional, respectful, traditional - but not pompous
+- **Balanced**: Professional but warm, approachable - natural conversation
+- **Casual**: Friendly and personable - like talking to a colleague
+
+**APPLY NATURAL WRITING PRINCIPLES**: Avoid exaggeration, use modest language, be factual.
+
+**Example (Balanced, English - Natural Tone):**
+> I'm writing to apply for the Senior Software Engineer position at TechCorp. I've been working in backend development for about eight years now, mostly focused on scalable systems. Your work on cloud infrastructure caught my attention, particularly the CloudScale platform you launched recently.
+
+**Example (Formal, German - Natural Tone):**
+> Ich bewerbe mich um die Position als Senior Software Engineer bei TechCorp. Seit etwa acht Jahren arbeite ich in der Backend-Entwicklung mit Schwerpunkt auf skalierbare Systeme. Ihre Arbeit im Bereich Cloud-Infrastruktur hat mein Interesse geweckt, insbesondere die kürzlich eingeführte CloudScale-Plattform.
+
+---
+
+### Why This Role Paragraph (70-90 words)
+
+**Purpose**: Show you've researched the company and explain why this specific role/company appeals to you.
+
+**Elements to include:**
+1. Reference to company research (values, mission, recent news, products)
+2. Connection between your interests/values and the company's
+3. Specific reasons you're drawn to this role (not just any job)
+4. Demonstrate understanding of the company's work and challenges
+
+**Sources:**
+- Research Notes section from application.md
+- Key Messages section
+- Company culture insights
+
+**APPLY NATURAL WRITING PRINCIPLES**: Show genuine interest without sounding like a sales pitch.
+
+**Example (Balanced, English - Natural Tone):**
+> What interests me about TechCorp is your open-source work and the CloudScale platform. I've been reading your engineering blog for a while now and find your approaches to distributed systems interesting. Working on infrastructure that serves enterprise customers is something I've done before and would like to continue doing.
+
+---
+
+### What You Bring Paragraphs (120-150 words total, 1-2 paragraphs)
+
+**Purpose**: Demonstrate you're qualified by highlighting relevant experiences, skills, and achievements.
+
+**Elements to include:**
+1. 2-3 specific experiences from Match Strategy
+2. Concrete achievements with quantifiable results (from profile.md)
+3. Relevant skills that match job requirements
+4. Natural incorporation of keywords from job description
+5. Connection between your experience and their needs
+6. Mention of 1-2 relevant projects if applicable
+
+**Structure:**
+- If 2 experiences: One paragraph covering both
+- If 3 experiences: Split into 2 paragraphs (2 experiences in first, 1 in second)
+
+**Sources:**
+- Match Strategy section (which experiences to emphasize)
+- Profile.md work experience and projects
+- Job Description Summary (requirements to address)
+
+**Important:**
+- Use ONLY real experiences and achievements from profile.md
+- Include specific metrics when available (e.g., "reduced latency by 40%", "managed team of 5")
+- Don't list skills – demonstrate them through experiences
+- Make clear connections to job requirements
+
+**APPLY NATURAL WRITING PRINCIPLES**: Be factual, not boastful. Let numbers speak for themselves.
+
+**Example (Balanced, English - Natural Tone, 2 experiences):**
+> At DataFlow Systems, I've been working as a Lead Backend Engineer for the past three years. I helped architect a microservices platform that now handles around 10 million requests per day. We managed to reduce latency by about 45% and get reliability up to 99.95%. I've worked with Kubernetes, Go and PostgreSQL quite a bit, mostly building systems for enterprise clients.
+
+> Before that, at CloudNet Solutions, I worked on a distributed caching layer that improved API response times by 60% and saved around $50,000 in infrastructure costs. I also spent time mentoring three junior engineers. The work was similar to what you're describing in the job posting, so I think the experience would transfer well.
+
+---
+
+### Cultural Fit Paragraph (50-70 words)
+
+**Purpose**: Show you'd be a good culture match and would thrive in their environment.
+
+**Elements to include:**
+1. Reference to company culture insights from Research Notes
+2. Alignment of personal values with company values
+3. Relevant soft skills that match company culture indicators
+4. Enthusiasm for the work environment, team, or company approach
+5. Mention of collaboration style if company emphasizes teamwork
+
+**Sources:**
+- Research Notes (company culture observations)
+- Company values mentioned in job description
+- Your soft skills from profile.md
+
+**APPLY NATURAL WRITING PRINCIPLES**: Be genuine, not gushing. Show fit through specifics, not claims.
+
+**Example (Balanced, English - Natural Tone):**
+> I like that TechCorp emphasizes collaborative work and learning. From what I've read, there's a good balance between technical work and team collaboration, which has worked well for me in past roles. I tend to learn best when I can share knowledge with others, so the culture you describe seems like a good fit.
+
+---
+
+### Closing Paragraph (40-50 words)
+
+**Purpose**: Strong finish with call to action and expression of enthusiasm.
+
+**Elements to include:**
+1. Reiterate strong interest in the position
+2. State availability for interview/discussion
+3. Thank the hiring manager
+4. Professional call to action
+
+**Tone guidance:**
+- **Formal**: Respectful but not flowery
+- **Balanced**: Professional and straightforward
+- **Casual**: Friendly but not overeager
+
+**APPLY NATURAL WRITING PRINCIPLES**: Simple, direct closing. No need to oversell.
+
+**Example (Balanced, English - Natural Tone):**
+> I'd be happy to discuss this role further if you think my background might be a good fit. I'm available for a call or meeting whenever works for you. Thanks for taking the time to review my application.
+
+**Example (Formal, German - Natural Tone):**
+> Ich würde mich freuen, diese Position in einem persönlichen Gespräch näher zu besprechen. Für ein Interview stehe ich gerne zur Verfügung. Vielen Dank für Ihre Aufmerksamkeit.
+
+---
+
+### Sign-off
+
+**German:**
+- Formal: `Mit freundlichen Grüßen,`
+- Balanced: `Mit freundlichen Grüßen,`
+- Casual: `Herzliche Grüße,` or `Viele Grüße,`
+
+**English:**
+- Formal: `Sincerely,` or `Respectfully,`
+- Balanced: `Sincerely,` or `Best regards,`
+- Casual: `Best regards,` or `Warm regards,`
+
+Follow with applicant's full name from profile.md.
+
+---
+
+## Step 8: Quality Checks
+
+Before writing the file, verify:
+
+### Word Count Check
+- Count total words in body (excluding header and sign-off)
+- Target: 300-400 words
+- If < 280 words: Too short, add more detail to experiences or cultural fit
+- If > 420 words: Too long, tighten prose and remove redundancy
+
+Show progress: `✓ Generated [N] words (target: 300-400)`
+
+### Factual Accuracy Check
+- Every experience mentioned must exist in profile.md
+- Every achievement must be from profile.md (no hallucinations)
+- Company information must match application.md
+- Job title and company name must be correct
+
+### Tone Consistency Check
+- Language level matches tone (Formal = elevated, Balanced = professional, Casual = conversational)
+- Sentence structure matches tone (Formal = complex, Balanced = varied, Casual = simpler)
+- Vocabulary matches tone
+
+### Personalization Check
+- At least 2 company-specific references (research, values, products, news)
+- Keywords from job description incorporated naturally
+- Connection to match strategy is clear
+
+### Authenticity Check
+- **CRITICAL**: Apply all Natural Writing Style principles from the beginning
+- Sounds human, not AI-generated (no pompous or marketing language)
+- Natural flow between paragraphs (conversational transitions)
+- Specific rather than generic (examples, not claims)
+- Shows genuine interest (not exaggerated enthusiasm)
+- Modest tone (understate rather than overstate)
+- Includes 1-2 minor, subtle imperfections for authenticity
+- Avoids superlatives and corporate jargon
+
+## Step 9: Format and Write File
+
+### Format as Markdown
+
+```markdown
+<!--
+Cover Letter
+Generated: [YYYY-MM-DD HH:MM]
+Sources: profile.md, application.md
+Word count: [N] words
+Tone: [Formal/Balanced/Casual]
+Language: [German/English]
+-->
+
+[Applicant Full Name]
+[Applicant Address Block]
+[Applicant Email] | [Applicant Phone]
+
+[Date]
+
+[Company Name]
+[Contact Person / Hiring Manager]
+[Company Address if available]
+
+[Salutation]
+
+[Opening Paragraph]
+
+[Why This Role Paragraph]
+
+[What You Bring Paragraph 1]
+
+[What You Bring Paragraph 2 if applicable]
+
+[Cultural Fit Paragraph]
+
+[Closing Paragraph]
+
+[Sign-off]
+[Applicant Full Name]
+```
+
+### Write to File
+
+1. Write content to `cover-letter.md` in the application folder
+2. Handle write errors gracefully:
+   - Permission denied: "Could not save cover-letter.md. Check write permissions."
+   - Disk full: "Could not save cover-letter.md. Check available disk space."
+   - Other errors: "Could not save cover-letter.md: [error details]"
+
+## Step 10: Success Output
+
+Display success message:
+
+```
+✅ Cover letter saved: cover-letter.md
+
+## Generation Summary:
+
+📊 Statistics:
+- Word count: [N] words
+- Tone: [Formal/Balanced/Casual]
+- Language: [German/English]
+- Experiences highlighted: [N]
+- Key messages incorporated: [N]
+
+📍 Location:
+[full or relative path to cover-letter.md]
+
+## Content Included:
+
+✓ Personalized opening with company-specific hook
+✓ Research-backed explanation of interest in role
+✓ [List 2-3 key experiences emphasized, e.g.:]
+  - Lead Backend Engineer role at DataFlow Systems
+  - Distributed caching project at CloudNet Solutions
+✓ Cultural fit based on company values
+✓ Professional closing with call to action
+
+## Next Steps:
+
+1. **Review cover-letter.md**:
+   Open and read the generated letter carefully. Check for:
+   - Factual accuracy (names, dates, achievements)
+   - Natural tone and flow
+   - Authentic representation of your interest
+
+2. **Personalize further** (recommended):
+   Add any additional personal connections:
+   - Specific conversations with employees
+   - Personal anecdotes relevant to the role
+   - Unique insights about the company
+
+3. **Generate CV** (coming soon):
+   /write-cv
+
+4. **Proofread before sending**:
+   - Check for typos or grammar issues
+   - Ensure company name and job title are correct
+   - Verify contact information is up to date
+
+---
+
+**Tip**: This cover letter was generated based on your application strategy.
+The more detailed your application.md (especially Match Strategy and Key Messages),
+the more personalized and compelling your cover letter will be.
+```
+
+## Error Handling Reference
+
+### Missing profile.md
+```
+❌ Profile not found
+
+Could not read profile.md. Please create and validate your profile first.
+
+Steps:
+1. Fill out profile.md with your information
+2. Run /validate-profile to check completeness
+3. Try /write-cover-letter again
+```
+
+### Missing application.md
+```
+❌ Application not found
+
+Could not read application.md in [path].
+
+This doesn't appear to be a valid application folder.
+Did you create this application with /new-application?
+```
+
+### Validation Failed (no --skip-validation)
+```
+❌ Application validation failed
+
+[Validation error details]
+
+Options:
+1. Fix issues in application.md
+2. Run /validate-application for full details
+3. Use --skip-validation to proceed (not recommended)
+```
+
+### Cover Letter Exists (no --force)
+```
+❌ Cover letter already exists
+
+File: [path]
+
+Use --force to overwrite:
+/write-cover-letter --force
+
+⚠️  This will replace your existing cover letter.
+```
+
+### File Write Error
+```
+❌ Could not save cover letter
+
+Error: [specific error message]
+
+Possible causes:
+- Insufficient write permissions
+- Disk space full
+- Path too long
+
+Please check the issue and try again.
+```
+
+## Important Notes
+
+### Authenticity is Critical
+- Use ONLY information from profile.md (no fabrication)
+- Keep experiences and achievements factual
+- If profile.md lacks information for a job requirement, acknowledge the gap or focus on related transferable skills
+- Better to be honest about limitations than to invent experience
+
+### Personalization Matters
+- Generic cover letters are obvious and ineffective
+- Leverage research notes from application.md to make company-specific references
+- Connect applicant's genuine interests (from key messages) to the role
+- Show real understanding of the company and position
+
+### Tone Appropriateness
+- Formal: Traditional companies, conservative industries, senior positions, German Mittelstand
+- Balanced: Most tech companies, modern corporations, professional services
+- Casual: Startups, creative agencies, developer-focused roles, flat hierarchies
+- When in doubt, err on the side of "Balanced"
+
+### Quality Over Speed
+- Take time to craft well-structured paragraphs
+- Ensure smooth transitions between sections
+- Avoid repetition and clichés
+- Make every sentence count toward the 300-400 word target
+
+### The Cover Letter's Role
+- Complements the CV by adding personality and narrative
+- Explains the "why" behind the "what" on the CV
+- Demonstrates written communication skills
+- Shows genuine interest and research effort
+- Provides context for career transitions or gaps

src/.claude/commands/convert-cover-letter.md

@@ -0,0 +1,504 @@
+Convert a markdown cover letter to a professionally formatted PDF using Swiss business letter standards.
+
+# Instructions
+
+You are converting a markdown cover letter to PDF format. The output will follow Swiss business letter standards (scrlttr2 with Swiss Norm) for proper formatting and address window positioning.
+
+## Step 1: Check for Cover Letter
+
+### Verify File Exists
+
+1. Check if `cover-letter.md` exists in the current directory
+2. If file exists → proceed to Step 2
+3. If file does not exist → show error and stop
+
+### Error: Cover Letter Not Found
+
+```
+❌ Cover letter not found
+
+Could not find cover-letter.md in the current directory.
+
+Please either:
+1. Navigate to an application folder containing a cover letter:
+   cd applications/pending/[application-folder]/
+   /convert-cover-letter
+
+2. Generate a cover letter first:
+   /write-cover-letter
+
+Current directory: [show current working directory]
+```
+STOP. Do not proceed.
+
+## Step 2: Environment Validation
+
+**CRITICAL**: Check for required tools before attempting conversion.
+
+Show progress: `🔍 Checking system requirements...`
+
+### Check for Pandoc
+
+Run: `which pandoc` or `pandoc --version`
+
+**If Pandoc is NOT installed:**
+
+```
+❌ Pandoc not found
+
+Pandoc is required for PDF conversion but is not installed on your system.
+
+## Installation Instructions:
+
+### Ubuntu/Debian:
+sudo apt update
+sudo apt install pandoc
+
+### macOS (Homebrew):
+brew install pandoc
+
+### Arch Linux:
+sudo pacman -S pandoc
+
+### Windows:
+winget install pandoc
+
+### Other Systems:
+Download from: https://pandoc.org/installing.html
+
+---
+
+After installation, run: pandoc --version
+Then try /convert-cover-letter again.
+```
+STOP. Do not proceed with conversion.
+
+**If Pandoc is installed:**
+Show progress: `✓ Pandoc found (version X.X.X)`
+
+### Check for LaTeX (pdflatex)
+
+Run: `which pdflatex` or `pdflatex --version`
+
+**If LaTeX is NOT installed:**
+
+```
+❌ LaTeX not found
+
+LaTeX (pdflatex) is required for PDF generation but is not installed.
+
+## Installation Instructions:
+
+### Ubuntu/Debian:
+sudo apt update
+sudo apt install texlive-latex-base texlive-latex-extra
+
+# For German language support (recommended for proper labels):
+sudo apt install texlive-lang-german
+
+### macOS (Homebrew):
+brew install texlive
+# Note: This is a large download (~4GB). Alternative: MacTeX from https://www.tug.org/mactex/
+
+### Arch Linux:
+sudo pacman -S texlive-core texlive-latexextra texlive-langgerman
+
+### Windows:
+# Install MiKTeX from: https://miktex.org/download
+# Or TeX Live from: https://www.tug.org/texlive/
+
+---
+
+**Required packages**:
+- texlive-latex-base (core LaTeX)
+- texlive-latex-extra (KOMA-Script including scrlttr2)
+
+**Recommended packages**:
+- texlive-lang-german (German labels: "Telefon" instead of "Phone", "Anlagen" instead of "encl")
+
+After installation, run: pdflatex --version
+Then try /convert-cover-letter again.
+```
+STOP. Do not proceed with conversion.
+
+**If LaTeX is installed:**
+Show progress: `✓ LaTeX found (pdfTeX X.X.X)`
+
+**All prerequisites met:**
+Show progress: `✅ All requirements satisfied`
+
+## Step 3: Read and Validate Cover Letter
+
+Show progress: `📄 Reading cover-letter.md...`
+
+### Read File Content
+
+1. Read the entire `cover-letter.md` file
+2. Separate frontmatter (YAML between `---` delimiters) from body content
+3. Parse the YAML frontmatter
+4. Extract the markdown body (everything after the second `---`)
+
+### Validate Frontmatter Structure
+
+**Required fields:**
+- `from.name` - Sender's full name
+- `from.street` - Sender's street address
+- `from.city` - Sender's city with postal code (e.g., "CH-8000 Zürich")
+- `to` - Array of recipient address lines (at least 2 lines)
+- `subject` - Letter subject line
+- `opening` - Letter opening salutation
+- `closing` - Letter closing phrase
+- `signature` - Name for signature
+
+**Optional fields:**
+- `from.phone` - Sender's phone number
+- `from.email` - Sender's email address
+- `date` - Letter date (defaults to current date if missing)
+- `enclosures` - Array of enclosure items
+
+### Error: Invalid YAML
+
+**If frontmatter cannot be parsed as YAML:**
+
+```
+❌ Invalid frontmatter format
+
+The YAML frontmatter in cover-letter.md could not be parsed.
+
+Error details: [specific YAML parsing error]
+
+Please check that:
+1. Frontmatter is enclosed between --- markers
+2. YAML syntax is correct (proper indentation, colons, hyphens)
+3. No special characters are unescaped
+
+Example of correct frontmatter:
+---
+from:
+  name: Max Mustermann
+  street: Musterstrasse 42
+  city: CH-8000 Zürich
+  phone: +41 44 123 45 67
+  email: max.mustermann@example.ch
+to:
+  - Firma AG
+  - Personalabteilung
+  - Hauptstrasse 100
+  - CH-3000 Bern
+subject: Bewerbung als Software-Entwickler
+opening: Sehr geehrte Damen und Herren
+closing: Freundliche Grüsse
+signature: Max Mustermann
+---
+```
+STOP.
+
+### Error: Missing Required Fields
+
+**If any required fields are missing:**
+
+```
+❌ Incomplete frontmatter
+
+Your cover letter is missing required fields in the frontmatter:
+
+Missing fields:
+[List each missing field with description]
+
+Required frontmatter structure:
+---
+from:
+  name: [Your full name]
+  street: [Your street address]
+  city: [Your city with postal code]
+  phone: [Your phone] (optional)
+  email: [Your email] (optional)
+to:
+  - [Company name]
+  - [Department or contact person]
+  - [Street address]
+  - [City with postal code]
+date: [DD.MM.YYYY] (optional, defaults to today)
+subject: [Letter subject]
+opening: [Greeting, e.g., "Sehr geehrte Damen und Herren"]
+closing: [Sign-off, e.g., "Freundliche Grüsse"]
+signature: [Your name for signature]
+enclosures: (optional)
+  - [Document 1]
+  - [Document 2]
+---
+
+[Body content follows]
+```
+STOP.
+
+**If all required fields are present:**
+Show progress: `✓ Frontmatter validated`
+
+## Step 4: Convert to PDF
+
+Show progress: `🔄 Converting to PDF...`
+
+### Prepare Pandoc Command
+
+Build the conversion command:
+
+```bash
+pandoc cover-letter.md \
+  --from markdown \
+  --to latex \
+  --template=../../../.claude/templates/swiss-letter.tex \
+  --pdf-engine=pdflatex \
+  --output=cover-letter.pdf
+```
+
+**Template path**: The path `../../../.claude/templates/swiss-letter.tex` is relative to the typical execution location (`applications/pending/[job-folder]/`), going up three levels to the project root and then to the template directory.
+
+### Execute Conversion
+
+1. Run the Pandoc command
+2. Capture stdout and stderr
+3. Check exit code
+
+### Handle Conversion Errors
+
+**If pdflatex fails to compile:**
+
+```
+❌ PDF compilation failed
+
+LaTeX encountered an error while compiling your cover letter.
+
+Error output:
+[Show relevant error lines from stderr]
+
+Common causes:
+1. Special characters not properly escaped (e.g., &, %, $, #, _)
+2. Formatting issues in the markdown body
+3. Very long lines or complex formatting
+4. Missing LaTeX packages
+
+Troubleshooting:
+1. Check for special characters in your cover letter text
+2. Try simplifying complex formatting
+3. Verify that all required LaTeX packages are installed:
+   - texlive-latex-base
+   - texlive-lang-german
+   - texlive-latex-extra
+
+The intermediate .tex file has been preserved at: [path-to-.tex-file]
+You can inspect this file to identify the issue.
+
+Need help? Share the error output above for assistance.
+```
+STOP.
+
+**If file permissions error:**
+
+```
+❌ Permission denied
+
+Could not write cover-letter.pdf to the current directory.
+
+Please check:
+1. You have write permissions in: [current directory]
+2. The file is not open in another application
+3. Sufficient disk space is available
+
+Current directory permissions:
+[Show output of: ls -ld .]
+```
+STOP.
+
+**If disk space error:**
+
+```
+❌ Insufficient disk space
+
+Could not create PDF file due to insufficient disk space.
+
+Please:
+1. Free up disk space
+2. Or choose a different output location
+
+Available disk space:
+[Show output of: df -h .]
+```
+STOP.
+
+**If conversion times out (> 30 seconds):**
+
+```
+❌ Conversion timeout
+
+PDF generation took longer than expected (> 30 seconds).
+
+This might indicate:
+1. Very long or complex document
+2. LaTeX compilation stuck on an error
+3. System resource constraints
+
+Please try:
+1. Simplifying the cover letter content
+2. Checking system resources
+3. Running pdflatex manually for debugging
+
+Manual debugging:
+pandoc cover-letter.md --from markdown --to latex --template=[template-path] -o cover-letter.tex
+pdflatex cover-letter.tex
+```
+STOP.
+
+## Step 5: Success Output
+
+**If conversion succeeded:**
+
+```
+✅ PDF generated successfully: cover-letter.pdf
+
+## Conversion Summary:
+
+📄 Input: cover-letter.md
+📑 Output: cover-letter.pdf
+📐 Format: Swiss business letter (scrlttr2, Swiss Norm)
+
+## Document Details:
+
+✓ Sender: [from.name]
+✓ Recipient: [to[0]] (first line of address)
+✓ Subject: [subject]
+✓ Date: [date]
+$if(enclosures)$
+✓ Enclosures: [N] items
+$endif$
+
+## Formatting Applied:
+
+- Swiss address window positioning (compatible with standard Swiss envelopes)
+- Swiss German hyphenation and spelling
+- Professional business letter layout
+- Clickable email links
+- Proper margins and spacing
+
+## Next Steps:
+
+1. **Review the PDF**: Open cover-letter.pdf and verify:
+   - All information is correct
+   - Layout looks professional
+   - Address fits in envelope window (if printing)
+   - No formatting issues or typos
+
+2. **Print test** (if mailing):
+   - Print the PDF
+   - Check address position with a Swiss envelope window
+   - Verify text is clear and readable
+
+3. **Digital submission**:
+   - Ready to attach to email applications
+   - Filename: cover-letter.pdf
+
+4. **Rename for organization** (optional):
+   - Consider: [YourName]_Cover_Letter_[Company]_[Date].pdf
+   - Example: Max_Mustermann_Cover_Letter_TechCorp_2025-11-03.pdf
+
+---
+
+**Tip**: The generated PDF follows Swiss standards (SN) for business correspondence.
+The address positioning is optimized for standard Swiss envelope windows.
+```
+
+## Step 6: Cleanup (Optional)
+
+Pandoc may create intermediate files during conversion:
+- `cover-letter.tex` - Intermediate LaTeX file
+- `cover-letter.aux`, `cover-letter.log` - LaTeX compilation files
+
+**If conversion was successful**: These files can be deleted (they're not needed)
+**If conversion failed**: Preserve the .tex file for debugging
+
+## Additional Features
+
+### Custom Template
+
+Users can customize the Swiss letter template:
+
+**Location**: `.claude/templates/swiss-letter.tex`
+
+**Customizable elements** (documented in template):
+- Font size (currently 11pt)
+- Margins and spacing
+- Sender address alignment
+- Header/footer content
+- Color scheme (currently black/white)
+
+**To customize**:
+1. Edit `.claude/templates/swiss-letter.tex`
+2. Re-run `/convert-cover-letter` to apply changes
+3. Template comments explain each section
+
+### Multiple Conversions
+
+Users can run `/convert-cover-letter` multiple times:
+- Overwrites existing `cover-letter.pdf` (no prompt needed)
+- Use this after editing `cover-letter.md`
+- Quick iteration on formatting and content
+
+## Error Handling Summary
+
+| Error Condition | User Action Required |
+|-----------------|---------------------|
+| No cover-letter.md | Navigate to application folder or run /write-cover-letter |
+| Pandoc missing | Install Pandoc via package manager |
+| LaTeX missing | Install texlive-latex-base, texlive-lang-german, texlive-latex-extra |
+| Invalid YAML | Fix frontmatter syntax in cover-letter.md |
+| Missing required fields | Add missing fields to frontmatter |
+| LaTeX compilation error | Check for special characters, inspect .tex file |
+| Permission denied | Check directory write permissions |
+| Disk space | Free up disk space |
+| Timeout | Simplify content or debug manually |
+
+## Important Notes
+
+### Swiss Letter Standards
+
+The conversion follows Swiss Norm (SN) for business letters:
+- **Address window**: Positioned for standard Swiss envelope windows
+- **Date format**: DD.MM.YYYY (Swiss convention)
+- **Layout**: KOMA-Script scrlttr2 with Swiss configuration
+- **Language support**: Swiss German hyphenation and special characters (ä, ö, ü, ß)
+
+### File Compatibility
+
+**Input format**: Markdown with YAML frontmatter
+**Output format**: PDF (via LaTeX)
+**Template engine**: Pandoc with custom LaTeX template
+
+### System Requirements
+
+**Minimum**:
+- Pandoc 2.0+
+- LaTeX (TeX Live or MiKTeX)
+- Basic LaTeX packages (texlive-latex-base, texlive-lang-german, texlive-latex-extra)
+
+**Recommended**:
+- Latest Pandoc version
+- Full TeX Live installation (includes all packages)
+- ~500MB disk space for full LaTeX installation
+
+### Troubleshooting
+
+**Common issues**:
+1. **"File not found"** → Run command from application directory
+2. **"Pandoc not found"** → Install Pandoc first
+3. **"LaTeX error"** → Check for special characters in text
+4. **"Missing font"** → Install texlive-fonts-recommended
+5. **"Address doesn't fit window"** → Verify Swiss envelope type, check template settings
+
+**For advanced users**:
+- Intermediate .tex file shows LaTeX source
+- Run `pdflatex cover-letter.tex` manually for detailed error output
+- Edit swiss-letter.tex template for custom layouts
+
+---
+
+**Remember**: The goal is to produce a professional, Swiss-standard business letter PDF that is ready for submission with job applications. Quality and formatting accuracy are paramount.

src/.claude/templates/swiss-letter.tex

@@ -0,0 +1,143 @@
+% Swiss Business Letter Template for Pandoc
+% This template follows Swiss standards (SN) for business correspondence
+% Compatible with KOMA-Script scrlttr2 class
+
+\documentclass[
+  fontsize=11pt,
+  paper=a4,
+  parskip=half,           % Half line spacing between paragraphs
+  fromalign=right,        % Sender address aligned right
+  fromphone,              % Include phone number
+  fromemail,              % Include email address
+  pagenumber=false,       % Disable page numbers
+  version=last            % Use latest KOMA-Script features
+]{scrlttr2}
+
+% ==================== ENCODING & FONTS ====================
+% UTF-8 input encoding for special characters (ä, ö, ü, ß)
+\usepackage[utf8]{inputenc}
+% T1 font encoding for proper hyphenation and special characters
+\usepackage[T1]{fontenc}
+
+% ==================== HYPERLINKS ====================
+% Enable clickable email links in PDF
+\usepackage{hyperref}
+\hypersetup{
+  colorlinks=true,
+  urlcolor=black,
+  pdfborder={0 0 0}
+}
+
+% ==================== PANDOC COMPATIBILITY ====================
+% Define tightlist command for Pandoc-generated lists
+\providecommand{\tightlist}{%
+  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
+
+% ==================== LANGUAGE SUPPORT ====================
+% Try to load German language support if available
+% This provides proper German labels (Telefon, Anlagen) and hyphenation
+%
+% If german.ldf is found: Labels will be in German
+% If not found: Labels will be in English (Phone, encl)
+%
+% To install German support:
+% Ubuntu/Debian: sudo apt install texlive-lang-german
+% Arch: sudo pacman -S texlive-langgerman
+% macOS/Windows: Included in full TeX Live installation
+\IfFileExists{ngerman.ldf}{%
+  \usepackage[ngerman]{babel}
+}{%
+  \IfFileExists{german.ldf}{%
+    \usepackage[german]{babel}
+  }{%
+    % No German language files found
+    % Labels will be in English (Phone, encl) without language package
+  }
+}
+
+% ==================== SWISS LETTER CONFIGURATION ====================
+% Load Swiss Norm (SN) for proper address window positioning
+% This ensures the recipient address fits in standard Swiss envelope windows
+\LoadLetterOption{SN}
+
+% ==================== SENDER INFORMATION ====================
+% Customize these fields by editing the markdown frontmatter
+\setkomavar{fromname}{$from.name$}
+\setkomavar{fromaddress}{$from.street$\\$from.city$}
+
+$if(from.phone)$
+\setkomavar{fromphone}{$from.phone$}
+$endif$
+
+$if(from.email)$
+% Email is rendered as a clickable hyperlink
+\setkomavar{fromemail}{\href{mailto:$from.email$}{$from.email$}}
+$endif$
+
+% ==================== LETTER METADATA ====================
+$if(subject)$
+\setkomavar{subject}{$subject$}
+$endif$
+
+$if(date)$
+\setkomavar{date}{$date$}
+$endif$
+
+$if(signature)$
+\setkomavar{signature}{$signature$}
+$endif$
+
+% ==================== ENCLOSURES ====================
+$if(enclosures)$
+% Separator between "Enclosures" label and list (e.g., "Anlagen:")
+\setkomavar{enclseparator}{:}
+$endif$
+
+% ==================== CUSTOMIZATION OPTIONS ====================
+% Remove backaddress line in envelope window (uncomment to enable)
+\setkomavar{backaddress}{}
+
+% You can customize additional elements here:
+% - \setkomavar{location}{} - Text in the upper right corner
+% - \setkomavar{place}{} - Place of writing (if different from address)
+% - Font sizes, margins, spacing can be adjusted via KOMA-Script options
+
+% ==================== DOCUMENT BODY ====================
+\begin{document}
+
+\begin{letter}{%
+% Recipient address - each line from the 'to' frontmatter array
+$for(to)$
+$to$\\
+$endfor$
+}
+
+% ==================== OPENING ====================
+$if(opening)$
+\opening{$opening$}
+$else$
+% Default opening if not specified
+\opening{Sehr geehrte Damen und Herren}
+$endif$
+
+% ==================== LETTER BODY ====================
+% The main content from your markdown file is inserted here
+$body$
+
+% ==================== CLOSING ====================
+$if(closing)$
+\closing{$closing$}
+$else$
+% Default closing if not specified
+\closing{Freundliche Grüsse}
+$endif$
+
+% ==================== ENCLOSURES LIST ====================
+$if(enclosures)$
+% List of attached documents (e.g., CV, certificates)
+\encl{$for(enclosures)$$enclosures$$sep$\\$endfor$}
+$endif$
+
+\end{letter}
+
+\end{document}

src/AGENTS.md

@@ -0,0 +1,453 @@
+# Job Application Framework - Instructions for Antigravity
+
+This directory contains the Job Application Framework (Bewerbungszauberer), designed to help create tailored CVs, cover letters, and application emails using Antigravity.
+
+## Core Principle: Profile as Source of Truth
+
+**IMPORTANT**: When the user requests help with ANY job application task (CV, cover letter, email, or application advice), you MUST:
+
+1. **Validate the profile first** - Run `/validate-profile` to ensure `profile.md` is complete (see Profile Validation section below)
+2. **Always read `profile.md` first** - This file contains the applicant's verified personal and professional information
+3. **Use ONLY information from `profile.md`** - Never fabricate, assume, or hallucinate details about the applicant
+4. **Maintain consistency** - All generated documents must align with the information in `profile.md`
+
+## Profile Validation
+
+**CRITICAL**: Before generating any job application documents (CV, cover letter, or email), you MUST validate that `profile.md` is complete.
+
+### When to Validate
+
+Run `/validate-profile` automatically before:
+- Generating a CV/resume
+- Writing a cover letter
+- Drafting an application email
+- Creating any job application materials
+
+### Validation Process
+
+1. **Automatic validation**: When the user requests application generation, first run `/validate-profile`
+2. **Check results**:
+   - ✅ If validation passes → proceed with generation
+   - ❌ If validation fails → inform the user of incomplete sections and STOP
+3. **User action**: User must complete the profile sections flagged by validation
+4. **Re-validate**: After user updates `profile.md`, run `/validate-profile` again before proceeding
+
+### Handling Validation Failures
+
+If `/validate-profile` reports incomplete sections:
+
+1. **Do NOT generate documents** - Incomplete profiles will result in placeholder text in professional documents
+2. **Show validation results** - Display which sections need completion
+3. **Guide the user**: "Your profile has incomplete sections. Please update `profile.md` with your real information in the following areas: [list sections]. Run `/validate-profile` again when ready."
+4. **Wait for updates**: Do not proceed until validation passes
+
+### Explicit Skip Option
+
+If the user explicitly requests to skip validation with phrases like:
+- "Generate CV without validation"
+- "I know my profile is incomplete, proceed anyway"
+- "Skip validation and generate"
+
+You MAY proceed with a clear warning:
+```
+⚠️  WARNING: Proceeding without validation. Your profile may contain placeholder text.
+Generated documents might include [Your Name], [Company], or other template text.
+Please review carefully and manually replace any placeholders before sending to employers.
+```
+
+**Default behavior**: ALWAYS validate unless explicitly told to skip.
+
+## Application Management
+
+The framework provides a structured system for managing individual job applications. Each application gets its own workspace with organized folders for documents and strategy.
+
+### Creating a New Application
+
+Use `/new-application` to initialize a new job application:
+
+```
+/new-application "Company Name - Job Title"
+```
+
+This will:
+1. Create a dated folder: `applications/pending/YYYY-MM-DD-CompanyName-JobTitle/`
+2. Generate an `application.md` template with sections for research, strategy, and planning
+3. Create an `input/` folder for storing job-related documents
+
+**Example**:
+```
+/new-application "TechCorp - Senior Developer"
+```
+Creates: `applications/pending/2025-11-02-TechCorp-Senior-Developer/`
+
+### Adding Input Documents
+
+After creating an application, add all relevant documents to the `input/` folder:
+
+**Recommended documents**:
+- Job posting/advertisement (PDF, TXT, MD, DOCX)
+- Recruiter emails or communications
+- Company research notes (from website, LinkedIn, Glassdoor)
+- Follow-up emails or additional context
+- Application requirements or instructions
+
+**Supported formats**: PDF, TXT, MD, DOCX, HTML, EML
+
+The more context you provide, the better the analysis will be.
+
+### Populating the Application
+
+Once you've added documents to the `input/` folder, navigate to the application directory and run:
+
+```
+cd applications/pending/[your-application-folder]/
+/populate-application
+```
+
+This will:
+1. Read and analyze all documents in the `input/` folder
+2. Extract job requirements, company information, and keywords
+3. Read your `profile.md` to understand your background
+4. Match your experience and skills to the job requirements
+5. Populate `application.md` with:
+   - Extracted job information
+   - Company research and culture insights
+   - Match strategy (which experiences/skills to emphasize)
+   - Key messages to convey
+   - Tone recommendations
+   - Suggested projects and achievements to highlight
+
+**The population preserves any manual notes you've added** - it merges AI analysis with your insights.
+
+### Working with application.md
+
+After population, review and refine the `application.md` file:
+
+- **Review extracted information**: Ensure job details and requirements are accurate
+- **Add your insights**: Enhance the strategy with your own thoughts
+- **Adjust match strategy**: Fine-tune which experiences and projects to emphasize
+- **Add personal notes**: Document your authentic reasons for interest in the role
+- **Plan your approach**: Use the document checklist to track what needs to be created
+
+The `application.md` serves as your strategic planning document for the entire application process.
+
+### Re-populating Applications
+
+You can run `/populate-application` multiple times:
+- Add more documents to `input/` folder
+- Re-run to merge new analysis with existing content
+- Manual notes are always preserved
+
+## When to Read the Profile
+
+Read `profile.md` automatically when the user asks for help with:
+
+- Creating or tailoring a CV/resume
+- Writing a cover letter
+- Drafting an application email
+- Customizing application documents for a specific job
+- Reviewing or improving existing application materials
+- Extracting relevant experience or skills for a position
+- Advice on how to position themselves for a role
+
+## Job Application Workflow
+
+When helping with job applications, follow this comprehensive workflow:
+
+### 0. Profile Validation (REQUIRED FIRST STEP)
+- Run `/validate-profile` to check `profile.md` is complete
+- If validation fails, stop and ask user to complete profile
+- If validation passes or user explicitly skips, proceed to step 1
+
+### 1. Initialize Application (NEW)
+- Use `/new-application "Company - Job Title"` to create organized workspace
+- This creates: `applications/pending/YYYY-MM-DD-Company-JobTitle/`
+- Workspace includes `application.md` template and `input/` folder
+
+### 2. Gather Documents & Context (NEW)
+- User adds documents to `input/` folder:
+  - Job posting/description
+  - Recruiter communications
+  - Company research
+  - Any other relevant context
+- More context = better analysis and strategy
+
+### 3. Analyze & Populate (NEW)
+- Navigate to application folder: `cd applications/pending/[folder-name]/`
+- Run `/populate-application` to:
+  - Read and analyze all input documents
+  - Extract job requirements, keywords, company culture
+  - Cross-reference with `profile.md`
+  - Generate match strategy
+  - Populate `application.md` with research and recommendations
+
+### 4. Review & Refine Strategy
+- User reviews `application.md` for accuracy
+- User adds personal insights and authentic motivations
+- Adjust which experiences and projects to emphasize
+- Fine-tune key messages and tone
+
+### 5. Validate Application (NEW - Quality Gate)
+- Run `/validate-application` to ensure application.md is complete
+- Check that required sections are filled (Organization, Job Title, Job Description)
+- Verify no placeholder text remains (like `[To be filled]`)
+- Get warnings if input/ folder is empty or application seems unpopulated
+- **Must pass before document generation**
+
+### 6. Generate Cover Letter
+- Run `/write-cover-letter` to generate a tailored cover letter
+- System automatically validates application first (stops if incomplete)
+- Checks if cover-letter.md already exists (prevents overwriting)
+- Generates 300-400 word cover letter using:
+  - Profile.md for applicant background and achievements
+  - Application.md for job strategy, key messages, and tone
+- Standard structure: Opening → Why this role → What you bring → Cultural fit → Closing
+- Applies appropriate tone (Formal/Balanced/Casual) from application.md
+- Saves to `cover-letter.md` in application folder
+- Flags available: `--skip-validation`, `--force` (overwrite existing)
+
+### 7. Review and Refine Cover Letter
+- Read generated cover-letter.md carefully
+- Verify factual accuracy (names, dates, achievements)
+- Add personal touches or additional insights
+- Ensure authentic voice and genuine enthusiasm
+- Proofread for typos and flow
+
+### 8. Generate CV (FUTURE)
+- Generate tailored CV based on application.md strategy (coming soon)
+- Emphasize relevant experience from profile.md
+- Incorporate keywords naturally
+
+### 9. Prepare Attachments
+- Convert generated documents to PDF if needed
+- Add final documents to `attachments/` folder:
+  - CV/Resume (PDF)
+  - Cover letter (PDF) - convert from cover-letter.md
+  - Certificates and diplomas (PDF) if required by job posting
+
+### 10. Generate Application Email
+- Run `/write-application-email` to generate professional email with document references
+- System automatically:
+  - Validates application first (stops if incomplete)
+  - Verifies required documents exist in attachments/ folder (CV and cover letter minimum)
+  - Checks if application-email.md already exists (prevents overwriting)
+- Generates brief email (3-4 sentences) including:
+  - Professional subject line (format: "Application for [Job Title] - [Your Name]")
+  - Brief introduction and interest statement
+  - Explicit reference to all attached documents
+  - Contact information and availability statement
+- Applies appropriate tone (Formal/Balanced/Casual) from application.md
+- Detects and applies correct language (German/English)
+- Saves to `application-email.md` in application folder
+- Flags available: `--skip-validation`, `--force` (overwrite existing)
+
+### 11. Review Application Email
+- Read generated application-email.md
+- Verify all attachments are correctly listed
+- Ensure subject line is appropriate
+- Check contact information is current
+- Confirm tone matches company culture
+
+### 12. Quality Assurance
+- Verify all company names, dates, and facts are correct
+- Ensure consistency between all documents (CV ↔ cover letter ↔ email)
+- Check that tone matches the target company culture
+- Confirm ATS optimization if applicable (simple formatting, keywords, standard sections)
+
+## Document Standards
+
+### CV/Resume
+- Use information from relevant sections of `profile.md`
+- Tailor the professional summary to the specific role
+- Emphasize experiences and skills that match job requirements
+- Keep formatting simple and ATS-friendly
+- Use quantifiable achievements when available
+
+### Cover Letter (Generated by `/write-cover-letter`)
+- **Structure**: Opening → Why this role → What you bring → Cultural fit → Closing
+- **Length**: 300-400 words (approximately 1 page)
+- **Tone**: Applied from application.md tone assessment (Formal/Balanced/Casual)
+- **Language**: Inferred from job posting context (German/English)
+- **Content**:
+  - Use ONLY authentic information from profile.md (no fabrication)
+  - Incorporate 2-3 key experiences from match strategy
+  - Reference company research and culture insights from application.md
+  - Natural incorporation of keywords from job description
+  - Company-specific personalization (values, news, projects)
+- **Quality checks**:
+  - Automatic validation before generation
+  - Protection against overwriting existing work
+  - Word count target enforcement (300-400 words)
+  - Factual accuracy verification
+
+### Application Email (Generated by `/write-application-email`)
+- **Structure**: Subject → Greeting → Brief body (3-4 sentences) → Sign-off with contact info
+- **Length**: 3-4 sentences maximum (the cover letter contains the details)
+- **Tone**: Applied from application.md tone assessment (Formal/Balanced/Casual)
+- **Language**: Inferred from job posting context (German/English)
+- **Content**:
+  - Professional subject line: "Application for [Job Title] - [Your Name]"
+  - Brief statement of purpose (applying for the position)
+  - Explicit reference to attached documents (CV, cover letter, certificates)
+  - One sentence showing interest or fit
+  - Availability for interview/discussion
+- **Document Verification**:
+  - Automatic check that CV and cover letter exist in attachments/ folder
+  - Lists all documents that will be attached
+  - Stops generation if required documents are missing
+- **Quality checks**:
+  - Automatic validation before generation
+  - Protection against overwriting existing work
+  - Verification that attachments folder contains required documents
+
+## Cultural Considerations
+
+This framework is designed with the German job market in mind:
+
+- More formal tone is often expected
+- Detailed work history with exact dates is valued
+- Certificates and credentials are highly regarded
+- A professional photo on CV may be common (user's choice)
+
+Adjust recommendations based on the target market if the user specifies a different region.
+
+## Constraints
+
+**Data Privacy**:
+- All information stays local - only API calls to Antigravity use the data
+- Never suggest uploading sensitive personal data to third-party services
+- Respect GDPR and data protection principles
+
+**Accuracy & Honesty**:
+- NEVER fabricate experience, skills, or achievements
+- If `profile.md` lacks information needed for a job application, ask the user to update `profile.md` first
+- Be transparent about what can and cannot be emphasized from the applicant's background
+
+**Quality Standards**:
+- All generated content is a DRAFT - user must review and approve
+- Fact-check company names, contact persons, and details from job postings
+- Maintain consistency across all documents for a single application
+
+## Available Commands
+
+- `/validate-profile` - Validate that `profile.md` is complete and ready for application generation
+- `/new-application "Company - Job Title"` - Create a new application workspace with organized folder structure (includes attachments/ folder)
+- `/populate-application` - Analyze input documents and populate application.md with job info, research, and strategy
+- `/validate-application [optional-app-name]` - Validate that application.md is complete before document generation
+- `/write-cover-letter [optional-app-name] [--skip-validation] [--force]` - Generate a tailored cover letter based on application strategy
+- `/write-application-email [optional-app-name] [--skip-validation] [--force]` - Generate a professional application email with document references
+
+## Example Usage
+
+### Example 1: Complete Application Workflow
+
+**User**: "Help me apply for this software engineering position at TechCorp"
+
+**Antigravity should**:
+1. Run `/validate-profile` to check profile completeness
+2. If validation passes, suggest: "Let's create an application workspace. Run: `/new-application 'TechCorp - Software Engineer'`"
+3. After application is created, guide user: "Add the job posting and any other documents to `applications/pending/[folder]/input/`"
+4. When user has added documents: "Navigate to the application folder and run `/populate-application`"
+5. After population completes: "Review `application.md` to see the analysis and strategy"
+6. Validation step: "Run `/validate-application` to ensure the application is complete"
+7. If validation passes: "Generate cover letter with `/write-cover-letter`"
+8. After generation: "Review cover-letter.md and personalize as needed"
+9. Document preparation: "Convert cover-letter.md to PDF and add it along with your CV to the `attachments/` folder"
+10. Email generation: "Generate application email with `/write-application-email`"
+11. Final review: "Review application-email.md, verify all documents are listed correctly, and you're ready to send!"
+
+### Example 2: Quick Document Request (Legacy Flow)
+
+**User**: "Write a cover letter for this role [paste job description]"
+
+**Antigravity should**:
+1. Run `/validate-profile` to check profile completeness
+2. If validation fails: inform user of incomplete sections and stop
+3. If validation passes: Read `profile.md` to load applicant information
+4. Analyze the job description for requirements and culture
+5. Identify matching experiences and skills from the profile
+6. Generate tailored cover letter using only information from `profile.md`
+7. Suggest: "For better organization, consider using `/new-application` next time to manage the full application process"
+
+### Example 3: Validating an Application
+
+**User**: "Check if my TechCorp application is ready"
+
+**Antigravity should**:
+1. If user is in application folder: Run `/validate-application` (auto-detects current location)
+2. If user is elsewhere: Run `/validate-application 2025-11-02-TechCorp-Software-Engineer`
+3. If validation passes (✅): "Your application is complete! Organization: TechCorp, Position: Software Engineer. Ready for document generation."
+4. If validation fails (❌): Show specific issues like "Organization Name: Contains placeholder '[To be filled]'" and suggest "Please update application.md or run `/populate-application` if you have documents in input/"
+5. Provide clear next steps based on validation result
+
+### Example 4: Generating a Cover Letter
+
+**User**: "Generate cover letter for my TechCorp application"
+
+**Antigravity should**:
+1. If user is in application folder: Run `/write-cover-letter` (auto-detects location)
+2. If user is elsewhere: Run `/write-cover-letter 2025-11-02-TechCorp-Software-Engineer`
+3. System automatically validates application first:
+   - If validation fails: Stop and show errors, suggest fixing or using `--skip-validation`
+   - If validation passes: Proceed to generation
+4. Check for existing cover-letter.md:
+   - If exists: Stop and suggest using `--force` flag to overwrite
+   - If doesn't exist: Proceed to generation
+5. Generate cover letter:
+   - Read profile.md for applicant background
+   - Read application.md for job strategy and tone
+   - Generate 300-400 word tailored cover letter
+   - Save to cover-letter.md
+6. Show success: "✅ Cover letter saved: cover-letter.md. Generated 376 words. Next: Review and personalize."
+
+**User**: "Regenerate the cover letter with different approach"
+
+**Antigravity should**:
+1. Run `/write-cover-letter --force` to overwrite existing file
+2. System warns: "⚠️ Overwriting existing cover letter"
+3. Proceeds with generation
+4. Suggests: "Review the new version and keep whichever you prefer"
+
+### Example 5: Generating an Application Email
+
+**User**: "Generate application email for my TechCorp application"
+
+**Antigravity should**:
+1. If user is in application folder: Run `/write-application-email` (auto-detects location)
+2. If user is elsewhere: Run `/write-application-email 2025-11-02-TechCorp-Software-Engineer`
+3. System automatically validates application first:
+   - If validation fails: Stop and show errors, suggest fixing or using `--skip-validation`
+   - If validation passes: Proceed to document verification
+4. System verifies documents in attachments/ folder:
+   - Check for CV/Resume file
+   - Check for cover letter file
+   - Check for optional certificates
+   - If required documents missing: Stop and show clear error with guidance
+   - If documents found: Proceed to generation
+5. Generate application email:
+   - Read profile.md for applicant contact information
+   - Read application.md for job details and tone
+   - Generate brief email (3-4 sentences) with professional subject line
+   - Include explicit references to all attached documents
+   - Save to application-email.md
+6. Show success: "✅ Application email saved: application-email.md. Attachments ready: CV.pdf, Cover_Letter.pdf. Next: Review and send."
+
+**User**: "There's no CV in attachments folder"
+
+**Antigravity should**:
+1. System detects missing CV during verification step
+2. Show error: "❌ CV/Resume not found in attachments folder"
+3. List what was found and what's missing
+4. Provide guidance: "Please add your CV to: applications/pending/[folder]/attachments/"
+5. Suggest filename conventions: "Tip: Filename should contain 'cv', 'resume', or 'lebenslauf'"
+
+## Updating the Profile
+
+If you notice missing or outdated information during application preparation:
+- Inform the user which sections of `profile.md` need updates
+- Ask them to update `profile.md` first before generating documents
+- This ensures the profile remains the single source of truth
+
+---
+
+**Remember**: The quality of output depends on the quality of `profile.md`. Encourage users to keep it complete, accurate, and up to date.