diff --git a/openspec/changes/archive-applications/design.md b/openspec/changes/archive-applications/design.md new file mode 100644 index 0000000..108a31e --- /dev/null +++ b/openspec/changes/archive-applications/design.md @@ -0,0 +1,549 @@ +# Design Document: Application Archiving + +## Overview + +This document captures the technical design decisions and architectural considerations for implementing the application archiving feature. + +## Design Principles + +### 1. Follow Existing Patterns + +**Principle:** The archive command should follow established patterns from existing commands. + +**Rationale:** +- Consistency in user experience +- Easier maintenance and understanding +- Leverages proven patterns from `write-cover-letter.md` and `write-application-email.md` + +**Application:** +- Command file structure: Markdown with procedural instructions for Claude Code +- Argument parsing: Position-based with optional parameters and flags +- Error handling: Clear, actionable error messages with examples +- Validation: Check inputs before performing operations + +### 2. Safety First + +**Principle:** Protect user work by detecting and warning about generated documents. + +**Rationale:** +- Users may invest significant time in cover letters and emails +- Accidental archiving of work-in-progress could be frustrating +- Better to err on the side of caution + +**Application:** +- Detect: `cover-letter.md`, `application-email.md`, files in `attachments/` +- Warn: Show detailed message listing all detected work +- Require: Explicit `--force` flag to bypass warnings +- Preserve: All files during move (nothing is deleted) + +### 3. Minimal Metadata Updates + +**Principle:** Update only what's necessary, preserve everything else. + +**Rationale:** +- Reduce risk of data corruption +- Simple updates are easier to verify and rollback +- Users may have customized other fields + +**Application:** +- Only modify: Status field in Metadata section +- Format: `- **Status**: [State] (Archived: YYYY-MM-DD HH:MM)` +- Preserve: All other content in `application.md` +- Rollback: If move fails, don't update status + +### 4. On-Demand Creation + +**Principle:** Create archive folders only when needed. + +**Rationale:** +- Avoid cluttering file system with empty folders +- Simpler initial setup (no migration needed) +- Users who don't use archiving don't see archive folders + +**Application:** +- Check: Does `applications/rejected/` exist? +- Create: Only if first time archiving with "rejected" +- Same: For `applications/not-interested/` +- Track: In git with `.gitkeep` if desired + +## Technical Architecture + +### Command Flow + +``` +User Input: /archive-application [reason] [app-name] [--force] + ↓ + ┌─────────────────────────┐ + │ 1. Parse Arguments │ + │ - Extract reason │ + │ - Extract app name │ + │ - Check for --force │ + └──────────┬──────────────┘ + ↓ + ┌─────────────────────────┐ + │ 2. Validate Inputs │ + │ - Reason is valid? │ + │ - App exists? │ + └──────────┬──────────────┘ + ↓ + ┌─────────────────────────┐ + │ 3. Detect Location │ + │ - Current dir? │ + │ - Or resolve path │ + └──────────┬──────────────┘ + ↓ + ┌─────────────────────────┐ + │ 4. Safety Checks │ + │ - Cover letter? │ + │ - Email? │ + │ - Attachments? │ + └──────────┬──────────────┘ + ↓ + ┌────────┴────────┐ + │ Documents found? │ + └────────┬────────┘ + │ + Yes ┌─────┴─────┐ No + ↓ ↓ + ┌──────────────┐ ┌──────────────┐ + │ --force set? │ │ 5. Update │ + └──────┬───────┘ │ Status │ + │ └──────┬───────┘ + Yes ┌──┴──┐ No ↓ + ↓ ↓ ┌──────────────┐ + │ STOP │ 6. Create │ + │ (warn) │ Archive │ + ↓ │ Folder │ + ┌──────────────┐ └──────┬───────┘ + │ 5. Update │ ↓ + │ Status │ ┌──────────────┐ + └──────┬───────┘ │ 7. Move │ + ↓ │ Folder │ + ┌──────────────┐ └──────┬───────┘ + │ 6. Create │ ↓ + │ Archive │ ┌──────────────┐ + │ Folder │ │ 8. Verify │ + └──────┬───────┘ │ Success │ + ↓ └──────┬───────┘ + ┌──────────────┐ ↓ + │ 7. Move │ ┌──────────────┐ + │ Folder │ │ 9. Confirm │ + └──────┬───────┘ │ Message │ + ↓ └──────────────┘ + ┌──────────────┐ + │ 8. Verify │ + │ Success │ + └──────┬───────┘ + ↓ + ┌──────────────┐ + │ 9. Confirm │ + │ Message │ + └──────────────┘ +``` + +### Data Flow + +``` +Input: applications/pending/2025-11-02-TechCorp-Developer/ + ↓ + ┌─────────────────────────┐ + │ Read application.md │ + │ Current Status: Draft │ + └──────────┬──────────────┘ + ↓ + ┌─────────────────────────┐ + │ Update in Memory │ + │ New Status: Rejected │ + │ Timestamp: 2025-12-18 │ + └──────────┬──────────────┘ + ↓ + ┌─────────────────────────┐ + │ Write Back to File │ + │ application.md updated │ + └──────────┬──────────────┘ + ↓ + ┌─────────────────────────┐ + │ Move Entire Folder │ + │ Including updated file │ + └──────────┬──────────────┘ + ↓ +Output: applications/rejected/2025-11-02-TechCorp-Developer/ +``` + +### File System Operations + +```bash +# 1. Status Update (before move) +cd applications/pending/[folder]/ +cat application.md | sed 's/- \*\*Status\*\*:.*/- **Status**: Rejected (Archived: 2025-12-18 15:30)/' > application.md.tmp +mv application.md.tmp application.md + +# 2. Create Archive Directory (if needed) +mkdir -p applications/rejected/ + +# 3. Move Application +mv applications/pending/[folder]/ applications/rejected/[folder]/ + +# 4. Verify +test -d applications/rejected/[folder]/ && echo "Success" +test ! -d applications/pending/[folder]/ && echo "Source removed" +``` + +## Key Design Decisions + +### Decision 1: Status Update Timing + +**Options:** +- A) Update status BEFORE moving folder +- B) Update status AFTER moving folder +- C) Update status IN PLACE after moving + +**Chosen:** Option A - Update status BEFORE moving + +**Rationale:** +- Easier to rollback if move fails (just revert file) +- Status update is atomic operation (less likely to fail) +- If update fails, we stop early (don't move) +- Move operation is riskier, so do simpler operation first + +**Trade-offs:** +- If move fails, status is updated but folder isn't moved +- User sees "Rejected" status in pending folder +- Mitigation: Show clear error, user can fix status or retry move + +### Decision 2: Safety Check Scope + +**Options:** +- A) Only check for generated documents (cover-letter.md, application-email.md) +- B) Check for any modifications to application.md +- C) Check for generated documents + attachments folder +- D) No safety checks, always allow archiving + +**Chosen:** Option C - Generated documents + attachments + +**Rationale:** +- Generated documents represent significant work +- Attachments likely contain CV and certificates +- Checking application.md changes is too broad (may be auto-populated) +- Some safety is better than none, but not overly restrictive + +**Trade-offs:** +- Users can still accidentally archive applications with manual edits to application.md +- Acceptable: application.md is easier to recreate than generated documents + +### Decision 3: Archive Folder Naming + +**Options:** +- A) `rejected/` and `not-interested/` +- B) `archived-rejected/` and `archived-not-interested/` +- C) `archive/rejected/` and `archive/not-interested/` +- D) `rejected/` and `withdrawn/` + +**Chosen:** Option A - `rejected/` and `not-interested/` + +**Rationale:** +- Short, clear folder names +- "rejected" clearly indicates company rejected +- "not-interested" clearly indicates user withdrew +- No redundant "archived" prefix (location implies archived) +- Consistent with user's original request + +**Trade-offs:** +- "not-interested" is verbose compared to "withdrawn" +- Acceptable: clarity over brevity + +### Decision 4: Auto-Detection Scope + +**Options:** +- A) Only detect if in exact application folder +- B) Detect from application folder or subfolders +- C) Detect from anywhere in pending folder tree +- D) No auto-detection, always require application name + +**Chosen:** Option B - Application folder or subfolders + +**Rationale:** +- Users may be in `input/` or `attachments/` when deciding to archive +- Detecting parent folder is user-friendly +- Not too broad (don't detect from root or pending folder itself) +- Matches pattern from other commands + +**Trade-offs:** +- Slightly more complex path resolution logic +- Acceptable: improves user experience + +### Decision 5: Error Handling Strategy + +**Options:** +- A) Fail fast, stop on first error +- B) Try to proceed, show warnings +- C) Rollback on any error +- D) Partial success allowed (e.g., move but don't update status) + +**Chosen:** Option A - Fail fast with Option C rollback on critical errors + +**Rationale:** +- Validate all inputs BEFORE making changes +- Stop early if anything is wrong +- Rollback status update if move fails (critical path) +- Allow partial success only for non-critical operations (e.g., Timeline update) + +**Trade-offs:** +- Less forgiving for edge cases +- Acceptable: better to stop and fix than proceed with errors + +## Component Responsibilities + +### Command File (`archive-application.md`) + +**Responsibilities:** +- Parse and validate command arguments +- Detect application location +- Perform safety checks +- Update Status field +- Create archive directory +- Move application folder +- Verify success +- Show confirmation message + +**NOT Responsible For:** +- Modifying other files besides application.md +- Validating application completeness (separate concern) +- Tracking archived applications (future enhancement) +- Providing archive search (future enhancement) + +### Framework Documentation (`CLAUDE.md`) + +**Responsibilities:** +- Explain when and how to use archiving +- Document command syntax +- Describe safety features +- Show integration with workflow + +**NOT Responsible For:** +- Implementation details (that's in command file) +- Specification (that's in OpenSpec) + +### Specifications (`application-archiving/spec.md`) + +**Responsibilities:** +- Define requirements with scenarios +- Document expected behaviors +- Specify error handling +- Define integration points + +**NOT Responsible For:** +- Implementation approach (that's in command file) +- User-facing documentation (that's in CLAUDE.md) + +## Integration Points + +### With Existing Commands + +``` +/new-application + ↓ creates +application.md (with Status: Draft) + ↓ populated by +/populate-application + ↓ validated by +/validate-application + ↓ generates +/write-cover-letter → cover-letter.md + ↓ generates +/write-application-email → application-email.md + ↓ user sends +(Application submitted) + ↓ archives +/archive-application → moves to rejected/ or not-interested/ +``` + +### With File System + +``` +File System Operations: +- Read: application.md (for current status) +- Write: application.md (to update status) +- Check: cover-letter.md, application-email.md, attachments/* +- Create: applications/rejected/, applications/not-interested/ +- Move: applications/pending/[folder]/ → applications/[reason]/[folder]/ +- Verify: Destination exists, source removed +``` + +### With User Workflow + +``` +User Decision Points: +1. Should I archive? → User decides based on application outcome +2. Which reason? → rejected (company) or not-interested (user) +3. Force or not? → If documents exist, user decides to proceed or cancel +4. Where is it? → User can check archive folders if needed +``` + +## Performance Considerations + +### Operation Speed + +**Status update:** +- Fast: Read/write single text file +- ~10-50ms typical + +**Safety checks:** +- Fast: Check file existence (no content reading) +- ~5-20ms per file + +**Folder move:** +- Fast: On same filesystem, just updates directory entries +- ~10-100ms typical +- Slow: On different filesystems, copies all files +- ~1-10s depending on file count and size + +**Total typical time:** < 1 second + +### Resource Usage + +**Memory:** +- Minimal: Read/write application.md (~5-20KB) +- No large file operations or in-memory copies + +**Disk I/O:** +- Light: Status update (one file write) +- Moderate: Folder move (directory metadata updates) +- Heavy: Only if moving across filesystems (full copy) + +**Optimization:** +- Not needed for typical use case +- Could add progress indicator for large attachments folders + +## Security Considerations + +### File System Access + +**Concerns:** +- User must have write permissions on pending/ and archive folders +- Must be able to modify application.md +- Must be able to move folders + +**Mitigations:** +- Check permissions before attempting operations +- Clear error messages if permissions denied +- No privilege escalation or dangerous operations + +### Data Preservation + +**Concerns:** +- Accidental data loss if move fails partway +- Status update without successful move + +**Mitigations:** +- Verify move succeeded before confirming +- Rollback status if move fails +- Never delete source until verified at destination +- Safety warnings for generated documents + +### Path Traversal + +**Concerns:** +- User could provide application name like "../../../etc" +- Could try to move folders outside applications/ + +**Mitigations:** +- Validate application name is valid folder in pending/ +- Resolve full paths and check they're within applications/ +- No user-provided target paths (only reason parameter) + +## Testing Strategy + +### Unit-Level Testing + +**Test each component:** +- Argument parsing (valid/invalid inputs) +- Location detection (current dir vs. explicit name) +- Safety checks (detect documents correctly) +- Status update (find and replace correctly) +- Folder move (succeed and rollback) + +### Integration Testing + +**Test command flow:** +- End-to-end archiving (from pending to rejected) +- End-to-end with safety checks +- Error scenarios (not found, invalid reason, etc.) + +### Edge Case Testing + +**Test unusual scenarios:** +- Missing Status field (add it) +- Empty attachments folder (don't warn) +- Re-archiving (error appropriately) +- Concurrent access (handle gracefully) + +### Manual Testing + +**User acceptance:** +- Run through complete workflow +- Verify intuitive behavior +- Check error messages are clear +- Confirm success messages are helpful + +## Future Considerations + +### Extensibility + +**Easy to add later:** +- Additional archive reasons (accepted, on-hold, etc.) +- Archive search and listing commands +- Bulk archiving operations +- Archive statistics and reporting + +**Design supports:** +- Parameterized reason (easy to add new values) +- Consistent folder structure (easy to extend) +- Status field format (can add more states) + +### Scalability + +**Current design:** +- Handles dozens to hundreds of applications fine +- Linear search in pending folder (acceptable scale) +- File system operations are efficient + +**If needed later:** +- Index of archived applications +- Database for faster searches +- Bulk operations for managing many archives + +### Maintenance + +**Design for maintainability:** +- Follows existing command patterns +- Clear separation of concerns +- Well-documented in code and specs +- Testable components + +**Future updates:** +- Easy to modify error messages +- Easy to add new safety checks +- Easy to extend with new features +- Easy to update status field format + +## Summary + +The archiving feature is designed to: +- ✅ Follow established patterns for consistency +- ✅ Protect user work with safety checks +- ✅ Minimize changes to existing files +- ✅ Create resources on-demand +- ✅ Integrate naturally with existing workflow +- ✅ Handle errors gracefully with clear messages +- ✅ Support future enhancements + +**Complexity:** Low to moderate +**Risk:** Low (additive feature, no breaking changes) +**Maintenance:** Low (follows patterns, well-documented) +**User Impact:** High (solves real organizational need) + +--- + +**Design Status:** Complete and ready for implementation +**Next Steps:** Review proposal, implement according to tasks.md diff --git a/openspec/changes/archive-applications/proposal.md b/openspec/changes/archive-applications/proposal.md new file mode 100644 index 0000000..73c4b6d --- /dev/null +++ b/openspec/changes/archive-applications/proposal.md @@ -0,0 +1,709 @@ +# Proposal: Archive Applications + +## Change ID +`archive-applications` + +## Summary +Add the ability to archive unsuccessful job applications by moving them from `applications/pending/` to organized archive folders (`applications/rejected/` or `applications/not-interested/`). The system will update application metadata and warn users before archiving applications with generated documents. + +## Problem Statement + +Users currently have no structured way to organize completed or unsuccessful applications. All applications remain in the `applications/pending/` folder indefinitely, making it difficult to: + +1. Distinguish between active and inactive applications +2. Organize applications by outcome (rejected by company vs. user withdrew) +3. Keep the pending folder clean and focused on current opportunities +4. Track the lifecycle of applications from creation to completion + +## Proposed Solution + +Introduce a `/archive-application` command that: + +1. Moves applications from `applications/pending/` to outcome-specific folders: + - `applications/rejected/` - Company rejected the application + - `applications/not-interested/` - User decided not to pursue + +2. Updates application metadata: + - Modifies the Status field in `application.md` with timestamp + - Preserves all application work (documents, input files, attachments) + +3. Protects user work: + - Detects generated documents (cover letters, emails, attachments) + - Warns before archiving and requires explicit `--force` flag + - Prevents accidental loss of significant work + +4. Provides flexible usage: + - Auto-detects application when run from within application folder + - Accepts application name parameter when run from any location + - Supports help flag for usage information + +## User Requirements + +Based on user clarification during proposal phase: + +- ✅ **Metadata update**: Move files AND update Status field with timestamp +- ✅ **Command design**: Single command with parameter: `/archive-application [reason]` +- ✅ **Safety checks**: Warn if documents exist, require `--force` to proceed +- ✅ **Scope**: Only rejection paths (`rejected` and `not-interested`) for now + +## Success Criteria + +After implementation, users should be able to: + +1. Archive applications from within the application folder +2. Archive applications by name from any location +3. Receive warnings before archiving applications with work invested +4. See updated Status field with timestamp after archiving +5. Find archived applications in organized folders by reason +6. Use `--force` to skip safety checks when confident + +## Command Interface + +### Syntax + +```bash +/archive-application [reason] [application-name] [--force] +``` + +### Parameters + +- **reason** (required): Either `rejected` or `not-interested` + - `rejected` - Company rejected the application + - `not-interested` - User decided to withdraw or not pursue further + +- **application-name** (optional): Application folder name + - If omitted: Auto-detect from current working directory + - If provided: Resolve to full path in pending folder + +- **--force** (flag): Skip safety warnings about generated documents + +### Examples + +```bash +# From within application folder +cd applications/pending/2025-11-02-TechCorp-Developer/ +/archive-application rejected + +# From anywhere with application name +/archive-application rejected 2025-11-02-TechCorp-Developer + +# Skip safety checks +/archive-application not-interested --force + +# Get help +/archive-application --help +``` + +## Folder Structure + +### Before +``` +src/applications/ +└── pending/ + ├── 2025-11-02-TechCorp-Developer/ + ├── 2025-11-05-StartupCo-Engineer/ + └── 2025-11-10-BigCorp-Lead/ +``` + +### After +``` +src/applications/ +├── pending/ +│ └── 2025-11-10-BigCorp-Lead/ # Still active +├── rejected/ +│ └── 2025-11-02-TechCorp-Developer/ # Company rejected +└── not-interested/ + └── 2025-11-05-StartupCo-Engineer/ # User withdrew +``` + +Applications maintain their original folder name (`YYYY-MM-DD-Company-JobTitle/`) when moved. + +## Archiving Process + +### Step-by-Step Flow + +1. **Parse & Validate** + - Extract reason parameter (rejected/not-interested) + - Extract optional application name and flags + - Validate reason is one of the allowed values + +2. **Location Detection** + - If no application name: Check if running from within an application folder + - If application name: Resolve to full path in pending folder + - Verify `application.md` exists + +3. **Safety Check** (unless `--force`) + - Check for `cover-letter.md` in application folder + - Check for `application-email.md` in application folder + - Check for files in `attachments/` folder (excluding `.keep`) + - If ANY found: Show warning and require `--force` to proceed + +4. **Update Metadata** + - Read `application.md` + - Find Status field in Metadata section: `- **Status**: Draft` + - Replace with: `- **Status**: Rejected (Archived: 2025-12-18 15:30)` OR `- **Status**: Not Interested (Archived: 2025-12-18 15:30)` + - Write back to file + +5. **Create Archive Directory** + - Create `applications/rejected/` or `applications/not-interested/` if doesn't exist + +6. **Move Application** + - Execute: `mv applications/pending/[folder]/ applications/[reason]/[folder]/` + - Verify move succeeded (destination exists, source removed) + +7. **Confirm Success** + - Show success message with archive details + - Include original and new locations + - Display updated status + +### Safety Warning Example + +``` +⚠️ Warning: Generated documents detected + +This application contains work that may be lost: +- cover-letter.md (exists) +- application-email.md (exists) +- attachments/ folder (3 files) + +Archiving will move everything to the archive folder, but these documents +suggest you may have put significant work into this application. + +Options: +1. Continue archiving anyway: /archive-application rejected --force +2. Cancel and review the documents first +3. Export/backup documents before archiving + +Are you sure you want to archive this application? +``` + +**System behavior**: STOP and require `--force` flag to proceed. + +## Technical Implementation + +### Status Field Update + +**Current format (in template):** +```markdown +- **Status**: Draft +``` + +**After archiving (rejected):** +```markdown +- **Status**: Rejected (Archived: 2025-12-18 15:30) +``` + +**After archiving (not-interested):** +```markdown +- **Status**: Not Interested (Archived: 2025-12-18 15:30) +``` + +**Implementation approach:** +1. Read entire `application.md` file +2. Find line matching pattern: `^(\s*-\s*\*\*Status\*\*:\s*)(.*)$` +3. Replace entire line with new status and timestamp +4. Write back to file + +**Timestamp format:** `YYYY-MM-DD HH:MM` (ISO-style date, 24-hour time) + +### Safety Check Logic + +**Detection criteria:** +```bash +# Check for generated documents +test -f cover-letter.md # Cover letter exists +test -f application-email.md # Email exists +ls attachments/ | grep -v '\.keep' | wc -l > 0 # Has attachments besides .keep +``` + +**Warning trigger:** +- ANY of: cover-letter.md exists, application-email.md exists, attachments count > 0 + +**Bypass:** +- Provide `--force` flag to skip all safety checks + +### Auto-Detection Pattern + +**When no application name provided:** +1. Get current working directory +2. Check if path matches: `*/applications/pending/[folder-name]/` +3. Verify `application.md` exists in current directory +4. Extract folder name for use in move operation + +**When application name provided:** +1. Resolve to full path: `applications/pending/[provided-name]/` +2. Verify folder exists +3. Verify `application.md` exists + +## Error Handling + +### Error Scenarios + +1. **Invalid reason** + ``` + ❌ Invalid reason: [provided-reason] + + Reason must be one of: + - rejected: Company rejected the application + - not-interested: User withdrew or not pursuing + + Usage: /archive-application [reason] [application-name] + ``` + +2. **Application not found** + ``` + ❌ Application not found: [application-name] + + Available applications in pending: + [List folders in applications/pending/] + + Usage: /archive-application [reason] [application-name] + ``` + +3. **Not in application folder** + ``` + ❌ Not in an application folder + + Please either: + 1. Navigate to an application folder: + cd applications/pending/[application-folder]/ + /archive-application [reason] + + 2. Or provide the application folder name: + /archive-application [reason] [application-folder-name] + + Available applications: + [List folders in applications/pending/] + ``` + +4. **Already archived** + ``` + ❌ Application not found in pending folder + + The application "[folder-name]" doesn't exist in applications/pending/. + + Did you already archive it? Check: + - applications/rejected/ + - applications/not-interested/ + + To move between archives, use mv command directly. + ``` + +5. **File operation failure** + ``` + ❌ Failed to archive application + + Error: [specific error message] + + Possible causes: + - Insufficient permissions + - File system full + - Application folder is open in another program + + Please check the issue and try again. + The application has NOT been modified. + ``` + +6. **Status update failure** + ``` + ⚠️ Application moved but status update failed + + The application was moved to: + applications/[reason]/[folder-name]/ + + However, the Status field in application.md could not be updated. + Please manually update: - **Status**: [Rejected/Not Interested] (Archived: [date]) + + Error: [specific error details] + ``` + +## Edge Cases + +### Handled Edge Cases + +1. **Partially generated application** + - User created cover letter but not email + - **Handling:** Warn - any generated document is significant work + +2. **Empty attachments folder** + - `attachments/` exists but only contains `.keep` file + - **Handling:** Don't count as "having attachments" - no warning + +3. **Re-archiving** + - User tries to archive application already in rejected folder + - **Handling:** Error message suggesting application already archived + +4. **Missing Status field** + - Old `application.md` doesn't have Status field in Metadata section + - **Handling:** Add Status field to Metadata section, then proceed + +5. **Permission errors** + - Can't write to `application.md` or can't move folder + - **Handling:** Rollback any changes, show clear error, leave in pending + +6. **Concurrent operations** + - User has application open in editor while archiving + - **Handling:** File system will handle, may fail - show appropriate error + +## Integration Points + +### With Existing Workflow + +The archiving feature integrates at the end of the application lifecycle: + +``` +Current workflow: +1. Create: /new-application "Company - Job Title" +2. Populate: /populate-application +3. Validate: /validate-application +4. Generate: /write-cover-letter +5. Generate: /write-application-email +6. Send: (User sends application via email client) + +NEW: +7. Archive: /archive-application [reason] ← NEW STEP +``` + +### With Application States + +**Application lifecycle states:** + +- **Draft** - Created, not yet populated (in `pending/`) +- **In Progress** - Being worked on, documents generated (in `pending/`) +- **Submitted** - Sent to company, awaiting response (in `pending/`) +- **Rejected** - Company rejected (in `rejected/`) +- **Not Interested** - User withdrew (in `not-interested/`) + +**Status field tracking:** +- `application.md` Metadata section maintains current state +- Archive operation updates state with timestamp +- State history is preserved in Timeline section + +### With Documentation + +**Updates needed to `src/CLAUDE.md`:** + +1. Add new section: "Archiving Applications" (~40 lines) + - Explain archiving workflow + - Show command syntax and examples + - Describe safety checks + - Document archive folder structure + +2. Update "Available Commands" list + - Add `/archive-application` with parameters and flags + +3. Update workflow examples + - Include archiving as final step in lifecycle + +## Dependencies + +### File Dependencies + +**Required existing files:** +- `applications/pending/` - Source folder for active applications +- `application.md` - Must exist in each application folder +- `src/CLAUDE.md` - Framework instructions to update + +**Created files:** +- `applications/rejected/` - Created on-demand when first needed +- `applications/not-interested/` - Created on-demand when first needed + +### Command Dependencies + +**No hard dependencies on other commands**, but archiving is typically the last step after: +- `/new-application` - Creates the application +- `/populate-application` - Populates strategy +- `/write-cover-letter` - Generates cover letter +- `/write-application-email` - Generates email + +**Users can archive at any stage** (even immediately after creation if they change their mind). + +## Testing Considerations + +### Test Scenarios + +1. **Basic archiving from within application folder** + - No generated documents + - Should succeed without warnings + +2. **Archiving with application name parameter** + - From any location + - Should resolve path and succeed + +3. **Safety check with cover letter** + - Generated cover-letter.md exists + - Should warn and require --force + +4. **Safety check with attachments** + - Files exist in attachments/ folder + - Should warn and require --force + +5. **Force flag bypasses warnings** + - Use --force with generated documents + - Should proceed without warnings + +6. **Invalid reason parameter** + - Provide unsupported reason (e.g., "accepted") + - Should error with valid options + +7. **Application not found** + - Provide non-existent application name + - Should error with available applications list + +8. **Wrong directory without parameter** + - Run from root without application name + - Should error with usage guidance + +9. **Create rejected folder for first time** + - First time archiving with "rejected" reason + - Should create applications/rejected/ folder + +10. **Multiple applications to same folder** + - Archive multiple applications as rejected + - Should handle without conflicts + +11. **Status field update verification** + - Check application.md after archiving + - Should have updated Status with timestamp + +12. **Missing Status field** + - Archive old application without Status field + - Should add field before archiving + +## Backwards Compatibility + +### Compatibility Analysis + +**No breaking changes:** +- Existing applications in `pending/` folder are unaffected +- Archive folders are created on-demand +- Status field already exists in current template (line 12) +- No changes to existing command behavior +- No changes to folder structure for pending applications + +**Forwards compatible:** +- Old applications can be archived (Status field added if missing) +- New applications will work with archiving from day one +- Archive folders follow same naming convention as pending + +**Migration:** None required - feature works with existing applications as-is + +## Alternatives Considered + +### Alternative 1: Separate Commands for Each Reason + +**Approach:** Create `/reject-application` and `/withdraw-application` commands + +**Pros:** +- More intuitive command names +- Clearer user intent +- Better discoverability (separate help for each) + +**Cons:** +- Code duplication (same logic in two commands) +- More commands to maintain +- Harder to add new archive reasons later + +**Decision:** Rejected in favor of single parameterized command based on user preference + +### Alternative 2: Just Move Files (No Metadata Update) + +**Approach:** Simple file move without updating `application.md` + +**Pros:** +- Simpler implementation +- Faster execution +- Less chance of file corruption + +**Cons:** +- Lose tracking of when and why archived +- Status field becomes outdated +- No audit trail of archival + +**Decision:** Rejected - metadata update provides valuable tracking + +### Alternative 3: Always Allow Archiving (No Safety Checks) + +**Approach:** Skip all warnings, just move files + +**Pros:** +- Faster for experienced users +- No interruptions +- Simpler implementation + +**Cons:** +- Risk of accidentally archiving significant work +- No protection against mistakes +- Harder to recover from accidents + +**Decision:** Rejected - safety checks prevent data loss and frustration + +### Alternative 4: Add `accepted` Folder Immediately + +**Approach:** Include `applications/accepted/` from the start + +**Pros:** +- Complete lifecycle coverage +- Users can track successful applications +- More comprehensive solution + +**Cons:** +- Scope creep beyond user request +- Different use case (accepted apps are managed differently) +- Can add later if needed + +**Decision:** Rejected - focus on user's current need (rejection paths) + +## Future Enhancements + +Not included in this proposal but could be added in future changes: + +1. **Accepted archive** - `applications/accepted/` folder for successful applications +2. **Unarchive command** - `/unarchive-application` to move back to pending +3. **List archived** - `/list-archived` command to browse archives by reason +4. **Archive statistics** - Show counts of applications by outcome +5. **Archive search** - Find applications in archives by company or date +6. **Bulk operations** - Archive multiple applications at once +7. **Archive notes** - Add custom notes when archiving (why rejected, lessons learned) +8. **Expiration/cleanup** - Auto-delete archived applications older than X months +9. **Export archive** - Export archived applications to external format (CSV, JSON) +10. **Timeline tracking** - Add "Archived" entry to Timeline section in `application.md` + +## Risks and Mitigations + +### Risk 1: Accidental Data Loss + +**Risk:** Users accidentally archive applications with significant work + +**Likelihood:** Medium (users may not realize they have generated documents) + +**Impact:** High (loss of cover letters, emails, strategy work) + +**Mitigation:** +- Implement safety checks that detect generated documents +- Require explicit `--force` flag to bypass warnings +- Show detailed warning listing all documents that would be archived +- Preserve all files during move (nothing is deleted) + +### Risk 2: File System Errors + +**Risk:** Move operation fails due to permissions, disk space, or concurrent access + +**Likelihood:** Low (most systems handle file operations reliably) + +**Impact:** Medium (application left in inconsistent state) + +**Mitigation:** +- Check permissions before attempting move +- Verify destination doesn't already exist +- Rollback metadata changes if move fails +- Show clear error messages with troubleshooting steps +- Never delete source until move is verified + +### Risk 3: Status Update Failures + +**Risk:** Status field update fails but files are moved + +**Likelihood:** Low (text file updates usually succeed) + +**Impact:** Low (application is archived, just metadata is stale) + +**Mitigation:** +- Update status BEFORE moving files (easier to recover) +- If update fails, stop and don't move +- If move succeeds but status fails, warn user but don't rollback +- Provide manual update instructions in error message + +### Risk 4: User Confusion About Archive Locations + +**Risk:** Users can't find archived applications after moving them + +**Likelihood:** Medium (users may forget where they archived) + +**Impact:** Low (applications are still accessible, just in different folder) + +**Mitigation:** +- Show clear success message with new location +- Use intuitive folder names (rejected, not-interested) +- Document archive structure in CLAUDE.md +- Consider future enhancement: `/list-archived` command + +### Risk 5: Archive Folder Clutter + +**Risk:** Archive folders become cluttered with many old applications + +**Likelihood:** High (over time, many applications will be archived) + +**Impact:** Low (just organizational issue, doesn't affect functionality) + +**Mitigation:** +- Maintain date prefix in folder names for chronological sorting +- Document folder structure in CLAUDE.md +- Consider future enhancement: expiration/cleanup policy +- Consider future enhancement: archive search functionality + +## Implementation Approach + +### Phase 1: Core Command (Priority 1) + +1. Create command file: `src/.claude/commands/archive-application.md` + - ~500-700 lines procedural instructions + - Follow pattern from `write-cover-letter.md` + - Include all validation, safety checks, error handling + +2. Update framework docs: `src/CLAUDE.md` + - Add "Archiving Applications" section + - Update "Available Commands" list + - Include workflow integration examples + +### Phase 2: Specifications (Priority 1) + +3. Create OpenSpec spec: `openspec/specs/application-archiving/spec.md` + - Formal requirements with scenarios + - Document all behaviors and edge cases + +4. Update existing spec: `openspec/specs/application-management/spec.md` + - Add lifecycle management requirement + - Document application states + +### Phase 3: Testing & Validation (Priority 2) + +5. Manual testing of all scenarios +6. Verification of error handling +7. Documentation review for clarity + +### Phase 4: Optional Enhancements (Priority 3) + +8. Consider adding Timeline section updates +9. Consider archive listing functionality +10. Consider unarchive command + +## Approval Checklist + +Before implementation begins, verify: + +- [ ] User has confirmed archiving approach (move + metadata update) +- [ ] Command syntax is clear and intuitive +- [ ] Safety check behavior is acceptable +- [ ] Archive folder structure makes sense +- [ ] Error handling covers common scenarios +- [ ] Integration with existing workflow is smooth +- [ ] OpenSpec proposal follows project conventions +- [ ] No breaking changes to existing functionality + +## Success Metrics + +After implementation, measure success by: + +1. **Functionality**: Users can successfully archive applications +2. **Safety**: No reports of accidental data loss +3. **Usability**: Users understand command syntax without extensive documentation +4. **Integration**: Command fits naturally into existing workflow +5. **Maintenance**: Command follows established patterns, easy to maintain + +--- + +**Status:** Proposal draft ready for review +**Change ID:** archive-applications +**Estimated Effort:** Medium (1-2 hours implementation) +**Risk Level:** Low (non-breaking, additive feature) diff --git a/openspec/changes/archive-applications/specs/application-archiving/spec.md b/openspec/changes/archive-applications/specs/application-archiving/spec.md new file mode 100644 index 0000000..eb3b1bc --- /dev/null +++ b/openspec/changes/archive-applications/specs/application-archiving/spec.md @@ -0,0 +1,377 @@ +# application-archiving Specification + +## Purpose +Provide a structured way to archive job applications that are no longer active, maintaining organization and preserving all application work. This capability enables users to move applications from `applications/pending/` to outcome-specific folders (`rejected`, `not-interested`) with metadata updates and safety protections. + +## ADDED Requirements + +### Requirement: Application Archiving Command + +The system SHALL provide a `/archive-application` command that moves applications from pending to archive folders with metadata updates. + +#### Scenario: Archive rejected application from current directory + +- **WHEN** user navigates to `applications/pending/[folder]/` and runs `/archive-application rejected` +- **THEN** system detects current application automatically +- **AND** moves application folder from `applications/pending/` to `applications/rejected/` +- **AND** updates Status field to "Rejected (Archived: [timestamp])" +- **AND** preserves all files and folders (application.md, input/, attachments/) +- **AND** shows success message with archive location + +#### Scenario: Archive not-interested application by name + +- **WHEN** user runs `/archive-application not-interested 2025-11-02-TechCorp-Developer` from any location +- **THEN** system resolves application path in pending folder +- **AND** moves application to `applications/not-interested/` +- **AND** updates Status field to "Not Interested (Archived: [timestamp])" +- **AND** shows success message with original and new locations + +#### Scenario: Display help information + +- **WHEN** user runs `/archive-application --help` +- **THEN** system displays command syntax and usage information +- **AND** explains parameters (reason, application-name, flags) +- **AND** provides examples for common scenarios +- **AND** describes what happens during archiving + +#### Scenario: Validate reason parameter + +- **WHEN** user provides invalid reason (not "rejected" or "not-interested") +- **THEN** system shows error message listing valid reasons +- **AND** displays usage information +- **AND** does NOT modify any files + +#### Scenario: Resolve application location + +- **WHEN** user provides application name without full path +- **THEN** system searches `applications/pending/` for matching folder +- **AND** resolves to full path if found +- **AND** shows error if application not found +- **AND** lists available applications in pending folder + +--- + +### Requirement: Safety Warnings for Generated Documents + +The system SHALL warn users before archiving applications with generated documents to prevent accidental loss of work. + +#### Scenario: Detect and warn about cover letter + +- **WHEN** application folder contains `cover-letter.md` +- **THEN** system displays warning message +- **AND** lists cover-letter.md as generated document +- **AND** stops archiving process +- **AND** requires `--force` flag to proceed + +#### Scenario: Detect and warn about application email + +- **WHEN** application folder contains `application-email.md` +- **THEN** system displays warning message +- **AND** lists application-email.md as generated document +- **AND** stops archiving process +- **AND** requires `--force` flag to proceed + +#### Scenario: Detect and warn about attachments + +- **WHEN** `attachments/` folder contains files (excluding `.keep`) +- **THEN** system displays warning message +- **AND** shows count of files in attachments folder +- **AND** stops archiving process +- **AND** requires `--force` flag to proceed + +#### Scenario: Warning message provides clear options + +- **WHEN** safety warning is displayed +- **THEN** message lists all detected documents +- **AND** explains that archiving will move everything +- **AND** provides three options: continue with --force, cancel to review, or backup first +- **AND** shows exact command to use with --force flag + +#### Scenario: Force flag bypasses all warnings + +- **WHEN** user provides `--force` flag +- **THEN** system skips all safety checks +- **AND** proceeds with archiving without warnings +- **AND** shows brief notice that --force was used +- **AND** completes archiving successfully + +#### Scenario: No warning for empty attachments folder + +- **WHEN** `attachments/` folder exists but only contains `.keep` file +- **THEN** system does NOT treat this as "having attachments" +- **AND** does NOT display warning about attachments +- **AND** proceeds with archiving (if no other documents found) + +--- + +### Requirement: Status and Timestamp Tracking + +The system SHALL update application metadata when archiving to maintain audit trail and lifecycle tracking. + +#### Scenario: Update Status field for rejected application + +- **WHEN** application is archived with reason "rejected" +- **THEN** system reads `application.md` file +- **AND** locates Status field in Metadata section +- **AND** replaces Status line with: `- **Status**: Rejected (Archived: YYYY-MM-DD HH:MM)` +- **AND** writes updated content back to file +- **AND** preserves all other content in application.md + +#### Scenario: Update Status field for not-interested application + +- **WHEN** application is archived with reason "not-interested" +- **THEN** system reads `application.md` file +- **AND** locates Status field in Metadata section +- **AND** replaces Status line with: `- **Status**: Not Interested (Archived: YYYY-MM-DD HH:MM)` +- **AND** writes updated content back to file +- **AND** preserves all other content in application.md + +#### Scenario: Handle missing Status field + +- **WHEN** application.md does not have Status field in Metadata section +- **THEN** system adds Status field to Metadata section +- **AND** sets Status to appropriate archived value with timestamp +- **AND** preserves existing Metadata section formatting +- **AND** proceeds with archiving + +#### Scenario: Timestamp format + +- **WHEN** Status field is updated with timestamp +- **THEN** timestamp follows format: YYYY-MM-DD HH:MM +- **AND** uses current date and time at moment of archiving +- **AND** uses 24-hour time format +- **AND** is human-readable and sortable + +#### Scenario: Status update failure handling + +- **WHEN** Status field update fails (file locked, permissions error) +- **THEN** system stops archiving process +- **AND** shows error message with details +- **AND** does NOT move application folder +- **AND** leaves application in pending folder unchanged + +--- + +### Requirement: Archive Folder Structure + +The system SHALL maintain organized archive folders by reason while preserving application structure. + +#### Scenario: Create rejected archive folder on first use + +- **WHEN** user archives first application with reason "rejected" +- **AND** `applications/rejected/` folder does not exist +- **THEN** system creates `applications/rejected/` directory +- **AND** shows progress message: "Created archive directory: applications/rejected/" +- **AND** proceeds with archiving to new folder + +#### Scenario: Create not-interested archive folder on first use + +- **WHEN** user archives first application with reason "not-interested" +- **AND** `applications/not-interested/` folder does not exist +- **THEN** system creates `applications/not-interested/` directory +- **AND** shows progress message: "Created archive directory: applications/not-interested/" +- **AND** proceeds with archiving to new folder + +#### Scenario: Preserve folder naming convention + +- **WHEN** application is moved to archive +- **THEN** folder name remains unchanged (YYYY-MM-DD-Company-JobTitle format) +- **AND** application is placed in `applications/[reason]/[original-folder-name]/` +- **AND** date prefix is preserved for chronological sorting + +#### Scenario: Preserve application structure + +- **WHEN** application folder is moved to archive +- **THEN** all subfolders are preserved (input/, attachments/) +- **AND** all files are preserved (application.md, cover-letter.md, application-email.md) +- **AND** folder structure remains identical to pending folder structure +- **AND** no files are modified except application.md Status field + +#### Scenario: Verify successful move + +- **WHEN** move operation completes +- **THEN** system verifies destination folder exists: `applications/[reason]/[folder]/` +- **AND** verifies source folder no longer exists: `applications/pending/[folder]/` +- **AND** verifies application.md exists at destination +- **AND** only shows success message after verification passes + +--- + +### Requirement: Comprehensive Error Handling + +The system SHALL provide clear, actionable error messages for all failure scenarios. + +#### Scenario: Invalid reason parameter error + +- **WHEN** user provides unsupported reason (not "rejected" or "not-interested") +- **THEN** system displays error message: "Invalid reason: [provided-reason]" +- **AND** lists valid options: rejected, not-interested +- **AND** explains what each reason means +- **AND** shows usage syntax + +#### Scenario: Application not found error + +- **WHEN** user provides application name that doesn't exist in pending +- **THEN** system displays error message: "Application not found: [application-name]" +- **AND** lists all available applications in `applications/pending/` +- **AND** shows usage syntax with application name parameter + +#### Scenario: Not in application folder error + +- **WHEN** user runs command without application name parameter +- **AND** current directory is not within an application folder +- **THEN** system displays error message: "Not in an application folder" +- **AND** explains two options: navigate to application folder, or provide application name +- **AND** lists available applications in pending folder +- **AND** shows example commands for both approaches + +#### Scenario: Already archived error + +- **WHEN** user tries to archive application that doesn't exist in pending +- **THEN** system displays error message: "Application not found in pending folder" +- **AND** suggests checking archive folders (rejected/, not-interested/) +- **AND** explains how to move between archives if needed +- **AND** does NOT show pending applications list (not relevant) + +#### Scenario: File operation failure error + +- **WHEN** move operation fails (permissions, disk space, concurrent access) +- **THEN** system displays error message: "Failed to archive application" +- **AND** includes specific error details from file system +- **AND** lists possible causes (permissions, disk space, file in use) +- **AND** confirms: "The application has NOT been modified" +- **AND** suggests checking the issue and trying again + +#### Scenario: Permission denied error + +- **WHEN** user lacks permissions to write to application.md or move folder +- **THEN** system displays error about insufficient permissions +- **AND** explains which operation failed (status update or folder move) +- **AND** suggests checking file/folder permissions +- **AND** ensures no partial changes (rollback any modifications) + +--- + +### Requirement: Auto-Detection of Application Location + +The system SHALL automatically detect the target application when run from within an application folder. + +#### Scenario: Detect application from current directory + +- **WHEN** user is in directory matching pattern `*/applications/pending/[folder-name]/` +- **AND** current directory contains `application.md` file +- **THEN** system automatically detects application to archive +- **AND** extracts folder name for use in move operation +- **AND** does NOT require application name parameter + +#### Scenario: Verify application.md exists + +- **WHEN** system detects application from current directory +- **THEN** system verifies `application.md` file exists +- **AND** shows error if application.md missing +- **AND** explains that directory doesn't appear to be valid application folder + +#### Scenario: Handle subdirectories within application + +- **WHEN** user is in subdirectory like `*/applications/pending/[folder]/input/` +- **THEN** system detects parent application folder +- **AND** resolves to correct application path +- **AND** proceeds with archiving parent application + +#### Scenario: Explicit name overrides auto-detection + +- **WHEN** user provides application name parameter +- **THEN** system uses provided name instead of auto-detecting +- **AND** ignores current directory location +- **AND** resolves to specified application in pending folder + +--- + +### Requirement: Success Messaging and Confirmation + +The system SHALL provide clear confirmation when archiving succeeds with relevant details. + +#### Scenario: Display success message with details + +- **WHEN** archiving completes successfully +- **THEN** system displays success message: "Application archived successfully" +- **AND** shows application name (Company - Job Title) +- **AND** shows original location: `applications/pending/[folder]/` +- **AND** shows archived location: `applications/[reason]/[folder]/` +- **AND** shows reason: "Rejected by company" or "No longer interested" +- **AND** shows updated Status: "Rejected (Archived: [timestamp])" + +#### Scenario: Confirm preservation of all files + +- **WHEN** success message is displayed +- **THEN** message confirms: "All documents intact" +- **AND** explains application can still be accessed at new location +- **AND** provides full path to archived application + +#### Scenario: Success with --force flag + +- **WHEN** archiving completes with --force flag +- **THEN** success message includes note: "Safety checks skipped (--force)" +- **AND** lists which documents were detected but bypassed +- **AND** confirms all documents were moved to archive + +--- + +## Cross-References + +### Related Capabilities + +- **application-management**: Archiving is the final step in application lifecycle +- **application-validation**: Validation ensures applications are complete before potential archiving +- **cover-letter-generation**: Generated cover letters trigger safety warnings when archiving +- **application-email**: Generated emails trigger safety warnings when archiving + +### Integration Points + +- Status field in `application.md` (managed by application-management) +- Application folder structure (defined by application-management) +- Generated document detection (cover-letter.md, application-email.md) +- Attachments folder (created by application-management) + +--- + +## Technical Notes + +### Status Field Update Implementation + +**Pattern matching:** +```regex +^(\s*-\s*\*\*Status\*\*:\s*)(.*)$ +``` + +**Replacement format:** +```markdown +- **Status**: [Rejected|Not Interested] (Archived: YYYY-MM-DD HH:MM) +``` + +### Safety Check Detection + +**Files to check:** +1. `cover-letter.md` in application folder +2. `application-email.md` in application folder +3. Any files in `attachments/` excluding `.keep` + +**Warning triggered if ANY found** + +### Archive Folder Paths + +- Rejected: `src/applications/rejected/` +- Not interested: `src/applications/not-interested/` + +**Folders created on-demand when first needed** + +--- + +## Validation + +This specification can be validated by: + +1. Running `openspec validate archive-applications --strict` +2. Verifying all requirements have at least one scenario +3. Checking all scenarios follow WHEN/THEN/AND format +4. Confirming no placeholder text remains in requirements diff --git a/openspec/changes/archive-applications/specs/application-management/spec.md b/openspec/changes/archive-applications/specs/application-management/spec.md new file mode 100644 index 0000000..0c97c01 --- /dev/null +++ b/openspec/changes/archive-applications/specs/application-management/spec.md @@ -0,0 +1,197 @@ +# application-management Specification Delta + +## Purpose +Document updates to application-management capability to include lifecycle management and archival support. + +## ADDED Requirements + +### Requirement: Application Lifecycle Management + +The system SHALL support the complete lifecycle of applications from creation through archival with clear state tracking. + +#### Scenario: Application progresses through lifecycle states + +- **WHEN** application is created with `/new-application` +- **THEN** Status is set to "Draft" in Metadata section +- **AND** application is stored in `applications/pending/` folder +- **WHEN** application is archived with `/archive-application rejected` +- **THEN** Status is updated to "Rejected (Archived: [timestamp])" +- **AND** application is moved to `applications/rejected/` folder +- **WHEN** application is archived with `/archive-application not-interested` +- **THEN** Status is updated to "Not Interested (Archived: [timestamp])" +- **AND** application is moved to `applications/not-interested/` folder + +#### Scenario: Folder organization reflects application state + +- **WHEN** viewing applications directory structure +- **THEN** active applications are in `applications/pending/` +- **AND** rejected applications are in `applications/rejected/` +- **AND** withdrawn applications are in `applications/not-interested/` +- **AND** all folders use same naming convention (YYYY-MM-DD-Company-JobTitle) + +#### Scenario: Status field tracks current state + +- **WHEN** application exists in any folder +- **THEN** application.md contains Status field in Metadata section +- **AND** Status field accurately reflects current lifecycle state +- **AND** Archived states include timestamp of archival +- **AND** Status field format is: `- **Status**: [State] (Archived: [timestamp])` + +#### Scenario: Application structure preserved across lifecycle + +- **WHEN** application moves between lifecycle states +- **THEN** all files are preserved (application.md, generated documents) +- **AND** all folders are preserved (input/, attachments/) +- **AND** folder name remains unchanged +- **AND** only Status field in Metadata section is modified + +--- + +### Requirement: Archive Folder Support + +The system SHALL provide dedicated folders for archived applications organized by outcome. + +#### Scenario: Rejected applications folder + +- **WHEN** application is rejected by company +- **THEN** application is moved to `applications/rejected/` folder +- **AND** folder is created if it doesn't already exist +- **AND** folder contains applications rejected by companies + +#### Scenario: Not-interested applications folder + +- **WHEN** user decides not to pursue application +- **THEN** application is moved to `applications/not-interested/` folder +- **AND** folder is created if it doesn't already exist +- **AND** folder contains applications user withdrew from + +#### Scenario: Archive folders maintain chronological organization + +- **WHEN** multiple applications are archived +- **THEN** date prefix (YYYY-MM-DD) allows chronological sorting +- **AND** folders can be easily browsed by date +- **AND** organization matches pending folder structure + +--- + +### Requirement: Status Field Management + +The system SHALL maintain accurate Status field in application.md throughout lifecycle. + +#### Scenario: Status field exists in template + +- **WHEN** new application is created from template +- **THEN** Metadata section includes Status field +- **AND** Status field is formatted: `- **Status**: Draft` +- **AND** Status field is on line 12 of application.md + +#### Scenario: Status field is preserved during population + +- **WHEN** `/populate-application` analyzes documents +- **THEN** Status field in Metadata section is not modified +- **AND** user can manually update Status as needed +- **AND** Status field persists through multiple population runs + +#### Scenario: Status field is updated on archival + +- **WHEN** application is archived +- **THEN** Status field is updated with new state and timestamp +- **AND** old Status value is replaced (not appended) +- **AND** timestamp format is consistent (YYYY-MM-DD HH:MM) + +--- + +## MODIFIED Requirements + +### Requirement: Application Folder Structure + +The application folder structure SHALL include archive folders in addition to the pending folder for organizing applications by lifecycle state. + +#### Scenario: Complete folder hierarchy + +- **WHEN** application framework is in use +- **THEN** folder structure is: + ``` + applications/ + ├── pending/ # Active applications + ├── rejected/ # Rejected by company + └── not-interested/ # User withdrew + ``` +- **AND** each folder contains application subfolders with format: `YYYY-MM-DD-Company-JobTitle/` +- **AND** archive folders are created on-demand when first needed + +--- + +## Cross-References + +### Related Capabilities + +- **application-archiving** (NEW): Provides `/archive-application` command for moving applications to archive folders +- **applicant-profile**: Profile information is preserved in archived applications for future reference +- **cover-letter-generation**: Generated cover letters trigger safety checks during archiving +- **application-email**: Generated emails trigger safety checks during archiving +- **application-validation**: Validation ensures applications are complete, but archived applications may be incomplete + +### Integration Points + +- Archive folders created by `application-archiving` capability +- Status field updated by `application-archiving` capability +- Application folder structure maintained by both capabilities +- Generated document detection shared between capabilities + +--- + +## Technical Notes + +### Lifecycle State Diagram + +``` +[Created] ──/new-application──> [Draft (pending/)] + │ + ├──(user works on application) + ├──/populate-application + ├──/validate-application + ├──/write-cover-letter + ├──/write-application-email + ├──(user submits application) + │ + ├──/archive-application rejected + │ └─> [Rejected (rejected/)] + │ + └──/archive-application not-interested + └─> [Not Interested (not-interested/)] +``` + +### Status Field Values + +- **Draft**: Initial state, application being prepared +- **Rejected (Archived: [timestamp])**: Company rejected application +- **Not Interested (Archived: [timestamp])**: User decided not to pursue + +**Note**: Additional states may be used by user (e.g., "Submitted", "Interview Scheduled") but are not enforced by system. + +--- + +## Backwards Compatibility + +**No breaking changes:** +- Existing applications in `pending/` folder remain valid +- Archive folders are optional and created on-demand +- Status field already exists in template (line 12) +- No changes to existing command behavior + +**Forward compatible:** +- Old applications can be archived without modification +- New applications work with archiving from creation +- Archive structure supports future enhancements (e.g., accepted folder) + +--- + +## Validation + +This specification delta can be validated by: + +1. Running `openspec validate archive-applications --strict` +2. Verifying integration with application-archiving capability +3. Checking that existing application-management requirements still apply +4. Confirming no conflicts with other capabilities diff --git a/openspec/changes/archive-applications/tasks.md b/openspec/changes/archive-applications/tasks.md new file mode 100644 index 0000000..002bf25 --- /dev/null +++ b/openspec/changes/archive-applications/tasks.md @@ -0,0 +1,397 @@ +# Implementation Tasks: Archive Applications + +## Overview + +This document outlines the ordered list of tasks to implement the application archiving feature. Tasks are designed to deliver user-visible progress incrementally with validation at each step. + +## Task Sequence + +### Task 1: Create Archive Application Command File + +**Description:** Create the main command implementation file with complete procedural instructions for Claude Code. + +**Actions:** +1. Create file: `src/.claude/commands/archive-application.md` +2. Follow pattern from `write-cover-letter.md` and `write-application-email.md` +3. Include complete implementation logic in markdown format: + - Command purpose and overview + - Argument parsing (reason, application-name, flags) + - Location detection (auto-detect vs. explicit name) + - Safety checks for generated documents + - Status field update logic + - Directory creation + - File move operation + - Error handling for all scenarios + - Success messaging + +**Validation:** +- [ ] File exists and follows command pattern +- [ ] All scenarios from proposal are covered +- [ ] Error handling is comprehensive +- [ ] Help documentation is clear + +**Deliverable:** `src/.claude/commands/archive-application.md` (~500-700 lines) + +**Dependencies:** None + +--- + +### Task 2: Update Framework Documentation + +**Description:** Update `CLAUDE.md` to include archiving in the framework workflow. + +**Actions:** +1. Add new section "Archiving Applications" after "Application Management" section +2. Include: + - When to archive applications + - Command syntax and examples + - Safety check explanation + - Archive folder structure + - Integration with workflow +3. Update "Available Commands" list with `/archive-application` +4. Add archiving to workflow examples + +**Validation:** +- [ ] New section is clear and comprehensive +- [ ] Commands list includes archive command +- [ ] Examples are helpful and accurate +- [ ] Integration with existing workflow is explained + +**Deliverable:** Updated `src/CLAUDE.md` (~40 lines added) + +**Dependencies:** Task 1 (understand command functionality) + +--- + +### Task 3: Create Application Archiving Specification + +**Description:** Create formal OpenSpec specification for the archiving feature. + +**Actions:** +1. Create directory: `openspec/specs/application-archiving/` +2. Create file: `openspec/specs/application-archiving/spec.md` +3. Include requirements with scenarios for: + - Application Archiving Command + - Safety Warnings for Generated Documents + - Status and Timestamp Tracking + - Archive Folder Structure +4. Follow OpenSpec format: `## Requirements` → `### Requirement:` → `#### Scenario:` + +**Validation:** +- [ ] All proposal behaviors are captured as requirements +- [ ] Each requirement has clear scenarios +- [ ] Scenarios follow WHEN/THEN/AND format +- [ ] Spec validates with `openspec validate archive-applications` + +**Deliverable:** `openspec/specs/application-archiving/spec.md` (~150-200 lines) + +**Dependencies:** Task 1 (understand implementation details) + +--- + +### Task 4: Update Application Management Specification + +**Description:** Update existing spec to document application lifecycle including archival. + +**Actions:** +1. Open: `openspec/specs/application-management/spec.md` +2. Add new requirement: "Application Lifecycle Management" +3. Include scenarios for: + - Application states (Draft, Rejected, Not Interested) + - Folder organization by state (pending/, rejected/, not-interested/) + - Status field tracking through lifecycle + +**Validation:** +- [ ] Lifecycle states are clearly defined +- [ ] Folder organization is documented +- [ ] Integration with existing requirements is clear +- [ ] Spec validates with `openspec validate` + +**Deliverable:** Updated `openspec/specs/application-management/spec.md` (~30 lines added) + +**Dependencies:** Task 3 (understand new archiving spec) + +--- + +### Task 5: Verify Template Status Field + +**Description:** Verify that the application template has the Status field required for archiving. + +**Actions:** +1. Open: `src/.claude/templates/application-template.md` +2. Verify line 12 contains: `- **Status**: Draft` +3. Verify Status field is in Metadata section +4. Document finding (no changes needed if field exists) + +**Validation:** +- [ ] Status field exists at line 12 +- [ ] Field is in correct format: `- **Status**: Draft` +- [ ] Field is within Metadata section +- [ ] No changes needed (field already present) + +**Deliverable:** Verification confirmation (no file changes) + +**Dependencies:** None (verification task) + +--- + +### Task 6: Create Archive Folders (Test Setup) + +**Description:** Create initial archive folder structure for testing purposes. + +**Actions:** +1. Create directory: `src/applications/rejected/` +2. Create directory: `src/applications/not-interested/` +3. Add `.gitkeep` files to preserve empty directories in version control + +**Validation:** +- [ ] `src/applications/rejected/` exists +- [ ] `src/applications/not-interested/` exists +- [ ] Both directories are tracked in git +- [ ] Directories are ready for archiving operations + +**Deliverable:** Archive folder structure + +**Dependencies:** None + +**Note:** These folders will be created on-demand by the command, but creating them upfront ensures they're tracked in version control. + +--- + +### Task 7: Manual Testing - Basic Archiving + +**Description:** Test basic archiving functionality with simple application. + +**Test Cases:** +1. Create test application: `/new-application "TestCo - Test Role"` +2. Navigate to application folder +3. Run: `/archive-application rejected` +4. Verify: + - Application moved to `applications/rejected/` + - Status field updated with timestamp + - All files preserved (application.md, input/, attachments/) + +**Validation:** +- [ ] Application successfully moved +- [ ] Status field shows: `Rejected (Archived: [timestamp])` +- [ ] All folders and files intact +- [ ] Success message shows correct details + +**Deliverable:** Test results documentation + +**Dependencies:** Tasks 1-2 (command implementation and docs) + +--- + +### Task 8: Manual Testing - Safety Checks + +**Description:** Test safety warning functionality with generated documents. + +**Test Cases:** +1. Create test application with cover letter and email +2. Run: `/archive-application rejected` (without --force) +3. Verify warning message appears +4. Verify archiving is blocked +5. Run: `/archive-application rejected --force` +6. Verify archiving proceeds + +**Validation:** +- [ ] Warning appears when documents detected +- [ ] Warning lists all generated documents +- [ ] Archiving stops without --force +- [ ] --force flag bypasses warning +- [ ] Documents are preserved in archive + +**Deliverable:** Test results documentation + +**Dependencies:** Task 7 (basic functionality working) + +--- + +### Task 9: Manual Testing - Error Handling + +**Description:** Test error scenarios and messages. + +**Test Cases:** +1. Invalid reason: `/archive-application accepted` +2. Application not found: `/archive-application rejected NonExistent` +3. Not in application folder: Run from root without parameter +4. Already archived: Try to archive same application twice + +**Validation:** +- [ ] Invalid reason shows correct error with valid options +- [ ] Not found shows available applications +- [ ] Wrong location shows usage guidance +- [ ] Already archived shows helpful message +- [ ] All error messages are clear and actionable + +**Deliverable:** Test results documentation + +**Dependencies:** Task 7 (basic functionality working) + +--- + +### Task 10: Manual Testing - Auto-Detection + +**Description:** Test automatic application detection from current directory. + +**Test Cases:** +1. Create test application +2. Navigate INTO application folder: `cd applications/pending/[folder]/` +3. Run: `/archive-application not-interested` (no app name) +4. Verify correct application is detected and archived + +**Validation:** +- [ ] Auto-detection identifies correct application +- [ ] Archiving proceeds without application name parameter +- [ ] Success message shows detected application name +- [ ] Application moved to correct archive folder + +**Deliverable:** Test results documentation + +**Dependencies:** Task 7 (basic functionality working) + +--- + +### Task 11: OpenSpec Validation + +**Description:** Validate all OpenSpec specifications are correctly formatted. + +**Actions:** +1. Run: `openspec validate archive-applications --strict` +2. Resolve any validation errors +3. Run: `openspec validate` (validate entire project) +4. Ensure all specs pass validation + +**Validation:** +- [ ] `openspec validate archive-applications --strict` passes +- [ ] No formatting errors in proposal.md +- [ ] No formatting errors in spec files +- [ ] All requirements have at least one scenario + +**Deliverable:** Clean validation results + +**Dependencies:** Tasks 3-4 (all specs created) + +--- + +### Task 12: Documentation Review + +**Description:** Review all documentation for clarity, completeness, and accuracy. + +**Actions:** +1. Review `proposal.md` for completeness +2. Review `tasks.md` for task ordering and clarity +3. Review `archive-application.md` command for user-friendliness +4. Review `CLAUDE.md` updates for integration with existing docs +5. Review spec files for requirement coverage + +**Validation:** +- [ ] All documents are clear and well-organized +- [ ] No ambiguous or confusing sections +- [ ] Examples are helpful and accurate +- [ ] Error messages are user-friendly +- [ ] Integration with existing workflow is seamless + +**Deliverable:** Documentation review notes + +**Dependencies:** Tasks 1-4 (all documentation created) + +--- + +### Task 13: Final Integration Check + +**Description:** Verify archiving integrates smoothly with existing application workflow. + +**Test Workflow:** +1. Create complete application: `/new-application "FinalTest - Role"` +2. Populate: `/populate-application` (with documents in input/) +3. Validate: `/validate-application` +4. Generate cover letter: `/write-cover-letter` +5. Generate email: `/write-application-email` +6. Archive: `/archive-application rejected` + +**Validation:** +- [ ] All commands work in sequence +- [ ] Safety warning appears (cover letter and email detected) +- [ ] --force flag allows archiving +- [ ] All generated documents preserved in archive +- [ ] Workflow feels natural and intuitive + +**Deliverable:** End-to-end workflow validation + +**Dependencies:** All previous tasks (complete implementation) + +--- + +## Task Summary + +| Task | Description | Priority | Est. Time | Dependencies | +|------|-------------|----------|-----------|--------------| +| 1 | Create archive command file | P1 | 60 min | None | +| 2 | Update framework docs | P1 | 20 min | Task 1 | +| 3 | Create archiving spec | P1 | 30 min | Task 1 | +| 4 | Update management spec | P1 | 15 min | Task 3 | +| 5 | Verify template status field | P2 | 5 min | None | +| 6 | Create archive folders | P2 | 5 min | None | +| 7 | Test basic archiving | P1 | 15 min | Tasks 1-2 | +| 8 | Test safety checks | P1 | 15 min | Task 7 | +| 9 | Test error handling | P1 | 15 min | Task 7 | +| 10 | Test auto-detection | P2 | 10 min | Task 7 | +| 11 | OpenSpec validation | P1 | 10 min | Tasks 3-4 | +| 12 | Documentation review | P2 | 20 min | Tasks 1-4 | +| 13 | Final integration check | P1 | 20 min | All tasks | + +**Total Estimated Time:** ~4 hours + +## Parallelization Opportunities + +Tasks that can be done in parallel: +- Tasks 1, 5, 6 (independent) +- Tasks 3, 4 (both specs, can work simultaneously) +- Tasks 8, 9, 10 (all testing, can run concurrently) + +Critical path: Task 1 → Task 2 → Task 7 → Tasks 8-10 → Task 13 + +## Validation Checklist + +After all tasks complete, verify: + +- [ ] `/archive-application` command works from within application folder +- [ ] `/archive-application` command works with application name parameter +- [ ] Safety warnings appear when documents exist +- [ ] `--force` flag bypasses warnings +- [ ] Status field is updated with correct timestamp +- [ ] Applications move to correct archive folder +- [ ] All files and folders are preserved +- [ ] Error messages are clear and helpful +- [ ] OpenSpec validation passes +- [ ] Documentation is complete and accurate +- [ ] Integration with existing workflow is seamless + +## Rollback Plan + +If issues arise during implementation: + +1. **Command not working**: Comment out command file, revert CLAUDE.md changes +2. **Spec validation fails**: Fix spec formatting issues, re-validate +3. **File corruption**: Archive operations preserve originals, can restore from archive +4. **Integration issues**: Archive feature is additive, can be disabled without affecting other commands + +## Success Criteria + +Implementation is complete when: + +1. All tasks have passing validation +2. OpenSpec validation passes with `--strict` flag +3. All test scenarios pass +4. Documentation is clear and complete +5. Feature integrates smoothly with existing workflow +6. No breaking changes to existing functionality + +--- + +**Status:** Task list ready for implementation +**Total Tasks:** 13 +**Estimated Time:** ~4 hours +**Priority Distribution:** 9 P1, 4 P2 diff --git a/openspec/changes/fix-coverletter-template-path/proposal.md b/openspec/changes/archive/2026-01-12-fix-coverletter-template-path/proposal.md similarity index 100% rename from openspec/changes/fix-coverletter-template-path/proposal.md rename to openspec/changes/archive/2026-01-12-fix-coverletter-template-path/proposal.md diff --git a/openspec/changes/fix-coverletter-template-path/specs/cover-letter-pdf-conversion/spec.md b/openspec/changes/archive/2026-01-12-fix-coverletter-template-path/specs/cover-letter-pdf-conversion/spec.md similarity index 100% rename from openspec/changes/fix-coverletter-template-path/specs/cover-letter-pdf-conversion/spec.md rename to openspec/changes/archive/2026-01-12-fix-coverletter-template-path/specs/cover-letter-pdf-conversion/spec.md diff --git a/openspec/changes/fix-coverletter-template-path/tasks.md b/openspec/changes/archive/2026-01-12-fix-coverletter-template-path/tasks.md similarity index 100% rename from openspec/changes/fix-coverletter-template-path/tasks.md rename to openspec/changes/archive/2026-01-12-fix-coverletter-template-path/tasks.md