Session Management — Checkpoint, Wrap-Up, Handoff

Core Principles

• Sessions are bounded work periods with clear start and end
• Checkpoints save progress for safe resumption
• Wrap-up summarizes what was done and what remains
• Handoff provides context for the next session/developer
• State is persisted in .dotnet-ai-kit/sessions/ directory

Key Patterns

Session Directory Structure

.dotnet-ai-kit/
  sessions/
    2025-03-16-order-creation/
      checkpoint.md        # Current progress snapshot
      decisions.md         # Design decisions made
      next-steps.md        # What to do next

Checkpoint Format

# Session Checkpoint

## Date: {date}
## Feature: {feature-name}
## Phase: {current-phase}

## Completed
- [x] Created OrderCreatedData event type
- [x] Implemented Order aggregate with Create factory method
- [x] Added CreateOrderHandler with CommitEventService
- [x] Added FluentValidation for CreateOrderCommand

## In Progress
- [ ] Query-side entity (Order) — started, needs Apply methods
- [ ] Event handler for OrderCreated — not started

## Blocked On
- None

## Files Changed
- src/Domain/Events/OrderCreatedData.cs (new)
- src/Domain/Aggregates/Order.cs (new)
- src/Application/Handlers/CreateOrderHandler.cs (new)
- src/Application/Validators/CreateOrderValidator.cs (new)

## Build Status
- Command project: compiles
- Query project: not started
- Tests: 3 passing, 0 failing

Wrap-Up Summary

# Session Wrap-Up

## Summary
Implemented the command side for order creation feature (#001).
All command-side code compiles and passes tests.

## Key Decisions
1. Used decimal for money (not float/double) — consistency with existing
2. OrderCreatedData includes Items list for denormalized projection
3. Validation uses resource strings from Phrases.resx

## What's Left
1. Query-side implementation (entity, event handler, query handler)
2. Gateway endpoint for order creation
3. Integration tests

## Recommended Next Steps
Start with `query-architect` agent to implement:
1. Order query entity with CTO constructor
2. OrderCreatedHandler
3. GetOrdersQuery handler with pagination

## Context for Next Session
- Event types are in shared-contracts repo (already merged)
- Command service is deployable independently
- Proto files for OrderCommands service are ready

Handoff Between Agents

# Agent Handoff: command-architect → query-architect

## Context
Order creation feature (#001) command side is complete.
Events are published to `{company}-order-commands` topic.

## What You Need to Know
- Event data type: `OrderCreatedData(CustomerName, Total, List<OrderItemData>)`
- Sequence starts at 1, increments by 1
- SessionId = AggregateId (Guid) for ordered processing

## Your Tasks
1. Create `Order` entity in Query.Domain with CTO constructor
2. Create `OrderCreatedHandler : IRequestHandler<Event<OrderCreatedData>, bool>`
3. Add EF Core configuration for Order entity
4. Add `GetOrdersQuery` with pagination
5. Register event type in EventDeserializer

Resuming a Session

# Find latest checkpoint
ls -t .dotnet-ai-kit/sessions/*/checkpoint.md | head -1

# Read checkpoint to understand state
cat .dotnet-ai-kit/sessions/{latest}/checkpoint.md

# Check git status since last checkpoint
git log --oneline --since="2025-03-16"

Anti-Patterns

Anti-Pattern	Correct Approach
No checkpoint before stopping	Always checkpoint before ending session
Vague wrap-up ("worked on stuff")	Specific files, decisions, and next steps
Missing agent context in handoff	Include event types, topic names, conventions
Stale checkpoints	Update checkpoint at each significant milestone

Detect Existing Patterns

# Find session directory
ls -la .dotnet-ai-kit/sessions/ 2>/dev/null

# Find latest session
ls -t .dotnet-ai-kit/sessions/ 2>/dev/null | head -3

Adding to Existing Project

1. Create session directory at the start of each work session
2. Checkpoint regularly — at minimum before stopping work
3. Write wrap-up with specific files changed and decisions made
4. Include handoff context when switching between agents or developers
5. Reference feature directory for the broader feature context