>_ yoshiko-flow v0.4.0

yf-okf

Constructs, manages, and conformance-checks the OKF-compatible artifact folders ('bundles') that yf artifact-producing s

Constructs, manages, and conformance-checks the OKF-compatible artifact folders ('bundles') that yf artifact-producing skills emit (yf-plan, yf-research, yf-incubator), and owns the versioned OKF-* spec family (BASELINE + YF-EXTENSIONS + per-skill OKF-EXTENSION). The engine (okf.py) composes the effective ruleset and runs check (report-only conformance) and migrate (opt-in, per-folder, in-place).

At a glance

  • Category: utility
  • Invocation: /yf-okf (user-invocable)
  • Requires tools: uv
  • Source: SKILL.md · README.md

When it fires

/yf-okf invoked (init | check | migrate | assess); checking whether an artifact folder conforms to the OKF model; migrating a legacy plan/research/incubator folder to the reserved index.md + log.md + frontmatter+type model; or running an impact assessment of a corpus before adopting OKF.

When to skip it

authoring third-party OKF linters / validators / MCP servers (yf-okf is a producer/manager plus a conformance self-check, not a third-party validator); checking that already-written docs AGREE across declared edges (that is yf-drift-check, an orthogonal axis); running a repo's build/test/lint recipe (yf-change-validation). yf-okf never fires on an ordinary edit — it is operator-invoked.

Prerequisites

  • Claude Code (the skill loads as part of this repo's skill set).
  • uv on PATH (depends-on-tool: [uv]) — the engine is a PEP-723 uv run --script Python script with inline pyyaml. No in-repo skill dependency (depends-on-skill: []): the engine is vendored into each consumer, never force-installed.

Usage

User-invocable (/yf-okf) with four subcommands:

  • init — consent-only setup (prereq check; the skill installs automatically).
  • check [<dir>] — composed-ruleset conformance self-check over a bundle; report-only.
  • migrate <dir> [--dry-run] — opt-in, per-folder, in-place migration to the OKF model.
  • assess <corpus> — Epic-2 impact assessment: discover bundles under a root, run check + migrate --dry-run over each, produce an aggregate impact report (dispatches agents/assessor.md).

Scope boundary: yf-okf owns the shape of yf artifact bundles. Running a repo's build/test/lint recipe is yf-change-validation; checking that already-written docs agree across declared edges is yf-drift-check — orthogonal axes yf-okf never invokes.

OKF-* family

The effective ruleset is the composition OKF-BASELINE ∪ OKF-YF-EXTENSIONS ∪ per-skill OKF-EXTENSION.md. BASELINE + YF-EXTENSIONS are baked into okf.py (no runtime cross-skill read); the two spec/ docs are the authored reference, kept in agreement with the baked ruleset by a yf-drift-check edge. Only the per-skill member is resolved at runtime, __file__-relative to the running (vendored) okf.py, so composition runs from any vendored copy in both the worktree and installed address spaces.

Behavior model

/yf-okf check <dir>    ──▶ compose ruleset ──▶ report findings (report-only, crash-safe); exit 1 if not ok
/yf-okf migrate <dir>  ──▶ --dry-run first (change plan) ──▶ opt-in in-place write (merge-and-preserve,
                            fingerprint-stable, first scoping date preserved)
/yf-okf assess <root>  ──▶ discover bundles ──▶ per-bundle check + migrate --dry-run ──▶ impact report
  • Report-only check / assess never mutate the corpus; crash-safe on messy input.
  • Merge-and-preserve writes never drop a pre-existing frontmatter key.
  • No auto-fix — migration is the only write path, and it is opt-in and per-folder.

Layout

skills/yf-okf/
├── SKILL.md                    # engine: operational summary, invocations, dispatch
├── README.md                   # this file
├── LICENSE                     # MIT
├── SPEC.md                     # requirement-numbered (REQ-OKF-*) per-skill spec
├── agents/
│   └── assessor.md             # read-only corpus assessor (Epic-2 assess surface)
├── scripts/
│   └── okf.py                  # vendored engine (Issue 1.6 registers the sync); canonical: _shared/okf.py
└── spec/
    ├── OKF-BASELINE.md         # upstream OKF v0.1 rules (pinned okf_version: 0.1)
    └── OKF-YF-EXTENSIONS.md    # the yoshiko-flow extension layer (reserves OKF-SPECIFICATION)