organize · diff
git:20260503.631b94d to git:20260611.3d0afc4
67 added, 347 removed. Audit A to A.
---
name: organize
description: >-
- Three-pass project health scan: architectural compliance (are source files in
- the right layers?), filesystem hygiene (loose files, misplaced assets, stale
- artifacts), and bloat detection (oversized files, binaries in git, compressible
- assets). Reports composite score. Also manages enforceable directory manifests
- and dynamic directory lifecycle.
+ Repository structure only: directory layout, file placement, naming
+ conventions, and where-does-this-belong decisions. Detects the project's
+ convention, audits files against it, and executes move plans with
+ import-path updates. Never changes code inside files beyond the import
+ updates a move forces; in-file restructuring is /refactor.
user-invocable: true
auto-trigger: false
trigger_keywords:
- organize
- directory structure
- folder structure
- project structure
- file organization
- organize directories
- organize files
- cleanup directories
- directory convention
- where should this go
- messy project
- - project health
- - bloat
- last-updated: 2026-03-28
+ last-updated: 2026-06-11
---
- # /organize -- Project Organization Health
+ # /organize -- Repository Structure
## Orientation
- **Use when:** Auditing whether source files are in the right architectural layers, detecting loose files and misplaced assets, or configuring directory manifests and cleanup policies for a project.
+ **Use when:** Deciding where a file belongs, auditing file placement against the project's conventions, running a naming-convention sweep, or moving files so the tree matches the declared layout.
- **Don't use when:** You want a structural map of code relationships and module dependencies (use `/map`), you're moving logic between modules (use `/refactor`), or you need to execute a single organizational task without a health audit (use `/marshal`).
+ **Don't use when:** You want a structural map of code relationships (use `/map`), you want to change code inside files (use `/refactor`), you need disk or artifact cleanup (use `/houseclean`), or you need a single known move executed (use `/refactor move`).
+ ## Boundary with /refactor
+
+ /organize changes where files live and what they are named. Changing code structure within files (extract, inline, split functions or components, rename symbols) is /refactor. The only in-file edits /organize makes are import-path updates forced by a move or rename. If an audit reveals a file that should be split or merged, recommend /refactor; do not do it here.
+
## Commands
| Command | Behavior |
|---|---|
- | `/organize` | Full flow: scan, detect, recommend, configure |
- | `/organize --audit` | Check current files against the manifest, report violations |
- | `/organize --cleanup` | Run dynamic directory cleanup based on TTL policy |
- | `/organize --show` | Display current organization manifest |
+ | `/organize` | Detect convention, audit placement, propose and execute a move plan |
+ | `/organize --audit` | Check current files against the manifest, report violations only |
+ | `/organize --show` | Display the current organization manifest |
+ | `/organize --lock` | Set `locked: true` so the enforcement hook blocks violations |
| `/organize --unlock` | Set `locked: false` so enforcement is advisory |
- | `/organize --lock` | Set `locked: true` so enforcement blocks violations |
+ | `/organize where does {file} go` | Single placement decision, no full audit |
## Protocol
- ### Step 1: CHECK -- Read Existing Configuration
-
- 1. Read `.claude/harness.json` and check for an `organization` key
- 2. **If `organization` exists and user ran bare `/organize`:**
- - Display current convention, root count, placement rule count, dynamic dir count
- - Ask: "Your organization manifest is already configured. Want to **audit** current
- compliance, **adjust** the rules, or **reconfigure** from scratch?"
- - Route based on answer: audit -> Step 6, adjust -> Step 4, reconfigure -> Step 2
- 3. **If `organization` exists and user ran `--audit`:** Jump to Step 6
- 4. **If `organization` exists and user ran `--cleanup`:** Jump to Step 7
- 5. **If no `organization` key:** Continue to Step 2
-
- ### Step 2: SCAN -- Three-Pass Project Analysis
-
- Every scan runs all three passes. A user running `/organize` gets the full picture.
-
- **Do NOT use `find` or `Get-ChildItem`** -- use the **Glob tool** and **Bash** (`git ls-files`, `du`, `wc`) for cross-platform compatibility.
-
- ---
-
- #### Pass 1: Architectural Compliance
-
- 1. Use the **Glob tool** with pattern `**/` to discover directories. Filter out:
- `node_modules`, `.git`, `.planning`, `.citadel`, `.claude`, `dist`, `build`,
- `__pycache__`, `.next`, `target`, `.venv`, `venv`.
- Cap at 200 directories. If too large, scan only top 3 levels.
- 2. Read `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, or equivalent for stack
- 3. Read harness.json for `language` and `framework` fields
- 4. Count files per directory to find the "heavy" areas
- 5. Check for existing convention signals:
- - `src/components/`, `src/hooks/`, `src/utils/` -> **layer-based**
- - `src/features/auth/`, `src/features/dashboard/` -> **feature-based**
- - `src/auth/components/`, `src/auth/hooks/` -> **hybrid**
- - Flat `src/` with no subdirectories -> **flat**
- - Mixed signals -> **custom** (needs user input)
- 6. If an organization manifest exists, check each placement rule against current files. Count compliant vs. violating files.
-
- Record findings:
- ```
- Detected: {convention}
- Confidence: {high|medium|low}
- Roots: [{path, purpose, file_count}]
- Signals: [{pattern, evidence, convention_match}]
- Anomalies: [{path, issue}]
- ```
-
- **Scoring:** `architecture_score = compliant_files / total_source_files * 100`.
- If no manifest exists, score is based on how consistently the detected convention is followed.
-
- ---
-
- #### Pass 2: Filesystem Hygiene
-
- 1. **Loose files in project root.** List every file in the project root. Expected root files:
- - Config: `package.json`, `tsconfig*.json`, `*.config.{js,ts,mjs,cjs}`, `.eslintrc*`,
- `.prettierrc*`, `babel.config.*`, `jest.config.*`, `vite.config.*`, `next.config.*`,
- `rollup.config.*`, `webpack.config.*`, `Cargo.toml`, `pyproject.toml`, `go.mod`,
- `Makefile`, `Dockerfile`, `docker-compose*.yml`, `.env*`, `.editorconfig`,
- `.gitignore`, `.gitattributes`, `.npmrc`, `.nvmrc`, `.node-version`, `.tool-versions`
- - Docs: `README*`, `LICENSE*`, `CHANGELOG*`, `CONTRIBUTING*`, `CLAUDE.md`,
- `QUICKSTART*`, `CODE_OF_CONDUCT*`, `SECURITY*`
- - CI/lock: `*.lock`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`,
- `Gemfile.lock`, `.github/`, `.husky/`
- - Plugin/harness: `.claude/`, `.planning/`, `.citadel/`, `hooks/`, `hooks_src/`,
- `skills/`, `agents/`, `scripts/`
- - Any file listed in `.gitignore`
-
- Everything else in root (images, PDFs, ZIPs, random scripts, stray source files) is a finding.
-
- 2. **Images and assets outside designated directories.** Glob for
- `**/*.{png,jpg,jpeg,gif,svg,ico,webp,mp4,mp3,wav,pdf}`. Check if they
- live under a recognized asset directory (`assets/`, `public/`, `static/`,
- `images/`, `img/`, `media/`, `docs/images/`, `src/assets/`). Files outside are findings.
-
- 3. **Large files (>1 MB).** Use `git ls-files -z | xargs -0 stat` or equivalent
- to find tracked files over 1 MB. Report each with path and size.
-
- 4. **Empty directories.** Glob for directories, check which contain zero files
- (excluding `.gitkeep`). Report as clutter.
-
- 5. **Stale files in active directories.** Files in `src/` not modified in 6+ months
- while siblings are active. Report as "potentially stale" -- advisory only.
-
- 6. **Duplicate filenames.** Scan for files with identical names in different directories.
- Flag for awareness.
-
- **Scoring:** Start at 100, deduct:
- - -2 per loose non-standard file in project root
- - -1 per misplaced asset file
- - -3 per large file (>1 MB) tracked in git
- - -1 per empty directory
- - -0.5 per potentially stale file (capped at -10)
- - -0.5 per duplicate filename (capped at -5)
-
- Floor at 0. `hygiene_score = max(0, 100 - deductions)`.
-
- ---
-
- #### Pass 3: Bloat Detection
-
- 1. **Project size vs. source size.**
- - Total tracked size: `git ls-files -z | xargs -0 stat` (sum sizes)
- - Source code size: same but filtered to `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.rs`,
- `.go`, `.java`, `.css`, `.scss`, `.html`, `.md`
- - Ratio: `source_bytes / total_bytes`. Healthy = >60%. Below 40% means non-source dominates.
-
- 2. **Largest files ranked.** List top 10 largest tracked files with sizes.
-
- 3. **Binary files in git.** Glob for:
- `*.{png,jpg,jpeg,gif,ico,webp,mp4,mp3,wav,woff,woff2,ttf,eot,zip,tar,gz,jar,dll,so,dylib,exe,bin,dat,db,sqlite,pdf}`.
- Check if each could be gitignored or moved to Git LFS. Report count and total size.
-
- 4. **Accidentally committed directories.** Check if any of these exist as tracked paths:
- `node_modules/`, `dist/`, `build/`, `.next/`, `target/`, `__pycache__/`, `.venv/`,
- `venv/`, `.cache/`, `.parcel-cache/`, `.turbo/`, `coverage/`. Any hit is a critical finding.
-
- 5. **Compressible assets.** PNGs over 500 KB, SVGs over 100 KB, any video/audio file.
-
- **Scoring:** Start at 100, deduct:
- - If source ratio <60%: -(60 - ratio)
- - -5 per accidentally committed build/dependency directory
- - -2 per binary file in git that should be gitignored or in LFS
- - -1 per compressible asset (PNG >500KB, SVG >100KB)
- - -3 per video/audio file tracked in git
-
- Floor at 0. `bloat_score = max(0, 100 - deductions)`.
-
- ---
-
- #### Composite Score
-
- ```
- composite_score = round(
- architecture_score * 0.40 +
- hygiene_score * 0.35 +
- bloat_score * 0.25
- )
- ```
-
- **Always report all four numbers.** Never report just the architecture score.
-
- ```
- === Project Health: {project_name} ===
-
- Architecture: {score}% -- source file placement, layer boundaries, test colocation
- Hygiene: {score}% -- loose files, misplaced assets, stale artifacts, empty dirs
- Bloat: {score}% -- project size ratio, binaries in git, compressible assets
- -------------------------------
- Overall: {composite}%
- ```
-
- Follow scores with the most actionable findings from each pass. Group by severity (critical first, advisory last). Cap at 10 findings per pass; note "and N more" if truncated.
-
- ### Step 3: RECOMMEND -- Present Options
-
- Present a tailored recommendation based on confidence level:
-
- **If confidence is HIGH:** Present the detected convention and its roots. Ask: [Accept], [Adjust], or [Show alternatives].
-
- **If confidence is MEDIUM:** Present the detected convention with anomaly count and 2-3 alternatives including reorganization cost (number of files to move). Ask: [1/2/3].
-
- **If confidence is LOW:** Present the four convention options (feature-based, layer-based, hybrid, flat) with a one-line best-for description each, plus [Custom]. Ask: [1/2/3/4/5].
+ ### Step 1: CHECK
- Wait for user response before proceeding.
+ Read `.claude/harness.json`. If an `organization` key exists, use its convention and placement rules; on bare `/organize`, ask whether to audit, adjust the rules, or reconfigure. If no key exists, continue to Step 2.
- ### Step 4: CONFIGURE -- Write the Organization Manifest
+ ### Step 2: DETECT
- **4a. Build the roots tree:**
+ Use the **Glob tool** (not `find` or `Get-ChildItem`) to discover directories. Filter out `node_modules`, `.git`, `.planning`, `.citadel`, `.claude`, `dist`, `build`, `__pycache__`, `.next`, `target`, `.venv`, `venv`. Cap at 200 directories; if larger, scan only the top 3 levels.
- For each detected root directory:
- ```json
- {
- "purpose": "short description of what belongs here",
- "children": { ... } // recursive, only if subdirectories have distinct purposes
- }
- ```
- Only go 2-3 levels deep.
+ Convention signals:
+ - `src/components/`, `src/hooks/`, `src/utils/` -> **layer-based**
+ - `src/features/auth/`, `src/features/dashboard/` -> **feature-based**
+ - `src/auth/components/`, `src/auth/hooks/` -> **hybrid**
+ - Flat `src/` with no subdirectories -> **flat**
+ - Mixed signals -> **custom** (ask the user which convention to adopt)
- **4b. Build placement rules:**
+ Record: convention, confidence (high/medium/low), roots with purposes, anomalies.
- Derive placement rules from the detected convention:
+ ### Step 3: AUDIT
- | Convention | Example Rules |
- |---|---|
- | Feature-based | `*.test.ts` -> colocated with source, `*.types.ts` -> colocated |
- | Layer-based | `*.test.ts` -> `__tests__/` or `tests/`, `*.types.ts` -> `types/` |
- | Hybrid | `*.test.ts` -> colocated within feature, `*.types.ts` -> `{feature}/types/` |
- | Flat | No placement rules |
+ Check every source file against the placement rules (manifest if present, detected convention otherwise). Also check naming: files or directories that break the dominant casing or suffix pattern of their siblings.
- For each rule:
- ```json
- {
- "glob": "*.test.{ts,tsx}",
- "rule": "colocated",
- "target": null,
- "reason": "Tests live next to the code they test"
- }
```
-
- Rule types:
- - `colocated` -- file must be in the same directory as its source
- - `sibling-dir` -- file must be in `target` directory adjacent to source
- - `root-dir` -- file must be under `target` from project root
- - `within-root` -- file must be under one of the declared roots
-
- Ask the user if they want to adjust any rules before writing.
-
- **4c. Build dynamic directory entries:**
-
- Scan for directories created dynamically by the harness or tools. For each:
- ```json
- { "path": ".planning/screenshots/", "scope": "session", "cleanup": "empty-on-expire" }
+ === Structure Audit: {project} ===
+ Convention: {convention} ({confidence})
+ Compliant: {N}/{M} source files
+ Violations:
+ {current_path} -> {expected_path} ({rule broken})
+ Naming:
+ {path}: {issue}
```
- Scopes: `session` | `campaign` | `task` | `permanent`
+ ### Step 4: PLAN
- Cleanup strategies: `empty-on-expire` | `archive-then-delete` | `delete` | `ignore`
+ For each violation, build a move plan before touching anything: source path -> destination path, every importer whose import path must change, and barrel/index files that need re-exports updated. Moves and renames only; never delete files with content. Present the plan and wait for confirmation.
- **4d. Set cleanup policy:**
+ ### Step 5: APPLY
- Ask the user:
- ```
- When dynamic directories expire, how should cleanup work?
- 1. Auto -- Clean up silently on session end
- 2. Prompt -- Show what would be cleaned and ask first
- 3. Manual -- Just report stale directories, don't touch them
- [1/2/3] (default: 2)
- ```
+ Execute confirmed moves, update all import paths referencing moved files, update barrels, then run the project's typecheck command (from harness.json). Zero new errors allowed. If a move fails typecheck for reasons beyond import paths, revert that single move and flag the file instead of editing its code.
- **4e. Write to harness.json:**
+ ### Step 6: CONFIGURE
- Read-modify-write. Merge the `organization` key. Do NOT overwrite other keys.
+ On first run or reconfigure, write the `organization` key to harness.json. Read-modify-write: preserve all other keys, and preserve any existing `dynamic`/`cleanupPolicy` entries this skill no longer manages.
```json
{
"organization": {
"convention": "layer",
- "roots": { ... },
- "placement": [ ... ],
- "dynamic": [ ... ],
- "cleanupPolicy": "prompt",
+ "roots": { "src": { "purpose": "application source" } },
+ "placement": [
+ { "glob": "*.test.{ts,tsx}", "rule": "colocated", "target": null, "reason": "tests live next to source" }
+ ],
"locked": false
}
}
```
- Set `locked: false` initially. Tell the user they can run `/organize --lock` once confident.
-
- ### Step 5: VERIFY -- Confirm the Manifest Works
-
- 1. Run a full three-pass audit (Step 6 logic) against the current codebase
- 2. Report all three scores plus composite
- 3. If composite < 60%: warn with top issues
- 4. If architecture > 80% but hygiene or bloat < 60%: call out the drag and note quick wins
- 5. Tell the user about `--lock`, `--audit`, and `--cleanup` commands
-
- ### Step 6: AUDIT -- Full Three-Pass Health Check
-
- Run all three passes from Step 2. Output the composite score block first:
-
- ```
- === Project Health: {project_name} ===
-
- Architecture: {score}%
- Hygiene: {score}%
- Bloat: {score}%
- -------------------------------
- Overall: {composite}%
-
- --- Architecture ({N} violations) ---
- {glob pattern} should be {rule}:
- - {violating_path} -> {expected_path}
-
- --- Hygiene ({N} findings) ---
- Loose files in project root:
- - {filename}
- Images outside asset directories:
- - {path} -> should be {target}
- Large files (>1 MB):
- - {path} ({size})
- Empty directories:
- - {path}
-
- --- Bloat ({N} findings) ---
- Source ratio: {ratio}% ({source_size} source / {total_size} total)
- Top 5 largest files:
- 1. {path} ({size})
- Binary files that could be gitignored:
- - {path} (generated/build output)
-
- --- Suggested Actions ---
- [Concrete fixes, quick wins first, larger reorganizations last]
-
- Run quick fixes (move misplaced files, delete empty dirs)? [y/n]
- ```
-
- If the user says yes, execute safe fixes (moves, empty dir removal).
- Never auto-delete files with content -- only move them or flag for manual review.
-
- ### Step 7: CLEANUP -- Prune Dynamic Directories
-
- Read the `dynamic` entries from the organization manifest.
-
- For each entry:
- 1. Check if the directory exists
- 2. Determine if expired based on scope:
- - `session`: check `.planning/telemetry/` for last session end timestamp. Files older than last session start are stale.
- - `campaign`: check `.planning/campaigns/` for associated campaign status. If `completed` or `parked`, contents are stale.
- - `task`: check if the task ID still exists.
- - `permanent`: skip
- 3. Apply the cleanup strategy for expired entries:
- - `empty-on-expire`: delete contents, keep directory
- - `archive-then-delete`: move to `.planning/archive/{YYYY-MM-DD}/`, then empty
- - `delete`: remove directory and contents (recreate if in PLANNING_DIRS)
- - `ignore`: report but don't touch
-
- **Respect cleanupPolicy:** `auto` executes silently; `prompt` asks before each category; `manual` lists stale dirs without modifying.
-
- Output:
- ```
- === Cleanup Report ===
- Scanned: {N} dynamic directories
- Stale: {M} directories ({total_size})
-
- {path} ({scope}-scoped, {N} files, {size})
- Strategy: {strategy}
- Action: {Cleaned | Would clean | Skipped}
-
- Summary: {N} directories cleaned, {M} archived, {K} skipped
- ```
+ Rule types: `colocated`, `sibling-dir`, `root-dir`, `within-root`. Set `locked: false` initially; `/organize --lock` turns on blocking enforcement via the organize-enforce hook.
## Fringe Cases
- - **`.planning/` does not exist:** Run `/do setup` first to initialize the harness state directory; then re-run.
- - **No directories found:** Skip scan, suggest flat convention.
- - **Monorepo detected** (multiple package.json): Scan each package root separately. Ask if organization should be per-package or repo-wide.
- - **User changes convention:** Warn about number of files to move. Do NOT auto-move without explicit confirmation.
- - **Conflict with existing rules:** If harness.json `protectedFiles` conflict with placement rules, warn and ask which takes precedence.
- - **Dynamic dir doesn't exist yet:** Keep the entry in the manifest. Don't warn about missing dynamic dirs.
- - **Archive directory grows large:** If `.planning/archive/` exceeds 50MB, warn and suggest manual pruning.
+ - **No directories found / empty project:** suggest flat convention; nothing to audit.
+ - **Monorepo (multiple package.json):** scan each package root separately; ask whether rules are per-package or repo-wide.
+ - **harness.json missing:** audit in advisory mode from the detected convention; offer to create the manifest.
+ - **User changes convention:** warn with the number of files that would move. Never mass-move without explicit confirmation.
+ - **Conflict with `protectedFiles`:** if protected files conflict with placement rules, warn and ask which takes precedence.
## Contextual Gates
- **Disclosure:** "Running project health scan. Phase 3 (cleanup) may move files — will confirm scope before executing."
- **Reversibility:** amber — may move files or rename directories in cleanup phase; undo with `git checkout -- .` or `git revert`
- **Trust gates:**
- - Any: run scan and view report (Phases 1-2)
- - Familiar (5+ sessions): Phase 3 file moves execute autonomously; novices should stop after Phase 2 (report only)
+ **Disclosure:** "Auditing repository structure. Moves execute only after you confirm the plan."
+ **Reversibility:** amber -- file moves and import-path updates; undo with `git checkout -- .` before commit or `git revert` after.
+ **Trust gates:** Any: detect and audit. Familiar (5+ sessions): confirmed move plans execute autonomously.
## Quality Gates
- - [ ] All three passes ran -- never skip a pass
- - [ ] All three scores plus composite reported
- - [ ] Project directory tree scanned (Step 2 completed or skipped with existing config)
- - [ ] User presented with options and made a choice (not auto-decided)
- - [ ] Organization manifest written to harness.json under `organization` key
- - [ ] Placement rules are specific (glob + rule + reason, no vague entries)
- - [ ] Dynamic directory entries have valid scope and cleanup strategy
- - [ ] User told about `--lock`, `--audit`, and `--cleanup` commands
- - [ ] No other harness.json keys modified during write
+ - [ ] Convention detected or read from the manifest before any audit verdicts
+ - [ ] Every violation lists current path, expected path, and the rule it breaks
+ - [ ] Move plan presented and confirmed before any file moves
+ - [ ] No in-file code edits beyond import-path updates; split/extract needs are deferred to /refactor
+ - [ ] Typecheck clean after moves (zero new errors)
+ - [ ] harness.json write preserves all keys outside `organization`
## Exit Protocol
```
---HANDOFF---
- - Health: {composite}% (Architecture {arch}%, Hygiene {hyg}%, Bloat {bloat}%)
- - Convention: {convention} applied to {project}
- - {N} roots, {M} placement rules, {K} dynamic directories configured
- - Top findings: {1-2 most impactful issues from hygiene/bloat passes}
+ - Structure: {convention}; {compliant}/{total} files compliant after changes
+ - Moves: {N} files moved, {M} import paths updated, 0 in-file refactors
+ - Deferred to /refactor: {split/extract recommendations, or "none"}
- Enforcement: {"advisory (unlocked)" | "blocking (locked)"}
- - Reversibility: amber — file moves undoable with `git checkout -- .`; harness.json changes undoable with `git revert`
- - Next: Run `/organize --lock` when confident, `/organize --audit` to recheck
+ - Reversibility: amber -- undo moves with git checkout/revert
---
```