Whereami primitive

docs/whereami.md — the singleton project-state snapshot every session reads at start and updates at end.

Use this when

You are picking up a project after a gap and want to know where things stand, or you are writing a skill that needs project state.

Skip this when

You need a specific piece of state that is not in whereami — check the state-spine catalog for the entity that carries it.

What it is

A single Markdown file with YAML frontmatter at docs/whereami.md (or whereami/whereami.md in some adopter layouts). One file. One authoritative snapshot of project state.

Storage shape: Shape A (singleton JSON authoritative) or Shape B (Markdown + frontmatter, depending on adopter). Per bassclef 0.30+, Markdown + frontmatter is standard.

standards/whereami-schema.md

What lives in it

Frontmatter — schema version, tier, last-updated timestamp
Project-level phase — Inception / Elaboration / Construction / Transition
Active iteration — bet reference + phase + operator recap
Active sessions — sessions in flight
Subsystem phases — table of subsystems and their state
Gate progress — checkboxes for major gates
Risk register — retired + open risks
Recent /promote candidates — items filed but awaiting triage
Live URLs — production endpoints (for repos that ship a service)

The full schema lives at standards/whereami-schema.md.

Every session start. The bassclef-sync hook reads whereami as the freshness signal. The /sprint skill reads it as the primary project-state source. The /longrun prep skill reads it before proposing scope.

Who writes it

The /session-end skill updates whereami at session close. Frontmatter last_updated bumps to the current UTC timestamp. The operator_recap section gets a new entry (with prior entries pushed down as prior_operator_recap).

Never write whereami mid-session. It is a session-end artifact.

Freshness

Whereami has a freshness signal — if the file is stale (over 7 days since last update AND commits have happened), the bassclef-sync hook BLOCKS the session with an update prompt. This catches "I forgot to run /session-end" and prevents the file from silently rotting.

State spine — the authoritative layer whereami sits inside
Session log — the narrative companion to the whereami snapshot
Accessor library — how consumers read and write whereami through typed functions