Fewer AI errors. Durable records. The same process on every project.

What it is

Every file is half of a pair

One rule of thumb carries the whole convention: lowercase files are machine source you change only through tooling or review; UPPERCASE files are generated or published deliverables you read and never hand-edit.

Why it works

Structured input, deterministic process

The benefits above rest on two properties the standard enforces: deterministic rendering, same sources to the same bytes, and structured, schema-validated input. Together they reduce variance, ambiguity, and the opportunity for errors; they discipline the record the work runs on, not the judgment of whichever assistant runs it.

A process that reads a structured, schema-validated record does not have to reconstruct context from memory, guess at a missing field, or interpret free-form prose. The closed schemas mean a malformed input is refused rather than silently misread; the closed transform vocabulary means a view can only be composed in reviewed, versioned ways; and the byte-reproducible render means two runs over the same store produce the same bytes, so the views agree about what the record says. Determinism covers the rendering; the source records are authored content that review keeps correct.

For teams working with AI assistants, this structure helps reduce the likelihood of errors, omissions, and hallucinations in the operational record: the assistant writes into a schema that refuses what does not fit and reads from a store that carries the declared context, and the generator itself invokes no model and adds no model-generated interpretation, reproducing the declared source records, so assistant-authored content in those records still needs review. These mechanisms reduce the opportunity for a confident guess to enter the record; they do not remove it entirely, and the standard says so plainly in its own residual-coverage disclosures.

Captured context can also be an efficiency gain. Because the TOML carries the declared operational context, an assistant spends less of its run reconstructing it, which can reduce back-and-forth inference and token use, alongside a reduced likelihood of errors, omissions, and hallucinations. Structured recording adds its own overhead, so the net saving depends on the workflow and is worth measuring.

The standard files

Every standard TOML file, and what pairs with it

The complete roster, enumerated from the specification and the reference scaffolder. Each file has its own page: purpose, schema shape, lifecycle, and the processes that reference, update, and consume it.

<product repository root>/
  .opf.toml                 committed store pointer            details
  CHANGELOG.md              curated public changelog (gated on facts, not bytes)
  VERSION                   deterministic render of version.toml
  .working/                 the store (default in-repo location)
    TODO.md BACKLOG.md PIPELINE.md DONE.md FINDINGS.md DECISIONS.md
    BLOCKS.md HANDOFF.md REFERENCES.md CONTRIBUTIONS.md WORKLOG.md VERSION.md
    DECISIONS.toml          machine projection (generated TOML)  details
    toml/
      manifest.toml         store manifest and discovery marker  details
      counters.toml         per-namespace ID high-water marks    details
      version.toml          version and release ledger           details
      worklog.toml          durable operational record           details
      lease.toml            single-writer lease (only while held) details
      backlog_item.index.toml       and ten sibling typed indexes  details
      archive/<YYYY>/
        archive.toml        enumerates every rotated ID and span details

The eleven scaffolded record indexes are backlog_item, done, finding, pending_decision, autonomous_decision, maintainer_decision, preference_pattern, block, handoff, reference, and contribution; the worklog type lives in its own ledger, worklog.toml, rather than an index. Eight further record types ship in optional, default-off modules, and one (legacy_fragment) is created only by the importer: module and importer types.

Getting started

Adopt it

Assistant-driven adoption

The primary path is coming: point your AI development assistant at this site root and tell it to adopt OPF (or adopt AIQT). It reads the standard, plans the store, and, on your yes, carries out and merges the adoption, leaving the .working/ store for your review. This is the interface we are building; it is not live yet.

Manual adoption, available today

1. Scaffold.

   Run opf init at your project root. It creates the store sources (.working/toml/ with the manifest, counters, the two ledgers, and eleven empty typed indexes), writes the committed pointer .opf.toml, and adds a placeholder CHANGELOG.md only when you have none. Anything already sitting in .working/ is surfaced, never absorbed or overwritten.

2. Commit, then render.

   Review the created files, stage and commit them (init prints the exact command), and confirm nothing under .working/ is ignored: an untracked store is a hard failure, not a warning. Then opf render --write materializes the Markdown views.

3. Work records-first.

   Append a worklog entry per change, keep the backlog, findings, and decisions in their typed files, and regenerate views rather than editing them. At release, record the release and its worklog span in version.toml, curate the summary, and publish it into CHANGELOG.md with its freeze digest recorded.