FoundryVTT/.claude/CONTEXT_PERSISTENCE.md

# Context Persistence Across Claude Code Sessions

> **Last Updated**: 2025-01-30
> **Status**: ✅ Fully Configured

---

## 🎯 Overview

This document explains how project instructions and tooling requirements persist across Claude Code conversation sessions.

---

## ✅ What Happens Automatically

### 1. CLAUDE.md Loading
- **Status**: ✅ Automatic (built into Claude Code)
- **When**: Start of every conversation
- **File**: [CLAUDE.md](../CLAUDE.md)
- **How**: Claude Code includes it in the system prompt automatically
- **Action Required**: None - works out of the box

### 2. SessionStart Hook
- **Status**: ✅ Configured and active
- **When**: Start of every conversation
- **File**: [.claude/hooks/session-start.sh](.claude/hooks/session-start.sh)
- **Configuration**: [.claude/settings.json:116-126](.claude/settings.json#L116-L126)
- **What it does**: Displays a prominent reminder about:
  - Available MCP servers
  - Available agents
  - Mandatory tooling usage requirements
  - Links to documentation

### 3. MCP Servers
- **Status**: ✅ Auto-connect on every session
- **Configuration**: [.mcp.json](../.mcp.json) + `enableAllProjectMcpServers: true`
- **Servers**: serena, sequential-thinking, context7, memory, fetch, windows-mcp, playwright, database-server

### 4. Specialized Agents
- **Status**: ✅ Always available
- **Location**: [.claude/agents/](.claude/agents/)
- **Count**: 8 agents (Explore, Plan, test-engineer, code-reviewer, etc.)
- **Access**: Via `Task` tool with `subagent_type` parameter

### 5. Slash Commands
- **Status**: ✅ Always available
- **Location**: [.claude/commands/](.claude/commands/)
- **Count**: 9 commands (/test, /review, /explain, etc.)
- **Access**: Via `SlashCommand` tool

---

## 📋 Session Initialization Flow

```
New Conversation Started
    ↓
1. Claude Code loads CLAUDE.md automatically
    ↓
2. SessionStart hook executes (.claude/hooks/session-start.sh)
    ↓
3. Hook outputs reminder message to conversation
    ↓
4. MCP servers auto-connect
    ↓
5. Agents become available
    ↓
6. Slash commands become available
    ↓
✅ Session ready with full context!
```

---

## 🧪 Testing

### Verify Session Hook Works

Run manually to see output:
```bash
bash .claude/hooks/session-start.sh
```

Expected output:
```
🚀 **New Session Initialized - Foundry VTT Development Environment**

📋 **MANDATORY REMINDERS FOR THIS SESSION**:
[... reminder content ...]
```

### Verify CLAUDE.md Loading

Start a new conversation and ask:
> "What project am I working on?"

Claude should know about:
- Foundry VTT v11.315
- PF1e System v10.8
- Macro development focus
- All project structure details

### Verify MCP Servers

In a new conversation, ask:
> "What MCP servers are available?"

Should list all 8 servers.

### Verify Agents

In a new conversation, ask:
> "What specialized agents are available?"

Should list all 8 agents with descriptions.

---

## 📁 Key Files

| File | Purpose | Auto-Load? |
|------|---------|-----------|
| [CLAUDE.md](../CLAUDE.md) | Complete project documentation | ✅ Yes |
| [.claude/SESSION_INSTRUCTIONS.md](SESSION_INSTRUCTIONS.md) | Quick reference for mandatory policies | Manual read |
| [.claude/settings.json](settings.json) | Claude Code configuration | ✅ Yes |
| [.claude/hooks/session-start.sh](hooks/session-start.sh) | Session initialization hook | ✅ Yes |
| [.mcp.json](../.mcp.json) | MCP server configuration | ✅ Yes |

---

## 🔧 Customization

### To Modify Session Start Message

Edit: [.claude/hooks/session-start.sh](hooks/session-start.sh)

The heredoc section (lines 15-48) contains the message displayed at session start.

### To Add More Instructions

**Option A**: Add to CLAUDE.md (automatically loaded)
**Option B**: Modify session-start.sh hook (shown at session start)
**Option C**: Create new files in .claude/ (manual read required)

### To Add More Hooks

Edit: [.claude/settings.json](settings.json)

Available hooks:
- `SessionStart`: Start of session
- `SessionEnd`: End of session
- `PreToolUse`: Before any tool use
- `PostToolUse`: After any tool use
- `UserPromptSubmit`: When user sends a message
- `Stop`: When generation is stopped

---

## ✨ Benefits of This Setup

1. **Zero Manual Effort**: Everything loads automatically
2. **Consistent Reminders**: Every session starts with clear instructions
3. **Full Context**: Claude always knows about agents, MCP servers, and project details
4. **Trackable**: Session logs in `.claude/logs/session.log`
5. **Customizable**: Easy to modify hooks and instructions

---

## 🎯 What Claude Will See in Every New Session

At the start of every conversation, Claude receives:

1. ✅ **System Prompt**: Contains full CLAUDE.md automatically
2. ✅ **Hook Output**: Displays session initialization banner
3. ✅ **MCP Tools**: All 8 MCP servers' tools are registered
4. ✅ **Agents**: All 8 agents are available via Task tool
5. ✅ **Slash Commands**: All 9 commands are available
6. ✅ **Permissions**: All allowed/denied operations from settings.json

---

## 📝 Maintenance

### When to Update

Update these files when:
- Adding new MCP servers → Update session-start.sh
- Adding new agents → Update session-start.sh
- Changing project focus → Update CLAUDE.md + session-start.sh
- Adding new mandatory policies → Update CLAUDE.md + SESSION_INSTRUCTIONS.md

### Backup

Key files to backup:
- CLAUDE.md
- .claude/settings.json
- .claude/hooks/*.sh
- .claude/SESSION_INSTRUCTIONS.md
- .mcp.json

---

## 🐛 Troubleshooting

### Hook Not Running?

Check [.claude/settings.json](settings.json) lines 116-126:
```json
"hooks": {
  "SessionStart": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "bash .claude/hooks/session-start.sh"
        }
      ]
    }
  ]
}
```

### CLAUDE.md Not Loading?

- Ensure file exists at project root: `c:\DEV\Foundry\CLAUDE.md`
- File is automatically loaded by Claude Code (no configuration needed)

### MCP Servers Not Connecting?

- Check `.mcp.json` exists
- Verify `enableAllProjectMcpServers: true` in settings.json
- Check MCP server installations

---

**Reference**: See [CLAUDE.md](../CLAUDE.md) for complete project documentation

**Questions?**: The session-start hook ensures you see reminders at every session start!