---
name: project-structure-architect
description: Use when starting, expanding, refactoring, or organizing any software, web, game, app, plugin, UX, data, or repository project. Prevents monolithic files by planning maintainable folder/file structure, edit locality, documentation, repo hygiene, and future expansion. Do not trigger for explicitly requested one-off single-file deliverables unless the user asks for maintainability or future growth.
---

# Project Structure Architect Skill

## Purpose

Prevent project debt before it begins. Before building or expanding a project, create a maintainable structure that supports the current slice **and** the likely future project.

This skill is especially important when the user says any of the following:

- "make a game"
- "build a web app"
- "start a project"
- "create a plugin"
- "make this scalable"
- "this is phase one"
- "future expansion"
- "north star vision"
- "refactor this giant file"
- "organize this repo"
- "split this up"
- "don't cram everything into one file"

## Core rule

**Do not cram an expandable project into one giant file.**

For expandable projects, entry files should orchestrate. They should not contain every system, entity, style, asset rule, database rule, UI behavior, and future feature.

Use one-file output only when the user explicitly requests a self-contained single-file deliverable, such as a pasteable HTML prototype, small standalone demo, codepen-style example, or shareable artifact. If the request is ambiguous and likely to become a project, default to modular structure.

## Next-skill routing before structure

Before designing folders, check whether another skill owns the project domain:

- Creative, story, manuscript, TTRPG, publishing, rights, or game-world work:
  `creative-project-router`.
- Marketing, launch, social, or current community-signal work:
  `marketing-strategy-operator`, `social-content-studio`, or
  `current-social-research`.
- Public messaging, stakeholder trust, portfolio framing, or proof narrative:
  `communication-story-crafter`.
- UX/frontend/shareable layout, visual QA, screenshots, or media-heavy artifacts:
  `frontend-ux`, `visual-asset-integration`, or `design-taste-gate`.
- Browser games, video-game concepts, board/card games, or playtest systems:
  `develop-web-game`, `game-designer`, or `board-game-design`.
- Local MCPs, data tools, ChatGPT apps, or app/tooling scaffolds:
  `local-data-mcp-builder`, `local-mcp-debugging`, or `chatgpt-apps`.
- Skill ecosystem changes: `skill-authoring`.
- Mac storage, runtime, or mounted-volume placement: `mac-environment-conventions`.

Use only the next skill needed for the current output. Do not load a whole
family just because a project touches the domain.

## First decision: classify the deliverable

Before creating files, classify the work:

| Classification | Use when | Structure expectation |
|---|---|---|
| One-off artifact | User explicitly asks for a single HTML/file/demo/shareable snippet | One file is allowed; use clear sections and comments. |
| Prototype likely to grow | User asks for a game/app/site/plugin but scope is small | Light modular scaffold. Avoid heavy architecture, but split core concerns. |
| Expandable project | User gives a north star, roadmap, feature set, project repo, or future-facing goal | Create folder structure first; split by concern and/or feature. |
| Existing monolith | A file is large, tangled, or hard to edit | Propose staged refactor before changing behavior. |
| Multi-project/monorepo | Multiple apps/packages/plugins/shared code | Use `apps/`, `packages/`, `tools/`, `docs/`, and boundary rules. |

Ask at most one clarification only if essential:  
**"Should this be a single-file deliverable, or should I structure it as an expandable project?"**

If the user's wording implies expansion, do not ask. Proceed with an expandable structure.

## Required behavior before coding

For new expandable projects:

1. Identify the current slice and the north-star direction.
2. Propose or create a simple folder/file map.
3. Separate responsibilities by edit locality:
   - bootstrapping / entry
   - configuration / constants
   - domain logic
   - UI / presentation
   - styles
   - data / persistence
   - assets
   - tests
   - documentation
4. Create a `README.md` and, when useful, `docs/project-map.md`.
5. Keep `main`, `index`, `App`, or equivalent entry files thin.
6. Add TODOs only in appropriate roadmap/docs files, not scattered through implementation.
7. Preserve user velocity: do not over-engineer folders that do not yet help.

For existing projects:

1. Inspect current layout.
2. Identify monoliths, mixed concerns, duplicated config, generated-file pollution, and unclear asset/data placement.
3. If a large refactor is needed, make a staged plan before editing.
4. Make small, behavior-preserving moves first.
5. Update imports and tests after each stage.

## Heuristics

These are practical guardrails, not laws:

- New files over ~300–500 lines deserve a split review.
- Files over ~800 lines should have an explicit reason to remain large.
- Files over ~1,500 lines are likely harming maintainability unless generated or data-only.
- Files over ~5,000 lines are a refactor target unless explicitly one-off/generated.
- Prefer a few useful folders over many empty "architecture theater" folders.
- Prefer stable names over clever names.
- Prefer feature/domain grouping when future edits will be feature-focused.
- Prefer type/layer grouping when the project is tiny or framework conventions expect it.
- Keep generated files, cache files, build outputs, and third-party assets separate from source.

## Module quality lens

When refactoring or expanding code, prefer deep modules: a small, stable front
door with meaningful behavior behind it. Avoid shallow modules that only rename,
forward, or scatter one concept across several files.

Use this quick test:

- **Interface clarity:** Can a future editor tell where to make the change?
- **Locality:** Does a feature change mostly touch one obvious area?
- **Leverage:** Does the module hide real complexity, or only add ceremony?
- **Deletion test:** If this layer disappeared, would the code become simpler?
- **Adapter rule:** One hypothetical integration does not justify an adapter;
  two real integrations often do.
- **Vocabulary:** Are domain names consistent across UI, data, tests, docs, and
  errors?

If the answer is weak, improve structure before adding more behavior.

## Web/app default

For an expandable web project, avoid cramming HTML, CSS, and JS into one file unless explicitly requested.

Typical light scaffold:

```text
project/
  README.md
  package.json
  index.html
  src/
    main.js
    app/
    components/
    styles/
    assets/
    config/
    utils/
  docs/
    project-map.md
  tests/
```

For React/Next/Vite/framework projects, follow framework conventions first, then apply separation rules.

## Three.js/game default

For a Three.js or browser game, `src/main.js` should initialize and hand off. It should not contain the whole game.

Recommended scaffold:

```text
src/
  main.js                 # startup only
  core/
    Game.js
    Renderer.js
    Loop.js
    AssetLoader.js
  scenes/
    MainScene.js
  entities/
    Player.js
    Enemy.js
  systems/
    InputSystem.js
    PhysicsSystem.js
    CollisionSystem.js
    SpawnSystem.js
  ui/
    HUD.js
  audio/
    AudioManager.js
  config/
    constants.js
    controls.js
  utils/
assets/
  models/
  textures/
  audio/
  fonts/
docs/
  project-map.md
  roadmap.md
```

## Game engine defaults

- Unity: document naming conventions and folder structure. Common groupings include `Scripts/`, `Scenes/`, `Prefabs/`, `Art/`, `Materials/`, `Audio/`, `UI/`, `Editor/`, and feature folders.
- Godot: use `snake_case` for folder/file names except C# scripts; use `PascalCase` for node names.
- Unreal: establish asset naming early; use engine directories correctly; do not mix generated/cache/build outputs with source/content.

## Database/data default

For any project with persistence:

```text
db/
  migrations/
  schema/
  seeds/
  queries/
  docs/
```

Rules:

- Do not hide schema decisions in app logic.
- Use migrations for schema changes.
- Keep seed/demo data separate from production-like data.
- Document entity relationships and any denormalization.
- Use schemas/namespaces when they clarify ownership, logical groups, or third-party integration boundaries.

## Documentation default

Use docs to reduce future token cost and developer confusion:

```text
docs/
  project-map.md
  roadmap.md
  architecture/
    adr/
  how-to/
  reference/
  research/
```

Prefer short, living docs over sprawling manuals. Put decisions in ADRs when they affect structure, dependencies, interfaces, persistence, deployment, or non-functional requirements.

## Codebase understanding default

Before a large refactor, repo onboarding pass, project rescue, or request for an
interactive codebase graph, create or update a static `docs/project-map.md`
first. It should name:

- main entrypoints and what starts the app/tool
- domain terms and core concepts
- important folders and ownership boundaries
- data flows, external services, and persistence points
- high-risk dependencies, generated files, caches, and runtime assumptions
- where a future feature, test, asset, or MCP/tool hook should go
- guided reading order for a newcomer: start here, then inspect these files,
  then run these checks
- business or product flows when the codebase has domain logic, not only
  technical layers
- diff-impact notes: which folders or contracts are most likely to be affected
  by a proposed change

Do not jump straight to a graph dashboard, MCP import, or visual explorer unless
the static map leaves a specific unanswered question that the runtime view would
answer. Treat interactive graph tooling as a later, security-reviewed
enhancement, not the first response to "help me understand this repo."

For large or unfamiliar repos, add a short `Onboarding Packet` section to
`docs/project-map.md`:

```markdown
## Onboarding Packet

- First files to read:
- Core concepts:
- Main runtime commands:
- Safe checks:
- Risky commands or install steps:
- Common change paths:
- Open questions:
```

## Integration with other skills

When this skill is installed alongside game, web app, Mac app, plugin, UX, database, or project-manager skills, those skills should reference this one before creating or expanding file structures.

### Change packet structure

For implementation-affecting changes that need traceability, use the local
OpenSpec-inspired packet shape before touching files:

```text
changes/<change-slug>/
  .change-packet.json
  proposal.md
  specs/<capability>/spec.md
  design.md
  tasks.md
  verification.md
```

The `prd-strategist` helper can create it:

```bash
python3 /Users/jonathanhobson/.codex/skills/prd-strategist/scripts/create_change_packet.py \
  "<change name>" --output-root ./changes --capability "<capability-name>"
```

Keep this scaffold lightweight. Do not add a new spec system to a repo when a
single issue, PR description, or inline checklist is enough.

### AI-built app checkup lens

When a user says an AI-built app has become messy, fragile, or scary to change,
apply the Vibe Check structure lens:

- make or confirm a safety snapshot first when the repo supports it
- inspect entrypoints, project map, and the scary workflow before proposing a
  rewrite
- look for "one thing, one place" violations: repeated logic, scattered state,
  duplicated validation, or drifting names
- prefer modules with a simple front door and real work inside
- remove middleman layers that only forward calls and do not earn their keep
- fix one structural problem at a time and verify behavior after each move
- update `docs/project-map.md` or an ADR-style note when names, ownership, or
  structure changes

Suggested cross-reference sentence:

> Before creating or expanding project files, consult the `project-structure-architect` skill. Do not build expandable games, apps, websites, plugins, UX systems, or data projects as monolithic single-file implementations unless the user explicitly requests a one-off single-file deliverable.

## Done criteria

A project setup or refactor is not done until:

- the current slice works,
- the file map is understandable,
- future expansion has an obvious place to go,
- entry files are thin,
- docs or README explain the structure,
- generated/cache/build files are separated or ignored,
- tests/checks are added or documented when relevant,
- the main modules have clear front doors and earned boundaries,
- the final response explains what was created and why.
