AGENT SKILL

project-organization

Restructure project dirs by stack into standard layouts.

License 许可
MIT
最近更新
2026-08-16
Stars
★ 0
Forks
0

01 前言 Front Matter

name
project-organization
author
Hermes Agent
license
MIT
version
1.0.0
metadata
{ "hermes": { "tags": [ "project-structure", "cleanup", "standardization", "monorepo", "embedded", "mobile", "python", "node" ] } }
platforms
[ "linux", "macos" ]
description
Restructure project dirs by stack into standard layouts.

02 资源文件 2

03 SKILL.md 正文

Project Organization & Restructuring

Standardize project directory layouts by tech stack. Prefer restructuring in place over deletion — the user explicitly prefers "good structure" over archival.

When to Use

  • Project folders have flat or inconsistent layouts
  • Multiple projects need consistent structure before git init/commit
  • New project scaffold needed for a known stack
  • Cleanup of build artifacts, node_modules, venv, .pio from version control

Stack-Specific Structures

Electron / VS Code Extension (e.g., ghost-ide)

project/
├── src/
│   ├── main/           # Main process
│   ├── preload/        # Preload scripts
│   └── renderer/       # Renderer process (UI)
├── packages/           # Monorepo packages (tree-sitter, language-server)
├── resources/          # Icons, assets
├── .gitignore          # node_modules, dist, build, *.log, .env
├── package.json
└── README.md

Expo / React Native (e.g., olive-app)

project/
├── app/                # Expo Router file-based routing
│   ├── (tabs)/         # Tab layout group
│   ├── _layout.tsx     # Root layout
│   └── index.tsx       # Entry
├── src/
│   ├── components/     # Reusable UI components
│   ├── screens/        # Screen components
│   ├── navigation/     # Navigation config
│   ├── hooks/          # Custom hooks
│   ├── utils/          # Helpers
│   ├── data/           # Static data / mocks
│   └── theme/          # Design tokens
├── assets/             # Images, fonts
├── docs/               # DESIGN-SYSTEM.md, design references
├── .gitignore          # node_modules, .expo, dist, .vercel
├── package.json
├── tsconfig.json
└── README.md

Python CLI / Bot (e.g., olive-ai-starter-bot)

project/
├── src/
│   └── <package_name>/ # Importable package
│       ├── __init__.py
│       └── main.py     # Entry point
├── tests/              # pytest structure
├── docs/               # DEPLOY.md, architecture notes
├── .gitignore          # venv, __pycache__, *.pyc, .env
├── requirements.txt
├── .env.example
└── README.md

PlatformIO Embedded (e.g., trunx-math)

project/
├── src/                # Main source (main.cpp)
├── include/            # Headers (common/, drivers/)
├── lib/                # Private libraries
├── apps/               # Multi-app variants
│   ├── sets/
│   ├── logic/
│   └── functions/
├── docs/               # Hardware notes, wiring
├── .gitignore          # .pio, build, *.elf, *.bin, *.hex
├── platformio.ini
└── README.md           # Build commands per env

Node.js Config / Deployment (e.g., qm-ve-deploy)

project/
├── config/             # qm.config.jsonc, slack-app-manifest.yml
├── scripts/            # Deploy, migration scripts
├── docs/               # AGENTS.md, deployment.md
├── .gitignore          # node_modules, .env, package-lock.json
├── package.json
├── .env.example
└── README.md

Hardware Project (e.g., jifunze-device)

project/
├── hardware/           # PCB, enclosure, BOM, KiCad
├── software/           # Firmware, kiosk app
├── docs/               # Implementation plan, reports
├── .gitignore          # build_content.json, __pycache__
└── README.md

Standard Files to Ensure

Every project gets:

  • .gitignore tailored to stack
  • README.md with: purpose, structure, build/run commands, status
  • No build artifacts in version control (node_modules, venv, .pio, dist, build, *.log, .env, .DS_Store, package-lock.json)

Workflow

  1. Audit — search_files (target='files') to list all files, identify stack
  2. Create directories — mkdir -p for target structure
  3. Move files — mv into new locations (preserve git history if tracked)
  4. Add standard files — .gitignore, README.md
  5. Verify — search_files (target='files') again to confirm clean structure

Pitfalls

  • Don't delete — user prefers restructuring over archival. Only remove truly empty dirs (e.g., ghost-px).
  • Preserve git history — mv within repo keeps history; rm + cp loses it.
  • Don't commit generated files — .pio, node_modules, venv, dist, build, *.log, .env, .DS_Store, package-lock.json go in .gitignore.
  • README must be actionable — include exact build commands (e.g., pio run -e trunx-sets).

Verification Checklist

  • [ ] Each project has .gitignore excluding build artifacts
  • [ ] Each project has README.md with run commands
  • [ ] Source files organized under src/, app/, or apps/
  • [ ] Config/docs separated from source
  • [ ] No stray files at root (except config: package.json, platformio.ini, README.md, .gitignore)

References

  • references/stack-patterns.md — Detailed patterns per stack with examples
  • references/verification-script.py — Python script to audit project structure compliance

04 同仓库更多 Skills