Agent Skills Framework Extension

Project Structure Patterns Skill

When to Use This Skill

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

How to Use This Skill

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

Production-ready project templates, architecture patterns, and automated scaffolding for full-stack, microservices, and monorepo structures.

Core Capabilities

1. Template Library - Pre-configured project templates
2. Architecture Patterns - Clean Architecture, Hexagonal, MVC
3. Monorepo Setup - Multi-package repository structure
4. Microservices - Service-based architecture scaffolding
5. Full-Stack Templates - Frontend + Backend integration

Full-Stack Template (React + Node.js)

#!/usr/bin/env python3
"""
Full-stack project template generator.
Creates React frontend + Node.js backend + shared types.
"""

from pathlib import Path
import json

class FullStackTemplate:
    def __init__(self, project_name: str):
        self.project_name = project_name
        self.root = Path(project_name)

    def create_monorepo_structure(self):
        """Create monorepo with frontend, backend, and shared packages."""
        dirs = [
            "packages/frontend/src/components",
            "packages/frontend/src/pages",
            "packages/frontend/src/hooks",
            "packages/frontend/src/utils",
            "packages/frontend/public",
            "packages/backend/src/api/routes",
            "packages/backend/src/api/controllers",
            "packages/backend/src/services",
            "packages/backend/src/models",
            "packages/backend/src/middleware",
            "packages/backend/src/config",
            "packages/shared/src/types",
            "packages/shared/src/validators",
            "docs/api",
            "scripts"
        ]

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

    def create_root_config(self):
        """Create root-level configuration."""
        # Root package.json
        package_json = {
            "name": f"{self.project_name}-monorepo",
            "private": True,
            "workspaces": [
                "packages/*"
            ],
            "scripts": {
                "dev": "concurrently \"npm run dev:frontend\" \"npm run dev:backend\"",
                "dev:frontend": "npm run dev --workspace=frontend",
                "dev:backend": "npm run dev --workspace=backend",
                "build": "npm run build --workspaces",
                "test": "npm run test --workspaces",
                "lint": "npm run lint --workspaces"
            },
            "devDependencies": {
                "concurrently": "^8.0.0",
                "typescript": "^5.0.0"
            }
        }

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

        # TypeScript config
        tsconfig = {
            "compilerOptions": {
                "target": "ES2020",
                "module": "commonjs",
                "lib": ["ES2020"],
                "moduleResolution": "node",
                "esModuleInterop": True,
                "skipLibCheck": True,
                "strict": True,
                "declaration": True,
                "declarationMap": True,
                "sourceMap": True
            }
        }

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

    def create_frontend_package(self):
        """Create React frontend package."""
        package_json = {
            "name": "frontend",
            "version": "0.1.0",
            "private": True,
            "scripts": {
                "dev": "vite",
                "build": "tsc && vite build",
                "lint": "eslint src --ext ts,tsx",
                "test": "vitest"
            },
            "dependencies": {
                "react": "^18.0.0",
                "react-dom": "^18.0.0",
                "react-router-dom": "^6.0.0",
                "shared": "workspace:*"
            },
            "devDependencies": {
                "@types/react": "^18.0.0",
                "@vitejs/plugin-react": "^4.0.0",
                "vite": "^4.0.0",
                "vitest": "^0.34.0"
            }
        }

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

        # Vite config
        vite_config = """import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  server: {
    port: 3000,
    proxy: {
      '/api': 'http://localhost:8000'
    }
  }
});
"""
        (frontend_path / "vite.config.ts").write_text(vite_config)

        # Sample component
        app_tsx = """import React from 'react';
import { User } from 'shared/types';

export const App: React.FC = () => {
  return (
    <div>
      <h1>Welcome to {self.project_name}</h1>
    </div>
  );
};
""".format(self=self)
        (frontend_path / "src/App.tsx").write_text(app_tsx)

    def create_backend_package(self):
        """Create Node.js backend package."""
        package_json = {
            "name": "backend",
            "version": "0.1.0",
            "private": True,
            "scripts": {
                "dev": "ts-node-dev --respawn src/index.ts",
                "build": "tsc",
                "start": "node dist/index.js",
                "test": "jest",
                "lint": "eslint src --ext ts"
            },
            "dependencies": {
                "express": "^4.18.0",
                "cors": "^2.8.0",
                "dotenv": "^16.0.0",
                "shared": "workspace:*"
            },
            "devDependencies": {
                "@types/express": "^4.17.0",
                "@types/cors": "^2.8.0",
                "ts-node-dev": "^2.0.0"
            }
        }

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

        # Server entry point
        index_ts = """import express from 'express';
import cors from 'cors';
import dotenv from 'dotenv';
import { apiRouter } from './api/routes';

dotenv.config();

const app = express();
const PORT = process.env.PORT || 8000;

app.use(cors());
app.use(express.json());

app.use('/api', apiRouter);

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});
"""
        (backend_path / "src/index.ts").write_text(index_ts)

        # API routes
        routes_ts = """import { Router } from 'express';

export const apiRouter = Router();

apiRouter.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

apiRouter.get('/users', (req, res) => {
  res.json({ users: [] });
});
"""
        (backend_path / "src/api/routes/index.ts").write_text(routes_ts)

    def create_shared_package(self):
        """Create shared types package."""
        package_json = {
            "name": "shared",
            "version": "0.1.0",
            "private": True,
            "main": "dist/index.js",
            "types": "dist/index.d.ts",
            "scripts": {
                "build": "tsc",
                "dev": "tsc --watch"
            }
        }

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

        # Shared types
        types_ts = """export interface User {
  id: string;
  name: string;
  email: string;
  createdAt: Date;
}

export interface ApiResponse<T> {
  data: T;
  error?: string;
}
"""
        (shared_path / "src/types/index.ts").write_text(types_ts)

        # Index
        (shared_path / "src/index.ts").write_text('export * from "./types";\n')

    def create_docker_setup(self):
        """Create Docker configuration."""
        # Frontend Dockerfile
        frontend_dockerfile = """FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
COPY packages/frontend/package*.json ./packages/frontend/
COPY packages/shared/package*.json ./packages/shared/
RUN npm ci
COPY packages/frontend ./packages/frontend
COPY packages/shared ./packages/shared
RUN npm run build --workspace=frontend

FROM nginx:alpine
COPY --from=builder /app/packages/frontend/dist /usr/share/nginx/html
EXPOSE 80
"""
        (self.root / "packages/frontend/Dockerfile").write_text(frontend_dockerfile)

        # Backend Dockerfile
        backend_dockerfile = """FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
COPY packages/backend/package*.json ./packages/backend/
COPY packages/shared/package*.json ./packages/shared/
RUN npm ci --only=production
COPY packages/backend ./packages/backend
COPY packages/shared ./packages/shared
RUN npm run build --workspace=backend
EXPOSE 8000
CMD ["npm", "start", "--workspace=backend"]
"""
        (self.root / "packages/backend/Dockerfile").write_text(backend_dockerfile)

        # Docker Compose
        docker_compose = """version: '3.8'

services:
  frontend:
    build:
      context: .
      dockerfile: packages/frontend/Dockerfile
    ports:
      - "3000:80"
    depends_on:
      - backend

  backend:
    build:
      context: .
      dockerfile: packages/backend/Dockerfile
    ports:
      - "8000:8000"
    environment:
      - NODE_ENV=production
      - PORT=8000
"""
        (self.root / "docker-compose.yml").write_text(docker_compose)

    def generate(self):
        """Generate complete full-stack template."""
        print(f"🚀 Creating full-stack project: {self.project_name}\n")

        self.create_monorepo_structure()
        self.create_root_config()
        self.create_frontend_package()
        self.create_backend_package()
        self.create_shared_package()
        self.create_docker_setup()

        print(f"\n✅ Full-stack template generated!")
        print(f"\n📝 Next steps:")
        print(f"   cd {self.project_name}")
        print(f"   npm install")
        print(f"   npm run dev")

# CLI usage
if __name__ == '__main__':
    import sys

    project_name = sys.argv[1] if len(sys.argv) > 1 else "my-fullstack-app"

    template = FullStackTemplate(project_name)
    template.generate()

Microservices Architecture Template

# microservices-template.yaml
# Template for microservices architecture

structure:
  services:
    - auth-service
    - user-service
    - product-service
    - order-service
    - notification-service

  shared:
    - api-gateway
    - event-bus
    - service-mesh

  infrastructure:
    - kubernetes/
    - terraform/
    - monitoring/

service-template:
  directories:
    - src/api
    - src/domain
    - src/infrastructure
    - src/application
    - tests/unit
    - tests/integration

  files:
    - Dockerfile
    - kubernetes/deployment.yaml
    - kubernetes/service.yaml
    - .env.example
    - README.md

Clean Architecture Template

clean-architecture-project/
├── src/
│   ├── domain/                 # Enterprise business rules
│   │   ├── entities/
│   │   └── value-objects/
│   ├── application/            # Application business rules
│   │   ├── use-cases/
│   │   ├── ports/
│   │   └── services/
│   ├── infrastructure/         # Frameworks & drivers
│   │   ├── database/
│   │   ├── http/
│   │   └── messaging/
│   └── interfaces/             # Interface adapters
│       ├── controllers/
│       ├── presenters/
│       └── gateways/
├── tests/
└── config/

Usage Examples

Generate Full-Stack Project

Apply project-structure-patterns skill to create React + Node.js monorepo with shared types and Docker setup

Microservices Scaffolding

Apply project-structure-patterns skill to generate microservices architecture with API gateway and service mesh

Clean Architecture Setup

Apply project-structure-patterns skill to scaffold project with Clean Architecture layers and dependency inversion

Integration Points

• project-organization-patterns - Directory conventions
• git-workflow-patterns - Monorepo git workflows
• cicd-pipeline-design - Build and deployment automation

Success Output

When successful, this skill MUST output:

✅ SKILL COMPLETE: project-structure-patterns

Completed:
- [x] Project structure created (monorepo/microservices/clean-architecture)
- [x] All package.json files generated with correct dependencies
- [x] Docker configuration files created
- [x] TypeScript/build configurations established
- [x] Directory structure verified

Outputs:
- Root package.json with workspace configuration
- Frontend package (packages/frontend/package.json, vite.config.ts)
- Backend package (packages/backend/package.json, server files)
- Shared types package (packages/shared/src/types/)
- Docker files (Dockerfile per package, docker-compose.yml)
- Architecture documentation in project README

Completion Checklist

Before marking this skill as complete, verify:

• All required directories created per chosen architecture
• Package.json files include correct dependencies and scripts
• TypeScript configurations valid and compiled successfully
• Docker files built without errors
• Workspace/monorepo structure functional (npm install succeeds)
• All template files contain no placeholder errors
• Architecture documentation generated in README
• Project can be started with documented commands (npm run dev)

Failure Indicators

This skill has FAILED if:

• ❌ Directory structure incomplete or missing key paths
• ❌ Package.json files have syntax errors or missing dependencies
• ❌ TypeScript compilation fails due to config issues
• ❌ Docker build fails for any service
• ❌ Workspace installation fails (npm install errors)
• ❌ Generated code contains unresolved template variables
• ❌ Architecture type not clearly identifiable from structure

When NOT to Use

Do NOT use this skill when:

• Single-file applications - Use simpler project setup for standalone scripts
• Existing project restructure - Use project-organization skill instead for refactoring
• Non-JavaScript/TypeScript projects - Skill is optimized for Node.js ecosystem
• Simple library projects - Use minimal package.json, skip monorepo complexity
• Prototype/POC work - Overhead not justified for throwaway code
• Already have established architecture - Use pattern-specific skills (e.g., microservices-deployment)

Alternative skills:

• Use project-organization for reorganizing existing projects
• Use microservices-deployment for pure infrastructure-as-code
• Use language-specific templates for non-Node.js projects

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Mixing architecture styles	Confuses structure (monorepo + microservices)	Choose ONE primary architecture pattern
Over-engineering small projects	Monorepo for 2-file project wastes effort	Match complexity to project size
Skipping package.json validation	Syntax errors block npm install	Always validate JSON before completion
Missing workspace configuration	Packages don't link, duplicate dependencies	Ensure root package.json has workspaces array
Hardcoded paths in configs	Breaks on different systems	Use relative paths and environment variables
No README documentation	Team can't understand structure	Generate architecture diagram and setup docs
Copying without customization	Template values (myapp) left unchanged	Replace all placeholders with actual project name
Missing .gitignore	node_modules committed to git	Include comprehensive .gitignore from start

Principles

This skill embodies these CODITECT principles:

• #1 Recycle → Extend → Re-Use → Create - Provides proven templates before custom builds
• #3 Keep It Simple - Offers minimal, standard, and advanced patterns to match needs
• #4 Separation of Concerns - Clear boundaries between frontend, backend, shared code
• #5 Eliminate Ambiguity - Explicit directory structure eliminates "where does this go?"
• #6 Clear, Understandable, Explainable - Generated structure self-documents through layout
• #13 Automate Repetitive Tasks - Eliminates manual project scaffolding work

Full Principles: CODITECT-STANDARD-AUTOMATION.md