Project Organization Patterns Skill

When to Use This Skill

Use this skill when implementing project organization patterns patterns in your codebase.

How to Use This Skill

Review the patterns and examples below
Apply the relevant patterns to your implementation
Follow the best practices outlined in this skill

Standardized directory structures, file organization, naming conventions, and automated project scaffolding.

Core Capabilities

Directory Structure - Standard project layout
File Organization - Logical file grouping
Naming Conventions - Consistent naming patterns
Configuration Management - Centralized configuration
Template Generation - Automated project scaffolding

Standard Directory Structure

project-root/
├── .github/                    # GitHub configuration
│   ├── workflows/              # CI/CD pipelines
│   ├── ISSUE_TEMPLATE/         # Issue templates
│   └── PULL_REQUEST_TEMPLATE.md
├── docs/                       # Documentation
│   ├── architecture/           # Architecture diagrams
│   ├── api/                    # API documentation
│   ├── guides/                 # User guides
│   └── adr/                    # Architecture Decision Records
├── src/                        # Source code
│   ├── api/                    # API routes
│   ├── services/               # Business logic
│   ├── models/                 # Data models
│   ├── utils/                  # Utilities
│   └── config/                 # Configuration
├── tests/                      # Test files
│   ├── unit/                   # Unit tests
│   ├── integration/            # Integration tests
│   ├── e2e/                    # End-to-end tests
│   └── fixtures/               # Test fixtures
├── scripts/                    # Automation scripts
│   ├── build.sh                # Build script
│   ├── deploy.sh               # Deployment script
│   └── setup.sh                # Setup script
├── config/                     # Configuration files
│   ├── development.json
│   ├── staging.json
│   └── production.json
├── .env.example                # Environment template
├── .gitignore                  # Git ignore rules
├── .eslintrc.json              # Linter configuration
├── .prettierrc                 # Formatter configuration
├── package.json                # Dependencies
├── tsconfig.json               # TypeScript config
├── README.md                   # Project documentation
├── CONTRIBUTING.md             # Contribution guidelines
├── LICENSE                     # License file
└── CHANGELOG.md                # Version changelog

Project Scaffolding Script

#!/usr/bin/env python3
"""
Automated project scaffolding with standardized structure.
"""

from pathlib import Path
from typing import List
import json

class ProjectScaffold:
    def __init__(self, project_name: str, template: str = "standard"):
        self.project_name = project_name
        self.template = template
        self.root = Path(project_name)

    def create_structure(self):
        """Create standard directory structure."""
        dirs = [
            ".github/workflows",
            ".github/ISSUE_TEMPLATE",
            "docs/architecture",
            "docs/api",
            "docs/guides",
            "docs/adr",
            "src/api",
            "src/services",
            "src/models",
            "src/utils",
            "src/config",
            "tests/unit",
            "tests/integration",
            "tests/e2e",
            "tests/fixtures",
            "scripts",
            "config"
        ]

        for dir_path in dirs:
            (self.root / dir_path).mkdir(parents=True, exist_ok=True)

        print(f"✅ Created directory structure for {self.project_name}")

    def create_config_files(self):
        """Generate configuration files."""
        # package.json
        package_json = {
            "name": self.project_name,
            "version": "0.1.0",
            "description": "",
            "main": "src/index.ts",
            "scripts": {
                "dev": "ts-node-dev src/index.ts",
                "build": "tsc",
                "test": "jest",
                "lint": "eslint src/**/*.ts",
                "format": "prettier --write src/**/*.ts"
            },
            "keywords": [],
            "author": "",
            "license": "MIT"
        }

        with open(self.root / "package.json", "w") as f:
            json.dump(package_json, f, indent=2)

        # tsconfig.json
        tsconfig = {
            "compilerOptions": {
                "target": "ES2020",
                "module": "commonjs",
                "lib": ["ES2020"],
                "outDir": "./dist",
                "rootDir": "./src",
                "strict": true,
                "esModuleInterop": true,
                "skipLibCheck": true,
                "forceConsistentCasingInFileNames": true
            },
            "include": ["src/**/*"],
            "exclude": ["node_modules", "dist", "tests"]
        }

        with open(self.root / "tsconfig.json", "w") as f:
            json.dump(tsconfig, f, indent=2)

        # .eslintrc.json
        eslintrc = {
            "env": {
                "node": True,
                "es2020": True
            },
            "extends": [
                "eslint:recommended",
                "plugin:@typescript-eslint/recommended"
            ],
            "parser": "@typescript-eslint/parser",
            "plugins": ["@typescript-eslint"],
            "rules": {
                "indent": ["error", 2],
                "quotes": ["error", "single"],
                "semi": ["error", "always"]
            }
        }

        with open(self.root / ".eslintrc.json", "w") as f:
            json.dump(eslintrc, f, indent=2)

        print("✅ Created configuration files")

    def create_documentation(self):
        """Generate initial documentation files."""
        readme = f"""# {self.project_name}

## Description

[Brief description of the project]

## Installation

```bash
npm install

Usage

npm run dev

Testing

npm test

Documentation

See docs/ for detailed documentation.

Contributing

See CONTRIBUTING.md for contribution guidelines.

License

MIT """

    (self.root / "README.md").write_text(readme)

    contributing = """# Contributing Guidelines

Code of Conduct

Be respectful and inclusive.

Development Process

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

Coding Standards

Follow the existing code style
Write tests for new features
Update documentation

Commit Messages

Follow conventional commits format:

feat: New feature
fix: Bug fix
docs: Documentation changes
refactor: Code refactoring

test: Test changes """

  (self.root / "CONTRIBUTING.md").write_text(contributing)

  changelog = f"""# Changelog

All notable changes to {self.project_name} will be documented in this file.

[Unreleased]

Added

Initial project setup

[0.1.0] - {Path(file).stat().st_mtime}

Added

Project scaffolding """
```
  (self.root / "CHANGELOG.md").write_text(changelog)

  print("✅ Created documentation files")
```
def create_gitignore(self): """Generate .gitignore file.""" gitignore = """# Dependencies node_modules/ .pnp .pnp.js

Testing

coverage/ *.log

Production

dist/ build/

Environment

.env .env.local .env.*.local

IDE

.vscode/ .idea/ *.swp *.swo

OS

.DS_Store Thumbs.db

Logs

logs/ .log npm-debug.log """

    (self.root / ".gitignore").write_text(gitignore)
    print("✅ Created .gitignore")

def create_github_templates(self):
    """Generate GitHub templates."""
    issue_template = """---

name: Bug Report about: Report a bug title: '[BUG] ' labels: bug assignees: ''

Describe the bug A clear and concise description of what the bug is.

To Reproduce Steps to reproduce the behavior: 1. 2. 3.

Expected behavior What you expected to happen.

Screenshots If applicable, add screenshots.

Environment:

OS: [e.g. macOS]
Node version: [e.g. 18.0.0]

Package version: [e.g. 1.0.0] """

  (self.root / ".github/ISSUE_TEMPLATE/bug_report.md").write_text(issue_template)

  pr_template = """## Description

[Describe what this PR does]

Type of Change

Bug fix
New feature
Breaking change
Documentation update

Checklist

Tests added/updated
Documentation updated
Changelog updated
Code follows style guidelines

Closes #[issue number] """

    (self.root / ".github/PULL_REQUEST_TEMPLATE.md").write_text(pr_template)

    print("✅ Created GitHub templates")

def scaffold(self):
    """Execute full scaffolding."""
    print(f"🚀 Scaffolding project: {self.project_name}\n")

    self.create_structure()
    self.create_config_files()
    self.create_documentation()
    self.create_gitignore()
    self.create_github_templates()

    print(f"\n✅ Project scaffolding complete!")
    print(f"   Created: {self.root.absolute()}")
    print(f"\n📝 Next steps:")
    print(f"   1. cd {self.project_name}")
    print(f"   2. npm install")
    print(f"   3. npm run dev")

CLI usage

if name == 'main': import sys

project_name = sys.argv[1] if len(sys.argv) > 1 else "my-project"
template = sys.argv[2] if len(sys.argv) > 2 else "standard"

scaffold = ProjectScaffold(project_name, template)
scaffold.scaffold()

## File Naming Conventions

```yaml
# naming-conventions.yaml

files:
  components: "PascalCase.tsx"
  utilities: "camelCase.ts"
  constants: "UPPER_SNAKE_CASE.ts"
  tests: "*.test.ts or *.spec.ts"
  types: "*.types.ts"
  config: "kebab-case.json"

directories:
  lowercase: true
  separator: "-"
  examples:
    - "api-routes"
    - "user-service"
    - "test-fixtures"

code:
  classes: "PascalCase"
  functions: "camelCase"
  constants: "UPPER_SNAKE_CASE"
  interfaces: "PascalCase (I prefix optional)"
  types: "PascalCase"

Usage Examples

Create New Project Structure

Apply project-organization-patterns skill to generate standardized project structure with configuration files

Organize Existing Project

Apply project-organization-patterns skill to reorganize existing codebase according to standard directory structure

Success Output

When successful, this skill MUST output:

✅ SKILL COMPLETE: project-organization-patterns

Completed:
- [x] Directory structure created
- [x] Configuration files generated
- [x] Documentation files initialized
- [x] Git ignore configured
- [x] GitHub templates created
- [x] Naming conventions applied

Outputs:
- Standardized project structure
- Configuration files (package.json, tsconfig.json, .eslintrc.json)
- Documentation files (README.md, CONTRIBUTING.md, CHANGELOG.md)
- Git configuration (.gitignore)
- GitHub templates (issue/PR templates)

Completion Checklist

Before marking this skill as complete, verify:

Failure Indicators

This skill has FAILED if:

❌ Required directories missing or incorrectly named
❌ Configuration files contain syntax errors
❌ README.md missing critical sections (installation/usage)
❌ .gitignore allows sensitive files (secrets, credentials)
❌ GitHub templates not created
❌ Naming conventions inconsistent
❌ Project structure doesn't match declared template type

When NOT to Use

Do NOT use this skill when:

Project already has established structure (use refactor-project-structure instead)
Quick prototype or throwaway code (excessive overhead)
Migrating existing project (use project-migration-patterns)
Non-standard framework with opinionated structure (e.g., Next.js, NestJS)
Monorepo setup needed (use monorepo-organization-patterns)
Legacy codebase modernization (use gradual-modernization-patterns)

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Creating unnecessary directories	Complexity overhead	Only create directories needed for current scope
Inconsistent naming conventions	Confusion	Document and enforce one standard (camelCase vs kebab-case)
Generic configuration files	Not project-specific	Customize configs for actual tech stack
Missing .gitignore entries	Committing secrets/artifacts	Use comprehensive .gitignore template
Skipping documentation	Poor onboarding	Always create README, CONTRIBUTING
Over-engineering for simple projects	Wasted effort	Match structure complexity to project size
Copy-paste without customization	Irrelevant files	Adapt template to actual needs

Principles

This skill embodies:

#2 Keep It Simple - Create only necessary structure, avoid over-engineering
#3 Separation of Concerns - Logical grouping (src/, tests/, docs/, config/)
#6 Clear, Understandable, Explainable - Intuitive directory hierarchy
#1 Recycle → Extend → Re-Use - Reusable templates for new projects

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Integration Points

project-structure-patterns - Project templates
git-workflow-patterns - Repository structure
documentation-patterns - Documentation organization

When to Use This Skill​

How to Use This Skill​

Core Capabilities​

Standard Directory Structure​

Project Scaffolding Script​

Usage​

Testing​

Documentation​

Contributing​

License​

Code of Conduct​

Development Process​

Coding Standards​

Commit Messages​

[Unreleased]​

Added​

[0.1.0] - {Path(file).stat().st_mtime}​

Added​

Testing

Production

Environment

IDE

OS

Logs

name: Bug Report about: Report a bug title: '[BUG] ' labels: bug assignees: ''​

Type of Change​

Checklist​

Related Issues​

CLI usage

Usage Examples​

Create New Project Structure​

Organize Existing Project​

Success Output​

Completion Checklist​

Failure Indicators​

When NOT to Use​

Anti-Patterns (Avoid)​

Principles​

Integration Points​

When to Use This Skill

How to Use This Skill

Core Capabilities

Standard Directory Structure

Project Scaffolding Script

Usage

Testing

Documentation

Contributing

License

Code of Conduct

Development Process

Coding Standards

Commit Messages

[Unreleased]

Added

[0.1.0] - {Path(file).stat().st_mtime}

Added

name: Bug Report about: Report a bug title: '[BUG] ' labels: bug assignees: ''

Type of Change

Checklist

Related Issues

Usage Examples

Create New Project Structure

Organize Existing Project

Success Output

Completion Checklist

Failure Indicators

When NOT to Use

Anti-Patterns (Avoid)

Principles

Integration Points