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