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>

src/.claude/commands/new-application.md

@@ -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

src/.claude/commands/populate-application.md

@@ -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

src/.claude/templates/application-template.md

@@ -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]
+-->

src/CLAUDE.md

@@ -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
-- Read the job description provided by the user
-- Extract key requirements, skills, and keywords
-- Analyze the company culture from the job posting language
-- Read `profile.md` to understand what the applicant brings
+### 1. Initialize Application (NEW)
+- Use `/new-application "Company - Job Title"` to create organized workspace
+- This creates: `applications/pending/YYYY-MM-DD-Company-JobTitle/`
+- Workspace includes `application.md` template and `input/` folder
 
-### 2. Match & Strategy
-- Identify which of the applicant's experiences (from `profile.md`) best match the job requirements
-- Determine which skills and projects to emphasize
-- Decide on the appropriate tone (formal, balanced, or casual) based on company culture
+### 2. Gather Documents & Context (NEW)
+- User adds documents to `input/` folder:
+  - Job posting/description
+  - Recruiter communications
+  - Company research
+  - Any other relevant context
+- More context = better analysis and strategy
 
-### 3. Content Generation
-- Generate CV/cover letter/email based on the strategy
+### 3. Analyze & Populate (NEW)
+- 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?"
-7. Generate tailored documents using only information from `profile.md`
-8. Ensure all documents are consistent and factually accurate
+6. Generate tailored cover letter using only information from `profile.md`
+7. Suggest: "For better organization, consider using `/new-application` next time to manage the full application process"
 
 ## Updating the Profile
 

src/applications/pending/.gitkeep

@@ -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