Bewerbungszauberer/openspec/specs/applicant-profile/spec.md

applicant-profile Specification

Purpose

TBD - created by archiving change add-profile-template. Update Purpose after archive.

Requirements

Requirement: Profile Storage

The system SHALL provide a markdown file (src/profile.md) in the distributable framework directory for storing applicant information.

Scenario: Profile file exists with template structure

• WHEN the framework is set up in src/ directory
• THEN src/profile.md contains template sections for Personal Information, Professional Summary, Work Experience, Education, Skills, Projects, Certifications, and Languages

Scenario: Profile sections are clearly documented

• WHEN user opens src/profile.md
• THEN each section includes helpful comments explaining what information to include and formatting guidance

Requirement: Profile Schema

The profile markdown SHALL include the following sections with structured information:

1. Personal Information (name, email, phone, location, LinkedIn, GitHub)
2. Professional Summary (2-3 sentence overview)
3. Work Experience (company, position, dates, responsibilities, achievements)
4. Education (institution, degree, field, dates, honors)
5. Skills (categorized: technical, languages, tools, soft skills)
6. Projects (name, description, technologies, link)
7. Certifications (name, issuer, date)
8. Languages (language, proficiency level)

Scenario: Work experience includes all necessary fields

• WHEN user adds a work experience entry
• THEN template provides fields for company, position, employment period, key responsibilities, and quantifiable achievements

Scenario: Skills are organized by category

• WHEN user lists their skills
• THEN template groups skills into categories (Technical Skills, Programming Languages, Tools & Technologies, Soft Skills)

Requirement: Claude Code Integration

The src/CLAUDE.md file SHALL instruct Claude Code to automatically read profile.md when the user requests help with job applications.

Scenario: Claude Code loads profile for application tasks

• WHEN user asks Claude Code to help with a job application (CV, cover letter, or email) in a directory containing the framework
• THEN Claude Code reads profile.md to access applicant information without asking the user to provide it again

Scenario: Profile is used as source of truth

• WHEN generating application documents
• THEN Claude Code uses only information from profile.md, ensuring consistency across all applications and preventing hallucinations

Requirement: Framework Distribution

The framework SHALL be contained in a src/ directory separate from the development project files.

Scenario: Users can copy framework to use elsewhere

• WHEN user wants to use the job application framework
• THEN they can copy the entire src/ directory to any location and start using it immediately

Scenario: Development and usage are separated

• WHEN working on the framework itself
• THEN changes are made in this repository, and src/ contains only the distributable framework files

Requirement: Profile Validation Command

The system SHALL provide a /validate-profile slash command that verifies the profile is complete and ready for use.

Scenario: Validation command is available

• WHEN user is in a directory containing the framework
• THEN they can run /validate-profile to check if profile.md is complete

Scenario: Validation detects incomplete profile

• WHEN /validate-profile is run and profile.md contains placeholder text patterns (e.g., [Your name], [Company])
• THEN the command reports which sections contain placeholders and need completion

Scenario: Validation confirms complete profile

• WHEN /validate-profile is run and profile.md has no placeholder patterns in required fields
• THEN the command reports that the profile is ready for application generation

Requirement: Placeholder Detection

The validation SHALL detect common placeholder patterns indicating incomplete profile data.

Scenario: Square bracket placeholders detected

• WHEN profile contains text in the format [placeholder text]
• THEN validation identifies these as incomplete fields

Scenario: Required sections checked

• WHEN validation runs
• THEN it checks that Personal Information, Professional Summary, and at least one Work Experience entry are filled out (not placeholders)

Scenario: Optional sections allowed to be empty

• WHEN validation runs
• THEN empty optional sections (Certifications, Projects) do not cause validation failure

Requirement: Automatic Validation Before Applications

The src/CLAUDE.md instructions SHALL require Claude Code to validate the profile before generating any application documents.

Scenario: Profile validated before CV generation

• WHEN user requests CV generation
• THEN Claude Code first validates profile.md is complete before proceeding

Scenario: Profile validated before cover letter generation

• WHEN user requests cover letter or application email generation
• THEN Claude Code first validates profile.md is complete before proceeding

Scenario: Validation failure blocks application generation

• WHEN profile validation fails (incomplete data detected)
• THEN Claude Code informs the user to complete the profile and does not generate application documents

Scenario: User can skip validation explicitly

• WHEN user explicitly requests to skip validation (e.g., "generate CV without validation" or "I know my profile is incomplete, proceed anyway")
• THEN Claude Code can proceed with a warning about potential placeholder text in output