setting-up-projects

Setting Up Projects

You are activating project setup automation. Your role is to establish best practices, quality tooling, and proper configuration for new or existing projects.

When to Activate

This skill activates when:

User is creating a new project
Project lacks pre-commit hooks configuration
Missing essential config files (.gitignore, .editorconfig, etc.)
Setting up development environment
User asks about project setup or best practices
Establishing quality baselines

Philosophy

Quality from the Start

Automate Quality: Pre-commit hooks catch issues before commit
Consistency: Formatting and linting enforce standards
Security: Detect secrets and vulnerabilities early
Productivity: Proper setup accelerates development

Progressive Enhancement

Start with essentials, add more as needed:

Core configs (Git, editor, dependencies)
Quality tooling (linting, formatting)
Pre-commit hooks (automation)
CI/CD pipelines (continuous validation)

Setup Process

1. Assess Current State

Check what exists:

ls -la  # Check for config files
git status  # Check Git state

Identify gaps:

.gitignore present?
.editorconfig for consistency?
Package manager config (package.json, requirements.txt, etc.)?
Linter config?
Formatter config?
Pre-commit hooks?
CI/CD config?

2. Create Core Configs

.gitignore

Generate appropriate ignore patterns:

Language-specific (node_modules, pycache, etc.)
IDE files (.vscode, .idea, etc.)
OS files (.DS_Store, Thumbs.db, etc.)
Environment files (.env, .env.local)
Build artifacts (dist/, build/, *.pyc)

.editorconfig

Ensure consistent formatting across editors:

root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.py]
indent_size = 4

[*.md]
trim_trailing_whitespace = false

3. Set Up Quality Tooling

Python Projects

Linting & Formatting:

Ruff: Fast all-in-one tool (replaces black, flake8, isort)
Pyright or Mypy: Type checking

Configuration (pyproject.toml):

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W"]

[tool.pyright]
typeCheckingMode = "basic"

JavaScript/TypeScript Projects

Linting & Formatting:

Prettier: Code formatting
ESLint: Linting

Configuration:

// .prettierrc
{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5"
}

// .eslintrc.json
{
  "extends": ["eslint:recommended"],
  "env": {
    "node": true,
    "es2021": true
  }
}

4. Install Pre-commit Hooks

Pre-commit runs checks automatically before each commit.

Installation

pip install pre-commit
pre-commit install

Configuration (.pre-commit-config.yaml)

Python Project:

repos:
  # Universal checks
  - 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-json
      - id: check-merge-conflict
      - id: check-added-large-files
        args: ["--maxkb=500"]

  # Python: Ruff (linting + formatting)
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.5
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  # Python: Type checking
  - repo: https://github.com/RobertCraigie/pyright-python
    rev: v1.1.338
    hooks:
      - id: pyright

  # Security: Detect secrets
  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.4.0
    hooks:
      - id: detect-secrets
        args: ["--baseline", ".secrets.baseline"]

JavaScript/TypeScript Project:

repos:
  # Universal checks
  - 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-json
      - id: check-merge-conflict
      - id: check-added-large-files

  # JavaScript: Prettier
  - repo: https://github.com/pre-commit/mirrors-prettier
    rev: v3.1.0
    hooks:
      - id: prettier
        types_or: [javascript, jsx, ts, tsx, json, yaml, markdown]

  # JavaScript: ESLint
  - repo: https://github.com/pre-commit/mirrors-eslint
    rev: v8.54.0
    hooks:
      - id: eslint
        files: \.[jt]sx?$
        types: [file]

  # Security
  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.4.0
    hooks:
      - id: detect-secrets

5. Initialize Baseline

For existing projects, create baseline to avoid flagging existing issues:

# Create secrets baseline (won't flag existing patterns)
detect-secrets scan > .secrets.baseline

# Run pre-commit on all files
pre-commit run --all-files

6. Document Setup

Create or update README.md with:

Setup instructions
Development workflow
Quality tooling in use
How to run tests
How to contribute

Language-Specific Setups

Python

Essential Files:

requirements.txt or pyproject.toml
.python-version (for version pinning)
pytest.ini or pyproject.toml (test config)

Virtual Environment:

python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt

JavaScript/TypeScript

Essential Files:

package.json
tsconfig.json (TypeScript)
.nvmrc (Node version)

Install Dependencies:

npm install
# or
yarn install

Rust

Essential Files:

Cargo.toml
rustfmt.toml
clippy.toml

Setup:

cargo build
cargo fmt
cargo clippy

Go

Essential Files:

go.mod
.golangci.yml

Setup:

go mod download
go fmt ./...
go vet ./...

Configuration Templates

Full Python Project Setup

Create comprehensive setup:

project/
├── .gitignore
├── .editorconfig
├── .pre-commit-config.yaml
├── pyproject.toml
├── README.md
├── requirements.txt
├── requirements-dev.txt
├── src/
│   └── project/
│       └── __init__.py
└── tests/
    └── __init__.py

Full JavaScript Project Setup

project/
├── .gitignore
├── .editorconfig
├── .pre-commit-config.yaml
├── .prettierrc
├── .eslintrc.json
├── package.json
├── tsconfig.json
├── README.md
├── src/
│   └── index.ts
└── tests/
    └── index.test.ts

Integration Points

Invokes

Builder Agent: For code generation
Templates: Language-specific boilerplate
Pre-commit Setup: See Specs/PreCommitHooks.md

References

Project Structure: Specs/ProjectStructure.md
Best Practices: Language-specific guides
Templates: ~/.amplihack/.claude/templates/

Recommendations

Always Recommend

These are essential for all projects:

.gitignore - Prevent committing unwanted files
.editorconfig - Consistent formatting
Pre-commit hooks - Automated quality
README.md - Documentation

Recommend for Teams

When multiple developers:

Code formatting (Prettier, Black, etc.)
Linting (ESLint, Ruff, etc.)
Type checking (TypeScript, Mypy, etc.)
CI/CD pipeline

Recommend for Production

When shipping to users:

Security scanning (detect-secrets, etc.)
Dependency checking (Dependabot, etc.)
Test coverage tracking
Performance monitoring

Example Workflow

User: "I'm starting a new Python project for a REST API."

Setting Up Projects Skill:

Great! Let me set up a solid foundation for your Python REST API project.

## Setup Plan

I'll create:
1. Project structure with best practices
2. Pre-commit hooks for automated quality
3. Python configs (ruff, pyright)
4. Git ignore patterns
5. README template

## Project Structure

Creating:

api-project/ ├── .gitignore # Ignore patterns ├── .editorconfig # Editor consistency ├── .pre-commit-config.yaml # Pre-commit hooks ├── pyproject.toml # Python config + dependencies ├── README.md # Documentation ├── requirements.txt # Production dependencies ├── requirements-dev.txt # Development dependencies ├── src/ │ └── api/ │ ├── init.py │ ├── main.py # FastAPI app entry │ └── routers/ # API routes ├── tests/ │ ├── init.py │ └── test_main.py └── .env.example # Environment template


## Quality Tooling

Installing:
- **Ruff**: Fast linting + formatting
- **Pyright**: Type checking
- **Detect-secrets**: Prevent credential leaks
- **Pre-commit**: Automated checks

## Pre-commit Hooks

Configured to run on every commit:
- Trailing whitespace removal
- File ending fixes
- YAML/JSON validation
- Large file detection
- Ruff linting + formatting
- Type checking with pyright
- Secret detection

## Setup Instructions

```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

# Run initial check
pre-commit run --all-files

Next Steps

Review generated configuration
Customize as needed
Start implementing API endpoints
Set up CI/CD (GitHub Actions recommended)

Ready to create these files?


## Quality Checklist

Before completing setup:
- [ ] All essential configs present
- [ ] Pre-commit hooks installed and tested
- [ ] README documents setup process
- [ ] .gitignore covers common patterns
- [ ] Quality tooling configured
- [ ] Dependencies documented
- [ ] Example .env file provided (no secrets!)
- [ ] Tests directory created

## Common Mistakes to Avoid

### 1. No .gitignore
**Problem**: Commits unwanted files (node_modules, .env, etc.)
**Fix**: Create comprehensive .gitignore first

### 2. Inconsistent Formatting
**Problem**: Merge conflicts from formatting differences
**Fix**: Set up Prettier/Black and .editorconfig

### 3. No Pre-commit Hooks
**Problem**: Issues caught late in CI or code review
**Fix**: Install pre-commit hooks from start

### 4. Hardcoded Secrets
**Problem**: Credentials committed to Git
**Fix**: Use .env files + detect-secrets hook

### 5. Missing Type Checking
**Problem**: Type errors caught at runtime
**Fix**: Enable TypeScript/Mypy from start

### 6. No Documentation
**Problem**: New developers struggle with setup
**Fix**: Maintain clear README with setup steps

## Success Criteria

Good project setup:
- Developer can clone and run in <5 minutes
- Quality checks run automatically
- Consistent formatting across team
- No secrets in repository
- Clear documentation
- Minimal friction for contributors

## Related Capabilities

- **Skill**: "Architecting Solutions" for design decisions
- **Skill**: "Reviewing Code" for quality validation
- **Agent**: Builder agent for code generation
- **Documentation**: `Specs/PreCommitHooks.md`
- **Templates**: `~/.amplihack/.claude/templates/`

---

Remember: Time spent on setup saves exponentially more time fixing avoidable issues later. Start with quality automation from day one.

About this skill

When to Activate

Philosophy

Quality from the Start

Progressive Enhancement

Setup Process

1. Assess Current State

2. Create Core Configs

.gitignore

.editorconfig

3. Set Up Quality Tooling

Python Projects

JavaScript/TypeScript Projects

4. Install Pre-commit Hooks

Installation

Configuration (.pre-commit-config.yaml)

5. Initialize Baseline

6. Document Setup

Language-Specific Setups

Python

JavaScript/TypeScript

Rust

Go

Configuration Templates

Full Python Project Setup

Full JavaScript Project Setup

Integration Points

Invokes

References

Recommendations

Always Recommend

Recommend for Teams

Recommend for Production

Example Workflow

Next Steps