Filesystem Organization and Relocation

Use when organizing or relocating filesystem content. Organize cluttered directories without breaking active runtimes, Git worktrees, scheduled jobs, project tooling, or path-based configuration. Prefer reversible moves over deletion and prove the resulting layout works.

When to Use

Use this skill when the user asks to clean up a home directory, consolidate scattered projects, reorganize a workspace, move repositories into a standard hierarchy, archive generated artifacts, or relocate linked Git worktrees. It is especially important when active agents, schedulers, virtual environments, or absolute path references may coexist with the clutter.

For a simple move of one ordinary file with no dependencies, this full workflow is unnecessary. For deletion or storage reclamation, pair it with explicit deletion approval and duplicate/cache analysis rather than assuming organization includes removal.

Core principles

1. Preserve operational paths first. A tidy directory is not worth breaking a running service, active worker, scheduled task, virtual environment, or configured workspace.
2. Classify before moving. Separate runtime/configuration, active projects, linked worktrees, generated artifacts, research, tools, archives, and genuinely disposable material.
3. Use subsystem-aware relocation. Git worktrees, package environments, databases, and managed workspaces must be moved with their owning tool when possible—not with a blind filesystem move.
4. Delete nothing implicitly. A request to “clean up” authorizes organization, not destruction. Obtain explicit approval before deleting duplicates, caches, or old artifacts.
5. Leave a manifest. Every move should be reversible and machine-readable.
6. Verify behavior, not just paths. Confirm destinations exist, old paths are absent, repositories remain valid, registrations point to the new locations, and protected processes remain alive.

Workflow

1. Inventory the target directory

Collect a shallow inventory before changing anything:

• visible and hidden entries;
• file type, size, modification time, and symlink target;
• directory sizes;
• Git repositories and linked-worktree relationships;
• running processes whose current working directory or command points into the target;
• scheduled jobs, service definitions, scripts, and configuration containing absolute paths;
• existing destination structure and filename conflicts.

Avoid recursively dumping huge trees into context. Use programmatic summaries and narrow searches.

2. Assign each entry a disposition

Class	Default action
Shell files, dot-config, credentials, agent state	Leave in place
Running application source/venv	Leave unless a coordinated restart is in scope
Active scheduler/worker root	Leave or update all dependents atomically
Standalone inactive repository	Move under Working/Projects/
Linked Git worktree	Move under a project-specific worktrees/ directory using Git
Generated receipts/prompts/metrics	Move under project artifacts/ or receipts/
Research/source captures	Move under Working/Research/<topic>/
Utilities and source checkouts	Move under Working/Tools/
Uncertain item	Leave in place and report why

Choose a conservative interpretation when dependency evidence is incomplete. A small set of justified operational roots is better than cosmetic symlinks or broken automation.

3. Check prerequisites and hazards

Before relocation:

• detect processes with cwd below candidate paths;
• inspect cron/job workdir, prompts, scripts, and absolute-path references;
• check Git status so uncommitted work is recognized and preserved;
• identify linked worktrees via git worktree list --porcelain and git rev-parse --git-dir;
• ensure destination paths do not already exist;
• preserve timestamps and avoid filename collision renames unless explicitly planned.

Do not infer that a repository is inactive merely because no process has it as cwd; scheduled jobs and orchestration state may still depend on its absolute path.

4. Execute in safe groups

Move low-risk loose files and standalone inactive directories first. Stop on any destination conflict.

For linked Git worktrees:

git -C /path/to/main-repo worktree move /old/worktree /new/worktree

Do not use raw mv for linked worktrees. git worktree move updates both the worktree’s .git pointer and the main repository’s registration. Dirty worktrees can normally be relocated safely, but preserve and later report their status.

If the main worktree itself must move, treat it as a separate migration: inspect every registered linked worktree, move the main repository, run the appropriate Git repair flow, and validate every worktree before declaring success. Prefer leaving an operational main repository in place unless the user explicitly wants that deeper migration.

5. Write a reversible manifest

Store a JSON or TSV manifest inside the destination root containing:

• operation description;
• exact from and to paths;
• category/kind;
• move count;
• protected paths intentionally left in place;
• deletion list, which should be empty unless deletion was separately approved.

The manifest is the undo source of truth. Do not rely only on prose in the chat.

6. Verify comprehensively

At minimum, check:

1. The target root now contains only expected entries.
2. Every manifest destination exists.
3. Every manifest source is absent.
4. Manifest counts match programmatic counts.
5. git worktree list --porcelain shows the new paths and no stale old paths.
6. git rev-parse --is-inside-work-tree succeeds in every registered worktree.
7. Relocated standalone repositories still resolve their top-level directory and remotes.
8. Protected services/processes are still running, or their exit is independently known to be normal.
9. Scheduled jobs or configuration that retained protected roots remain valid.

Never print credential-bearing remote URLs or config values during verification. Report only sanitized host/repository identifiers or boolean success.

Common pitfalls

• Blindly moving everything: runtime source trees and virtual environments may be referenced by live process command lines.
• Raw-moving linked worktrees: leaves stale absolute Git metadata.
• Treating historical logs as active dependencies: distinguish current job/config references from archived output.
• Creating compatibility symlinks everywhere: preserves visual clutter and can hide incomplete migrations. Use only when a verified consumer cannot yet be updated.
• Overwriting a populated destination: abort instead of auto-merging unrelated trees.
• Calling cleanup complete after mv: require count, path, Git, and process verification.
• Leaking secrets while checking remotes: sanitize output; success does not require displaying embedded credentials.

Reporting

Summarize the final top-level layout, counts moved by category, intentionally protected paths, deletion count, verification results, and manifest location. Keep the report concrete; do not list every moved file when the manifest already contains that detail.

References

• references/root-home-cleanup.md — validated example and checklist for cleaning a Unix root home containing active agents, Git worktrees, and project artifacts.

---

Supporting files: this skill's supporting files are held in the docsite at docs/15-skills/_support/operations/filesystem-organization-and-relocation/ — fetch them fresh from jknash/docsite main alongside this page. Source: jknash/hermes-shared-skills · branch hermes-jkdev001 @ 1d0d545c3970 · skills/operations/filesystem-organization-and-relocation/ · view source · Imported 2026-10-04. Supporting files (references, scripts) remain in the source repository.

version 1.0.0 · author Hermes Agent · license MIT.

Published by Muse · 2026-10-04.