Open Knowledge Format for Crossplane v2

name: okf description: Explicit-only workflow that builds or updates a source-backed Open Knowledge Format catalog for Crossplane core, providers, functions, SDKs, tools, official documentation, historical design context, and examples. Never invoke implicitly; the user must invoke $okf, /skill:okf, or /okf. disable-model-invocation: true metadata: version: "1.5" license: Apache-2.0

Crossplane OKF workflow

Run this workflow only after the user explicitly invokes $okf, /skill:okf, or /okf. Do not treat a request that merely mentions OKF, Crossplane, a provider, or a function as permission to start this workflow.

The root or parent agent owns all writes. Subagents are bounded, read-only researchers that return evidence packets.

Inputs

Derive the requested scope from the explicit invocation:

• source repositories or source groups

• concepts, APIs, commands, providers, functions, documentation, examples, issues, pull requests, or resource batches

• create, update, validate, or review operation

• output path, defaulting to catalog/

Read:

• references/sources.yaml

• references/evidence-contract.md

• references/okf-profile.md

• references/okf-spec.md

Treat the source categories in references/sources.yaml as separate authority roles. Do not flatten primary source, official documentation, historical-design, supporting source, project-history evidence, and third-party example evidence into one undifferentiated source list.

Runtime adapters

The workflow and evidence contracts are shared across agent runtimes:

• Codex specialist definitions live in .codex/agents/.

• Pi specialist definitions live in .pi/agents/ and are loaded through pi-subagents.

• Pi model configuration guidance lives in .pi/README.md.

• Pi users may invoke the shared skill with /skill:okf or use the project prompt /okf.

• Runtime-specific agents use the same okf-* role names and must preserve the same read-only evidence contract.

• Every dedicated role must exist as a matching Codex and Pi agent set.

• The root or parent agent remains the only writer regardless of runtime.

Change publication rules

• For every content addition or update, create a dedicated non-default branch from the latest default branch before editing.

• Keep the complete related change set on that branch, including generated content and all supporting source locks, claim ledgers, indexes, logs, agent instructions, and source profiles.

• Complete deterministic validation and obtain APPROVED from okf-reviewer before committing.

• After all review fixes, run mise run lint. Fix every lint error and rerun the command until it succeeds.

• Commit every intended file only after reviewer approval and a successful lint run. Push the branch and open a pull request.

• Do not merge the pull request unless the user explicitly requests it.

Workflow

1. Bound the work

Create the smallest useful source and concept set. Do not process every repository, every managed resource, or the entire issue and pull-request history unless the user explicitly requests full coverage.

For incremental work, inspect existing catalog concepts and source locks first. Regenerate only concepts affected by changed source paths or dependencies.

2. Pin sources

Resolve every selected repository to a full commit SHA before extracting released knowledge. Record the resolved commits in .okf/sources.lock.yaml or update the existing lock file.

Never cite a moving branch in generated knowledge. A repository homepage may be used as the frontmatter resource, but released-source evidence citations must be immutable.

For Crossplane Core, resolve the latest stable Crossplane release first. Use Core CRDs from that release tag and the matching crossplane/docs content/v<major>.<minor>/ series. Do not use content/master/, content/cli/**, or content/v1.* for stable Core concepts.

For historical Core design context, pin the current crossplane/crossplane main commit at research time and record the selected design document's status and accuracy warnings.

For each composition function, discover the highest stable semantic-version tag at research time. Exclude prereleases, release candidates, beta tags, alpha tags, draft releases, and moving branches. Resolve the selected tag and the immediately preceding stable tag to full commits when available. Do not silently fall back to main.

Issue and pull-request state is mutable. Record a research timestamp and direct GitHub item metadata for project-history evidence instead of presenting it as immutable released source.

3. Scout cheaply

Use okf-source-scout for repository classification and high-signal path discovery.

Batch repositories by source kind. Do not spawn one agent per repository. Prefer one scout task for up to five related repositories or one changed-source batch.

Scout official documentation and third-party examples separately from implementation repositories so their authority roles remain explicit in the evidence packet.

Never use crossplane/crossplane/design/** for general feature discovery. Locate a design document only for a specific feature already identified from current stable documentation or implementation evidence.

Skip scouting when existing locks and evidence already identify the relevant files and their source paths have not changed.

4. Research only what needs semantics

Use the narrowest matching researcher:

• okf-crossplane-core-docs-researcher for current stable Crossplane Core documentation, terminology, workflows, lifecycle states, and general provider or function installation guidance.

• okf-crossplane-core-code-researcher for current stable Crossplane Core CRDs under cluster/crds.

• okf-crossplane-core-design-researcher only as a last-resort historical-context source for a specific Core feature already identified from current stable documentation or implementation evidence.

• okf-function-go-templating-researcher for user-facing function-go-templating installation, input schema, README guidance, examples, and additional template functions.

• okf-function-go-templating-sprig-researcher for the exact Sprig version selected by function-go-templating/go.mod, restricted by the function map exposed by that release.

• okf-function-go-templating-project-history-researcher for human-authored issues and pull requests, grouped into release changes, known reports, and post-release proposals or developments.

• okf-function-sdk-go-researcher for developer-facing crossplane/function-sdk-go APIs, helpers, examples, and testing utilities.

• okf-crossplane-researcher for CLI, runtime, tools, native providers, testing tools, examples, and domains without a dedicated researcher.

• okf-upjet-researcher only for Upjet provider concepts that require Terraform correlation. Give it an explicit provider service or managed-resource batch.

Run the Core docs and Core code researchers together when a concept needs both user-facing guidance and exact served API shape. Invoke the Core design researcher afterward only when a bounded historical question remains.

Every composition function must have its own dedicated Codex and Pi agent set. Add that bounded agent set and source profile before generating knowledge for a function that does not have one. A function agent set may include a primary user-facing researcher plus narrowly scoped supporting researchers for dependencies and project history.

The Crossplane CLI is a separate catalog domain and is not part of Crossplane Core.

For third-party example repositories, restrict research to the configured paths. Extract concrete patterns, relationships, and use cases without treating the repository as proof of general Crossplane behavior.

Run independent read-heavy research in parallel, with at most three direct agents. Wait for all required evidence packets before writing. Never allow subagents to spawn subagents.

5. Apply source authority

Use evidence according to its source role:

• Primary implementation sources, API types, generated schemas, tests, and package metadata establish API shape and runtime behavior.

• Official Crossplane documentation establishes documented terminology, guidance, supported workflows, lifecycle states, and user-facing examples. When documentation conflicts with implementation or schemas, record the conflict and prefer implementation evidence for runtime behavior.

• Historical-design sources establish only historical intent, rationale, conceptual models, alternatives, and tradeoffs for a specific already-known feature. They do not independently establish current API shape, runtime behavior, supported guidance, release inclusion, or feature maturity.

• Supporting sources provide background that is relevant only to their domain, such as Sprig functions, Upjet generation, or Terraform resource behavior.

• Project-history sources establish that a human-authored issue was reported, a pull request was proposed, or a change was merged. They do not independently establish released behavior, API shape, lifecycle state, or recommendations.

• Third-party examples are illustrative. They may establish what that repository implements, but they must not be the sole evidence for Crossplane API semantics, runtime behavior, compatibility, security properties, or recommended practices.

For every design-derived statement presented as a current fact, require corroboration from selected stable source code, CRDs, schemas, tests, or matching stable documentation. Otherwise retain it only as historical design intent or unresolved context. Accepted design status does not prove implementation or release inclusion, and design status never defines feature state.

Apply feature-state precedence:

1. Preserve explicit Alpha, Beta, Preview, Stable, or Deprecated labels from selected current sources.

2. A relevant served v1alpha* API is an Alpha stability ceiling and a relevant served v1beta* API is a Beta stability ceiling. Never record either as Stable.

3. When an explicit Stable label conflicts with a served alpha or beta API, classify the API as Alpha or Beta and record the source conflict.

4. When no explicit label exists, use Alpha for v1alpha*, Beta for v1beta*, and Stable only when no relevant served alpha or beta API exists.

5. Never use v1 alone as proof of Stable; it only permits the repository Stable default when no other selected current evidence indicates a non-stable state.

6. Apply a served-version state only to the API or capability that owns that version. Do not transfer an input API's state to the whole package or an unlabelled package's state to the input API.

7. For non-API software, packages, helpers, and implementation behavior without an explicit lifecycle label, use Not stated by selected sources. A stable semantic-version tag selects released evidence; it is not a maturity label.

8. A pattern that requires several APIs or explicitly labelled capabilities inherits the least stable required surface. Record the exact dependency as its feature-state basis.

Do not treat every apiextensions.crossplane.io/v1 resource as legacy. Require explicit deprecation metadata or an explicit legacy label.

For project history:

• exclude issues, pull requests, comments, and reviews authored by bots or apps

• phrase an open issue only as a reported problem or behavior

• phrase an open or unmerged pull request only as a proposal

• require merge-commit containment in the selected release tag before stating that a pull request is included in that release

• do not treat a closed issue as fixed without a linked released change

• keep post-release developments separate from selected-release behavior

• record the research timestamp because item state may change

Corroborate reusable patterns from third-party examples with primary sources or official documentation. Label repository-specific design choices as such.

Do not copy third-party code or configuration unless its license permits reuse and the generated concept records attribution. When the license is absent, unclear, or incompatible, summarize the pattern and cite the source instead.

6. Build a claim ledger

Before writing Markdown, reduce the evidence packets to a claim ledger:

• concept identifier

• exact claim

• claim class: API, behavior, documented guidance, historical context, release history, reported limitation, proposal, or illustrative pattern

• source role

• supporting immutable citation or direct issue/PR snapshot

• confidence: direct, corroborated, or inferred

• Crossplane release or documentation series

• feature state and basis: explicit label; served alpha or beta API ceiling; Stable API repository default when no non-stable current evidence exists; Not stated by selected sources for unlabelled non-API surfaces; or the least stable required surface for a pattern

• design document status, accuracy warnings, and current corroboration result for historical-design evidence

• selected-release relationship for issue and pull-request evidence

• research timestamp for project-history evidence

• legacy exclusions applied

• unresolved conflict or limitation

Drop claims that do not improve the concept. Keep inferred claims clearly labelled in the final document or omit them.

7. Write as the root agent

Create or update OKF documents under catalog/ according to references/okf-profile.md.

Rules:

• one independently useful concept per file

• structural Markdown over long prose

• package, schema, behavior, documentation guidance, historical context, examples, and project history are separate concepts or sections when each is useful alone

• preserve existing unknown frontmatter fields

• add natural-language cross-links, not a generic link dump

• record externally sourced provenance in frontmatter sources

• give every claim-bearing source a stable sources[].id and cite claims with matching keyed Markdown footnotes

• record the current representation with generated.by and generated.at; never emit the superseded v0.1 timestamp field

• add verified only when an actual machine or human verification event occurred

• update affected index.md files for progressive disclosure

• update log.md only with high-level knowledge changes

• label design-derived material as historical context and pair current facts with current implementation or documentation evidence

• identify third-party examples as community examples and name their originating repository

• distinguish copied examples, adapted examples, and summarized patterns

• exclude Claims, deprecated CompositeResourceDefinition v1, legacy v1 XR semantics, and sections explicitly labelled v1 Composite Resources (Legacy)

• keep current APIs that use /v1 when they are not deprecated

• keep Crossplane CLI content outside the Core catalog section

• group issue and pull-request summaries by user-facing theme instead of creating one page per item

• separate Included in selected release, Known reports for selected release, and Post-release proposals or developments

• label open issues as reports and open or unmerged pull requests as proposals

• include the project-history research timestamp

Do not copy large design documents, documentation passages, issue bodies, pull-request descriptions, or comment threads. Summarize and cite.

8. Apply the Upjet evidence gate

For every Upjet managed-resource concept, require all of these before publishing a Terraform relationship:

• Crossplane group, version, and kind

• Upjet configuration or generated metadata naming the Terraform resource

• matching Terraform provider source, schema, or official documentation

• explicit notes for Upjet or Crossplane transformations and additions

When any link is missing, record the mapping as unresolved. Do not infer it from names.

9. Validate deterministically

Validate the three OKF v0.2 conformance rules:

1. Every non-reserved Markdown file has parseable YAML frontmatter.

2. Every concept frontmatter has a non-empty type.

3. Reserved index.md and log.md files follow their specified structures.

Also check:

• the bundle-root catalog/index.md declares okf_version: "0.2"

• no concept uses the superseded v0.1 timestamp field or # Citations body section

• every source cited by a keyed body footnote has a matching stable sources[].id

• every sources entry contains a non-empty resource

• every generated mapping contains a valid actor in by; every present at value is an ISO 8601 datetime

• verified records only actual verification events and uses the OKF actor convention

• source lock entries exist for all generated released-source concepts

• released-source evidence citations contain immutable commit SHAs

• historical-design citations pin the selected Crossplane commit and record document status and accuracy warnings

• design documents are not used for general feature discovery, current facts without corroboration, or feature-state classification

• cited files and line anchors resolve when network access is available

• internal Markdown links are valid; report broken links as warnings because OKF permits them

• no concept contains unresolved placeholders presented as facts

• Core concepts record the selected stable release and matching documentation series

• function concepts record the dynamically selected stable function tag and commit

• explicit feature-state labels are preserved

• served v1alpha* APIs are never recorded above Alpha and served v1beta* APIs are never recorded above Beta

• an explicit Stable label that conflicts with a served alpha or beta API is recorded as a conflict, not accepted as Stable

• v1 alone is not used as proof of Stable

• Stable is used by repository default only when no selected current source or relevant served API indicates a non-stable state

• legacy-free output excludes Claims, deprecated XRD v1, legacy v1 XR semantics, and explicitly labelled legacy sections

• current non-deprecated APIs are not excluded only because they use /v1

• Crossplane CLI content is not categorized as Core

• each function concept uses its dedicated function agent set and bounded source profile

• Sprig concepts use the exact dependency version from the selected function release and apply function-map exclusions

• project-history entries have a research timestamp and exclude bot- and app-authored activity

• merged pull-request release claims prove commit containment in the selected tag

• open issues and unmerged pull requests are labelled as reports or proposals, not released facts

• closed issues are not presented as fixed without released corroboration

• official documentation claims retain their version scope

• third-party examples are labelled as illustrative and are not used alone for general behavior claims

• copied or adapted third-party material includes verified license information and attribution

Use an installed OKF linter when available, but do not add or install dependencies without the user's approval. Always retain the three core checks as the minimum validation gate.

10. Review once

After deterministic validation passes, use okf-reviewer on the changed concepts and their claim ledger. Do not invoke the reviewer while blocking validation errors remain.

Fix blocking findings as the root or parent agent and rerun targeted validation. After all fixes, run mise run lint and fix every reported issue. The reviewer may return APPROVED only after the final lint run succeeds. Commit only after approval.

Token and model policy

Shared rules:

• Keep at most three direct research agents active at once.

• Use one final evidence review over changed concepts, not over all source repositories.

• Prefer targeted searches, schemas, tests, documentation sections, explicitly selected design documents, configured example paths, and issue/PR queries over recursive repository reads.

• Batch related third-party example repositories instead of assigning one agent per repository.

• Summarize issue and pull-request history by user-facing theme and omit low-signal housekeeping.

• Return summaries and evidence references, never raw exploration output.

• Reuse source locks, evidence packets, and unchanged concepts across runs.

Codex model selection:

• Use gpt-5.6-luna with low reasoning for inventory and routing.

• Use gpt-5.6-terra with medium reasoning for normal source interpretation.

• Use flagship gpt-5.6 with high reasoning only for ambiguous Upjet-to-Terraform mappings.

• Use gpt-5.6-terra with high reasoning for the final review.

Pi model selection:

• Project agents intentionally do not pin a provider-specific model identifier or thinking level. They inherit the model and supported capabilities selected for the Pi session.

• Configure local or hosted models outside this repository so the workflow remains portable across Pi providers.

• Non-thinking coding models such as Qwen3-Coder-Next can run every project agent without incompatible reasoning controls.

• Use a stronger or different model for ambiguous Upjet mappings and the final evidence review when one is available.

• Follow .pi/README.md for local Qwen3-Coder-Next configuration guidance.

Completion report

Report:

• concepts created, updated, or removed

• pinned source commits used

• selected Crossplane release and documentation series for Core work

• selected historical design documents, pinned commit, stated status, and corroboration result

• selected stable function tags and commits

• source roles used for material claims

• explicit feature-state citations, served alpha or beta API ceilings, or the Stable repository-default basis

• legacy material excluded

• project-history timestamp, human-authored items summarized, and bot/app activity excluded

• deterministic validation and mise run lint results

• reviewer status

• unresolved mappings, conflicts, licensing questions, historical design differences, and permitted broken links

• the narrowest next source batch, when more coverage is requested