# How to Contribute to the no-mistakes Project: A Complete Guide to the AI-Driven Git Workflow

> Learn how to contribute to the no-mistakes AI-driven Git workflow. This guide shows how to use the tool as a Git proxy for automated validation and PR creation.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: how-to-guide
- Published: 2026-06-28

---

**Contributing to no-mistakes requires using the tool itself as a git proxy, where every push runs through an AI-driven validation pipeline that auto-fixes issues, validates changes, and opens pull requests automatically.**

The no-mistakes repository implements a Go CLI that functions as a git proxy, enforcing a rigorous AI-driven validation pipeline before any changes reach the remote. Since the project uses its own gate mechanism to ensure code quality, contributors must follow a specialized workflow that mirrors the tool's enforcement philosophy. This guide walks you through the exact steps to contribute to the no-mistakes project using the same pipeline the tool enforces on all submissions.

## Understanding the no-mistakes Architecture

Before contributing, understanding the architecture helps navigate the codebase. The system consists of several key components:

- **CLI entrypoint** (`cmd/no-mistakes`): Parses flags, boots the daemon, and launches the TUI.
- **Daemon** ([`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go)): Runs a detached work-tree and coordinates pipeline steps while isolating side-effects.
- **Pipeline** (`internal/pipeline/steps`): Executes the sequence `intent → rebase → review → test → document → lint → push → pr → ci`, where each step can produce findings that pause for human approval or trigger auto-fixes.
- **Agent integrations** (`internal/agent`, including [`internal/agent/claude.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/agent/claude.go)): Connects to Claude, Codex, Rovo Dev, OpenCode, Copilot, and ACP agents.
- **Configuration** ([`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go)): Loads [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) and enforces security with trusted default-branch configurations.
- **Database** ([`internal/db/run.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/run.go)): Persists run metadata, including awaiting-agent signals and SHA anchors for safe force-pushes.
- **TUI & AXI** ([`internal/tui/axi_render.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/tui/axi_render.go)): Provides the interactive terminal UI (`no-mistakes`) and non-interactive TOON interface (`axi`) for agents.
- **Documentation generation** ([`internal/skill/skill.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/skill.go)): Generates the `/no-mistakes` skill body that agents read.

## Contributing to no-mistakes: Step-by-Step Workflow

The repository's [`CONTRIBUTING.md`](https://github.com/kunchenguid/no-mistakes/blob/main/CONTRIBUTING.md) mandates that every contribution flow through the gate. Here's the complete workflow:

### 1. Fork and Clone the Repository

Start by creating a fork on GitHub and cloning it locally:

```bash
git fork https://github.com/kunchenguid/no-mistakes.git
git clone git@github.com:kunchenguid/no-mistakes.git
cd no-mistakes

```

Create a feature branch for your changes:

```bash
git checkout -b my-feature

```

### 2. Initialize the Gate Configuration

Before making changes, initialize the gate to point to your fork as the push target:

```bash
no-mistakes init --fork-url git@github.com:<you>/no-mistakes.git

```

The `no-mistakes init` command writes the gate configuration under `~/.no-mistakes/repos/…` and registers your fork as the destination. This configuration is managed in [`internal/wizard/wizard.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/wizard/wizard.go).

### 3. Make Changes and Commit Locally

Edit the Go code, documentation, or tests as needed. Keep the CI green by running linting locally:

```bash
make fmt && make lint

```

Commit your changes normally:

```bash
git add .
git commit -m "feat: improve XYZ"

```

### 4. Push Through the Validation Pipeline

Instead of `git push origin`, push through the gate:

```bash
git push no-mistakes

```

This triggers the full pipeline implemented in `internal/pipeline/steps`. The gate:
- Fetches remote refs and rebases onto the latest upstream (`origin/<default>`) via [`pipeline/steps/rebase.go`](https://github.com/kunchenguid/no-mistakes/blob/main/pipeline/steps/rebase.go)
- Runs the complete validation sequence including `intent`, `review`, `test`, `lint`, and `ci`
- Auto-fixes safe issues automatically
- Pushes the validated branch to your fork via [`pipeline/steps/push.go`](https://github.com/kunchenguid/no-mistakes/blob/main/pipeline/steps/push.go)
- Opens a PR against the upstream repository using [`pipeline/steps/pr.go`](https://github.com/kunchenguid/no-mistakes/blob/main/pipeline/steps/pr.go)

### 5. Handle Pipeline Findings

If the pipeline pauses—for example, when a review finding has `action: ask-user`—launch the interactive TUI:

```bash
no-mistakes

```

Approve, fix, or skip each finding. The tool commits any auto-fixes and continues automatically. The daemon persists run metadata in [`internal/db/run.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/run.go), including SHA anchors for safe force-pushes.

### 6. Review and Merge

The automatically generated PR contains:
- An `## Intent` section (if intent was inferred)

- A `## What Changed` summary

- Artifacts from the test step

The PR is created by [`pipeline/steps/pr.go`](https://github.com/kunchenguid/no-mistakes/blob/main/pipeline/steps/pr.go) using the GitHub CLI (`gh`). Once CI passes and the PR is approved, merge it in the upstream repository. The pipeline handles post-merge rebases automatically.

## Code Examples for Contributors

### Running the Gate Locally

Here's the quick-start workflow for local development:

```bash

# Initialise the gate targeting your fork

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

# After editing files

git add .
git commit -m "fix: improve error handling"
git push no-mistakes      # triggers the full pipeline

```

### Programmatically Invoking Pipeline Steps

You can invoke specific pipeline steps programmatically. For example, to rebase a branch:

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

func rebaseBranch(runID string) error {
    // `runID` identifies the active run in the daemon DB.
    // The Rebase step returns an error iff a conflict occurs.
    return steps.Rebase(runID)
}

```

### Adding a New Agent Implementation

To add a new AI agent, create a file in `internal/agent` (e.g., [`myagent.go`](https://github.com/kunchenguid/no-mistakes/blob/main/myagent.go)), implement the `Agent` interface, and register it in [`internal/agent/agent.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/agent/agent.go):

```go
type MyAgent struct{}
func (a *MyAgent) Name() string { return "myagent" }
// implement other required methods (Prompt, Stream, etc.)

```

## Key Files and Configuration References

When contributing, these files are essential:

- **[`CONTRIBUTING.md`](https://github.com/kunchenguid/no-mistakes/blob/main/CONTRIBUTING.md)**: Authoritative contribution workflow; mandates PRs via `no-mistakes`.
- **`Makefile`**: Contains build, test, lint, e2e, skill generation, and docs compilation targets.
- **`internal/pipeline/steps/**`**: Core pipeline implementations including [`rebase.go`](https://github.com/kunchenguid/no-mistakes/blob/main/rebase.go), [`review.go`](https://github.com/kunchenguid/no-mistakes/blob/main/review.go), [`test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/test.go), [`lint.go`](https://github.com/kunchenguid/no-mistakes/blob/main/lint.go), [`push.go`](https://github.com/kunchenguid/no-mistakes/blob/main/push.go), [`pr.go`](https://github.com/kunchenguid/no-mistakes/blob/main/pr.go), and [`ci.go`](https://github.com/kunchenguid/no-mistakes/blob/main/ci.go).
- **[`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go)**: Coordinates the detached worktree and run lifecycle.
- **[`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go)**: Handles repository configuration parsing and security checks.
- **`docs/src/content/docs/**`**: Full documentation site covering pipeline steps, concepts, and guides.

## Summary

- **no-mistakes** is a Go CLI that acts as a git proxy, requiring all contributions to pass through an AI-driven validation pipeline.
- **Initialize the gate** using `no-mistakes init --fork-url <your-fork>` before contributing.
- **Push through the gate** with `git push no-mistakes` instead of standard git push to trigger the `intent → rebase → review → test → document → lint → push → pr → ci` pipeline.
- **Handle findings** interactively via the TUI (`no-mistakes`) when the pipeline pauses for human approval.
- **Key source files** include [`internal/pipeline/steps/rebase.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/rebase.go), [`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go), and [`internal/agent/claude.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/agent/claude.go).
- **Follow [`CONTRIBUTING.md`](https://github.com/kunchenguid/no-mistakes/blob/main/CONTRIBUTING.md)** exactly, as the GitHub Actions check `Require no-mistakes` enforces this workflow.

## Frequently Asked Questions

### Do I need to install no-mistakes before contributing?

Yes, you must install the `no-mistakes` CLI locally and run `no-mistakes init` to configure the gate. The repository enforces this via the `Require no-mistakes` GitHub Actions check, which rejects direct pushes that bypass the validation pipeline.

### What happens if the pipeline finds an issue I disagree with?

The TUI (`no-mistakes`) allows you to approve, fix, or skip each finding. If you skip a finding, the pipeline continues but documents the override. The system in [`internal/db/run.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/run.go) tracks these decisions as part of the run metadata for audit trails.

### Can I contribute to the agent integrations or add new AI providers?

Yes, agent implementations live in `internal/agent/`. Create a new file (e.g., [`myagent.go`](https://github.com/kunchenguid/no-mistakes/blob/main/myagent.go)), implement the `Agent` interface with methods like `Name()`, `Prompt()`, and `Stream()`, then register it in [`internal/agent/agent.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/agent/agent.go). The existing Claude implementation in [`internal/agent/claude.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/agent/claude.go) serves as the reference pattern.

### How do I debug a failed pipeline step locally?

Run the specific step programmatically using the `internal/pipeline/steps` package. Each step function accepts a `runID` string that identifies the active run in the daemon database. Check [`internal/daemon/manager.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go) for how the daemon coordinates these runs in isolated worktrees.