File Organization

File Organization

Use this skill when the real question is "what structure should this repo use next, and how do we improve it without creating a bigger mess?"

The job is to choose the lowest-complexity structure that fits, define the boundary rules, and give an incremental migration path when the repo already exists.

Read references/repo-shape-decision-guide.md before choosing a structure. Read references/migration-playbook.md when the repo is already messy. Read references/repo-type-patterns.md when the request spans frontend, backend, docs/ops, or game-development layouts.

When to use this skill

• Decide how to structure a frontend, backend, fullstack, docs, or game-development repo
• Choose between framework defaults, feature/domain folders, apps/ + packages/libs/, docs taxonomy, or engine-aware hybrid layouts
• Reorganize an existing repo whose folders no longer communicate ownership or intent
• Define naming and placement rules for code, docs, scripts, assets, tests, or packages
• Stop shared/, common/, misc/, helpers/, or utils/ junk drawers from spreading
• Plan an incremental reorganization instead of a risky all-at-once rewrite

When not to use this skill

• The main task is finding where something currently lives → use codebase-search
• The main task is scaffolding generators, task runners, hooks, or recurring commands → use workflow-automation
• The main task is Docker/devcontainers/toolchains/services needed to run the repo → use system-environment-setup
• The main task is frontend state ownership or store boundaries → use state-management
• The main task is shared UI primitives, tokens, or package boundaries inside the design system → use design-system
• The main task is game-production planning or milestone routing → use bmad-gds

Core idea

Good file organization is a decision ladder, not one canonical folder tree: 1. Keep framework or engine defaults first when they already solve the problem. 2. Escalate to feature/domain grouping when change locality matters more than technical layers. 3. Escalate to apps/ + packages/libs/ when multiple deployables or real shared packages appear. 4. Add naming rules, placement rules, and migration guardrails before inventing more folders. 5. Prefer incremental migrations unless the repo is small enough to restart safely.

Instructions

Step 1: Classify the repository before proposing structure

Normalize the request into this intake:

repo_structure_intake:
  repo_type: frontend-app | backend-service | fullstack-monorepo | docs-ops-repo | game-project | library-cli | mixed | unknown
  lifecycle: greenfield | growing | messy-existing | partial-reorg | unknown
  dominant_pressure:
    - route-sprawl
    - feature-sprawl
    - shared-folder-junk-drawer
    - ownership-unclear
    - docs-taxonomy-drift
    - asset-sprawl
    - too-many-top-level-folders
    - monorepo-boundary-confusion
    - unknown
  current_shape: framework-defaults | layer-first | feature-first | monorepo | hybrid | ad-hoc | unknown
  migration_tolerance: low | medium | high
  contributors: solo | small-team | multi-team | mixed-discipline
  constraints:
    - framework-routing-rules
    - engine-special-folders
    - generator-lock-in
    - import-path-stability
    - docs-url-stability
    - asset-pipeline-rules
    - unknown

If the request is vague, prefer the smallest reasonable interpretation and state the assumption.

Step 2: Choose one primary organization mode

Pick exactly one primary mode for the run:

1. framework-default mode — early framework/engine defaults still fit; add only small colocated boundaries. 2. feature/domain mode — one workflow touches UI/state/api/tests/docs together and layer-first folders are scattering the work. 3. workspace/monorepo mode — multiple deployables or reusable packages need explicit top-level separation. 4. docs-taxonomy mode — the repo is mostly documentation, runbooks, or knowledge assets and should be organized by reader task and content type. 5. engine-aware hybrid mode — the project must honor engine-required folders while still preserving ownership and naming rules.

Return the chosen mode explicitly before proposing folders.

Step 3: Define the boundary packet

For any chosen mode, return this packet:

structure_packet:
  primary_mode: framework-default | feature-domain | workspace-monorepo | docs-taxonomy | engine-aware-hybrid
  top_level_folders:
    - name: <folder>
      purpose: <why it exists>
      owner: <role/team/unknown>
  naming_rules:
    files: <rule>
    folders: <rule>
    shared_code: <rule>
  placement_rules:
    - "new route-specific code goes near the route"
    - "extract to shared only after proven reuse"
  anti_patterns_to_block:
    - <pattern>
  migration_scope: greenfield | incremental | targeted-reorg
  route_outs:
    - <adjacent skill if needed>

Do not stop at a folder tree. Explain why each boundary exists.

Step 4: Apply the repo-type pattern that fits

Use the references for detailed patterns. In the front door, keep only the routing decision:

• Frontend / meta-framework app → keep framework routing/layout conventions first, colocate route-specific code, and add feature folders only when components/ or hooks/ become dumping grounds.
• Backend service → keep framework/module conventions first, then group by domain/module when one workflow keeps crossing controllers/services/schemas/jobs unnecessarily.
• Fullstack / monorepo → keep apps/ + packages/libs/, extract shared code only after repeated reuse, and document ownership/public APIs.
• Docs / ops repo → organize by user need and document type; separate tutorials, runbooks, reference, and explanation when audiences differ.
• Game-development repo → respect engine-required roots and special folders, then add naming and ownership rules for scenes/assets/scripts/tools.

Step 5: Plan migration only if needed

If the repo already exists, prefer this order: 1. freeze the target vocabulary, 2. pick one hot path or one feature/domain, 3. move new work into the new shape before backfilling old code, 4. add compatibility notes or shims where needed, 5. clean the highest-confusion legacy buckets last.

Step 6: Guard against junk-drawer patterns

Always call out these failure modes if they appear:

• shared/, common/, misc/, helpers/, utils/ with unclear ownership
• barrels at every folder level
• too many top-level folders without distinct purpose
• packages extracted before a stable public API exists
• docs trees organized around org history instead of reader tasks
• game asset trees that ignore engine/tool constraints
• generated or cache folders treated like first-class source structure

Step 7: Produce the output in this order

1. Repository diagnosis — current shape, pressure, and constraints 2. Chosen organization mode — one sentence 3. Boundary packet — top-level folders, naming rules, placement rules, anti-patterns 4. Migration plan — only if the repo already exists 5. Route-outs — adjacent skills when the problem expands beyond structure

Output format

Repository diagnosis

• Repo type:
• Lifecycle:
• Main pressure:
• Constraints:

Recommended structure

Naming and placement rules

• Files:
• Folders:
• Shared code:
• Assets/docs/scripts:

Anti-patterns to block

• ...

Migration plan

1. ... 2. ... 3. ...

Route-outs

• ...

Examples

Example 1: Growing Next.js app with components/ sprawl

Input: “Our Next.js repo has components, hooks, lib, and utils, and no one knows where new checkout code belongs.”

Output direction: Keep App Router defaults, choose feature/domain mode only for high-churn product areas, shrink components/ to truly shared UI primitives, and route store-boundary questions to state-management.

Example 2: Fullstack monorepo with premature package extraction

Input: “We have three apps, six packages, duplicated helpers, and no clarity on what should stay shared.”

Output direction: Keep apps/ + packages/, collapse pseudo-shared packages that do not have stable public APIs, define extraction rules, and route generator/task-runner follow-up to workflow-automation.

Example 3: Docs repo with a giant mixed notes tree

Input: “Our docs repo has onboarding notes, runbooks, architecture docs, and user help all mixed together.”

Output direction: Choose docs-taxonomy mode, separate by reader task and document type, keep runbooks distinct from end-user help, and avoid one catch-all notes/ bucket.

Example 4: Unity repo with asset sprawl

Input: “Our Unity project has art, prefabs, scenes, tools, and scripts mixed together under Assets/.”

Output direction: Choose engine-aware hybrid mode, respect Unity special folders, separate scenes/prefabs/scripts/tools/content assets intentionally, and add naming/ownership rules for cross-discipline contributors.

Best practices

1. Start from framework or engine defaults before inventing custom top-level folders. 2. Organize by what changes together, not just by file type. 3. Extract shared code only after repeatable reuse is obvious. 4. Keep top-level folders few, named, and purposeful. 5. Treat naming and placement rules as part of the design, not optional polish. 6. Prefer incremental migrations over heroic restructures. 7. Document exceptions when the tree cannot fully explain the repo. 8. Respect engine/tooling constraints in game/content repositories.

References

• references/repo-shape-decision-guide.md
• references/migration-playbook.md
• references/repo-type-patterns.md
• Next.js Project Structure
• GitHub Well-Architected: Monorepos
• Diátaxis
• Unity: Best practices for organizing your project

Migration Playbook

Use this when the repo is already messy.

Goal

Improve structure without forcing a heroic rewrite.

Sequence

1. Name the target vocabulary

• top-level folders
• what counts as a feature/domain
• when code becomes shared
• naming conventions for files and folders

2. Pick one migration slice

• one feature
• one backend module
• one docs section
• one game system/content area

3. Move the hottest path first Prefer the area people edit every week, not the oldest dead zone.

4. Preserve stability while moving

• aliases or compatibility exports if needed
• small README notes for changed paths
• package/public-API guards if using workspaces

5. Freeze junk-drawer growth New code should stop entering misc/, common/, helpers/, utils/, or equivalent buckets unless they have an explicit owner and rule.

6. Backfill deliberately Clean old areas only after the new placement rules are already being followed.

Migration do/don't

Do

• move one boundary at a time
• publish simple placement rules
• track exceptions explicitly
• let old and new coexist temporarily when necessary

Don't

• rename everything in one PR unless the repo is tiny
• invent new shared folders just to avoid choosing an owner
• turn migration into a tooling rewrite unless that is the actual bottleneck
• confuse file movement with environment or deployment work

Signs the migration is working

• contributors know where the next file goes
• fewer files land in generic shared buckets
• route/domain changes stay locally scoped
• package extraction becomes rarer and more intentional
• repo docs describe the shape in a few lines, not a wall of exceptions

Repo Shape Decision Guide

Use this quick ladder before proposing a folder tree.

1. Start with the narrowest valid default

• Meta-framework frontend / fullstack app → keep framework routing/layout conventions first.
• Backend service → keep framework/module defaults first.
• Docs repo → organize by reader task and document type.
• Game repo → start from engine-required roots and special folders.

2. Escalate only when a clear pressure appears

3. Delay extraction of shared code

A folder/package becomes shared only when:

• reuse is proven across more than one area,
• its owner is identifiable,
• its public API is small enough to describe,
• moving it will not create a permanent junk drawer.

4. Prefer these top-level buckets

Use only the buckets the repo can explain clearly.

Common valid buckets

• app/ or src/app/ — route/layout entrypoints
• features/ — product or domain slices
• shared/ or ui/ — only truly shared primitives
• apps/ — deployable applications
• packages/ or libs/ — stable shared packages
• docs/ — documentation
• scripts/ — repo utilities and entrypoints
• tools/ — project tooling with clear ownership
• Assets/, Content/, Scenes/, Prefabs/ — game/content structures when engine conventions support them

5. Avoid these anti-patterns

• misc/, common/, helpers/, temp/ with no owner
• top-level folders whose names explain file type but not responsibility
• extracting packages before a stable boundary exists
• barrels at every folder level
• generated or cache folders treated like source architecture

6. Choose the migration scope

• Greenfield: define the target shape up front.
• Incremental: put new work in the new structure first.
• Targeted reorg: move one hot path or feature area; clean old buckets later.

Repo Type Patterns

Frontend / meta-framework app

Default first:

• framework routing/layout conventions
• route colocation
• small intentional shared UI layer

Escalate when:

• components/ and hooks/ stop communicating ownership
• feature work touches UI, state, tests, and data together

Backend service

Default first:

• framework/module/package conventions
• explicit homes for migrations, scripts, jobs, and operational docs

Escalate when:

• one module keeps crossing controllers/services/schemas/jobs unnecessarily
• a global common/ bucket starts owning domain logic

Fullstack monorepo

Default first:

• apps/ + packages/ / libs/
• shared code extracted only after repeated reuse
• docs/scripts/tooling placed as first-class peers when important

Escalate when:

• package boundaries no longer match ownership
• shared packages are mostly wrappers around one app's needs

Docs / ops repo

Default first:

• content organized by user task and document type
• runbooks, architecture notes, onboarding, and reference separated when audiences differ

Escalate when:

• readers cannot predict where a document belongs
• publishing history dominates the folder tree

Game-development repo

Default first:

• engine-required roots and special folders
• clear separation of scenes/levels, prefabs/assets, scripts/tools, and generated outputs
• naming and ownership rules for cross-discipline collaboration

Escalate when:

• asset sprawl makes ownership unclear
• feature/system grouping is needed on top of engine-required buckets

Boundary reminders

• codebase-search finds current files; it does not design structure.
• workflow-automation enforces or scaffolds a chosen structure; it does not choose the structure.
• system-environment-setup makes the repo runnable; it does not decide folder ownership.
• state-management and design-system own subsystem-specific structure inside a broader repo shape.