Whereami primitive
docs/whereami.md — the singleton project-state snapshot every session reads at start and updates at end.
Ships with bassclef execution
The whereami file is not something you edit by hand in normal flow.
It ships with bassclef, is auto-read by the session-start hook, and
is auto-updated by /session-end at every substantive close. Skills
like /sprint and /longrun prep read it as the primary
project-state source. You look at whereami to orient after a gap;
you do not write to it directly.
Read this page when you are picking up a project after a gap and want to know what lives in the snapshot, or when you are writing a skill that needs project state.
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.mdWhat 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.
Who reads it
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.
Related concepts
- State spine — the authoritative layer whereami sits inside
- Chronicle — the narrative companion to the whereami snapshot
- Accessor library — how consumers read and write whereami through typed functions
Chronicle
Narrative record of a session — what shipped, what was decided, what's still open. Written automatically at session end by /session-end.
Built with bassclef
What bassclef actually did on this site, counted from files. Every number here comes from a chronicle, a state marker, or a git-log commit.