Engineering Baseline

Engineering Baseline is a portable repo starter kit and quality CLI for teams that want practical engineering standards without adopting a heavyweight platform. It packages documentation norms, test discipline checks, formatting gates, starter templates, and agent-friendly project guidance into a small reusable toolkit.

The project exists for a common open-source problem: every new repository needs a working definition of "done", but copying those expectations by hand is tedious and inconsistent. Engineering Baseline makes those expectations explicit, versioned, testable, and easy to reuse.

What This Project Accomplishes

Engineering Baseline gives a repo a clear starting shape:

• a starter README.md, AGENTS.md, napkin.md, and baseline config
• documentation policies for durable project knowledge
• testing policies that discourage low-value or misleading tests
• AI collaboration guidance for coding agents and human reviewers
• Git hooks and CI-friendly commands for quality checks
• a baseline CLI for initialization, sync, and verification

The result is a small operating system for a repository. It helps contributors understand where decisions live, what checks matter, how automation should behave, and how to keep a codebase reviewable as it grows.

Community Value

Open-source projects often struggle less from a lack of code and more from a lack of shared expectations. New contributors may not know:

• which docs are canonical
• how to introduce a change safely
• where to put temporary notes
• when tests are expected
• which generated files should stay out of review
• what an AI coding agent is allowed to change

Engineering Baseline turns those expectations into files and checks that can travel from repo to repo. Community maintainers can adopt the whole baseline, copy the policy docs, or study the CLI patterns for their own governance tooling.

The project is intentionally pragmatic. It does not try to define a universal engineering culture. It provides a concrete, editable baseline that favors clarity, reviewability, repeatable checks, and small documented decisions.

Repository Layout

• packages/cli/ contains the reusable baseline CLI.
• templates/starter/ contains the files seeded into new repositories.
• docs/ contains the policy and design documents behind the baseline.
• examples/ shows how the baseline applies to different repo shapes.
• .github/workflows/ contains CI and release workflows.

The Baseline CLI

The CLI is published as @m-rousseau/repo-baseline and exposes the baseline command.

Core commands:

baseline init
baseline sync
baseline check --changed --write
baseline check --all

baseline init adds the starter files to a new repo and configures Git hooks.

baseline sync updates managed template files when a consumer intentionally wants to adopt template changes.

baseline check --changed --write is designed for local development. It focuses on changed files and applies safe formatting fixes where supported.

baseline check --all is designed for full-repo verification in CI or before release.

What The Checks Cover

The baseline currently includes:

• documentation governance for required root docs and canonical docs folders
• Biome checks for JavaScript and TypeScript projects
• optional TypeScript typecheck lanes
• optional Python subtree checks through Ruff
• report-mode unused-file/dependency checks through Knip
• test-discipline checks that flag patterns such as tests with no assertions, placeholder-only tests, and broad smoke tests pretending to prove behavior
• template parity checks to ensure packaged starter files match the repo templates

The checks are intentionally lightweight. They are guardrails, not a replacement for design review, domain tests, or human judgment.

Adoption Model

There are two common adoption paths.

For a new repo:

pnpm add -D @m-rousseau/repo-baseline
pnpm exec baseline init
pnpm exec baseline check --all

For an existing repo:

1. Add the package.
2. Run baseline init or copy the starter files manually.
3. Tune baseline.config.json for the repo shape.
4. Start with changed-file checks locally.
5. Add full-repo checks to CI once the repo is clean enough.

See docs/adoption-lifecycle.md for upgrade and sync guidance.

Package Consumption

The package is configured for GitHub Packages:

pnpm add -D @m-rousseau/repo-baseline@<version>

Depending on package visibility and organization settings, GitHub Packages may require npm registry authentication even for normal installs. If authentication is required, configure the @m-rousseau npm scope for https://npm.pkg.github.com and use a token with read:packages.

CI consumers can either use package access granted through GitHub repository settings or provide a GH_PACKAGES_TOKEN secret. The starter workflow supports both paths.

Development

Install dependencies:

pnpm install

Run tests:

pnpm test

Run the full baseline check:

pnpm run check

Run the full verification lane:

pnpm run test:all

Project Status

Engineering Baseline is being dogfooded in real repositories before broader reuse. The CLI and templates are intentionally small, but the repo already includes the core pieces needed to bootstrap and verify a practical baseline.

Near-term improvement areas include clearer public package setup, more examples, expanded language-specific lanes, stronger release notes, and more migration guidance for mature repositories.

Open Source Use

This repository is meant to be copied, adapted, and debated. If your project has different standards, the useful part may be the structure: write the expectations down, put them in version control, make the checks cheap to run, and keep the baseline understandable enough that contributors can reason about it.

License

Engineering Baseline is released under the MIT License. See LICENSE.