desktop-cleanup

<Workflow - Desktop Cleanup description="Review desktop, propose folder architecture, execute moves with sign-off" tools=[folder_list, folder_create, file_move, file_delete, run_python, create_scheduled_agent] triggers=["when user asks to clean/organise/tidy/declutter their desktop"]>

1. [Agent] Detect the Desktop path using run_python (Path.home() / "Desktop") and call folder_list on it. Capture the full listing of files and subfolders. If the path is inaccessible, inform the user and stop. If fails: If the Desktop cannot be located or listed, ask the user to provide the Desktop path, and stop if none is given.

2. [Agent] Using run_python, check the last access time (os.stat st_atime) of every loose file. Classify each file as:

   • "Recent" (accessed within last 14 days) - these will NOT be moved
   • "Stale" (not accessed in 14+ days) - these are cleanup candidates Also separate out:
   • Existing subfolders (potential destinations)
   • .lnk files and desktop.ini (untouchable, always ignored)
   • Temp lock files (~$ prefix) - deletion candidates

   If fewer than 5 stale loose files exist, tell the user "Desktop looks tidy, nothing to do!" and stop. If fails: If access times cannot be read, retry using modification time (st_mtime) and note this to the user; if that also fails, report the error and stop.

3. [Ask user] Present a REVIEW of the current Desktop state:

   • Total loose files count
   • Files flagged as "current work" (recent access) with their last-accessed dates - these will stay
   • Stale files grouped into logical categories using extensions, name patterns, and context:
     • Work documents (spreadsheets, reports, operational docs)
     • AI/Tech projects (skills, agents, code projects, FDS documents)
     • Presentations and events
     • Scripts and development files (.py, .js, .html, .vbs)
     • Media files (.mp4, .jpg, .png, .gif)
     • Personal items
     • Temp/delete candidates (~$ lock files, duplicate downloads)
   • Existing subfolders already on the Desktop

   Ask the user to confirm the categorisation is correct, or adjust categories. If fails: If the user does not respond or the categorisation is unclear, re-present the review and ask them to confirm or adjust before continuing.

4. [Ask user] Based on the confirmed categories and existing subfolders, propose a FOLDER ARCHITECTURE:

   • Which existing folders will receive files (and which files go where)
   • Any new folders to create (with proposed names)
   • Files that will remain on the Desktop (recent/current work)
   • Files proposed for deletion (only ~$ temp files)

   Present this as a clear table. Offer a decision card:

   • "Approve architecture"
   • "Suggest changes"

   If the user suggests changes, revise and re-present until approved. If fails: If no clear decision is given, re-ask the user to approve the architecture or specify changes before proceeding.

5. [Ask user] With the architecture approved, present the specific file moves for sign-off:

   • List each file and its destination
   • Group by destination folder for readability
   • Highlight any potential name conflicts

   Offer a decision card:

   • "Execute all moves"
   • "Let me pick which ones"

   If "Let me pick", present each group individually for approve/skip. If fails: If the user does not sign off, re-present the move list and ask them to approve all or pick specific moves before executing.

6. [Agent] Execute the approved plan:

   • Create any new folders first (folder_create)
   • Move approved files in batch (file_move for each)
   • Delete approved ~$ temp files (file_delete)
   • If any move fails (locked file, conflict), skip it and log the failure If fails: If folder creation or a move fails, skip the affected file, record the reason (locked, conflict, or error), and continue with the remaining approved actions.

7. [Agent] Present a final summary:

   • Files moved (count and destinations)
   • Files deleted
   • Files skipped (with reason: locked, conflict, or user-skipped)
   • Files left as current work (with note they were recently accessed)
   • Remaining loose file count on Desktop If fails: If any action's result cannot be determined, report the actions whose outcome is unknown and ask the user to verify the Desktop state.

8. [Ask user] If this is the first run (no existing weekly schedule detected), offer to set up a recurring weekly cleanup:

   • "Want me to run this automatically once a week?"
   • Decision card: "Yes, schedule weekly" / "No thanks"
   • If yes, use create_scheduled_agent to set up a weekly schedule (suggest Monday morning). The scheduled run should use the same skill and present findings via the activity feed for review rather than auto-moving files.
   • If no, skip silently. If fails: If scheduling cannot be set up or the user does not respond, skip the schedule and report that the cleanup completed without a recurring run.

</Workflow - Desktop Cleanup>

Overview

Scans the user's Desktop folder, identifies loose files, checks recency (files accessed in the last 2 weeks stay as current work), categorises stale files, proposes a folder architecture for approval, and executes moves with user sign-off at each stage. On first run, offers to schedule itself weekly.

Workflow

See the structured workflow above within Instructions.

Output

A tidy Desktop with stale files grouped into approved folders and recently-accessed files left in place as current work. The user receives a summary of all actions taken, and an optional weekly schedule for ongoing tidiness.

Lessons Learned

Do

• Check file access times to identify current work before proposing moves
• Discover existing folders at runtime before proposing destinations
• Present the review, then architecture, then moves as three distinct approval stages
• Group independent file_move calls for speed
• Fall back to st_mtime if st_atime appears unreliable (all identical timestamps)

Don't

• Don't move recently-accessed files, they are likely current work
• Don't move .lnk shortcut files or desktop.ini
• Don't delete anything except ~$ temp lock files, and only with approval
• Don't rename files, only move them
• Don't assume folder names exist from prior runs
• Don't collapse the three approval gates into one
• Don't auto-move files in a scheduled run. Scheduled runs should only report findings for user review.

Common Failures

• File locked by another application: skip it, report to user
• Destination already contains a same-named file: alert user, don't overwrite
• Desktop path detection fails (rare): fall back to asking the user for the path
• Access time unreliable (NTFS setting): fall back to modification time

When to Ask the User

• After the initial review (confirm categorisation)
• After proposing folder architecture (approve or adjust)
• Before executing moves (final sign-off)
• When a file doesn't clearly fit any category
• When there's a name conflict in the destination folder
• When offering to schedule (never auto-create a schedule without approval)