Session Context Protocol

Instructions

Prevent vibe-coding pitfall 2 (context drift across sessions) and pitfall 4 (no ownership of generated code) by standardizing the session lifecycle.

Session Opener (start of every build session)

Step 1 — Context handshake. Before writing any code, the AI must demonstrate it understands the project:

I'm starting a session on [project name]. Let me verify my understanding:
- Stack: [list from CLAUDE.md]
- Current sprint scope: [from requirements doc or scope lock]
- Conventions: [key patterns from CLAUDE.md / coding-playbook.md]
- Last session left off at: [from session log or git log]
- Known constraints: [from CLAUDE.md]

If any item is wrong or outdated, correct it before proceeding.

Step 2 — Requirement link. Every build task must reference a requirement:

This session addresses: [REQ-ID or User Story ID]
Acceptance criteria: [paste from requirements doc]

If no requirement exists for the requested work, invoke the scope-control skill to classify the request before building.

Step 3 — File awareness. Read the relevant files before editing:

Files I'll be working with this session:
- [file1] — [purpose]
- [file2] — [purpose]
I've read all of them and understand the current state.

During the Session

Commit protocol:

• Atomic commits: one logical change per commit
• Descriptive messages: “Add [what] for [why]” not “update files”
• Never commit code you cannot explain in plain English
• Run linting after every substantive edit

Context preservation:

• If the session is long (20+ tool calls), produce a mid-session summary
• If architecture decisions are made, document them inline or in a DECISIONS.md entry
• If scope changes are requested, invoke the scope-control skill

Session Closer (end of every significant session)

Step 1 — Session summary. Produce a structured log:

## Session Summary — [Date]
**Project**: [name]
**Duration**: [approximate]
**Requirement(s)**: [REQ-IDs addressed]

### Completed
- [What was built/changed, with file paths]

### Decisions Made
- [Any architectural or design decisions, with rationale]

### Known Issues
- [Anything left incomplete, broken, or needing follow-up]

### Next Steps
- [What the next session should start with]

### CLAUDE.md Updates Needed
- [Any project context that changed and should be reflected in CLAUDE.md]

Step 2 — CLAUDE.md update. If the session changed the stack, conventions, data model, or project structure, update CLAUDE.md to reflect the current state. Never leave CLAUDE.md describing the old state.

Step 3 — Git status. Verify:

• All changes committed (no uncommitted work left)
• Commit messages are descriptive
• No secrets or credentials in the commit

Context Drift Detection

Signs that context has drifted (flag immediately):

• AI generates code using a naming convention different from the existing codebase
• AI creates a new utility function that duplicates an existing one
• AI references a file structure that doesn’t match reality
• AI suggests installing a dependency the project already has
• AI implements a pattern inconsistent with coding-playbook.md

When drift is detected: stop, re-read the relevant files, re-establish context, then continue.

Antigravity session knowledge sync:

When sessions involve Antigravity test/debug work, the session closer must include the Antigravity knowledge sync protocol:

1. Scan Walkthrough artifacts for [CONTEXT-UPDATE] flags (search all artifacts from the session)
2. Classify each flag by tier: GLOBAL, PROJECT, PRODUCT, CLIENT, or MANUAL
3. Switch to Claude Code to apply approved updates using the tier-specific prompts in operations/claude-scripts/context-update-template.md
4. Commit knowledge updates separately from code fixes: docs: sync knowledge files from Antigravity session YYYY-MM-DD

The session summary should include an additional section for Antigravity sessions:

### Antigravity Findings
- [CONTEXT-UPDATE] flags surfaced: [count]
- Flags applied to CLAUDE.md: [list tiers updated]
- [TEST-FAILURE] flags resolved: [count]
- Unresolved findings: [list for next session]

See operations/documentation/antigravity-runbook.md Phase 3 (Steps 8-11) for the complete knowledge sync protocol.

Outputs: Context handshake verification, requirement link, session summary, CLAUDE.md update diff, context drift flags.