NAVIGATOR
Practitioner track
Module 03 of 6

Sessions, Events, Artifacts

Operate ATLAS Phase 1 cleanly: open a session, log decisions that survive review, and register artifacts that hold up.

90 MINFOCUS · ATLAS PHASE 1

Outcome: Operate ATLAS Phase 1: open a session, log decisions, register artifacts.

Introduction

COMPASS only works if the work is visible to the team, not trapped in one person's chat history. ATLAS is where that visibility lives. This module is the operational core of the Practitioner track: the everyday loop of working inside ATLAS so that what you did, why you did it, and what you produced are all on the shared record.

Everything here is exposed as compass_* tools over MCP — the same surface your Claude Code session calls. You don't need to memorise all 53; you need the everyday handful and the discipline to use them.

What you'll be able to do by the end

  • Open, resume, and close a COMPASS session attached to the right Journey
  • Log decisions with rationale that a reviewer who wasn't there can follow
  • Register and update artifacts through the version + status machine without breaking it

1. The shared-brain model

One premise underlies all of this:

Same data, two entry points. Your agent reads and writes project state over the MCP server; your teammates see and act on that same state through the web app. Every mutating call also writes an immutable event, and that event log is the source of truth for the activity feed and the audit trail.

So "doing the work in ATLAS" isn't bureaucracy — it's how the work becomes the team's, automatically. The cost is a few extra tool calls; the payoff is that no context is private by accident.

2. Sessions — scope a stretch of work

A session scopes a stretch of your activity inside one project. Sessions are unique per (user, project) while open — opening a second just resumes the first.

ToolWhat it does
compass_session_openOpens or resumes your session. Pass journey_slug to attach it to a Journey.
compass_session_contextYour open session + recent events — the canonical "what was I doing?" call.
compass_session_closeCloses your session, optionally with a summary of what you accomplished.

The discipline:

  • Open against the Journey you're working on. An attached session means your events, decisions, and artifacts roll up under that feature automatically.
  • Resume with context. Coming back after lunch (or after a week)? compass_session_context replays the recent events so you re-enter where you left off instead of guessing.
  • Close with a summary. A two-sentence close-out summary is the cheapest handoff you'll ever write — and the next person (or the next you) reads it first.

3. Events — the append-only record

Every mutating action emits a structured event. You can also log free-form ones with compass_activity_log (a lowercase dotted kind plus an opaque JSON payload). The activity feed (compass_activity_feed, or the web board) is just this log, newest-first.

You rarely need to log events by hand — the artifact and decision tools do it for you. What matters is the mindset: the event log is immutable and shared. It's not your private notebook; it's the project's memory. Write as if a teammate will read it tomorrow, because they will.

4. Decisions — the why that survives review

The single most undervalued tool. A decision record is a logged choice plus its rationale:

  • compass_decisions_log — a summary (≤500 chars), a rationale (≤8000), and related_slugs[] that cross-link the artifacts or journeys the decision touches.

A decision that survives review answers three questions a reviewer who wasn't in the room will ask:

  1. What did you decide? ("Use Postgres row-level security instead of app-layer tenant checks.")
  2. Why, and what did you reject? The rationale — the alternatives considered and why this one won.
  3. What does it touch? The related_slugs, so the decision shows up against the right spec and stories.

The test for a good decision record Could someone reverse or defend this choice in three months without finding you and asking? If the rationale only lives in your head or a Slack thread, it doesn't survive review. Write it down where the artifact is.

Decisions you log become traceable context for every later phase — and they're exactly what a reviewer reaches for when an artifact looks surprising.

5. Artifacts — versioned, with a status machine

Artifacts are the deliverables: feature_request, feature_specification, user_story, implementation_plan, code_and_tests, release_artifacts. They're immutable per version — metadata lives in ATLAS, content in object storage.

ToolWhat it does
compass_artifact_registerCreate an artifact + version 1.
compass_artifact_updateAppend a new version.
compass_artifact_list / _historyMetadata only — what exists, and every version.
compass_artifact_getDownload a specific version's content.

Two rules that keep the version chain honest:

  • The status machine is DRAFT → REVIEW → ACCEPTED → IMPLEMENTED (or → ARCHIVED). You don't jump straight to ACCEPTED — an artifact earns it by passing a review (Module 05). Moving status is a deliberate status_change, not an accident.
  • change_summary must match the document. When you append a version, its change_summary.version must equal current + 1 and match the latest entry in the document's own revision-history block. The metadata and the document never drift apart. (For files over ~1 MB or binaries, use the HTTP upload endpoint / atlas-upload script instead of inlining base64.)

6. A clean session loop

Put it together. A tidy stretch of COMPASS work looks like this:

1. compass_session_open        (attach to the journey)
2. …do the work with your agent…
3. compass_decisions_log       (capture each real choice + rationale)
4. compass_artifact_register / _update   (register what you produced)
5. compass_session_close       (summary: what got done, what's next)

Five steps. The middle is where your skill lives; the bookends are what make the work the team's instead of yours alone.

Exercise — run one clean session

On a sandbox project, take a single small task end to end:

  1. Open a session attached to a journey.
  2. Make one real decision during the work and log it with a rationale a stranger could follow — name at least one alternative you rejected.
  3. Register or update one artifact, with a change_summary that matches its revision-history block.
  4. Close the session with a two-sentence summary.

Then open compass_session_context (or the web activity feed) and read your own trail back. If you can reconstruct exactly what you did and why from the record alone — without your memory filling gaps — you've operated ATLAS cleanly. Module 04 chains these artifacts together into a full Journey.

Next: Artifact Chains End-to-End