project-setup-standards

Project Setup Standards

Guidance for initializing new projects that comply with all SDLC requirements from the start.

Tooling

Available Tools: If using Claude Code with the sdlc plugin, run /sdlc:init to bootstrap a compliant project structure. The /sdlc:check command validates existing projects.

Project Initialization

Required Steps (MUST)

New projects MUST complete these setup steps:

Repository Initialization

# Initialize repository
git init
git branch -M main

# Create standard directory structure
mkdir -p src tests docs .github/workflows

# Initialize with empty commit
git commit --allow-empty -m "chore: initialize repository"

Required Files

Mandatory Files (MUST)

Every project MUST include:

Configuration Files (MUST)

Projects MUST include appropriate configuration:

EditorConfig (MUST)

Projects MUST include .editorconfig:

root = true

[*]
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
charset = utf-8

[*.{rs,ts,js,py,java,go}]
indent_style = space
indent_size = 4

[*.{yml,yaml,json}]
indent_style = space
indent_size = 2

[Makefile]
indent_style = tab

Build System Setup

Makefile Targets (MUST)

Create Makefile with standard targets:

.PHONY: all build test lint format clean

all: build test

build:
	# Language-specific build command

test:
	# Run test suite

lint:
	# Run linter

format:
	# Format code

format-check:
	# Check formatting without changes

clean:
	# Clean build artifacts

Language-Specific Setup

Rust

cargo init
# Add to Cargo.toml:
# [lints.clippy]
# all = "warn"
# pedantic = "warn"

touch rustfmt.toml clippy.toml

TypeScript/Node.js

npm init -y
npm install -D typescript eslint prettier
npx tsc --init

Python

python -m venv .venv
pip install ruff pytest
# Create pyproject.toml with ruff config

Java

# Maven
mvn archetype:generate -DgroupId=com.example -DartifactId=project

# Gradle
gradle init --type java-application

CI/CD Setup

GitHub Actions (MUST)

Create .github/workflows/ci.yml:

name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: make build
      - name: Test
        run: make test
      - name: Lint
        run: make lint

Branch Protection (MUST)

Configure branch protection for main:

• Require pull request reviews
• Require status checks to pass
• Require linear history (recommended)

Quality Tools Setup

Pre-commit Hooks (SHOULD)

Install pre-commit:

pip install pre-commit
pre-commit install

Create .pre-commit-config.yaml:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

Security Setup

Secret Scanning (SHOULD)

Enable GitHub secret scanning or configure gitleaks:

# .gitleaks.toml
[extend]
useDefault = true

Dependency Auditing (MUST)

Configure automated dependency scanning based on language.

Documentation Setup

README Template

Create README.md with required sections:

• Project name and description
• Badges (CI, version, license)
• Installation instructions
• Quick start
• Contributing link
• License

ADR Directory (SHOULD)

Set up Architecture Decision Records:

mkdir -p docs/adrs
touch docs/adrs/README.md

Implementation Checklist

Repository Setup

• Initialize Git repository
• Create main branch
• Add .gitignore
• Add .gitattributes
• Configure branch protection

Required Files

• Create README.md
• Add LICENSE
• Create CONTRIBUTING.md
• Create CHANGELOG.md
• Add SECURITY.md
• Create .editorconfig

Build System

• Create Makefile with standard targets
• Add language-specific build config
• Verify make all works

Quality Tools

• Configure formatter
• Configure linter
• Set up pre-commit hooks
• Verify make lint and make format work

CI/CD

• Create GitHub Actions workflow
• Configure required status checks
• Add security scanning job

Documentation

• Populate README with content
• Set up ADR directory
• Create initial ADRs if applicable

Compliance Verification

# Verify required files exist
for f in README.md LICENSE CONTRIBUTING.md CHANGELOG.md SECURITY.md .gitignore .gitattributes Makefile .editorconfig; do
  [ -f "$f" ] && echo "✓ $f" || echo "✗ $f missing"
done

# Verify CI workflow exists
ls .github/workflows/ci.yml

# Verify Makefile targets
make -n build test lint format

# Run initial compliance check
make lint && make test

Additional Resources

Reference Files

• references/setup-guide.md - Detailed setup walkthrough
• references/toolchain-versions.md - Recommended tool versions

Examples

• examples/project-rust/ - Complete Rust project template
• examples/project-typescript/ - Complete TypeScript template
• examples/project-python/ - Complete Python template