Session start protocol — 5 minutes before any code

Why

A new Claude session starts with no memory. Without a startup ritual, it defaults to its instinct — jumps to code, ignores state, overwrites other work. 5 minutes of reading saves hours of debugging.

Reading order (5 min, BEFORE you do anything)

1. CLAUDE.md (repo root, auto-loaded) — non-negotiable harness rules.
2. Session brief (docs/session-briefs/next-session-phase{N}-brief.md) — current state, first task, insights/gotchas.
3. Phase spec (external roadmap — ClickUp / Linear / Notion) — current phase DoD.
4. Relevant ADR (external doc or docs/adr/) — architectural decisions affecting current scope.
5. Credentials (.env.*.local or other gitignored file) — fallback for connection strings.

Kick-off message (paste on start)

I'm a new Claude session for <project>. Read:
1. CLAUDE.md
2. docs/session-briefs/next-session-phase{N}-brief.md
3. <phase spec link>
4. <relevant ADR link>

Act per the harness. Plan before code. Wait for GO.

Infra quick-check (run before the first commit)

git switch <feature-branch> && git pull
cat CLAUDE.md | head -40
curl -s <backend-test-url>/health
<cli> whoami --json | head -3
psql "<test-pooler-url>" -c "SELECT ..."

Pre-flight checklist (before the first plan)

• Phase spec read (DoD clear)
• Relevant ADR read
• git log -5 --oneline + git status checked
• Test env verified
• Credentials located
• I know what the first concrete task is

What NOT to do at start

• DO NOT edit any file before reading CLAUDE.md + brief
• DO NOT trust your memory from the previous session
• DO NOT guess state — read the brief
• DO NOT skip the quick-check (30 seconds — saves hours)
• DO NOT start with git push or git reset — check state first

Closing the session

Before session end, always:

1. Status note in external system
2. If phase closed → create next-session-phase{N+1}-brief.md
3. git log -5 --oneline — are commits atomic?
4. TODO list reflects state