restructure

name	restructure
description	Extract misplaced code from any folder (backend or frontend) and move it to a properly-named folder that fits this project's existing conventions. Plan-first - reads the codebase to infer style, proposes a move-plan grounded in clean-code principles (Rule 15, Martin ch 11, McConnell ch 5), waits for a single confirmation, then moves files + rewrites imports atomically with git-aware history preservation. Handles backend layouts (services, repositories, controllers, route handlers), frontend layouts (components, pages, features, hooks, stores, ui/design-system), and mixed monorepos. Auto-chains from /cleancode:rewrite when a file split would benefit from cross-folder relocation. Triggers on phrases like "restructure my project", "move this code to a proper folder", "extract this from routes/", "my routes folder is doing too much", "where should this code live", "reorganize my folders", "split this across modules", "extract feature folder", "move business logic out of pages/components", "promote this shared code", or /cleancode:restructure.
argument-hint	[target folder, default=current dir]
allowed-tools	Read, Write, Edit, Glob, Grep, Bash
version	0.4.0

Clean Code Restructure

Move misplaced code into folders that fit this project's existing conventions. Plan-first, single-confirmation, with full rollback on failure.

This is the only cleancode skill that touches the directory tree. Every other skill (/refactor, /rewrite, /structure) operates within existing files. /restructure exists because Rule 15 (Clean Module & Folder Structure) needs an active fixer that respects the project's domain — it can't be auto-applied silently.

Core principle

Read the codebase first, then propose. Never apply a generic framework rule without first matching it against what this project actually does. The references/framework-hints.md cheatsheet is consulted for priors only when the codebase is genuinely ambiguous (new project, no clear pattern yet).

Triggers

"restructure my project" · "reorganize folders" · "move this code to a proper folder" · "extract this from routes/" · "my routes/ folder is doing too much" · "where should this code live" · "split this across modules" · "extract a feature folder" · "promote this shared component" · "move business logic out of pages/" · "my page file is too big" · "this component is duplicated across features" · /cleancode:restructure [folder].

Workflow

1. Discover the project's conventions

Before proposing anything, build a picture of how this project is organised. In parallel:

• Glob **/* (skip node_modules, dist, build, .git, .next, .nuxt, .svelte-kit, .turbo, coverage, __pycache__, .venv, vendor)
• Glob package.json, requirements.txt, Gemfile, go.mod, Cargo.toml, pom.xml, composer.json, pyproject.toml, *.csproj to identify language + ecosystem
• Glob framework config files (next.config.*, nuxt.config.*, svelte.config.*, astro.config.*, vite.config.*, angular.json, nest-cli.json, Gemfile, manage.py, pom.xml) — these are hints, not commands
• Glob for barrel files: **/index.{ts,tsx,js,jsx} — they reveal the project's intended public APIs
• Sample 5–10 representative files from each top-level folder via Read (limit 50 lines each) to infer the kind of content each folder contains

From this, identify:

Question	Why it matters
Top-level shape: package-by-feature (features/auth/, features/billing/) or package-by-layer (components/, services/, hooks/)?	Proposals must match the existing pattern. Don't impose features/ on a layered project, or vice versa.
File naming convention: kebab-case.ts, PascalCase.tsx, .service.ts / .repository.ts suffixes?	New files we create must match.
Are barrel index.ts files present? Where?	Indicates intentional public APIs — preserve them with re-exports.
What does this project actually call its folders? (lib/ vs utils/, routes/ vs pages/, ui/ vs components/)	Use the project's vocabulary in proposals.
Is this a monorepo? (apps/, packages/, pnpm-workspace.yaml, turbo.json)	Each subtree may have its own conventions; treat them independently.

If discovery returns nothing useful (very small project, brand-new repo), consult references/framework-hints.md for priors and say so explicitly in the plan: "Project is too new to infer conventions — using defaults from cheatsheet."

2. Classify the target

For the user's target (a folder, or the whole project if they didn't specify), Read each file and bucket it by what the code actually does. File extension is a hint; content is the truth.

Kinds:

• Page — declares a route (Next.js page.tsx, SvelteKit +page.svelte, Remix route.tsx); user-visible screen
• Route handler — server-only HTTP handler (+server.ts, route.ts, Express handler, Rails controller action)
• Controller — orchestrates request → service → response (NestJS controller, Spring @RestController)
• Service — business logic, transactions, orchestrates repositories
• Repository / DAO — data access only; talks to DB, ORM, or external API
• Domain model / entity — pure data shape with rules (no I/O)
• Component — UI element (React/Vue/Svelte/Angular component)
• Layout — page/screen scaffolding (layout.tsx, +layout.svelte)
• Hook / composable / use- function* — reactive UI logic
• Store / context / signal — UI state container
• API client / fetcher — frontend code that calls backend
• Util / helper — pure cross-cutting helpers
• Type / interface — type-only declaration
• Style — CSS/SCSS/Tailwind/CSS-in-JS extracted styles
• Test — unit / integration / e2e
• Config — env, settings, build config

3. Detect misplacements

A file is misplaced when any of these hold:

• It violates Rule 15 (Clean Module & Folder Structure):
  • Business logic inside a presentation layer (route handler, page, component)
  • Repeated cross-folder duplicates (e.g., the same Button.tsx copied into 3 feature folders)
  • Catch-all dump (utils/, helpers/, common/, shared/) accumulating dozens of unrelated files
  • Domain mixing (auth code scattered across controllers/, services/, models/, routes/ with no auth/ folder consolidating it)
• It breaks the project's own observed conventions (see §1)
• It exceeds size/cohesion thresholds that call for a split into multiple files in different folders (Rules 1, 6 — Single Responsibility)

Cite the specific principle for each finding (Rule 15, Martin ch 10/11, McConnell ch 5/6, or the Mayer principle).

4. Propose the move-plan

Output the plan in this exact format:

## Restructure plan — <target>

### Detected conventions
- Style: <package-by-feature | package-by-layer | mixed>
- Naming: <kebab-case | PascalCase | mixed>
- Barrel files: <yes/no, location>
- Framework signals: <Next App Router | SvelteKit | Express | none / new project>

### Proposed moves (N files)

| # | Source | Destination | Why |
|---|---|---|---|
| 1 | `routes/api/projects/+server.ts` (lines 45-180, the service block) | `src/lib/server/services/projects/project-service.ts` | Business logic doesn't belong in a route handler (Rule 15, Martin ch 11) |
| 2 | `routes/api/projects/+server.ts` (lines 200-260, DB queries) | `src/lib/server/repositories/project-repository.ts` | Data access should be isolated (SRP, Martin ch 10) |
| 3 | `src/features/billing/Button.tsx` | DELETE — duplicate of `src/ui/Button.tsx` | Cross-folder duplication (Rule 8 DRY) |

### Imports affected
- 7 files reference `routes/api/projects/+server.ts` exports → all rewritten
- 12 files reference `src/features/billing/Button.tsx` → rewritten to `src/ui/Button.tsx`

### Barrel re-exports proposed
- `src/lib/server/services/projects/index.ts` (NEW) re-exports `ProjectService` so callers needn't change deep imports

### Rollback strategy
- Git repo detected → all moves via `git mv`; rollback = `git restore -SW .`
- Or: non-git → backup before each move; manual rollback instructions provided

Apply this plan? [y/N]

5. Single confirmation

Wait for user response. Do nothing if they say no, ask questions, or want to amend the plan. If they amend, regenerate the plan and re-confirm.

6. Execute atomically

Order of operations:

1. Pre-flight checks
   • Confirm .git/ exists (or user passed --force-non-git)
   • Confirm no destination paths already exist (no overwrites)
   • Confirm working tree is clean (or warn loudly that uncommitted changes exist)
2. Move files
   • Git repo: git mv <source> <destination> for each
   • Non-git: mv <source> <destination>; record originals for rollback
3. Rewrite imports
   • Use Grep to find every reference to the old path
   • Use Edit to replace each import string (only static import / from / require / export … from patterns)
   • Skip and report dynamic imports (import(variable), string-concat paths) for manual review
4. Create barrel files (if proposed)
5. Verify atomic completion — if any step failed, abort and rollback

On any failure: git restore -SW . (git repo) or restore from backup (non-git), then report which step failed and why.

7. Verify

After successful execution:

• If tsconfig.json exists: run npx tsc --noEmit and report
• If package.json has scripts.typecheck: run npm run typecheck and report
• If package.json has scripts.test: suggest the user run it (don't run automatically — tests can be slow)
• If neither: suggest /cleancode:analyze <target> to verify no new violations

Print final summary:

✓ Moved N files
✓ Rewrote M imports across K files
✓ Created J barrel re-exports
✓ Type check: PASSED | FAILED (details)
Suggested next: npm test, /cleancode:analyze <target>, /cleancode:health

Ground rules

• Always read the codebase first. Never propose moves based on cheatsheet alone.
• NEVER move a file without explicit user confirmation.
• NEVER use rm. Only git mv (git repo) or mv (fallback). Files must end up at their destination — no deletions.
• If any import rewrite fails, abort the whole batch. Roll back via git restore -SW . or restored backup. Report the failed file and let the user decide.
• Prefer barrel re-exports when a file's public API is imported from many places — preserves callers, avoids touching every file.
• Respect the project's existing style. If it uses features/<name>/, propose into feature folders. If it's layered, match the layers. Don't impose a style the project isn't already using.
• Skip dynamic imports. Only rewrite static import x from '...', require('...'), export … from '...' patterns. List dynamic imports and string-concat paths in the report for manual review.
• Per-subtree detection in monorepos. A repo with apps/web/ + apps/api/ gets two independent restructuring contexts.
• Cite the principle for every move. Reference Rule 15, Martin chapter, or McConnell chapter so the user understands the why.
• Don't fight the language. Go's flat packages, Rails' MVC, Java's src/main/java/com/... are conventions for a reason. See references/framework-hints.md.

When /cleancode:rewrite chains here

/rewrite invokes /restructure when its split-plan reveals files that belong elsewhere. In that case:

• The chain provides the specific files and proposed destinations as input.
• Skip the discovery step (already done by /rewrite).
• Go directly to step 4 (propose move-plan) with the inherited context.

What this skill does NOT do

• Rename files within their existing folder (use /cleancode:refactor or /cleancode:rewrite)
• Apply design patterns (Strategy/Factory/Command/State) within a class (use /cleancode:structure)
• Fix in-file violations (long functions, deep nesting, bad names) (use /cleancode:refactor / /cleancode:rewrite)
• Touch dependencies, build configs, or CI files
• Move tests independently — tests follow the code they test

Reference files

• references/folder-structure-principles.md — distilled from Martin / McConnell / Mayer + Rule 15
• references/frontend-patterns.md — feature folders, atomic design, page-file bloat, co-location vs promotion, hooks/stores placement
• references/backend-patterns.md — layered, hexagonal, feature modules, catch-all antipatterns
• references/framework-hints.md — cheatsheet for SvelteKit / Next / Remix / Nuxt / Astro / NestJS / Express / Rails / etc.; consulted only when the project's own style is ambiguous
• examples/before-after-restructure.md — three worked examples (Next.js page-file bloat, SvelteKit fat route handler, React cross-feature duplication) showing exactly what the skill proposes and how it cites the rules