Engineered for Deterministic AI Context
Open Document Spec (ODS) turns scattered markdown documentation into a structured, queryable knowledge graph with deterministic linting, binary compliance, and automated bi-directional code linking.
Deterministic AI Context Graph
Eliminate token-wasting probabilistic vector search. ODS constructs a deterministic DAG linking code symbols to exact documentation anchors.
When an AI agent modifies a function, ODS delivers exact required reading lists with zero vector search hallucinations, zero chunking noise, and deterministic relevance.
$ ods context src/auth/jwt.rs
→ docs/architecture/auth.md (score: 1.0, role: spec)
→ docs/security/tokens.md (score: 0.95, role: policy)
→ tests/jwt_validation_test.rs (score: 0.90, role: test)
✓ 3 verified documents delivered in 3.8ms
Compare deterministic DAG traversal against traditional embedding search for codebase documentation.
Probabilistic similarity. Misses critical architectural edge-cases, returns noisy chunks, and hallucinates outdated schema definitions.
Explicit symbol-to-spec binding. Always retrieves the exact authoritative documentation, bound test suites, and required ADRs.
Bi-Directional Code & Specification Linking
Bind documentation pages directly to program functions, data schemas, and test suites so your AI understands both the architectural intent and the actual codebase.
Declare implementation symbols and test files directly inside document frontmatter. The graph automatically discovers related source files.
---
description: Storage engine connection pool.
ods:
profile: architecture
status: stable
code:
- path: src/storage/db.rs
symbol: init_pool()
role: implementation
- path: tests/db_test.rs
role: test
---
Plugs directly into Claude Code, Antigravity, Cursor, and Windsurf via standard JSON context streams without changing your editor workflow.
{
"symbol": "init_pool()",
"doc": "docs/architecture/storage.md",
"role": "implementation",
"tests": ["tests/db_test.rs"],
"verified": true
}
Structured Document Profiles & Binary Compliance
Eliminate formatting confusion with standardized document profile schemas, required section headings, and a binary compliance validation engine.
Enforce consistent structure across architecture docs, runbooks, PRDs, and ADRs with automated heading validation.
Architecture Spec
Enforces system goals, component requirements, and acceptance criteria.
## Goal## Requirements## Acceptance CriteriaRunbooks & Guides
Enforces operational overview, prerequisites, and sequential steps.
## Overview## Prerequisites## StepsProduct PRDs
Enforces user problem statements and explicit acceptance criteria.
## User Goal## Acceptance CriteriaADRs & Decision Notes
Enforces architectural context, chosen decision, and trade-off consequences.
## Context## Decision## ConsequencesGradual adoption with zero vendor lock-in. ods lint is binary: compliant (exit 0) or diagnostic failure (exit 1).
Plain Markdown
Zero workspace config required. Use standard Markdown as-is.
Root Workspace
Add a root ods.toml (spec = "0.1") to mark repository boundary.
ods lint: Exit 0
CompliantGraph connections, schema keys, and profile headings fully valid.
Deterministic Diagnostics
Pinpoint exact broken links, missing headings, or stale symbol bindings.
Enterprise-Grade Privacy & Secret Shield
Built-in redaction, token isolation, and security controls ensure proprietary credentials, confidential files, and API secrets never leak into external AI prompts.
Private File Filters
Pages marked with share: private are strictly quarantined and never forwarded to external AI tools or API prompts.
Inline Secret Blurring
Secrets and keys placed inside encrypted/secret tags are automatically stripped and masked before dispatching to AI assistants.
Snapshot & State Restoration
Easily backup, audit, and verify document workspace state before and after AI agent batch refactoring operations.
Automated Tooling, Background Healing & Scale
Maintain a pristine documentation repository effortlessly with background link-repair daemons, single-command workspace migration, and team ROI analytics.
Auto-Healing Link Daemon
Move or rename markdown files freely — background daemons instantly update relative paths and cross-document links across the repository.
1-Command Folder Adoption
Migrate hundreds of existing markdown files in seconds. ods init --adopt drafts frontmatter and sets up workspace boundaries.
Bulk Tag Refactoring & Analytics
Search, filter, and rename tags across your entire workspace, while calculating annual token savings benchmarks with precision.
Ready to Upgrade Your AI Documentation DX?
Join high-velocity teams using Open Document Spec to eliminate AI hallucinations and automate code-to-spec synchronization.