---
description: "Scans the active workspace for disposable artifacts—logs, caches, stale build output, and stray draft markdown—and proposes consolidation of scattered assets. Produces a reviewable list, asks for explicit confirmation before any delete or move, and optionally revises .gitignore. Use when the user says \"clean my room\", \"organize workspace\", \"workspace cleanup\", \"remove temp files\", \"organize assets\", \"gitignore\", or wants a safe tidy pass."
alwaysApply: false
---

# 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](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

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

## Find common logs (respect `.gitignore` when using fd)

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

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

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

## Stray markdown at repo root (heuristic)

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

## Git-safe moves

```sh
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):

   ```sh
   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?”):

   ```sh
   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](https://mcpmarket.com/tools/skills/post-deploy-environment-cleanup) style workflows.
- [Agent template public](https://github.com/matsuni-kk/agent_template_public): honor **Flow** (draft) vs **Stock** (stable); do not “clean” user drafts from Flow without explicit approval.