
# 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.

---

# 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.
