Skip to content

Boot Flow Explainer, Brief

URL: https://mkdocs.justinsforge.com/memory/handoffs/explain-boot-flow-brief-2026-05-22/

Your task

Justin wants a phone-readable walkthrough of what auto-loads when a fresh Claude Code session boots on forge, and in what order. Write it to memory/handoffs/session-boot-flow-explainer-2026-05-22.md and stop. No code changes.

Cover, in this order

  1. CLAUDE.md — project-root auto-load on session start; the doctrine hard rules inlined at the top; L4 path-scoped CLAUDE.md files in sub-directories that load when CWD descends (reference example: brands/nova-design/CLAUDE.md).
  2. SessionStart hook → boot briefing — scripts/forge_hook_session_start_since_last.sh runs at every session start. What it surfaces: last session, recent handoffs (7d), pending tasks, monitor alerts, active tmux sessions. The # Boot briefing block Justin sees at the top of every session comes from this script.
  3. MEMORY.md — auto-loaded, first 300 lines, index-not-knowledge-base pattern. Topic files live at memory/general/<topic>.md; MEMORY.md just points to them.
  4. Steering layer — system-map/steering.md and the Phase 4.8 runtime deny-list. How routing rules reach the agent. (Note: steering is read on-demand per CLAUDE.md startup checklist, not auto-injected.)
  5. UserPromptSubmit hook — auto-loads project context when Justin mentions a project name. See memory/general/reference_auto_context.md.
  6. Auto-memory + auto-dream (Phase 4.4) — Stop-hook captures facts at session end; nightly auto-dream consolidates. Both write to LESSONS.md for audit. See memory/general/reference_auto_memory.md.

Files to read first

  • forge/CLAUDE.md
  • forge/FORGE-DOCTRINE.md (sections 9, 10, 11, 12 most relevant)
  • forge/system-map/steering.md
  • forge/scripts/forge_hook_session_start_since_last.sh
  • forge/MEMORY.md (just look at structure, don't reread topic files)
  • forge/memory/general/reference_boot_briefing.md
  • forge/memory/general/reference_auto_memory.md
  • forge/memory/general/reference_auto_context.md
  • forge/.claude/settings.json (hooks block — see which hooks are actually wired)

Style

  • Phone-readable: short paragraphs, scannable headers, ordered list when ordering matters.
  • No em dashes (doctrine).
  • Concrete file paths + script names so Justin can click through on mkdocs.
  • Where the boot sequence has an actual ordering, number the steps 1→N.
  • End with a 5-bullet "if you remember nothing else" recap.

Stop conditions

  • Write the file.
  • One-line acknowledgement that it's written. No summary in chat; the file IS the deliverable.