.claude/
├── context/              # Current session state
│   ├── current-task.md   # Active task description
│   ├── decisions.md      # Decisions made this session
│   └── blockers.md       # Current blockers
├── memory/               # Persistent learnings (survives sessions)
│   ├── patterns.md       # Codebase patterns discovered
│   ├── gotchas.md        # Things to remember
│   └── preferences.md    # User preferences
├── scratch/              # Temporary working files
│   └── tool-outputs/     # Large command outputs
├── plans/                # Implementation plans
│   └── *.md              # Individual plan files
└── skills/               # Skill definitions

# Instead of showing full output in chat
npm run build 2>&1 | tee .claude/scratch/build-output.txt

# Then reference specific parts
grep -n "error" .claude/scratch/build-output.txt

1. Run command, pipe to scratch file
2. Return summary to chat: "Build completed with 3 errors, see .claude/scratch/build-output.txt"
3. When debugging, grep specific errors from file
4. Delete scratch file when done

# Plan: [Feature/Task Name]

## Metadata
- **Status**: PLANNING | IN_PROGRESS | BLOCKED | COMPLETE
- **Created**: YYYY-MM-DD
- **Updated**: YYYY-MM-DD HH:MM
- **Priority**: HIGH | MEDIUM | LOW

## Objective
[Clear statement of what we're trying to achieve]

## Context
[Background information and why this matters]

## Implementation Steps
- [ ] Step 1: Description
  - Files: `path/to/file.ts`
  - Notes: Implementation details
- [ ] Step 2: Description
- [ ] Step 3: Description

## Files to Modify
| File | Purpose | Status |
|------|---------|--------|
| `app/api/route.ts` | Main endpoint | Pending |
| `lib/service.ts` | Business logic | Done |

## Decisions Made
1. **[Decision]**: [Rationale]
2. **[Decision]**: [Rationale]

## Blockers
- [ ] Blocker 1: Description
- [ ] Blocker 2: Description

## Notes
[Any additional context]

# Create new plan
echo "# Plan: Feature X" > .claude/plans/feature-x.md

# Resume work - read plan first
cat .claude/plans/feature-x.md

# Update progress
# Edit the plan file as steps complete

# Current Task

## What I'm Working On
[Brief description of current focus]

## Recent Actions
- [Action 1] - [Result]
- [Action 2] - [Result]

## Next Steps
1. [Next immediate action]
2. [Following action]

## Files Currently Open/Relevant
- `path/to/file1.ts` - [Why relevant]
- `path/to/file2.ts` - [Why relevant]

## Session Notes
[Any important context for this session]

# Session Decisions

## [Date]

### Decision: [Title]
- **Context**: [Why this came up]
- **Options Considered**:
  - Option A: [Description]
  - Option B: [Description]
- **Chosen**: Option A
- **Rationale**: [Why this was chosen]
- **Impact**: [What this affects]

# Codebase Patterns

## Authentication
- Always use `createClient` from `@/lib/supabase/server` for API routes
- Check BOTH Authorization header AND cookies (see commit ac642e8)

## API Routes
- Next.js 15 requires async params: `context: { params: Promise<{ id: string }> }`
- Always await params before use

## Database
- Use service role client for admin operations
- RLS policies apply to anon key only

## Testing
- Run `npm run type-check:memory` to avoid heap errors
- Use `npm run dev:memory` for development server

# Gotchas & Lessons Learned

## [Category]

### [Issue Title]
- **Symptom**: [What you see]
- **Cause**: [Why it happens]
- **Fix**: [How to resolve]
- **Prevention**: [How to avoid]
- **Reference**: [Commit/PR/Doc]

# User Preferences

## Code Style
- Prefer explicit types over inference
- Use early returns for guard clauses
- Keep functions under 50 lines

## Workflow
- Always run type-check before committing
- Use conventional commits (feat:, fix:, etc.)
- Test in staging before production

## Communication
- Be concise, skip unnecessary explanations
- Show code diffs for changes
- Summarize at end of complex tasks

.claude/
└── agents/
    ├── research/         # Research agent outputs
    │   └── findings.md
    ├── implementation/   # Implementation agent state
    │   └── progress.md
    └── review/           # Review agent feedback
        └── issues.md

# Agent Handoff: [From Agent] → [To Agent]

## Completed Work
[What was accomplished]

## Key Findings
1. [Finding 1]
2. [Finding 2]

## Files Created/Modified
- `path/to/file.ts` - [What was done]

## Recommendations for Next Agent
1. [Recommendation]
2. [Recommendation]

## Open Questions
- [Question needing resolution]

# Append new learning to appropriate file
echo "
### [New Learning Title]
- **Context**: [When this applies]
- **Details**: [The learning]
- **Added**: $(date +%Y-%m-%d)
" >> .claude/memory/patterns.md

# 1. Check for existing context
cat .claude/context/current-task.md 2>/dev/null || echo "No active task"

# 2. Check active plans
ls -la .claude/plans/*.md 2>/dev/null || echo "No active plans"

# 3. Review memory
cat .claude/memory/gotchas.md 2>/dev/null | head -50

# Before ending session, update current-task.md with:
# - What was accomplished
# - What's next
# - Any blockers

# 1. Read the plan
cat .claude/plans/[plan-name].md

# 2. Read current context
cat .claude/context/current-task.md

# 3. Check recent decisions
cat .claude/context/decisions.md | tail -30

# Clean old scratch files (older than 7 days)
find .claude/scratch -type f -mtime +7 -delete

# Archive completed plans
mv .claude/plans/completed-*.md .claude/plans/archive/

# Prune old context
# Keep only last 5 days of context files