organize-workspace

Organize Workspace

HARD GATE — HARD GATE — Workspace structure must reflect domain structure. If the codebase feels disorganized, flag it. Disorganization != 'just a style thing;' it is a signal of domain misalignment.

Principles

• Read-only first: inventory and size (du, ls -la) before any change.
• Never delete or move without a numbered list and explicit user approval (item-level or "approve all").
• Prefer fd / ripgrep / find in that order; avoid blind rm -rf on vague globs.
• Do not touch .git/, node_modules/, venv/, .env*, or SSH keys; flag them only if the user asked about them.
• Confirm prompts in the user's language if they are not writing in English.

1. Establish scope

• Default: current project root (where the user is working) or the path they name.
• Record OS (macOS vs Linux) for ignore patterns (e.g. .DS_Store).

2. Classify candidates (scan)

Group findings under these buckets:

Bucket	Examples	Typical action
Logs & temp	*.log, logs/, tmp/, temp/, *.pid	Delete after confirm
Build / cache	dist/, build/, .next/, coverage/, .turbo/	Delete if rebuildable
Package caches	root .cache/, __pycache__/	Offer delete
Stray drafts	root-level *.md named draft, scratch, temp	User picks: delete, move to specs/, or keep
Duplicate / dump dirs	old/, backup/, copy/, *_backup	List + ask

Use quick size hints: du -sh per top-level dir; sort large items first.

3. Assets & data (organize, not only delete)

If the user wants organization:

1. Propose a single convention, e.g.:
   • assets/ — images, fonts, static media
   • data/ — JSON, CSV, fixtures, samples
   • specs/ — all planning and domain documents
2. For each cluster of loose files, suggest one target path and a short rationale.
3. Use git-aware moves when in a repo: git mv if tracked; otherwise mv and report.
4. Never move secrets or production DB dumps into docs/ or public assets/.

4. Present the plan

Output a table or numbered list:

• Path
• Kind (log / build / draft / asset / other)
• Approx size
• Proposed action: delete | move to … | keep

Ask: "Delete items 1–3? Move 4–5? Skip 6?"

5. Execute after approval

• Deletes: on macOS, prefer a Trash-capable tool (e.g. trash from Homebrew) if installed; else rm with paths echoed back.
• Moves: create dirs with mkdir -p first; one batch at a time.
• Verify: re-run listing on affected parents; if anything failed, report stderr.

6. Post-cleanup and .gitignore revision

Do this when the repo is under Git and the cleanup surfaced untracked noise:

1. Inventory ignore sources: root .gitignore, .git/info/exclude, any subpackage .gitignore files.
2. Map findings to rules: for each deleted or recurring artifact class, check whether a pattern already exists; note gaps.
3. Propose a patch: list only concrete changes — + add / - remove / ~ reword — with one-line why.
4. User must approve the exact diff before editing the file.
5. Verify: run git check-ignore -v <path> on 2–3 representative paths.

See REFERENCE.md for shell patterns, .gitignore mechanics, and safety checks.

<!-- story: e04s03 -->

---

clean-my-room — reference patterns

Optional commands for the agent. Adapt paths; dry-run before bulk delete.

Discover large top-level entries

du -sh ./* .[!.]* 2>/dev/null | sort -hr | head -30

Find common logs (respect .gitignore when using fd)

fd -t f '\.log$' . 2>/dev/null
fd 'npm-debug' . 2>/dev/null

Find build-like dirs (review list before rm -rf)

fd -t d '^(dist|build|out|target|\.next|coverage)$' . --max-depth 3 2>/dev/null

Stray markdown at repo root (heuristic)

ls -1 ./*.md 2>/dev/null
fd -t f '^(draft|scratch|untitled|TODO|notes)' . --max-depth 1 2>/dev/null

Git-safe moves

git status -sb
git check-ignore -v <path>   # was ignored?
# Tracked: git mv old new
# Untracked: mkdir -p … && mv old new

.gitignore revision (after cleanup)

Goal: stop regenerated junk from polluting git status, without hiding real source.

1. Read root .gitignore and, in monorepos, apps/*/.gitignore / packages/*/.gitignore as needed. Check .git/info/exclude for machine-only rules that should not be committed (keep personal noise there; don’t copy into shared .gitignore unless the team agrees).

2. Per-path checks (last match wins; shows which file defined the rule):

   git check-ignore -v path/to/artifact
   git status -u --ignored    # optional: see ignored names (noisy)
   

3. Pattern style

   • Leading / = relative to the .gitignore’s directory (e.g. /dist/ = only that folder at that level, not all nested dist unless intended).
   • ** for deep trees, e.g. **/*.log, when noise appears at many depths.
   • Negation (!) is tricky: later rules, parent dirs, and git add -f interact—prefer narrow positive ignores over ! unless you already use negation in that file.

4. Do not add rules that would ignore: application source, small JSON/YAML config the repo tracks, or !important assets. When unsure, run git check-ignore -v on a known good file that must stay tracked.

5. Tracked but should be ignored (user already committed build/ once): this skill does not silently fix history; flag git rm -r --cached <path> + .gitignore as a separate explicit step the user must approve.

6. Global excludes (optional heads-up for “why is this still ignored?”):

   git config --get core.excludesfile
   

Safety: never pass through these in automated deletes

• .git/, .svn/, .hg/
• node_modules/, vendor/, venv/, .venv/, __pypackages__/
• Files matching .env, .env.* (except .env.example if intentional)
• ~/.ssh, id_rsa*, *.pem inside project trees

Post-deploy / server-ish extras (name buckets to stack)

• Docker: dangling images/volumes (only if user asked for Docker cleanup; requires docker context).
• CI: *.log under build/, artifact dirs from previous runs.
• K8s: local *.kube, tmp kubeconfigs—list only; do not delete without confirmation.

Inspiration

• Same inventory → plan → confirm → act flow as post-deploy environment cleanup style workflows.
• Agent template public: honor Flow (draft) vs Stock (stable); do not “clean” user drafts from Flow without explicit approval.