orient

orient

Ground the session and answer one question: where does this repo stand relative to the standard, and is every gap accounted for? Drift is any unaccounted-for delta — whatever its source. A divergence recorded in ARCHITECTURE.md is on the books, not drift; an undocumented one is drift. Read-only — never writes, scaffolds, or reconciles files.

Step 1 — read in order (load-bearing)

1. Read ARCHITECTURE.md first — the project's durable truth and its recorded Divergences from CONVENTIONS (what varies and why).
2. Then read CONVENTIONS.md — the house style.

Order matters: ARCHITECTURE first means the conventions are read through the lens of where this project intentionally differs, so a recorded divergence is never mistaken for drift.

Brownfield (no CONVENTIONS.md): the repo isn't on the standard. Don't just say "run bootstrap" — do a quick gap assessment: read the bundled canonical CONVENTIONS.md, skim the repo's actual shape, and summarize the largest gaps (layout, contract layer, surface, tooling) and the rough cost of adopting. Then suggest bootstrap. Stop there — read-only.

Step 2 — version & content status (cheap)

Read the project's conventions-version and compare it to the installed canonical (resolved from conventions-source, else the bundled standard). Integer compare; offline-tolerant — if upstream can't be reached, note it and move on.

• In sync → conventions in sync (vN).
• Behind → conventions vX → vY available; summarize the CHANGELOG.md delta and whether it's worth adopting given this project's ARCHITECTURE/divergences. Route to sync to apply.
• Content drift (same version, but the session-start hook flagged a content-hash mismatch, or the user passes --deep): the vendored CONVENTIONS.md / base configs were edited without a version bump. By default just report it and route to sync. Only on --deep do the actual diff of the vendored artifacts against canonical — it's the expensive path, off by default.

Step 3 — divergence check (documented vs. undocumented)

The core of "drift, however it arrives." Compare what the repo actually does against the conventions, then cross-reference ARCHITECTURE.md's Divergences section:

• A departure with a recorded "what varies and why" → fine, not flagged. (This is where platform drift lands too — e.g. "pinned Tailwind v3 because X" is a documented divergence, not drift.)
• A departure without a record → flag it as undocumented drift: name what's off the paved road and that no reason is on file. Rule by reason: the fix is either to record the why in ARCHITECTURE.md or to pull back onto the standard — the user chooses; orient only surfaces it.

Keep this judgment-level and cheap — read what's already in front of you (the two docs, obvious structure). Do not crawl the whole codebase; deep conformance auditing is out of scope.

Step 4 — brief & route

Short orientation: what this project is (from ARCHITECTURE), which conventions are in play, recorded divergences, the version/content status, and any undocumented drift. Route anything actionable to sync (upgrade/reconcile) or bootstrap (brownfield). Then stop.

Notes

• Intentionally tiny so it's cheap to auto-trigger from the session-start hook without dragging the heavier skills into routine sessions.
• The session-start hook does the deterministic cheap checks (version + content hash); orient adds judgment — especially the documented-vs-undocumented divergence call, which a script can't make.
• --deep is the only mode that does expensive content diffing; everything else stays cheap.