Bewerbungszauberer/openspec/specs/application-management/spec.md

# application-management Specification

## Purpose
TBD - created by archiving change add-application-email. Update Purpose after archive.
## Requirements
### Requirement: Attachments Folder Creation

The system SHALL create an `attachments/` subfolder with a `.keep` file when initializing new applications to support document organization for email generation.

#### Scenario: Application folder creation includes attachments directory

- **WHEN** user runs `/new-application "Company - Job Title"`
- **THEN** the system creates folder structure: `applications/pending/[folder-name]/attachments/`
- **AND** creates an empty `.keep` file inside `attachments/` folder
- **AND** the attachments folder is ready for user to add documents

#### Scenario: Version control compatibility

- **WHEN** attachments folder is created with `.keep` file
- **THEN** the empty folder can be tracked in version control systems
- **AND** the folder structure is preserved even when empty

#### Scenario: Success message includes attachments folder

- **WHEN** new application is created successfully
- **THEN** the success message mentions the attachments folder
- **AND** provides guidance on what documents to place there
- **AND** indicates this folder is for CV, cover letter, certificates

### Requirement: Application Folder Structure

The system SHALL create a complete folder structure for each new application including metadata, input documents, and attachments.

#### Scenario: Complete folder structure created

- **WHEN** `/new-application` command is executed
- **THEN** the following structure is created:
  ```
  applications/pending/[YYYY-MM-DD-Company-JobTitle]/
  ├── application.md
  ├── input/
  └── attachments/
      └── .keep
  ```
- **AND** application.md contains the template with metadata
- **AND** input/ folder is empty and ready for job posting documents
- **AND** attachments/ folder contains .keep file for version control

### Requirement: User Guidance for Attachments

The system SHALL provide clear guidance on the purpose and usage of the attachments folder.

#### Scenario: Attachments folder purpose explained

- **WHEN** new application is created
- **THEN** the success message explains attachments folder is for "final documents ready to send"
- **AND** distinguishes it from input/ folder (which is for "source materials and research")
- **AND** lists expected document types (CV, cover letter, certificates, diplomas)

#### Scenario: Workflow guidance includes attachments

- **WHEN** user views success message after creating application
- **THEN** the workflow guidance mentions adding documents to attachments/ after generation
- **AND** indicates attachments/ folder is checked by `/write-application-email` command

### Requirement: Application Initialization Command

The system SHALL provide a `/new-application` slash command that creates a new application workspace with proper folder structure.

#### Scenario: Create new application with minimal info

- **WHEN** user runs `/new-application "TechCorp - Senior Developer"`
- **THEN** system creates folder `src/applications/pending/2025-11-02-TechCorp-Senior-Developer/` with `application.md` template and empty `input/` folder

#### Scenario: Create application with date prefix

- **WHEN** application folder is created
- **THEN** folder name is prefixed with current date in `YYYY-MM-DD` format for chronological sorting

#### Scenario: Handle special characters in folder names

- **WHEN** organization name or job title contains special characters (/, \, :, etc.)
- **THEN** system sanitizes the folder name by replacing invalid characters with hyphens or removing them

#### Scenario: Application template is created

- **WHEN** new application is initialized
- **THEN** `application.md` file is created with template sections (Organization, Job Title, Research, Match Strategy, Key Messages, Tone, etc.)

#### Scenario: Input folder is created automatically

- **WHEN** new application is initialized
- **THEN** `input/` subfolder is created for storing job-related documents

### Requirement: Application Structure

Each application workspace SHALL contain a standardized folder structure and files.

#### Scenario: Folder hierarchy is consistent

- **WHEN** application is created
- **THEN** structure is: `src/applications/pending/[date-org-title]/application.md` and `src/applications/pending/[date-org-title]/input/`

#### Scenario: Application template has required sections

- **WHEN** `application.md` is created
- **THEN** it includes sections for: Organization Name, Job Title, Job Description Summary, Research Notes, Match Strategy, Key Messages, Tone of Voice, and Document Checklist

#### Scenario: Template provides guidance

- **WHEN** user opens newly created `application.md`
- **THEN** each section includes helpful comments explaining what information to include

### Requirement: Document Population Command

The system SHALL provide a `/populate-application` slash command that analyzes input documents and populates `application.md`.

#### Scenario: Populate from current directory

- **WHEN** user runs `/populate-application` from within an application folder
- **THEN** system reads all files in `input/` subfolder and extracts relevant information

#### Scenario: Analyze job advertisement

- **WHEN** `input/` contains a job advertisement (PDF, DOCX, TXT, MD)
- **THEN** system extracts: company name, job title, requirements, responsibilities, keywords, and company culture indicators

#### Scenario: Analyze email communications

- **WHEN** `input/` contains email files or text
- **THEN** system extracts: recruiter name, company context, timeline, special instructions, and tone expectations

#### Scenario: Update application.md with findings

- **WHEN** input analysis is complete
- **THEN** system updates relevant sections of `application.md` with extracted information while preserving any existing manual entries

#### Scenario: Ask user for missing information

- **WHEN** critical information cannot be extracted from input files (e.g., no clear job title)
- **THEN** system prompts user to provide missing details before completing population

#### Scenario: Handle empty input folder

- **WHEN** `/populate-application` is run and `input/` folder is empty or doesn't exist
- **THEN** system informs user to add job-related documents first and explains what types of files are helpful

### Requirement: Profile Integration

The application management system SHALL integrate with the existing profile system.

#### Scenario: Reference profile during population

- **WHEN** `/populate-application` runs
- **THEN** system reads `src/profile.md` to understand applicant's background for match strategy analysis

#### Scenario: Profile validation is preserved

- **WHEN** working with applications
- **THEN** the existing `/validate-profile` requirement remains enforced before document generation (to be implemented in future proposal)

#### Scenario: Match applicant to job requirements

- **WHEN** populating application
- **THEN** system identifies which experiences, skills, and projects from profile.md best match the job requirements

### Requirement: Claude Code Workflow Instructions

The `src/CLAUDE.md` file SHALL include instructions for the application management workflow.

#### Scenario: Instructions explain application lifecycle

- **WHEN** Claude Code is helping with applications
- **THEN** it understands the workflow: initialize → add input files → populate → [future: generate documents]

#### Scenario: Commands are documented

- **WHEN** user asks how to create an application
- **THEN** Claude Code can explain `/new-application` and `/populate-application` commands

#### Scenario: Input file guidance is provided

- **WHEN** user asks what files to add to input folder
- **THEN** Claude Code suggests: job postings (PDF/DOCX/text), recruiter emails, company research notes, or any relevant context

### Requirement: File Format Support

The population command SHALL support multiple input file formats.

#### Scenario: Read PDF files

- **WHEN** `input/` contains PDF files
- **THEN** system extracts text content for analysis (Note: Claude Code has built-in PDF reading capability)

#### Scenario: Read text-based formats

- **WHEN** `input/` contains TXT, MD, or copied text files
- **THEN** system reads and analyzes content directly

#### Scenario: Read email formats

- **WHEN** `input/` contains .eml or plain text email content
- **THEN** system parses sender, subject, body and extracts relevant application context

#### Scenario: Handle unsupported formats gracefully

- **WHEN** `input/` contains unsupported file types (e.g., images, videos)
- **THEN** system skips these files with a warning and processes supported formats