all-the-vibes/atv-phoenix/phoenix-okf

phoenix-okf — knowledge that pays rent in the open

Overview

OKF (Open Knowledge Format) is a vendor-neutral spec for representing knowledge as a directory of markdown files with YAML frontmatter — one required key (type), graph-shaped via plain markdown links, with index.md for progressive disclosure. It is the format Phoenix's Context Assembly pillar already implies: pay once to understand structure, then never again. This skill makes that knowledge portable and inspectable instead of trapped in an opaque .token-master/graph.json.

A bundle is a directory. If you can cat a file you can read it; if you can git clone it you can ship it.

When to use

• You have a graphed repo (.token-master/graph.json) and want the knowledge **human-readable,

diffable, and consumable by any tool** (Obsidian, the OKF graph viewer, another agent).

• You want skill discovery to ride a standard progressive-disclosure format.
• You want to feed an external OKF bundle (a data catalog, runbooks, org knowledge) into a

Phoenix run as cheap context.

When NOT to use: a single local lookup grep answers in one turn. OKF earns its place on reusable, shareable knowledge, not one-off questions.

Three moves

1. Produce — code graph → OKF bundle

python scripts/okf_export.py --graph .token-master/graph.json --out okf-out --name <repo>

One concept document per source file; cross-file edges become bundle-relative markdown links. INFERRED (name-matched, ~0.8-confidence) edges are flagged candidate — verify at the cited `file:line` before trusting one for a risky change (phoenix-context honesty rule). Auto-writes per-directory index.md, a root index.md (declaring okf_version), and a log.md.

2. Validate — the objective gate

python scripts/okf_validate.py okf-out

Checks OKF §9 conformance: every non-reserved .md has parseable frontmatter and a non-empty type; reserved files (index.md/log.md) follow their rules. Exit 0 = conformant — use it as a phoenix_sense check. Broken cross-links are tolerated per spec (warning, not error) unless --strict-links.

3. Consume — ingest an OKF bundle as cheap context

python scripts/okf_ingest.py <bundle> [--query TYPE_OR_TAG] [--full PATH] [--max N]

Index-first by default: emits the bundle's progressive-disclosure outline (types, tags, concept list) without dumping every document — the cheapest sufficient context. --query filters by type or tag; --full prints one concept's body. Tolerates broken links and unknown types.

Bonus — make the skill pack itself an OKF bundle

python scripts/okf_skillsync.py skills

Adds type: Phoenix Skill to each SKILL.md (idempotent, non-breaking) and generates skills/index.md, so the capability library and knowledge share one progressive-disclosure roof.

Why this elevates Phoenix

• Context Assembly, now inspectable. The strongest measured pillar (TokenMasterX) stops

hiding in JSON; its knowledge becomes a git-reviewable artifact.

• Reuse standards, don't reinvent. Adopts a vendor-neutral spec instead of a bespoke schema.
• Harness → platform. Producing and consuming OKF turns a code harness into a knowledge

platform that carries and grows knowledge across runs.

Red Flags

• Dumping a whole bundle into context. → okf_ingest index-first, then --full only what matters.
• Trusting a candidate edge for a refactor. → Verify at file:line, or escalate to the AST backend.
• Hand-editing the generated bundle. → It is derived; re-run okf_export and let git diff it.

Citations

[1] Open Knowledge Format SPEC v0.1 — local mirror of GoogleCloudPlatform/knowledge-catalog/okf/SPEC.md.