scaffold-engineer

name	scaffold-engineer
description	Use this skill when creating a new Python project or setting up tooling for an existing one. Runs pyscaffold, configures pre-commit with comprehensive hooks, and sets up CLAUDE.md for documentation. Trigger when starting new projects or adding standard tooling.

Scaffold Engineer Protocol

Set up projects right from the start. Proper tooling, proper structure, proper documentation hooks.

Core Responsibilities

1. Run pyscaffold for project structure
2. Configure pre-commit with full hook suite
3. Update all tools to latest versions
4. Set up CLAUDE.md structure for documentation-engineer

Step 1: Initialize with PyScaffold

# Install pyscaffold if needed
pip install pyscaffold

# Create new project
putup project_name --description "Project description" --license MIT

# Or add to existing project
putup --force .

PyScaffold options to consider:

putup project_name \
  --description "Description" \
  --license MIT \
  --url "https://github.com/org/project" \
  --pre-commit \
  --github-actions \
  --cirrus

Step 2: Configure Pre-commit

Create or update .pre-commit-config.yaml:

repos:
  # Standard pre-commit hooks
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-ast
      - id: check-xml
      - id: check-yaml
      - id: check-added-large-files
        args: ['--maxkb=1000']
      - id: check-merge-conflict
      - id: check-json
        exclude: ^frontend/tsconfig.*\.json$
      - id: check-toml
      - id: debug-statements
      - id: mixed-line-ending
        args: ['--fix=lf']

  # pyupgrade - modernize Python syntax
  - repo: https://github.com/asottile/pyupgrade
    rev: v3.19.1
    hooks:
      - id: pyupgrade

  # Black - code formatting
  - repo: https://github.com/psf/black
    rev: 24.10.0
    hooks:
      - id: black
        language_version: python3.12

  # blacken-docs - format code in docstrings
  - repo: https://github.com/asottile/blacken-docs
    rev: 1.19.1
    hooks:
      - id: blacken-docs
        additional_dependencies: [black]

  # isort - import sorting
  - repo: https://github.com/pycqa/isort
    rev: 5.13.2
    hooks:
      - id: isort

  # autoflake - remove unused imports and variables
  - repo: https://github.com/PyCQA/autoflake
    rev: v2.3.1
    hooks:
      - id: autoflake
        args:
          - --in-place
          - --remove-all-unused-imports
          - --remove-unused-variables
          - --remove-duplicate-keys
          - --ignore-init-module-imports

  # flake8 - linting
  - repo: https://github.com/pycqa/flake8
    rev: 7.1.1
    hooks:
      - id: flake8
        args: ['--max-line-length=120', '--extend-ignore=E203,W503,B008']
        additional_dependencies: [flake8-bugbear]

  # mypy - type checking
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.13.0
    hooks:
      - id: mypy
        exclude: ^tests/.*$
        args: [--config-file=pyproject.toml]
        additional_dependencies:
          - pydantic>=2.5.0
          - pydantic-settings>=2.1.0

  # pytest - run tests
  - repo: local
    hooks:
      - id: pytest
        name: pytest
        entry: pytest -v --tb=short
        language: python
        pass_filenames: false
        always_run: true
        additional_dependencies: [".[dev]"]

  # Frontend (if applicable)
  - repo: local
    hooks:
      - id: frontend-lint
        name: Frontend ESLint
        entry: bash -c 'cd frontend && [ -d node_modules ] || npm install && npm run lint'
        language: system
        files: ^frontend/.*\.(ts|tsx)$
        pass_filenames: false
        always_run: false

      - id: frontend-test
        name: Frontend Tests
        entry: bash -c 'cd frontend && [ -d node_modules ] || npm install && npm run test:run'
        language: system
        files: ^frontend/.*\.(ts|tsx)$
        pass_filenames: false
        always_run: false

Step 3: Update to Latest Versions

Run autoupdate to get latest versions of all hooks:

# Update all hooks to latest versions
pre-commit autoupdate

# Verify updates worked
pre-commit run --all-files

This automatically updates all rev values in .pre-commit-config.yaml to the latest stable releases.

Step 4: Configure pyproject.toml

Add tool configurations:

[tool.black]
line-length = 120
target-version = ['py312']

[tool.isort]
profile = "black"
line_length = 120

[tool.mypy]
python_version = "3.12"
strict = true
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
disallow_incomplete_defs = true

[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = "test_*.py"
python_functions = "test_*"
addopts = "-v --tb=short"

[tool.autoflake]
remove-all-unused-imports = true
remove-unused-variables = true

Step 5: Set Up CLAUDE.md Structure

Create project documentation following documentation-engineer patterns:

Root CLAUDE.md:

# Project Name

One-line description.

## Commands

pip install -e ".[dev]"
pre-commit install
pytest
pre-commit run --all-files

## Structure

src/project_name/     # Main package
tests/                # Test files
docs/                 # Documentation

## Patterns

- All models in src/project_name/models/
- All API handlers in src/project_name/api/
- Config via pydantic-settings in src/project_name/config.py

## Pre-commit

Runs automatically on commit:
- black, isort (formatting)
- flake8, mypy (linting, types)
- pytest (tests)

Run manually: pre-commit run --all-files

Root ARCHITECTURE.md:

# Architecture

## Components

**Models** (src/project_name/models/)
Pydantic models for data validation.

**Services** (src/project_name/services/)
Business logic. No framework dependencies.

**API** (src/project_name/api/)
HTTP handlers if applicable.

## Data Flow

1. Request enters via API handler
2. Handler validates with Pydantic model
3. Handler calls service
4. Service returns result or raises error
5. Handler returns response

Per-directory CLAUDE.md for each major directory.

Step 6: Install and Verify

# Install pre-commit
pip install pre-commit
pre-commit install

# Run all hooks to verify
pre-commit run --all-files

# Fix any issues
pre-commit run --all-files  # Run again after fixes

Step 7: Customize for Project

Adjust based on project needs:

Add dependencies to mypy hook:

additional_dependencies:
  - pydantic>=2.5.0
  - fastapi>=0.109.0
  - sqlalchemy>=2.0.0
  # Add your project's typed dependencies

Remove frontend hooks if no frontend:

# Delete the frontend-lint and frontend-test hooks

Adjust Python version:

• Update language_version in black hook
• Update target-version in pyproject.toml
• Update python_version in mypy config

Checklist

Before finishing:

• pyscaffold structure created
• .pre-commit-config.yaml with all hooks
• pre-commit autoupdate ran (latest versions)
• pyproject.toml has tool configs
• CLAUDE.md at root (for documentation-engineer)
• ARCHITECTURE.md at root
• pre-commit install ran
• pre-commit run --all-files passes
• .gitignore includes standard Python entries

Calibration

Search for latest versions. Don't use hardcoded versions from this doc - they go stale. Always verify current versions.

Customize mypy dependencies. The additional_dependencies must include your project's typed libraries or mypy will fail.

Test the hooks. Run pre-commit run --all-files before committing the config.

Stay in your lane. Don't cover:

• What the project should do (product-manager)
• Library choices (framework-engineer)
• Writing the actual code (that's implementation)