seiso

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

AI writes project docs faster than anyone can review them, and coding agents read those docs back as context for the next change. People and agents alike 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. And AI makes the same few mistakes over and over.

seiso defines one convention for how Markdown in a repository is organized, the way rustfmt settled formatting for Rust code. Projects share the rules instead of negotiating their own; each project mainly maps its documents to kinds, and seiso init suggests a starting point.

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's rules check documents against this convention; stable rules run by default, and the rest are opt-in previews. Each diagnostic says where the problem is and how to fix it, so an agent can repair most findings from seiso's output alone. When a fix needs a judgment, such as which of two pages owns a fact, the diagnostic names the decision. 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 macOS on Apple silicon and Intel, Linux x64 and arm64 with glibc, and Windows x64. On other platforms, including musl-based Linux such as Alpine, use cargo; the PyPI package also works there but builds from source, which requires a Rust toolchain. From a source checkout, run cargo run -- <command>.

Quick start

From the repository root:

seiso init
seiso check

seiso init writes a seiso.toml at the repository root with suggested exclusions and kind mappings; review them before relying on the results.

seiso check runs only stable rules, which have met the promotion criteria. The other rules are in preview: they are experimental, can report false positives, and run only with --preview. Try them locally before relying on them, and keep them out of CI gates. seiso rule --all lists every rule with its status, 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.