init-deep

name	init-deep
description	Generate hierarchical AGENTS.md and ensure paired CLAUDE.md files for codebases. Creates root AGENTS.md + CLAUDE.md plus complexity-scored subdirectory files. Use when user asks to "generate AGENTS.md files", "create codebase knowledge base", "run /init-deep", or wants comprehensive project documentation. Supports update mode (default) and --create-new flag to regenerate from scratch.

/init-deep

Generate hierarchical AGENTS.md files. Ensure every AGENTS.md has a paired CLAUDE.md (and vice versa) via symlinks. Root + complexity-scored subdirectories + all monorepo packages.

Usage

/init-deep                      # Update mode: modify existing + create new where warranted
/init-deep --create-new         # Read existing → remove all → regenerate from scratch
/init-deep --max-depth=2        # Limit directory depth (default: 3)

---

Workflow (High-Level)

1. Discovery + Analysis (concurrent)
   • Fire background explore agents immediately
   • Main session: bash structure + LSP codemap + read existing AGENTS.md and CLAUDE.md
2. Score & Decide - Determine AGENTS.md/CLAUDE.md locations from merged findings
3. Generate - Root first, then subdirs in parallel
4. Review - Deduplicate, trim, validate, ensure pairs

**TodoWrite ALL phases. Mark in_progress → completed in real-time.** ``` TodoWrite([ { id: "discovery", content: "Fire explore agents + LSP codemap + read existing AGENTS.md and CLAUDE.md", status: "pending", priority: "high" }, { id: "scoring", content: "Score directories, determine locations + monorepo packages", status: "pending", priority: "high" }, { id: "generate", content: "Generate AGENTS.md + CLAUDE.md files (root + subdirs)", status: "pending", priority: "high" }, { id: "review", content: "Deduplicate, validate, trim, ensure file pairs", status: "pending", priority: "medium" } ]) ```

---

Phase 1: Discovery + Analysis (Concurrent)

Mark "discovery" as in_progress.

Fire Background Explore Agents IMMEDIATELY

Don't wait—these run async while main session works.

// Fire all at once, collect results later
task(subagent_type="explore", load_skills=[], description="Explore project structure", run_in_background=true, prompt="Project structure: PREDICT standard patterns for detected language → REPORT deviations only")
task(subagent_type="explore", load_skills=[], description="Find entry points", run_in_background=true, prompt="Entry points: FIND main files → REPORT non-standard organization")
task(subagent_type="explore", load_skills=[], description="Find conventions", run_in_background=true, prompt="Conventions: FIND config files (.eslintrc, pyproject.toml, .editorconfig) → REPORT project-specific rules")
task(subagent_type="explore", load_skills=[], description="Find anti-patterns", run_in_background=true, prompt="Anti-patterns: FIND 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED' comments → LIST forbidden patterns")
task(subagent_type="explore", load_skills=[], description="Explore build/CI", run_in_background=true, prompt="Build/CI: FIND .github/workflows, Makefile → REPORT non-standard patterns")
task(subagent_type="explore", load_skills=[], description="Find test patterns", run_in_background=true, prompt="Test patterns: FIND test configs, test structure → REPORT unique conventions")

**DYNAMIC AGENT SPAWNING**: After bash analysis, spawn ADDITIONAL explore agents based on project scale:

Factor	Threshold	Additional Agents
Total files	>100	+1 per 100 files
Total lines	>10k	+1 per 10k lines
Directory depth	≥4	+2 for deep exploration
Large files (>500 lines)	>10 files	+1 for complexity hotspots
Monorepo	detected	+1 per package/workspace
Multiple languages	>1	+1 per language

# Measure project scale first
total_files=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)
total_lines=$(find . -type f \( -name "*.ts" -o -name "*.py" -o -name "*.go" \) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}')
large_files=$(find . -type f \( -name "*.ts" -o -name "*.py" \) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | awk '$1 > 500 {count++} END {print count+0}')
max_depth=$(find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | awk -F/ '{print NF}' | sort -rn | head -1)

Example spawning:

// 500 files, 50k lines, depth 6, 15 large files → spawn 5+5+2+1 = 13 additional agents
task(subagent_type="explore", load_skills=[], description="Analyze large files", run_in_background=true, prompt="Large file analysis: FIND files >500 lines, REPORT complexity hotspots")
task(subagent_type="explore", load_skills=[], description="Explore deep modules", run_in_background=true, prompt="Deep modules at depth 4+: FIND hidden patterns, internal conventions")
task(subagent_type="explore", load_skills=[], description="Find shared utilities", run_in_background=true, prompt="Cross-cutting concerns: FIND shared utilities across directories")
// ... more based on calculation

Main Session: Concurrent Analysis

While background agents run, main session does:

1. Bash Structural Analysis

# Directory depth + file counts
find . -type d -not -path '*/\.*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/dist/*' -not -path '*/build/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c

# Files per directory (top 30)
find . -type f -not -path '*/\.*' -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -30

# Code concentration by extension
find . -type f \( -name "*.py" -o -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.go" -o -name "*.rs" \) -not -path '*/node_modules/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20

# Existing AGENTS.md / CLAUDE.md
find . -type f \( -name "AGENTS.md" -o -name "CLAUDE.md" \) -not -path '*/node_modules/*' 2>/dev/null

# Monorepo detection (package directories)
find . \( -name "package.json" -o -name "pyproject.toml" -o -name "Cargo.toml" -o -name "go.mod" \) -not -path '*/node_modules/*' -not -path '*/.git/*' | sed 's|/[^/]*$||' | sort | uniq

2. Read Existing AGENTS.md and CLAUDE.md

For each directory where either AGENTS.md or CLAUDE.md exists:

agents_exists = file exists at {dir}/AGENTS.md
claude_exists = file exists at {dir}/CLAUDE.md

If agents_exists AND claude_exists:
  Read both files
  Merge their contents into EXISTING_AGENTS map for that directory
Else if agents_exists AND NOT claude_exists:
  Read AGENTS.md
  Create symlink: ln -s AGENTS.md CLAUDE.md (or ln -s CLAUDE.md AGENTS.md if you prefer; standard: ln -s AGENTS.md CLAUDE.md)
Else if claude_exists AND NOT agents_exists:
  Read CLAUDE.md
  Create symlink: ln -s CLAUDE.md AGENTS.md

If `--create-new`: Read all existing first (preserve context) → delete all AGENTS.md and CLAUDE.md + their symlinks → regenerate.

3. LSP Codemap (if available)

LspServers()  # Check availability

# Entry points (parallel)
LspDocumentSymbols(filePath="src/index.ts")
LspDocumentSymbols(filePath="main.py")

# Key symbols (parallel)
LspWorkspaceSymbols(filePath=".", query="class")
LspWorkspaceSymbols(filePath=".", query="interface")
LspWorkspaceSymbols(filePath=".", query="function")

# Centrality for top exports
LspFindReferences(filePath="...", line=X, character=Y)

LSP Fallback: If unavailable, rely on explore agents + AST-grep.

Collect Background Results

// After main session analysis done, collect all task results
for each task_id: background_output(task_id="...")

Merge: bash + LSP + existing + explore findings. Mark "discovery" as completed.

---

Phase 2: Scoring & Location Decision

Mark "scoring" as in_progress.

Scoring Matrix

Factor	Weight	High Threshold	Source
File count	3x	>20	bash
Subdir count	2x	>5	bash
Code ratio	2x	>70%	bash
Unique patterns	1x	Has own config	explore
Module boundary	2x	Has index.ts/init.py	bash
Symbol density	2x	>30 symbols	LSP
Export count	2x	>10 exports	LSP
Reference centrality	3x	>20 refs	LSP

Monorepo Rule

Every monorepo package directory MUST have an AGENTS.md + CLAUDE.md pair, regardless of score.

Detect packages via:

• package.json in subdirectories (Node/Yarn/npm workspaces, pnpm)
• pyproject.toml with [tool.poetry] or [project]
• Cargo.toml (Rust workspace member)
• go.mod (Go module)

Add all unique package directories to AGENTS_LOCATIONS with type: "package".

Decision Rules

Score	Action
Root (.)	ALWAYS create
Monorepo package	ALWAYS create
>15	Create AGENTS.md + CLAUDE.md
8-15	Create if distinct domain
<8	Skip (parent covers)

Output

AGENTS_LOCATIONS = [
  { path: ".", type: "root" },
  { path: "packages/core", type: "package", score: null, reason: "monorepo package" },
  { path: "src/hooks", score: 18, reason: "high complexity" },
  { path: "src/api", score: 12, reason: "distinct domain" }
]

Mark "scoring" as completed.

---

Phase 3: Generate AGENTS.md & CLAUDE.md

Mark "generate" as in_progress.

**File Writing Rule**: - If AGENTS.md already exists at the target path → use `Edit` tool. - If AGENTS.md does NOT exist → use `Write` tool. - NEVER use Write to overwrite an existing file. ALWAYS check existence first via `Read` or discovery results. - After writing AGENTS.md, ensure CLAUDE.md exists in the same directory. If missing, create it as a symlink to AGENTS.md. - If both files already exist and both are regular files (not symlinks), merge their content mentally and then use `Edit` to update both to the merged content.

Pairing Rules Per Directory

For every location in AGENTS_LOCATIONS:

1. Generate AGENTS.md content using the templates below.
2. Ensure CLAUDE.md exists in the same directory:
   • If neither exists: Write AGENTS.md, then ln -s AGENTS.md CLAUDE.md
   • If only AGENTS.md exists: ln -s AGENTS.md CLAUDE.md
   • If only CLAUDE.md exists: mv CLAUDE.md AGENTS.md, then ln -s AGENTS.md CLAUDE.md
   • If both exist as regular files: Merge content from both, then use Edit to update both to the merged content.

Preferred approach: Write AGENTS.md as the canonical file, then ln -s AGENTS.md CLAUDE.md in all cases where no conflict exists.

Root AGENTS.md (Full Treatment)

# PROJECT KNOWLEDGE BASE

**Generated:** {TIMESTAMP}
**Commit:** {SHORT_SHA}
**Branch:** {BRANCH}

## OVERVIEW

{1-2 sentences: what + core stack}

## STRUCTURE

{root}/ ├── {dir}/ # {non-obvious purpose only} └── {entry}

## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|

## CODE MAP
{From LSP - skip if unavailable or project <10 files}

| Symbol | Type | Location | Refs | Role |
|--------|------|----------|------|------|

## CONVENTIONS
{ONLY deviations from standard}

## ANTI-PATTERNS (THIS PROJECT)
{Explicitly forbidden here}

## UNIQUE STYLES
{Project-specific}

## COMMANDS

{dev/test/build}

## NOTES
{Gotchas}

Quality gates: 50-150 lines, no generic advice, no obvious info.

Monorepo Package AGENTS.md

Same structure as root but scoped to the package:

• Mention package name and its role in the monorepo
• Link to root AGENTS.md for global conventions
• 30-80 lines max

Subdirectory AGENTS.md (Parallel)

Launch writing tasks for each location:

for loc in AGENTS_LOCATIONS (except root):
  task(category="writing", load_skills=[], run_in_background=false, description="Generate AGENTS.md", prompt=`
    Generate AGENTS.md for: ${loc.path}
    - Type: ${loc.type} (package | subdir)
    - Reason: ${loc.reason}
    - 30-80 lines max
    - NEVER repeat parent content
    - Sections: OVERVIEW (1 line), STRUCTURE (if >5 subdirs), WHERE TO LOOK, CONVENTIONS (if different), ANTI-PATTERNS
    If type is "package", include the package's role in the monorepo and link to root conventions.
  `)

After each AGENTS.md is written, run the pairing check to ensure CLAUDE.md exists (create symlink if missing).

Wait for all. Mark "generate" as completed.

---

Phase 4: Review & Deduplicate

Mark "review" as in_progress.

For each generated file:

• Remove generic advice
• Remove parent duplicates
• Trim to size limits
• Verify telegraphic style
• Verify every AGENTS.md has a paired CLAUDE.md in the same directory
• Fix any missing symlinks

Mark "review" as completed.

---

Final Report

=== init-deep Complete ===

Mode: {update | create-new}

Files:
  [OK] ./AGENTS.md (root, {N} lines)
  [OK] ./CLAUDE.md → symlinked to ./AGENTS.md
  [OK] ./packages/core/AGENTS.md ({N} lines)
  [OK] ./packages/core/CLAUDE.md → symlinked to ./AGENTS.md
  [OK] ./src/hooks/AGENTS.md ({N} lines)
  [OK] ./src/hooks/CLAUDE.md → symlinked to ./AGENTS.md

Dirs Analyzed: {N}
AGENTS.md Created: {N}
CLAUDE.md Created: {N}
Pairs Ensured: {N}

Hierarchy:
  ./AGENTS.md
  ├── packages/core/AGENTS.md
  └── src/hooks/AGENTS.md

---

Anti-Patterns

• Static agent count: MUST vary agents based on project size/depth
• Sequential execution: MUST parallel (explore + LSP concurrent)
• Ignoring existing: ALWAYS read existing first, even with --create-new
• Over-documenting: Not every dir needs AGENTS.md (except monorepo packages)
• Redundancy: Child never repeats parent
• Generic content: Remove anything that applies to ALL projects
• Verbose style: Telegraphic or die
• Orphan files: NEVER leave AGENTS.md without CLAUDE.md in the same directory