--- 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 | ```bash # 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 ```bash # 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) ```markdown # 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