setup-code-scaffolding

name	setup-code-scaffolding
description	Bootstrap or fill gaps in a project's code quality tooling. Sets up pre-commit hooks, linting, formatting, test coverage enforcement, static analysis, dependency auditing, and documentation coverage. Writes an agent-friendly guide to AGENTS.md (or appends to CLAUDE.md if one already exists).
argument-hint	[language or project path, or leave blank to auto-detect]

Bootstrap code quality scaffolding for a project — or fill in gaps if some tooling already exists. Sets up pre-commit hooks that enforce strict standards, installs the necessary tools, configures them, and documents everything so both humans and coding agents know how to run checks.

Input

The user may provide: $ARGUMENTS (language hint, project path, or specific tools to set up)

If no arguments, auto-detect the project language and existing tooling.

What This Skill Sets Up

1. Pre-commit hooks — Gate commits on passing checks
2. Test coverage enforcement — 95%+ line and branch coverage (configurable)
3. Linter — Strict rules, language-appropriate
4. Auto-formatter — Consistent style, no debates
5. Static analysis — Catch bugs before tests do
6. Dependency vulnerability scanning — Audit for known CVEs
7. Documentation coverage — Enforce doc comments on public APIs (where tooling supports it)
8. Agent guide — AGENTS.md documenting all tools and commands (or appends to CLAUDE.md if one already exists)

Process

---

Phase 1: Assess Current State

1. Detect project language and structure

   • Check for: Cargo.toml, go.mod, package.json, pyproject.toml, setup.cfg, pom.xml, build.gradle, etc.
   • Identify subpackages/workspaces (Cargo workspace members, Go modules, npm workspaces, Python packages)
   • Note the language(s) — this drives all tool selection
   • If ambiguous or multi-language, use AskUserQuestion to confirm

2. Inventory existing tooling

   • Check for existing configs: .pre-commit-config.yaml, .husky/, .lefthook.yml, .git/hooks/
   • Check for linter configs: clippy.toml, .eslintrc*, .golangci.yml, ruff.toml, .flake8, pylintrc
   • Check for formatter configs: rustfmt.toml, .prettierrc*, .editorconfig, pyproject.toml [tool.black]
   • Check for test coverage configs: tarpaulin.toml, .nycrc, jest.config.*, pytest.ini, coverage.ini
   • Check for static analysis: clippy (Rust), mypy.ini / pyright (Python), tsconfig.json strict mode (TS)
   • Check for dependency audit tools: cargo audit, npm audit, pip-audit, govulncheck
   • Check for doc coverage: #![deny(missing_docs)] (Rust), eslint-plugin-jsdoc (JS/TS), pydocstyle (Python)
   • Check for CLAUDE.md or AGENTS.md
   • Read Makefile, Justfile, Taskfile.yml for existing targets

3. Identify gaps

   • For each of the 7 categories above, note: fully configured / partially configured / missing
   • Present the assessment to the user before proceeding

Phase 2: Select Tools

For each gap, select the ecosystem-appropriate tool. Default to the most widely adopted tool for each language. Only ask the user when there's a genuine choice to make (not when there's a clear ecosystem default).

Tool defaults by language:

Rust

Category	Default	Notes
Pre-commit hooks	Raw git hooks via shell script	Rust projects rarely use hook frameworks
Test runner	cargo test	Built-in
Coverage	cargo tarpaulin or cargo llvm-cov	Ask user; tarpaulin is simpler, llvm-cov is more accurate
Linter	cargo clippy	Use -D warnings for strictness
Formatter	cargo fmt	Use rustfmt.toml for config
Static analysis	cargo clippy (doubles as linter + static analysis)	Enable pedantic lints
Dep audit	cargo audit	Install via cargo install cargo-audit
Doc coverage	#![deny(missing_docs)] in lib.rs	Compiler-enforced

Go

Category	Default	Notes
Pre-commit hooks	Raw git hooks or pre-commit framework	Ask if pre-commit is already in use
Test runner	go test ./...	Built-in
Coverage	go test -coverprofile with -covermode=atomic	Use go tool cover for reports
Linter	golangci-lint	Configure via .golangci.yml
Formatter	gofmt / goimports	Built-in
Static analysis	staticcheck or golangci-lint (includes it)
Dep audit	govulncheck	Install via go install golang.org/x/vuln/cmd/govulncheck@latest
Doc coverage	golangci-lint with godot and exported function checks	Limited compared to other languages

Python

Category	Default	Notes
Pre-commit hooks	pre-commit framework	De facto standard for Python
Test runner	pytest
Coverage	pytest-cov (wraps coverage.py)	Configure in pyproject.toml
Linter	ruff	Fast, replaces flake8 + isort + many others
Formatter	ruff format	Or black if already in use
Static analysis	mypy (strict mode) or pyright	Ask user preference
Dep audit	pip-audit
Doc coverage	ruff rules (D series / pydocstyle)	Enable D rules in ruff config

TypeScript / JavaScript

Category	Default	Notes
Pre-commit hooks	husky + lint-staged	Ecosystem standard
Test runner	jest or vitest	Ask if not obvious from package.json
Coverage	Built into test runner (--coverage)	Configure thresholds in config
Linter	eslint	Use @typescript-eslint for TS
Formatter	prettier
Static analysis	TypeScript strict mode ("strict": true in tsconfig)
Dep audit	npm audit	Built-in
Doc coverage	eslint-plugin-jsdoc	For public API enforcement

Java / Kotlin

Category	Default	Notes
Pre-commit hooks	Raw git hooks or pre-commit framework	Ask user
Test runner	gradle test or mvn test	Depends on build tool
Coverage	JaCoCo	Configure minimum thresholds
Linter	Checkstyle (Java) / ktlint (Kotlin)
Formatter	google-java-format / ktfmt
Static analysis	SpotBugs or Error Prone	Ask user preference
Dep audit	OWASP Dependency-Check or gradle dependencyCheckAnalyze
Doc coverage	Checkstyle JavaDoc rules

For languages not listed above, use AskUserQuestion to determine appropriate tools.

Phase 3: Install and Configure Tools

For each tool being set up:

1. Install the tool

   • Use the language's package manager to add dev dependencies
   • For CLI tools, document the install command
   • Verify the tool runs after installation

2. Write configuration

   • Create config files with strict defaults
   • For linters: enable the strictest reasonable ruleset, not just defaults
   • For coverage: set 95% line and 95% branch coverage thresholds as the starting point
   • For formatters: use the community standard style (don't customize unless asked)

3. Handle subpackages/workspaces

   • For Cargo workspaces: configure coverage and linting per workspace member
   • For Go modules: ensure ./... patterns cover all packages
   • For npm workspaces: configure lint-staged to handle workspace paths
   • For Python monorepos: configure tool paths to cover all packages

4. Verify each tool works

   • Run each tool and confirm it produces output (even if there are failures to fix)
   • If a tool fails to install or run, ask the user for guidance rather than skipping silently

Phase 4: Set Up Pre-Commit Hooks

Create pre-commit hooks that run the configured tools. The hook should:

1. Run auto-formatter (fix mode — auto-fix and stage the formatted files)
2. Run linter (check mode — fail the commit if lint errors exist)
3. Run tests with coverage enforcement (fail if below threshold)
4. Run static analysis (fail if issues found)
5. Run dependency audit (warn on vulnerabilities — don't block commits, but print warnings)

Hook configuration by ecosystem:

• Rust: Shell script in .git/hooks/pre-commit or a hooks/ directory with setup script
• Go: Shell script or pre-commit framework if already in use
• Python: .pre-commit-config.yaml with pre-commit framework
• TypeScript/JavaScript: husky + lint-staged configured in package.json
• Java/Kotlin: Shell script or pre-commit framework

Coverage threshold configuration:

• Default: 95% line coverage, 95% branch coverage
• If the project has existing tests with lower coverage, use AskUserQuestion:
  • "Current coverage is X%. Set threshold to 95% (strict) or X+5% (incremental improvement)?"
  • The goal is always 95%+ but we may need to ratchet up from existing levels

The hook must be installable. Include a setup command (e.g., make setup-hooks, npm prepare, pre-commit install) and document it.

Phase 5: Add Makefile/Taskrunner Targets (if applicable)

If the project uses a Makefile, Justfile, or similar, add targets for each tool:

.PHONY: test lint fmt check audit

test:          ## Run tests with coverage
	{test command with coverage flags}

lint:          ## Run linter
	{lint command}

fmt:           ## Auto-format code
	{format command}

check:         ## Run all checks (format check + lint + test + audit)
	{all checks in sequence}

audit:         ## Run dependency vulnerability scan
	{audit command}

setup-hooks:   ## Install pre-commit hooks
	{hook installation command}

If no task runner exists, create a Makefile with these targets. The check target should run everything the pre-commit hook runs, so developers can run the full check suite manually.

Phase 6: Write Agent Guide

This is the most important output — it tells coding agents exactly how to work in this project.

1. Determine which file to write — never create a new CLAUDE.md

   • If CLAUDE.md already exists in the project root: append a ## Code Quality & Development Commands section to it
   • Otherwise: create AGENTS.md (or append to it if it already exists)

2. Write the guide with this content:

## Code Quality & Development Commands

### Quick Reference

| Action | Command |
|--------|---------|
| Run tests | `{command}` |
| Run tests with coverage | `{command}` |
| Run linter | `{command}` |
| Auto-format | `{command}` |
| Run static analysis | `{command}` |
| Run dependency audit | `{command}` |
| Run all checks | `{command}` |
| Install pre-commit hooks | `{command}` |

### Coverage Requirements

- **Line coverage:** {threshold}%
- **Branch coverage:** {threshold}%
- Coverage is enforced by pre-commit hooks. Tests that reduce coverage below the threshold will block commits.

### Pre-Commit Hooks

The following checks run automatically on `git commit`:
1. Auto-format (fixes and re-stages)
2. Lint (fails on errors)
3. Test with coverage (fails if below threshold)
4. Static analysis (fails on issues)
5. Dependency audit (warns on vulnerabilities)

To install hooks: `{install command}`
To bypass hooks (emergency only): `git commit --no-verify`

### Before Submitting Code

Always run the full check suite before requesting a commit:

{full check command}

If coverage is below threshold, add tests for uncovered code paths before committing.

### Subpackages

{If applicable: describe workspace/package structure and any per-package test/lint commands}

3. Keep it concise and command-focused — agents need commands they can run, not prose explanations of philosophy.

Phase 7: Present Summary

After completing setup, present to the user:

1. What was set up — table of tools installed and configured
2. What was already in place — tools that existed and were left as-is
3. Coverage thresholds — the configured line and branch coverage targets
4. How to install hooks — the setup command for new clones
5. Known issues — any tools that couldn't be configured or had errors
6. Next steps — e.g., "Run make check to see current state of the codebase against these standards"

---

Output

After completion:

• Pre-commit hooks installed and working
• All quality tools configured with strict defaults
• AGENTS.md created (or CLAUDE.md updated if it already existed) with complete agent guide
• Task runner targets added (if applicable)
• Summary of what was set up and how to use it