/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

<critical> **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" }
])

</critical>

---

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-agents> **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

</dynamic-agents>

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