← back to Exo

Add pre-commit checks documentation to AGENTS.md (#1184)

c5158bee5302f7a425ef59157ed8174899e497d2 · 2026-01-17 21:50:24 +0000 · Alex Cheema

## Motivation

CI failures can be avoided by running checks locally before committing.
This adds clear documentation to AGENTS.md so that AI agents (and
humans) know exactly which checks must pass before pushing code.

## Changes

Added a new "Pre-Commit Checks (REQUIRED)" section to AGENTS.md that:
- Lists all 4 required checks (basedpyright, ruff, nix fmt, pytest)
- Provides a one-liner to run all checks in sequence
- Notes that `nix fmt` changes must be staged before committing
- Explains that CI runs `nix flake check` which verifies everything

## Why It Works

Clear documentation prevents CI failures by ensuring contributors run
checks locally first. The one-liner command makes it easy to run all
checks before committing.

## Test Plan

### Manual Testing
- Verified the documented commands work correctly

### Automated Testing
- N/A - documentation only change

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Files touched

• M AGENTS.md

Diff

commit c5158bee5302f7a425ef59157ed8174899e497d2
Author: Alex Cheema <41707476+AlexCheema@users.noreply.github.com>
Date:   Sat Jan 17 21:50:24 2026 +0000

    Add pre-commit checks documentation to AGENTS.md (#1184)
    
    ## Motivation
    
    CI failures can be avoided by running checks locally before committing.
    This adds clear documentation to AGENTS.md so that AI agents (and
    humans) know exactly which checks must pass before pushing code.
    
    ## Changes
    
    Added a new "Pre-Commit Checks (REQUIRED)" section to AGENTS.md that:
    - Lists all 4 required checks (basedpyright, ruff, nix fmt, pytest)
    - Provides a one-liner to run all checks in sequence
    - Notes that `nix fmt` changes must be staged before committing
    - Explains that CI runs `nix flake check` which verifies everything
    
    ## Why It Works
    
    Clear documentation prevents CI failures by ensuring contributors run
    checks locally first. The one-liner command makes it easy to run all
    checks before committing.
    
    ## Test Plan
    
    ### Manual Testing
    - Verified the documented commands work correctly
    
    ### Automated Testing
    - N/A - documentation only change
    
    Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
---
 AGENTS.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index ec3a3b19..f9e16397 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -40,6 +40,31 @@ uv run ruff check
 nix fmt
 ```
 
+## Pre-Commit Checks (REQUIRED)
+
+**IMPORTANT: Always run these checks before committing code. CI will fail if these don't pass.**
+
+```bash
+# 1. Type checking - MUST pass with 0 errors
+uv run basedpyright
+
+# 2. Linting - MUST pass
+uv run ruff check
+
+# 3. Formatting - MUST be applied
+nix fmt
+
+# 4. Tests - MUST pass
+uv run pytest
+```
+
+Run all checks in sequence:
+```bash
+uv run basedpyright && uv run ruff check && nix fmt && uv run pytest
+```
+
+If `nix fmt` changes any files, stage them before committing. The CI runs `nix flake check` which verifies formatting, linting, and runs Rust tests.
+
 ## Architecture
 
 ### Node Composition

← 5c8a2379 Handle model timeouts (#1177)  ·  back to Exo  ·  Add proxy and custom SSL certificate support for corporate 9c29eb7d →