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:

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:

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.

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.

/ship <what + why + done> — describe the change as fully as you can; this is what makes the dev-flow good. Include what to do, why (the goal), and the done-criteria, and name the target service/file if you know it.

• Good: /ship add a 60 rpm rate-limit to /api/search; goal: stop abuse; done = HTTP 429 over the limit + a unit test + a note in docs/reference/limits.md.
• Weak: /ship fix search → the agent has to guess the goal and the done-criteria.
• Add "deploy it" / "don't deploy" if you want to control the last step.

destructive-guard — a PreToolUse Bash hook that intercepts destructive commands (rm, git reset --hard, docker rm -v, SQL DROP/TRUNCATE) and forces a y/n confirmation even in bypassPermissions, with sound + a macOS banner. Token-level parsing — no false positives on perform/transform/terraform.

Quickstart

python3 skills/kb-search/gitmark.py index            # build .gitmark/index.db
python3 skills/kb-search/gitmark.py search "auth flow"
python3 skills/kb-search/gitmark.py map -o docs-map.html && open docs-map.html

Pure python3 (≥3.7) with SQLite FTS5; the trigram tokenizer (SQLite ≥ 3.34) adds fuzzy/substring/non-Latin matching — detected automatically, degrades gracefully. Add .gitmark/ to .gitignore — it's a build artifact.

Install as a Claude Code plugin

/plugin marketplace add vakovalskii/ontoship
/plugin install gitmark@ontoship
/plugin install destructive-guard@ontoship   # optional: the safety hook

Or just copy skills/ and commands/ into your repo's .claude/ — project-local, no marketplace needed.

Optional: the ontology (only if you want guardrails)

The simple core needs no frontmatter at all — index/search/map work on raw markdown. If a team wants the KB not to rot as it grows, there's a light code-ontology (inspired by Palantir's Ontology): each doc gets a node_type, a few frontmatter properties, and typed links — and gitmark lint enforces it (no broken links, no orphans, every folder has a README index). See docs/ontology.md. Use it or ignore it; the tool doesn't force it.

Why this and not a wiki / Notion / vector-DB memory

Because the simplest thing wins: md you already read, git you already use, one stdlib file you can audit in an afternoon. It runs offline, leaks nothing to a SaaS, and you own every byte. There are a thousand "memory banks" — this one's bet is radical simplicity that you can watch working on a real product, not another service to run.

License

MIT — see LICENSE.