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, or the work it describes, was made.
• Judgment calls a tool can't make are written down with a reason. An exception without one is itself a violation.

The convention is written up as a standalone specification, with worked examples and an adoption guide, so a project can follow it without installing anything. The specification is provisional before 1.0.0 and versioned separately from seiso; its direction is open for discussion in #37.

seiso is the reference implementation. Its rules check documents against the specification; 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. How seiso checks the convention maps each rule to the requirement it covers and the evidence it 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 or musl (such as Alpine), and Windows x64 and arm64. On other platforms, 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, kind mappings, and documentation site entries; 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.