| name | okf-maintain |
| description | Curate OKF bundles — indexes, log.md, drift detection, broken links, orphan cleanup, staleness, and v0.1 to v0.2 migration. Use when the graph feels messy, catalogs are out of date, links break, content is stale, or the user asks to maintain, curate, or migrate an OKF bundle. |
OKF Maintain / Curate
Keep the dual knowledge + agent graph healthy and reviewable.
Maintenance checklist
- Broken links — every Markdown link to a
.md target resolves inside the bundle.
- Orphans — concepts with no inbound or outbound edges (except intentional roots).
- Index drift — subdirectory
index.md catalogs list actual children.
- Log hygiene —
log.md has recent entries for structural changes.
- Staleness — nodes past
stale_after or long-unchanged high-impact agents.
- Trust gaps — high-impact types (
AgentNode, Workflow, SharedState) with verified: false.
- Frontmatter completeness —
type, title, description, timestamp.
- Migration — if
okf_version is missing or 0.1, plan upgrade to 0.2.
Process
- Locate bundle root.
- Run deterministic checks:
okf validate <bundle>
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/okf-graph.py" validate <bundle>
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/okf-graph.py" orphans <bundle>
- Produce a curation report with severity (
error / warn / info) and suggested fixes.
- Apply safe automatic fixes only when asked or clearly desired:
- Regenerate index listings from directory contents
- Append log entries for performed maintenance
- Fix obvious relative→absolute link rewrites only with confirmation if many files change
- For migrations v0.1 → v0.2:
- Set
okf_version: "0.2" on root index
- Ensure absolute-link convention is documented
- Add graph-eng directories (
agents/, workflows/, …) only if missing
- Do not delete legacy concepts
Report template
# OKF Curation Report — <bundle>
Date: ...
## Errors
- ...
## Warnings
- ...
## Info
- ...
## Applied fixes
- ...
## Recommended follow-ups
- [ ] ...
Rules
- Prefer small, reviewable commits/changesets over mass rewrites.
- Never invent domain content while curating.
- Preserve user wording in concept bodies; only fix structure/metadata when needed.
- After fixes, re-validate.
Done when
- Report delivered (and optional fixes applied)
- Validation error count is zero or remaining errors are explicitly listed as deferred
