/organize

name: organize
license: MIT
description: >-
  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
last-updated: 2026-06-11

/organize -- Repository Structure

Orientation

**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 (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` | 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 where does {file} go` | Single placement decision, no full audit |

Protocol

Step 1: CHECK

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 2: DETECT

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.

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)

Record: convention, confidence (high/medium/low), roots with purposes, anomalies.

Step 3: AUDIT

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.

=== Structure Audit: {project} ===
Convention: {convention} ({confidence})
Compliant: {N}/{M} source files
Violations:
  {current_path} -> {expected_path} ({rule broken})
Naming:
  {path}: {issue}

Step 4: PLAN

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.

Step 5: APPLY

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.

Step 6: CONFIGURE

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.

{
  "organization": {
    "convention": "layer",
    "roots": { "src": { "purpose": "application source" } },
    "placement": [
      { "glob": "*.test.{ts,tsx}", "rule": "colocated", "target": null, "reason": "tests live next to source" }
    ],
    "locked": false
  }
}

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

• **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:** "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

• [ ] Convention detected or read from the manifest before any audit verdicts
• [ ] Every violation lists current path, expect