OKF Explorer OKF Explorer documentation

Review of OKF repository guidance and portable agent packaging

Date: 2026-08-09

Outcome

The baseline review found a coherent OKF production method distributed across domain repositories. The implementation recorded by this document now makes that method available to an unfamiliar agent through one portable workflow, repository-local machine-readable contracts and bounded guidance blocks.

okf-uk-living is the strongest single application exemplar: it makes an ontology understandable through everyday citizen journeys while retaining a named denominator, jurisdiction variants, source and assertion status, authority/redress, competency questions, population assurance, specialist review, and publication boundaries. It is not the sole normative template. The most reusable baseline combines:

The new okf-repositories Agent Plugin packages that synthesis as a focused skill, references, a read-only inspector, and an adaptable AGENTS.md template.

Scope reviewed

The review compared repository guidance, authored/generated boundaries, descriptors, source and assertion semantics, build and validation entrypoints, evaluation, release state, and publication rules. It did not rerun every repository's complete release suite.

Findings

P1 — The shared operating contract is implicit and fragmented

The strongest safeguards recur with different wording and depth across eight AGENTS.md files. The shortest files are only a few lines; the longest contain domain-specific acquisition semantics. An unfamiliar agent must reconstruct the common method before it can decide which rules are portable and which belong only to statistics, legislation, GOV.UK content, land registration, or life-course services.

Consequence: an agent can over-apply a domain rule, miss a cross-repository invariant, or spend context repeatedly rediscovering the same source/generated, authority, denominator, and publication boundaries.

Correction: keep concise repository-specific AGENTS.md files and install or invoke the portable work-with-okf-repositories skill for the shared method.

P1 — Local, candidate, publication, and release state require an explicit read order

The strongest repositories correctly preserve multiple state planes. For example, okf-uk-living/okf-explorer.json remains a local-evaluation descriptor, while publication/okf-explorer.json records the separately authorized preview. Generated assurance retains the pre-publication candidate state. These are not contradictions, but an agent that reads one convenient file can report the wrong current publication claim.

Consequence: population-complete, release-grade, publication-authorized, deployed, and browser-verified can be collapsed into one inaccurate status.

Correction: require the agent to read status, candidate, publication unit, and deployment verification as separate evidence and report each gate explicitly.

P2 — OKF core and Explorer profile boundaries are clearest in documentation, not every agent file

docs/okf-conformance.md correctly keeps the permissive OKF v0.2 Markdown core separate from richer Explorer, YAML-LD, JSON-LD, SHACL, large-corpus, federation, and Foundry profiles. Several producer AGENTS.md files assume that context without linking or restating the distinction.

Consequence: an agent can reject a valid core bundle for lacking profile fields or present a local profile convention as universal OKF.

Correction: make core/profile classification an orientation step and include it in all new agent guidance.

P2 — Validation commands are intentionally heterogeneous but hard to discover uniformly

The repository family uses locked uv, pinned virtual-environment Python, plain Python, Node, shell, Make, targeted check modes, and release reproduction profiles. Translating one repository's commands into another environment can break evidence identity; loading every README to find the right commands is slow.

Correction: extract exact commands from local guidance, prefer check modes for diagnosis, and never invent a common build command. The plugin's inspector reports commands declared in root AGENTS.md without executing them.

Resolved P2 — okf-explorer/okf.config.json retained a stale v0.1 profile label

The baseline root Markdown and generated bundle declared OKF v0.2 while okf.config.json still labelled the profile OKF v0.1 + explorer bundle.

Consequence: tools or agents that use the configuration label during orientation can report the wrong producer version even though the generated bundle is correct.

Resolution: the configuration label now declares OKF v0.2 and the affected runtime and semantic projections have been rebuilt and checked.

Resolved P3 — The fixture workspace lacked an implementation contract

At baseline, okf-testing was an empty non-Git directory and therefore provided no test contract despite its name. Editor state and unrelated working-tree changes elsewhere remained repository hygiene concerns and were deliberately not treated as migration inputs.

Resolution: okf-testing now contains a defined, executable fixture contract with digest-bound positive, negative and sparse-compatibility expectations. It intentionally remains non-Git and non-publishable. Agents must still inspect and preserve each working tree and keep editor state ignored.

Why a plugin rather than one enormous AGENTS.md

OpenAI's current guidance treats AGENTS.md as always-loaded repository instruction context, with nested files providing more specific overrides. A skill is loaded only when its trigger matches. The portable OKF method is too large and too cross-repository for every root prompt, while domain paths, commands, prohibitions, and publication authority must remain local.

The recommended split is:

Agent Plugins v1 packaging decision

The linked ExplainX article was published one day after the announcement and correctly warned that the manifest shape was not then documented. The live Agent Plugins v1.0.0 working draft now defines:

The package therefore uses the portable root plugin.json. It also retains .codex-plugin/plugin.json as a compatibility manifest for the currently documented Codex local-plugin workflow. No MCP server is included: the skill needs repository files and ordinary local validation, not a live authenticated service. No marketplace entry or installation was created implicitly.

  1. Validate and forward-test the plugin with query, review, bounded change, incomplete-input, and should-not-trigger prompts.
  2. Add a short link from each maintained OKF repository's AGENTS.md to the shared plugin or copy only the relevant repository-specific sections from its template.
  3. Use okf-explorer as the distribution home and version the plugin independently from OKF core and Explorer releases.
  4. Keep the now-correct Explorer v0.2 configuration label synchronized with generated descriptors.
  5. Keep okf-uk-living as the primary educational/application showcase while describing the other exemplars as complementary assurance patterns.

Standards and guidance consulted