blockwatch: Instructions file for Codex

AGENTS.md

This file tells AI coding agents how to work in this repository. Every agent reads the same file. CLAUDE.md is a symlink to it, because Claude Code only looks for CLAUDE.md.

Project

blockwatch is a linter written in Rust and published on crates.io. It works with any language. Rules are written as HTML-like <block ...> tags inside code comments, and blockwatch checks them. It can check the whole repository, or only the lines changed in a unified diff piped into it.

Common commands

cargo run -- list '<path or glob>'         # print the blocks parsed from matching files, as JSON
cargo llvm-cov                             # run the tests and report coverage
cargo clippy --all-targets -- -D warnings  # lint
cargo test --doc                           # run the examples in the doc comments (cargo llvm-cov skips them)
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --document-private-items  # check the doc comments
markdownlint-cli2                          # lint Markdown (config: .markdownlint-cli2.yaml)
pre-commit run --all-files                 # run every hook the repository installs

Fuzzing lives in fuzz/. It needs the nightly toolchain and cargo-afl. See fuzz/README.md.

Integration tests use assert_cmd to run the built binary on the fixtures in tests/testdata/. Many of them also pipe a made-up diff into stdin. When you add a test, follow the pattern in tests/<validator>.rs. Build the command with common::cargo_bin_cmd!. It passes an empty config, because this repository's blockwatch.toml skips tests/testdata/. Clippy rejects assert_cmd::cargo_bin_cmd!, so a test can't read that file by mistake.

Rules for agents

You must follow every rule below, at all times.

Writing style

These rules apply to everything you write, with no exceptions: code comments, doc comments, --help text, error messages, docs, CHANGELOG.md, commit messages, and your replies to the human in chat.

• Always write so that each sentence is understood on the first read. If a sentence needs a second read, split it or say it more simply.
• Always use short sentences, one idea each, and everyday words.
• Always say the concrete thing. Name the file, flag or value instead of describing it in the abstract.
• Always say what happens, such as what passes or fails, rather than naming a property like "order-insensitive".
• Never use jargon or formal framing, such as "hold for", "as opposed to", "govern" or "self-describes". Use the plain word instead.
• Prefer an example when it is shorter than the explanation.
• Prefer a short list or a table to a long sentence with several clauses.