Skip to main content
skill CX Codex

organize · sethgammon — Claude Code skill: repository structure audit and fixes

organize — a skill that audits and corrects project structure: checks file placement, moves files to match conventions, updates imports. Leaves code inside files untouched.

MIT ★ 937 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What organize does

Detect identifies the project's convention (layer-based, feature-based, hybrid or flat) by scanning directories with the Glob tool. Audit checks every file against placement and naming rules, builds a move plan and waits for confirmation. Apply executes the moves, updates all import paths in dependent modules and barrels, then runs typecheck — new errors are not allowed.

Configuration is stored in .claude/harness.json under the organization key; the locked flag there enables a blocking enforcement hook. Monorepos are scanned per package root. If a file needs splitting or function extraction, the skill defers that to /refactor — it only moves and renames, leaving content intact.

The skill caps directory scans at 200 entries; for larger projects, it scans only the top three levels. Violations report current path, expected path, and the broken rule.

What it helps with

  • check files against the project's layout convention
  • move files to match placement rules with import updates
  • decide where a new module belongs
  • write the structure convention to config

Example prompts for the agent

  • Audit the project structure and propose a move plan
  • Where should UserProfile.tsx go?
  • Turn on blocking enforcement for placement rules — /organize --lock

How to install organize

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

This installs the whole citadel plugin with all its skills

2Skills CLI (Vercel)

npx skills add SethGammon/Citadel --skill organize -a claude-code

3Manually: put the files in place

~/.claude/skills/organize/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/organize/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about organize

How to install organize in Claude Code?

Run /plugin marketplace add SethGammon/Citadel, then /plugin install citadel@citadel-local. For other platforms use npx skills add SethGammon/Citadel --skill organize -a claude-code or npx skills add SethGammon/Citadel --skill organize -a codex.

What does organize do?

It detects the repository's structure convention, checks file placement against the rules, builds a move plan and executes it with import path updates. Does not change code inside files except for import paths.

How is organize different from /refactor?

organize moves and renames files without touching their content. In-file refactoring — extracting functions, renaming symbols, splitting components — is done by /refactor.

Source text

SKILL.md · MIT
---
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`, Citadel's shared config path for all runtimes including Codex. 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.

```json
{
  "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, 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---
- 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 -- undo moves with git checkout/revert
---
```

© SethGammon · MIT · SethGammon/Citadel

Similar skills

All skills for Code review and refactoring →

organize by other authors comes first.

From the same set55

The whole set →
cost See token usage and costs for sessions, campaigns, and time periods. Use it to check where spend is going and how quickly it is rising. CX Codex +1 ★ 937repo stars merge-review merge-review scans the fleet worktree merge queue, flags files touched by more than one branch, and suggests a merge order before anything lands in main. CX Codex +1 ★ 937repo stars deploy-steward deploy-steward serializes PR merges into main, tracks CI gates, triggers deploys, and files repair tasks when checks fail. CX Codex +1 ★ 937repo stars prd prd turns an app idea into a structured product requirements document, asking about decisions that affect its shape. Use it before handing a project plan to Archon. CX Codex +1 ★ 937repo stars create-app create-app — a skill for Claude Code and Codex that builds applications from a single prompt. It routes work across five distinct tiers, passing through PRD, architecture, and verified execution phases. CX Codex +1 ★ 937repo stars postmortem The postmortem skill reviews completed campaigns or incidents using project files, telemetry, and Git history. It shows what failed and which safeguards caught it. CX Codex +1 ★ 937repo stars map map generates a JSON index of a repository's files, exports, imports and dependency graph so an agent can locate relevant code without extra Glob or Grep calls. CX Codex +1 ★ 937repo stars phase-validator The phase-validator subagent for Claude Code compares phase handoff reports with exit conditions and returns a pass or fail verdict. It checks automated development pipelines. CX Codex ★ 937repo stars

Project sponsors

Companies that keep this analytics open