Brief: Phased development plan for Ourobor OS, synthesized from docs/PLAN.md.
Objective
Establish a compounding, product-agnostic LLM Wiki system (ouro/wiki/) supported by an offline-first dashboard (ouro-webui/). The wiki serves as the persistent knowledge base maintained by the LLM and curated by the developer.
Phase 1: Ouro Core — COMPLETED
- Created
ouro/wiki/schema.md— philosophy, taxonomy, and maintenance protocols. - Created
ouro/wiki/index.md— initialized the hub with links to categories. - Updated
CLAUDE.md/GEMINI.md— LLM agent maintenance protocol appended. - Initialized logging and cleanup of project documentation.
ouro/wiki/entities/Parser.md and foundational ADRs as part of Phase 1. These were not kept — the ouro/ wiki directories must stay empty (skeleton only). See ADR-001. The project's own documentation now lives in wiki/ instead. See ADR-002.Phase 2: Ouro-WebUI — COMPLETED
- ✅ Scaffold
ouro-webui/directory and basic structure. - ✅ Develop
builder.pyusingmistune(Markdown + Doxygen tag processing) andjinja2(templating). - ✅ Create responsive, portable dashboard templates (two-column sidebar layout, mobile-responsive).
- ✅ Integrate Doxygen tag renderer via regex preprocessing (
@entity,@brief,@note,@warning). - ✅ Verify generation and portability of the dashboard.
Phase 3: Observability App & Sidecar Vault — IN PROGRESS
An observability, interpretability and documentation app for vibecoders and professionals: explain code, and test values or debug more easily. See ADR-011 and docs/spec-v0.3-sidecar.md (v0.3.3).
- ✅ Measure and onboard:
ouro/scripts/claim_scan.pyshipped in the skill (claim_scan), with--wikibaseline pages.- Agent Onboarding checklist added to
SKILL.md. bootstrap.pyfills in the real skill path.- Code Comments & TODOs rule in the protocol and in AGENT.md.
- Local run log (
runlog.py, ADR-012) so external test runs can be reviewed.
- ✅ Exit check (first run, dabao-dasher): comment debt was negligible, while docs drift was real (2/2). Nine onboarding defects were found and fixed in
feat/onboarding-fixes. - ⬜ More field tests, including a non-TypeScript repo and a vibecoder-owned repo.
- 🔄 Docs-vs-code drift (on
feat/doc-scan: ✅doc_scan.py(doc_scan, ADR-013) and thedrift_page.pypage module (drift_page) are built and wired into onboarding step 5; on dabao-dasher both known drifts rank in the top 5. ⬜ Comment claims on the same page, the agent feed, and--vaultfollow):doc_scan.pyshortlists outdated doc statements (broken references, docs older than the code they reference); the agent confirms them intomaps/doc-drift.md; comment claims feed the same page; agent feed through the hooks;--vault/OURO_VAULT. - ⬜ Ask & Verify: explanations, suggested tests, value probes, and one-click local verify with the project's own runner in a throwaway worktree (inferred → verified).
- ⬜ Trace view and vibecoder flows:
sys.settracetrace view from real runs, guided "what happens if…?" flows, vault mode as the default.
- Deferred: isolated sandbox (for untrusted repos), LSP/SCIP, local UI app, LLM "contradicted" judge, advisory Pass Gate, vault sync.
Next Steps (as of 2026-10-25)
Pick up here. Work in this order. Step 5 was built first, on 2026-10-25, so the re-run in steps 2–3 can measure it.
- Merge PR #2 (
feat/onboarding-fixes): the nine onboarding fixes plus the Phase 1 retarget. Thengit checkout main && git pull. - Re-run the dabao-dasher onboarding with the fixed skill:
- Reinstall or update the skill (
npx skills add robobooga/ourobor-os). - In
~/base/dabao-dasher, remove the previous run'souro/directory and the appended protocol section inAGENTS.md, or start on a fresh branch frommaster. - Ask the agent: "Set up Ourobor OS in this project."
- Reinstall or update the skill (
- Review the run:
- Run
python3 ouro/scripts/runlog.py show ~/base/dabao-dasher --last 200and compare it with the previous run (the first report, from 2026-09-30, is in the same log). - Check that the agent:
- clears captures with
--donerather than editing the queue by hand - runs
doc_scan.py --wikiand marks every raised entry onmaps/doc-drift.mdconfirmed or dismissed.docs/AUDIO.mdis already fixed at HEAD; the ENGINE.md kerb stopgap and the MAPGEN.md stage table should come out confirmed, and GRAPHICS.md dismissed. - Count the confirmed entries in the top 10 (the ≥50% precision criterion), and record the count in doc_scan.
- uses the
python3commands bootstrap wrote - needs no workarounds
- clears captures with
- Record any new deviations in the capture queue or as an ADR-011 amendment.
- Run
- Field-test two more repos (Phase 0 item above): one non-TypeScript repo, ideally Python, and one owned by a vibecoder. Log both, and compare doc drift with comment drift again before committing to the Phase 1 design.
- ✅ Build
doc_scan.py(Phase 1), built 2026-10-25 onfeat/doc-scan(doc_scan, ADR-013):- Known-positive test passed: at the commit before the AUDIO fix, the two drifts rank #1 and #5. It also found an unknown drift at #2 (the MAPGEN.md stage table).
- Still open: the success criterion (at least 50% of the top 10 confirmed) needs the full labelling in step 3, and a second repo from step 4.
- Next for Phase 1: comment claims on the same page, the agent feed through hooks, and
--vault.
- Open decisions, with the defaults chosen in PR #2 (change them if the field tests disagree):
- Crawl pointer
Commitlabel is HEAD even for dirty files. claim_scanspan cap is 6 lines.- Non-Python comments annotate only the next line.
- Spec §9 open questions: runner detection for local verify, the "trusted repo" rule, prose-claim patterns for
doc_scan.
- Crawl pointer
- Known rough edge:
- The crawl on dabao-dasher still queues 291 entries (about 68 KB), including 91 test files.
- Consider letting onboarding crawl only source directories (
--crawl src tools), or skipping tests by default. - Decide after the re-run in step 2.
Verification Criteria
These define what "done" looks like for the current phase:
| Criterion | Status |
|---|---|
| LLM can look up a decision or entity in the wiki | ✅ Met — wiki/ is now populated |
python ouro-webui/builder.py generates a functional, linked dashboard |
✅ Met |
| Wiki structure is portable and drop-in ready | ✅ Met — ouro/ skeleton is clean |
Source
Synthesized from docs/PLAN.md. That file can be considered superseded by this entry and the broader wiki/ documentation. It is retained in docs/ as a historical artifact.