orient: pick the next move

When to use it

• You have a bundle (or think you might) and no clear next step. Orient reads the signals and tells you which verb pays off most right now.
• You just picked up a repo with an unfamiliar .okf/ directory and want a state-of-the-bundle briefing before touching anything.
• In Claude Code, /okf:gem with no arguments lands here.

What the agent does

Orient is a diagnosis, not a workflow. The agent works down a short ladder of signals and stops at the first one that decides the recommendation:

1. Is the CLI present? okf --version. If it is missing, the only useful move is setup: the agent recommends doctor and stops there. Everything below needs the CLI.
2. Is there a bundle? The directory you named, else a .okf/ directory, else a root index.md whose frontmatter carries okf_version. No bundle means nothing to curate, maintain, or consume yet, so the recommendation is produce: create the first bundle from the code, the docs, or what lives only in people's heads.
3. What state is it in? The agent measures instead of eyeballing: okf validate --json, okf lint --json, okf loose --json. Then it recommends by what they report, most blocking first:
   • validate reports errors: lead with curate. Section 9 conformance errors are the only hard failures, and they get fixed before anything else.
   • clean validate but lint or loose findings: still curate, to settle the curation debt, naming the top one or two categories from the report.
   • clean across the board: the bundle is healthy, so lead with consume and offer maintain for when the code or docs have since changed. If git status shows uncommitted changes to code the bundle describes, prefer maintain: that is exactly the drift it exists to close.
4. A freshness caveat. If the bundle carries timestamps, the agent notes that a plain lint said nothing about staleness, and that okf lint <dir> --stale-after 90d is the check that would.

The output is two or three pointed picks, each with the exact command to run and a one-line reason drawn from the signals. The agent never runs a workflow from here; the choice stays with you.

Try it

In Claude Code with the okf plugin, run /okf:gem with no arguments. Without the plugin, ask the skill in plain words:

I have an OKF bundle in docs/. What is the highest-value thing to do with it right now?

Pitfalls

• Orient recommends but never auto-runs. If the agent starts fixing lint findings from here, it has skipped the handoff; the fixing belongs to curate after you pick it.
• The signals come from the CLI, not from skimming files. An agent that opens a few concepts and calls the bundle "fine" has not oriented; the three --json measurements are the diagnosis.
• A quiet report is not "nothing to do". Freshness is off by default, so a clean lint says nothing about stale concepts, and a healthy bundle is exactly the one worth consuming.