Ourobor OS: Project Wiki
This is the internal documentation for the Ourobor OS project. It also serves as a reference example for users of the skill — this is what a populated ouro/wiki/ looks like in practice.
The distributable skill package lives in
ouro/. Thiswiki/directory documents the Ourobor OS project itself and mirrors the structure users receive when they runbootstrap.py. See ADR-002.
Core Documentation
schema.md— Doxygen tag reference (@entity,@brief,@snippet, etc.) and maintenance protocols (capture → synthesize → pop → index).
Entities
- capture.py — Stages files/text into the capture queue (deduplicated by source).
--crawlrespects.gitignoreand stages pointer entries (--contentembeds contents),--crawl --gitstages git-changed files,--done <path-or-glob>clears finished captures in bulk,--popremoves one.--from-commit/--from-indexstage hook pointers,--check-docsflags staged code without wiki updates,--statusreports pending captures. - bootstrap.py — One-time init: detects the LLM environment, creates the
ouro/wiki/tree, and appends the maintenance protocol to instruction files (AGENTS.mdfirst, symlinked aliases once), with the real skill path and a workingpython3/pythoncommand filled in. It adds an "Existing project docs" section whendocs/or an ADR folder exists.--install-hooksopts in to automatic capture. Idempotent. - hooks.py — Opt-in, declarative installer for git capture hooks (post- or pre-commit), the pre-commit docs check (warn/strict), the Claude Code SessionStart status hook, the Claude Code commit gate, and the Claude Code Stop hook that has the agent write docs before finishing. Honours
core.hooksPath. - builder.py — Converts
wiki/*.md→ouro-webui/dist/*.html; processes Doxygen tags via regex, renders Markdown withmistune, generates grouped sidebar. Not part of the distributed skill. - package.py — Validates
ouro/structure then zips it todist/ouro-skill.zip. Aborts if required files/dirs are missing. Root-level only, not in the distributed skill. - runlog.py — Local, opt-out run log: wraps every script's
main()to record argv, exit code, duration and capped stdout/stderr in~/.ouro/runs/<project>-<hash>/events.jsonl;reportlogs an agent summary plus a wiki snapshot;show/listto review. Nothing is transmitted. - claim_scan.py — Shipped in the skill: a read-only, stdlib scan of a repo's comments. Reports TODO age, stale comments (the first statement under a comment changed in a later commit) and a review-only list of directive-worded comments.
--wikisavesouro/wiki/maps/comment-baseline.md; skips the skill's own files unless--include-skill. Includes the ourobor-os and dabao-dasher baselines. - doc_scan.py — Phase 1, shipped in the skill: a read-only, stdlib scan of tracked Markdown docs. It ranks sections with broken references (paths, links,
git grep-missing symbols) or cited files changed after the citing paragraph; provisional wording ("stopgap", "nothing imports") boosts the rank.--wikimerges the shortlist intoouro/wiki/maps/doc-drift.md. Includes the dabao-dasher field test. - drift_page.py — Owns the
maps/doc-drift.mdformat:###entries with Key/Status/Code state; reviewed entries are kept verbatim, a dismissed entry returns only when its code state moves, and unconfirmed entries are regenerated.
Architecture Decisions
- ADR-001 —
ouro/wiki/subdirs stay empty (.gitkeeponly); project docs must not ship to users at install time. - ADR-002 — Root
wiki/doubles as internal docs and a populated reference example; one directory, two jobs. - ADR-003 — Inline Doxygen-style tags in plain Markdown (not real Doxygen); readable in any viewer, provides a rendering hook for
builder.py. - ADR-004 — Web UI excluded from the skill package; core skill stays pure stdlib + Markdown, web UI evolves independently.
- ADR-005 —
--crawlis secure-by-default: skips ~50 credential dirs, exact sensitive filenames, and dangerous extensions. Edit constants incapture.pyto tune. - ADR-006 — Sidebar sections with >20 links use
<details>/<summary>; active section auto-opens via inline script. - ADR-007 —
--crawl --gitlimits staging to git-changed files; full--crawlreserved for initial wiki population. - ADR-008 — Opt-in git post-commit hook stages deduplicated pointer captures; Claude Code SessionStart hook prompts synthesis. LLMs are never called from git.
- ADR-009 — Docs ship with the feature: opt-in pre-commit docs check (warn/strict), Claude Code commit gate, and pre-commit capture mode; one capture mode at a time; declarative install.
- ADR-010 — Opt-in Claude Code Stop hook blocks once when a turn ends with undocumented changes, so the running agent writes the docs; loop-safe via
stop_hook_active, once per session per content fingerprint; no separate LLM call. - ADR-011 — Ourobor OS is an observability, interpretability and documentation app for vibecoders and professionals, heading toward a sidecar vault. Phases: measure and onboard (shipped) → deterministic claim ledger → Ask & Verify (explanations, suggested tests, value probes, one-click local runs) → trace view. Comments are scoped claims; code wins over stale comments; a TODO is not permission to defer. Spec:
docs/spec-v0.3-sidecar.md. - ADR-012 — Local run log in
~/.ouro/runs/(on by default,OURO_RUNLOG=offto disable, never transmitted) so real agent-driven onboardings can be compared with what the maintainer would do; remote telemetry and in-repo logs were rejected. - ADR-013 —
doc_scan.pyheuristics: dated per paragraph (not section), directories checked for existence only, score driven by the most-changed cited file, provisional wording only ranks; the agent confirms entries onmaps/doc-drift.md, whose reviews survive re-runs.
Patterns
- Capture-Synthesize Loop — The core workflow: raw code/notes → capture queue → LLM synthesizes into entities/patterns/decisions →
--popclears entry →index.mdupdated.
Maps
- System Architecture — Full directory tree, data flow diagram, and separation-of-concerns table (what ships vs. what doesn't).
- Project Roadmap — Phase 1 (core) and Phase 2 (web UI) complete; Phase 3 (observability app and sidecar vault, ADR-011) in progress: Phase 0 (measure and onboard) shipped.
Capture Queue
capture-queue.md