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
- 参考文档references/stack-patterns.md2.4 KB
- 脚本references/verification-script.py3.9 KB
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:
.gitignoretailored to stackREADME.mdwith: 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
- Audit —
search_files(target='files') to list all files, identify stack - Create directories —
mkdir -pfor target structure - Move files —
mvinto new locations (preserve git history if tracked) - Add standard files —
.gitignore,README.md - 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 —
mvwithin repo keeps history;rm+cploses 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
.gitignoreexcluding build artifacts - [ ] Each project has
README.mdwith run commands - [ ] Source files organized under
src/,app/, orapps/ - [ ] 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 examplesreferences/verification-script.py— Python script to audit project structure compliance
04 同仓库更多 Skills
web-ui-verification
Verify web UIs via headless Chrome CDP, no vision needed.
★ 0
test-driven-development
TDD: enforce RED-GREEN-REFACTOR, tests before code.
★ 0
systematic-debugging
4-phase root cause debugging: understand bugs before fixing.
★ 0
spike
Throwaway experiments to validate an idea before build.
★ 0
simplify-code
Parallel 4-agent cleanup of recent code changes.
★ 0
scroll-driven-3d-websites
Scroll-scrubbed 3D promo sites (Three.js + GSAP).
★ 0