feat: implement application management system

Add structured workflow for managing job applications with /new-application and /populate-application commands. Users can now organize applications in dated folders, store job documents, and have AI analyze requirements to populate strategy documents. Includes bug fix for src/ path references and safe update documentation. OpenSpec: add-application-management 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-02 19:04:49 +01:00
parent 751af9e310
commit f1ba0dd98d
9 changed files with 1263 additions and 18 deletions
@@ -15,4 +15,92 @@ Use `@/openspec/AGENTS.md` to learn:
 Keep this managed block so 'openspec update' can refresh the instructions.
-<!-- OPENSPEC:END -->
+<!-- OPENSPEC:END -->
 ---
 # Updating the Test Framework
 ## ⚠️ CRITICAL: Preserve User Data During Updates
 When updating the test framework at `~/workspace/test-bewerbungen/`, you MUST preserve user data files. **NEVER** use `cp -r src/* ~/workspace/test-bewerbungen/` as this overwrites everything including user work.
 ## Protected Files & Folders
 **NEVER overwrite these in the test directory:**
 - `profile.md` - Contains user's personal and professional information
 - `applications/` folder - Contains all job application work in progress
 - Any PDF files - User's CVs, certificates, or job-related documents
 - Any user-created files or modifications
 ## Safe Update Process
 ### Method 1: Selective File Update (Recommended)
 Update only framework code files, preserving user data:
 ```bash
 # Update main instruction file
 cp src/CLAUDE.md ~/workspace/test-bewerbungen/
 # Update slash commands and templates
 cp -r src/.claude ~/workspace/test-bewerbungen/
 # ONLY create applications directory if it doesn't exist
 # (don't overwrite existing one with user's applications)
 if [ ! -d ~/workspace/test-bewerbungen/applications ]; then
  mkdir -p ~/workspace/test-bewerbungen/applications/pending
 fi
 ```
 ### Method 2: Manual Selective Copy
 For more control, copy specific files individually:
 ```bash
 # Framework instructions
 cp src/CLAUDE.md ~/workspace/test-bewerbungen/
 # Slash commands
 cp src/.claude/commands/new-application.md ~/workspace/test-bewerbungen/.claude/commands/
 cp src/.claude/commands/populate-application.md ~/workspace/test-bewerbungen/.claude/commands/
 cp src/.claude/commands/validate-profile.md ~/workspace/test-bewerbungen/.claude/commands/
 # Templates
 cp src/.claude/templates/application-template.md ~/workspace/test-bewerbungen/.claude/templates/
 ```
 ### ❌ NEVER Use These Commands on Test Directory
 ```bash
 # DANGEROUS - Overwrites everything including user data
 cp -r src/* ~/workspace/test-bewerbungen/
 # DANGEROUS - Overwrites user's profile
 cp src/profile.md ~/workspace/test-bewerbungen/
 # DANGEROUS - Deletes user's applications
 rm -rf ~/workspace/test-bewerbungen/applications/
 ```
 ## When to Update Test Framework
 Update the test directory when:
 - Adding new slash commands to `src/.claude/commands/`
 - Modifying the application template in `src/.claude/templates/`
 - Updating framework instructions in `src/CLAUDE.md`
 - Fixing bugs in command logic
 **Do NOT update** `profile.md` or touch the `applications/` folder - these belong to the user.
 ## Workflow Summary
 1. **Make changes** to framework files in `src/`
 2. **Test locally** in development environment first
 3. **Selectively copy** only framework files to test directory
 4. **Verify** user data (`profile.md`, `applications/`) remains intact
 5. **Test** the updated commands in the test environment
 ---
 **Remember**: The test directory simulates a real user's environment. Treat user data with care!
@@ -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
@@ -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,157 @@
 Initialize a new job application with organized folder structure.
 # Instructions
 You are creating a new job application workspace for the user.
 ## Input Processing
 ### 1. Parse User Input
 The user will provide information about the application in the command. Extract:
 - **Organization Name**: The company/organization they're applying to
 - **Job Title**: The position they're applying for
 Example inputs:
 - `/new-application "TechCorp - Senior Developer"`
 - `/new-application "Startup Inc - Product Manager"`
 - `/new-application "Google - Software Engineer"`
 If the user provides insufficient information, prompt them:
 ```
 Please provide the organization name and job title.
 Format: /new-application "Organization Name - Job Title"
 Example: /new-application "TechCorp - Senior Developer"
 ```
 ### 2. Generate Folder Name
 Create a folder name in the format: `YYYY-MM-DD-OrganizationName-JobTitle`
 **Date Format**:
 - Use today's date from the system
 - Format: YYYY-MM-DD (e.g., 2025-11-02)
 **Name Sanitization**:
 - Remove or replace invalid filesystem characters: `/ \ : * ? " < > |`
 - Replace spaces with hyphens
 - Remove multiple consecutive hyphens
 - Trim leading/trailing hyphens
 - Limit total length to 100 characters for filesystem compatibility
 - If too long, truncate job title portion first, then organization name if needed
 **Examples**:
 - Input: "Tech Corp Inc. - Senior Software Engineer"
 - Output: `2025-11-02-Tech-Corp-Inc-Senior-Software-Engineer`
 - Input: "Company/Organization - Manager: Sales & Marketing"
 - Output: `2025-11-02-Company-Organization-Manager-Sales-Marketing`
 ### 3. Handle Duplicate Folders
 If a folder with the generated name already exists:
 - Append a counter: `-2`, `-3`, etc.
 - Example: `2025-11-02-TechCorp-Developer-2`
 - Inform the user: "A folder for this application already exists. Created with suffix -2."
 ## Folder Creation
 ### 4. Create Directory Structure
 Create the following structure in `applications/pending/`:
 ```
 applications/pending/[generated-folder-name]/
 ├── application.md
 └── input/
 ```
 Use these steps:
 1. Create the application folder: `applications/pending/[generated-folder-name]/`
 2. Create the `input/` subfolder inside it
 3. Create `application.md` from the template
 ### 5. Create application.md
 Copy the template from `.claude/templates/application-template.md` to the new folder as `application.md`.
 **Update Metadata Section**:
 - Replace `[Auto-filled on creation]` in the Created field with current timestamp
 - Format: `YYYY-MM-DD HH:MM` (e.g., "2025-11-02 14:30")
 **Optional - Pre-fill Known Information**:
 If the user provided clear organization name and job title:
 - Fill in "Organization Name" field
 - Fill in "Job Title" field
 - Leave all other fields as placeholders for `/populate-application` to fill
 ## User Confirmation
 ### 6. Success Message
 After successfully creating the application, provide this output:
 ```
 ✅ New application created successfully!
 **Location**: applications/pending/[folder-name]/
 **Organization**: [Organization Name]
 **Position**: [Job Title]
 ## Next Steps:
 1. **Add documents to the input folder**:
   ```
   applications/pending/[folder-name]/input/
   ```
   Add any of these documents:
   - Job posting/advertisement (PDF, TXT, MD, DOCX)
   - Recruiter emails or communications
   - Company research notes
   - Any other relevant context
 2. **Populate the application**:
   Once you've added your documents, run:
   ```
   /populate-application
   ```
   This will analyze all input files and populate application.md with:
   - Job requirements and keywords
   - Company research and culture insights
   - Match strategy (your relevant skills/experience)
   - Suggested tone and key messages
 3. **Review and refine**:
   After population, review `application.md` and add your own insights.
 4. **Generate documents** (coming soon):
   Use the populated application to generate tailored CV, cover letter, and email.
 ---
 **Tip**: You can manually edit `application.md` at any time to add notes, ideas, or strategy thoughts.
 ```
 ## Error Handling
 ### 7. Handle Edge Cases
 **If applications/pending/ doesn't exist**:
 - Create it automatically with parent directories
 - Inform user: "Created applications directory structure."
 **If template file is missing** (`.claude/templates/application-template.md`):
 - Create a basic application.md with minimal structure
 - Warn user: "Template file not found. Created basic application.md structure."
 **If filesystem errors occur**:
 - Provide clear error message
 - Suggest checking permissions or path length
 ## Important Notes
 - Always use forward slashes (/) for paths, even on Windows (handled by tools)
 - Preserve the YYYY-MM-DD prefix for chronological sorting
 - Keep folder names readable - avoid cryptic abbreviations
 - The input/ folder should be empty initially - it's for the user to fill
@@ -0,0 +1,388 @@
 Analyze input documents and populate the application.md file with job information, research, and strategy.
 # Instructions
 You are populating a job application by analyzing documents and cross-referencing with the applicant's profile.
 ## Pre-flight Checks
 ### 1. Verify Location
 **Check Current Directory**:
 - Verify you're inside an application folder (should be in `applications/pending/[application-name]/`)
 - Check if `application.md` exists in current directory
 - Check if `input/` subfolder exists
 **If NOT in correct location**:
 ```
 ❌ Not in an application folder
 Please navigate to an application folder first:
 cd applications/pending/[your-application-folder]/
 Then run /populate-application again.
 To see available applications:
 ls applications/pending/
 ```
 **If application.md doesn't exist**:
 ```
 ❌ No application.md found
 This doesn't appear to be a valid application folder.
 Did you create this application with /new-application?
 ```
 ### 2. Check Input Folder
 **If input/ folder doesn't exist**:
 - Create it automatically
 - Inform user: "Created input/ folder. Please add documents before populating."
 **If input/ folder is empty**:
 ```
 ⚠️  Input folder is empty
 Please add documents to analyze:
 - Job posting/advertisement (PDF, TXT, MD, DOCX)
 - Recruiter emails or communications
 - Company research notes
 - Any other relevant context
 Add files to: ./input/
 Then run /populate-application again.
 ```
 ## Document Discovery & Analysis
 ### 3. List Input Files
 Scan the `input/` folder and categorize files:
 **Supported Formats**:
 - PDF files (`.pdf`) - Read using Read tool (has built-in PDF support)
 - Text files (`.txt`, `.md`, `.markdown`)
 - Document files (`.docx`) - Try to read as best as possible
 - Email files (`.eml`, `.msg`) - Extract as text
 - HTML files (`.html`, `.htm`)
 **Unsupported Formats** (warn but skip):
 - Images (`.jpg`, `.png`, `.gif`) - "Cannot extract text from images"
 - Videos, audio, archives, executables
 **Output file list**:
 ```
 📄 Found [N] documents in input/ folder:
 Supported:
 ✓ job-posting.pdf
 ✓ recruiter-email.txt
 ✓ company-research.md
 Skipped (unsupported format):
 ⊘ company-logo.png
 ```
 ### 4. Read All Supported Files
 For each supported file:
 1. Use the Read tool to extract content
 2. Note the filename for reference
 3. If a file fails to read, skip it with a warning
 ### 5. Analyze Job Information
 **Extract from job postings/descriptions**:
 **Organization Information**:
 - Company name
 - Industry/sector
 - Location (city, country, remote options)
 - Company size (if mentioned)
 - Website or apply URL
 **Job Details**:
 - Job title
 - Job level (Junior, Mid, Senior, Lead, Manager, etc.)
 - Department or team
 - Employment type (Full-time, Part-time, Contract, Freelance)
 - Salary range (if mentioned)
 - Remote/hybrid/on-site requirements
 **Job Description**:
 - Key responsibilities (extract 5-10 main duties)
 - Required skills and qualifications
 - Preferred/nice-to-have skills
 - Required experience (years, specific domains)
 - Education requirements
 - Certifications or licenses
 **Keywords**:
 - Extract important keywords for ATS optimization
 - Programming languages, frameworks, tools mentioned
 - Industry-specific terms
 - Soft skills mentioned
 **Company Culture Indicators**:
 - Language tone (formal, casual, enthusiastic)
 - Values mentioned (innovation, collaboration, diversity, etc.)
 - Benefits and perks mentioned
 - Work environment description
 ### 6. Analyze Additional Documents
 **From recruiter emails**:
 - Recruiter/contact person name and email
 - Timeline and deadlines
 - Special instructions or requirements
 - Salary expectations or discussions
 - Interview process details
 **From research notes**:
 - Company news, funding, acquisitions
 - Product launches or initiatives
 - Company culture insights
 - Employee reviews or Glassdoor data
 - Competitive landscape
 ## Profile Cross-Reference
 ### 7. Read Applicant Profile
 Read `profile.md` (in the framework root directory) to understand the applicant's background.
 **If profile.md doesn't exist or is incomplete**:
 ```
 ⚠️  Profile not found or incomplete
 Your profile.md should be filled out for best results.
 Run /validate-profile to check your profile status.
 Continuing with job analysis only (without personalized matching).
 ```
 ### 8. Match Analysis
 **IF profile is available**, analyze matches:
 **Experience Matching**:
 - Which work experiences from profile align with job requirements?
 - Which responsibilities overlap?
 - Which achievements are most relevant?
 **Skills Matching**:
 - Which technical skills match required skills?
 - Which soft skills align with the role?
 - Which tools/technologies match?
 **Projects Matching**:
 - Which projects demonstrate relevant capabilities?
 - Which projects solve similar problems?
 **Gap Analysis**:
 - What required skills are missing from profile?
 - Can any gaps be filled with transferable skills?
 - What learning or growth opportunities does this role present?
 **Recommendations**:
 - Which experiences to emphasize in CV?
 - Which projects to highlight?
 - Which achievements to feature prominently?
 - Stories or examples from profile that demonstrate required skills?
 ## Population Strategy
 ### 9. Check Existing Content
 Before populating, read current `application.md`:
 - Check which sections already have content
 - Identify manually added notes or insights
 - Determine which sections need population
 ### 10. Populate application.md
 **Update each section intelligently**:
 **Metadata**:
 - Update status if appropriate
 - Add deadline if found in documents
 **Organization Information**:
 - Fill in company name, industry, location, website, contact person
 - Only overwrite `[To be filled]` placeholders, preserve manually entered data
 **Job Information**:
 - Fill in job title, level, department, employment type, remote status
 - Only overwrite placeholders
 **Job Description Summary**:
 - Add key responsibilities (bulleted list)
 - Add required skills (bulleted list)
 - Add preferred skills (bulleted list)
 - Add extracted keywords
 **Research Notes**:
 - Add company culture observations
 - Add recent news/developments
 - If user has manual notes, ADD to them (don't replace)
 **Match Strategy** (only if profile is available):
 - List relevant experiences to emphasize
 - Map required skills to applicant's skills
 - List projects to highlight
 - Identify gaps and suggest how to address them
 **Key Messages**:
 - Suggest 3-5 main points to convey in application
 - Base these on match analysis
 **Tone of Voice**:
 - Assess appropriate tone (Formal/Balanced/Casual)
 - Provide reasoning based on job posting language
 - Suggest example phrases
 **Document Checklist**:
 - Check appropriate boxes based on application requirements
 ### 11. Preserve Manual Content
 **IMPORTANT**:
 - Do NOT overwrite manually entered content
 - If a section has user-written notes, ADD analysis below them with a separator
 - Add a timestamp comment: `<!-- Auto-populated on YYYY-MM-DD HH:MM -->`
 - Mark auto-populated sections clearly
 **Example**:
 ```markdown
 ## Research Notes
 <!-- User's manual notes -->
 I really like their commitment to open source.
 ---
 <!-- Auto-populated on 2025-11-02 14:30 -->
 ### Company Culture & Values
 Based on job posting analysis:
 - Emphasizes collaboration and innovation
 - Values work-life balance (mentions flexible hours)
 - Strong focus on diversity and inclusion
 ```
 ### 12. Interactive Prompts
 **Ask for missing critical information**:
 If critical fields cannot be determined:
 ```
 Some information couldn't be extracted from the documents.
 Please provide the following:
 1. Job Title: [Current extracted value or "Unknown"]
 2. Organization Name: [Current extracted value or "Unknown"]
 Would you like to provide this now? (Or leave as-is to fill manually later)
 ```
 **Confirm before major changes**:
 If application.md already has significant content:
 ```
 ⚠️  This application already has populated content.
 Would you like to:
 1. **Merge** - Add new analysis alongside existing content (recommended)
 2. **Replace** - Overwrite with new analysis (will preserve metadata)
 3. **Cancel** - Don't make changes
 Choice: [Ask user to respond]
 ```
 ## Completion
 ### 13. Summary Report
 After successful population:
 ```
 ✅ Application populated successfully!
 ## Analyzed Documents:
 - job-posting.pdf
 - recruiter-email.txt
 - company-research.md
 ## Extracted Information:
 ✓ Organization: [Company Name]
 ✓ Position: [Job Title]
 ✓ Key Requirements: [N] identified
 ✓ Keywords: [N] extracted
 ✓ Company Culture: [Tone assessment]
 ## Profile Matching:
 ✓ Relevant Experience: [N] positions identified
 ✓ Skills Match: [N/M] required skills matched
 ✓ Projects to Highlight: [N] projects suggested
 ✓ Potential Gaps: [N] areas for development
 ## Updated Sections:
 ✓ Organization Information
 ✓ Job Information
 ✓ Job Description Summary
 ✓ Research Notes
 ✓ Match Strategy
 ✓ Key Messages
 ✓ Tone of Voice
 ## Next Steps:
 1. **Review application.md**:
   Open and review the populated information for accuracy.
 2. **Add your insights**:
   Enhance sections with your own thoughts and strategy.
 3. **Refine match strategy**:
   Adjust which experiences and projects to emphasize.
 4. **Generate documents** (coming soon):
   Once satisfied, generate tailored CV and cover letter.
 ---
 **Tip**: You can re-run /populate-application after adding more documents to input/.
 The analysis will be merged with existing content.
 ```
 ## Error Handling
 **If files cannot be read**:
 - Skip the file
 - Warn: "Could not read [filename]. Continuing with other files."
 **If no useful information extracted**:
 ```
 ⚠️  Limited information extracted
 The documents in input/ didn't contain clear job information.
 Please check:
 - Do you have the job posting/description?
 - Are the files readable (not corrupted)?
 - Is the text extractable (not image-only PDFs)?
 You can manually fill in application.md or add more documents.
 ```
 **If profile analysis fails**:
 - Continue with job analysis only
 - Warn: "Could not analyze profile matching. Consider running /validate-profile."
 ## Important Notes
 - Be thorough but not overwhelming - prioritize the most relevant information
 - Preserve user's manual work - they may have important insights
 - Be honest about gaps and limitations
 - Provide actionable next steps
 - Always leave the user in control - they can manually edit anything
@@ -0,0 +1,197 @@
 # Job Application
 <!--
 This file contains all information for this specific job application.
 It will be populated by analyzing documents in the input/ folder.
 You can manually edit any section to add your own notes and insights.
 -->
 ## Metadata
 - **Created**: [Auto-filled on creation]
 - **Status**: Draft
 - **Application Deadline**: [To be filled]
 - **Follow-up Date**: [To be filled]
 ---
 ## Organization Information
 <!--
 Basic information about the company/organization you're applying to.
 This will be extracted from job postings and research documents.
 -->
 - **Organization Name**: [To be filled]
 - **Industry**: [To be filled]
 - **Website**: [To be filled]
 - **Location**: [To be filled]
 - **Contact Person**: [To be filled]
 - **Contact Email**: [To be filled]
 ---
 ## Job Information
 <!--
 Details about the specific position you're applying for.
 -->
 - **Job Title**: [To be filled]
 - **Job Level**: [To be filled - e.g., Junior, Mid-level, Senior, Lead]
 - **Department/Team**: [To be filled]
 - **Employment Type**: [To be filled - e.g., Full-time, Part-time, Contract]
 - **Remote/On-site**: [To be filled]
 ---
 ## Job Description Summary
 <!--
 Key points extracted from the job posting.
 This section will be auto-populated from the job description in input/ folder.
 -->
 ### Key Responsibilities
 - [Responsibility 1]
 - [Responsibility 2]
 - [Responsibility 3]
 ### Required Skills & Qualifications
 - [Requirement 1]
 - [Requirement 2]
 - [Requirement 3]
 ### Preferred/Nice-to-Have
 - [Preferred skill 1]
 - [Preferred skill 2]
 ### Keywords from Job Posting
 [Keywords will be extracted automatically for ATS optimization]
 ---
 ## Research Notes
 <!--
 Information about the company culture, values, recent news, and insights.
 Add your own research or let the AI populate from documents in input/.
 -->
 ### Company Culture & Values
 [Notes about company culture, mission, values]
 ### Recent News & Developments
 [Recent news, funding rounds, product launches, etc.]
 ### Why This Company?
 [Your authentic reasons for being interested in this company]
 ---
 ## Match Strategy
 <!--
 Analysis of how your background aligns with the job requirements.
 This section helps you decide what to emphasize in your application.
 -->
 ### Relevant Experience to Emphasize
 <!--
 Based on your profile.md, which work experiences best match this role?
 -->
 - [Experience 1 from profile.md]
 - [Experience 2 from profile.md]
 ### Skills Match
 <!--
 Which of your skills directly address the job requirements?
 -->
 - **Required Skill 1**: [Your matching skill/experience]
 - **Required Skill 2**: [Your matching skill/experience]
 ### Projects to Highlight
 <!--
 Which projects from your profile should be featured?
 -->
 - [Project 1]: [Why it's relevant]
 - [Project 2]: [Why it's relevant]
 ### Potential Gaps & How to Address
 <!--
 Skills or experience you don't have yet, and how to position this positively.
 -->
 - [Gap 1]: [How to address - e.g., transferable skills, willingness to learn]
 ---
 ## Key Messages
 <!--
 The main points you want to convey in your application.
 These should be woven into your CV, cover letter, and email.
 -->
 1. [Key message 1 - e.g., "I bring 5 years of experience in exactly the tech stack you're using"]
 2. [Key message 2 - e.g., "My background in X directly addresses your need for Y"]
 3. [Key message 3 - e.g., "I'm passionate about your mission to Z"]
 ---
 ## Tone of Voice
 <!--
 How should your application sound? This depends on the company culture.
 -->
 - **Assessed Tone**: [Formal / Balanced / Casual]
 - **Reasoning**: [Why this tone - based on job posting language, company culture]
 - **Examples**: [Specific phrases or language style to use]
 ---
 ## Document Checklist
 <!--
 What documents are needed for this application?
 -->
 - [ ] Tailored CV/Resume
 - [ ] Cover Letter
 - [ ] Application Email
 - [ ] Portfolio/Work Samples
 - [ ] Other: [Specify]
 ---
 ## Application Strategy Notes
 <!--
 Any other strategic notes, ideas, or reminders for this application.
 -->
 [Your notes here]
 ---
 ## Timeline
 <!--
 Track your progress and deadlines.
 -->
 - **Application Submitted**: [Date]
 - **Follow-up Planned**: [Date]
 - **Interview Scheduled**: [Date]
 - **Decision Expected**: [Date]
 ---
 <!--
 WORKFLOW:
 1. Create this application: /new-application "CompanyName - Job Title"
 2. Add documents to input/ folder (job posting, company research, emails)
 3. Populate this file: /populate-application
 4. Review and refine the populated information
 5. Generate documents: [Future feature]
 -->
@@ -57,6 +57,87 @@ Please review carefully and manually replace any placeholders before sending to
 **Default behavior**: ALWAYS validate unless explicitly told to skip.
 ## Application Management
 The framework provides a structured system for managing individual job applications. Each application gets its own workspace with organized folders for documents and strategy.
 ### Creating a New Application
 Use `/new-application` to initialize a new job application:
 ```
 /new-application "Company Name - Job Title"
 ```
 This will:
 1. Create a dated folder: `applications/pending/YYYY-MM-DD-CompanyName-JobTitle/`
 2. Generate an `application.md` template with sections for research, strategy, and planning
 3. Create an `input/` folder for storing job-related documents
 **Example**:
 ```
 /new-application "TechCorp - Senior Developer"
 ```
 Creates: `applications/pending/2025-11-02-TechCorp-Senior-Developer/`
 ### Adding Input Documents
 After creating an application, add all relevant documents to the `input/` folder:
 **Recommended documents**:
 - Job posting/advertisement (PDF, TXT, MD, DOCX)
 - Recruiter emails or communications
 - Company research notes (from website, LinkedIn, Glassdoor)
 - Follow-up emails or additional context
 - Application requirements or instructions
 **Supported formats**: PDF, TXT, MD, DOCX, HTML, EML
 The more context you provide, the better the analysis will be.
 ### Populating the Application
 Once you've added documents to the `input/` folder, navigate to the application directory and run:
 ```
 cd applications/pending/[your-application-folder]/
 /populate-application
 ```
 This will:
 1. Read and analyze all documents in the `input/` folder
 2. Extract job requirements, company information, and keywords
 3. Read your `profile.md` to understand your background
 4. Match your experience and skills to the job requirements
 5. Populate `application.md` with:
   - Extracted job information
   - Company research and culture insights
   - Match strategy (which experiences/skills to emphasize)
   - Key messages to convey
   - Tone recommendations
   - Suggested projects and achievements to highlight
 **The population preserves any manual notes you've added** - it merges AI analysis with your insights.
 ### Working with application.md
 After population, review and refine the `application.md` file:
 - **Review extracted information**: Ensure job details and requirements are accurate
 - **Add your insights**: Enhance the strategy with your own thoughts
 - **Adjust match strategy**: Fine-tune which experiences and projects to emphasize
 - **Add personal notes**: Document your authentic reasons for interest in the role
 - **Plan your approach**: Use the document checklist to track what needs to be created
 The `application.md` serves as your strategic planning document for the entire application process.
 ### Re-populating Applications
 You can run `/populate-application` multiple times:
 - Add more documents to `input/` folder
 - Re-run to merge new analysis with existing content
 - Manual notes are always preserved
 ## When to Read the Profile
 Read `profile.md` automatically when the user asks for help with:
@@ -71,31 +152,49 @@ Read `profile.md` automatically when the user asks for help with:
 ## Job Application Workflow
-When helping with job applications, follow this workflow:
+When helping with job applications, follow this comprehensive workflow:
 ### 0. Profile Validation (REQUIRED FIRST STEP)
 - Run `/validate-profile` to check `profile.md` is complete
 - If validation fails, stop and ask user to complete profile
 - If validation passes or user explicitly skips, proceed to step 1
-### 1. Research & Context
+### 1. Initialize Application (NEW)
- Read the job description provided by the user
+- Use `/new-application "Company - Job Title"` to create organized workspace
- Extract key requirements, skills, and keywords
+- This creates: `applications/pending/YYYY-MM-DD-Company-JobTitle/`
- Analyze the company culture from the job posting language
+- Workspace includes `application.md` template and `input/` folder
 - Read `profile.md` to understand what the applicant brings
-### 2. Match & Strategy
+### 2. Gather Documents & Context (NEW)
- Identify which of the applicant's experiences (from `profile.md`) best match the job requirements
+- User adds documents to `input/` folder:
- Determine which skills and projects to emphasize
+  - Job posting/description
- Decide on the appropriate tone (formal, balanced, or casual) based on company culture
+  - Recruiter communications
  - Company research
  - Any other relevant context
 - More context = better analysis and strategy
-### 3. Content Generation
+### 3. Analyze & Populate (NEW)
- Generate CV/cover letter/email based on the strategy
+- Navigate to application folder: `cd applications/pending/[folder-name]/`
 - Run `/populate-application` to:
  - Read and analyze all input documents
  - Extract job requirements, keywords, company culture
  - Cross-reference with `profile.md`
  - Generate match strategy
  - Populate `application.md` with research and recommendations
 ### 4. Review & Refine Strategy
 - User reviews `application.md` for accuracy
 - User adds personal insights and authentic motivations
 - Adjust which experiences and projects to emphasize
 - Fine-tune key messages and tone
 ### 5. Content Generation (FUTURE)
 - Generate CV/cover letter/email based on `application.md` strategy
 - Emphasize relevant experience from `profile.md`
 - Incorporate keywords from the job description naturally
 - Maintain factual accuracy - use only verified information from `profile.md`
 - **Note**: Document generation will be implemented in a future update
-### 4. Quality Assurance
+### 6. Quality Assurance
 - Verify all company names, dates, and facts are correct
 - Ensure consistency between all documents (CV ↔ cover letter ↔ email)
 - Check that tone matches the target company culture
@@ -154,10 +253,26 @@ Adjust recommendations based on the target market if the user specifies a differ
 ## Available Commands
 - `/validate-profile` - Validate that `profile.md` is complete and ready for application generation
 - `/new-application "Company - Job Title"` - Create a new application workspace with organized folder structure
 - `/populate-application` - Analyze input documents and populate application.md with job info, research, and strategy
 ## Example Usage
-**User**: "Help me apply for this software engineering position at TechCorp [paste job description]"
+### Example 1: Complete Application Workflow
 **User**: "Help me apply for this software engineering position at TechCorp"
 **Claude Code should**:
 1. Run `/validate-profile` to check profile completeness
 2. If validation passes, suggest: "Let's create an application workspace. Run: `/new-application 'TechCorp - Software Engineer'`"
 3. After application is created, guide user: "Add the job posting and any other documents to `applications/pending/[folder]/input/`"
 4. When user has added documents: "Navigate to the application folder and run `/populate-application`"
 5. After population completes: "Review `application.md` to see the analysis and strategy"
 6. Future: Generate tailored CV, cover letter, and email based on `application.md`
 ### Example 2: Quick Document Request (Legacy Flow)
 **User**: "Write a cover letter for this role [paste job description]"
 **Claude Code should**:
 1. Run `/validate-profile` to check profile completeness
@@ -165,9 +280,8 @@ Adjust recommendations based on the target market if the user specifies a differ
 3. If validation passes: Read `profile.md` to load applicant information
 4. Analyze the job description for requirements and culture
 5. Identify matching experiences and skills from the profile
-6. Ask clarifying questions: "Would you like me to create a CV, cover letter, or both?"
+6. Generate tailored cover letter using only information from `profile.md`
-7. Generate tailored documents using only information from `profile.md`
+7. Suggest: "For better organization, consider using `/new-application` next time to manage the full application process"
 8. Ensure all documents are consistent and factually accurate
 ## Updating the Profile
@@ -0,0 +1,2 @@
 # This file ensures the pending applications directory is tracked in git
 # Application folders will be created here when users run /new-application
		`@@ -0,0 +1,2 @@`
							`# This file ensures the pending applications directory is tracked in git`
							`# Application folders will be created here when users run /new-application`