seiso

A Markdown convention and linter for project docs written by AI and read by humans and agents.

Hardly anyone writes project docs by hand anymore. AI writes most of them, and coding agents read them as context as often as people do. Both kinds of reader take the page at its word, so a stale version number or a field list updated in only one of its three copies misleads all of them. AI writes docs faster than anyone can review them, and it makes the same few mistakes every time.

seiso defines one convention for how Markdown in a repository is organized, so projects can follow the same rules without agreeing on them first, the way rustfmt settled formatting for Rust code.

The convention

• Every document declares one kind, such as howto, reference, or adr, and holds only what that kind is for. A how-to gives the steps. Why the design looks this way belongs in an ADR.
• Each fact has one home. Other pages link to it instead of retelling it.
• Long-lived pages don't record values that change faster than the page, such as versions, deployment status, or counts.
• A pointer names a file or symbol, so the reader doesn't have to search for what the sentence promised.
• The finished page doesn't address whoever asked for it or narrate how it was made.
• Judgment calls a tool can't make are written down with a reason. An exception without one is itself a violation.

seiso checks documents against this convention. Each diagnostic says where the problem is and how to fix it, so an agent can repair the page from seiso's output alone. seiso doesn't guess whether prose sounds machine-written, and it leaves formatting and spelling to other tools. The convention defines each kind's contract and the evidence a diagnostic can claim.

Install

cargo install seiso
uv tool install seiso    # or: pipx install seiso
npm install -g @scarletkc/seiso

The PyPI and npm packages include prebuilt binaries for Linux x64 and Windows x64. Other platforms build from source, which requires a Rust toolchain. From a source checkout, run cargo run -p seiso -- <command>.

Quick start

From the repository root:

seiso init
seiso check

seiso init writes a seiso.toml with suggested kind mappings; review them before relying on the results. Default checks use accepted stable rules; --preview adds selected preview rules. seiso rule <CODE> explains a rule with examples, and seiso parse inspects the document model without running rules.

Documentation

• Checking documents: configuration, rule selection, and output formats
• Integrations: Claude Code hooks, pre-commit, and CI
• Development: building, testing, and validation commands
• Architecture: command execution
• Roadmap: proposed features and milestone evidence
• Documentation index: guides, references, and evaluation records
• Contributing: issues, branches, commits, and pull requests

License

seiso is licensed under MIT.