Adopt by hand

Adopt OPFiles

There are two paths to adoption. The model we are building toward is a single instruction: point your AI development assistant at this site and ask it to adopt OPFiles; that assistant-driven flow is described below as the direction, not a finished tool. Adopting by hand is a first-class path you can take today: the store files are plain TOML, simple enough to keep by hand, and a conformance claim is self-asserted until validation tooling covers it (the reference tooling can scaffold the same store for you, but nothing about adopting the standard requires it).

How adoption will work

The adopter interface we are building toward is one instruction. You point your AI development assistant at the site root and tell it to adopt OPFiles, or to adopt AIQT, and nothing more is meant to be asked of you up front.

The assistant then investigates your project and presents a short plan: which files it will import, retire, or create, and how they are wired together. It asks a single question, yes, no, or let us discuss. On yes it carries out the change and merges it, and you review the resulting .working/ store at the end. Adopting AIQT this way brings OPFiles with it and migrates your existing operational files into the store; adopting OPFiles alone is also supported.

This hands-free flow is the model we are building toward, not a finished feature, and this page does not ask you to run it. Adopting by hand, described below, works today.

Why by hand is a first-class path

OPFiles specifies formats, layout, naming, lifecycle, and enforcement posture. It does not require any particular tool: the specification states that a project can conform with hand-maintained files and its own checks. Adopting by hand gives you the records-first discipline today, and you can move to the reference tooling later without changing the store format. 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.

The minimal store

Create the machine store at .working/toml/ in your repository, with these files:

manifest.toml: the control document and discovery marker. It declares standard = "opf" (the exact discovery token) in its [opf] table, along with the base spec_version you conform to, the storage layout, and the enforcement posture.
counters.toml: the per-namespace ID high-water marks, so an ID is never reused.
version.toml: the version and release ledger (numbers and digests only, never prose).
worklog.toml: the durable, append-only operational record. It is the exempt ledger, not a typed index.
Eleven typed indexes, one per baseline record type: backlog_item, done, finding, pending_decision, autonomous_decision, maintainer_decision, preference_pattern, block, handoff, reference, and contribution, each as <type>.index.toml (empty to start).

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

A minimal manifest, illustrative and drawn from the specification's own example (see the standard for the normative shape):

# .working/toml/manifest.toml
[opf]
standard = "opf"          # discovery token; exact value required
spec_version = "1.1.0"    # the base spec version this store conforms to
layout = "inline"         # "inline" or "per-record"
posture = "warn"          # "off", "warn", or "required" (section 11)
import_status = "none"    # "none", "partial", or "complete"

The layout, and the one rule of thumb

Machine source lives under .working/toml/; generated human-readable views live at .working/ top level; the curated CHANGELOG.md and the generated VERSION live at the product repository root.

<product repository root>/
  .opf.toml                 committed store pointer
  CHANGELOG.md              curated public changelog
  VERSION                   rendered from version.toml
  .working/
    BACKLOG.md FINDINGS.md DECISIONS.md WORKLOG.md ...   generated views (UPPERCASE)
    toml/
      manifest.toml counters.toml version.toml worklog.toml
      backlog_item.index.toml  and its ten sibling indexes

One rule of thumb carries the whole convention: lowercase files are machine source you change through tooling or review; UPPERCASE files are generated or published deliverables you read and never hand-edit. The curated CHANGELOG.md is the one you edit, and only through its publish flow.

Working records-first

Treat the store as the source of truth: a decision, finding, or completion that is not recorded did not happen. Append a worklog entry per change; keep the backlog, findings, and decisions in their typed files; and regenerate the views rather than editing them. Records carry a typed envelope (an ID, type, status, title, timestamps read from the clock, an actor, links, and captured references), IDs are never reused, and records are corrected before release and frozen after it, superseded by new records that link the old rather than deleted.

The release triad by hand

At a release, record the release and the worklog span it covers as a [[release]] row in version.toml; draft the summary from that span; curate it by hand; publish it into CHANGELOG.md; and record the freeze digest for the published entry. Old summaries can be rolled up into range summaries later, because the details always survive in the worklog, so re-rolling or re-wording stays safe.

Bring your own checks

Even before you run the reference validator, you can assert the standard's key invariants yourself. A hand adopter can check that the store is a tracked git repository (an untracked store is a hard failure, not a warning); that generated views match a fresh render; that worklog spans tile the released versions with no gap or overlap; and that the changelog range tiles every released version, with published entries unchanged since their recorded digest. These are the checks the integrity layer performs when the tooling runs; asserting them by hand keeps you honest in the meantime.

Honest limits

Without the validation tooling, your conformance is self-asserted and should say so. Digest freezing and span tiling are your own discipline until a validator checks them. Some residuals are part of the standard itself and no adopter escapes them: the freeze gate cannot judge whether prose is accurate, range coverage cannot judge summary quality, and the unreleased worklog tail rests on review rather than machine freezing. The disclosure page states these limits plainly.