PRD Example 15: CLI File Organizer

Difficulty: Intermediate | Project Type: CLI Tool | Time: 4-6 hours

---

Overview

What	A command-line tool that organizes files into folders by type or date
Who	Anyone with cluttered Downloads or Desktop folders
Why	Automates the tedious task of sorting files into organized folders

---

Core Features (MVP)

1. Organize by Type: organize ./Downloads --by-type → Moves files into Images/, Documents/, Videos/, etc.
2. Organize by Date: organize ./Downloads --by-date → Moves files into 2025/02/, 2025/01/, etc.
3. Dry Run: organize ./Downloads --dry-run → Shows what would happen without moving
4. Undo: organize --undo → Reverts last organization using log file

---

Non-Goals

Will NOT build:

• Duplicate file detection
• File renaming or deduplication
• Recursive subfolder organization
• Custom rules or configuration file
• GUI or interactive mode
• File content analysis (only extension-based)
• Cloud storage integration
• Scheduled/automatic organization

Will NOT use:

• External APIs
• Database
• File watching libraries
• Configuration files

---

Technical Constraints

Language	Go 1.21+
Framework	None (stdlib only)
Dependencies	None — stdlib only
Log File	~/.organize/history.json for undo
Testing	Go built-in testing
Code Style	gofmt, golint

---

Success Criteria

• [ ] --by-type creates folders: Images, Documents, Videos, Audio, Archives, Other
• [ ] --by-date creates folders: YYYY/MM format
• [ ] --dry-run shows plan without moving files
• [ ] --undo reverts last operation
• [ ] Handles filename conflicts (adds _1, _2, etc.)
• [ ] Skips hidden files and directories
• [ ] All tests pass

---

Implementation Phases

Phase 1: Project Setup & File Scanning

Goal: Set up project and scan directory

Tasks:

1. Create Go project with main.go
2. Implement directory scanning (non-recursive)
3. Define file type mappings (extension → category)
4. Parse command line arguments

Verification:

go run main.go ./Downloads --dry-run --by-type
# Output:
# Would move vacation.jpg → Images/vacation.jpg
# Would move report.pdf → Documents/report.pdf
# Would move song.mp3 → Audio/song.mp3
#
# 3 files would be organized (dry run)

Deliverables: main.go with scanning and dry-run

---

Phase 2: Organize by Type

Goal: Move files into category folders

Tasks:

1. Create category folders if not exist
2. Move files to appropriate folders
3. Handle filename conflicts
4. Log operations to history file

Verification:

go run main.go ./Downloads --by-type
# Output:
# Moved vacation.jpg → Images/vacation.jpg
# Moved report.pdf → Documents/report.pdf
#
# 2 files organized

ls ./Downloads/Images
# vacation.jpg

Deliverables: Working --by-type command

---

Phase 3: Organize by Date

Goal: Move files into date-based folders

Tasks:

1. Read file modification time
2. Create YYYY/MM folder structure
3. Move files to date folders
4. Log operations

Verification:

go run main.go ./Downloads --by-date
# Output:
# Moved vacation.jpg → 2025/02/vacation.jpg
# Moved old_doc.pdf → 2024/12/old_doc.pdf

ls ./Downloads/2025/02
# vacation.jpg

Deliverables: Working --by-date command

---

Phase 4: Undo & Testing

Goal: Implement undo and add tests

Tasks:

1. Read history file for last operation
2. Reverse all moves
3. Clear history entry after undo
4. Write Go tests for all features

Verification:

go run main.go --undo
# Output:
# Reverted: Images/vacation.jpg → vacation.jpg
# Reverted: Documents/report.pdf → report.pdf
#
# 2 files restored

go test ./...
# All tests pass

Deliverables: Complete CLI with tests

---

File Type Mappings

var categories = map[string][]string{
    "Images":    {".jpg", ".jpeg", ".png", ".gif", ".svg", ".webp"},
    "Documents": {".pdf", ".doc", ".docx", ".txt", ".xlsx", ".pptx"},
    "Videos":    {".mp4", ".mov", ".avi", ".mkv", ".webm"},
    "Audio":     {".mp3", ".wav", ".flac", ".aac", ".ogg"},
    "Archives":  {".zip", ".tar", ".gz", ".rar", ".7z"},
    "Code":      {".py", ".js", ".ts", ".go", ".rs", ".java"},
}

---

Agent Rules

Always	Ask First	Never
Skip hidden files (starting with .)	Before adding new categories	Delete any files
Handle filename conflicts safely	Before recursive organization	Modify file contents
Log all operations for undo	Before changing folder structure	Organize system directories
Show summary after operation		Require config file