Map Project Monorepo

SKIPPING DISCOVERY = INCOMPLETE PER-PACKAGE DOCS = CLAUDE SEARCHING BLINDLY

This is not optional. Each sub-directory CLAUDE.md must be self-contained. Claude lazy-loads these files — they ONLY load when Claude touches files in that directory. If the CLAUDE.md is incomplete, Claude has NO context for that package.

Update CLAUDE.md for Monorepo

MANDATORY FIRST RESPONSE PROTOCOL

Before writing ANY documentation:

1. ☐ Discover all packages/*/ and apps/*/ directories
2. ☐ For each, count exports and identify key files
3. ☐ Map inter-package dependencies
4. ☐ Identify which packages have tests
5. ☐ Announce: "Generating CLAUDE.md for X packages + Y apps, targeting 10/10"

Writing per-package docs without discovery = guaranteed gaps. Phase 1 is NON-NEGOTIABLE.

Overview

In a monorepo, Claude Code lazy-loads subdirectory CLAUDE.md files — they only load when Claude touches files in that directory. Sibling packages never see each other's CLAUDE.md. This means each per-package CLAUDE.md must be self-contained: everything Claude needs to work effectively in that package, right there.

This skill generates a focused CLAUDE.md for every packages/*/ and apps/*/ directory, then simplifies the root CLAUDE.md and reference files by pushing per-package detail down to where Claude actually needs it.

Core principle: Detail lives where it's used. Root stays lean. Packages are self-contained.

Quality target: 10/10 — Claude should implement features correctly on first attempt in ANY package.

How Claude Code Loads Subdirectory CLAUDE.md

Understanding the loading mechanism is critical:

Implication: Per-package CLAUDE.md must include everything Claude needs for that package. Don't assume root-level detail will be available — keep root lean, push detail down.

Context Budget

Why these limits:

• Root is ALWAYS in context — every token counts
• Per-package files load only when needed — can be more detailed
• But still concise — tables over prose, no duplication

When to Use

• After monorepo refactor: Single package split into many (e.g., packages/core → 12 packages)
• Package added/removed: New package needs CLAUDE.md, removed package's docs are stale
• After running map-project: Root docs exist but no per-package files
• Claude searches blindly: Searching across 15+ packages for something in one package
• Periodic refresh: User asks to update monorepo docs or sync CLAUDE.md files

Symptoms:

• Claude reads 10 files across 5 packages to find one function
• No CLAUDE.md files exist in packages/*/ or apps/*/
• Root CLAUDE.md has 400+ line exports-reference trying to cover all packages
• Claude uses wrong import patterns or outdated types for a specific package

When NOT to Use

• Single-package project: Use map-project instead
• Only root needs updating: Use map-project instead
• Monorepo with 1-2 packages: Overhead not worth it — root docs suffice

Common Rationalizations (All Wrong)

• "The root CLAUDE.md already covers everything" → Root loads for ALL sessions; per-package loads ONLY when needed. Push detail down.
• "Per-package CLAUDE.md will be redundant" → No — Claude doesn't see root @import files when working in a subdirectory unless they're loaded. Each package must stand alone.
• "I'll just do the important packages" → ALL packages need CLAUDE.md. The one you skip is the one Claude will struggle with.
• "50 lines isn't enough" → Tables compress information 3x. 50 lines of tables = 150 lines of prose.
• "I can copy the same template everywhere" → Each package has different exports, dependencies, and conventions. Customize every file.
• "The root exports-reference.md already has this" → Move it down. Root should have summary counts, not full export tables.
• "Phase 1 takes too long for 15 packages" → Use parallel grep/find commands. Discovery takes 2 minutes. Skipping it costs 20 minutes of rework.

Phase 1: Monorepo Discovery (MANDATORY)

Gate: Complete inventory before writing ANY per-package CLAUDE.md.

Step 1: Find All Packages and Apps

# List all packages
ls -d packages/*/package.json 2>/dev/null | sed 's|/package.json||'

# List all apps
ls -d apps/*/package.json 2>/dev/null | sed 's|/package.json||'

Step 2: Build Package Inventory

For EACH package/app, collect:

# Package name from package.json
cat packages/*/package.json | jq -r '.name'

# Export count from index.ts
for pkg in packages/*/; do
  name=$(jq -r '.name' "$pkg/package.json" 2>/dev/null)
  count=$(grep -c "^export" "$pkg/src/index.ts" 2>/dev/null || echo 0)
  echo "$name: $count exports"
done

Create inventory table:

Step 3: Map Inter-Package Dependencies

For each package, find which other monorepo packages it imports:

# For each package, find internal dependencies
for pkg in packages/*/; do
  name=$(jq -r '.name' "$pkg/package.json" 2>/dev/null)
  deps=$(grep -rh "from \"@" "$pkg/src/" --include="*.ts" 2>/dev/null | \
    sed 's/.*from "\(@[^"]*\)".*/\1/' | sort -u | tr '\n' ', ')
  echo "$name → $deps"
done

Step 4: Extract Exports Per Package

For each package, list ALL exports:

# Full export listing per package
for pkg in packages/*/; do
  name=$(jq -r '.name' "$pkg/package.json" 2>/dev/null)
  echo "=== $name ==="
  grep "^export" "$pkg/src/index.ts" 2>/dev/null
  echo ""
done

Step 5: Identify Key Files Per Package

# List source files per package
for pkg in packages/*/; do
  name=$(jq -r '.name' "$pkg/package.json" 2>/dev/null)
  echo "=== $name ==="
  find "$pkg/src" -name "*.ts" -not -name "*.test.ts" -not -name "*.spec.ts" | sort
  echo ""
done

Step 6: Check for Tests

# Find which packages have tests
for pkg in packages/*/; do
  name=$(jq -r '.name' "$pkg/package.json" 2>/dev/null)
  tests=$(find "$pkg" -name "*.test.ts" -o -name "*.spec.ts" 2>/dev/null | wc -l)
  echo "$name: $tests test files"
done

Phase 1 Gate

Before proceeding, you MUST have:

• List of ALL packages with export counts
• List of ALL apps with descriptions
• Inter-package dependency map
• Key files per package
• Test file inventory
• Role description for each package (1-line purpose)

Phase 2: Per-Package CLAUDE.md Generation

Gate: EVERY package in packages/*/ has a CLAUDE.md.

For EACH package, create packages/<name>/CLAUDE.md using the template from references/package-template.md.

Required Sections Per Package

Every per-package CLAUDE.md MUST have:

Content Quality Rules

1. Export tables must be COMPLETE — every export from index.ts appears in the table
2. Key files must list ALL source files — not just "the important ones"
3. Dependencies must be accurate — grep the actual imports, don't guess
4. Import patterns must show real examples — from actual consumers in the monorepo
5. No prose paragraphs — tables and bullet lists only. Save tokens.

Package CLAUDE.md Size Guide

Phase 3: Per-App CLAUDE.md Generation

Gate: EVERY app in apps/*/ has a CLAUDE.md.

Apps are more complex than packages. Use the template from references/app-template.md.

Required Sections Per App

Every per-app CLAUDE.md MUST have:

App-Specific Sections

For API/Server apps, also include:

• Route table (ALL routes with methods, handlers)
• Middleware stack
• Request/response patterns with types

For CLI apps, also include:

• Command table (all commands with descriptions)
• Hook handler table (if applicable)
• stdin/stdout patterns

For Web UI apps, also include:

• Pages table (route → component)
• Key components list
• State management patterns
• API integration patterns

App CLAUDE.md Size Guide

Phase 4: Root Simplification

Gate: Root CLAUDE.md + reference files simplified. No per-package detail in root.

After generating per-package CLAUDE.md files, simplify the root:

What STAYS in Root CLAUDE.md

• Project name + 1-line description
• Package map table (name + 1-line purpose — NO export counts)
• Global conventions (ESM, bare imports, build commands)
• Quick reference table (which file to read)
• @imports for shared reference files
• Skills, agents, plugins table
• Hook handlers table (cross-cutting concern)
• Type gotchas (cross-cutting concern)

What MOVES to Per-Package CLAUDE.md

• Per-package export tables → each package's own CLAUDE.md
• Per-package file listings → each package's own CLAUDE.md
• Package-specific conventions → each package's own CLAUDE.md

What STAYS in Root Reference Files

architecture.md:

• High-level dependency graph (package relationships)
• Data flow diagrams (cross-package flows)
• State machines (cross-cutting concepts)
• API routes table (quick lookup — detail in apps/api/CLAUDE.md)

development-guide.md:

• Cross-cutting "how to add a new X" guides
• Response formats (shared across API)
• Error handling patterns (shared)
• Testing patterns (shared)

exports-reference.md:

• Summary table ONLY (package name + export count + 1-line purpose)
• Import patterns section (how to import from each package)
• Remove per-export detail — that now lives in per-package CLAUDE.md

Root Simplification Checklist

• Root CLAUDE.md is ≤ 300 lines
• exports-reference.md has summary table only (≤ 150 lines)
• architecture.md has no per-package file listings (≤ 400 lines)
• development-guide.md has no per-package export tables (≤ 500 lines)
• No per-package detail duplicated between root and subdirectory files

Phase 5: Verification (MANDATORY)

Gate: ALL checks pass before marking complete.

Check 1: Coverage

# Count packages/apps that need CLAUDE.md
TOTAL=$(ls -d packages/*/package.json apps/*/package.json 2>/dev/null | wc -l)

# Count generated CLAUDE.md files
GENERATED=$(ls packages/*/CLAUDE.md apps/*/CLAUDE.md 2>/dev/null | wc -l)

echo "Coverage: $GENERATED / $TOTAL"

FAIL if: Any package/app is missing CLAUDE.md

Check 2: Export Completeness

For each package, verify export coverage:

for pkg in packages/*/; do
  actual=$(grep -c "^export" "$pkg/src/index.ts" 2>/dev/null || echo 0)
  documented=$(grep -c "^|" "$pkg/CLAUDE.md" 2>/dev/null || echo 0)
  name=$(basename "$pkg")
  echo "$name: $documented documented / $actual exports"
done

FAIL if: Any package has < 90% export coverage

Check 3: Context Budget

# Root files
wc -l CLAUDE.md
wc -l .claude/claude-md-refs/*.md

# Per-package files
for f in packages/*/CLAUDE.md apps/*/CLAUDE.md; do
  wc -l "$f"
done

FAIL if:

• Root CLAUDE.md > 300 lines
• Any per-package CLAUDE.md > 200 lines
• Any per-app CLAUDE.md > 250 lines

Check 4: Self-Containment

For each per-package CLAUDE.md, verify it answers:

• What does this package do? (header)
• What does it export? (exports table)
• What files does it contain? (key files)
• What does it depend on? (dependencies)
• How do I import from it? (import pattern)

Check 5: No Duplication

Verify per-package export details are NOT duplicated in root reference files:

• exports-reference.md has summary table only — no per-export rows
• Root CLAUDE.md has no per-package file listings
• Per-package CLAUDE.md does not repeat root conventions

Check 6: Root Simplified

• Root CLAUDE.md is ≤ 300 lines (down from previous size)
• exports-reference.md is ≤ 150 lines (summary only)
• No per-package detail remains in root files

Quality Checklist (Must Score 10/10)

Coverage (0-2 points)

• 0: Some packages missing CLAUDE.md
• 1: All packages have CLAUDE.md but some incomplete
• 2: Every package and app has complete CLAUDE.md

Export Completeness (0-2 points)

• 0: <50% of exports documented per package
• 1: 50-89% coverage
• 2: >90% coverage in every package

Self-Containment (0-2 points)

• 0: Per-package docs reference root files for basic info
• 1: Mostly self-contained but missing some context
• 2: Each CLAUDE.md is fully self-contained for its package

Root Simplification (0-2 points)

• 0: Root still has per-package detail
• 1: Some detail moved but root still verbose
• 2: Root is lean (≤300 lines), detail pushed to packages

Context Efficiency (0-2 points)

• 0: Over budget or heavy duplication
• 1: Within budget but some duplication
• 2: Within budget, zero duplication, tables over prose

Total: 10/10 required to complete this skill

Failure Modes

Failure Mode 1: Copy-Paste Templates

Symptom: All per-package CLAUDE.md files look identical with placeholder text Fix: Each file must have actual exports, actual file names, actual dependencies from discovery.

Failure Mode 2: Root Not Simplified

Symptom: Per-package files created but root CLAUDE.md still 500+ lines with full export tables Fix: Phase 4 is mandatory. Move detail down, slim root to ≤300 lines.

Failure Mode 3: Missing Packages

Symptom: 10 of 12 packages have CLAUDE.md, 2 skipped Fix: Check 1 catches this. Every package, no exceptions.

Failure Mode 4: Incomplete Exports

Symptom: Package has 43 exports but CLAUDE.md only lists 20 Fix: Use grep to get actual count, verify table row count matches.

Failure Mode 5: Broken Cross-References

Symptom: Per-package CLAUDE.md references root @import that moved Fix: Per-package files should be self-contained. No @imports to root reference files.

Failure Mode 6: Prose Instead of Tables

Symptom: Per-package CLAUDE.md is 300 lines of paragraphs Fix: Tables compress 3x. A 40-export package needs a 40-row table, not 40 paragraphs.

Quick Workflow Summary

PHASE 1: DISCOVERY (Do not skip)
├── Find all packages/ and apps/ directories
├── Count exports per package
├── Map inter-package dependencies
├── List key files per package
├── Check for test files
└── Gate: Complete inventory

PHASE 2: PER-PACKAGE CLAUDE.md (Every package)
├── Header + purpose
├── Exports table (ALL exports)
├── Key files table
├── Dependencies list
├── Import patterns
├── Conventions + testing
└── Gate: Every package has CLAUDE.md

PHASE 3: PER-APP CLAUDE.md (Every app)
├── Header + purpose
├── File structure + entry points
├── Commands table
├── Dependencies with purposes
├── App-specific sections (routes/commands/pages)
└── Gate: Every app has CLAUDE.md

PHASE 4: ROOT SIMPLIFICATION
├── Slim root CLAUDE.md to ≤300 lines
├── Slim exports-reference.md to summary table only
├── Remove per-package detail from root files
├── Keep cross-cutting concerns in root
└── Gate: Root simplified, no duplication

PHASE 5: VERIFICATION (All must pass)
├── Check 1: Every package/app has CLAUDE.md
├── Check 2: >90% export coverage per package
├── Check 3: Context budget met
├── Check 4: Self-containment verified
├── Check 5: No duplication
├── Check 6: Root simplified
└── Gate: All 6 checks pass

COMPLETE: Announce final quality score (must be 10/10)

Completion Announcement

When done, announce:

Monorepo CLAUDE.md generation complete.

**Quality Score: X/10**
- Coverage: X/2 (N packages + M apps documented)
- Export Completeness: X/2 (>90% per package)
- Self-Containment: X/2
- Root Simplification: X/2 (root: N lines, was M lines)
- Context Efficiency: X/2

**Files created:**
- packages/contracts/CLAUDE.md: X lines
- packages/config/CLAUDE.md: X lines
- [... all packages ...]
- apps/api/CLAUDE.md: X lines
- apps/cli/CLAUDE.md: X lines
- apps/web-ui/CLAUDE.md: X lines

**Root simplified:**
- CLAUDE.md: X lines (was Y)
- exports-reference.md: X lines (was Y)

**Verification passed:** All 6 checks complete.

Integration with Other Skills

• map-project — Use that for single-package projects or root-only updates. Use THIS skill for monorepo per-package docs.
• start — Start skill identifies if monorepo docs are needed
• rebuild — After rebuild, run this if packages were added/removed

Workflow:

New package added
       │
       ▼
rebuild skill (verify build)
       │
       ▼
map-project-monorepo (this skill)
       │
       ▼
commit skill (commit the new CLAUDE.md files)

References

See references/ for templates:

This skill ensures every package and app in a monorepo has focused, self-contained documentation that loads exactly when Claude needs it.