Project Onboarding

Project Onboarding

Read the handoff. Don't re-explore what's already written down.

Three-Layer Loading

Loading order optimized for KV cache (stable content first, volatile last):

Layer 1: Meta-skill (rarely changes)

cat CLAUDE.md

Provides: how to work in this project, architecture, conventions.

Layer 2: Session State (from latest daily file)

# Find the most recent daily file
ls daily/​*.md 2>/​dev/​null | sort | tail -1
# Read first section (## Session Handoff)

Handoff is fresh if: git_commit in handoff matches current HEAD and date is recent (within 3 days).

If fresh: use handoff directly. Skip cortex/​skills exploration. If stale or missing: degrade to file exploration (see below). If stale + gap >7 days: git log --since="7 days ago" --oneline to reconstruct activity, then cortex probe to check current state. Don't rely on stale Next Steps.

Layer 3: Ground Truth Verification (always required)

git status
git log --oneline -5

Compare against handoff's 0. Verify Current State section. If they diverge, handoff is stale — flag it and rely on real-time git output.

Degraded Exploration (no usable handoff)

Only when Layer 2 fails. Read in this order:

cat skill-deck.toml               # What skills are active
cat cortex/​INDEX.md               # Project governance state
git log --oneline -10             # Recent changes
ls -lt cortex/​adr/​02-accepted/ | head -10   # Recent decisions
ls -lt cortex/​wiki/​02-research/ | head -10  # Recent research
ls cortex/​epics/​01-active/        # Active epics
ls cortex/​tasks/​01-backlog/       # Pending work
ls cortex/​tasks/​02-in-progress/   # Active work

If the project has cortex, the ls -lt on adr/, wiki/, epics/, tasks/ directories tells you what happened recently without reading every file — timestamps reveal the most recent decisions, research, and active work at a glance.

Cortex ID = timestamp: ADR-/​TASK-/​EPIC- prefixes use yyyyMMddHHmmssSSS. This enables date-range grep reconstruction (e.g., ls cortex/​adr/​02-accepted/ | grep '^ADR-2026051' finds all May 2026 decisions). Use this when a weekly is missing or when verifying claims across a date range.

Freshness Decision Table

Output Format

After loading, summarize to user:

📋 Project: <name> (<tech stack>)
📌 Version: <tag> (git: <hash>)
📄 Source: daily/<date>.md | degraded exploration
⚠️ Pitfalls: <top 1-2 from handoff>
🎯 Current: <active task>
💡 Next: <prioritized next step>
✅ Verification: git state matches handoff | ⚠️ diverged

Checklist

• Layer 1: Read CLAUDE.md
• Layer 2: Find latest daily/, read handoff section
• Assess freshness (git_commit match, date recency)
• Layer 3: Verify with git status + git log
• If handoff fresh → use directly
• If handoff stale/​missing → degraded exploration
• Output summary to user

Gotchas

Don't re-explore when handoff is fresh. The whole point of the scribe→onboarding pipeline is to avoid burning tokens on redundant ls and cat. If the handoff exists and git state matches, trust it.

Handoff date ≠ freshness. A 2-day-old handoff with matching git_commit is fresher than a same-day handoff whose git_commit doesn't match HEAD (someone committed outside the agent session). Multiple handoff sections. If the daily file has multiple ## Session Handoff sections (multiple sessions same day), read the first one — scribe prepends new handoffs to the top of the file.

Supporting References