Code Quality Setup

When starting or scaffolding any project, set up formatting, linting, import sorting, type checking, and pre-commit hooks before writing application code. This prevents the painful scenario of adding these tools later and facing thousands of lines of formatting changes in a single commit.

Detect the ecosystem

Determine the project type from existing files or the scaffolding context:

Signal	Ecosystem
pyproject.toml, setup.py, requirements.txt, .py files	Python
package.json, tsconfig.json, .ts/.js/.tsx files	JavaScript/TypeScript
Both present	Monorepo — configure each ecosystem separately

Also check for existing quality tooling configs (.eslintrc, .prettierrc, biome.json, [tool.black] or [tool.ruff] in pyproject.toml, .pre-commit-config.yaml, lefthook.yml). If present, preserve them — only migrate to different tools if the user explicitly requests it (see Guardrails).

Set up tooling

After detecting the ecosystem, follow the appropriate guide:

• Python projects — see python.md for Ruff + pre-commit setup
• JS/TS projects — see javascript.md for Biome + Knip + lefthook + tsc setup

Standard command contract

Every project must expose these five commands (via package.json scripts or Makefile):

Command	What it does
format	Auto-format and sort imports
lint	Lint without writing (report only)
typecheck	Run type checker (tsc --noEmit, mypy, or pyright)
check	All non-writing checks: lint + typecheck + unused-code detection
check:fix	Run autofixers (format + lint fix), then run check

Pre-commit hooks should run check:fix so that commits are always clean.

Workflow

1. Install and configure the tools (formatter, linter, type checker)
2. Add pre-commit hook infrastructure (lefthook or pre-commit)
3. Run the full suite once to establish a clean baseline
4. Fix any initial issues so the first "real" commit starts clean
5. Commit the configuration files as the first or second commit in the project

When working on existing projects

If a project already has code but no quality tooling:

1. Add and configure the tools
2. Run the formatter first — commit the formatting changes in a single dedicated commit with a message like chore: apply initial formatting
3. Run the linter — fix issues and commit separately: chore: fix initial lint issues
4. Wire up pre-commit hooks last so all future commits are clean

Guardrails

• Don't replace existing mature tooling. If a project already uses ESLint/Prettier, Black, or other established tools, keep them. Only migrate to Biome/Ruff if the user explicitly asks.
• Don't broadly disable rules to force a green baseline. Use narrow, targeted exceptions (// biome-ignore, # noqa: XX) with comments explaining why — never bulk-suppress to make errors disappear.
• If tooling binaries aren't available, scaffold configs anyway. Write the configuration files and report the install commands the user needs to run.

Completion checklist

Before considering the setup done, verify:

1. Formatter, linter, and type checker installed and configured for the project's ecosystem
2. Import sorting enabled (Ruff's I rules or Biome's organizeImports)
3. All five standard commands work: format, lint, typecheck, check, check:fix
4. Pre-commit hooks configured and executable (pre-commit run --all-files or npx lefthook run pre-commit)
5. Baseline autofix applied and a clean check passes with no errors