# Plan: Implement CLAUDE.md Across All Repos

**Date:** 2026-03-19
**Author:** cc-opus
**Repo:** wip-ai-devops-toolbox-private

## Context

AI agents read CLAUDE.md on session startup. Without it, agents have no project-specific context — wrong paths, wrong conventions, wrong guardrails. With 100+ repos, manually writing and maintaining CLAUDE.md per repo doesn't scale. Agents also routinely overwrite or truncate CLAUDE.md after context compaction.

**The cross-repo problem:** When an agent launches in repo-A, it can't read repo-B. But repos work together — they share APIs, import each other, follow shared conventions. Without cross-repo awareness, the agent makes wrong assumptions about sibling repos it depends on.

**The solution:** `wip-repos claude` runs locally where all repos are on disk. It reads every repo's metadata and bakes a cross-repo ecosystem map into each repo's CLAUDE.md. The agent never needs to read sibling repos at runtime — the context was pre-generated.

This plan covers: global CLAUDE.md, per-repo templates, cross-repo ecosystem generation, and protection at scale.

---

## Phase 1: Global CLAUDE.md (`~/.claude/CLAUDE.md`)

**What to build:** A global CLAUDE.md that applies to every Claude Code session, regardless of repo.

**Contents (universal conventions only):**
- Team identity (WIP Computer, who the agents are)
- Commit message style, branch naming rules
- "Never push to main" guardrail
- Toolbox usage: wip-release for releases, wip-file-guard for protection
- `.npmignore` rules (always exclude CLAUDE.md, ai/, .claude/)
- Link to DEV-GUIDE-GENERAL-PUBLIC.md for full conventions
- Boot sequence: "Read the repo's CLAUDE.md first"

**Deliverable:** `templates/global-claude-md.md` template in the toolbox, plus documentation on where to place it.

**Status:** TODO

---

## Phase 2: Per-Repo CLAUDE.md Template System

**What to build:** A template that `wip-repo-init` uses to generate a starter CLAUDE.md for any new or existing repo.

**Template pulls from:**
- `package.json` — name, description, scripts (test, build, lint commands)
- `repos-manifest.json` — category, related repos, local path
- Directory structure scan — detect `src/`, `tools/`, `ai/`, etc.
- Git remote — org/repo name

**Template structure:**
```markdown
# CLAUDE.md — {repo-name}

## Boot Sequence
1. Read this file completely before acting
2. Read ai/read-me-first.md if it exists
3. Current repo path: {path}
4. Never commit directly to main

## Project Overview
- {description from package.json}
- Language/framework: {detected}
- Test: `{scripts.test}`
- Build: `{scripts.build}`
- Lint: `{scripts.lint}`

## Architecture
- {auto-detected key directories}

## Repo-Specific Guardrails
- {auto-detected: dual-license notice if .license-guard.json exists}
- {auto-detected: private repo warning if name ends in -private}

## Ecosystem
<!-- wip-repos:start -->
{auto-generated cross-repo map — see Phase 3}
<!-- wip-repos:end -->
```

**Deliverable:** `tools/wip-repo-init/templates/CLAUDE.md.template` + generation logic in `wip-repo-init`.

**Status:** TODO

---

## Phase 3: `wip-repos claude` — Cross-Repo Ecosystem Generation

**The core problem this solves:** Agent in repo-A can't read repo-B, repo-C, etc. But it needs to know what they provide, where they live, and how to import them.

**What to build:** A subcommand of `wip-repos` that reads ALL repos on disk and bakes cross-repo context into each repo's CLAUDE.md.

**How it works:**
```
wip-repos claude              # regenerate all repos
wip-repos claude my-repo      # regenerate one repo
wip-repos claude --dry-run    # preview changes
wip-repos claude --init       # create CLAUDE.md for repos missing one
```

### What it reads from each repo

For every repo in the manifest, `wip-repos claude` reads:

| Source | What it extracts |
|--------|-----------------|
| `package.json` | name, description, version, exports, bin commands, scripts |
| `SKILL.md` | capabilities, interfaces (CLI/module/MCP/etc.) |
| `repos-manifest.json` | category, path, public/private, related repos |
| `.git/config` | remote URL |
| Directory structure | key dirs (src/, tools/, api/, etc.) |

### What it writes into each repo's CLAUDE.md

An `## Ecosystem` section delimited by `<!-- wip-repos:start -->` / `<!-- wip-repos:end -->` comments. Example for the toolbox repo:

```markdown
## Ecosystem (auto-generated by wip-repos claude)
<!-- wip-repos:start -->

### memory-crystal — ~/ldm-os/identity/memory-crystal-private
Identity and memory storage for AI agents.
- Category: identity
- Provides: memory store, retrieval API
- Import: `@wipcomputer/memory-crystal`
- Interfaces: module, MCP

### wip-inc — ~/ldm-os/operations/wip-inc
Organization-wide operations, daily summaries, config.
- Category: operations
- Key files: repos-manifest.json, operations/daily/

### lesa-core — ~/ldm-os/identity/lesa-core-private
Lesa agent personality and behavioral config.
- Category: identity
- Provides: agent personality, response patterns
- Interfaces: module

<!-- wip-repos:end -->
```

### How it decides what's relevant

Not every repo needs to know about every other repo. Relevance is determined by:

1. **Direct dependencies** — repos listed in `package.json` dependencies
2. **Same category** — repos in the same manifest category (e.g., all `devops` repos)
3. **Explicit links** — repos that reference each other in their manifests
4. **Core repos** — a configurable list of repos that every repo should know about (e.g., the toolbox, wip-inc)

This keeps the ecosystem section focused rather than dumping 100 repos into every CLAUDE.md.

### The flow

1. Load `repos-manifest.json` — get all repo paths and metadata
2. For each repo on disk, read `package.json` + `SKILL.md` + directory structure
3. Build a dependency/relevance graph
4. For each repo, generate its ecosystem section (only relevant siblings)
5. Find `<!-- wip-repos:start -->` / `<!-- wip-repos:end -->` delimiters in CLAUDE.md
6. Replace only the content between delimiters (hand-written sections untouched)
7. If `--init` and no CLAUDE.md exists, generate from template (Phase 2)

### Key design decisions

- **Delimiter comments** protect hand-written sections from being overwritten
- **Edit semantics only** — never Write the whole file, respects file-guard
- **Relevance filtering** — not every repo sees every repo, keeps context focused
- **Runs locally** — has access to all repos on disk, bakes context for agents that can't
- **Idempotent** — safe to re-run anytime, only changes what's between delimiters

**Deliverable:** `tools/wip-repos/claude.mjs` subcommand + `claude` command in `cli.mjs`.

**Status:** TODO

---

## Phase 4: Repo Metadata Convention

**What to build:** A lightweight convention for repos to declare what they provide to the ecosystem.

**Option A: package.json field**
```json
{
  "wipEcosystem": {
    "provides": ["wip-release", "wip-file-guard"],
    "interfaces": ["CLI", "module", "MCP", "CC Hook"],
    "category": "devops"
  }
}
```

**Option B: Auto-detect from existing files**
- `bin` field → CLI commands
- `exports` field → module interfaces
- `SKILL.md` frontmatter → capabilities and interfaces
- `.license-guard.json` → dual-license flag
- Repo name ending in `-private` → private repo flag

**Recommendation:** Option B first (zero setup cost, works with existing repos), with Option A as an optional override for repos that want more control.

**Status:** TODO

---

## Phase 5: Protection at Scale

**What already exists:**
- `wip-file-guard` blocks Write on CLAUDE.md, blocks Edit removing >2 net lines
- Works as CC Hook and OpenClaw Plugin

**What to add:**
- `wip-repo-init` automatically installs file-guard hook config when scaffolding a new repo
- `wip-repos check` verifies every repo in the manifest has:
  - A CLAUDE.md file
  - CLAUDE.md listed in `.npmignore` (if `.npmignore` exists)
  - file-guard configured

**Deliverable:** Additions to `wip-repo-init` and `wip-repos check`.

**Status:** TODO

---

## Phase 6: Rollout Across All Repos

**Rollout order:**
1. **Toolbox repo** — dogfood first, manually write CLAUDE.md
2. **5 core repos** — run `wip-repos claude --init` to generate from template + ecosystem
3. **All remaining repos** — batch `wip-repos claude --init`
4. **Schedule refresh** — run `wip-repos claude` after releases or repo moves

**Trigger points for regeneration:**
- After `wip-release` (version changed)
- After `wip-repos sync` (repos moved)
- After `wip-repos add` (new repo added to ecosystem)
- Manual: anytime via `wip-repos claude`

---

## Integration Points

- **wip-repo-init** — generates starter CLAUDE.md from template (Phase 2)
- **wip-repos** — `wip-repos claude` generates cross-repo ecosystem (Phase 3), `wip-repos check` validates (Phase 5)
- **wip-file-guard** — protects CLAUDE.md from agent overwrites
- **wip-release** — triggers `wip-repos claude --update` after version bumps
- **deploy-public** — already excludes ai/ and CLAUDE.md from public repos
- **repos-manifest.json** — the source of truth for what repos exist and where

---

## Files to Create/Modify

| File | Action |
|------|--------|
| `templates/global-claude-md.md` | **Create** — global template |
| `tools/wip-repo-init/templates/CLAUDE.md.template` | **Create** — per-repo template with ecosystem placeholder |
| `tools/wip-repo-init/init.mjs` | **Modify** — add CLAUDE.md generation |
| `tools/wip-repos/claude.mjs` | **Create** — cross-repo ecosystem generator |
| `tools/wip-repos/cli.mjs` | **Modify** — add `claude` subcommand |
| `tools/wip-repos/core.mjs` | **Modify** — add ecosystem reading/writing functions |
| `tools/wip-repos/mcp-server.mjs` | **Modify** — expose `repos_claude` MCP tool |
| `tools/wip-repos/check.mjs` | **Modify** — add CLAUDE.md validation |
| `SKILL.md` | **Modify** — document new commands |
| `TECHNICAL.md` | **Modify** — document new architecture |

---

## Done Criteria

- [ ] Global CLAUDE.md template exists and is documented
- [ ] Per-repo CLAUDE.md template includes `<!-- wip-repos:start/end -->` ecosystem placeholder
- [ ] `wip-repo-init` generates CLAUDE.md for new repos
- [ ] `wip-repos claude` reads all repos on disk and generates cross-repo ecosystem sections
- [ ] Ecosystem section shows: path, description, provides, imports, interfaces for each relevant sibling
- [ ] Relevance filtering: only related repos shown, not all 100+
- [ ] `wip-repos claude --init` batch-creates CLAUDE.md for repos missing one
- [ ] Delimiter comments protect hand-written sections from overwrite
- [ ] `wip-repos check` validates CLAUDE.md presence and .npmignore inclusion
- [ ] file-guard protection verified across all repos
- [ ] Dogfooded on the toolbox repo + 5 core repos
