# 🎯 THE DEFINITIVE CLAUDE CODE SETUP WIZARD
Marc Hoag | marc@marchoag.com | github.com/marchoag | linkedin.com/in/marchoag | x.com/marchoag

**Battle-Tested Documentation System for Maximum AI Productivity**  
*Includes bulletproof security protocols and 67% context optimization*

Created: August 26, 2025
Optimized: February 4, 2026

---

## 🎬 PURPOSE: Ultra-optimized Claude Code setup using 3 active MD files (17KB total) plus searchable archive system with bulletproof security protocols.

---

## 🔐 GLOBAL SECURITY (One-Time Setup)

**CRITICAL**: Before running this wizard for ANY project, ensure global security is configured. This is done ONCE and protects ALL your projects forever.

### Two-Layer Security Model

| Layer | File | Purpose |
|-------|------|---------|
| **Hard Block** | `~/.claude/settings.json` | Tool-level enforcement — Claude literally cannot read denied files |
| **Soft Block** | `~/.claude/CLAUDE.md` | Instructions Claude reads and understands — can explain refusals |

### First-Time Setup (Run Once Ever)

**1. Create/update `~/.claude/settings.json`:**
```json
{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./**/*.pem)",
      "Read(./**/*.key)",
      "Read(./**/credentials.json)",
      "Read(./**/secrets.json)",
      "Read(./**/.npmrc)",
      "Read(./**/.netrc)",
      "Read(./**/Config.swift)",
      "Read(./**/Secrets.swift)",
      "Read(./**/APIKeys.swift)",
      "Read(./**/*.xcconfig)",
      "Read(./**/GoogleService-Info.plist)"
    ]
  }
}
```

**2. Create `~/.claude/CLAUDE.md`:**
```markdown
# Global Security Policy

- Never read `.env*` files or any secrets/credentials files
- Reference environment variables by NAME only, never values
- If asked to access secrets, suggest alternatives (.env.example, variable names)
- Never include secret values in code, commits, or output
```

### Why Both Layers?

- **settings.json**: Even if you forget session protocols, Claude cannot physically read these files
- **CLAUDE.md**: Claude understands the policy and can explain why it refuses (better UX)

### Subsequent Projects

The wizard will verify global security is in place. If already configured, it confirms and moves on.

---

## 📁 THE 3-FILE ACTIVE SYSTEM

**MANDATORY STRUCTURE**: Your MD-ACTIVE/ folder must contain EXACTLY these files:

### **1. MD-SESSION-PROTOCOL.md** (~6KB)
**Purpose**: Session automation + security acknowledgment
**Usage**: Read at every session start
**Contains**:
- Session start/end commands
- Security acknowledgment (complements global `~/.claude/settings.json` protection)
- Working relationship dynamics (CEO/CTO challenge mandate)
- Technical Mastery Reference auto-triggers
- Git commit workflows with intelligent messages
- Project-specific env var guidance

### **2. MD-YYYYMMDD-[SESSION-NAME].md** (~6KB)
**Purpose**: Current session bookmark  
**Usage**: Read at session start, archived at session end  
**Contains**:
- Last work completed (✅ COMPLETED, 🔄 IN PROGRESS, 🚫 BLOCKED)
- Current platform status (version, branch, deployment state)
- Next priorities (3-5 specific actionable tasks)
- Critical context (gotchas, decisions, blockers)

### **3. CHANGELOG-CURRENT.md** (~5KB)
**Purpose**: Recent version history only  
**Usage**: Referenced for product evolution context  
**Contains**: Last 5-10 versions with user-facing descriptions

**TOTAL: ~17KB (67% reduction from previous 52KB system)**  
**BREAKTHROUGH**: Eliminates context overflow while preserving perfect continuity

---

## 📚 THE ARCHIVE SYSTEM (MD-ARCHIVE/)

**Purpose**: Searchable institutional memory that doesn't break context limits

### **Core Archive Files**

#### **MD-CLAUDE-TECHNICAL-MASTERY-REFERENCE.md** (~88KB)
**THE DEBUGGING BIBLE**: Complete technical solutions and patterns
- **When Claude uses it**: Automatically searches when encountering known issue patterns
- **How it works**: Searchable, not readable - Claude never reads the whole file
- **Auto-triggers**: Auth bugs, database errors, modal conflicts, infinite loops, email issues
- **Manual triggers**: "Search Technical Mastery for [topic]"
- **Updates**: New patterns added at each session end

#### **MD-[PROJECT-NAME]-EISENHOWER-MATRIX.md**
**PURPOSE**: Strategic priority management
- **When to use**: Planning major features and roadmap decisions
- **Contains**: Urgent vs Important task categorization
- **Updates**: Modified when priorities shift significantly

### **Organized Archive Structure**
- **MD-ARCHIVE/bookmarks/**: All previous session bookmarks (chronological)
- **MD-ARCHIVE/reference/**: Technical guides, full changelog, build guides
  - CHANGELOG-FULL.md (complete version history)
  - MD-[PROJECT]-BUILD-GUIDE.md (moved from MD-ACTIVE for context optimization)
  - MD-CLAUDE-TECHNICAL-MASTERY-REFERENCE.md (debugging patterns)
  - Strategy documents, deployment guides, specialized documentation

---

## 🤖 AUTOMATED CLAUDE BEHAVIORS

### **Session Start (User says "session start")**
1. **Security First**: Acknowledge `.env*` protection policy
2. **Read** MD-SESSION-PROTOCOL.md
3. **Read** latest session bookmark  
4. **Read** CHANGELOG-CURRENT.md
5. **Echo back** working relationship and platform status
6. **Create TodoWrite** list from bookmark priorities
7. **Auto-activate** Technical Mastery Reference (ready to search)
8. **Begin work** on first task

### **Session End (User says "session end")**
1. **Update** CHANGELOG-CURRENT.md if new version
2. **Sync** to CHANGELOG-FULL.md in archive
3. **Create** new session bookmark with big-picture summary
4. **Archive** previous bookmark to MD-ARCHIVE/bookmarks/
5. **Update** Technical Mastery Reference with new patterns
6. **Ask commit prompt**: "Ready to commit and deploy? (y/n)"
7. **Git commit & deploy** with intelligent commit message
8. **Confirm**: "Session complete: [message] → deployed. Ready for next."

### **Automatic Technical Mastery Searches**
Claude automatically searches when encountering:
- **Auth issues** → "authentication" patterns
- **Database errors** → "database safety" protocols
- **Modal problems** → "modal conflict" solutions
- **Infinite loops** → "infinite loop debugging"
- **Email verification** → "mobile Safari email" fixes
- **Deployment failures** → "production debugging"

**Claude announces**: "🔍 Searching Technical Mastery for [pattern]..."

---

## 💡 WHY THIS SYSTEM WORKS

### **Context Window Management**
- **Active folder**: 17KB (massive optimization breakthrough)
- **Archive folder**: Unlimited size (searched when needed)
- **No context overflow**: Sessions always start successfully
- **67% reduction**: From 52KB to 17KB without losing any functionality

### **Zero Information Loss**
- **Complete history**: Every solution and pattern preserved
- **Institutional memory**: Technical knowledge accumulates
- **Session continuity**: Perfect handoffs between sessions

### **AI-Optimized Design**
- **Readable vs Searchable**: Small files read, large files searched
- **Automatic triggers**: Claude knows when to consult archives
- **Pattern recognition**: Recurring issues solved with proven solutions

### **Human Workflow Integration**
- **Simple commands**: "session start" and "session end"
- **Transparent process**: User always knows what's happening
- **Flexible content**: Works with any project type

---

## 🚀 IMPLEMENTATION GUIDE

### **Step 1: Initial Setup**
```bash
mkdir MD-ACTIVE MD-ARCHIVE
cd MD-ACTIVE
```

### **Step 2: Create Core Files**
1. **Copy** MD-SESSION-PROTOCOL.md template
2. **Create** initial session bookmark
3. **Move** existing CHANGELOG.md (if exists)
4. **Create** project build guide

### **Step 3: Archive Migration**
```bash
mv old-md-files/* MD-ARCHIVE/
```

### **Step 4: Test Session Protocol**
- User says "Read @MD-ACTIVE/ and session start"
- Verify Claude reads all 4 files and creates TodoWrite list
- User says "session end"
- Verify new bookmark created and archived

### **Step 5: Customize for Project**
- Update session protocol working relationship
- Modify build guide for your architecture
- Add project-specific Technical Mastery patterns

---

## 📋 SESSION BOOKMARK TEMPLATE

```markdown
# 📋 Session Complete: [Feature Name]

**Date**: [YYYY-MM-DD]  
**Focus**: [Session main objective]

## 🎯 Last Work
✅ **COMPLETED**: [Big picture accomplishment]
🔄 **IN PROGRESS**: [Current state if not finished]
🚫 **BLOCKED**: [Any blockers with reasons]

## 🚀 Current Platform Status
- **Version**: [Current version]
- **Branch**: [Git branch]
- **Latest**: [Most recent major change]

## 📋 Next Priorities
1. [Specific actionable task]
2. [Specific actionable task]
3. [Specific actionable task]

## 🔧 Critical Context
- [Important gotchas or decisions]
- [Any technical debt or known issues]
- [Dependencies or blockers]

---
**Next Claude**: [Brief instruction for next session]
```

---

## ⚡ ADVANCED PATTERNS

### **Multi-Project Management**
- **Separate MD-ACTIVE folders** for each project
- **Shared Technical Mastery Reference** across projects
- **Project-specific session protocols**

### **Team Collaboration**
- **Git-tracked documentation** for team access
- **Individual session bookmarks** per developer
- **Shared Technical Mastery** for team knowledge

### **Scaling Strategies**
- **Archive compression** for very old sessions
- **Pattern categorization** in Technical Mastery
- **Automated archive pruning** (optional)

---

## 🎯 SUCCESS METRICS

### **Context Management**
- ✅ Session start time: <10 seconds
- ✅ No context overflow errors
- ✅ Complete information preservation

### **Productivity Gains**
- ✅ Zero session setup friction
- ✅ Perfect session handoffs
- ✅ No repeated debugging of solved problems
- ✅ Institutional knowledge accumulation

### **Quality Indicators**
- ✅ Claude remembers all previous solutions
- ✅ Automatic application of proven patterns
- ✅ Transparent decision-making process

---

## 🔧 TROUBLESHOOTING

### **Context Still Too Large**
1. Check MD-ACTIVE folder size: `du -sh MD-ACTIVE/` (should be ~17KB)
2. Archive older session bookmarks to MD-ARCHIVE/bookmarks/
3. Ensure only 3 core files in MD-ACTIVE
4. Verify global security is configured (`~/.claude/settings.json`)

### **Session Handoffs Failing**
1. Verify session bookmark completeness
2. Check "Next Priorities" specificity
3. Ensure critical context is documented
4. Test session start/end commands

### **Technical Mastery Not Working**
1. Verify file is in MD-ARCHIVE
2. Test manual search: "Search Technical Mastery for authentication"
3. Check automatic trigger patterns
4. Ensure patterns are being added at session end

---

## 🎉 FINAL RECOMMENDATIONS

### **For Individual Developers**
- **Start simple**: Begin with optimized 3-file structure (17KB)
- **Security first**: Configure global `~/.claude/settings.json` deny rules (one-time)
- **Be disciplined**: Always use session start/end commands
- **Document patterns**: Add every solution to Technical Mastery

### **For Teams**
- **Standardize structure**: Same folder layout across all projects
- **Share knowledge**: Collaborative Technical Mastery Reference
- **Review regularly**: Periodic optimization of documentation

### **For Complex Projects**
- **Multiple specialists**: Separate MD-ACTIVE per domain
- **Cross-references**: Link between related documentation
- **Automated backups**: Protect institutional knowledge

---

## 🔒 BULLETPROOF SECURITY PROTOCOLS

### Security Hierarchy

**Layer 1: Global Protection (Permanent)**
- `~/.claude/settings.json` with `permissions.deny` — tool-level hard block
- `~/.claude/CLAUDE.md` — global instructions Claude reads
- Set up ONCE, protects ALL projects forever
- See "🔐 GLOBAL SECURITY" section above for setup

**Layer 2: Session Protocol (Per-Project)**
- Security acknowledgment at each session start
- Project-specific env var guidance (which are server-only, etc.)
- Contextual understanding for this specific codebase

### 🚨 MANDATORY: .ENV FILE PROTECTION

**ABSOLUTE REFUSAL POLICY**:
- **NEVER** open, read, or print any `.env*` files (`.env`, `.env.local`, etc.)
- **NEVER** reveal, echo, diff, or log environment VALUES
- **ONLY** reference variable NAMES when needed
- **CLIENT CODE**: Use only `NEXT_PUBLIC_*` environment variables
- **SERVER CODE**: `SUPABASE_SERVICE_ROLE_KEY`, `RESEND_API_KEY` only in route handlers or `lib/server/*`

**CLAUDE RESPONSE** when asked to read `.env*`:
*"For safety, I won't open or print `.env*` files or secret values. I can reference variable NAMES only."*

**RUNTIME GUARDS**:
- Before any filesystem operation: verify no `.env*` file access
- Before any bash command: ensure no literal secret values
- When searching/grepping: always exclude `.env*` files
- When showing diffs: ensure no secret values revealed

**Note**: With global `settings.json` deny rules in place, Claude physically cannot read these files even if instructed to. The session protocol provides additional context and explanation.

---

## 🤖 IMPLEMENTATION INSTRUCTIONS FOR CLAUDE

### 🚨 CRITICAL: SESSION START TRIGGER BEHAVIOR

**WHEN A USER SAYS "session start" (or similar phrases):**

**MANDATORY ACTIONS - Execute IMMEDIATELY without asking:**

1. **Acknowledge security**: "I will not open or read any `.env*` files. I will reference env by NAME only."
2. **Read ALL MD-ACTIVE files** using multiple Read tool calls in parallel:
   - MD-SESSION-PROTOCOL.md
   - MD-YYYYMMDD-[latest].md (current session bookmark) 
   - CHANGELOG-CURRENT.md

2. **Echo back to user**:
   - Working relationship (from protocol)
   - Current platform status (from bookmark)
   - Today's priorities (from bookmark)

3. **Create TodoWrite list** from bookmark priorities

4. **Auto-activate Technical Mastery Reference** (ready for searches)

5. **Begin work** on first task

**TRIGGER PHRASES THAT REQUIRE THIS BEHAVIOR:**
- "session start" 
- "start session"
- "begin session"
- "read the files"
- "read MD-ACTIVE"

**FAILURE TO EXECUTE = BROKEN SYSTEM**
If you do not automatically execute this protocol when these phrases are detected, the entire documentation strategy fails. This is the core promise of the system.

### 🚨 CRITICAL: SESSION END TRIGGER BEHAVIOR

**WHEN A USER SAYS "session end" (or similar phrases):**

**MANDATORY ACTIONS - Execute IMMEDIATELY without asking:**

1. **Create new session bookmark**: MD-YYYYMMDD-[SESSION-NAME].md with:
   - Last Work (BIG PICTURE summary: ✅ COMPLETED, 🔄 IN PROGRESS, 🚫 BLOCKED)
   - Current Platform Status (version, branch, latest changes)
   - Next Priorities (3-5 specific actionable tasks)
   - Critical Context (gotchas, decisions, blockers)

2. **Archive previous bookmark** to MD-ARCHIVE/ folder

3. **Update Technical Mastery Reference** with any new patterns learned

4. **Git commit & deploy** with intelligent commit message format:
   - `✅ [Feature]: Brief user-facing description`
   - Always push to main branch (auto-deploys)

5. **Confirm completion**: "Session complete: [commit message] → deployed. Ready for next session."

**TRIGGER PHRASES THAT REQUIRE THIS BEHAVIOR:**
- "session end"
- "end session"
- "finish session"
- "wrap up"
- "create bookmark"

---

**WHEN A USER SAYS**: *"Read this strategy and implement it"* or *"Set up this documentation system"*

### **STEP 1: AUTOMATIC SETUP (No Questions Asked)**

Execute immediately without asking permission:

```bash
# 1. Check global security (one-time setup)
# If ~/.claude/settings.json lacks permissions.deny → add deny rules
# If ~/.claude/CLAUDE.md doesn't exist → create with security policy
# If already configured → confirm "✓ Global security active"

# 2. Create optimized folder structure
mkdir -p MD-ACTIVE MD-ARCHIVE/bookmarks MD-ARCHIVE/reference

# 3. Scan for existing documentation to migrate
# 4. Create the 3 core files with security-enhanced templates
# 5. Move historical files to organized archive structure
```

**Global Security Check Output:**
- First time ever: "Setting up global security for all your projects..."
- Already configured: "✓ Global security already active (settings.json + CLAUDE.md)"

### **STEP 2: SETUP WIZARD (Essential Questions)**

After setup, prompt user with these questions to populate the files:

#### **🤝 Working Relationship (Questions 1-3 of 12)**
- **Q1/12**: "What's your role? (CEO, Developer, PM, etc.)"
- **Q2/12**: "Technical background? (Non-technical founder, Senior dev, etc.)"
- **Q3/12**: "How should I challenge bad ideas? (Direct pushback, alternatives, etc.)"

#### **📋 Project Essentials (Questions 4-7 of 12)**
- **Q4/12**: "Project name and tech stack? (React, Python, etc.)"
- **Q5/12**: "Current version/status and main deployment branch?"
- **Q6/12**: "Development commands? (npm run dev, build, test, etc.)"
- **Q7/12**: "Where deployed? (Vercel, AWS, local only, etc.)"

#### **🔒 Security Setup (Questions 8-9 of 12)**
- **Q8/12**: "Global protection is already active. For this project, which env vars are server-only vs client-side?"
- **Q9/12**: "Any project-specific secrets patterns I should know about? (e.g., Config.swift for iOS)"

#### **🎯 Current Focus (Questions 10-12 of 12)**
- **Q10/12**: "Top 3 priorities RIGHT NOW? (Specific actionable tasks)"
- **Q11/12**: "Biggest current problem or blocker?"
- **Q12/12**: "Any debugging patterns or gotchas to remember?"

### **STEP 3: FILE POPULATION**

Use answers to generate:

1. **MD-SESSION-PROTOCOL.md**: Security-first protocol with working relationship and `.env*` protection
2. **MD-YYYYMMDD-INITIAL-SETUP.md**: Session bookmark with priorities and platform status
3. **CHANGELOG-CURRENT.md**: Recent version history template
4. **MD-ARCHIVE/reference/MD-[PROJECT]-BUILD-GUIDE.md**: Architecture guide (archived for context optimization)
5. **MD-ARCHIVE/reference/MD-CLAUDE-TECHNICAL-MASTERY-REFERENCE.md**: Fresh debugging template

*(Global security files `~/.claude/settings.json` and `~/.claude/CLAUDE.md` are created/verified in Step 1)*

### **STEP 4: VERIFICATION**

After setup:
1. **Show folder structure** created
2. **Test session protocol**: "Say 'session start' to test the system"
3. **Confirm next steps**: "Here are your top 3 priorities based on our conversation..."

### **STEP 5: CLEANUP & FAREWELL**

**MANDATORY FINAL STEP - Execute automatically:**

1. **Move setup wizard to archive**:
   ```bash
   mv MD-CLAUDE-CODE-SETUP-WIZARD.md MD-ARCHIVE/
   ```

2. **Verify clean project state**: Optimized 3-file system:
   - Global security configured (`~/.claude/settings.json` + `~/.claude/CLAUDE.md`)
   - MD-ACTIVE/ contains exactly 3 files (17KB total)
   - MD-ARCHIVE/ organized with bookmarks/ and reference/ folders
   - Setup wizard moved to MD-ARCHIVE/reference/
   - Project ready for maximum productivity

3. **Clean goodbye message**:
   ```
   🎉 **SETUP WIZARD COMPLETE!**

   ✅ Global security active (settings.json + CLAUDE.md)
   ✅ Documentation system ready (3 active files, 17KB total)
   ✅ Archive system organized (bookmarks/ + reference/)
   ✅ Setup wizard archived to MD-ARCHIVE/reference/
   ✅ Project optimized for maximum Claude Code productivity

   **Your project now has battle-tested AI-assisted development setup!**

   📋 Next Steps:
   1. Tell Claude: "Read @MD-ACTIVE/ and session start"
   2. Claude will acknowledge security protocols and read all 3 files
   3. Your top priorities are tracked and ready
   4. Technical Mastery Reference will grow as you solve problems

   🔒 **Security Note**: Global deny rules protect ALL your projects.
   Claude physically cannot read .env files, Config.swift, etc.

   🚀 **Ready for maximum productivity with bulletproof security!**
   ```

### **WIZARD CONVERSATION EXAMPLE**

```
🤖 Claude: "I've created your MD-ACTIVE/ and MD-ARCHIVE/ folders! Now let's customize the system for you.

🤝 Working Relationship (Questions 1-4 of 21):
Q1/21 - What's your role in this project?"

👤 User: "I'm the CEO and founder, but I'm not a developer"

🤖 Claude: "Got it! So I should challenge technical decisions and explain things clearly.
Q2/21 - What's your technical background?"

👤 User: "Non-technical founder, I understand concepts but don't code"

🤖 Claude: "Perfect. That helps me know how to explain things.
Q3/21 - How should I push back when I think an approach might be wrong?"

👤 User: "Be direct, offer alternatives, don't just say yes to everything"

🤖 Claude: "Excellent. I'll challenge decisions constructively.
Q4/21 - What's your preferred working style?"

👤 User: "Fast iteration, get something working quickly then polish"

🤖 Claude: "📋 Project Context (Questions 5-9 of 21):
Q5/21 - What's your project name?"

[Continue through all 21 questions with progress tracking...]
```

### **FILE TEMPLATES TO AUTO-GENERATE**

Based on wizard answers, create files with this structure:

**MD-SESSION-PROTOCOL.md**:
- Customized working relationship from answers
- Project-specific deployment commands
- Git workflow from their setup

**Session Bookmark**:
- Their stated priorities as TodoWrite items
- Current project status from their description
- Next steps based on their goals

**Build Guide**:
- Their tech stack and setup commands
- Architecture notes from their description
- Common workflows they mentioned

**Technical Mastery**:
- Empty template with standard debugging categories
- Seeded only with patterns they mentioned in Q19-21
- Ready to grow with project-specific solutions

#### **Technical Mastery Reference Template**

```markdown
# CLAUDE TECHNICAL MASTERY REFERENCE

**Purpose**: Searchable institutional memory for debugging patterns and solutions

---

## 🎯 **CRITICAL: SESSION START CHECKLIST**

### **Working Relationship & Role Dynamics**
[Populated from setup wizard answers Q1-Q4]

---

## 🚨 **DATABASE SAFETY PROTOCOLS**
*Solutions will be added as patterns are discovered*

---

## 🧠 **AUTHENTICATION & SESSION MANAGEMENT** 
*Solutions will be added as patterns are discovered*

---

## 🎨 **UI/MODAL PATTERNS & CONFLICTS**
*Solutions will be added as patterns are discovered*

---

## 🔍 **INFINITE LOOP DEBUGGING**
*Solutions will be added as patterns are discovered*

---

## 🤖 **API & DATA FETCHING PATTERNS**
*Solutions will be added as patterns are discovered*

---

## 📱 **MOBILE & CROSS-PLATFORM ISSUES**
*Solutions will be added as patterns are discovered*

---

## 🚀 **BUILD & DEPLOYMENT DEBUGGING**
*Solutions will be added as patterns are discovered*

---

## 🎯 **PROJECT-SPECIFIC PATTERNS**
[Seeded with patterns mentioned in Q19-21]

---

*This file grows over time as you encounter and solve technical challenges. Each pattern should include: Problem, Investigation, Solution, and Reusable Code Examples.*
```

### **SUCCESS CONFIRMATION**

End with:
"✅ **SETUP COMPLETE!** Your documentation system is ready. 
- Total context: ~17KB (67% optimized breakthrough)
- Say 'session start' to test the system
- Say 'session end' when done to save progress

Your top 3 priorities are now tracked. Ready to work!"

---

**🏆 RESULT: MAXIMUM CLAUDE CODE PRODUCTIVITY**

This system transforms Claude Code from a session-limited tool into a continuously improving development partner with perfect memory, proven debugging patterns, and seamless workflow integration.

**Use this strategy on ANY project to achieve optimal AI-assisted development productivity.**

---

_This documentation represents battle-tested experience from intensive Claude Code usage. The patterns and optimizations are proven to work at scale._

**DO NOT MODIFY THIS FILE WITHOUT CRITICAL NEED - IT REPRESENTS COMPLETE OPTIMIZATION**