Development Workflow for Contributors to no-mistakes: Step-by-Step Guide

The development workflow for contributors to no-mistakes requires using a specialized Git proxy called "the gate" that intercepts pushes, runs an AI-driven validation pipeline with stages for review, test, docs, and lint, and automatically creates pull requests only after all checks pass.

The no-mistakes repository enforces a unique contribution model that prevents unvalidated code from reaching upstream. Instead of pushing directly to your fork, you route changes through a local Git proxy that performs automated reviews, tests, and linting before forwarding commits. This workflow ensures every pull request meets the repository's quality standards through deterministic pipeline stages defined in CONTRIBUTING.md.

How the no-mistakes Gate Works

The Git Proxy Architecture

Unlike standard Git workflows where you push to origin, the no-mistakes tool creates a gate remote that intercepts your pushes. According to CONTRIBUTING.md, this design ensures the AI validation pipeline runs before any code reaches the upstream repository. The gate stores temporary worktrees under $NM_HOME and only forwards branches after the pipeline succeeds.

Pipeline Stages

The validation pipeline consists of deterministic stages: review → test → docs → lint → push → PR → CI. As implemented in internal/pipeline/, each stage either succeeds automatically or produces a finding that requires contributor action. Safe mechanical fixes are applied automatically, while changes affecting author intent generate "ask-user" findings for manual review.

Step-by-Step Development Workflow

Fork and Clone the Upstream Repository

Begin by forking the repository on GitHub, then clone the parent repository—not your fork. This ensures origin points to the upstream source, which is required for the proxy to forward changes correctly.

git clone git@github.com:kunchenguid/no-mistakes.git
cd no-mistakes

Initialize the Gate

Run no-mistakes init to create a local gate—a disposable worktree that serves as a temporary remote. If you specify --fork-url, the tool knows where to push successful branches.

no-mistakes init --fork-url git@github.com:yourusername/no-mistakes.git

This command also installs the /no-mistakes skill for coding agents, as documented in AGENTS.md.

Create a Feature Branch

Create and switch to a new branch for your changes:

git checkout -b my-feature

Make Changes and Optional Local Checks

Edit code, add tests, and update documentation. Before pushing through the gate, you can run local validation using the Makefile targets:

make fmt      # Run gofmt on the code

make lint     # Execute go vet plus skill-drift checks

make test     # Run unit tests with race detection

make e2e      # Execute full end-to-end test suite

Push Through the Gate

Instead of git push origin, push to the no-mistakes remote created during initialization:

git push no-mistakes

This triggers the AI-driven validation pipeline in internal/pipeline/. The gate blocks the push until all stages complete.

Review Findings in the TUI

Launch the interactive terminal UI to review pipeline results:

no-mistakes

As documented in README.md, this attaches to the active run and displays findings categorized as auto-fixable or ask-user. You can approve, fix, or skip each finding directly in the interface.

Automated PR Creation

Once the pipeline completes successfully, the gate automatically pushes the branch to your fork and opens a pull request against the upstream repository. No manual git push origin or PR body creation is required. The resulting PR carries a deterministic signature that satisfies the "Require no-mistakes" GitHub Action check.

Agent-Driven Workflow

Contributors can also execute the entire workflow headlessly using the /no-mistakes skill inside coding agents like Claude or Codex. The skill invokes the same pipeline via no-mistakes axi, as specified in AGENTS.md. This mode is useful for automated refactoring or batch updates where interactive TUI usage is not desired.

Summary

• Clone upstream, not your fork: The no-mistakes proxy requires origin to point at the upstream repository.
• Initialize the gate: Use no-mistakes init --fork-url to create the validation remote.
• Push to no-mistakes, not origin: The gate intercepts pushes to run the AI pipeline.
• Review findings interactively: Use the TUI to handle auto-fixable and ask-user findings.
• Automated PR creation: Successful pipeline runs automatically create PRs with deterministic signatures.
• Agent support: Use /no-mistakes skill or no-mistakes axi for headless execution.

Frequently Asked Questions

Why must I clone the upstream repository instead of my fork?

The no-mistakes gate forwards validated changes to your fork only after the pipeline succeeds. By cloning the upstream repository and initializing the gate, you ensure the proxy can correctly route changes from the temporary worktree in $NM_HOME to your fork's remote URL specified during no-mistakes init.

What happens if the pipeline finds issues I don't want to fix?

The TUI presents findings as either auto-fixable or ask-user. You can skip ask-user findings if they don't align with your intent, though the pipeline may block PR creation if critical checks fail. The gate gives you control over mechanical changes while enforcing repository standards through internal/pipeline/ logic.

Can I use standard Git commands like git push origin?

No. Pushing to origin bypasses the required validation pipeline. You must push to the no-mistakes remote created by no-mistakes init. This remote routes your changes through pipeline stages (review, test, docs, lint) before they reach any public repository.

How do I run the workflow without the interactive TUI?

Use the agent skill with no-mistakes axi as documented in AGENTS.md. This headless mode runs the same pipeline stages but outputs results to the console, suitable for CI environments or automated agent workflows where the TUI cannot be displayed.

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