project-structure
Scannednpx machina-cli add skill tartinerlabs/skills/project-structure --openclawYou are a project structure expert. Infer the project's language variant (US/UK English) from existing commits, docs, and code, and match it in all output.
Read individual rule files in rules/ for detailed explanations and examples.
Rules Overview
| Rule | Impact | File |
|---|---|---|
| Colocation | HIGH | rules/colocation.md |
| Anti-patterns | HIGH | rules/anti-patterns.md |
| Feature-based grouping | MEDIUM | rules/feature-based.md |
| Layer-based grouping | MEDIUM | rules/layer-based.md |
| Framework structure | MEDIUM | rules/framework-structure.md |
Workflow
Step 1: Detect Project Type
Scan for project indicators to determine the appropriate organisation approach:
- Frontend SPA / Next.js / React → feature-based
- Backend API / Express / Fastify / Hono → layer-based
- Monorepo (apps/ + packages/) → hybrid
- Existing structure → respect and extend current patterns
Step 2: Audit
Check the existing structure against all rules. Report violations grouped by severity with directory paths.
Step 3: Recommend
Based on project type and existing patterns, recommend where new code should live. Always prioritise colocation.
Source
git clone https://github.com/tartinerlabs/skills/blob/main/skills/project-structure/SKILL.mdView on GitHub Overview
This skill helps you decide where code should live, organise files, and audit project structure. It emphasises colocation, sensible grouping, and avoiding directory anti-patterns to keep a scalable codebase.
How This Skill Works
It first detects the project type by scanning for indicators (frontend SPA/Next.js/React, backend API/Express/Fastify/Hono, or a monorepo). It then audits the repository against all rules (colocation, anti-patterns, feature-based grouping, layer-based grouping, framework structure) and reports violations by severity with directory paths. Finally, it generates recommendations that prioritise colocating new code and aligning with current patterns.
When to Use It
- Starting a new project and deciding where code should live (frontend, backend, or monorepo).
- Auditing an existing codebase to identify colocation opportunities and anti-patterns.
- Planning feature-based vs layer-based organisation for scalable growth.
- Migrating to a hybrid monorepo structure with apps/ and packages/.
- Enforcing consistency when projects use multiple frameworks (e.g., Next.js with NestJS).
Quick Start
- Step 1: Scan the repo to detect project type (frontend, backend, or monorepo).
- Step 2: Run the audit to identify colocation opportunities and anti-patterns.
- Step 3: Review and apply the recommendations, starting with colocating related code.
Best Practices
- Prioritise colocating related code into the same feature or domain.
- Audit against all rules: colocation, anti-patterns, feature-based, layer-based, and framework structure.
- Respect and extend the current structure rather than rewriting wholesale.
- Report violations with exact directory paths and severities.
- Refer to rules/ for detailed explanations and examples when in doubt.
Example Use Cases
- A Next.js app reorganises pages and components into a feature-based structure.
- An Express API project realigns services and routes by domain to support layer-based grouping.
- A monorepo transitions to a hybrid structure with apps/ and packages/ while sharing utilities.
- Auditing and removing deep nesting anti-patterns in a large legacy repo.
- A multi-framework project (Next.js + NestJS) aligns structure to framework-specific conventions.
