| name | okf-validate |
| description | Validate OKF v0.2 conformance and graph quality — orphans, connectivity, staleness, unverified high-impact nodes, broken links, missing frontmatter. Use when checking bundle health, before commits/PRs, after bulk edits, or when the user asks if the OKF graph is valid. |
OKF Validate
Goal
Confirm the bundle is structurally sound (OKF-oriented conventions) and graph-quality healthy for engineering use.
Checks
Conformance (structural)
- Root
index.md present; prefer okf_version: "0.2"
- Concept files use YAML frontmatter starting with
---
- Required-ish fields:
type, title (warn if missing on non-index files)
log.md present (warn if missing)
Graph quality
- Broken Markdown links to missing
.md targets (error)
- Orphan concepts (info/warn)
- High-impact unverified nodes:
AgentNode, Workflow, Harness, SharedState with verified: false (warn)
- Stale nodes past
stale_after (warn)
- Empty catalogs / empty agent graph when user expected harness modeling (info)
Process
- Resolve bundle path (argument,
.okf/, sample-okf/, or user path).
- Run tools:
okf validate <bundle>
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/okf-graph.py" validate <bundle>
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/okf-graph.py" orphans <bundle>
- Optionally spot-check a sample of high-degree nodes for body quality (not just links).
- Emit a pass/fail summary with issue table.
Output format
# Validation: <bundle>
**Result:** PASS | FAIL (N errors, M warnings)
| Severity | Path | Message |
|----------|------|---------|
| error | ... | ... |
## Graph stats
- Concepts: N
- Orphans: K
- Unverified high-impact: J
Rules
- Deterministic tools first; LLM judgment only for qualitative notes.
- Do not modify files unless the user asks to fix issues (then hand off to
okf-maintain / okf-author).
- Exit guidance: FAIL if any broken links or missing root index; otherwise PASS with warnings.
Done when
- Clear PASS/FAIL and actionable issue list
