# Plan: Single Source of Truth (Rules, Docs, CLAUDE.md Consolidation)

**Date:** 2026-03-25
**Author:** cc-mini (with Parker)
**Issues:** #157, #158, #183, #166, #117, #190

## Context

Lesa needed three corrections to get a basic git workflow right (commit to main, then branch without worktree, then finally worktree). The rules exist. The docs exist. The Dev Guide is comprehensive. But nothing connects them. Agents read thin shared rules (5 files, 80 lines) and a bloated CLAUDE.md (367 lines, 23% duplicated conventions) but never see the full Dev Guide or settings/docs/.

The workspace root plan (2026-03-21) already designed the fix: three-level CLAUDE.md, dev guide moved to settings/, docs deployed by ldm install. This plan executes it.

## The Problem (Three Copies, None in Sync)

```
Dev Guide (900 lines, comprehensive, in toolbox repo)
  ↓ manually excerpted
Shared rules (80 lines, thin, in ~/.ldm/shared/rules/)
  ↓ ldm install deploys
~/.claude/rules/ and ~/.openclaw/workspace/DEV-RULES.md

Also:
CLAUDE.md (367 lines, duplicates conventions from Dev Guide)
TOOLS.md (Lesa's copy, also drifting)
settings/docs/ (human docs, agents don't read)
```

## The Architecture (from workspace root plan, 2026-03-21)

### Three-Level CLAUDE.md

Claude Code reads these in cascade: global first, then workspace, then repo.

**Level 1: `~/.claude/CLAUDE.md` (global, ~30 lines)**
- Writing style (from config.json writingStyle)
- Co-authors on every commit (from config.json coAuthors)
- 1Password: always use SA token
- Never run tools from repo clones
- Shared file protection
- Generated from settings/config.json by ldm install

**Level 2: `~/.openclaw/CLAUDE.md` (workspace, ~100-150 lines)**
- Directory structure (what lives where)
- Config architecture (openclaw.json)
- Plugin table
- Memory system + Lesa's MCP tools
- Boot sequence + end-of-session
- What NOT to touch
- Pointer: "For dev conventions, read settings/docs/"

**Level 3: `<repo>/CLAUDE.md` (per-repo, generated by wip-repos claude)**
- What this repo does
- Build/test/lint commands
- Repo-specific guardrails
- Future (not in scope for this plan)

### Where Dev Conventions Live

```
Source of truth:
  Public Dev Guide    -> toolbox repo (ships with LDM OS, same for everyone)
  Private Dev Guide   -> ~/wipcomputerinc/settings/templates/dev-guide-private.md (org config)

Deployed docs (human + agent readable):
  ~/wipcomputerinc/settings/docs/
    how-worktrees-work.md
    how-releases-work.md
    system-directories.md
    ... (already exist, deployed by ldm install)

Guardrail rules (thin, every session):
  ~/.ldm/shared/rules/ -> ~/.claude/rules/ + ~/.openclaw/workspace/DEV-RULES.md
  (stay thin, but ADD pointer to settings/docs/ for full details)

Boot sequence (CC):
  boot-config.json reads CLAUDE.md + SOUL + CONTEXT + daily logs + repo-locations
  (no change needed, just CLAUDE.md gets smaller)
```

### Flow

```
settings/config.json (org identity)
  ↓ ldm install generates
~/.claude/CLAUDE.md (Level 1, ~30 lines)

settings/docs/ (full operational docs, human + agent)
  ↓ agents read when doing repo work (on demand, not on boot)
Dev conventions, worktree workflow, release pipeline, etc.

~/.ldm/shared/rules/ (guardrails)
  ↓ ldm install deploys
~/.claude/rules/ + DEV-RULES.md (thin, every session)
  Each rule file says: "For details, read ~/wipcomputerinc/settings/docs/<relevant-doc>.md"

settings/templates/dev-guide-private.md (org-specific conventions)
  ↓ agents read for WIP-specific details
Branch prefixes, agent IDs, incidents, deploy paths
```

## Existing Tickets

### wip-ldm-os (public)
| # | Title | What it does for this plan |
|---|-------|--------------------------|
| #157 | Move org-specific dev guide out of toolbox repo | Private dev guide -> settings/templates/ |
| #158 | ldm install: deploy docs/ to workspace settings | Universal docs + "Your System" from config.json |
| #183 | ldm audit-rules: dead weight detection | Cut CLAUDE.md from 367 to ~30 lines (Level 1) |
| #166 | CLAUDE.md template: Crystal fallback | Per-repo CLAUDE.md template |
| #117 | Move ~/.ldm/ to ~/wipcomputer/ldm/ | Future: single folder (not in scope now) |
| #190 | Use workspace templates from settings/templates/ | Tools read org overrides |

### memory-crystal
| # | Title | What it does for this plan |
|---|-------|--------------------------|
| #55 | Adopt centralized _worktrees/ convention | STALE: says `_worktrees/`, resolved to `.ldm/worktrees` (harness-agnostic). Needs update. |

### wip-ai-devops-toolbox (public)
| # | Title | What it does for this plan |
|---|-------|--------------------------|
| #163 | Rename to WIP Code | Branding (not blocking) |
| #165 | Auto-generate Claude Code plugin manifest | Per-repo CLAUDE.md generation |
| #174 | repos-manifest.json -> ai/ + bootstrap | New machine setup |

## Stale Content to Fix

1. `workspace-boundaries.md` says `staff/` -> should be `team/`
2. CLAUDE.md has ~83 lines of duplicated conventions -> move to Level 1 or cut
3. Private Dev Guide `lesa-mini` branch prefix -> was `lesa/`, now `lesa-mini/`
4. MC #55 says `_worktrees/` -> resolved to `.ldm/worktrees` (harness-agnostic, config.json already correct)
5. Dev Guide worktree section mentions `.claude/worktrees/` and `_worktrees/` -> should say `.ldm/worktrees`
6. `settings/docs/how-worktrees-work.md` says `~/wipcomputerinc/repos/_worktrees/` -> should say `.ldm/worktrees`

## Implementation Steps

### Principle: Addition by Subtraction

Ole Lehmann: "I deleted half my Claude setup and every output got BETTER."
Anthropic's own team found their scaffolding was making the AI worse.
Over-prompting makes the model try to follow everything and do none of it well.
**Cut first. Organize what survives. Never move dead weight to new shelves.**

### Step 1: Audit everything (#183)

Run the 5-question check against ALL instruction files:
- `~/.openclaw/CLAUDE.md` (367 lines)
- `~/.claude/CLAUDE.md` (duplicate of above)
- `~/.ldm/shared/rules/` (5 files, 80 lines)
- `~/.openclaw/workspace/TOOLS.md` (Lesa's rules)
- Boot files loaded via `boot-config.json` (10 files)

For each rule/instruction, ask:
1. **Default?** Does the model already do this without being told?
2. **Conflict?** Does this contradict another rule somewhere?
3. **Duplicate?** Is this covered by a different rule or file?
4. **One-off fix?** Was this added to patch one bad output?
5. **Vague?** Would the model interpret this differently every time?

Output: list of what to cut, list of conflicts, cleaned version.

### Step 2: Cut and test

1. Delete flagged rules
2. Run 3 most common tasks with trimmed setup
3. Did output stay the same or get better? Dead weight confirmed.
4. Did something specific break? Add back just that one rule.
5. Goal: minimum viable setup

### Step 3: Split what remains into levels

Only AFTER cutting. Now organize what survived:

**Level 1: `~/.claude/CLAUDE.md` (~30 lines, generated from config.json)**
- Writing style, co-authors, 1Password SA token, shared file protection
- Generated by `ldm install` from `settings/config.json`

**Level 2: `~/.openclaw/CLAUDE.md` (~100-150 lines, workspace)**
- Directory structure, config architecture, plugins, memory system
- Agent-specific: Lesa comms, MCP tools, boot sequence
- Pointer: "For dev conventions, read `settings/docs/` on demand"

**Level 3: per-repo CLAUDE.md (future, not this plan)**

### Step 4: Move private Dev Guide (#157)

- Move `wip-ai-devops-toolbox-private/ai/DEV-GUIDE-FOR-WIP-ONLY-PRIVATE.md` to `~/wipcomputerinc/settings/templates/dev-guide-private.md`
- Replace placeholder at `settings/templates/dev-guide-private-placeholder.md`
- Update reference in the public Dev Guide

### Step 5: Add on-demand pointers to shared rules

Agents DON'T read settings/docs/ on boot (too many tokens). Rules tell agents WHERE to look when they need details:

- `git-conventions.md` footer: "Before repo work, read `~/wipcomputerinc/settings/docs/how-worktrees-work.md`"
- `release-pipeline.md` footer: "Before releasing, read `~/wipcomputerinc/settings/docs/how-releases-work.md`"
- `workspace-boundaries.md` footer: "For full directory map, read `~/wipcomputerinc/settings/docs/system-directories.md`"
- Fix `staff/` -> `team/` in workspace-boundaries.md

On-demand = tokens only when needed. Boot stays lean.

### Step 6: Update ldm install (#158)

- Deploy universal docs from LDM OS repo to `settings/docs/`
- Generate "Your System" sections from `config.json`
- Generate Level 1 CLAUDE.md from template + `config.json`
- Deploy shared rules with pointers

### Step 7: Verify

- Both agents can find worktree workflow (on demand, not boot)
- Boot token count reduced (CLAUDE.md ~180 lines total vs 367)
- Common tasks produce same or better output with trimmed setup
- No dead weight moved to new locations

## Verification

```bash
# After implementation:
wc -l ~/.claude/CLAUDE.md               # should be ~30 lines (Level 1)
wc -l ~/.openclaw/CLAUDE.md             # should be ~150 lines (Level 2)
cat ~/.ldm/shared/rules/git-conventions.md  # should have pointer to how-worktrees-work.md
ls ~/wipcomputerinc/settings/templates/dev-guide-private.md  # should exist
ls ~/wipcomputerinc/settings/docs/how-worktrees-work.md      # should exist

# Test agent awareness:
# In CC session: "what's the worktree workflow?" -> should reference settings/docs/
# In Lesa session: same question -> should find the same doc
```

## What This Does NOT Cover

- Level 3 per-repo CLAUDE.md (future, #165, #166)
- #117 single folder architecture (~/.ldm/ -> ~/wipcomputer/ldm/)
- Total Recall pipeline (#193, #194) ... separate plan exists
- Backfill summaries (#194) ... separate plan exists
