Start session

start-session

The always-on entry point for an atlas session. Assemble the Session Primer, hold it as starting context, then route to the right skill.

<SUBAGENT-STOP> If you were dispatched as a subagent to execute a specific task, skip this skill entirely — implementation only. The controller session owns session start and vault integration. Subagents never route on their own. </SUBAGENT-STOP> <EXTREMELY-IMPORTANT> If you are a primary agent and there is even a **1% chance** this is the start of a session, a resumed session, a post-compaction continuation, or a post-clear/reset context, you ABSOLUTELY MUST run this skill before anything else — before any response, any clarifying question, any code exploration, any file read. This is not negotiable and you cannot rationalize your way out of it.

These thoughts mean STOP — you are rationalizing:

Thought	Reality
"This is just a quick question"	Questions open sessions. Build the primer first.
"Let me just check the repo/files first"	The primer is the context you'd check against. It comes first.
"I'll load context after I answer"	There is no after — starting context must be held from the first response.
"The user just cleared context; this isn't a new session"	A clear/reset is a new primary-agent context. Rebuild the primer before continuing.
"I'll wait until I'm told to start"	The trigger lives here, in this skill. Nothing else will tell you. Run it.

Building the Session Primer first is not optional. The one exception is the quiet exit in §1: if the primer reports the project is not an atlas workspace, stop silently and proceed normally — do not pitch initialization. </EXTREMELY-IMPORTANT>

1. Build the Session Primer

Run the bundled build_primer.py relative to this skill directory. Take the source path the harness supplied for the currently loaded SKILL.md, resolve its sibling build_primer.py, verify that file exists, then invoke its absolute path with unqualified python3 so the active shell PATH selects the interpreter.

If the harness did not expose the loaded skill's source path, or the sibling script is missing, stop and report start-session cannot locate its bundled build_primer.py. Do not search known install roots or fall back to another copy.

• If it prints ATLAS_UNINITIALIZED: …, this project has no Project Binding (.atlas.toml) — it isn't an atlas workspace. Stop silently and proceed with the user's request normally; do not mention atlas or pitch initialization. This skill triggers on any session (the trigger lives in the skill, not in a per-project file), so an unbound project is the common, expected case — exit quietly. Only route to initialize-atlas if the user is explicitly setting up atlas (e.g. "initialize my workspace", "bind this repo to a vault").
• If it reports ATLAS_PATH is not set, the vault location is unknown — ask the user to export ATLAS_PATH=<their atlas vault root> (it always points at the atlas vault), then re-run.
• Otherwise, treat the printed payload as your Active Context for the session — User Profile, Shared Memory, the Workspace Brief, and (when the repo tracks work in Mimir) the current work queue. Internalize it; don't echo it back to the user.
• If the payload opens with a ⚠️ Primer hygiene banner, the Workspace Brief has outgrown its groomed baseline (or was never consolidated). Surface that soft recommendation and offer to run consolidate-workspace — it's non-blocking, so proceed with the user's request either way; don't let it derail the session.

2. Hold the through-line

A Session is bounded by a body of work, not by one context window. The primer is what you re-load on each resumption — including compactions, clears/resets, and new windows — to keep the work's through-line intact.

3. Decisions & glossary are live

The workspace glossary.md and decisions/ are authored by the domain-modeling skill: it maintains the glossary (from the project's context/domain terms) and writes the ADRs. Redirect that skill to the workspace location — the vault workspace (<ATLAS_PATH>/Workspaces/<workspace>/), where glossary.md and decisions/ live — rather than its default in-repo path.

Repo override: a repo may set decisions = "local" (or a path) in .atlas.toml to keep decisions/glossary in the repo instead of the vault workspace. When that key is present, honor the local target; otherwise default to the vault workspace.

Wherever they live, glossary.md and decisions/ are constraints on the work, not an archive — hold them open the whole session, whatever you're doing (planning, brainstorming, building):

• When planning, check the plan against decisions/. A conflict means either the plan is wrong or the decision is stale — resolve it before building; never silently violate a recorded norm. Updating a decision can cascade, so do it thoughtfully.
• Keep language true to glossary.md. Use its canonical terms and let them frame the problem; challenge drift the moment you notice it.
• Capture as it crystallizes — a term sharpens → glossary; a hard-to-reverse, surprising, real-trade-off decision → an ADR (offer ADRs sparingly). Route both through domain-modeling.

This is general practice, not gated behind any one skill.

4. Routing surface

From the Active Context and what the user wants, route to:

• initialize-atlas — bind/scaffold/heal the workspace (also when the primer reports uninitialized).
• write-session-log — at a work boundary, memorialize the Session.
• consolidate-workspace — lift a workspace's durable knowledge from its Session Logs into the workspace + Mimir.
• consolidate-memory — (global) regenerate the shared user.md / memory.md from user observations across all workspaces.

5. Keep the vault high-signal

Follow resources/workspace-hygiene.md: keep the Brief small, put new files in the right place, prune stale content, and trigger write-session-log at the right time. Don't bloat Active Context. When writing any file into the vault, follow the frontmatter rules in resources/frontmatter.md so agents can find and progressively disclose it.