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

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): 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): Connects to Claude, Codex, Rovo Dev, OpenCode, Copilot, and ACP agents.
• Configuration (internal/config/config.go): Loads .no-mistakes.yaml and enforces security with trusted default-branch configurations.
• Database (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): Provides the interactive terminal UI (no-mistakes) and non-interactive TOON interface (axi) for agents.
• Documentation generation (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 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:

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:

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:

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.

3. Make Changes and Commit Locally

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

make fmt && make lint

Commit your changes normally:

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

4. Push Through the Validation Pipeline

Instead of git push origin, push through the gate:

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
• 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
• Opens a PR against the upstream repository using 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:

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, 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 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:

# 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:

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), implement the Agent interface, and register it in internal/agent/agent.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: 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, review.go, test.go, lint.go, push.go, pr.go, and ci.go.
• internal/daemon/manager.go: Coordinates the detached worktree and run lifecycle.
• 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, internal/daemon/manager.go, and internal/agent/claude.go.
• Follow 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 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), implement the Agent interface with methods like Name(), Prompt(), and Stream(), then register it in internal/agent/agent.go. The existing Claude implementation in 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 for how the daemon coordinates these runs in isolated worktrees.

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