blockwatch
Use when writing or modifying code in a project that uses BlockWatch — proactively link co-dependent code with `<block affects=...>`/`<block name=...>` so it catches drift when one side changes without the other (an enum and its docs, a constant and its config), or assert two places hold the same value with `<block same-as=...>`. Also for lists that must stay sorted/unique or values with a strict format/size, and when editing files that contain `<block ...>` tags (affects, same-as, keep-sorted, keep-unique, line-pattern, line-count, check-ai, check-lua).
mennanov · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add mennanov/blockwatch --skill blockwatch技能说明
name: blockwatch
description: Use when writing or modifying code in a project that uses BlockWatch — proactively link co-dependent code with <block affects=...>/<block name=...> so it catches drift when one side changes without the other (an enum and its docs, a constant and its config), or assert two places hold the same value with <block same-as=...>. Also for lists that must stay sorted/unique or values with a strict format/size, and when editing files that contain <block ...> tags (affects, same-as, keep-sorted, keep-unique, line-pattern, line-count, check-ai, check-lua).
BlockWatch
BlockWatch is a language-agnostic linter that enforces rules declared inside HTML-like <block ...> tags placed in
source-file comments. It works across Rust, Python, JS/TS, Go, Java, Markdown, YAML, TOML, HTML, and more. By default it
checks the whole tree; given a git diff on stdin it can instead check only the blocks that diff changed.
Use this skill in three situations:
- As you write code (the default): the moment you write something a block would guard, add the block in the same change — don't wait for a separate pass.
- First-time / bulk pass: annotating an existing project that has no blocks yet.
- Maintaining blocks: keeping existing blocks valid when you edit files that already contain them.
Two rules apply to all three:
- High-value only. A block must catch a real mistake someone could plausibly make, not decorate. Too many blocks create noise and get ignored. When in doubt, leave it out.
- Only in projects that use BlockWatch. This skill being installed, or existing
<block>tags in the tree, means the project opted in. Don't add blocks to a project that doesn't use the tool.
Annotate as you write code
This is the primary way blocks should get added: incrementally, as part of normal coding. Whenever you write or change code matching a row in Where blocks add value (below), add the tag right then, using the Validator reference for the syntax.
Introduce a list that should stay ordered → wrap it in keep-sorted in the same edit. Add a fact that also lives in the
docs or config → add affects in the same edit. Retrofitting later is exactly the cost this avoids.
Then run git diff --patch | blockwatch --diff --only-changed to confirm the new tags pass (see Running and
verifying).
Annotating a new project
- Survey the repo for the patterns in the catalog below. Read the code and the docs/config; use
rg/grep to find lists, enums, match arms, tables, and constants. - For each candidate, add the minimal block tag using the comment syntax of that file's language.
- Run
blockwatch listto confirm every new tag parses and is recognized, then runblockwatchto confirm all blocks pass on the current (clean) tree. Fix any tag you placed on already-inconsistent content. - Commit, then wire BlockWatch into hooks/CI (see below) so the rules are enforced from now on.
Where blocks add value (catalog)
| You see... | Add | Why |
|---|---|---|
| A hand-maintained list/enum/match that should stay ordered (dependencies, CLI flags, feature lists, route tables) | keep-sorted | Eliminates "please sort this" review nits |
| A list that must not repeat (allowlists, IDs, registered names) | keep-unique | Prevents accidental duplicates |
| The same fact in two places — an enum and its docs, a version constant and a changelog row, a config key and its README table | affects + name | Forces docs/config to be updated alongside code |
| The same value duplicated across places — a constant and its docs, a port in code and in a manifest, an env-var set and its README table | same-as + name | Fails when the copies actually disagree, not just when one side is touched |
| A list whose items have a strict format (slugs, semver, env-var names) | line-pattern="<regex>" | Catches typos at the source |
| A block that must not grow past N lines (public API surface, a switch mapped to a fixed enum) | line-count="<=N" | Flags unbounded growth |
| Prose or config with a natural-language rule ("must mention X", "no TODOs left") | check-ai="..." | Rules regex can't express |
| Domain logic too complex for regex | check-lua="script.lua" | Custom programmable checks |
Prefer the deterministic validators (keep-sorted, keep-unique, affects, same-as, line-pattern, line-count)
first — they are free, fast, and need no API keys. Reserve check-ai for rules the cheaper validators genuinely can't
express.
When two blocks should hold the same value, prefer same-as over a bare affects: affects only notices that o