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>
This commit is contained in:
Claude
@@ -0,0 +1,28 @@
|
||||
# Add Application Email Generation
|
||||
|
||||
## Why
|
||||
|
||||
Users need a simple, automated way to compose professional application emails with proper subject lines and document references. Manually crafting these emails for every application is time-consuming and error-prone.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Add `/write-application-email` command that generates email content and subject line
|
||||
- Command verifies required documents exist in `attachments/` folder before generation
|
||||
- Email references CV, cover letter, and optionally certificates/diplomas
|
||||
- Update `/new-application` command to create `attachments/` subfolder with `.keep` file
|
||||
- Follow similar implementation pattern to `/write-cover-letter` command
|
||||
|
||||
## Impact
|
||||
|
||||
**Affected specs:**
|
||||
- `application-email` (new capability)
|
||||
- `application-management` (modification to folder structure)
|
||||
|
||||
**Affected code:**
|
||||
- `src/.claude/commands/new-application.md` - Add attachments folder creation
|
||||
- `src/.claude/commands/write-application-email.md` - New command file
|
||||
- `src/.claude/templates/` - Potentially new email template (if needed)
|
||||
|
||||
**Out of scope:**
|
||||
- Creating or generating documents (CV, certificates) - must exist beforehand
|
||||
- Attachment handling beyond verification
|
||||
+176
@@ -0,0 +1,176 @@
|
||||
# Application Email Generation Specification
|
||||
|
||||
## ADDED 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
|
||||
+63
@@ -0,0 +1,63 @@
|
||||
# Application Management Specification
|
||||
|
||||
## ADDED 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
|
||||
@@ -0,0 +1,58 @@
|
||||
# Implementation Tasks
|
||||
|
||||
## 1. Update Application Folder Structure
|
||||
|
||||
- [ ] 1.1 Modify `src/.claude/commands/new-application.md` to create `attachments/` subfolder
|
||||
- [ ] 1.2 Add creation of `.keep` file inside `attachments/` folder for version control
|
||||
- [ ] 1.3 Update success message in new-application to mention attachments folder
|
||||
- [ ] 1.4 Update test framework at `~/workspace/test-bewerbungen/` with new application structure
|
||||
|
||||
## 2. Create Email Generation Command
|
||||
|
||||
- [ ] 2.1 Create `src/.claude/commands/write-application-email.md` command file
|
||||
- [ ] 2.2 Implement command argument parsing (application name, flags: --force, --help)
|
||||
- [ ] 2.3 Implement location detection (current directory or parameter-based)
|
||||
- [ ] 2.4 Add document verification logic (check for CV, cover letter, certificates in attachments/)
|
||||
- [ ] 2.5 Implement email subject line generation based on job title and company
|
||||
- [ ] 2.6 Implement email body generation with document references
|
||||
- [ ] 2.7 Add language detection (German/English) similar to cover letter
|
||||
- [ ] 2.8 Add tone adaptation (Formal/Balanced/Casual) from application.md
|
||||
- [ ] 2.9 Implement file existence checks and user-friendly error messages
|
||||
- [ ] 2.10 Write generated email to `application-email.md` in application folder
|
||||
|
||||
## 3. Testing & Quality Assurance
|
||||
|
||||
- [ ] 3.1 Test new-application creates attachments folder correctly
|
||||
- [ ] 3.2 Test write-application-email with all required documents present
|
||||
- [ ] 3.3 Test write-application-email with missing documents (error handling)
|
||||
- [ ] 3.4 Test --force flag to overwrite existing email
|
||||
- [ ] 3.5 Test language detection (German/English)
|
||||
- [ ] 3.6 Test tone variations (Formal/Balanced/Casual)
|
||||
- [ ] 3.7 Verify error messages are clear and actionable
|
||||
|
||||
## 4. Documentation
|
||||
|
||||
- [ ] 4.1 Update main CLAUDE.md with write-application-email command reference
|
||||
- [ ] 4.2 Add email generation step to workflow documentation
|
||||
- [ ] 4.3 Update example usage sections with email generation examples
|
||||
- [ ] 4.4 Document attachments folder structure and purpose
|
||||
|
||||
## 5. Integration
|
||||
|
||||
- [ ] 5.1 Ensure email command integrates with existing validation workflow
|
||||
- [ ] 5.2 Verify consistency with write-cover-letter command pattern
|
||||
- [ ] 5.3 Test end-to-end workflow: new-application → populate → validate → cover-letter → email
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Tasks 2.x depend on 1.x (attachments folder must exist)
|
||||
- Tasks 3.x depend on 1.x and 2.x (implementation must be complete)
|
||||
- Tasks 5.x depend on all previous tasks
|
||||
|
||||
## Verification Criteria
|
||||
|
||||
Each task is considered complete when:
|
||||
- Code is written and tested
|
||||
- Error cases are handled gracefully
|
||||
- User-facing messages are clear and helpful
|
||||
- Functionality matches specification
|
||||
@@ -0,0 +1,40 @@
|
||||
# Add Application Management System
|
||||
|
||||
## Why
|
||||
|
||||
Currently, the framework has a profile template and validation, but no structured way to manage individual job applications. Users need a systematic approach to:
|
||||
- Initiate new applications with proper organization
|
||||
- Store job-related documents (ads, emails, recruiter communications) in one place
|
||||
- Have the AI analyze these documents to populate application strategy
|
||||
- Track applications in a folder structure that supports the workflow stages
|
||||
|
||||
This implements the first three steps of the project workflow (Research & Context, Proposal/Strategy, Specification) from `project.md`.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Create two new slash commands:
|
||||
- `/new-application` - Initializes a new application with folder structure
|
||||
- `/populate-application` - Analyzes input documents and populates application.md
|
||||
- Implement folder structure: `src/applications/pending/YYYY-MM-DD-CompanyName-JobTitle/`
|
||||
- Create standardized `application.md` template with sections for research, strategy, and specification
|
||||
- Automatically create `input/` folder for storing job-related documents
|
||||
- Update `src/CLAUDE.md` to include application management workflow
|
||||
|
||||
## Impact
|
||||
|
||||
- **Affected specs**: New capability `application-management`
|
||||
- **Affected code**:
|
||||
- New file: `src/.claude/commands/new-application.md`
|
||||
- New file: `src/.claude/commands/populate-application.md`
|
||||
- Modified: `src/CLAUDE.md` (add application workflow instructions)
|
||||
- New structure: `src/applications/pending/` (created dynamically)
|
||||
- **User benefit**:
|
||||
- Organized workspace for each application
|
||||
- Centralized storage for all job-related documents
|
||||
- AI-powered analysis of job requirements and company research
|
||||
- Clear progression from research → strategy → content generation
|
||||
- **Out of scope**:
|
||||
- Actual CV/cover letter/email generation (future proposal)
|
||||
- Moving applications between stages (pending → sent → archived)
|
||||
- Application tracking and follow-up reminders
|
||||
- **Breaking changes**: None - this is purely additive functionality
|
||||
+147
@@ -0,0 +1,147 @@
|
||||
# Application Management
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### 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,112 @@
|
||||
# Implementation Tasks
|
||||
|
||||
## 1. Create Application Folder Structure
|
||||
|
||||
- [x] 1.1 Create `src/applications/` directory structure
|
||||
- [x] 1.2 Create `src/applications/pending/` directory for applications not yet sent
|
||||
- [x] 1.3 Add `.gitkeep` file to preserve directory structure in git
|
||||
|
||||
## 2. Design Application Template
|
||||
|
||||
- [x] 2.1 Design `application.md` template structure with sections:
|
||||
- Organization Information (name, website, contact person)
|
||||
- Job Information (title, level, department)
|
||||
- Job Description Summary (key points from posting)
|
||||
- Research Notes (company culture, values, recent news)
|
||||
- Match Strategy (which experiences/skills to emphasize)
|
||||
- Key Messages (main points to convey in application)
|
||||
- Tone of Voice (formal/balanced/casual assessment)
|
||||
- Document Checklist (CV needed? Cover letter? Application form?)
|
||||
- [x] 2.2 Add helpful comments and instructions within template
|
||||
- [x] 2.3 Include metadata section (date created, status, deadline if known)
|
||||
|
||||
## 3. Implement `/new-application` Command
|
||||
|
||||
- [x] 3.1 Create `src/.claude/commands/new-application.md`
|
||||
- [x] 3.2 Implement folder name generation logic:
|
||||
- Get current date in YYYY-MM-DD format
|
||||
- Parse user input for organization name and job title
|
||||
- Sanitize names (remove/replace invalid filesystem characters)
|
||||
- Combine into format: `YYYY-MM-DD-OrgName-JobTitle`
|
||||
- [x] 3.3 Implement folder creation logic:
|
||||
- Create `src/applications/pending/[generated-name]/`
|
||||
- Copy `application.md` template to new folder
|
||||
- Create `input/` subfolder
|
||||
- [x] 3.4 Add user guidance:
|
||||
- Confirm successful creation with folder path
|
||||
- Explain next steps (add files to input/, run /populate-application)
|
||||
- Provide examples of useful input files
|
||||
|
||||
## 4. Implement `/populate-application` Command
|
||||
|
||||
- [x] 4.1 Create `src/.claude/commands/populate-application.md`
|
||||
- [x] 4.2 Implement current directory detection:
|
||||
- Check if running from inside an application folder
|
||||
- Verify `application.md` and `input/` exist
|
||||
- Provide helpful error if not in correct location
|
||||
- [x] 4.3 Implement input file discovery:
|
||||
- List all files in `input/` folder
|
||||
- Filter by supported formats (PDF, TXT, MD, DOCX, EML)
|
||||
- Warn about unsupported files
|
||||
- [x] 4.4 Implement document analysis:
|
||||
- Read each supported file
|
||||
- Extract key information (job requirements, company info, contact details)
|
||||
- Identify keywords and skills mentioned
|
||||
- Analyze tone and company culture from language
|
||||
- [x] 4.5 Implement profile cross-reference:
|
||||
- Read `src/profile.md`
|
||||
- Match job requirements to applicant's experience
|
||||
- Identify which projects/skills/achievements to emphasize
|
||||
- Suggest relevant stories or examples from profile
|
||||
- [x] 4.6 Implement application.md population:
|
||||
- Update each section with extracted/analyzed information
|
||||
- Preserve any existing manual entries
|
||||
- Mark auto-populated sections with timestamp
|
||||
- Leave sections empty if no relevant information found
|
||||
- [x] 4.7 Implement interactive prompts:
|
||||
- Ask user for missing critical information
|
||||
- Confirm before overwriting existing content
|
||||
- Provide summary of changes made
|
||||
|
||||
## 5. Update Framework Instructions
|
||||
|
||||
- [x] 5.1 Update `src/CLAUDE.md` to add application management workflow section
|
||||
- [x] 5.2 Document the workflow sequence:
|
||||
1. Validate profile (existing)
|
||||
2. Initialize new application (`/new-application`)
|
||||
3. Gather documents (user adds to input/)
|
||||
4. Populate application (`/populate-application`)
|
||||
5. Review and refine application.md manually if needed
|
||||
6. Generate documents (future: CV, cover letter, email)
|
||||
- [x] 5.3 Add command reference for `/new-application` and `/populate-application`
|
||||
- [x] 5.4 Add guidance on what files to put in input/ folder
|
||||
- [x] 5.5 Explain how to work with application.md after population
|
||||
|
||||
## 6. Handle Edge Cases
|
||||
|
||||
- [x] 6.1 Handle duplicate folder names (append counter if exists)
|
||||
- [x] 6.2 Handle very long organization/job names (truncate with ellipsis)
|
||||
- [x] 6.3 Handle missing input folder during population
|
||||
- [x] 6.4 Handle corrupted or unreadable input files
|
||||
- [x] 6.5 Handle running commands from wrong directory
|
||||
- [x] 6.6 Handle missing profile.md during population (graceful degradation)
|
||||
|
||||
## 7. Create Example Application (for testing)
|
||||
|
||||
- [x] 7.1 Create example application folder structure manually for testing
|
||||
- [x] 7.2 Add sample job posting to input/ folder
|
||||
- [x] 7.3 Test population command with sample data
|
||||
- [x] 7.4 Document expected output in tasks or design doc
|
||||
|
||||
## 8. Validation & Documentation
|
||||
|
||||
- [x] 8.1 Verify `/new-application` creates correct folder structure
|
||||
- [x] 8.2 Verify application.md template has all required sections
|
||||
- [x] 8.3 Verify input/ folder is created
|
||||
- [x] 8.4 Verify `/populate-application` reads files from input/
|
||||
- [x] 8.5 Verify population extracts key information correctly
|
||||
- [x] 8.6 Verify profile integration works (matches skills/experience)
|
||||
- [x] 8.7 Verify edge cases are handled gracefully
|
||||
- [x] 8.8 Test with real job posting to validate workflow
|
||||
- [x] 8.9 Update CLAUDE.md instructions are clear and complete
|
||||
- [x] 8.10 Validate with `openspec validate add-application-management --strict`
|
||||
@@ -0,0 +1,120 @@
|
||||
# Proposal: Application Validation
|
||||
|
||||
## Why
|
||||
|
||||
Currently, users can create and populate applications using `/new-application` and `/populate-application`, but there's no validation mechanism to ensure the application.md files are complete before generating professional documents (CV, cover letter, email).
|
||||
|
||||
**Problems without validation:**
|
||||
- Users might try to generate documents with placeholder text like `[To be filled]` still present
|
||||
- Incomplete job information could lead to poorly targeted applications
|
||||
- No quality gate to catch missing critical information before document generation
|
||||
- Users might forget to run `/populate-application` after adding input documents
|
||||
|
||||
**Similar to `/validate-profile`**, we need a validation command that acts as a quality gate, ensuring application.md files are ready for document generation.
|
||||
|
||||
## What
|
||||
|
||||
Add a `/validate-application` slash command that validates the completeness of application.md files.
|
||||
|
||||
### Core Functionality
|
||||
|
||||
1. **Auto-detection**: When run without parameters, detect if current directory is inside an application folder
|
||||
2. **Explicit path**: Accept optional application folder name/path as parameter
|
||||
3. **Required section validation**: Check that critical sections are filled (Organization Info, Job Info, Job Description Summary)
|
||||
4. **Placeholder detection**: Identify unfilled template placeholders like `[To be filled]`, `[...]`, bracket patterns
|
||||
5. **Population awareness**: Warn if `input/` folder is empty or application seems unpopulated
|
||||
6. **Binary pass/fail**: Clear ✅ PASSED or ❌ FAILED status (consistent with `/validate-profile`)
|
||||
7. **Actionable errors**: Show specific issues with quoted placeholder text and guidance on how to fix
|
||||
|
||||
### Optional Sections
|
||||
|
||||
These can remain incomplete without causing validation failure:
|
||||
- Match Strategy
|
||||
- Key Messages
|
||||
- Tone of Voice
|
||||
- Research Notes
|
||||
- Document Checklist
|
||||
|
||||
### User Experience
|
||||
|
||||
```bash
|
||||
# Run from inside application folder
|
||||
cd applications/pending/2025-11-02-TechCorp-Senior-Developer
|
||||
/validate-application
|
||||
|
||||
# Or provide path from anywhere
|
||||
/validate-application 2025-11-02-TechCorp-Senior-Developer
|
||||
```
|
||||
|
||||
**Success output:**
|
||||
```
|
||||
✅ Application Validation: PASSED
|
||||
|
||||
Your application is complete and ready for document generation!
|
||||
|
||||
Summary:
|
||||
- Organization: TechCorp
|
||||
- Position: Senior Developer
|
||||
- Job requirements: 12 identified
|
||||
- Match strategy: Complete
|
||||
- Input documents: 3 files analyzed
|
||||
|
||||
You can now proceed with generating tailored CV, cover letter, and application email.
|
||||
```
|
||||
|
||||
**Failure output:**
|
||||
```
|
||||
❌ Application Validation: FAILED
|
||||
|
||||
Your application has incomplete sections that need attention.
|
||||
|
||||
Issues found:
|
||||
|
||||
## Organization Information
|
||||
- [ ] Organization Name: Contains placeholder "[To be filled]"
|
||||
|
||||
## Job Description Summary
|
||||
- [ ] Responsibilities: No responsibilities documented
|
||||
- [ ] Required Skills: Contains placeholder "[List required skills]"
|
||||
|
||||
## Population Status
|
||||
⚠️ Input folder appears empty. Consider:
|
||||
1. Adding job posting and related documents to input/
|
||||
2. Running /populate-application to extract information
|
||||
|
||||
Please update application.md, then run /validate-application again.
|
||||
```
|
||||
|
||||
## Impact
|
||||
|
||||
### Benefits
|
||||
- **Quality gate**: Prevents generating documents with placeholder text
|
||||
- **User guidance**: Clear feedback on what's missing and how to fix it
|
||||
- **Workflow integration**: Natural step before document generation
|
||||
- **Consistency**: Matches `/validate-profile` pattern users already know
|
||||
- **Error prevention**: Catches incomplete applications early
|
||||
|
||||
### Changes Required
|
||||
- New slash command: `/validate-application`
|
||||
- Documentation updates in `src/CLAUDE.md`
|
||||
- No changes to existing commands or templates
|
||||
|
||||
### User Workflow Update
|
||||
```
|
||||
1. Validate profile (/validate-profile)
|
||||
2. Initialize application (/new-application)
|
||||
3. Add documents to input/ folder
|
||||
4. Populate application (/populate-application)
|
||||
5. **Validate application (/validate-application)** ← NEW
|
||||
6. Generate documents (future: CV, cover letter, email)
|
||||
```
|
||||
|
||||
## Implementation Approach
|
||||
|
||||
Follow the same pattern as `/validate-profile`:
|
||||
- Read application.md and parse sections
|
||||
- Check for bracket patterns: `\[([^\]]+)\]`
|
||||
- Validate required sections have real content
|
||||
- Check input/ folder exists and has files
|
||||
- Provide structured, actionable error messages
|
||||
- Use encouraging tone and clear next steps
|
||||
+223
@@ -0,0 +1,223 @@
|
||||
# Application Validation
|
||||
|
||||
## ADDED 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,192 @@
|
||||
# Implementation Tasks
|
||||
|
||||
## 1. Design Validation Logic
|
||||
|
||||
- [x] 1.1 Study `/validate-profile` command structure and pattern
|
||||
- [x] 1.2 Define required vs optional sections for application.md
|
||||
- [x] 1.3 Design placeholder detection regex patterns
|
||||
- [x] 1.4 Define validation pass/fail criteria
|
||||
- [x] 1.5 Design error message format and structure
|
||||
|
||||
## 2. Implement Location Detection
|
||||
|
||||
- [x] 2.1 Implement current directory detection logic
|
||||
- Check if cwd ends with pattern: `applications/pending/[folder-name]/`
|
||||
- Verify `application.md` exists in current directory
|
||||
- [x] 2.2 Implement parameter parsing logic
|
||||
- Accept folder name (e.g., `2025-11-02-TechCorp-Developer`)
|
||||
- Accept relative path (e.g., `applications/pending/2025-11-02-TechCorp-Developer`)
|
||||
- Accept absolute path
|
||||
- [x] 2.3 Implement application discovery
|
||||
- List available applications in `applications/pending/`
|
||||
- Handle empty applications directory gracefully
|
||||
|
||||
## 3. Implement Error Handling for Location
|
||||
|
||||
- [x] 3.1 Handle running from wrong directory without parameter
|
||||
- Show error message
|
||||
- List available applications
|
||||
- Provide usage examples
|
||||
- [x] 3.2 Handle non-existent application with parameter
|
||||
- Show error: "Application not found: [name]"
|
||||
- List available applications
|
||||
- [x] 3.3 Handle missing application.md
|
||||
- Show error: "No application.md found in [path]"
|
||||
- Suggest this may not be a valid application folder
|
||||
|
||||
## 4. Implement File Reading & Parsing
|
||||
|
||||
- [x] 4.1 Read application.md file content
|
||||
- [x] 4.2 Parse markdown sections by headings
|
||||
- Identify section boundaries
|
||||
- Extract content for each section
|
||||
- [x] 4.3 Handle corrupted or unreadable files
|
||||
- Catch read errors
|
||||
- Provide helpful error message
|
||||
- [x] 4.4 Implement case-insensitive section matching
|
||||
- Match "Organization Information", "organization information", etc.
|
||||
|
||||
## 5. Implement Placeholder Detection
|
||||
|
||||
- [x] 5.1 Create regex for square bracket placeholders: `\[([^\]]+)\]`
|
||||
- [x] 5.2 Create patterns for common placeholders:
|
||||
- `[To be filled]`
|
||||
- `[Organization name]`
|
||||
- `[Job Title]`
|
||||
- `[...]`
|
||||
- [x] 5.3 Detect generic template text
|
||||
- "Add information here"
|
||||
- "To be filled"
|
||||
- Other unchanged template phrases
|
||||
- [x] 5.4 Implement context-aware detection
|
||||
- Don't flag legitimate brackets like `[PhD]`, `[Acquired]`
|
||||
- Check surrounding context for meaningful use
|
||||
- [x] 5.5 Handle very long placeholder text (truncate to 100 chars)
|
||||
|
||||
## 6. Implement Required Section Validation
|
||||
|
||||
- [x] 6.1 Validate Organization Information section
|
||||
- Check for Organization Name field
|
||||
- Detect placeholders in name field
|
||||
- [x] 6.2 Validate Job Information section
|
||||
- Check for Job Title field
|
||||
- Detect placeholders in title field
|
||||
- [x] 6.3 Validate Job Description Summary section
|
||||
- Check if section has any content
|
||||
- Verify at least one subsection (Responsibilities/Required Skills/etc.) has real content
|
||||
- Detect if all subsections only have placeholders
|
||||
- [x] 6.4 Implement empty section detection
|
||||
- Check if required sections exist but have no content
|
||||
- Report missing required sections
|
||||
|
||||
## 7. Implement Optional Section Handling
|
||||
|
||||
- [x] 7.1 Identify optional sections (don't validate):
|
||||
- Match Strategy
|
||||
- Key Messages
|
||||
- Tone of Voice
|
||||
- Research Notes
|
||||
- Document Checklist
|
||||
- Application Strategy Notes
|
||||
- Timeline
|
||||
- [x] 7.2 Ensure optional sections don't cause validation failure
|
||||
- [x] 7.3 Allow these sections to contain placeholders without error
|
||||
|
||||
## 8. Implement Population Awareness
|
||||
|
||||
- [x] 8.1 Check if `input/` folder exists
|
||||
- [x] 8.2 Check if `input/` folder contains files
|
||||
- [x] 8.3 Implement warning logic:
|
||||
- If `input/` is empty AND most sections have placeholders → suggest adding documents and running `/populate-application`
|
||||
- If `input/` has files AND most sections still have placeholders → suggest running `/populate-application`
|
||||
- If required sections are filled → don't warn (manually populated is fine)
|
||||
- [x] 8.4 Add population warning to failure output
|
||||
|
||||
## 9. Implement Pass/Fail Reporting
|
||||
|
||||
- [x] 9.1 Design success output format:
|
||||
- ✅ emoji and "Application Validation: PASSED" title
|
||||
- Summary section with key information extracted from application.md
|
||||
- Encouraging message
|
||||
- Clear next step
|
||||
- [x] 9.2 Design failure output format:
|
||||
- ❌ emoji and "Application Validation: FAILED" title
|
||||
- Explanation paragraph
|
||||
- "Issues found:" heading
|
||||
- Structured error list organized by section
|
||||
- Actionable guidance
|
||||
- [x] 9.3 Implement structured error grouping
|
||||
- Group errors by section (## Organization Information, ## Job Description Summary, etc.)
|
||||
- Use checkbox format: `- [ ] Field Name: Issue description`
|
||||
- [x] 9.4 Quote specific placeholder text in errors
|
||||
- Extract and quote the actual placeholder found
|
||||
- Truncate if longer than 100 characters
|
||||
|
||||
## 10. Create Slash Command File
|
||||
|
||||
- [x] 10.1 Create `src/.claude/commands/validate-application.md`
|
||||
- [x] 10.2 Write comprehensive instructions covering:
|
||||
- Location detection logic (current directory vs parameter)
|
||||
- Error handling for wrong location
|
||||
- File reading and parsing
|
||||
- Placeholder detection patterns
|
||||
- Required vs optional section validation
|
||||
- Population awareness checks
|
||||
- Success/failure output formatting
|
||||
- Edge case handling
|
||||
- [x] 10.3 Add examples of success and failure outputs
|
||||
- [x] 10.4 Include edge case handling instructions
|
||||
|
||||
## 11. Update Framework Documentation
|
||||
|
||||
- [x] 11.1 Update `src/CLAUDE.md` - Add `/validate-application` to command reference
|
||||
- [x] 11.2 Update workflow section to include validation step
|
||||
- Add between "Populate application" and "Generate documents" (future)
|
||||
- [x] 11.3 Add best practices note about validating before generation
|
||||
- [x] 11.4 Add usage examples:
|
||||
- Running from inside application folder
|
||||
- Running with explicit path
|
||||
- [x] 11.5 Update `/populate-application` documentation to mention validation as next step
|
||||
|
||||
## 12. Integration Points
|
||||
|
||||
- [x] 12.1 Ensure consistency with `/validate-profile` pattern
|
||||
- Match output format
|
||||
- Match tone and language
|
||||
- Match error structure
|
||||
- [x] 12.2 Verify workflow integration:
|
||||
- Profile validation → Application init → Add documents → Populate → **Validate** → Generate
|
||||
- [x] 12.3 Consider future document generation integration
|
||||
- Validation will be prerequisite for generation commands
|
||||
|
||||
## 13. Testing & Validation
|
||||
|
||||
- [x] 13.1 Test from inside application folder (no parameter)
|
||||
- [x] 13.2 Test with folder name parameter
|
||||
- [x] 13.3 Test with path parameter
|
||||
- [x] 13.4 Test from wrong location (should show error + list)
|
||||
- [x] 13.5 Test with non-existent application
|
||||
- [x] 13.6 Test with complete application (should pass)
|
||||
- [x] 13.7 Test with incomplete application (should fail with specific errors)
|
||||
- [x] 13.8 Test with empty input/ folder (should warn)
|
||||
- [x] 13.9 Test with populated input/ but empty sections (should suggest /populate-application)
|
||||
- [x] 13.10 Test with manually populated application (should pass even if input/ empty)
|
||||
- [x] 13.11 Test placeholder detection accuracy (catch placeholders, allow legitimate brackets)
|
||||
- [x] 13.12 Test missing application.md file
|
||||
- [x] 13.13 Test missing required sections
|
||||
- [x] 13.14 Validate proposal: `openspec validate add-application-validation --strict`
|
||||
|
||||
## 14. Update Test Environment
|
||||
|
||||
- [x] 14.1 Copy new `/validate-application` command to test directory
|
||||
- [x] 14.2 Update `CLAUDE.md` in test directory
|
||||
- [x] 14.3 Preserve test directory's `profile.md` and `applications/` folder
|
||||
- [x] 14.4 Test in actual test environment
|
||||
|
||||
## 15. Git Workflow
|
||||
|
||||
- [x] 15.1 Verify all changes are on feature branch `feature/application-validation`
|
||||
- [x] 15.2 Stage all files (OpenSpec proposal, slash command, documentation updates)
|
||||
- [x] 15.3 Create descriptive commit message following conventional commits format
|
||||
- [x] 15.4 Merge feature branch into main
|
||||
- [x] 15.5 Verify final state
|
||||
@@ -0,0 +1,218 @@
|
||||
# Proposal: Cover Letter Generation
|
||||
|
||||
## Why
|
||||
|
||||
The application management system now supports creating, populating, and validating applications, but users still must manually write their cover letters. This is time-consuming and doesn't leverage the strategic analysis already captured in `application.md`.
|
||||
|
||||
**Problems without automated cover letter generation:**
|
||||
- Users must manually translate match strategy into compelling narrative
|
||||
- Risk of inconsistency between application strategy and actual cover letter content
|
||||
- Time-consuming to write personalized cover letters for each application
|
||||
- May not effectively incorporate key messages and tone guidance from application.md
|
||||
- Difficult to maintain consistent quality across multiple applications
|
||||
|
||||
**Current workflow gap:**
|
||||
1. ✅ Validate profile
|
||||
2. ✅ Create application
|
||||
3. ✅ Populate application with job analysis
|
||||
4. ✅ Validate application completeness
|
||||
5. ❌ **Generate cover letter** ← Missing
|
||||
6. ❌ Generate CV (future)
|
||||
7. ❌ Generate application email (future)
|
||||
|
||||
## What
|
||||
|
||||
Add a `/write-cover-letter` slash command that generates tailored cover letters based on the strategic analysis in `application.md` and personal information in `profile.md`.
|
||||
|
||||
### Core Functionality
|
||||
|
||||
1. **Location Detection**: Auto-detect current application folder or accept optional application name parameter
|
||||
2. **Safety Gates**:
|
||||
- Automatically run `/validate-application` before generating (stop if fails)
|
||||
- Check if `cover-letter.md` already exists (stop if exists)
|
||||
- Allow explicit overrides via flags: `--skip-validation`, `--force`/`--overwrite`
|
||||
3. **Multi-source Generation**:
|
||||
- Read `profile.md` for applicant background (experience, skills, achievements)
|
||||
- Read `application.md` for job-specific strategy (match strategy, key messages, tone, company insights)
|
||||
4. **Standard Structure**: Generate 1-page cover letter with:
|
||||
- **Opening**: Introduction and position reference
|
||||
- **Why This Role**: Genuine interest, company research insights
|
||||
- **What You Bring**: Relevant experience and skills (from match strategy)
|
||||
- **Cultural Fit**: Alignment with company values and culture
|
||||
- **Closing**: Strong call to action, availability
|
||||
5. **Tone & Language**:
|
||||
- Use tone guidance from application.md (Formal/Balanced/Casual)
|
||||
- Infer language (German/English) from job posting context
|
||||
6. **Output**: Save to `cover-letter.md` in application folder
|
||||
|
||||
### User Experience
|
||||
|
||||
```bash
|
||||
# From inside application folder
|
||||
cd applications/pending/2025-11-02-TechCorp-Senior-Developer
|
||||
/write-cover-letter
|
||||
|
||||
# Or from anywhere with parameter
|
||||
/write-cover-letter 2025-11-02-TechCorp-Senior-Developer
|
||||
|
||||
# Override safety checks
|
||||
/write-cover-letter --skip-validation
|
||||
/write-cover-letter --force # Overwrite existing cover-letter.md
|
||||
```
|
||||
|
||||
**Success flow:**
|
||||
```
|
||||
🔍 Validating application...
|
||||
✅ Application validation passed
|
||||
|
||||
📝 Generating cover letter...
|
||||
|
||||
✓ Read profile.md (applicant background)
|
||||
✓ Read application.md (job strategy)
|
||||
✓ Analyzed match strategy (3 key experiences identified)
|
||||
✓ Incorporated key messages
|
||||
✓ Applied tone: Balanced
|
||||
✓ Language: English
|
||||
✓ Generated 376 words (target: 300-400)
|
||||
|
||||
✅ Cover letter saved: cover-letter.md
|
||||
|
||||
Next steps:
|
||||
1. Review cover-letter.md for accuracy and authenticity
|
||||
2. Personalize with any additional insights
|
||||
3. Generate CV: /write-cv (coming soon)
|
||||
```
|
||||
|
||||
**Blocked flow (validation fails):**
|
||||
```
|
||||
🔍 Validating application...
|
||||
❌ Application validation failed
|
||||
|
||||
Your application has incomplete sections. Please fix these issues first:
|
||||
|
||||
## Job Description Summary
|
||||
- [ ] Required Skills: Missing or empty
|
||||
|
||||
Run /validate-application for full details, or use --skip-validation to proceed anyway (not recommended).
|
||||
```
|
||||
|
||||
**Blocked flow (cover letter exists):**
|
||||
```
|
||||
❌ Cover letter already exists: cover-letter.md
|
||||
|
||||
To regenerate, use:
|
||||
/write-cover-letter --force
|
||||
|
||||
Warning: This will overwrite your existing cover letter.
|
||||
```
|
||||
|
||||
### Content Generation Strategy
|
||||
|
||||
**Opening Paragraph (Hook + Position):**
|
||||
- Reference specific job title and company name
|
||||
- Brief statement of interest
|
||||
- One compelling reason for applying (from research notes or key messages)
|
||||
|
||||
**Why This Role Paragraph:**
|
||||
- Connection to company mission/values (from research notes)
|
||||
- Genuine interest in the role (from key messages)
|
||||
- Reference to company news, projects, or initiatives
|
||||
|
||||
**What You Bring Paragraphs (1-2):**
|
||||
- Highlight 2-3 most relevant experiences from match strategy
|
||||
- Use specific achievements and quantifiable results from profile.md
|
||||
- Connect experiences to job requirements
|
||||
- Incorporate keywords from job description
|
||||
|
||||
**Cultural Fit Paragraph:**
|
||||
- Align personal values with company culture (from research notes)
|
||||
- Reference soft skills that match company culture indicators
|
||||
- Show enthusiasm for work environment or team
|
||||
|
||||
**Closing Paragraph:**
|
||||
- Strong statement of interest
|
||||
- Availability for interview
|
||||
- Thank you and call to action
|
||||
- Professional sign-off
|
||||
|
||||
**Quality Standards:**
|
||||
- Length: 300-400 words (1 page)
|
||||
- Tone: Match application.md tone assessment
|
||||
- Language: Inferred from job posting
|
||||
- Authenticity: Use real experiences from profile.md only
|
||||
- Keywords: Incorporate naturally from job description
|
||||
- Personalization: Reference company-specific insights
|
||||
|
||||
## Impact
|
||||
|
||||
### Benefits
|
||||
- **Time savings**: Reduce cover letter writing from 1-2 hours to 10-15 minutes (review/refinement)
|
||||
- **Consistency**: Ensures cover letter aligns with application strategy
|
||||
- **Quality**: Leverages strategic analysis already done in application.md
|
||||
- **Personalization**: Each cover letter tailored to specific job and company
|
||||
- **Completeness**: Addresses all key messages identified in planning phase
|
||||
- **ATS optimization**: Natural incorporation of keywords from job description
|
||||
|
||||
### Changes Required
|
||||
- New slash command: `/write-cover-letter`
|
||||
- Documentation updates in `src/CLAUDE.md`
|
||||
- No changes to existing commands or templates
|
||||
|
||||
### User Workflow Impact
|
||||
|
||||
**Updated workflow:**
|
||||
```
|
||||
1. Validate profile (/validate-profile)
|
||||
2. Initialize application (/new-application)
|
||||
3. Add documents to input/ folder
|
||||
4. Populate application (/populate-application)
|
||||
5. Validate application (/validate-application)
|
||||
6. **Generate cover letter (/write-cover-letter)** ← NEW
|
||||
7. Review and refine cover-letter.md manually
|
||||
8. Generate CV (future: /write-cv)
|
||||
9. Generate email (future: /write-email)
|
||||
```
|
||||
|
||||
### Risks & Mitigations
|
||||
|
||||
**Risk**: Generated cover letters may sound generic or AI-written
|
||||
**Mitigation**:
|
||||
- Use authentic experiences from profile.md only
|
||||
- Incorporate company-specific research from application.md
|
||||
- Apply appropriate tone from tone assessment
|
||||
- Encourage manual review and personalization
|
||||
|
||||
**Risk**: Overwriting existing work
|
||||
**Mitigation**:
|
||||
- Check for existing cover-letter.md and stop
|
||||
- Require explicit `--force` flag to overwrite
|
||||
- Warn user about overwrite consequences
|
||||
|
||||
**Risk**: Generating from incomplete application
|
||||
**Mitigation**:
|
||||
- Auto-run /validate-application before generation
|
||||
- Stop if validation fails (unless `--skip-validation`)
|
||||
- Clear error messages about what needs to be fixed
|
||||
|
||||
## Implementation Approach
|
||||
|
||||
**Pattern consistency:**
|
||||
- Follow same location detection as `/validate-application`
|
||||
- Match command structure and error handling patterns
|
||||
- Use consistent validation and safety check patterns
|
||||
|
||||
**Data sources:**
|
||||
- Primary: application.md (match strategy, key messages, tone, research)
|
||||
- Secondary: profile.md (experience, skills, achievements)
|
||||
- Tertiary: Job description from input/ (if needed for additional context)
|
||||
|
||||
**Generation approach:**
|
||||
- Use Claude to generate human-quality prose
|
||||
- Maintain factual accuracy (no hallucination)
|
||||
- Balance structure with natural flow
|
||||
- Target specific word count (300-400 words)
|
||||
|
||||
**Future integration:**
|
||||
- Cover letter generation is first of three document commands
|
||||
- Pattern will be reused for `/write-cv` and `/write-email`
|
||||
- Consider unified template system for all document types
|
||||
+343
@@ -0,0 +1,343 @@
|
||||
# Cover Letter Generation
|
||||
|
||||
## ADDED 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,315 @@
|
||||
# Implementation Tasks
|
||||
|
||||
## 1. Design Cover Letter Structure
|
||||
|
||||
- [x] 1.1 Define standard cover letter sections and order
|
||||
- [x] 1.2 Determine word count targets for each section
|
||||
- [x] 1.3 Design template structure for German vs English letters
|
||||
- [x] 1.4 Define tone variations (Formal/Balanced/Casual) and language patterns
|
||||
- [x] 1.5 Create examples of good opening hooks, closing statements
|
||||
|
||||
## 2. Implement Location Detection
|
||||
|
||||
- [x] 2.1 Reuse location detection pattern from `/validate-application`
|
||||
- Check current directory for application folder pattern
|
||||
- Accept optional application name parameter
|
||||
- Resolve parameter to full application path
|
||||
- [x] 2.2 Handle missing or unclear location
|
||||
- Show error message
|
||||
- List available applications in `applications/pending/`
|
||||
- Provide usage examples
|
||||
- [x] 2.3 Verify application.md exists in target location
|
||||
|
||||
## 3. Implement Validation Gate
|
||||
|
||||
- [x] 3.1 Auto-run `/validate-application` before generation
|
||||
- Execute validation command programmatically
|
||||
- Capture validation result (pass/fail)
|
||||
- Show validation progress: "🔍 Validating application..."
|
||||
- [x] 3.2 Handle validation failure
|
||||
- Stop generation if validation fails
|
||||
- Show validation error details
|
||||
- Suggest fixing issues or using `--skip-validation` flag
|
||||
- [x] 3.3 Implement `--skip-validation` flag
|
||||
- Parse flag from command arguments
|
||||
- Skip validation check if flag present
|
||||
- Show warning: "Skipping validation (not recommended)"
|
||||
- [x] 3.4 Handle validation success
|
||||
- Show success message: "✅ Application validation passed"
|
||||
- Proceed to generation
|
||||
|
||||
## 4. Implement Existing File Check
|
||||
|
||||
- [x] 4.1 Check if `cover-letter.md` exists in application folder
|
||||
- [x] 4.2 Handle existing file (stop generation)
|
||||
- Show error: "Cover letter already exists"
|
||||
- Suggest using `--force` flag to overwrite
|
||||
- Include file path in error message
|
||||
- [x] 4.3 Implement `--force` / `--overwrite` flag
|
||||
- Parse flag from command arguments
|
||||
- Skip existing file check if flag present
|
||||
- Show warning: "Overwriting existing cover-letter.md"
|
||||
- [x] 4.4 Proceed if no existing file
|
||||
|
||||
## 5. Implement Data Reading
|
||||
|
||||
- [x] 5.1 Read profile.md
|
||||
- Check if profile.md exists
|
||||
- Parse personal information section
|
||||
- Parse professional summary
|
||||
- Parse work experience entries
|
||||
- Parse skills and achievements
|
||||
- Parse projects section
|
||||
- Handle missing or corrupted profile.md (error and stop)
|
||||
- [x] 5.2 Read application.md
|
||||
- Check if application.md exists
|
||||
- Parse organization information (company name, location)
|
||||
- Parse job information (job title, level)
|
||||
- Parse job description summary (requirements, responsibilities)
|
||||
- Parse match strategy section
|
||||
- Parse key messages section
|
||||
- Parse tone of voice section
|
||||
- Parse research notes section
|
||||
- Handle missing or corrupted application.md (error and stop)
|
||||
- [x] 5.3 Cross-reference match strategy with profile
|
||||
- Identify experiences to emphasize from match strategy
|
||||
- Extract those specific experiences from profile.md
|
||||
- Identify skills to highlight
|
||||
- Identify projects to mention
|
||||
|
||||
## 6. Implement Tone and Language Detection
|
||||
|
||||
- [x] 6.1 Extract tone assessment from application.md
|
||||
- Find "Tone of Voice" section
|
||||
- Parse tone value (Formal/Balanced/Casual)
|
||||
- Default to "Balanced" if not specified
|
||||
- [x] 6.2 Infer language from context
|
||||
- Check job posting language indicators
|
||||
- Check company location (German companies likely want German)
|
||||
- Check if application.md is written in German
|
||||
- Default to English if unclear
|
||||
- [x] 6.3 Define language-specific formatting
|
||||
- German: "Sehr geehrte Damen und Herren" / "Mit freundlichen Grüßen"
|
||||
- English: "Dear Hiring Manager" / "Sincerely"
|
||||
- Date formats (DE: DD.MM.YYYY, EN: Month DD, YYYY)
|
||||
|
||||
## 7. Implement Content Generation
|
||||
|
||||
- [x] 7.1 Generate contact header
|
||||
- Use applicant name, email, phone from profile.md
|
||||
- Format address block
|
||||
- Add date (current date)
|
||||
- Add company address (from application.md)
|
||||
- [x] 7.2 Generate salutation
|
||||
- Use recruiter name if available in application.md
|
||||
- Otherwise: "Dear Hiring Manager" (EN) or "Sehr geehrte Damen und Herren" (DE)
|
||||
- [x] 7.3 Generate opening paragraph (50-70 words)
|
||||
- Reference job title and company name
|
||||
- State interest in the position
|
||||
- Include one compelling hook (from key messages or research)
|
||||
- Maintain appropriate tone
|
||||
- [x] 7.4 Generate "why this role" paragraph (70-90 words)
|
||||
- Reference company research insights
|
||||
- Connect to company values or mission
|
||||
- Show genuine interest based on key messages
|
||||
- Reference company-specific news or initiatives if available
|
||||
- [x] 7.5 Generate "what you bring" content (120-150 words, 1-2 paragraphs)
|
||||
- Highlight 2-3 experiences from match strategy
|
||||
- Use specific achievements from profile.md
|
||||
- Connect experiences to job requirements
|
||||
- Incorporate keywords naturally
|
||||
- Use quantifiable results when available
|
||||
- [x] 7.6 Generate cultural fit paragraph (50-70 words)
|
||||
- Reference company culture insights from research notes
|
||||
- Align personal values with company values
|
||||
- Mention relevant soft skills
|
||||
- Show enthusiasm for work environment
|
||||
- [x] 7.7 Generate closing paragraph (40-50 words)
|
||||
- Strong statement of interest
|
||||
- Availability for interview/discussion
|
||||
- Thank hiring manager
|
||||
- Professional call to action
|
||||
- [x] 7.8 Generate sign-off
|
||||
- Use appropriate closing based on language and tone
|
||||
- Include applicant name from profile.md
|
||||
|
||||
## 8. Implement Quality Checks
|
||||
|
||||
- [x] 8.1 Verify word count (target: 300-400 words)
|
||||
- Count words in generated content
|
||||
- Adjust if too short (<280) or too long (>420)
|
||||
- [x] 8.2 Verify factual accuracy
|
||||
- Ensure all experiences mentioned exist in profile.md
|
||||
- Ensure all company information matches application.md
|
||||
- No hallucinated facts or achievements
|
||||
- [x] 8.3 Verify tone consistency
|
||||
- Check language matches tone assessment
|
||||
- Formal: professional vocabulary, traditional structure
|
||||
- Balanced: mix of professional and approachable
|
||||
- Casual: conversational but still professional
|
||||
- [x] 8.4 Verify keyword incorporation
|
||||
- Check that key job requirements are mentioned
|
||||
- Ensure keywords flow naturally (not listed)
|
||||
- [x] 8.5 Verify personalization
|
||||
- Check company-specific references are included
|
||||
- Verify it doesn't sound generic
|
||||
|
||||
## 9. Implement File Writing
|
||||
|
||||
- [x] 9.1 Format cover letter as markdown
|
||||
- Use proper heading hierarchy
|
||||
- Format contact information block
|
||||
- Format body paragraphs with spacing
|
||||
- Include metadata comment (generated date, sources)
|
||||
- [x] 9.2 Write to cover-letter.md in application folder
|
||||
- Create file with proper path
|
||||
- Handle write permissions errors
|
||||
- Verify file was written successfully
|
||||
- [x] 9.3 Add metadata comment at top
|
||||
- Include generation date/time
|
||||
- Note sources used (profile.md, application.md)
|
||||
- Include word count
|
||||
- Note tone and language used
|
||||
|
||||
## 10. Implement Progress Reporting
|
||||
|
||||
- [x] 10.1 Show validation progress
|
||||
- Display: "🔍 Validating application..."
|
||||
- Show validation result
|
||||
- [x] 10.2 Show generation progress
|
||||
- Display: "📝 Generating cover letter..."
|
||||
- Show steps: "✓ Read profile.md", "✓ Read application.md", etc.
|
||||
- [x] 10.3 Show completion status
|
||||
- Display: "✓ Analyzed match strategy ([N] key experiences identified)"
|
||||
- Display: "✓ Incorporated key messages"
|
||||
- Display: "✓ Applied tone: [tone]"
|
||||
- Display: "✓ Language: [language]"
|
||||
- Display: "✓ Generated [N] words (target: 300-400)"
|
||||
|
||||
## 11. Implement Success Output
|
||||
|
||||
- [x] 11.1 Design success message format
|
||||
- ✅ emoji and title
|
||||
- Summary of generation (word count, tone, language, experiences used)
|
||||
- File location
|
||||
- Next steps
|
||||
- [x] 11.2 Generate detailed summary
|
||||
- Word count achieved
|
||||
- Tone applied
|
||||
- Language used
|
||||
- Number of experiences highlighted
|
||||
- Number of key messages incorporated
|
||||
- [x] 11.3 Provide next steps
|
||||
- Suggest reviewing cover-letter.md
|
||||
- Suggest personalizing with additional insights
|
||||
- Suggest next command (generate CV when available)
|
||||
|
||||
## 12. Implement Error Handling
|
||||
|
||||
- [x] 12.1 Handle missing profile.md
|
||||
- Show error: "profile.md not found"
|
||||
- Suggest running /validate-profile first
|
||||
- Stop generation
|
||||
- [x] 12.2 Handle missing application.md
|
||||
- Show error: "No application.md found"
|
||||
- Suggest creating application with /new-application
|
||||
- Stop generation
|
||||
- [x] 12.3 Handle validation failure
|
||||
- Show validation errors
|
||||
- Stop generation unless --skip-validation
|
||||
- Provide guidance on fixing issues
|
||||
- [x] 12.4 Handle existing cover-letter.md
|
||||
- Show error with file path
|
||||
- Suggest --force flag to overwrite
|
||||
- Stop generation unless --force provided
|
||||
- [x] 12.5 Handle file write errors
|
||||
- Show clear error message with reason
|
||||
- Suggest checking permissions or disk space
|
||||
- [x] 12.6 Handle corrupted data files
|
||||
- Catch parsing errors
|
||||
- Show helpful error message
|
||||
- Identify which file is corrupted
|
||||
|
||||
## 13. Implement Command Flags
|
||||
|
||||
- [x] 13.1 Parse --skip-validation flag
|
||||
- Check command arguments for flag
|
||||
- Set validation skip flag if present
|
||||
- [x] 13.2 Parse --force / --overwrite flag
|
||||
- Check command arguments for flag
|
||||
- Set overwrite flag if present
|
||||
- [x] 13.3 Parse --help flag
|
||||
- Check for --help flag
|
||||
- Show usage information, available flags, examples
|
||||
- Exit without generating
|
||||
- [x] 13.4 Handle combined flags
|
||||
- Support multiple flags in single command
|
||||
- Process each flag appropriately
|
||||
|
||||
## 14. Create Slash Command File
|
||||
|
||||
- [x] 14.1 Create `src/.claude/commands/write-cover-letter.md`
|
||||
- [x] 14.2 Document location detection logic
|
||||
- [x] 14.3 Document validation gate behavior
|
||||
- [x] 14.4 Document existing file check
|
||||
- [x] 14.5 Document data reading from profile.md and application.md
|
||||
- [x] 14.6 Document content generation strategy
|
||||
- Opening paragraph structure
|
||||
- Why this role paragraph
|
||||
- What you bring paragraphs
|
||||
- Cultural fit paragraph
|
||||
- Closing paragraph
|
||||
- [x] 14.7 Document tone and language handling
|
||||
- [x] 14.8 Document word count targets and quality checks
|
||||
- [x] 14.9 Document available flags (--skip-validation, --force, --help)
|
||||
- [x] 14.10 Include output format examples (success, errors)
|
||||
- [x] 14.11 Document edge cases and error handling
|
||||
|
||||
## 15. Update Framework Documentation
|
||||
|
||||
- [x] 15.1 Update `src/CLAUDE.md` - Add `/write-cover-letter` to Available Commands
|
||||
- [x] 15.2 Update workflow section
|
||||
- Change Step 6 from "Content Generation (FUTURE)" to actual cover letter generation
|
||||
- Add detailed workflow step for cover letter generation
|
||||
- [x] 15.3 Add usage examples
|
||||
- Generate from current directory
|
||||
- Generate with application parameter
|
||||
- Using flags (--skip-validation, --force)
|
||||
- [x] 15.4 Update "Document Standards" section
|
||||
- Add cover letter standards (structure, length, tone)
|
||||
- [x] 15.5 Add example interaction showing cover letter generation
|
||||
|
||||
## 16. Integration and Testing
|
||||
|
||||
- [x] 16.1 Test from inside application folder (no parameter)
|
||||
- [x] 16.2 Test with application name parameter
|
||||
- [x] 16.3 Test from wrong location (should list applications)
|
||||
- [x] 16.4 Test automatic validation (passing)
|
||||
- [x] 16.5 Test automatic validation (failing) - should stop
|
||||
- [x] 16.6 Test --skip-validation flag
|
||||
- [x] 16.7 Test existing cover-letter.md (should stop)
|
||||
- [x] 16.8 Test --force flag to overwrite
|
||||
- [x] 16.9 Test with complete application (should generate successfully)
|
||||
- [x] 16.10 Test tone variations (Formal, Balanced, Casual)
|
||||
- [x] 16.11 Test language detection (German vs English)
|
||||
- [x] 16.12 Test word count (should be 300-400 words)
|
||||
- [x] 16.13 Test personalization (company-specific references)
|
||||
- [x] 16.14 Test factual accuracy (only uses profile.md info)
|
||||
- [x] 16.15 Test missing profile.md
|
||||
- [x] 16.16 Test missing application.md
|
||||
- [x] 16.17 Validate proposal: `openspec validate add-cover-letter-generation --strict`
|
||||
|
||||
## 17. Update Test Environment
|
||||
|
||||
- [x] 17.1 Copy new `/write-cover-letter` command to test directory
|
||||
- [x] 17.2 Update `CLAUDE.md` in test directory
|
||||
- [x] 17.3 Preserve test directory's `profile.md` and `applications/` folder
|
||||
- [x] 17.4 Test in actual test environment with real application
|
||||
|
||||
## 18. Git Workflow
|
||||
|
||||
- [x] 18.1 Verify all changes are on feature branch `feature/cover-letter-generation`
|
||||
- [x] 18.2 Stage all files (OpenSpec proposal, slash command, documentation updates)
|
||||
- [x] 18.3 Create descriptive commit message following conventional commits format
|
||||
- [x] 18.4 Merge feature branch into main
|
||||
- [x] 18.5 Verify final state
|
||||
@@ -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)
|
||||
+144
@@ -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
|
||||
@@ -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,25 @@
|
||||
# Add Applicant Profile Template
|
||||
|
||||
## Why
|
||||
|
||||
The job application workflow requires applicant information (personal details, experience, skills, education) to generate CVs, cover letters, and emails. Currently, there's no structured way to store and access this information, forcing Claude Code to ask repeatedly or requiring manual input each time.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Create `src/` directory to hold the distributable framework files (separate from this development project)
|
||||
- Add `src/profile.md` template file for storing applicant's personal and professional information
|
||||
- Create `src/CLAUDE.md` with instructions for Claude Code to read `profile.md` when helping with job applications
|
||||
- Define a structured markdown format for the profile that covers all necessary sections (personal info, experience, education, skills, projects)
|
||||
|
||||
## Impact
|
||||
|
||||
- **Affected specs**: Creates new capability `applicant-profile`
|
||||
- **Affected code**:
|
||||
- New directory: `src/` (contains the distributable framework)
|
||||
- New file: `src/profile.md` (template for users to fill out)
|
||||
- New file: `src/CLAUDE.md` (framework instructions for Claude Code)
|
||||
- **User benefit**:
|
||||
- Clear separation between framework development and framework usage
|
||||
- Users can copy `src/` folder to any location to start using the framework
|
||||
- One-time profile setup, reusable for all applications
|
||||
- **No breaking changes**: This is the first foundational piece of the framework
|
||||
+68
@@ -0,0 +1,68 @@
|
||||
# Applicant Profile
|
||||
|
||||
## ADDED 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
|
||||
@@ -0,0 +1,24 @@
|
||||
# Implementation Tasks
|
||||
|
||||
## 1. Create Framework Directory
|
||||
|
||||
- [x] 1.1 Create `src/` directory to hold distributable framework files
|
||||
|
||||
## 2. Create Profile Template
|
||||
|
||||
- [x] 2.1 Create `src/profile.md` with all required sections
|
||||
- [x] 2.2 Add helpful comments and examples for each section
|
||||
- [x] 2.3 Include markdown formatting guidelines within the template
|
||||
|
||||
## 3. Create Framework Claude Instructions
|
||||
|
||||
- [x] 3.1 Create `src/CLAUDE.md` with profile reading instructions
|
||||
- [x] 3.2 Specify that profile should be read for any job application-related tasks
|
||||
- [x] 3.3 Add instruction to use profile as single source of truth for applicant data
|
||||
|
||||
## 4. Validation
|
||||
|
||||
- [x] 4.1 Verify `src/profile.md` template is complete and well-documented
|
||||
- [x] 4.2 Verify `src/CLAUDE.md` contains clear instructions for Claude Code
|
||||
- [x] 4.3 Ensure all required profile sections are present and clearly explained
|
||||
- [x] 4.4 Test that the framework can be copied to another directory and works independently
|
||||
@@ -0,0 +1,25 @@
|
||||
# Add Profile Validation Mechanism
|
||||
|
||||
## Why
|
||||
|
||||
Before generating job application documents, we need to ensure `profile.md` is completely filled out with real information. Currently, there's no automated check to verify that users have replaced all placeholder text with actual data. Attempting to generate applications with incomplete profiles would result in placeholder text appearing in CVs or cover letters, which is unprofessional and defeats the purpose of the framework.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Create a slash command `/validate-profile` that checks if `profile.md` is complete and ready to use
|
||||
- Implement validation logic to detect placeholder patterns (e.g., `[Your name]`, `[Company]`, etc.)
|
||||
- Update `src/CLAUDE.md` to require profile validation before any application generation
|
||||
- Provide clear feedback on what sections need completion
|
||||
|
||||
## Impact
|
||||
|
||||
- **Affected specs**: Modifies `applicant-profile` capability
|
||||
- **Affected code**:
|
||||
- New file: `src/.claude/commands/validate-profile.md` (slash command)
|
||||
- Modified: `src/CLAUDE.md` (add validation requirement)
|
||||
- **User benefit**:
|
||||
- Prevents generating applications with incomplete/placeholder data
|
||||
- Clear guidance on what profile sections still need work
|
||||
- Confidence that profile is application-ready
|
||||
- **Out of scope**: Implementation of actual application generation workflow (planned for future proposal)
|
||||
- **No breaking changes**: Adds validation layer without changing existing functionality
|
||||
+65
@@ -0,0 +1,65 @@
|
||||
# Applicant Profile
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### 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,28 @@
|
||||
# Implementation Tasks
|
||||
|
||||
## 1. Create Slash Command Structure
|
||||
|
||||
- [x] 1.1 Create `src/.claude/` directory
|
||||
- [x] 1.2 Create `src/.claude/commands/` directory
|
||||
|
||||
## 2. Implement Validation Slash Command
|
||||
|
||||
- [x] 2.1 Create `src/.claude/commands/validate-profile.md` with validation instructions
|
||||
- [x] 2.2 Define validation rules for detecting placeholder patterns
|
||||
- [x] 2.3 Specify required sections that must be complete (Personal Info, Summary, at least one Work Experience)
|
||||
- [x] 2.4 Specify optional sections that can be empty
|
||||
- [x] 2.5 Include clear output format for validation results (success or list of incomplete sections)
|
||||
|
||||
## 3. Update Framework Instructions
|
||||
|
||||
- [x] 3.1 Update `src/CLAUDE.md` to add automatic validation requirement before application generation
|
||||
- [x] 3.2 Add instructions for when to run `/validate-profile`
|
||||
- [x] 3.3 Add guidance on handling validation failures
|
||||
- [x] 3.4 Document the explicit skip validation option
|
||||
|
||||
## 4. Validation
|
||||
|
||||
- [x] 4.1 Verify `/validate-profile` command file is complete and well-documented
|
||||
- [x] 4.2 Verify `src/CLAUDE.md` correctly requires validation before applications
|
||||
- [x] 4.3 Test validation logic detects common placeholder patterns
|
||||
- [x] 4.4 Ensure validation provides helpful feedback on incomplete sections
|
||||
Reference in New Issue
Block a user