How to Contribute to the no-mistakes Project: Complete Developer Guide

To contribute to the no-mistakes project, fork the repository, initialize the contribution gate with your fork URL, and push changes through the AI-driven validation pipeline that automatically handles rebasing, testing, and pull request creation.

The no-mistakes repository implements a Go-based CLI that functions as a git proxy, enforcing a strict validation pipeline before any code reaches the remote. Because the project uses itself as the contribution gate, every pull request must pass through the same automated checks that the tool provides to users.

Fork and Clone the Repository

Start by creating your own fork of the repository on GitHub, then clone it locally:

git clone git@github.com:<your-username>/no-mistakes.git
cd no-mistakes

Create a feature branch for your changes:

git checkout -b my-feature

This fork URL serves as the push target for the validation gate, which you will configure in the next step.

Initialize the Contribution Gate

Before making changes, initialize the no-mistakes gate to point to your fork. This writes the configuration under ~/.no-mistakes/repos/ and registers your fork as the remote target:

no-mistakes init --fork-url git@github.com:<your-username>/no-mistakes.git

The initialization logic resides in internal/wizard/wizard.go, which sets up the daemon configuration and validates the repository structure.

Understanding the Validation Pipeline

The contribution workflow relies on a pipeline defined in internal/pipeline/steps that processes every commit through a strict sequence:

1. Intent – Captures the purpose of the change.
2. Rebase – Automatically rebases onto the latest upstream default branch (internal/pipeline/steps/rebase.go).
3. Review – AI-driven code review with findings that may pause for approval.
4. Test – Runs the test suite in an isolated worktree managed by internal/daemon/manager.go.
5. Document – Updates or validates documentation.
6. Lint – Code quality checks.
7. Push – Pushes the validated branch to your fork (internal/pipeline/steps/push.go).
8. PR – Automatically opens a pull request against upstream (internal/pipeline/steps/pr.go).
9. CI – Final continuous integration checks.

The Daemon (internal/daemon/manager.go) coordinates this pipeline in a detached worktree, isolating side effects and persisting run metadata via internal/db/run.go.

Push Your Changes Through the Gate

After editing files, stage and commit your changes normally:

git add .
git commit -m "feat: add new validation step"

Instead of pushing to origin, push to the no-mistakes remote:

git push no-mistakes

This triggers the full pipeline. If the pipeline pauses due to review findings requiring human approval, launch the interactive TUI:

no-mistakes

Approve, fix, or skip each finding. The tool commits any auto-fixes and continues automatically.

Architecture Components for Contributors

When contributing to the no-mistakes project, understanding these key components helps navigate the codebase:

• cmd/no-mistakes – CLI entrypoint that parses flags and boots the daemon.
• internal/agent/ – AI agent integrations including Claude, Codex, Rovo Dev, OpenCode, Copilot, and ACP (internal/agent/claude.go).
• internal/config/config.go – Loads .no-mistakes.yaml and enforces security policies including trusted default-branch configuration.
• internal/tui/ – Interactive terminal UI and the non-interactive AXI interface for agents (internal/tui/axi_render.go).
• internal/skill/skill.go – Generates the /no-mistakes skill body that agents reference.

You can also invoke pipeline steps programmatically for testing or custom scripts:

import "github.com/kunchenguid/no-mistakes/internal/pipeline/steps"

func rebaseBranch(runID string) error {
    // runID identifies the active run in the daemon DB
    // Returns error only if a conflict occurs
    return steps.Rebase(runID)
}

To add a new agent implementation, create a file in internal/agent implementing the Agent interface and register it in internal/agent/agent.go.

Local Development and Testing

Before pushing through the gate, run local checks to keep CI green:

make fmt
make lint

The Makefile also provides targets for building, end-to-end testing, and skill generation. The repository's CONTRIBUTING.md contains the authoritative workflow documentation.

The GitHub Actions check Require no-mistakes enforces that all contributions arrive via the gate, preventing direct pushes that bypass the validation pipeline.

Summary

• Fork the repository and initialize the gate with no-mistakes init --fork-url <your-fork>.
• Use git push no-mistakes instead of standard git push to trigger the validation pipeline.
• The pipeline automatically handles rebasing, testing, linting, and opening pull requests.
• Interact with paused pipelines via the no-mistakes TUI when findings require approval.
• Keep local code quality high using make fmt and make lint before triggering the gate.
• All changes must pass through the gate enforced by the GitHub Actions check.

Frequently Asked Questions

Do I need to install the no-mistakes CLI before contributing?

Yes. You must have the no-mistakes binary installed locally to initialize the contribution gate and push changes through the validation pipeline. The tool acts as a git proxy that intercepts pushes and runs the necessary checks before forwarding commits to your fork, as implemented in cmd/no-mistakes.

What happens if the pipeline finds issues with my code?

The pipeline may pause and display findings in the TUI if it encounters issues requiring human judgment. You can approve changes, apply auto-fixes, or skip specific findings. Safe issues are automatically fixed and committed by the pipeline logic in internal/pipeline/steps, while complex issues may require manual intervention before the PR is created.

Can I push directly to the upstream repository without using the gate?

No. The repository enforces the Require no-mistakes GitHub Actions check, which rejects any pull request not created through the gate. This ensures every contribution receives the same automated validation, including AI review, testing, and documentation checks that the pipeline provides.

How do I add support for a new AI agent?

Create a new file in internal/agent (e.g., myagent.go) and implement the Agent interface with methods like Name(), Prompt(), and Stream(). Register your agent in internal/agent/agent.go to make it available to the pipeline. Follow the existing implementations in internal/agent/claude.go as reference patterns for integrating with agent APIs.

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