BlockWatch: Catch Cross-File Drift Before It Ships

Where this fits

You change a status enum in Rust, update the matching YAML config, but forget the Markdown docs. CI passes, and users see stale values. BlockWatch solves this by letting you declare dependencies inside HTML-like <block ...> tags in comments. When one side changes, the linter flags the other side before the PR lands. For agents, this turns hidden cross-file assumptions into explicit, checkable rules.

Why agents benefit

• While writing an enum and its docs, an agent can add <block affects=...> and <block name=...> in the same change — no separate annotation pass needed.
• For values that must match across files, <block same-as=...> lets an agent assert equivalence without running the app.
• For lists that need consistent ordering, keep-sorted and keep-unique tags give automatic checks instead of manual reasoning.
• For values with strict shapes, line-pattern and line-count validate formats, sizes, and regex constraints directly in lint output.
• When editing files that already contain block tags, the agent treats them as guardrails and updates dependent blocks, reducing regressions.

Practical scenarios

Enum docs catch fire after a rename

A Rust enum gains a new variant. The docs table in README.md lists all variants, but nobody updates it. Add a named block around the enum and a matching affects block in the docs; the next run flags the mismatch immediately.

Dual-source constant drift

A Python backend default and a TypeScript UI constant must stay identical. Wrap both with <block same-as=...>; when the backend changes, the agent sees the failure and updates the frontend in the same pull request.

Feature list ordering breaks review

A YAML or Markdown list must remain sorted and unique. Apply keep-sorted and keep-unique tags so agents can safely insert new entries and verify the whole list stays valid.

Add it to your agent workflow

Install the skill with:

npx skills add mennanov/blockwatch --skill blockwatch

Then instruct your agent to add blocks in the same change that introduces the dependency. For example, when editing a Markdown file that documents a value defined elsewhere:

<!-- <block affects="src/status.py" name="status-docs" /> -->

The agent can run BlockWatch on the final diff and fix any violations before finishing.

Compare before adopting

Evaluate how BlockWatch fits your stack: does it parse your main languages and support diff-only checks? Check maintenance freshness — recent commits and issue activity — and compare against alternatives like code generation, generated docs, or dedicated schema tests. Most importantly, assess workflow fit: can your agent run it in CI, pre-commit, or as a review tool without adding friction?

Why it is worth tracking

With 29 stars, BlockWatch is not the loudest project, but its approach is pragmatic: comment-local invariants work in any language and keep dependencies visible at the exact edit sites. It is worth evaluating when your agents routinely touch enums, configs, and docs, and cross-file drift keeps appearing. Its diff-aware mode makes it especially promising for agent loops. For a fuller profile and related skills, see https://www.openagentskill.com/skills/mennanov-blockwatch.