chore: archive fix-coverletter-template-path change
Archived completed OpenSpec change after successful deployment. The template path fix has been applied to specs and is now in production. Change archived as: 2026-01-12-fix-coverletter-template-path Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Claude Sonnet 4.5
@@ -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
|
||||
@@ -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)
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user