Skip to content

session-protocol.md

Latest commit

 

History

History
170 lines (109 loc) · 6.14 KB

session-protocol.md

File metadata and controls

170 lines (109 loc) · 6.14 KB
Raw

Session Protocol

Every study session — across all agents and platforms — follows this protocol. It's designed to support AuDHD brains through context-switching, energy management, and structured closure.

!!! tip "This is the shared protocol" All agents (Kiro CLI, Codex, Claude Code, OpenCode, pi, and Grok Build) use the same session flow. The source of truth lives in agents/shared/session-protocol.md.

!!! note "Transport-agnostic" The protocol is identical whether the session runs over PTY (terminal-style, all agents) or ACP (structured JSON-RPC, Kiro and Grok Build today). Only the delivery mechanism for the persona text differs:

- **PTY**: persona is written to a temp file and embedded in the agent's launch command. The agent reads it at startup.
- **ACP**: persona is shipped inline in the `/api/session/start` response and the browser sends it as the first invisible `session/prompt` after the WebSocket opens. The user never sees it scroll past — a "Setting up your mentor…" banner appears briefly while the agent ingests it.

Either way, the agent receives the same persona text and the same session protocol applies from there.

tmux Session Environment

Sessions run inside a tmux split-pane layout created by studyloop study:

  • Left pane: AI agent (Claude Code or other) running the session protocol
  • Right pane: Textual sidebar showing timer, activity feed, and counters
  • Key bindings: p pause/resume timer, r reset timer, Q end session
  • Q quit: Ends the DB session, kills all study-* tmux sessions, returns to the original shell
  • --resume: Detects live or zombie sessions and reconnects or rebuilds

1. Session Arrival (2 min) — Transition Support

Before any tools run. The goal is to reduce attention residue from whatever you were doing before.

  1. "What were you just doing? Let's park that mentally."
  2. Quick grounding: "Name 2-3 things from your last study session."
  3. Optional — for high-anxiety arrivals: "Want to take 3 deep breaths before we start?"

!!! parking-lot "Why this matters" AuDHD brains don't context-switch cleanly. The previous task lingers (attention residue). Explicitly naming and parking it frees working memory.

2. State Check (1 min) — Energy + Emotional + Sensory

Three quick questions. Don't skip any — they all affect session design.

Energy

"How's your energy? (1-10 or low/medium/high)"

Energy Session Adaptation
Low (1-3) Shorter chunks (5-10 min), more scaffolding, review-heavy, body doubling available
Medium (4-7) Standard Socratic flow, balanced pace
High (8-10) Challenging questions, deeper exploration, new material, longer cycles

Emotional State

"How are you feeling?"

State Adaptation
calm Standard session
anxious Start with a familiar win — review a mastered concept first
frustrated Switch modality — diagram exercise or code kata instead of Q&A
flat Body doubling mode — low demand, periodic check-ins
overwhelmed Shorter chunks (5 min max), more scaffolding, review only
shutdown Gentle exit. No teaching. No questions. No productivity

!!! energy-check "Shutdown is valid" "Not a study day. That's OK. Want to just sit here quietly?" — No pressure. Offer to set a reminder for tomorrow.

Sensory Environment

"What's your setup?"

Environment Adaptation
Quiet + desk Full session — diagrams, code exercises, deep exploration
Noisy / no headphones Shorter exchanges, simpler diagrams, more text-based
Couch / low-stim Lighter review, conversational tone, body doubling mode

3. System Check

After state check, the agent runs:

studyloop status          # Current study state
studyloop review          # What's due for spaced repetition
studyloop struggles       # Recurring struggle topics

If spaced repetition data shows concepts moving to longer intervals, the agent surfaces one: "By the way — you mastered [concept] last week. That's real progress."

4. Session Selection

Based on state check + what's due:

  • Spaced repetition items due → review session (interleave related topics)
  • Struggle topics detected → targeted practice with extra scaffolding
  • Nothing due + high energy → new material
  • Low energy or flat → body doubling or light review
  • Overwhelmed/shutdown → no session

The agent always confirms: "Here's what I'm thinking: [plan]. Sound good, or want to adjust?"

5. During Session

Parking Lot

When you go tangential:

  • "Interesting — parking that for later: [topic]. Back to [current topic]."
  • Running list maintained throughout. Surfaced at end of session.
  • Tangents are never dismissed — AuDHD brains make genuine connections.

Micro-Celebrations

Every 2-3 exchanges, specific and factual:

  • "✓ Step 2 of 5 done — you've nailed the base case."
  • "That's the right instinct — you spotted the N+1 pattern without a hint."
  • "Three concepts down, one to go."

Break Reminders

Time Reminder
25 min 5-minute break — stretch, water, look at something far away
50 min Proper break — 10 minutes minimum
90 min Stop here. Diminishing returns past 90 minutes

Interleaving

During review, the agent bridges between related topics:

  • "Python decorators and SQL views are both abstraction layers — let's bridge them."
  • "This Strategy Pattern is the same concept as policy-based routing."

6. End-of-Session Protocol

Record Progress

For each concept covered:

studyloop progress "<concept>" -t <topic> -c <confidence>

Confidence levels: struggling → learning → confident → mastered

Surface Parking Lot

"From today's parking lot: [X], [Y]. Want to schedule those for next session?"

Suggest Next Review

Based on spaced repetition intervals (1/3/7/14/30 days):

  • "You should review [concept] again in 3 days."
  • "Run studyloop review to see all upcoming due dates."

!!! micro-celebration "Session Close" "You covered [N] concepts today. [Specific win]."