gitmark

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.