Session Startup Checklist

Run this checklist at the start of every session. No exceptions.

Step 1: Check Setup

Read CLAUDE.md and check if the Setup Checklist has uncompleted items. If so, remind the user.

Step 2: Load Context Documents

Read these files in order:

1. docs/openspec-workflow-reference.md — canonical naming + workflow reference (if present; graceful skip with "workflow ref: not found" notice if missing)
2. docs/project-brief.md — living summary: capability map, service registry, skill inventory, ADR index, active work pointer, known debt (if present; graceful skip with "project-brief: not found" notice if missing)
3. docs/session-startup-checklist.md
4. docs/project-naming-standards.md
5. docs/current-story.md
6. docs/next-prompt.md (the hub/index)

Then check for branch-specific next-prompt files:

• Get current branch: !git branch --show-current
• Detect identifier format via shared utility: bash .claude/skills/_shared/milestone-format.sh "<id-from-branch>" outputs format=M|kebab and normalizes the id
  • Branch feature/M1.2.3-description → identifier M1.2.3, format M
  • Branch feature/architecture-compliance-sweep → identifier architecture-compliance-sweep, format kebab
• If docs/next-prompt-[identifier].md exists, read it too
• If on main, check docs/next-prompt.md for active milestone pointers and read the relevant files

Step 3: Check Git State

Current branch and status:

• Branch: !git branch --show-current
• Status: !git status --short
• Recent commits: !git log --oneline -5

Step 4: Set Status Line

Write the active identifier and step to a branch-keyed status file so the status line displays it for the entire session. This prevents multiple sessions from overwriting each other.

Parse the active identifier and current step from current-story.md. Determine the branch slug by replacing / with - in the branch name. Detect format via .claude/skills/_shared/milestone-format.sh.

Format by identifier type:

• Legacy M-format: [M#.#] feature-name .# step-name
  • [M16.9] ml-model-retraining .3 full-retrain
  • [M7.7] app-store-submission
• OpenSpec change-id format: [<change-id>] <optional-phase>
  • [architecture-compliance-sweep] phase 1
  • [expand-claude-context-infrastructure]

Use a single line. The step/phase is optional — include it when a sub-milestone or phase is active.

# Identifier detected from branch via milestone-format.sh (e.g., M7.7 or architecture-compliance-sweep)
bash .claude/skills/_shared/status-line.sh write "[<identifier>] <phase-or-feature-name>"

The helper derives the branch-slug automatically from git branch --show-current and writes to ~/.claude/forager-status-<slug>.txt. All workflow skills that represent a focus transition use this same helper — see CLAUDE.md § Status Line (Focus Sync).

Step 5: Check Active OpenSpec Changes

Check if there are any active (non-archived) changes:

ls openspec/changes/ 2>/dev/null | grep -v archive

If active changes exist, read their tasks.md to understand what's in progress.

Step 6: Report

After reading all documents, provide a concise status report:

1. Current milestone: What M#.#.# is active, what status
2. Branch check: Are we on the correct feature branch? Flag if on main
3. Uncommitted work: Any staged/unstaged changes?
4. Setup status: Any unconfigured items in CLAUDE.md Setup Checklist?
5. Next action: What should we work on based on current-story.md and the branch-specific next-prompt

Step 7: Red Flag Check

Verify:

• Not on main (should be on feature branch for any code work)
• Branch identifier matches a valid format (M#.#.# legacy OR kebab change-id) — bash .claude/skills/_shared/milestone-format.sh exits non-zero on malformed names
• Current work is documented in current-story.md
• OpenSpec change exists for active work (or next-prompt file as legacy fallback)
• No duplicate services being created

If any red flags are found, report them before proceeding.