OPFiles.ai

Adopt

Ask your assistant for a plan. Review it, then authorize.

Ask your AI development assistant to read the standard, inspect your project, and propose an adoption plan naming what it would create, import, or retire. Review that plan before authorizing changes, then inspect the scaffolded store and validation results. In this build the reference tooling stops after approval.

Copy this prompt

Read https://opfiles.ai/llms.txt and https://opfiles.ai/adopt.md, then inspect this project and propose a plan to adopt OPFiles (OPF). The plan should name every file you would create, import, or retire, and why. Do not change any files until I have reviewed and approved the plan.

Paste it into your AI development assistant. It proposes a plan and waits for your approval before changing anything.

How

  1. Give your assistant this site's machine-readable entry point, /llms.txt, and the adoption guide, /adopt.md, as the starting material.
  2. Review the plan it proposes: what it would create, import, or retire.
  3. Authorize, then inspect the scaffolded store and the validation results (the reference tooling cannot apply a plan yet).

Adopting by hand is the fallback for when you cannot use an assistant; both paths target the same store format.

By hand

The manual path

The shape of the manual path is short: create the store (write the files from the specification and schemas), commit it, generate the views with opf render --write for a supported store or your own renderer, and then work records-first. The standard requires no particular tool. The reference tooling requires Python 3.14 or newer. It validates spec 1.2.0 stores in either layout, with limits: it does not render or drift-check per-record views, and the baseline validator reports module-tier and importer record content schemas as cannot-evaluate. For a store with module-tier or importer records, or a per-record store that declares views, doctor's overall verdict is cannot-evaluate (exit 2).

The reference tooling's opf init does not scaffold this store yet: its scaffold still writes a 1.2.0 store, a format the standard's validation refuses (specification section 9.2). Conformance you assert by hand is self-asserted, and you should say so wherever you claim it, because no validator has checked it for you yet.

manifest.toml
The control document. It declares standard = "opf" (the exact discovery token) in its [opf] table, along with the base spec_version you conform to ("2.0.0"), the homes generation homes = 2, the storage layout, the enforcement posture, and import_status.
counters.toml
The ID high-water marks. It holds the clean row and the imported counter row (the quoted key "imported:<NS>", at zero to start) of every enabled type.
version.toml
The version and release ledger: numbers, dates, spans, and digests, never release prose.
worklog.toml
The durable operational record: one entry per change, correctable in place until a release freezes its span, never deleted. It is a ledger kept as a single file in either layout, not a typed index.
Typed indexes
The eleven baseline typed indexes, each a .index.toml file that starts with no records, in the canonical form the reference tooling writes, never as a zero-byte file.

The imported leaves: one <type>.imported.index.toml beside each of those eleven indexes, plus worklog.imported.toml for the worklog, each starting with no records in the same canonical form, never as a zero-byte file. The standard requires them in every store (OPF-SPEC.md sections 4.2 and 8.2). The "Hand-start file contents" section of OPF-QUICKSTART.md gives the exact starting bytes of these files.

Then write the committed pointer .opf.toml at your product repository root, so the store resolves from a stable location (specification section 4.3). In the manifest, a [profiles.aiqt] table is optional and is ignored by base-only tooling; a base adopter need not add it.

The illustrative base [opf] table of a manifest, not a complete manifest: also set layout, posture and import_status, register each enabled type in [types], and declare views and the other settings (see the standard for the normative shape, and the core store files for every table it can carry):

.working/toml/manifest.toml

[opf]
standard = "opf"         # the exact discovery token
spec_version = "2.0.0"   # the base spec version this store conforms to
homes = 2                # the homes generation; required, and 2 is the only value

Reference tooling

Where the reference tooling stands

The reference tooling's opf init does not scaffold a 2.0.0 store yet: its scaffold still writes a 1.2.0 store, a format the standard's validation refuses (specification section 9.2). The reference tooling does not yet implement spec 2.0.0, the only base version the standard defines; it validates spec 1.2.0 stores, as described above. Its opf doctor grades a manifest declaring spec_version = "2.0.0" with homes = 2 under its 1.2.0 rules, so its VALID verdict on such a store says nothing about conformance to the standard; opf upgrade and opf record refuse such a store. The reference tooling defines no store upgrade: opf upgrade refuses every invocation with exit 2, reading and writing nothing.

The opf reference CLI, its 10 command verbs, and what each does today are on the technical details page.