How the Build Process Is Managed in the no-mistakes Repository: A Complete Guide to the Makefile-Driven Workflow

The no-mistakes repository uses a single Makefile to orchestrate Go compilation, version embedding, cross-platform distribution, testing, linting, and documentation generation, ensuring reproducible builds from local development to CI releases.

The no-mistakes project relies on a conventional Make-driven workflow that centralizes all build operations. This approach ties together Go compilation, embedded version metadata, and distribution packaging into a transparent, extensible pipeline defined entirely in the root Makefile.

Version Embedding and Build Metadata

How Git Data Injects into Binaries

The build process automatically computes version information from Git and injects it into every binary. In the Makefile, the variables VERSION, COMMIT, and DATE are derived from Git state and passed to the Go linker via -ldflags.

These values populate the variables in internal/buildinfo:

• Version
• Commit
• Date
• TelemetryHost
• TelemetryWebsiteID

This ensures every executable carries accurate build metadata for debugging and telemetry purposes.

Core Build Targets

Compiling the Binary

The primary build target compiles the CLI entry point located at cmd/no-mistakes/main.go.

make build

This command runs go build with the LDFLAGS containing version information and writes the executable to bin/no-mistakes. This is the standard target for local development.

Cross-Platform Distribution

For releases, the dist target iterates over a predefined list of OS/architecture tuples.

make dist

The process sets GOOS and GOARCH for each target, disables CGO to produce static binaries, and packages Linux and macOS binaries as tarballs while Windows binaries are zipped. This creates distributable artifacts for all supported platforms without requiring platform-specific build machines.

Local Installation

The install target automates local deployment.

make install

This first builds the binary, then copies it to $GOPATH/bin/no-mistakes, and finally restarts the daemon by executing daemon stop followed by daemon start.

Testing and Quality Assurance

Unit and Integration Testing

Fast feedback during development comes from the standard test target.

make test

This executes go test -race ./..., running unit tests and integration tests while enabling the race detector. The end-to-end suite is excluded from this target to maintain speed.

End-to-End Testing

The e2e target validates the full push-pipeline flow against a fake agent.

make e2e

This runs go test -tags=e2e ..., driving the actual CLI and verifying integration points. This suite is significantly slower than standard tests and is typically reserved for CI or pre-release validation.

Fixture Re-recording

When API responses change, the e2e-record target refreshes stored fixtures.

make e2e-record

This runs the recordfixture command for each supported agent (claude, codex, opencode), incurring real API usage. The target is gated explicitly to prevent accidental execution during standard development.

Code Generation and Validation

Skill Markdown Generation

The repository maintains human-readable skill documentation generated from source constants.

make skill

This regenerates skills/no-mistakes/SKILL.md from the source constant defined in internal/skill/skill.go. The companion skill-check target validates that the committed skill file matches the source code and is automatically invoked by the lint target.

Linting and Static Analysis

The lint target enforces code quality and documentation consistency.

make lint

This first runs skill-check to detect drift in the generated skill file, then executes go vet ./... to catch static analysis issues. This ensures both code correctness and documentation synchronization.

Formatting

Canonical Go formatting is enforced via:

make fmt

This runs gofmt -w . to automatically format all Go source files in the repository.

Documentation and Media

Documentation Site

The project uses an Astro-based documentation site located in the docs directory.

make docs

This builds the production site after installing npm dependencies. For local development, make docs-preview runs a development server with hot reloading.

Demo Media Generation

The README contains demo GIFs and MP4s generated from code.

make demo

This rebuilds the media assets using vhs and ffmpeg, ensuring the visual documentation stays synchronized with the actual CLI behavior.

Cleanup

Remove generated artifacts with:

make clean

This deletes the bin/ directory containing compiled binaries and distribution archives.

Summary

• The build process is centralized in a single Makefile that orchestrates all development tasks.
• Version metadata is extracted from Git and injected via -ldflags into internal/buildinfo variables.
• Cross-platform releases are built via make dist, which produces static binaries for multiple OS/architecture combinations.
• Quality assurance combines make test for fast unit checks and make e2e for full integration validation.
• Generated artifacts include the skill markdown (make skill) and documentation site (make docs), both validated during linting.

Frequently Asked Questions

How does the no-mistakes build process embed version information?

The Makefile computes VERSION, COMMIT, and DATE from Git state. These values are passed to the Go compiler via -ldflags and stored in the internal/buildinfo package variables (Version, Commit, Date, TelemetryHost, TelemetryWebsiteID). This ensures every binary contains accurate build metadata accessible at runtime.

What is the difference between make test and make e2e?

make test runs go test -race ./..., executing unit and integration tests with the race detector enabled but excluding end-to-end tests for speed. make e2e runs the tagged suite go test -tags=e2e ..., which drives the actual CLI against a fake agent to validate the complete push-pipeline flow. Use make test for rapid feedback during development and make e2e for pre-release validation.

How does the repository handle cross-platform releases?

The make dist target iterates over a list of OS/architecture tuples, setting GOOS and GOARCH for each build while disabling CGO to create static binaries. Linux and macOS binaries are archived as tarballs, while Windows binaries are packaged as zip files. This produces distribution-ready artifacts for all supported platforms from a single build environment.

What triggers the skill-check during the build process?

The skill-check target compares the generated skills/no-mistakes/SKILL.md file against the source constant in internal/skill/skill.go. It is automatically invoked as the first step of make lint, ensuring that any modification to the skill source code is reflected in the documentation before code passes the linting stage.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}