chore: archive completed OpenSpec changes

Archive all completed changes and create final specifications: Archived changes (2025-11-03): - add-application-email (8 requirements) - add-application-management (9 requirements) - add-application-validation (9 requirements) - add-cover-letter-generation (13 requirements) - add-cover-letter-pdf-conversion (7 requirements) - add-profile-template (4 requirements) - add-profile-validation (3 requirements) Created specifications: - applicant-profile: User profile management with validation - application-email: Email generation for job applications - application-management: Application workflow and folder structure - application-validation: Application completeness checking - cover-letter-generation: Tailored cover letter creation - cover-letter-pdf-conversion: PDF export with Swiss formatting All features are now fully documented in openspec/specs/ and ready for use. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-03 20:38:51 +01:00
parent a05521efa8
commit 84a229c255
29 changed files with 1293 additions and 58 deletions
@@ -1,58 +0,0 @@
 # Implementation Tasks
 ## 1. Template Creation
 - [ ] 1.1 Create Swiss letter LaTeX template at `src/.claude/templates/swiss-letter.tex`
 - [ ] 1.2 Configure scrlttr2 with Swiss Norm (SN) settings
 - [ ] 1.3 Add proper encoding (UTF-8, T1 font encoding) for German characters
 - [ ] 1.4 Implement hyperlinks for email addresses
 - [ ] 1.5 Add Pandoc variable placeholders for all frontmatter fields
 - [ ] 1.6 Add inline comments explaining customizable sections
 - [ ] 1.7 Test template with sample data to ensure proper formatting
 ## 2. Slash Command Implementation
 - [ ] 2.1 Create command file at `src/.claude/commands/convert-cover-letter.md`
 - [ ] 2.2 Implement cover letter file detection logic
 - [ ] 2.3 Implement environment validation checks (Pandoc, LaTeX)
 - [ ] 2.4 Add platform-specific installation instructions
 - [ ] 2.5 Implement frontmatter parsing and validation
 - [ ] 2.6 Build Pandoc command with correct arguments
 - [ ] 2.7 Execute conversion and capture output
 - [ ] 2.8 Implement error handling for common failure scenarios
 - [ ] 2.9 Add success message with file path output
 ## 3. Error Handling & Messaging
 - [ ] 3.1 Create clear error message for missing cover letter
 - [ ] 3.2 Create error message for missing required frontmatter fields
 - [ ] 3.3 Create installation guide for Pandoc (apt, brew, winget)
 - [ ] 3.4 Create installation guide for LaTeX packages
 - [ ] 3.5 Add error handling for YAML parsing failures
 - [ ] 3.6 Add error handling for LaTeX compilation failures
 - [ ] 3.7 Add error handling for file permission issues
 - [ ] 3.8 Add timeout handling for long-running conversions
 ## 4. Testing
 - [ ] 4.1 Test with complete frontmatter and body content
 - [ ] 4.2 Test with minimal required frontmatter only
 - [ ] 4.3 Test with optional enclosures list
 - [ ] 4.4 Test with missing cover-letter.md file
 - [ ] 4.5 Test with invalid YAML frontmatter
 - [ ] 4.6 Test with missing required frontmatter fields
 - [ ] 4.7 Test with special characters (ä, ö, ü, ß) in German text
 - [ ] 4.8 Test environment validation when Pandoc is missing
 - [ ] 4.9 Test environment validation when LaTeX is missing
 - [ ] 4.10 Test error handling for file permission issues
 - [ ] 4.11 Verify Swiss address window positioning with printed output
 - [ ] 4.12 Verify date formatting follows Swiss convention
 ## 5. Documentation
 - [ ] 5.1 Document required frontmatter structure
 - [ ] 5.2 Document system requirements (Pandoc, LaTeX)
 - [ ] 5.3 Add example cover-letter.md with complete frontmatter
 - [ ] 5.4 Document troubleshooting steps for common errors
 - [ ] 5.5 Add template customization guide
 ## 6. Integration
 - [ ] 6.1 Update test directory with new command
 - [ ] 6.2 Update test directory with new template
 - [ ] 6.3 Ensure compatibility with existing cover letter generation
 - [ ] 6.4 Verify workflow integration (step 7 in project.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)
@@ -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
@@ -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
@@ -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
@@ -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)
@@ -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)
@@ -0,0 +1,146 @@
 # 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.
 #### 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