project-scaffolding

Project Scaffolding Skill

Comprehensive guide to project type detection, template selection, post-scaffolding setup, Harness integration, and testing strategies.

Project Type Detection Matrix

How to Detect Project Type

Detection Priority:

1. Look for language-specific files in root
2. Check build system presence
3. Examine package/dependency files
4. Analyze configuration files
5. Review existing CI/CD setup

Type Identification Checklist

Python Project:
  ✓ setup.py, pyproject.toml, or requirements.txt
  ✓ .python-version file
  ✓ Pipfile (Pipenv)
  ✓ poetry.lock (Poetry)

Node.js/JavaScript:
  ✓ package.json exists
  ✓ node_modules/ directory
  ✓ .npmrc or .yarnrc
  ✓ yarn.lock or package-lock.json

Java/JVM:
  ✓ pom.xml (Maven) or build.gradle (Gradle)
  ✓ src/main/java structure
  ✓ .java files present

Go:
  ✓ go.mod file
  ✓ *.go source files
  ✓ go.sum dependencies file

Rust:
  ✓ Cargo.toml
  ✓ src/ directory
  ✓ Cargo.lock

C#/.NET:
  ✓ *.csproj or *.sln files
  ✓ appsettings.json
  ✓ global.json

TypeScript:
  ✓ tsconfig.json
  ✓ *.ts or *.tsx files
  ✓ package.json with typescript dependency

Kubernetes/DevOps:
  ✓ Dockerfile
  ✓ docker-compose.yml
  ✓ k8s/ or helm/ directory
  ✓ Helmfile

Infrastructure as Code:
  ✓ *.tf files (Terraform)
  ✓ bicep/ directory (Azure Bicep)
  ✓ cloudformation.yaml (AWS CloudFormation)

---

Project Type Recommendations Matrix

1. Python Projects

Best Templates:

• Cookiecutter - Standard Python projects, packages
• Copier - Complex projects with versioning needs
• Poetry - Modern Python packaging

Template Structure:

{project_name}/
├── {project_name}/          # Main package
│   ├── __init__.py
│   ├── main.py
│   └── config.py
├── tests/                   # Test directory
│   ├── __init__.py
│   ├── conftest.py         # pytest fixtures
│   └── test_main.py
├── docs/                    # Documentation
│   ├── conf.py             # Sphinx config
│   ├── index.rst
│   └── api.rst
├── .gitignore
├── README.md
├── LICENSE
├── requirements.txt         # Or pyproject.toml
├── setup.py                # Or tool.poetry in pyproject.toml
├── pytest.ini
├── tox.ini                 # Multi-environment testing
└── Dockerfile

Key Variables:

project_name: str           # Package name (lowercase, underscores)
author_name: str           # Author name
author_email: str          # Author email
python_version: str        # Target version (3.9, 3.10, 3.11, 3.12)
use_poetry: bool          # Use Poetry for dependency management
use_pytest: bool          # Use pytest (default: true)
use_docker: bool          # Include Dockerfile
include_cli: bool         # Include Click CLI framework

Post-Scaffolding:

cd {project_name}
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
pytest tests/             # Verify test setup

---

2. Node.js/JavaScript Projects

Best Templates:

• Cookiecutter - Standard Node projects
• Copier - Full-stack applications

Template Structure:

{project_name}/
├── src/
│   ├── index.js
│   ├── config.js
│   └── utils/
├── tests/
│   ├── unit/
│   ├── integration/
│   └── fixtures/
├── public/                # Static assets
├── docs/
├── .env.example          # Environment template
├── .eslintrc.json        # ESLint config
├── .prettierrc.json      # Code formatting
├── jest.config.js        # Jest testing config
├── tsconfig.json         # If using TypeScript
├── package.json
├── package-lock.json     # Or yarn.lock / pnpm-lock.yaml
├── Dockerfile
├── docker-compose.yml
├── .gitignore
├── README.md
└── LICENSE

Key Variables:

project_name: str              # Project name
author_name: str               # Author
use_typescript: bool          # TypeScript support
use_eslint: bool              # ESLint (default: true)
use_prettier: bool            # Code formatter
use_jest: bool                # Jest testing
use_docker: bool              # Docker support
use_express: bool             # Express.js framework
package_manager: str          # npm, yarn, pnpm

Post-Scaffolding:

cd {project_name}
npm install              # or yarn / pnpm install
npm run lint             # Check linting
npm run test             # Run tests
npm run dev              # Start development server

---

3. Java/JVM Projects

Best Templates:

• Maven Archetypes - Standard Java projects
• Gradle Template - Gradle-based projects

Template Structure (Maven):

{project_name}/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/company/{project_name}/
│   │   │       ├── App.java
│   │   │       └── service/
│   │   └── resources/
│   │       └── application.properties
│   └── test/
│       ├── java/
│       │   └── com/company/{project_name}/
│       │       └── AppTest.java
│       └── resources/
├── docs/
├── pom.xml              # Maven configuration
├── README.md
├── Dockerfile
└── .gitignore

Key Variables:

groupId: str             # Maven group ID (e.g., com.company)
artifactId: str          # Maven artifact ID
package: str             # Java package name
java_version: str        # JDK version (11, 17, 21)
spring_boot_version: str # If using Spring Boot
build_tool: str          # maven or gradle

Post-Scaffolding:

cd {project_name}
mvn clean compile        # Compile project
mvn test                 # Run tests
mvn spring-boot:run      # If using Spring Boot

---

4. TypeScript Projects

Best Templates:

• ts-node - CLI tools and scripts
• Next.js - Full-stack web applications
• NestJS - Backend APIs

Template Structure:

{project_name}/
├── src/
│   ├── index.ts
│   ├── types/
│   │   └── index.ts
│   ├── services/
│   ├── controllers/      # If REST API
│   └── utils/
├── tests/
│   ├── unit/
│   └── integration/
├── dist/                 # Compiled JavaScript (output)
├── tsconfig.json        # TypeScript config
├── jest.config.js       # Jest testing
├── .eslintrc.json       # ESLint
├── package.json
├── Dockerfile
├── README.md
└── .gitignore

Key Variables:

project_name: str
typescript_version: str   # Exact version or latest
jest_enabled: bool        # Testing framework
eslint_enabled: bool      # Linting
strict_mode: bool         # tsconfig strict
target: str               # Compilation target (ES2020, etc.)
module: str               # Module system (ESNext, CommonJS)

Post-Scaffolding:

cd {project_name}
npm install
npm run build             # Compile TypeScript
npm test                  # Run tests
npm start                 # Run compiled code

---

5. Go Projects

Best Templates:

• Go Project Layout - Standard Go project structure
• Cobra CLI - CLI applications

Template Structure:

{project_name}/
├── cmd/
│   ├── cli/
│   │   └── main.go      # Application entry point
│   └── server/          # If server application
│       └── main.go
├── internal/            # Private packages
│   ├── config/
│   ├── handler/
│   └── service/
├── pkg/                 # Public packages
│   └── {package_name}/
├── api/                 # API definitions
├── test/
├── docs/
├── Makefile             # Build automation
├── go.mod               # Module definition
├── go.sum               # Checksums
├── Dockerfile
├── .gitignore
├── README.md
└── LICENSE

Key Variables:

project_name: str        # Go module name (github.com/user/project)
author_name: str
go_version: str          # Minimum Go version (1.19, 1.20, 1.21)
use_cobra: bool          # CLI framework
use_gin: bool            # Web framework (if server)
use_gorm: bool           # ORM (if database needed)

Post-Scaffolding:

cd {project_name}
go mod download          # Download dependencies
go build ./cmd/cli       # Build application
go test ./...            # Run tests
./cli --help             # Test CLI

---

6. Kubernetes/DevOps Projects

Best Templates:

• Helm Chart - Kubernetes deployments
• Kustomize - Kubernetes customization
• Copier - Multi-environment setups

Template Structure:

{project_name}/
├── helm/
│   └── {release_name}/
│       ├── Chart.yaml
│       ├── values.yaml
│       ├── values-dev.yaml
│       ├── values-prod.yaml
│       └── templates/
│           ├── deployment.yaml
│           ├── service.yaml
│           ├── configmap.yaml
│           └── ingress.yaml
├── k8s/
│   ├── base/
│   ├── dev/
│   └── prod/
├── kustomization.yaml
├── docker-compose.yml   # For local development
├── Dockerfile
├── .dockerignore
├── docs/
├── README.md
└── .gitignore

Key Variables:

project_name: str        # Application name
image_registry: str      # Docker registry
image_name: str          # Docker image name
replicas_dev: int        # Dev environment replicas
replicas_prod: int       # Prod environment replicas
namespace: str           # Kubernetes namespace
enable_ingress: bool
enable_monitoring: bool  # Prometheus/monitoring

Post-Scaffolding:

cd {project_name}
docker build -t {image}:latest .
helm lint helm/{release}
helm template helm/{release} -f values-dev.yaml
kubectl apply -f k8s/dev/  # Deploy to dev

---

7. Infrastructure as Code (Terraform)

Best Templates:

• Terraform Module - Reusable infrastructure components
• Terraform Project - Full environment setup

Template Structure:

{project_name}/
├── main.tf              # Main configuration
├── variables.tf         # Input variables
├── outputs.tf           # Output values
├── terraform.tfvars     # Variable values
├── locals.tf            # Local values
├── vpc.tf               # VPC configuration
├── security.tf          # Security groups
├── iam.tf               # IAM roles/policies
├── modules/
│   ├── vpc/
│   ├── compute/
│   └── database/
├── environments/
│   ├── dev/
│   │   └── terraform.tfvars
│   ├── staging/
│   └── prod/
├── docs/
├── .gitignore
├── README.md
├── versions.tf          # Terraform version constraints
└── backend.tf           # State backend config

Key Variables:

project_name: str        # Project identifier
aws_region: str          # AWS region
environment: str         # dev, staging, prod
terraform_version: str   # Minimum version

Post-Scaffolding:

cd environments/dev
terraform init           # Initialize backend
terraform plan           # Preview changes
terraform apply          # Apply configuration
terraform output         # View outputs

---

Post-Scaffolding Checklist

Universal Tasks (All Projects)

• Review generated files and structure
• Verify .gitignore is appropriate
• Update README.md with project-specific info
• Add LICENSE file (if not included)
• Initialize Git repository
• Create initial commit
• Add remote repository
• Verify dependency installation
• Run basic tests to confirm setup works
• Document build/run commands
• Set up CI/CD configuration

Language-Specific Tasks

Python:

• Verify virtual environment works
• Test package imports
• Check pytest configuration
• Verify linting (flake8/pylint) setup
• Test documentation build (if Sphinx)
• Verify type hints (if mypy configured)

Node.js:

• Verify npm/yarn/pnpm setup
• Test linting and formatting
• Verify test framework (Jest/Mocha)
• Check TypeScript compilation
• Verify build output directory
• Test hot reload (if dev server)

Java:

• Verify Maven/Gradle build
• Test unit tests run successfully
• Verify IDE integration
• Check dependency tree
• Verify JAR/WAR packaging

Go:

• Verify go mod download
• Test build command
• Verify all tests pass
• Check linting (golangci-lint)
• Verify binary execution

Docker Tasks

• Build Docker image
• Test image runs locally
• Verify volumes/ports are correct
• Document docker run command
• Add Docker Compose if multi-container
• Set up .dockerignore

---

Harness Integration Patterns

Pattern 1: Basic CI Pipeline

For: Single service, simple build and push

# harness/build-pipeline.yaml
pipeline:
  name: Build and Push
  identifier: build_push
  stages:
    - stage:
        name: Build Docker
        type: CI
        spec:
          codebase:
            repoName: {project_name}
            branch: main
          build:
            type: Docker
            spec:
              dockerfile: Dockerfile
              registryConnector: <+input.docker_connector>
              imageName: <+input.image_name>
              imageTag: <+codebase.commitSha>

Pattern 2: Build, Test, and Deploy

For: Multi-stage pipeline with testing

pipeline:
  name: Build Test Deploy
  identifier: build_test_deploy
  stages:
    - stage:
        name: Build
        type: CI
        spec:
          build:
            type: Docker
            spec:
              dockerfile: Dockerfile

    - stage:
        name: Test
        type: CI
        depends_on:
          - Build
        spec:
          steps:
            - step:
                type: Run
                spec:
                  image: <+artifact.image>
                  script: npm test

    - stage:
        name: Deploy Dev
        type: Deployment
        depends_on:
          - Test
        spec:
          service:
            serviceRef: <+input.service>
          environment:
            environmentRef: dev

Pattern 3: Multi-Environment Deployment

For: Dev → Staging → Production with approvals

stages:
  - stage:
      name: Deploy Dev
      type: Deployment
      spec:
        environment: dev
        infrastructure: dev-k8s-cluster

  - stage:
      name: Deploy Staging
      type: Deployment
      depends_on:
        - Deploy Dev
      spec:
        environment: staging
        infrastructure: staging-k8s-cluster

  - stage:
      name: Approval for Production
      type: Approval
      depends_on:
        - Deploy Staging
      spec:
        approvers:
          - <+input.approver_group>

  - stage:
      name: Deploy Production
      type: Deployment
      depends_on:
        - Approval for Production
      spec:
        environment: production
        infrastructure: prod-k8s-cluster

Pattern 4: GitOps with Harness

For: Managing manifests separately from source code

stages:
  - stage:
      name: Build
      type: CI
      spec:
        build:
          type: Docker

  - stage:
      name: Update Manifests
      type: CI
      spec:
        steps:
          - step:
              type: Run
              spec:
                script: |
                  git clone <+input.manifest_repo>
                  sed -i "s/IMAGE_TAG/<+artifact.imageTag>/g" k8s/deployment.yaml
                  git commit && git push

  - stage:
      name: Deploy via GitOps
      type: Deployment
      spec:
        gitOpsEnabled: true
        service:
          serviceRef: <+input.service>
        environment:
          environmentRef: <+input.environment>

---

Testing Recommendations by Project Type

Python Testing

Frameworks:

• pytest - Modern, flexible test framework
• unittest - Standard library
• nose2 - Plugin-based testing

Setup:

pip install pytest pytest-cov pytest-mock

Test Structure:

tests/
├── conftest.py          # Shared fixtures
├── unit/
│   ├── test_module.py
│   └── test_service.py
├── integration/
│   └── test_api.py
└── fixtures/
    └── sample_data.py

Coverage Target: 80%+

---

Node.js Testing

Frameworks:

• Jest - All-in-one solution
• Mocha + Chai - Flexible combination
• Vitest - Fast alternative

Setup:

npm install --save-dev jest @testing-library/react

Test Structure:

tests/
├── unit/
│   ├── utils.test.js
│   └── helpers.test.js
├── integration/
│   └── api.test.js
└── e2e/
    └── user-flow.test.js

Coverage Target: 80%+

---

Java Testing

Frameworks:

• JUnit 5 - Modern testing framework
• Mockito - Mocking framework
• TestNG - Alternative to JUnit

Setup:

<dependency>
    <groupId>junit</groupId>
    <artifactId>junit-jupiter</artifactId>
    <scope>test</scope>
</dependency>

Test Structure:

src/test/java/
└── com/company/project/
    ├── ServiceTest.java
    ├── ControllerTest.java
    └── IntegrationTest.java

Coverage Target: 80%+

---

Go Testing

Testing Style:

• Standard Go testing package
• Table-driven tests
• Subtests

Setup:

go get github.com/stretchr/testify

Test Structure:

internal/
├── service/
│   ├── service.go
│   └── service_test.go
└── handler/
    ├── handler.go
    └── handler_test.go

Coverage Target: 80%+

---

Post-Scaffolding Setup Verification

Universal Verification Commands

# Git setup
git init
git add .
git commit -m "Initial commit from template"

# Dependency verification
{build-tool} list              # List dependencies

# Test verification
{build-tool} test              # Run test suite

# Build verification
{build-tool} build             # Build project

# Docker verification (if applicable)
docker build -t {image}:test .
docker run {image}:test --version

Checklist Summary

ESSENTIAL:
- [ ] Project initialized and builds
- [ ] Dependencies installed
- [ ] Tests run and pass
- [ ] Documentation exists
- [ ] .gitignore configured
- [ ] Initial commit created

HARNESS INTEGRATION:
- [ ] Harness service created
- [ ] Pipeline template ready
- [ ] Environment configured
- [ ] Deployment target defined

QUALITY GATES:
- [ ] Linting passes
- [ ] Tests pass
- [ ] Code coverage >= 80%
- [ ] Documentation complete
- [ ] Security scan passes

---

Related Documentation

• Cookiecutter Documentation
• Copier Documentation
• Maven Archetypes
• Harness Delegate Setup
• Helm Charts
• Terraform Best Practices