User Guide

Current — this is the living version. Historical snapshots are linked from Index-Releases.

User Guide

Day-to-day use of okf-graph-eng on an OKF repository.

Concepts

The plugin treats your OKF bundle as a dual graph:

1. Knowledge graph — datasets, metrics, runbooks, APIs, references
2. Agent / harness graph — AgentNode, Workflow, SharedState, DecisionRecord, ToolCapability, TicketLink

Edges are absolute Markdown links ([Label](/path/to/concept.md)). Optional typed relations live in frontmatter:

links:
  - target: /agents/writer.md
    rel: routes_to

Common workflows

Scaffold a bundle

• Slash: /okf-init
• Or ask to initialize an OKF graph-engineering bundle (skill: okf-init-graph)

Default tree: .okf/ with agents/, workflows/, knowledge/, decisions/, shared/, tickets/, plus index.md and log.md.

Author concepts

Use skill okf-author (or /okf-author). Every concept needs at least type, title, description, timestamp.

Impact before structure changes

python3 scripts/okf-graph.py impact <bundle> <concept>
# or /okf-impact

Prefer this before renaming or splitting high-degree agents, workflows, or shared state.

Progressive disclosure packs

Default: 2 hops, ~20 nodes, following outbound edges only. Add --undirected to walk inbound edges too — useful for "what would break", but it floods easily through hub index pages.

python3 scripts/okf-graph.py pack <bundle> <concept> --hops 2 --max-nodes 20
python3 scripts/okf-graph.py subgraph <bundle> <concept> --hops 2
# or /okf-query

Visualize

python3 scripts/okf-graph.py graph <bundle>                          # mermaid (default)
python3 scripts/okf-graph.py graph <bundle> --focus <concept> --hops 2
python3 scripts/okf-graph.py graph <bundle> --format html > graph.html
python3 scripts/okf-graph.py graph <bundle> --format json
# or /okf-visualize

Whole-bundle by default, including isolated concepts. --focus scopes to one concept's neighborhood. The html output is a single self-contained file — no CDN, no network fetches — so it opens straight from disk.

Validate

python3 scripts/okf-graph.py validate <bundle>
python3 scripts/okf-graph.py validate <bundle> --strict   # warnings also exit non-zero
# or /okf-validate

Default is lenient. Only errors — a broken link, a missing root index.md — exit non-zero. Warnings (missing type or title, an unverified high-impact concept, a TicketLink with no external_id/worklog_id) print but still exit 0. Use --strict to make warnings gate CI. Every skill and the post-edit hook call the lenient form.

Maintain

python3 scripts/okf-graph.py orphans <bundle>    # concepts with no edges either way
python3 scripts/okf-graph.py edges <bundle> --rel routes_to
# or /okf-maintain

Curation on save

The post-edit hook (Write|Edit|MultiEdit) runs scripts/okf-curate.sh on OKF paths and validates the surrounding bundle. It reports; it never blocks the edit.

Tickets (WikiTicket / worklog)

This repo is managed with WikiTicket SDD. Map work items into OKF:

bin/worklog fold | python3 scripts/okf-ticket-link.py emit --bundle sample-okf --open-only

Sample bundle

sample-okf/ models this plugin as both knowledge and agent graph. Use it as a template and for demos.

See also

• CLI-Reference — scripts and flags
• Plugin-Guide — install on Claude Code / Grok Build
• Roadmap — generated from the worklog