# Master Plan: CLAUDE.md Three-Level Cascade

**Date:** 2026-04-03
**Author:** CC Mini + Parker
**Supersedes:** 2026-03-25 (single-source-of-truth), 2026-03-27 (reversed)
**Tickets:** #157, #158, #183, #165, #166, #190 (LDM OS), #55 (MC), #163, #165, #174 (Toolbox)
**Active tests / extensions of this plan:**
- `ai/product/bugs/dot-claude/2026-04-16--cc-mini--dot-claude-level-3-missing.md` ... adds `.claude` as repo #12 in Step 2 and pilots the `REPO.md` naming where `CLAUDE.md` is already Level 1.

## Why now

On April 2-3, we discovered a critical bug: after context compaction, Claude Code's internal CWD shifts from the workspace root to the last repo touched by a bash command. The repo has no CLAUDE.md. The cascade breaks. All project context vanishes. Both agents flail.

This is not theoretical. It happened during the Kaleidoscope demo build. 10+ incorrect iterations. Hours of rework. Parker had to re-explain every decision. The root cause: no Level 3 CLAUDE.md in the repo.

See: `2026-04-03--cc-mini--cwd-compaction-bug-journal.md`

## The three levels

```
Level 1: ~/.claude/CLAUDE.md (global, ~30 lines)
  Writing style, co-authors, 1Password, universal rules.
  Every session. Generated by ldm install from config.json.

Level 2: ~/wipcomputerinc/CLAUDE.md (workspace, ~150 lines)
  Directory structure, boot sequence, agent instructions, memory tools.
  When opened from workspace root. The comprehensive one.

Level 3: <repo>/CLAUDE.md (per-repo, ~50 lines)
  What this repo does, build commands, current product context.
  Points up to Level 2. Points to Crystal for cross-repo search.
  THIS IS WHAT'S MISSING. Build it first.
```

## Approach: bottom-up

Don't touch Level 1 or Level 2 until Level 3 is proven. The Mar 25 plan went top-down (thinned Level 1 first). CC lost system knowledge for two days. Never again.

### Step 1: Level 3 for wip-ldm-os-private

This repo is where the bug manifests. Fix it first. CLAUDE.md content:
- What this repo is (LDM OS installer, Kaleidoscope demo, hosted MCP server)
- Build/test commands
- Key file locations
- Current product context (Kaleidoscope is the product, Lēsa is the platform agent, six sub-products)
- Pointer to Level 2: "For full system context, read ~/wipcomputerinc/CLAUDE.md"
- Pointer to docs: "For conventions, read ~/wipcomputerinc/settings/docs/"
- Pointer to Crystal: "For cross-repo context, use crystal_search"

### Step 2: Level 3 for the other repos

Same pattern. 12 repos total:
1. wip-ldm-os-private (Step 1)
2. memory-crystal-private
3. wip-ai-devops-toolbox-private
4. wip-agent-pay-private
5. wip-1password-private
6. wip-xai-grok-private
7. wip-xai-x-private
8. wip-markdown-viewer-private
9. dream-weaver-protocol-private
10. wip-healthcheck-private
11. wip-bridge-private
12. `.claude` (remote: `wipcomputer-ldmos-wipcomputerinc-dot-claude-private`) ... Level 3 lives at `REPO.md`, not `CLAUDE.md`, because the `CLAUDE.md` slot at this path is already Level 1 (global). One-line pointer from Level 1 surfaces it. Piloted in `ai/product/bugs/dot-claude/2026-04-16--cc-mini--dot-claude-level-3-missing.md`.

### Step 3: Test

Open CC from a repo directory. Verify it knows:
- What the repo does (Level 3)
- What the product is (Level 3 context or pointer to Level 2)
- Org conventions (Level 3 pointer to settings/docs)
- Cross-repo context (Crystal search)

Simulate the compaction scenario: work in repo, verify context survives.

### Step 4: Trim Level 2 (only after Step 3 passes)

~/wipcomputerinc/CLAUDE.md is 366 lines. After Level 3 exists in every repo, Level 2 can drop repo-specific details and shrink to ~150 lines.

### Step 5: Generate Level 1 from config (only after Step 4 passes)

~/.claude/CLAUDE.md becomes ~30 lines generated from settings/config.json. ldm install deploys it. Only universal rules. Last step.

## What this does NOT cover

- Level 3 content auto-generation (`wip-repos claude` ... future, ticket #165)
- Single folder architecture (#117)
- Total Recall pipeline
- TOOLS.md / MEMORY.md consolidation (Lēsa's files)

## Verification

```bash
# After Step 1:
cat repos/ldm-os/wip-ldm-os-private/CLAUDE.md  # exists

# Test from repo CWD:
cd repos/ldm-os/wip-ldm-os-private && claude
# "what is Kaleidoscope?" -> knows
# "what's the release pipeline?" -> knows or knows where to look
# "who is Lēsa?" -> knows

# Test compaction survival:
# Work in repo for extended session
# After compaction, verify context is still available
```
