OntoShip
A project knowledge base is just markdown + a README index + git. Nothing simpler works better.
Above: the actual documentation graph of a live production project
(hub.neuraldeep.ru) — generated by gitmark map, gravity
mode on. Colors = services. This isn't a mockup; it's a KB being used and evolved daily.
The idea
Markdown is the source of truth — the thing you and your AI assistant read directly, in
any editor. Everything derived (a search index, this HTML overview, the link graph) is
regenerated from the md, so git stays clean. No service, no database, no embeddings,
no vendor. The entry point is CLAUDE.md / AGENTS.md; every folder's README.md is its
index.
CLAUDE.md / AGENTS.md ← entry point
/docs
README.md ← master index
/services
/<service>
README.md ← always the folder index
Battle-tested over months of building with AI assistants. The KB an agent (and a human)
actually wants is plain md you can read anywhere — plus instant search so you find the
right file instead of grepping blind.
What's in here
gitmark — one self-contained Python-stdlib CLI, zero dependencies:
| command | what |
|---|
index | build a SQLite FTS5 index: bm25 ∪ trigram (substring) ∪ fuzzy (4-char windows, typo/morphology/non-Latin tolerant) |
search | ranked file:line · heading · snippet; --json for tooling |
map | self-contained HTML: collapsible tree + rendered markdown + a force/radial graph of links |
serve | tiny local HTTP server to view the map |
stat | index/KB stats |
lint | (optional) ontology checks: broken links, frontmatter, folder READMEs |
version | — |
OntoShip ships as a Claude Code marketplace with two plugins — gitmark (KB + dev-flow) and destructive-guard (safety hook).
gitmark — three skills and five commands:
| skill | what |
|---|
kb-search | search the KB (FTS5) instead of grepping blind |
kb-curate | light ontology rules when adding/editing docs (types, frontmatter, typed links) |
dev-flow | the spec-driven loop to ship a feature: research → tasks → goal → spec (md via kb-curate) → isolated git worktree → implement → tests → independent review → dev-tests → prod-tests → ship (MR → dev → main). Feature to prod in ~40 min – 2 h. |
So the agent searches the KB instead of grepping, follows light curation rules when
editing, and ships changes through one repeatable, gated flow built around the KB.
| command | what |
|---|
/kb | search the KB (FTS5) and answer from the top hits |
/kb-map | build the self-contained HTML graph of the KB and open it |
/doc | compose/update one KB doc following the ontology (wraps kb-curate) |
/onto-doc | build the whole KB — fans out kb-curate curator agents per area, then lint + index + map |
/ship | run the dev-flow on a feature/fix: research → … → ship (MR → dev → main) |
What to write after a command (for best results)
The argument after the command is the prompt — be specific, results scale with it.
/kb <query> — a topic, symbol, concept or question to find in the KB.
- Good:
/kb how is the billing webhook signature verified, /kb tier rate limits, /kb sandbox isolation.
- Use concrete nouns, not full sentences. Cyrillic, typos and substrings are fine (trigram/fuzzy).
- Bare
/kb → prints index stats + the syntax.
/kb-map [output-path] — usually nothing (defaults to docs-map.html).
- Optional path:
/kb-map build/graph.html.
/doc <topic / what to document> — name the thing to write up; the agent picks the
node_type+folder, writes frontmatter + typed links, and indexes it.
- Good:
/doc how the billing webhook verifies the YooKassa signature, /doc decision: drop Firecracker-per-session.
- It searches first and edits an existing doc instead of duplicating.
/onto-doc [scope] — bootstrap/rebuild the entire KB. Empty = whole repo; or scope it
(/onto-doc services/api services/billing, or /onto-doc only reference docs).
- Surveys the codebase, splits it into doc areas, and dispatches a curator agent per area
(parallel), then lints + reindexes + regenerates the graph.
- Use it on a fresh repo to stand up docs/ from nothing, or to backfill coverage.
