Sessions

Note: This session structure is a TEMPLATE. Customize file names, add fields, or use a different organization that works for you.

Introduction

Sessions are organized folders that contain all artifacts for a feature's development lifecycle. Each session provides complete history, progress tracking, and agent coordination in one location.

Sessions replace scattered documentation across project management tools, chat logs, and temporary files with a single source of truth for each feature.

What is a Session?

A session is a dedicated folder for one feature containing four key files:

.claude/sessions/user-profile-edit/
├── clickup_task_user_profile_edit.md  # Business requirements
├── plan_user_profile_edit.md          # Technical implementation plan
├── progress_user_profile_edit.md      # Development progress tracking
└── context_user_profile_edit.md       # Agent coordination log

Purpose:

• Organization - All feature artifacts in one place
• History - Complete development timeline
• Coordination - Clear handoffs between agents
• Visibility - Instant progress overview
• Git-Trackable - Can be committed for permanent record

Session Directory Structure

.claude/sessions/
├── README.md                      # Session system documentation
├── TEMPLATE_clickup_task.md       # Template for task metadata
├── TEMPLATE_plan.md               # Template for technical plans
├── TEMPLATE_progress.md           # Template for progress tracking
├── TEMPLATE_context.md            # Template for coordination
│
├── user-profile-edit/             # Example session
│   ├── clickup_task_user_profile_edit.md
│   ├── plan_user_profile_edit.md
│   ├── progress_user_profile_edit.md
│   └── context_user_profile_edit.md
│
├── api-rate-limiting/             # Another session
│   ├── clickup_task_api_rate_limiting.md
│   ├── plan_api_rate_limiting.md
│   ├── progress_api_rate_limiting.md
│   └── context_api_rate_limiting.md
│
└── email-notifications/           # Another session
    └── ...

The Four Session Files

1. clickup_task_{feature}.md

Created by: Product Manager
Purpose: Business context and acceptance criteria

Contains:

• Task ID and URL (if using ClickUp)
• Business context (why this feature matters)
• Acceptance criteria (numbered list)
• Success metrics
• User stories
• Links to related tasks

Example:

# Task: User Profile Edit

**ClickUp Task ID:** 86abc123  
**URL:** https://app.clickup.com/t/86abc123

## Business Context

### Why
Users need to update their personal information without contacting support.

### Impact
- Reduces support tickets by ~30%
- Improves user autonomy
- Increases user satisfaction

### User Story
As a registered user, I want to edit my profile information so that I can keep my account details up to date.

## Acceptance Criteria

1. **Navigation**: User can access edit page from dashboard
2. **Fields**: User can update name, email, and profile photo
3. **Email Verification**: Email changes require verification before saving
4. **Validation**: Form shows clear validation errors
5. **Success**: Changes save successfully with confirmation message

## Success Metrics

- 0 validation bypass vulnerabilities
- < 2 seconds form submission time
- 100% acceptance criteria met

## Feature Branch

`feature/user-profile-edit`

When to Update:

• Initially by PM
• If requirements change (scope changes)
• When acceptance criteria are clarified

---

2. plan_{feature}.md

Created by: Architecture Supervisor
Purpose: Complete technical implementation plan

Contains:

• Technical summary and approach
• Phase 1: Backend (database + API)
• Phase 2: Frontend (UI components)
• Phase 3: Integration (E2E testing)
• Phase 4: QA Plan (test cases)
• Technical notes (patterns, security, performance)

Example:

# Technical Plan: User Profile Edit

## Technical Summary

**Approach:** RESTful API with React form components  
**Database:** Add profile fields to users table  
**Frontend:** shadcn/ui form with Zod validation  
**Security:** Rate limiting, email verification flow

## Phase 1: Backend (Database + API)

### 1.1 Database Migration
- [ ] Create `migrations/20250119_add_profile_fields.sql`
- [ ] Add columns: display_name, bio, avatar_url
- [ ] Run migration: `npm run db:migrate`
- [ ] Verify: `npm run db:verify`

### 1.2 API Endpoint
- [ ] Create `app/api/profile/route.ts`
- [ ] Implement PUT /api/profile endpoint
- [ ] Add Zod validation schema
- [ ] Implement rate limiting (5 updates/hour)
- [ ] Add dual authentication (session + API key)

### 1.3 Email Verification
- [ ] Create email_verifications table
- [ ] Implement verification token generation
- [ ] Add verification email sending
- [ ] Create verification endpoint

### 1.4 Testing
- [ ] Write API tests for valid updates
- [ ] Test invalid data handling
- [ ] Test rate limiting
- [ ] Test email verification flow

## Phase 2: Frontend (UI Components)

### 2.1 Form Component
- [ ] Create `components/profile/ProfileEditForm.tsx`
- [ ] Use shadcn/ui Form component
- [ ] Add Zod validation
- [ ] Implement image upload
- [ ] Add loading states

### 2.2 Internationalization
- [ ] Add translations: `en.json`, `es.json`
- [ ] Keys: profile.edit.*, profile.validation.*
- [ ] No hardcoded strings

### 2.3 Testing
- [ ] Write component tests
- [ ] Test validation states
- [ ] Test loading states
- [ ] Test error handling

## Phase 3: Integration

- [ ] E2E test: Complete profile update flow
- [ ] E2E test: Email verification flow
- [ ] Performance: < 2s form submission
- [ ] Security: No XSS vulnerabilities

## Phase 4: QA Plan

### Functional Tests
1. **Valid Update**: Fill form with valid data → Submit → Success
2. **Invalid Email**: Enter invalid email → Validation error shown
3. **Email Verification**: Change email → Verify link sent → Verify → Updated
4. **Rate Limiting**: Update 6 times quickly → Rate limit triggered
5. **Image Upload**: Upload 3MB image → Success, Upload 11MB → Error

### Visual Tests
1. **Desktop (1920x1080)**: Form layout, spacing, alignment
2. **Mobile (375x667)**: Responsive, touch targets, scrolling
3. **Tablet (768x1024)**: Layout transitions

### Acceptance Criteria Validation
- ✅ CA1: Navigation from dashboard works
- ✅ CA2: All fields editable
- ✅ CA3: Email verification required
- ✅ CA4: Validation errors clear
- ✅ CA5: Success confirmation shown

## Technical Notes

### Registry Pattern
- Form registered in entity-registry
- Validation in shared schema

### Performance
- Optimistic updates
- Image compression before upload
- Debounced validation

### Security
- Rate limiting via middleware
- Email verification tokens expire in 24h
- XSS prevention via proper escaping

When to Update:

• Initially by Architect
• If technical approach changes
• When new phases are added

---

3. progress_{feature}.md

Created by: Architecture Supervisor (template)
Updated by: All developers, QA tester
Purpose: Local progress tracking (replaces ClickUp checklists)

Contains:

• Checkboxes for all implementation steps
• Timeline tracking
• Blocker documentation
• Phase completion status

Example:

# Progress Tracking: User Profile Edit

**Feature Branch:** `feature/user-profile-edit`  
**Started:** 2025-01-19  
**Target:** 2025-01-22

## Phase 1: Backend ✅ COMPLETED

- [x] Create migrations/20250119_add_profile_fields.sql
- [x] Execute migration with npm run db:migrate
- [x] Verify table with npm run db:verify
- [x] Create app/api/profile/route.ts
- [x] Implement PUT /api/profile endpoint
- [x] Add Zod validation schema
- [x] Implement rate limiting (5 updates/hour)
- [x] Add dual authentication
- [x] Create email_verifications table
- [x] Implement verification flow
- [x] Write 12 API tests (100% coverage)

**Completed:** 2025-01-19 14:00  
**Completed by:** backend-developer

## Phase 2: Frontend ✅ COMPLETED

- [x] Create components/profile/ProfileEditForm.tsx
- [x] Use shadcn/ui Form component
- [x] Add Zod validation (client-side)
- [x] Implement image upload with compression
- [x] Add loading states
- [x] Add error handling
- [x] Add translations (en.json, es.json)
- [x] Zero hardcoded strings
- [x] Write 8 component tests

**Completed:** 2025-01-19 16:00  
**Completed by:** frontend-developer

## Phase 3: Integration ✅ COMPLETED

- [x] E2E test: Complete update flow
- [x] E2E test: Email verification flow
- [x] Performance validation: 1.2s submission (✅ < 2s)
- [x] Security review: No vulnerabilities found
- [x] Build validation: pnpm build passes

**Completed:** 2025-01-19 17:00

## Phase 4: QA ✅ COMPLETED

### Functional Tests
- [x] Valid profile update
- [x] Invalid email format
- [x] Email verification flow
- [x] Rate limiting enforcement
- [x] Image upload validation

### Visual Tests
- [x] Desktop (1920x1080) - Perfect
- [x] Mobile (375x667) - Perfect
- [x] Tablet (768x1024) - Perfect

### Acceptance Criteria
- [x] CA1: Navigation works
- [x] CA2: All fields editable
- [x] CA3: Email verification required
- [x] CA4: Validation errors clear
- [x] CA5: Success confirmation shown

**Completed:** 2025-01-19 18:00  
**Tested by:** qa-tester  
**Result:** All tests passed ✅

## Phase 5: Code Review ✅ COMPLETED

- [x] Security review
- [x] Performance review
- [x] Code quality review
- [x] Best practices review
- [x] Pattern compliance review

**Completed:** 2025-01-19 19:00  
**Reviewed by:** code-reviewer  
**Result:** Approved for merge ✅

## Timeline

- 2025-01-19 10:00: Planning complete (architect)
- 2025-01-19 14:00: Backend complete (backend-developer)
- 2025-01-19 16:00: Frontend complete (frontend-developer)
- 2025-01-19 17:00: Integration complete
- 2025-01-19 18:00: QA complete (qa-tester) - All passed
- 2025-01-19 19:00: Code review complete (code-reviewer) - Approved

**Total time:** 9 hours

## Blockers

None

## Notes

- Image compression reduced upload size by 60%
- Rate limiting prevented abuse in testing
- Email verification flow works smoothly

When to Update:

• Developers mark [x] as they complete items
• QA marks test results
• Code reviewer marks review steps
• Document any blockers immediately

Key Benefits:

• No ClickUp API calls needed
• Instant visibility of progress
• Complete history in file
• Git-trackable changes

---

4. context_{feature}.md

Created by: Product Manager (initial)
Updated by: ALL agents
Purpose: Agent-to-agent coordination and handoffs

Contains:

• Timestamped entries from each agent
• Work summaries
• Decisions made
• Status indicators
• Next step guidance

Example:

# Context Log: User Profile Edit

## [2025-01-19 09:00] Product Manager

**Status:** ✅ Completed

**Work Summary:**
- Created ClickUp task (ID: 86abc123)
- Defined 5 acceptance criteria
- Documented business context
- Initialized session folder

**Decisions:**
- Target: All authenticated users
- Priority: High (reduces support load)
- Timeline: 3 days

**Next Step:** Architecture supervisor should create technical plan

---

## [2025-01-19 10:00] Architecture Supervisor

**Status:** ✅ Completed

**Work Summary:**
- Created comprehensive technical plan
- Defined 4 implementation phases
- Created progress template
- Documented security requirements

**Technical Decisions:**
- Using Zod for validation (client + server)
- Rate limiting: 5 updates/hour
- Email verification for email changes
- Image upload with compression

**Next Step:** Backend developer can begin Phase 1

---

## [2025-01-19 14:00] Backend Developer

**Status:** ✅ Completed

**Work Summary:**
- Created database migration
- Implemented PUT /api/profile endpoint
- Added Zod validation schema
- Implemented rate limiting middleware
- Created email verification flow
- Wrote 12 API tests (100% coverage)

**Decisions:**
- Using separate email_verifications table
- Verification tokens expire in 24 hours
- Rate limiting via middleware pattern

**Challenges:**
- Email verification required new table design
- Rate limiting needed redis integration

**Next Step:** Frontend developer can implement UI

---

## [2025-01-19 16:00] Frontend Developer

**Status:** ✅ Completed

**Work Summary:**
- Created ProfileEditForm component
- Implemented Zod validation (client-side)
- Added image upload with compression
- Added loading and error states
- Completed i18n (en, es)
- Wrote 8 component tests

**Decisions:**
- Using shadcn/ui Form component
- Image compression before upload (60% reduction)
- Optimistic updates for better UX

**Next Step:** Integration testing can begin

---

## [2025-01-19 17:00] Integration Phase

**Status:** ✅ Completed

**Work Summary:**
- E2E tests for complete flow
- Performance validation
- Security review
- Build validation

**Results:**
- Performance: 1.2s (target: < 2s) ✅
- Security: No vulnerabilities found ✅
- Build: pnpm build passes ✅

**Next Step:** QA tester can begin testing

---

## [2025-01-19 18:00] QA Tester

**Status:** ✅ Completed

**Test Results:**
- Functional: 5/5 passed ✅
- Visual: All viewports perfect ✅
- Acceptance Criteria: All met ✅

**Devices Tested:**
- Desktop: Chrome, Firefox, Safari
- Mobile: iPhone 13, Samsung Galaxy
- Tablet: iPad Air

**Issues Found:** None

**Next Step:** Code reviewer can perform final review

---

## [2025-01-19 19:00] Code Reviewer

**Status:** ✅ Completed

**Review Summary:**
- Security: Approved ✅
- Performance: Approved ✅
- Code Quality: Approved ✅
- Pattern Compliance: Approved ✅

**Highlights:**
- Excellent test coverage
- Clean code structure
- Proper error handling
- Good performance

**Issues:** None

**Approval:** ✅ Ready for merge

**Next Step:** Human can merge feature branch to main

When to Update:

• Each agent adds entry when starting work
• Each agent adds entry when completing work
• Document all significant decisions
• Note any challenges or blockers
• Provide clear next step guidance

Key Benefits:

• Complete audit trail
• Clear handoffs between agents
• Decision documentation
• Problem tracking

---

Creating a New Session

Method 1: Using /init-task Command

/init-task Add user profile edit functionality

This automatically:

1. Launches PM to create task and initialize session
2. Launches Architect to create technical plan

Method 2: Manual Creation

Step 1: Create Session Folder

mkdir .claude/sessions/user-profile-edit

Step 2: Copy Templates

cd .claude/sessions

# Copy all templates
cp TEMPLATE_clickup_task.md user-profile-edit/clickup_task_user_profile_edit.md
cp TEMPLATE_plan.md user-profile-edit/plan_user_profile_edit.md
cp TEMPLATE_progress.md user-profile-edit/progress_user_profile_edit.md
cp TEMPLATE_context.md user-profile-edit/context_user_profile_edit.md

Step 3: Fill In Information

Edit each file with feature-specific details.

---

Session Naming Conventions

Format: kebab-case, descriptive

Good Examples:

user-profile-edit
api-rate-limiting
email-notifications
dark-mode-toggle
payment-integration

Bad Examples:

feature1              (not descriptive)
UserProfileEdit       (wrong case)
user_profile_edit     (snake_case, not kebab-case)
edit-profile          (not specific enough)

Guidelines:

• Use kebab-case (lowercase with hyphens)
• Be descriptive and specific
• Match feature branch name: feature/[session-name]
• Keep reasonably short (2-4 words)

---

Benefits of Session-Based Workflow

vs ClickUp Checklists

Aspect	ClickUp Checklists	Session Files
Speed	API calls (~200ms)	Local file (<5ms)
Offline	Requires internet	Works offline
History	Limited	Complete git history
Detail	Limited space	Unlimited detail
Search	ClickUp search only	grep, IDE search

vs _tmp/ Folder

Aspect	_tmp/ Folder	Sessions
Organization	Flat by task ID	Organized by feature
Discovery	Search by ID	Browse by name
Context	Scattered	Centralized
Cleanup	Manual	Structured

vs No Organization

Aspect	No Organization	Sessions
Progress	In head	Visible
Handoffs	Verbal/chat	Documented
History	Lost	Preserved
Coordination	Ad-hoc	Structured

---

Session Lifecycle

1. Created (PM)
   ├─> clickup_task_{feature}.md created
   └─> context_{feature}.md initialized

2. Planned (Architect)
   ├─> plan_{feature}.md created
   └─> progress_{feature}.md template created

3. Development (Developers)
   └─> progress_{feature}.md updated

4. Testing (QA)
   └─> progress_{feature}.md tests marked

5. Review (Reviewer)
   └─> context_{feature}.md final entry

6. Complete (Human)
   └─> Session archived or kept for reference

---

Session Management

Active Sessions

Keep in .claude/sessions/ during development.

Completed Sessions

Option 1: Keep for Reference

# Sessions are valuable history
# Keep them for documentation and learning

Option 2: Archive

mkdir .claude/sessions/_archived
mv .claude/sessions/user-profile-edit .claude/sessions/_archived/

Option 3: Commit to Git

# Remove from .gitignore to track
git add .claude/sessions/user-profile-edit/
git commit -m "docs: Add session for user-profile-edit feature"

Cleaning Up

# Remove old sessions (optional)
rm -rf .claude/sessions/old-feature-name/

---

Best Practices

Session Organization

✅ DO:

• Create session at start of feature
• Update files as you progress
• Document all decisions
• Mark progress immediately
• Keep context entries concise

❌ DON'T:

• Skip session creation
• Update files after feature complete
• Leave gaps in context
• Forget to mark progress
• Write novels in context

File Maintenance

✅ DO:

• Use templates for consistency
• Follow naming conventions
• Keep files organized
• Update progress in real-time

❌ DON'T:

• Create files manually without templates
• Use inconsistent naming
• Mix multiple features in one session
• Batch-update progress at end

---

Troubleshooting

Problem: Can't find session for feature

Solution:

# List all sessions
ls .claude/sessions/

# Search by keyword
find .claude/sessions/ -name "*profile*"

Problem: Session files out of sync

Solution:

• Read all 4 files to understand current state
• Update out-of-date file
• Add context entry explaining sync issue

Problem: Multiple developers, same session

Solution:

• Both update same progress_{feature}.md
• Add separate context entries
• Use git to merge conflicts

---

Next Steps

• Commands - Use pre-built session workflows
• Development Workflow - See sessions in action
• Customization - Adapt session structure